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 ... is the name of the subcommand is the format of the 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= 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= 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 " 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.