summaryrefslogtreecommitdiffstatshomepage
path: root/docs/source/tools
diff options
context:
space:
mode:
author Vas Crabb <vas@vastheman.com>2024-02-05 05:07:29 +1100
committer Vas Crabb <vas@vastheman.com>2024-02-05 05:07:29 +1100
commitfa9d0fc32aac619172361d62eb5070a9042465f8 (patch)
treeb24601fac56b41a63b43c3380398835517fff77c /docs/source/tools
parentac4bd1a7ea8ef0abd4b09ae3966f5a9887c60201 (diff)
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.
Diffstat (limited to 'docs/source/tools')
-rw-r--r--docs/source/tools/castool.rst4
-rw-r--r--docs/source/tools/chdman.rst393
-rw-r--r--docs/source/tools/floptool.rst4
-rw-r--r--docs/source/tools/imgtool.rst6
-rw-r--r--docs/source/tools/index.rst16
5 files changed, 409 insertions, 14 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