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
------------------------
Converts .tap files from Virtual MSX 1.x to .cas files. It is not
fault-tolerant. 


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 getall vmsx_gm2 gmaster2.ram 

You'll get a file called gmaster2.mem, which must place in the correct directory
of mess to use  (MESS\MEMCARD\GameMaster2 if your Game Master 2 .rom file is
called GameMaster2.rom). It's ~/.xmess/memcard/GameMaster2.mem for xmess.


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. 

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


XelaSoft Archive (.xsa)
-----------------------

The XelaSoft Archive is a compressed file. It can only contain one
file. Although it can contain any file, it's always used for MSX 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/


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

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

msx_img are disk images with an extra byte at the beginning. It' 1 (0x01)
for single-sided images and 2 (0x02) for double-side images. These 
files are at: ftp://ftp.funet.fi/pub/msx/. The extension is .img

msx_ddi are DiskDupe 5.12 disk images. There is a 0x1800 bytes header
at the beginning. The CompuJunkS MSX emulator used these files. The header
often contain garbage so it's simply stripped. The extension is .ddi

msx_msx are disk images with a weird sector order. You can find them
at: ftp://jazz.snu.ac.kr/pub/msx/. The extension is .msx

msx_mul are "multi disk" images, used by fmsx-dos 1.6. It is simply 
more than one .dsk image appended to one another. The extension is
still .dsk, but the file is larger than 720kB (actually always a 
multiple of 720kB.


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


Amstrad NC100/NC150/NC200 PCMCIA Ram Card Images (crd/card)
-----------------------------------------------------------

The card filesystem is similar to FAT, but not identical.
The maximum card size is 1mb, and maximum file size is 64k.
(Files will be cut at 64k if they are larger - e.g. when putting a large file)

As far as I know there is no directory system, however there is always a 
system "NC100" directory which points to the root directory. (Like the DOS "."
directory).

Using imgtool, you can put, get and delete files.

At this time only ascii file type is supported. These files can be loaded
into the internal wordprocessor,or,if the file is a BASIC listing, it can
be loaded into basic with "*EXEC <filename>" at the ">" prompt.

From BASIC you can get a directory listing of the card filesystem with "*."
at the ">" prompt.

The file date information is not supported at this time.

The card filesystem reading/writing in imgtool has not been heavily tested.



Texas Instruments calculators variable files
--------------------------------------------

+--------+------------------------------------------+-----------+
| Format | Description                              | Extension |
+--------+------------------------------------------+-----------+
| ti85p  | TI-85 program file                       |    85p    |
| ti85s  | TI-85 string file (also ZShell programs) |    85s    |
| ti85i  | TI-85 picture file (85-image)            |    85i    |
| ti85n  | TI-85 real number file                   |    85n    |
| ti85c	 | TI-85 complex number file                |    85c    |
| ti85l  | TI-85 list (real or complex)             |    85l    |
| ti85k  | TI-85 constant file                      |    85k    |
| ti85m  | TI-85 matrix (real or complex) file      |    85m    |
| ti85v  | TI-85 vector (real or complex) file      |    85v    |
| ti85d  | TI-85 graphics database file             |    85d    |
| ti85e  | TI-85 equation file                      |    85e    |
| ti85r  | TI-85 range settings file                |    85r    |
| ti85g	 | TI-85 grouped file                       |    85g    |
| ti85   | TI-85 generic file                       |    85?    |
| ti86p  | TI-86 program file                       |    86p    |
| ti86s  | TI-86 string file                        |    86s    |
| ti86i  | TI-86 picture file (85-image)            |    86i    |
| ti86n  | TI-86 real number file                   |    86n    |
| ti86c  | TI-86 complex number file                |    86c    |
| ti86l  | TI-86 list (real or complex) file        |    86l    |
| ti86k	 | TI-86 constant file                      |    86k    |
| ti86m  | TI-86 matrix (real or complex) file      |    86m    |
| ti86v  | TI-86 vector (real or complex) file      |    86v    |
| ti86d  | TI-86 graphics database file             |    86d    |
| ti86e  | TI-86 equation file                      |    86e    |
| ti86r  | TI-86 range settings file                |    86r    |
| ti86g  | TI-86 grouped file                       |    86g    |
| ti86   | TI-86 generic file                       |    86?    |
+--------+------------------------------------------+-----------+

Grouped formats (ti85g and ti86g) can keep more than one variable.
Generic formats (ti85 and ti86) can be used for all types of variable files.
For all types of variable files dir, create, put, get and delete commands are
supported.


Texas Instruments calculators memory backup files
-------------------------------------------------

+--------+------------------------------------------+-----------+
| Format | Description                              | Extension |
+--------+------------------------------------------+-----------+
| ti85b  | TI-85 memory backup file                 |    85b    |
+--------+------------------------------------------+-----------+

For TI memory backup files only dir command is supported.
