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