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