summaryrefslogtreecommitdiffstatshomepage
path: root/docs/imgtool.txt
diff options
context:
space:
mode:
Diffstat (limited to 'docs/imgtool.txt')
-rw-r--r--docs/imgtool.txt577
1 files changed, 577 insertions, 0 deletions
diff --git a/docs/imgtool.txt b/docs/imgtool.txt
new file mode 100644
index 00000000000..d770eccbaeb
--- /dev/null
+++ b/docs/imgtool.txt
@@ -0,0 +1,577 @@
+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 existence would not be if it were not for MESS. As such,
+the distribution terms are the same as MESS. Please read mess.txt thoroughly.
+
+Some portions in Imgtool is 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:
+
+ 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 (wildcards supported)
+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=(basic|data|binary|assembler) Specifies the file type
+ --ascii=(ascii|binary) 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 necessary 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 necessary 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 necessary 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.
+
+
+TI99 floppy disk images (v9t9/pc99fm/pc99mfm/ti99_old)
+------------------------------------------------------
+
+These modules enable you to create and catalog ti99 images, to delete
+individual files and directories, and to get and put files in TIFILE format.
+Note that you cannot create images in pc99 format.
+
+The v9t9 module supports the v9t9 disk images that is used by MESS, the pc99fm
+module supports FM-encoded pc99 images, and the pc99mfm supports MFM-encoded
+pc99 images, and the ti99_old module supports the now obsolete image format
+that was used by MESS versions prior to .69. The MESS ti99 drivers supports
+the v9t9 disk image format only. (Note that the old MESS format was identical
+to the V9T9 format for single-sided disks, but that the track order was
+completely different for double-sided disks, which caused the two formats to be
+incompatible for double-sided disk images. I have changed the format to v9t9
+as this format is used by most other TI99 utilities and emulators.)
+
+The TIFILE format is a file format that is supported by many ti99 utilities: it
+encodes a TI99 file as a flat stream of bytes, which enables to store it on
+file systems that do not support the TI99 file structure and to transmit it
+through networks. This format uses a data format similar to the one used on
+ti99 floppies (i.e. logical records are grouped in physical records of 256
+bytes), with a custom 128-byte header.
+
+Legal characters for volume and file names are upper case ASCII characters,
+except period ('.') and space (' '). Lower case characters are not recommended
+because they are not supported by TI99/4. You had better avoid control
+characters and non-ASCII characters, too. (Additionally, the NULL character is
+forbidden in file names, but I think nobody in his right sense would even try
+to enter a NULL character in a file name.) The restriction on the period ('.')
+character may sound strange to users of other OSes, but this character is used
+as a path separator by TI systems. (As a matter of fact, no TI99 floppy disk
+DSR (except the HFDC DSR) implements disk directories, but other TI systems
+implement this convention extensively.) Since period is used as the path
+separator, TI99 users often use the slash ('/') or dash ('-') characters as
+file extension separators; note, however, that the use of file extensions is
+never systematic in TI99: you may use file extensions if you find them useful,
+just like you may use any other file naming scheme, but no program enforce or
+require filename extensions as it is often the case in the DOS/windows world.
+
+
+Parameters for create:
+
+--label=...: an optional string of up to 10 characters.
+--sides=[1|2]: 1 for single-sided, 2 for double-sided.
+--tracks=[1-80]: number of track per side. Should be 40 for a 40-track disk,
+ and 80 for an 80-track disk.
+--sectors=[1-36]: number of sectors per track. Should be 9 in single density
+ (FM), 18 in double density (MFM), and 36 in high density (MFM).
+--protection=[0|1]: when set to 1, the disk will be protected and some (but not
+ all) TI99 programs won't overwrite the disk.
+--density=[Auto|SD|DD|HD]: you should probably leave this parameter to Auto, so
+ that imgtool picks the correct value automatically (according to the number
+ of sectors per track). If you really need to, SD forces single density
+ (FM), DD forces double density (MFM), and HD forces high density (MFM).
+
+Supported geometries for create:
+
+ description |sides|tracks|sectors| size | FDC Compatibility (1)
+ | | | | |
+SSSD 48TPI 5"1/4 | 1 | 40 | 9 | 90K | All
+ | | | | |
+DSSD 48TPI 5"1/4 | 2 | 40 | 9 | 180K | All
+ | | | | |
+DSDD 48TPI 5"1/4 | 2 | 40 | 18 | 360K | SNUG BwG, Myarc HFDC
+ | | | | |
+DSDD 96TPI 5"1/4 | 2 | 80 | 18 | 720K | Myarc HFDC (2)
+or DSDD 3"1/2 | | | | |
+ | | | | |
+DSHD 3"1/2 | 2 | 80 | 36 |1.44M | Myarc HFDC (Geneve Only) (3)
+
+(1) Only emulated controllers are listed in this table
+(2) SNUG BwG can read such images, but it will corrupt them when writing new
+ data to them
+(3) You cannot boot from such images (this is because the Geneve MDOS operating
+ system needs to replaces the incomplete HFDC DSR with a better DSR to
+ support HD: since MDOS is not loaded yet at boot time, you cannot boot from
+ a HD disk).
+
+
+Examples:
+
+List the catalog of image test.dsk:
+imgtool dir v9t9 test.dsk
+
+Extract file FILE1 located on image test.dsk:
+imgtool get v9t9 test.dsk FILE1
+
+Extract file FILE1 located in subdirectory SUBDIR1 on image test.dsk:
+imgtool get v9t9 test.dsk SUBDIR1.FILE1
+
+Write file FILE1 on image test.dsk:
+imgtool put v9t9 test.dsk FILE1
+(Note that file FILE1 must not exist before the command is run. Use the delete
+command first if you need to overwrite an existing file.)
+
+Delete file FILE1 located in subdirectory SUBDIR1 on image test.dsk:
+imgtool delete v9t9 test.dsk SUBDIR1.FILE1
+
+Delete subdirectory SUBDIR1 on image test.dsk:
+imgtool delete v9t9 test.dsk SUBDIR1
+(Subdirectory SUBDIR1 must be empty.)
+
+Create a SSSD image compatible with all controllers:
+imgtool create v9t9 test.dsk --sides=1 --tracks=40 --sectors=9
+
+Create a DSSD image compatible with all controllers:
+imgtool create v9t9 test.dsk --sides=2 --tracks=40 --sectors=9
+
+Create a DSDD image compatible with BwG and HFDC controllers:
+imgtool create v9t9 test.dsk --sides=2 --tracks=40 --sectors=18
+
+Create a 80-track DSDD image compatible with the HFDC controller:
+imgtool create v9t9 test.dsk --sides=2 --tracks=80 --sectors=18
+
+Create a DSHD image compatible with the Geneve with a HFDC controller:
+imgtool create v9t9 test.dsk --sides=2 --tracks=80 --sectors=36
+
+
+TI99 hard disk images (ti99hd)
+------------------------------
+
+This module can catalog ti99 hard disk images, delete individual files and
+directories, and get and put files in TIFILE format. Only images in HFDC
+format are supported for now (no SCSI format).
+
+
+TI990 disk images (ti990hd)
+---------------------------
+
+This module supports disk images in DNOS format (which appears to be virtually
+identical to DX10 3.x format). Although the module is named ti990hd, this
+module will work fine with floppy images as well as hard disk images: just make
+sure that the disks are formatted in the proper format, as neither DX10 2.x nor
+TX990 formats are supported.
+
+
+Parameters for create:
+
+The most interesting command is create, as you cannot create new images within
+emulation.
+
+--cylinders: number of cylinders
+--heads: number of heads
+--sectors: number of sectors per track
+--seclen: bytes per sector
+
+
+Known restrictions on geometry:
+
+256 < bytes per sector < 512 (arbitrary restriction, actual TI990s might
+ accept values out of this range)
+bytes per sector must be even
+3 < # cylinders < 2047
+1 < # heads < 31
+1 < sectors per track < 256
+(sectors per track) * (bytes per sector) < 2^17 = 131072 (which implies
+ (sectors per track) < 255 if sectors are 512-byte long)
+
+(There are probably other restrictions, so you had better stick to values
+similar to the ones used by actual disk units... Also note that according to
+the Spectra 126-Plus manual, ADU size limitations prevent most operating
+systems from supporting units larger than 500MBytes.)
+
+
+Known drive geometries:
+
+(Sources: 946250-9703 p. 3-14, 2270512-9701 p. 11-3, 945250-9701 pp. 5-20
+through 5-28, 946250-9701B pp. 2-1 through 2-3, 2540219A-0001 pp. 4-2 and 4-3,
+2306140-9701 p. 1-15, 223439B-9701 pp. 3-14 and 3-28. See also "Spectra
+126-Plus Product Reference Manual" by Cipher P/N 8500055 revision A4 page 2-8.)
+
+Disk Type Units Size (MB) Cylinders Heads Sectors/Track Bytes/Sector
+FD800 (min) 1 .244 77 1 26 128
+FD800 (max) 1 .978??? 77 2??? 26??? 256???
+FD1000 1 1.15 77 2 26 288
+DS31/DS32 1 2.81 203 2 24 288
+DS10 2 4.70 408 2(*2) 20 288
+DS25 1 22.3 408 5 38 288
+DS50 1 44.6 815 5 38 288
+DS200 1 169.5 815 19 38 288
+CD1400-32 2 13.5 821(h) 1 64 256
+CD1400-64 (rem) 1 13.5 821(h) 1 64 256
+CD1400-64 (fix) 1 38.5 821(h) 3 64 256
+CD1400-96 (rem) 1 13.5 821(h) 1 64 256
+CD1400-96 (fix) 1 67.3 821(h) 5 64 256
+DS80 1 62.7 803(g) 5 61 256
+DS300 1 238.3 803(c) 19 61 256
+WD800-18 1 18.5 651(b) 3 37 256
+WD800-43 1 43.2 651(b) 7 37 256
+WD800A/38 1 38.5 911(d) 5 33 256
+WD800A/69 1 69.3 911(d) 9 33 256
+WD800A/114 1 114.6 904(d) 15 33 256
+WD500 1 4.92 150(a) 4 32 256
+WD500A 1 17.1 694(a) 3 32 256
+WD900-138 1 138.1 805(e) 10 67 256
+WD900-138/2 2 69.0 805(e) 5(*2) 67 256
+WD900-425 1 425.8 693(e) 24 100 256
+WD900-425/2 2 212.9 693(e) 12(*2) 100 256
+MSU II 1 158.8 957(f) 9 36 512
+MSU IIA 1 332.9 1204(f) 15 36 512
+
+a) some extra cylinders are reserved for diagnostics
+b) 6 extra cylinders are reserved for storage system use (including 2 for
+ diagnostics)
+c) some extra cylinders are reserved for diagnostics, and 10 extra cylinders
+ are reserved to replace bad tracks
+d) 4 extra cylinders are reserved for storage system use (including 2 for
+ diagnostics), and 10 extra cylinders are reserved to replace bad tracks
+e) 16 extra cylinders are reserved for bad track relocation
+f) there are extra cylinders, and the way logical addresses relates to physical
+ address is so complex I don't even want to talk about it
+g) 2 extra cylinders are reserved for diagnostics, and 10 extra cylinders are
+ reserved to replace bad tracks
+h) 2 extra cylinders are reserved for diagnostics
+
+Note that 2270512-9701 and 946250-9703 describe more disk units (namely CMD 16,
+CMD 80, WD800A-43 and WD800A-100 for the former, and WD500-10 for the later).
+Since there are no other references anywhere and DX-10 does not seem to know
+about them, I assume that these models were uncommon.
+
+FD800 is a 8" floppy disc unit that is not emulated, and it is only cited for
+completeness. (The FD800 controller is connected to the CRU bus instead of the
+TILINE bus, and it is the only disc controller that is supported by non-TILINE
+systems).
+
+FD1000 is a 8" floppy disc unit.
+
+DS31/DS32 was the first hard disk unit for ti990. The only difference between
+DS31 and DS32 is that DS32 does not require a screwdriver to change the disc
+cartridge.
+
+DS10 has one 5-mb fixed platter and one 5mb disk cartridge.
+
+CD1400-32 and CD1400-96 have a one-platter 16-mb removable unit, and a fixed
+unit (16 mb for CD1400-32 and 80 mb for CD1400-96).
+
+WDxxx units are Winchester drives that connect to a proprietary PBUS bus
+interface. This bus is a built-in interface in BS300 and BS300A systems, and
+the TPBI card enables any TILINE 990 system to support it. WD800s are 8"
+drives with integrated tape backup, WD500s are 5"1/4 drives with integrated
+FD1000 backup, and WD900s are 9" drives. The WD900 controller can optionally
+partition the disc into two partitions: the set-up with no partitioning is
+listed as WD900-138 and WD900-425, whereas the set-up with partitioning is
+listed as WD900-138/2 and WD900-425/2.
+
+MSU II and MSU IIa are SCSI units to be connected to the 990/SCSI controller
+board.
+
+
+Macintosh floppy disk images (mac)
+----------------------------------
+
+This module supports MFS (Macintosh File System) and HFS (Hierarchical File
+System) floppy disk images, either in diskcopy 4.2 or raw image format (the raw
+image format is partially compatible with diskcopy 6 format).
+
+This module can catalog images, and get files in MacBinary format. You can put
+files on MFS-formatted images, too, but not on HFS-formatted images.
+
+The module does not support folders in MFS format, because MFS folders are not
+documented by Apple.
+
+Extracted files are in MacBinary III format (which is fully compatible with
+MacBinary I and II). The MacBinary III format joins both macintosh file forks,
+the comment field, and most file info in one single file: it is supported by
+several Macintosh utilities.
+
+
+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.
+