| 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 "coretypes.h" |
| 50 | |
| 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 | /* compression types */ |
| 198 | #define CHDCOMPRESSION_NONE 0 |
| 199 | #define CHDCOMPRESSION_ZLIB 1 |
| 200 | #define CHDCOMPRESSION_ZLIB_PLUS 2 |
| 201 | #define CHDCOMPRESSION_AV 3 |
| 202 | |
| 203 | /* A/V codec configuration parameters */ |
| 204 | #define AV_CODEC_COMPRESS_CONFIG 1 |
| 205 | #define AV_CODEC_DECOMPRESS_CONFIG 2 |
| 206 | |
| 207 | /* metadata parameters */ |
| 208 | #define CHDMETATAG_WILDCARD 0 |
| 209 | #define CHD_METAINDEX_APPEND ((UINT32)-1) |
| 210 | |
| 211 | /* metadata flags */ |
| 212 | #define CHD_MDFLAGS_CHECKSUM 0x01 /* indicates data is checksummed */ |
| 213 | |
| 214 | /* standard hard disk metadata */ |
| 215 | #define HARD_DISK_METADATA_TAG 0x47444444 /* 'GDDD' */ |
| 216 | #define HARD_DISK_METADATA_FORMAT "CYLS:%d,HEADS:%d,SECS:%d,BPS:%d" |
| 217 | |
| 218 | /* hard disk identify information */ |
| 219 | #define HARD_DISK_IDENT_METADATA_TAG 0x49444e54 /* 'IDNT' */ |
| 220 | |
| 221 | /* hard disk key information */ |
| 222 | #define HARD_DISK_KEY_METADATA_TAG 0x4b455920 /* 'KEY ' */ |
| 223 | |
| 224 | /* pcmcia CIS information */ |
| 225 | #define PCMCIA_CIS_METADATA_TAG 0x43495320 /* 'CIS ' */ |
| 226 | |
| 227 | /* standard CD-ROM metadata */ |
| 228 | #define CDROM_OLD_METADATA_TAG 0x43484344 /* 'CHCD' */ |
| 229 | #define CDROM_TRACK_METADATA_TAG 0x43485452 /* 'CHTR' */ |
| 230 | #define CDROM_TRACK_METADATA_FORMAT "TRACK:%d TYPE:%s SUBTYPE:%s FRAMES:%d" |
| 231 | #define CDROM_TRACK_METADATA2_TAG 0x43485432 /* 'CHT2' */ |
| 232 | #define CDROM_TRACK_METADATA2_FORMAT "TRACK:%d TYPE:%s SUBTYPE:%s FRAMES:%d PREGAP:%d PGTYPE:%s PGSUB:%s POSTGAP:%d" |
| 233 | #define GDROM_TRACK_METADATA_TAG 0x43484744 /* 'CHTD' */ |
| 234 | #define GDROM_TRACK_METADATA_FORMAT "TRACK:%d TYPE:%s SUBTYPE:%s FRAMES:%d PAD:%d PREGAP:%d PGTYPE:%s PGSUB:%s POSTGAP:%d" |
| 235 | |
| 236 | /* standard A/V metadata */ |
| 237 | #define AV_METADATA_TAG 0x41564156 /* 'AVAV' */ |
| 238 | #define AV_METADATA_FORMAT "FPS:%d.%06d WIDTH:%d HEIGHT:%d INTERLACED:%d CHANNELS:%d SAMPLERATE:%d" |
| 239 | |
| 240 | /* A/V laserdisc frame metadata */ |
| 241 | #define AV_LD_METADATA_TAG 0x41564C44 /* 'AVLD' */ |
| 242 | |
| 243 | /* CHD open values */ |
| 244 | #define CHD_OPEN_READ 1 |
| 245 | #define CHD_OPEN_READWRITE 2 |
| 246 | |
| 247 | /* error types */ |
| 248 | enum _chd_error |
| 249 | { |
| 250 | CHDERR_NONE, |
| 251 | CHDERR_NO_INTERFACE, |
| 252 | CHDERR_OUT_OF_MEMORY, |
| 253 | CHDERR_INVALID_FILE, |
| 254 | CHDERR_INVALID_PARAMETER, |
| 255 | CHDERR_INVALID_DATA, |
| 256 | CHDERR_FILE_NOT_FOUND, |
| 257 | CHDERR_REQUIRES_PARENT, |
| 258 | CHDERR_FILE_NOT_WRITEABLE, |
| 259 | CHDERR_READ_ERROR, |
| 260 | CHDERR_WRITE_ERROR, |
| 261 | CHDERR_CODEC_ERROR, |
| 262 | CHDERR_INVALID_PARENT, |
| 263 | CHDERR_HUNK_OUT_OF_RANGE, |
| 264 | CHDERR_DECOMPRESSION_ERROR, |
| 265 | CHDERR_COMPRESSION_ERROR, |
| 266 | CHDERR_CANT_CREATE_FILE, |
| 267 | CHDERR_CANT_VERIFY, |
| 268 | CHDERR_NOT_SUPPORTED, |
| 269 | CHDERR_METADATA_NOT_FOUND, |
| 270 | CHDERR_INVALID_METADATA_SIZE, |
| 271 | CHDERR_UNSUPPORTED_VERSION, |
| 272 | CHDERR_VERIFY_INCOMPLETE, |
| 273 | CHDERR_INVALID_METADATA, |
| 274 | CHDERR_INVALID_STATE, |
| 275 | CHDERR_OPERATION_PENDING, |
| 276 | CHDERR_NO_ASYNC_OPERATION, |
| 277 | CHDERR_UNSUPPORTED_FORMAT |
| 278 | }; |
| 279 | typedef enum _chd_error chd_error; |
| 280 | |
| 281 | |
| 282 | |
| 283 | /*************************************************************************** |
| 284 | TYPE DEFINITIONS |
| 285 | ***************************************************************************/ |
| 286 | |
| 287 | /* opaque types */ |
| 288 | typedef struct _chd_file chd_file; |
| 289 | |
| 290 | |
| 291 | /* extract header structure (NOT the on-disk header structure) */ |
| 292 | typedef struct _chd_header chd_header; |
| 293 | struct _chd_header |
| 294 | { |
| 295 | UINT32 length; /* length of header data */ |
| 296 | UINT32 version; /* drive format version */ |
| 297 | UINT32 flags; /* flags field */ |
| 298 | UINT32 compression[4]; /* compression type */ |
| 299 | UINT32 hunkbytes; /* number of bytes per hunk */ |
| 300 | UINT32 totalhunks; /* total # of hunks represented */ |
| 301 | UINT64 logicalbytes; /* logical size of the data */ |
| 302 | UINT64 metaoffset; /* offset in file of first metadata */ |
| 303 | UINT64 mapoffset; /* TOOD V5 */ |
| 304 | UINT8 md5[CHD_MD5_BYTES]; /* overall MD5 checksum */ |
| 305 | UINT8 parentmd5[CHD_MD5_BYTES]; /* overall MD5 checksum of parent */ |
| 306 | UINT8 sha1[CHD_SHA1_BYTES]; /* overall SHA1 checksum */ |
| 307 | UINT8 rawsha1[CHD_SHA1_BYTES]; /* SHA1 checksum of raw data */ |
| 308 | UINT8 parentsha1[CHD_SHA1_BYTES]; /* overall SHA1 checksum of parent */ |
| 309 | UINT32 unitbytes; /* TODO V5 */ |
| 310 | UINT64 unitcount; /* TODO V5 */ |
| 311 | UINT32 hunkcount; /* TODO V5 */ |
| 312 | |
| 313 | // map information |
| 314 | UINT32 mapentrybytes; // length of each entry in a map (V5) |
| 315 | UINT8* rawmap; // raw map data |
| 316 | |
| 317 | UINT32 obsolete_cylinders; /* obsolete field -- do not use! */ |
| 318 | UINT32 obsolete_sectors; /* obsolete field -- do not use! */ |
| 319 | UINT32 obsolete_heads; /* obsolete field -- do not use! */ |
| 320 | UINT32 obsolete_hunksize; /* obsolete field -- do not use! */ |
| 321 | }; |
| 322 | |
| 323 | |
| 324 | /* structure for returning information about a verification pass */ |
| 325 | typedef struct _chd_verify_result chd_verify_result; |
| 326 | struct _chd_verify_result |
| 327 | { |
| 328 | UINT8 md5[CHD_MD5_BYTES]; /* overall MD5 checksum */ |
| 329 | UINT8 sha1[CHD_SHA1_BYTES]; /* overall SHA1 checksum */ |
| 330 | UINT8 rawsha1[CHD_SHA1_BYTES]; /* SHA1 checksum of raw data */ |
| 331 | UINT8 metasha1[CHD_SHA1_BYTES]; /* SHA1 checksum of metadata */ |
| 332 | }; |
| 333 | |
| 334 | |
| 335 | |
| 336 | /*************************************************************************** |
| 337 | FUNCTION PROTOTYPES |
| 338 | ***************************************************************************/ |
| 339 | |
| 340 | |
| 341 | /* ----- CHD file management ----- */ |
| 342 | |
| 343 | /* create a new CHD file fitting the given description */ |
| 344 | // chd_error chd_create(const char *filename, UINT64 logicalbytes, UINT32 hunkbytes, UINT32 compression, chd_file *parent); |
| 345 | |
| 346 | /* same as chd_create(), but accepts an already-opened core_file object */ |
| 347 | // chd_error chd_create_file(core_file *file, UINT64 logicalbytes, UINT32 hunkbytes, UINT32 compression, chd_file *parent); |
| 348 | |
| 349 | /* open an existing CHD file */ |
| 350 | chd_error chd_open(const char *filename, int mode, chd_file *parent, chd_file **chd); |
| 351 | |
| 352 | /* precache underlying file */ |
| 353 | chd_error chd_precache(chd_file *chd); |
| 354 | |
| 355 | /* close a CHD file */ |
| 356 | void chd_close(chd_file *chd); |
| 357 | |
| 358 | /* return the associated core_file */ |
| 359 | core_file *chd_core_file(chd_file *chd); |
| 360 | |
| 361 | /* return an error string for the given CHD error */ |
| 362 | const char *chd_error_string(chd_error err); |
| 363 | |
| 364 | |
| 365 | |
| 366 | /* ----- CHD header management ----- */ |
| 367 | |
| 368 | /* return a pointer to the extracted CHD header data */ |
| 369 | const chd_header *chd_get_header(chd_file *chd); |
| 370 | |
| 371 | |
| 372 | |
| 373 | |
| 374 | /* ----- core data read/write ----- */ |
| 375 | |
| 376 | /* read one hunk from the CHD file */ |
| 377 | chd_error chd_read(chd_file *chd, UINT32 hunknum, void *buffer); |
| 378 | |
| 379 | |
| 380 | |
| 381 | /* ----- metadata management ----- */ |
| 382 | |
| 383 | /* get indexed metadata of a particular sort */ |
| 384 | chd_error chd_get_metadata(chd_file *chd, UINT32 searchtag, UINT32 searchindex, void *output, UINT32 outputlen, UINT32 *resultlen, UINT32 *resulttag, UINT8 *resultflags); |
| 385 | |
| 386 | |
| 387 | |
| 388 | |
| 389 | /* ----- codec interfaces ----- */ |
| 390 | |
| 391 | /* set internal codec parameters */ |
| 392 | chd_error chd_codec_config(chd_file *chd, int param, void *config); |
| 393 | |
| 394 | /* return a string description of a codec */ |
| 395 | const char *chd_get_codec_name(UINT32 codec); |
| 396 | |
| 397 | #ifdef __cplusplus |
| 398 | } |
| 399 | #endif |
| 400 | |
| 401 | #endif /* __CHD_H__ */ |