1 /*************************************************************************** 2 3 chd.h 4 5 MAME Compressed Hunks of Data file format 6 7 **************************************************************************** 8 9 Copyright Aaron Giles 10 All rights reserved. 11 12 Redistribution and use in source and binary forms, with or without 13 modification, are permitted provided that the following conditions are 14 met: 15 16 * Redistributions of source code must retain the above copyright 17 notice, this list of conditions and the following disclaimer. 18 * Redistributions in binary form must reproduce the above copyright 19 notice, this list of conditions and the following disclaimer in 20 the documentation and/or other materials provided with the 21 distribution. 22 * Neither the name 'MAME' nor the names of its contributors may be 23 used to endorse or promote products derived from this software 24 without specific prior written permission. 25 26 THIS SOFTWARE IS PROVIDED BY AARON GILES ''AS IS'' AND ANY EXPRESS OR 27 IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED 28 WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE 29 DISCLAIMED. IN NO EVENT SHALL AARON GILES BE LIABLE FOR ANY DIRECT, 30 INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES 31 (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR 32 SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 33 HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, 34 STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING 35 IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 36 POSSIBILITY OF SUCH DAMAGE. 37 38 ***************************************************************************/ 39 40 #pragma once 41 42 #ifndef __CHD_H__ 43 #define __CHD_H__ 44 45 #ifdef __cplusplus 46 extern "C" { 47 #endif 48 49 #include <libchdr/coretypes.h> 50 #include <libchdr/chdconfig.h> 51 52 /*************************************************************************** 53 54 Compressed Hunks of Data header format. All numbers are stored in 55 Motorola (big-endian) byte ordering. The header is 76 (V1) or 80 (V2) 56 bytes long. 57 58 V1 header: 59 60 [ 0] char tag[8]; // 'MComprHD' 61 [ 8] UINT32 length; // length of header (including tag and length fields) 62 [ 12] UINT32 version; // drive format version 63 [ 16] UINT32 flags; // flags (see below) 64 [ 20] UINT32 compression; // compression type 65 [ 24] UINT32 hunksize; // 512-byte sectors per hunk 66 [ 28] UINT32 totalhunks; // total # of hunks represented 67 [ 32] UINT32 cylinders; // number of cylinders on hard disk 68 [ 36] UINT32 heads; // number of heads on hard disk 69 [ 40] UINT32 sectors; // number of sectors on hard disk 70 [ 44] UINT8 md5[16]; // MD5 checksum of raw data 71 [ 60] UINT8 parentmd5[16]; // MD5 checksum of parent file 72 [ 76] (V1 header length) 73 74 V2 header: 75 76 [ 0] char tag[8]; // 'MComprHD' 77 [ 8] UINT32 length; // length of header (including tag and length fields) 78 [ 12] UINT32 version; // drive format version 79 [ 16] UINT32 flags; // flags (see below) 80 [ 20] UINT32 compression; // compression type 81 [ 24] UINT32 hunksize; // seclen-byte sectors per hunk 82 [ 28] UINT32 totalhunks; // total # of hunks represented 83 [ 32] UINT32 cylinders; // number of cylinders on hard disk 84 [ 36] UINT32 heads; // number of heads on hard disk 85 [ 40] UINT32 sectors; // number of sectors on hard disk 86 [ 44] UINT8 md5[16]; // MD5 checksum of raw data 87 [ 60] UINT8 parentmd5[16]; // MD5 checksum of parent file 88 [ 76] UINT32 seclen; // number of bytes per sector 89 [ 80] (V2 header length) 90 91 V3 header: 92 93 [ 0] char tag[8]; // 'MComprHD' 94 [ 8] UINT32 length; // length of header (including tag and length fields) 95 [ 12] UINT32 version; // drive format version 96 [ 16] UINT32 flags; // flags (see below) 97 [ 20] UINT32 compression; // compression type 98 [ 24] UINT32 totalhunks; // total # of hunks represented 99 [ 28] UINT64 logicalbytes; // logical size of the data (in bytes) 100 [ 36] UINT64 metaoffset; // offset to the first blob of metadata 101 [ 44] UINT8 md5[16]; // MD5 checksum of raw data 102 [ 60] UINT8 parentmd5[16]; // MD5 checksum of parent file 103 [ 76] UINT32 hunkbytes; // number of bytes per hunk 104 [ 80] UINT8 sha1[20]; // SHA1 checksum of raw data 105 [100] UINT8 parentsha1[20];// SHA1 checksum of parent file 106 [120] (V3 header length) 107 108 V4 header: 109 110 [ 0] char tag[8]; // 'MComprHD' 111 [ 8] UINT32 length; // length of header (including tag and length fields) 112 [ 12] UINT32 version; // drive format version 113 [ 16] UINT32 flags; // flags (see below) 114 [ 20] UINT32 compression; // compression type 115 [ 24] UINT32 totalhunks; // total # of hunks represented 116 [ 28] UINT64 logicalbytes; // logical size of the data (in bytes) 117 [ 36] UINT64 metaoffset; // offset to the first blob of metadata 118 [ 44] UINT32 hunkbytes; // number of bytes per hunk 119 [ 48] UINT8 sha1[20]; // combined raw+meta SHA1 120 [ 68] UINT8 parentsha1[20];// combined raw+meta SHA1 of parent 121 [ 88] UINT8 rawsha1[20]; // raw data SHA1 122 [108] (V4 header length) 123 124 Flags: 125 0x00000001 - set if this drive has a parent 126 0x00000002 - set if this drive allows writes 127 128 ========================================================================= 129 130 V5 header: 131 132 [ 0] char tag[8]; // 'MComprHD' 133 [ 8] uint32_t length; // length of header (including tag and length fields) 134 [ 12] uint32_t version; // drive format version 135 [ 16] uint32_t compressors[4];// which custom compressors are used? 136 [ 32] uint64_t logicalbytes; // logical size of the data (in bytes) 137 [ 40] uint64_t mapoffset; // offset to the map 138 [ 48] uint64_t metaoffset; // offset to the first blob of metadata 139 [ 56] uint32_t hunkbytes; // number of bytes per hunk (512k maximum) 140 [ 60] uint32_t unitbytes; // number of bytes per unit within each hunk 141 [ 64] uint8_t rawsha1[20]; // raw data SHA1 142 [ 84] uint8_t sha1[20]; // combined raw+meta SHA1 143 [104] uint8_t parentsha1[20];// combined raw+meta SHA1 of parent 144 [124] (V5 header length) 145 146 If parentsha1 != 0, we have a parent (no need for flags) 147 If compressors[0] == 0, we are uncompressed (including maps) 148 149 V5 uncompressed map format: 150 151 [ 0] uint32_t offset; // starting offset / hunk size 152 153 V5 compressed map format header: 154 155 [ 0] uint32_t length; // length of compressed map 156 [ 4] UINT48 datastart; // offset of first block 157 [ 10] uint16_t crc; // crc-16 of the map 158 [ 12] uint8_t lengthbits; // bits used to encode complength 159 [ 13] uint8_t hunkbits; // bits used to encode self-refs 160 [ 14] uint8_t parentunitbits; // bits used to encode parent unit refs 161 [ 15] uint8_t reserved; // future use 162 [ 16] (compressed header length) 163 164 Each compressed map entry, once expanded, looks like: 165 166 [ 0] uint8_t compression; // compression type 167 [ 1] UINT24 complength; // compressed length 168 [ 4] UINT48 offset; // offset 169 [ 10] uint16_t crc; // crc-16 of the data 170 171 ***************************************************************************/ 172 173 174 /*************************************************************************** 175 CONSTANTS 176 ***************************************************************************/ 177 178 /* header information */ 179 #define CHD_HEADER_VERSION 5 180 #define CHD_V1_HEADER_SIZE 76 181 #define CHD_V2_HEADER_SIZE 80 182 #define CHD_V3_HEADER_SIZE 120 183 #define CHD_V4_HEADER_SIZE 108 184 #define CHD_V5_HEADER_SIZE 124 185 186 #define CHD_MAX_HEADER_SIZE CHD_V5_HEADER_SIZE 187 188 /* checksumming information */ 189 #define CHD_MD5_BYTES 16 190 #define CHD_SHA1_BYTES 20 191 192 /* CHD global flags */ 193 #define CHDFLAGS_HAS_PARENT 0x00000001 194 #define CHDFLAGS_IS_WRITEABLE 0x00000002 195 #define CHDFLAGS_UNDEFINED 0xfffffffc 196 197 #define CHD_MAKE_TAG(a,b,c,d) (((a) << 24) | ((b) << 16) | ((c) << 8) | (d)) 198 199 /* compression types */ 200 #define CHDCOMPRESSION_NONE 0 201 #define CHDCOMPRESSION_ZLIB 1 202 #define CHDCOMPRESSION_ZLIB_PLUS 2 203 #define CHDCOMPRESSION_AV 3 204 205 #define CHD_CODEC_NONE 0 206 #define CHD_CODEC_ZLIB CHD_MAKE_TAG('z','l','i','b') 207 /* general codecs with CD frontend */ 208 #define CHD_CODEC_CD_ZLIB CHD_MAKE_TAG('c','d','z','l') 209 #define CHD_CODEC_CD_LZMA CHD_MAKE_TAG('c','d','l','z') 210 #define CHD_CODEC_CD_FLAC CHD_MAKE_TAG('c','d','f','l') 211 212 /* A/V codec configuration parameters */ 213 #define AV_CODEC_COMPRESS_CONFIG 1 214 #define AV_CODEC_DECOMPRESS_CONFIG 2 215 216 /* metadata parameters */ 217 #define CHDMETATAG_WILDCARD 0 218 #define CHD_METAINDEX_APPEND ((UINT32)-1) 219 220 /* metadata flags */ 221 #define CHD_MDFLAGS_CHECKSUM 0x01 /* indicates data is checksummed */ 222 223 /* standard hard disk metadata */ 224 #define HARD_DISK_METADATA_TAG CHD_MAKE_TAG('G','D','D','D') 225 #define HARD_DISK_METADATA_FORMAT "CYLS:%d,HEADS:%d,SECS:%d,BPS:%d" 226 227 /* hard disk identify information */ 228 #define HARD_DISK_IDENT_METADATA_TAG CHD_MAKE_TAG('I','D','N','T') 229 230 /* hard disk key information */ 231 #define HARD_DISK_KEY_METADATA_TAG CHD_MAKE_TAG('K','E','Y',' ') 232 233 /* pcmcia CIS information */ 234 #define PCMCIA_CIS_METADATA_TAG CHD_MAKE_TAG('C','I','S',' ') 235 236 /* standard CD-ROM metadata */ 237 #define CDROM_OLD_METADATA_TAG CHD_MAKE_TAG('C','H','C','D') 238 #define CDROM_TRACK_METADATA_TAG CHD_MAKE_TAG('C','H','T','R') 239 #define CDROM_TRACK_METADATA_FORMAT "TRACK:%d TYPE:%s SUBTYPE:%s FRAMES:%d" 240 #define CDROM_TRACK_METADATA2_TAG CHD_MAKE_TAG('C','H','T','2') 241 #define CDROM_TRACK_METADATA2_FORMAT "TRACK:%d TYPE:%s SUBTYPE:%s FRAMES:%d PREGAP:%d PGTYPE:%s PGSUB:%s POSTGAP:%d" 242 #define GDROM_OLD_METADATA_TAG CHD_MAKE_TAG('C','H','G','T') 243 #define GDROM_TRACK_METADATA_TAG CHD_MAKE_TAG('C', 'H', 'G', 'D') 244 #define GDROM_TRACK_METADATA_FORMAT "TRACK:%d TYPE:%s SUBTYPE:%s FRAMES:%d PAD:%d PREGAP:%d PGTYPE:%s PGSUB:%s POSTGAP:%d" 245 246 /* standard A/V metadata */ 247 #define AV_METADATA_TAG CHD_MAKE_TAG('A','V','A','V') 248 #define AV_METADATA_FORMAT "FPS:%d.%06d WIDTH:%d HEIGHT:%d INTERLACED:%d CHANNELS:%d SAMPLERATE:%d" 249 250 /* A/V laserdisc frame metadata */ 251 #define AV_LD_METADATA_TAG CHD_MAKE_TAG('A','V','L','D') 252 253 /* CHD open values */ 254 #define CHD_OPEN_READ 1 255 #define CHD_OPEN_READWRITE 2 256 257 /* error types */ 258 enum _chd_error 259 { 260 CHDERR_NONE, 261 CHDERR_NO_INTERFACE, 262 CHDERR_OUT_OF_MEMORY, 263 CHDERR_INVALID_FILE, 264 CHDERR_INVALID_PARAMETER, 265 CHDERR_INVALID_DATA, 266 CHDERR_FILE_NOT_FOUND, 267 CHDERR_REQUIRES_PARENT, 268 CHDERR_FILE_NOT_WRITEABLE, 269 CHDERR_READ_ERROR, 270 CHDERR_WRITE_ERROR, 271 CHDERR_CODEC_ERROR, 272 CHDERR_INVALID_PARENT, 273 CHDERR_HUNK_OUT_OF_RANGE, 274 CHDERR_DECOMPRESSION_ERROR, 275 CHDERR_COMPRESSION_ERROR, 276 CHDERR_CANT_CREATE_FILE, 277 CHDERR_CANT_VERIFY, 278 CHDERR_NOT_SUPPORTED, 279 CHDERR_METADATA_NOT_FOUND, 280 CHDERR_INVALID_METADATA_SIZE, 281 CHDERR_UNSUPPORTED_VERSION, 282 CHDERR_VERIFY_INCOMPLETE, 283 CHDERR_INVALID_METADATA, 284 CHDERR_INVALID_STATE, 285 CHDERR_OPERATION_PENDING, 286 CHDERR_NO_ASYNC_OPERATION, 287 CHDERR_UNSUPPORTED_FORMAT 288 }; 289 typedef enum _chd_error chd_error; 290 291 292 293 /*************************************************************************** 294 TYPE DEFINITIONS 295 ***************************************************************************/ 296 297 /* opaque types */ 298 typedef struct _chd_file chd_file; 299 300 301 /* extract header structure (NOT the on-disk header structure) */ 302 typedef struct _chd_header chd_header; 303 struct _chd_header 304 { 305 UINT32 length; /* length of header data */ 306 UINT32 version; /* drive format version */ 307 UINT32 flags; /* flags field */ 308 UINT32 compression[4]; /* compression type */ 309 UINT32 hunkbytes; /* number of bytes per hunk */ 310 UINT32 totalhunks; /* total # of hunks represented */ 311 UINT64 logicalbytes; /* logical size of the data */ 312 UINT64 metaoffset; /* offset in file of first metadata */ 313 UINT64 mapoffset; /* TOOD V5 */ 314 UINT8 md5[CHD_MD5_BYTES]; /* overall MD5 checksum */ 315 UINT8 parentmd5[CHD_MD5_BYTES]; /* overall MD5 checksum of parent */ 316 UINT8 sha1[CHD_SHA1_BYTES]; /* overall SHA1 checksum */ 317 UINT8 rawsha1[CHD_SHA1_BYTES]; /* SHA1 checksum of raw data */ 318 UINT8 parentsha1[CHD_SHA1_BYTES]; /* overall SHA1 checksum of parent */ 319 UINT32 unitbytes; /* TODO V5 */ 320 UINT64 unitcount; /* TODO V5 */ 321 UINT32 hunkcount; /* TODO V5 */ 322 323 /* map information */ 324 UINT32 mapentrybytes; /* length of each entry in a map (V5) */ 325 UINT8* rawmap; /* raw map data */ 326 327 UINT32 obsolete_cylinders; /* obsolete field -- do not use! */ 328 UINT32 obsolete_sectors; /* obsolete field -- do not use! */ 329 UINT32 obsolete_heads; /* obsolete field -- do not use! */ 330 UINT32 obsolete_hunksize; /* obsolete field -- do not use! */ 331 }; 332 333 334 /* structure for returning information about a verification pass */ 335 typedef struct _chd_verify_result chd_verify_result; 336 struct _chd_verify_result 337 { 338 UINT8 md5[CHD_MD5_BYTES]; /* overall MD5 checksum */ 339 UINT8 sha1[CHD_SHA1_BYTES]; /* overall SHA1 checksum */ 340 UINT8 rawsha1[CHD_SHA1_BYTES]; /* SHA1 checksum of raw data */ 341 UINT8 metasha1[CHD_SHA1_BYTES]; /* SHA1 checksum of metadata */ 342 }; 343 344 345 346 /*************************************************************************** 347 FUNCTION PROTOTYPES 348 ***************************************************************************/ 349 #ifdef __LIBRETRO__ 350 #define CHD_EXPORT 351 #else 352 #define CHD_EXPORT __attribute__ ((visibility("default"))) 353 #endif 354 355 /* ----- CHD file management ----- */ 356 357 /* create a new CHD file fitting the given description */ 358 /* chd_error chd_create(const char *filename, UINT64 logicalbytes, UINT32 hunkbytes, UINT32 compression, chd_file *parent); */ 359 360 /* same as chd_create(), but accepts an already-opened core_file object */ 361 /* chd_error chd_create_file(core_file *file, UINT64 logicalbytes, UINT32 hunkbytes, UINT32 compression, chd_file *parent); */ 362 363 /* open an existing CHD file */ 364 CHD_EXPORT chd_error chd_open_file(core_file *file, int mode, chd_file *parent, chd_file **chd); 365 CHD_EXPORT chd_error chd_open(const char *filename, int mode, chd_file *parent, chd_file **chd); 366 367 /* precache underlying file */ 368 CHD_EXPORT chd_error chd_precache(chd_file *chd); 369 370 /* close a CHD file */ 371 CHD_EXPORT void chd_close(chd_file *chd); 372 373 /* return the associated core_file */ 374 CHD_EXPORT core_file *chd_core_file(chd_file *chd); 375 376 /* return an error string for the given CHD error */ 377 CHD_EXPORT const char *chd_error_string(chd_error err); 378 379 380 381 /* ----- CHD header management ----- */ 382 383 /* return a pointer to the extracted CHD header data */ 384 CHD_EXPORT const chd_header *chd_get_header(chd_file *chd); 385 386 387 388 389 /* ----- core data read/write ----- */ 390 391 /* read one hunk from the CHD file */ 392 CHD_EXPORT chd_error chd_read(chd_file *chd, UINT32 hunknum, void *buffer); 393 394 395 396 /* ----- metadata management ----- */ 397 398 /* get indexed metadata of a particular sort */ 399 CHD_EXPORT chd_error chd_get_metadata(chd_file *chd, UINT32 searchtag, UINT32 searchindex, void *output, UINT32 outputlen, UINT32 *resultlen, UINT32 *resulttag, UINT8 *resultflags); 400 401 402 403 404 /* ----- codec interfaces ----- */ 405 406 /* set internal codec parameters */ 407 CHD_EXPORT chd_error chd_codec_config(chd_file *chd, int param, void *config); 408 409 /* return a string description of a codec */ 410 CHD_EXPORT const char *chd_get_codec_name(UINT32 codec); 411 412 #ifdef __cplusplus 413 } 414 #endif 415 416 #endif /* __CHD_H__ */ 417