b24e7fce |
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 | |
350 | #ifdef _MSC_VER |
351 | #ifdef CHD_DLL |
352 | #ifdef CHD_DLL_EXPORTS |
353 | #define CHD_EXPORT __declspec(dllexport) |
354 | #else |
355 | #define CHD_EXPORT __declspec(dllimport) |
356 | #endif |
357 | #else |
358 | #define CHD_EXPORT |
359 | #endif |
360 | #else |
361 | #define CHD_EXPORT __attribute__ ((visibility("default"))) |
362 | #endif |
363 | |
364 | /* ----- CHD file management ----- */ |
365 | |
366 | /* create a new CHD file fitting the given description */ |
367 | /* chd_error chd_create(const char *filename, UINT64 logicalbytes, UINT32 hunkbytes, UINT32 compression, chd_file *parent); */ |
368 | |
369 | /* same as chd_create(), but accepts an already-opened core_file object */ |
370 | /* chd_error chd_create_file(core_file *file, UINT64 logicalbytes, UINT32 hunkbytes, UINT32 compression, chd_file *parent); */ |
371 | |
372 | /* open an existing CHD file */ |
373 | CHD_EXPORT chd_error chd_open_file(core_file *file, int mode, chd_file *parent, chd_file **chd); |
374 | CHD_EXPORT chd_error chd_open(const char *filename, int mode, chd_file *parent, chd_file **chd); |
375 | |
376 | /* precache underlying file */ |
377 | CHD_EXPORT chd_error chd_precache(chd_file *chd); |
378 | |
379 | /* close a CHD file */ |
380 | CHD_EXPORT void chd_close(chd_file *chd); |
381 | |
382 | /* return the associated core_file */ |
383 | CHD_EXPORT core_file *chd_core_file(chd_file *chd); |
384 | |
385 | /* return an error string for the given CHD error */ |
386 | CHD_EXPORT const char *chd_error_string(chd_error err); |
387 | |
388 | |
389 | |
390 | /* ----- CHD header management ----- */ |
391 | |
392 | /* return a pointer to the extracted CHD header data */ |
393 | CHD_EXPORT const chd_header *chd_get_header(chd_file *chd); |
394 | |
395 | /* read CHD header data from file into the pointed struct */ |
396 | CHD_EXPORT chd_error chd_read_header(const char *filename, chd_header *header); |
397 | |
398 | |
399 | |
400 | /* ----- core data read/write ----- */ |
401 | |
402 | /* read one hunk from the CHD file */ |
403 | CHD_EXPORT chd_error chd_read(chd_file *chd, UINT32 hunknum, void *buffer); |
404 | |
405 | |
406 | |
407 | /* ----- metadata management ----- */ |
408 | |
409 | /* get indexed metadata of a particular sort */ |
410 | CHD_EXPORT chd_error chd_get_metadata(chd_file *chd, UINT32 searchtag, UINT32 searchindex, void *output, UINT32 outputlen, UINT32 *resultlen, UINT32 *resulttag, UINT8 *resultflags); |
411 | |
412 | |
413 | |
414 | |
415 | /* ----- codec interfaces ----- */ |
416 | |
417 | /* set internal codec parameters */ |
418 | CHD_EXPORT chd_error chd_codec_config(chd_file *chd, int param, void *config); |
419 | |
420 | /* return a string description of a codec */ |
421 | CHD_EXPORT const char *chd_get_codec_name(UINT32 codec); |
422 | |
423 | #ifdef __cplusplus |
424 | } |
425 | #endif |
426 | |
427 | #endif /* __CHD_H__ */ |