diff options
-rw-r--r-- | docs/source/tools/castool.rst | 4 | ||||
-rw-r--r-- | docs/source/tools/chdman.rst | 393 | ||||
-rw-r--r-- | docs/source/tools/floptool.rst | 4 | ||||
-rw-r--r-- | docs/source/tools/imgtool.rst | 6 | ||||
-rw-r--r-- | docs/source/tools/index.rst | 16 | ||||
-rw-r--r-- | src/tools/chdman.cpp | 10 |
6 files changed, 416 insertions, 17 deletions
diff --git a/docs/source/tools/castool.rst b/docs/source/tools/castool.rst index b4d8f81467f..73fb095d9b1 100644 --- a/docs/source/tools/castool.rst +++ b/docs/source/tools/castool.rst @@ -9,7 +9,7 @@ Castool is part of the MAME project. It shares large portions of code with MAME, Using Castool -============= +------------- Castool is a command line program that contains a simple set of instructions. Commands are invoked in a manner along the lines of this: @@ -30,7 +30,7 @@ Example usage: Castool Formats -=============== +--------------- These are the formats supported by Castool for conversion to .WAV files. diff --git a/docs/source/tools/chdman.rst b/docs/source/tools/chdman.rst new file mode 100644 index 00000000000..f23a21cddf5 --- /dev/null +++ b/docs/source/tools/chdman.rst @@ -0,0 +1,393 @@ +.. _chdman: + +chdman – CHD (Compressed Hunks of Data) File Manager +==================================================== + +chdman can be used to create, convert, check the integrity of and extract data +from media images in CHD (Compressed Hunks of Data) format. + +The basic usage is ``chdman <command> <option>...`` + +.. contents:: :local: + + +.. _chdman-commonopts: + +Common options +-------------- + +The options available depend on the command, but the following options are +used by multiple commands: + +--input <file> / -i <file> + Specify the input file. This option is required for most commands. The + input file formats supported depend on the command +--inputparent <chdfile> / -ip <chdfile> + Specify the parent CHD file for the input file. This option is supported for + most commands that operate on CHD format input files. This option must be + used if the input file is a *delta CHD*, storing only the hunks that differ + from its parent CHD, +--output <file> / -o <file> + Specify the output file name. This option is required for commands that + produce output files. The output file formats supported depend on the + command. +--outputparent <chdfile> / -op <chdfile> + Specify the parent CHD file for the output file. This option is supported + for commands that produce CHD format output files. Using this option + produces a *delta CHD*, storing only the hunks that differ from its parent + CHD. The parent CHD should be the same media type and size, with the same + hunk size. +--compression none|<type>[,<type>]... / -c none|<type>[,<type>]... + Specify compression algorithms to use. This option is supported for commands + that produce CHD format output files. Specify ``none`` to disable + compression, or specify up to four comma-separated compression algorithms. + See :ref:`compression algorithms <chdman-compression>` for supported + compression algorithms. Compression must be disable to create writable media + image files. +--hunksize <bytes> / -hs <bytes> + Specifies the hunk size in bytes. This option is supported for commands that + produce CHD format output files. The hunk size must be no smaller than + 16 bytes and no larger than 1048576 bytes (1 MiB). The hunk size must be a + multiple of the sector size or unit size of the media. Larger hunk sizes may + give better compression ratios, but reduce performance for small random + reads as an entire hunk needs to be read and decompressed at a time. +--force / -f + Overwrite output files if they already exist. This option is supported for + commands that produce output files. +--verbose / -v + Enable verbose output. This prints more detailed information for some + commands. +--numprocessors <count> / -np <count> + Limit the maximum number of concurrent threads used for data compression. + This option is supported for commands that produce CHD format output files. + + +.. _chdman-commands: + +Commands +-------- + +info +~~~~ + +Display information about a CHD format file. Information includes: + +* CHD format version and compression algorithms used. +* Compressed and uncompressed sizes and overall compression ratio. +* Hunk size, unit size and number of hunks in the file. +* SHA1 digests of the data and metadata. + +Common options supported: + +* ``--input <file>`` / ``-i <file>`` (required) +* ``--verbose`` / ``-v`` + +verify +~~~~~~ + +Verify the integrity of a CHD format file. The input file must be a read-only +CHD format file (the integrity of writable CHD files cannot be verified). + +Common options supported: + +* ``--input <file>`` / ``-i <file>`` (required) +* ``--inputparent <chdfile>`` / ``-ip <chdfile>`` + +createraw +~~~~~~~~~ + +Create a CHD format file from a raw media image. + +Common options supported: + +* ``--input <file>`` / ``-i <file>`` (required) +* ``--output <file>`` / ``-o <file>`` (required) +* ``--outputparent <chdfile>`` / ``-op <chdfile>`` +* ``--compression none|<type>[,<type>]...`` / ``-c none|<type>[,<type>]...`` +* ``--hunksize <bytes>`` / ``-hs <bytes>`` (required) +* ``--force`` / ``-f`` +* ``--numprocessors <count>`` / ``-np <count>`` + +Additional options: + +* ``--unitsize <bytes>`` / ``-us <bytes>`` (required) +* ``--inputstartbyte <offset>`` / ``-isb <offset>`` +* ``--inputstarthunk <offset>`` / ``-ish <offset>`` +* ``--inputbytes <length>`` / ``-ib <length>`` +* ``--inputhunks <length>`` / ``-ih <length>`` + +If the ``--compression`` or ``-c`` option is not supplied, it defaults to +``lzma,zlib,huff,flac``. + +createhd +~~~~~~~~ + +Create a CHD format hard disk image file. + +Common options supported: + +* ``--input <file>`` / ``-i <file>`` (required) +* ``--output <file>`` / ``-o <file>`` (required) +* ``--outputparent <chdfile>`` / ``-op <chdfile>`` +* ``--compression none|<type>[,<type>]...`` / ``-c none|<type>[,<type>]...`` +* ``--hunksize <bytes>`` / ``-hs <bytes>`` (required) +* ``--force`` / ``-f`` +* ``--numprocessors <count>`` / ``-np <count>`` + +Additional options: + +* ``--sectorsize <bytes>`` / ``-ss <bytes>`` +* ``--size <bytes>`` / ``-s <bytes>`` +* ``--chs <cylinders>,<heads>,<sectors>`` / ``-chs <cylinders>,<heads>,<sectors>`` +* ``--template <template>`` / ``-tp <template>`` +* ``--inputstartbyte <offset>`` / ``-isb <offset>`` +* ``--inputstarthunk <offset>`` / ``-ish <offset>`` +* ``--inputbytes <length>`` / ``-ib <length>`` +* ``--inputhunks <length>`` / ``-ih <length>`` + +If the ``--compression`` or ``-c`` option is not supplied, it defaults to +``lzma,zlib,huff,flac``. + +createcd +~~~~~~~~ + +Create a CHD format CD-ROM image file. + +Common options supported: + +* ``--input <file>`` / ``-i <file>`` (required) +* ``--output <file>`` / ``-o <file>`` (required) +* ``--outputparent <chdfile>`` / ``-op <chdfile>`` +* ``--compression none|<type>[,<type>]...`` / ``-c none|<type>[,<type>]...`` +* ``--hunksize <bytes>`` / ``-hs <bytes>`` (required) +* ``--force`` / ``-f`` +* ``--numprocessors <count>`` / ``-np <count>`` + +If the ``--compression`` or ``-c`` option is not supplied, it defaults to +``cdlz,cdzl,cdfl``. + +createdvd +~~~~~~~~~ + +Create a CHD format DVD-ROM image file. + +Common options supported: + +* ``--input <file>`` / ``-i <file>`` (required) +* ``--output <file>`` / ``-o <file>`` (required) +* ``--outputparent <chdfile>`` / ``-op <chdfile>`` +* ``--compression none|<type>[,<type>]...`` / ``-c none|<type>[,<type>]...`` +* ``--hunksize <bytes>`` / ``-hs <bytes>`` (required) +* ``--force`` / ``-f`` +* ``--numprocessors <count>`` / ``-np <count>`` + +If the ``--compression`` or ``-c`` option is not supplied, it defaults to +``lzma,zlib,huff,flac``. + +createld +~~~~~~~~ + +Create a CHD format LaserDisc image file. + +Common options supported: + +* ``--input <file>`` / ``-i <file>`` (required) +* ``--output <file>`` / ``-o <file>`` (required) +* ``--outputparent <chdfile>`` / ``-op <chdfile>`` +* ``--compression none|<type>[,<type>]...`` / ``-c none|<type>[,<type>]...`` +* ``--hunksize <bytes>`` / ``-hs <bytes>`` (required) +* ``--force`` / ``-f`` +* ``--numprocessors <count>`` / ``-np <count>`` + +Additional options: + +* ``--inputstartframe <offset>`` / ``-isf <offset>`` +* ``--inputframes <length>`` / ``-if <length>`` + +If the ``--compression`` or ``-c`` option is not supplied, it defaults to +``avhu``. + +extractraw +~~~~~~~~~~ + +Extract data from a CHD format raw media image. + +Common options supported: + +* ``--input <file>`` / ``-i <file>`` (required) +* ``--inputparent <chdfile>`` / ``-ip <chdfile>`` +* ``--output <file>`` / ``-o <file>`` (required) +* ``--force`` / ``-f`` + +Additional options: + +* ``--inputstartbyte <offset>`` / ``-isb <offset>`` +* ``--inputstarthunk <offset>`` / ``-ish <offset>`` +* ``--inputbytes <length>`` / ``-ib <length>`` +* ``--inputhunks <length>`` / ``-ih <length>`` + +extracthd +~~~~~~~~~ + +Extract data from a CHD format hard disk image. + +Common options supported: + +* ``--input <file>`` / ``-i <file>`` (required) +* ``--inputparent <chdfile>`` / ``-ip <chdfile>`` +* ``--output <file>`` / ``-o <file>`` (required) +* ``--force`` / ``-f`` + +Additional options: + +* ``--inputstartbyte <offset>`` / ``-isb <offset>`` +* ``--inputstarthunk <offset>`` / ``-ish <offset>`` +* ``--inputbytes <length>`` / ``-ib <length>`` +* ``--inputhunks <length>`` / ``-ih <length>`` + +extractcd +~~~~~~~~~ + +Extract data from a CHD format CD-ROM image. + +Common options supported: + +* ``--input <file>`` / ``-i <file>`` (required) +* ``--inputparent <chdfile>`` / ``-ip <chdfile>`` +* ``--output <file>`` / ``-o <file>`` (required) +* ``--force`` / ``-f`` + +Additional options: + +* ``--outputbin <file>`` / ``-ob <file>`` + +extractdvd +~~~~~~~~~~ + +Extract data from a CHD format DVD-ROM image. + +Common options supported: + +* ``--input <file>`` / ``-i <file>`` (required) +* ``--inputparent <chdfile>`` / ``-ip <chdfile>`` +* ``--output <file>`` / ``-o <file>`` (required) +* ``--force`` / ``-f`` + +extractld +~~~~~~~~~ + +Extract data from a CHD format DVD-ROM image. + +Common options supported: + +* ``--input <file>`` / ``-i <file>`` (required) +* ``--inputparent <chdfile>`` / ``-ip <chdfile>`` +* ``--output <file>`` / ``-o <file>`` (required) +* ``--force`` / ``-f`` + +Additional options: + +* ``--inputstartframe <offset>`` / ``-isf <offset>`` +* ``--inputframes <length>`` / ``-if <length>`` + +addmeta +~~~~~~~ + +Add a metadata item to a CHD format file. Note that this command modifies its +input file. + +Common options supported: + +* ``--input <file>`` / ``-i <file>`` (required) + +Additional options: + +* ``--tag <tag>`` / ``-t <tag>`` (required) +* ``--index <index>`` / ``-ix <index>`` +* ``--valuetext <text>`` / ``-vt <text>`` +* ``--valuefile <file>`` / ``-vf <file>`` +* ``--nochecksum`` / ``-nocs`` + +delmeta +~~~~~~~ + +Delete a metadata item from a CHD format file. Note that this command modifies +its input file. + +Common options supported: + +* ``--input <file>`` / ``-i <file>`` (required) + +Additional options: + +* ``--tag <tag>`` / ``-t <tag>`` (required) +* ``--index <index>`` / ``-ix <index>`` + +dumpmeta +~~~~~~~~ + +Extract metadata items from a CHD format file to the standard output or to a +file. + +Common options supported: + +* ``--input <file>`` / ``-i <file>`` (required) +* ``--output <file>`` / ``-o <file>`` +* ``--force`` / ``-f`` + +Additional options: + +* ``--tag <tag>`` / ``-t <tag>`` (required) +* ``--index <index>`` / ``-ix <index>`` + +listtemplates +~~~~~~~~~~~~~ + +List available hard disk templates. This command does not accept any options. + + +.. _chdman-compression: + +Compression algorithms +---------------------- + +The following compression algorithms are supported: + +zlib – zlib deflate + Compresses data using the zlib deflate algorithm. +zstd – Zstandard + Compresses data using the Zstandard algorithm. This gives very good + compression and decompression performance with better compression ratios than + zlib deflate, but older software may not support CHD files that use Zstandard + compression. +lzma – Lempel-Ziv-Markov chain algorithm + Compresses data using the Lempel-Ziv-Markov-chain algorithm (LZMA). This + gives high compression ratios at the cost of poor compression and + decompression performance. +huff – Huffman coding + Compresses data using 8-bit Huffman entropy coding. +flac – Free Lossless Audio Codec + Compresses data as two-channel (stereo) 16-bit 44.1 kHz PCM audio using the + Free Lossless Audio Codec (FLAC). This gives good compression ratios if the + media contains 16-bit PCM audio data. +cdzl – zlib deflate for CD-ROM data + Compresses audio data and subchannel data from CD-ROM sectors separately + using the zlib deflate algorithm. +cdzs – Zstandard for CD-ROM data + Compresses audio data and subchannel data from CD-ROM sectors separately + using the Zstandard algorithm. This gives very good compression and + decompression performance with better compression ratios than zlib deflate, + but older software may not support CHD files that use Zstandard compression. +cdlz - Lempel-Ziv-Markov chain algorithm/zlib deflate for CD-ROM data + Compresses audio data and subchannel data from CD-ROM sectors separately + using the Lempel-Ziv-Markov chain algorithm (LZMA) for audio data and the + zlib deflate algorithm for subchannel data. This gives high compression + ratios at the cost of poor compression and decompression performance. +cdfl – Free Lossless Audio Codec/zlib deflate for CD-ROM data + Compresses audio data and subchannel data from CD-ROM sectors separately + using the Free Lossless Audio Codec (FLAC) for audio data and the zlib + deflate algorithm for subchannel data. This gives good compression ratios + for audio CD tracks. +avhu – Huffman coding for audio-visual data + This is a specialised compression algorithm for audio-visual (A/V) data. It + should only be used for LaserDisc CHD files. diff --git a/docs/source/tools/floptool.rst b/docs/source/tools/floptool.rst index f2e24eac56f..bf71c296aee 100644 --- a/docs/source/tools/floptool.rst +++ b/docs/source/tools/floptool.rst @@ -9,7 +9,7 @@ Floptool is part of the MAME project. It shares large portions of code with MAME Using Floptool -============== +-------------- Floptool is a command line program that contains a simple set of instructions. Commands are invoked in a manner along the lines of this: @@ -33,7 +33,7 @@ Example usage: Floptool Formats -================ +---------------- These are the formats supported by Floptool for conversion to other formats. diff --git a/docs/source/tools/imgtool.rst b/docs/source/tools/imgtool.rst index 7efa850ca93..e54638ea59b 100644 --- a/docs/source/tools/imgtool.rst +++ b/docs/source/tools/imgtool.rst @@ -10,7 +10,7 @@ Imgtool is part of the MAME project. It shares large portions of code with MAME, **Some portions of Imgtool are Copyright (c) 1989, 1993 The Regents of the University of California. All rights reserved.** Using Imgtool -============= +------------- Imgtool is a command line program that contains several "subcommands" that actually do all of the work. Most commands are invoked in a manner along the lines of this: @@ -32,7 +32,7 @@ Further details vary with each subcommand. Also note that not all subcommands a Imgtool Subcommands -=================== +------------------- **create** @@ -151,7 +151,7 @@ Imgtool Subcommands Imgtool Filters -=============== +--------------- Filters are a means to process data being written into or read out of an image in a certain way. Filters can be specified on the get, put, and getall commands by specifying --filter=xxxx on the command line. Currently, the following filters are supported: diff --git a/docs/source/tools/index.rst b/docs/source/tools/index.rst index 6d0551bf1d1..4086f924b99 100644 --- a/docs/source/tools/index.rst +++ b/docs/source/tools/index.rst @@ -1,12 +1,14 @@ MAME External Tools -------------------- +=================== -This section covers various extra tools that come with your MAME distribution (e.g. *imgtool*) +This section describes additional tools that are built alongside and typically +distributed with MAME. .. toctree:: - :titlesonly: + :titlesonly: - imgtool - castool - floptool - othertools + chdman + imgtool + castool + floptool + othertools diff --git a/src/tools/chdman.cpp b/src/tools/chdman.cpp index 3a4277c50d1..c613a968bad 100644 --- a/src/tools/chdman.cpp +++ b/src/tools/chdman.cpp @@ -710,6 +710,7 @@ static const command_description s_commands[] = OPTION_OUTPUT_PARENT, OPTION_OUTPUT_FORCE, REQUIRED OPTION_INPUT, + OPTION_HUNK_SIZE, OPTION_COMPRESSION, OPTION_NUMPROCESSORS } @@ -768,7 +769,6 @@ static const command_description s_commands[] = { COMMAND_EXTRACT_DVD, do_extract_dvd, ": extract DVD file from a CHD input file", { REQUIRED OPTION_OUTPUT, - OPTION_OUTPUT_BIN, OPTION_OUTPUT_FORCE, REQUIRED OPTION_INPUT, OPTION_INPUT_PARENT, @@ -2110,6 +2110,10 @@ static void do_create_dvd(parameters_map ¶ms) chd_file output_parent; std::string *output_chd_str = parse_output_chd_parameters(params, output_parent); + // process hunk size + uint32_t hunk_size = output_parent.opened() ? output_parent.hunk_bytes() : (2 * 2048); + parse_hunk_size(params, 2048, hunk_size); + // process input start/end uint64_t filesize = 0; input_file->length(filesize); // FIXME: check error return @@ -2146,9 +2150,9 @@ static void do_create_dvd(parameters_map ¶ms) chd.reset(new chd_rawfile_compressor(*input_file, 0, filesize)); std::error_condition err; if (output_parent.opened()) - err = chd->create(output_chd_str->c_str(), uint64_t(totalsectors) * 2048, 2048, compression, output_parent); + err = chd->create(output_chd_str->c_str(), uint64_t(totalsectors) * 2048, hunk_size, compression, output_parent); else - err = chd->create(output_chd_str->c_str(), uint64_t(totalsectors) * 2048, 2048, 2048, compression); + err = chd->create(output_chd_str->c_str(), uint64_t(totalsectors) * 2048, hunk_size, 2048, compression); if (err) report_error(1, "Error creating CHD file (%s): %s", output_chd_str, err.message()); |