ce188d4d |
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__ */ |