mirror of
https://github.com/holub/mame
synced 2025-06-06 04:43:45 +03:00
chdman: Fixed a couple of issues and added preliminary web docs.
tools/chdman.cpp: Added --hunksize/-hs option for createdvd command and default to 4K hunks (2 sectors, same size as hard disk hunks). Also removed --outputbin/-ob option from extractdvd command - it did nothing as it's CD-specific. docs: Added preliminary chdman documentation. Most common options have at least basic descriptions, supported options are listed for all commands, and supported compression algorithms are described. docs: Cleaned up heading levels in tools section.
This commit is contained in:
Vas Crabb
parent
ac4bd1a7ea
commit
fa9d0fc32a
@ -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.
|
||||
|
||||
|
||||
393
docs/source/tools/chdman.rst
Normal file
393
docs/source/tools/chdman.rst
Normal file
@ -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.
|
||||
@ -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.
|
||||
|
||||
|
||||
@ -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:
|
||||
|
||||
|
||||
@ -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
|
||||
|
||||
@ -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());
|
||||
|
||||
|
||||
Loading…
Reference in New Issue
Block a user