Imgtool - A generic image manipulation tool for MESS

Imgtool is a tool for the maintenance and manipulation of disk and other types
of images that MESS users need to deal with.  Functions include retrieving and
storing files and CRC checking/validation.

Imgtool is part of the MESS project.  It shares large portions of code with
MESS/MAME, and its existance would not be if it were not for MESS.  As such,
the distribution terms are the same as MESS.  Please read mess.txt thouroughly.

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:

	imgtool <subcommand> <format> <image> ...

<subcommand> is the name of the subcommand
<format> is the format of the image
<image> is the filename of the image

Further details vary with each subcommand.  Also note that not all subcommands
are applicable or supported for different image formats.

Certain Imgtool subcommands (info, crc, good) make use of the CRC files, so if
you use these commands, make sure that your CRC directory is set up.

Imgtool Subcommands
===================

create            Creates an image
dir               Lists the contents of an image
get               Gets a single file from an image
put               Puts a single file on an image
getall            Gets all files off an image
del               Deletes a file on an image
info              Retrieves info about an image (by reading CRC files)
crc               Retrieves info about an image in the same format used by the
                  CRC files
good              CRC checks a set of images and for matching images, copy into
                  a new directory
listformats       Lists all image file formats supported by imgtool
listfilters       Lists all filters supported by imgtool
listdriveroptions Lists all format-specific options for the 'put' and 'create'
                  commands

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, only
three filters are supported:

  ascii           Translates end-of-lines to the appropriate format
  cocobas         Processes tokenized CoCo BASIC programs
  dragonbas       Processes tokenized Dragon BASIC programs

Format Info
===========

rsdos CoCo Disks
----------------
Fully implemented.  This format supports two format-specific options on the put
command:

  --ftype=(0|1|2|3) Specifies the file type
  --ascii=(A|B)     Specifies the ASCII flag

cococas CoCo Cassettes
----------------------
Both .cas and .wav supported, but read only.

lnx Commodore 64 Lynx Archive
-----------------------------
only for early revisions of lynx archivs
only extraction supported
not heavily tested

Lynx archivs could and should be handled in a c64 emulation 
with the native lynx tool


t64 Commodore 64/C64S Archive for Tapes
---------------------------------------
not heavily tested
further creation/use of these archivs discouraged


c64crt/crt Commodore 64 Cartridge
---------------------------------
for professional use only (cartridge dumper)
not heavily tested


d64 Commodore SX64/VC1541/1551/2031 Diskette
x64 VICE variant of the above
d71 Commodore 128D/1571 Diskette
d81 Commodore 65/1565/1581 Diskette
-----------------------------------
not heavily tested
x64: further creation/use discouraged


msdos/fat Microsoft DOS Diskette
--------------------------------
directories not finished
not heavily tested

Formatting (low and high level) must be done with the msdos utility format!
Boot structures must be installed on these disks with the msdos utility sys!

standard parameter for common disk formats:
type 0: 5 1/4 inch, double density, single sided, 160kb: sectors 8, heads 1, tracks 40
type 1: 5 1/4 inch, DD, SS, 180kb: sectors 9, heads 1, tracks 40
type 2: 5 1/4 inch, DD, double sided, 320kb: sectors 8, heads 2, tracks 40
type 3: 5 1/4 inch, DD, DS, 360kb: sectors 9, heads 2, tracks 40
type 4: 3 1/2 inch, DD, DS, 720kb: sectors 9, heads 2, tracks 80
at disk controller neccessary for high density
type 5: 5 1/4 inch, high density, DS, 1.2mb: sectors 15, heads 2, tracks 80
        3 1/2 inch, HD, DS, 1.2mb: sectors 15, heads 2, tracks 80
type 6: 3 1/2 inch, HD, DS, 1.44mb: sectors 18, heads 2, tracks 80
special disk controller neccessary for enhanced density
type 7: 3 1/2 inch, enhanced density, DS, 2.88mb: sectors 36, heads 2, tracks 80

unix with bash: use
dd if=/dev/zero of=<name.dsk> bs=512 count=$((9*2*40)) 
to generate standard blank 360kb image


msdoshd/fat Microsoft DOS Harddisk/PC Partition Table
-----------------------------------------------------
not finished and not working
(see also unter msdos/fat)

No low level format neccessary with image files
Partitioning must be done with the msdos utility fdisk
Then you can format each partition with msdos utility format

standard parameter for common disk formats:
type 0: 20mb standard pc/xt harddisk: 17 sectors, 4 heads, 615 cylinders

unix with bash: use
dd if=/dev/zero of=<name.dsk> bs=512 count=$((17*4*615)) 
to generate standard blank 20mb pc xt harddisk image


Virtual MSX tape archive
------------------------
not heavily tested
not fault-tolerant
dir/get/getall implemented, converts to .cas 


Virtual MSX Game Master 2 SRAM file
-----------------------------------
Very simple, not overly useful but some might want it. Virtual MSX stored the
SRAM of Konami's Game Master 2 in "gmaster2.ram". To convert this to something
useful with MESS and other MSX emulators, go:

imgtool extract vmsx_gm2 gmaster2.ram gmaster2.mem


fMSX style .cas file
--------------------
Converts .cas files to .wav files. The MSX driver can use .cas files directly
so you don't have to convert them. You can use it to export files to a real
MSX. Connect the MSX to the line out of your computer. Give the apropriate
command on the MSX (BLOAD "CAS:",R for example) and then play the .wav file
on your computer. 

Not tested at all, but it should work fine.

imgtool dir fmsx_cas file.cas
imgtool extract fmsx_cas file.cas file.wav
imgtool getall fmsx_cas file.cas
imgtool get fmsx_cas file.cas file.wav newfile.wav


Various bogus MSX disk images (xsa/img/ddi/msx)
-----------------------------------------------

These are formats you might come across, which have no actual added value
whatsoever. The only format MESS will support (not yet!), like other MSX
emulators, is .dsk (a plain dump without any header information). This
filetype converts them all to .dsk format.

img and ddi formats have a useless header, .msx has a weird sector order
(which is faster to save on a real MSX). .xsa is special format, not
nearly as useless as the others. It's basically a compressed format, it
doesn't matter what you use it for. However it's always been used for
disk images. The were programs written by XelaSoft which made a dump
of a disk, and compressing them at the same time. Very useful to store
a disk dump on another disk. zip/gzip offer much better compression and
are mainstream, so let's stick with that.

imgtool uses XSA code developed by Alex Wulms/XelaSoft.

http://web.inter.nl.net/users/A.P.Wulms/


rom16 16 bit wide rom image
---------------------------
allows easy access to even and odd parts
file even: even bytes
file odd: odd bytes

