amitools Release 0.6.0

Jul 09, 2021

Contents

1 xdftool 1 1.1 Introduction...... 1 1.2 Usage...... 1 1.3 Commands...... 2

2 xdfscan 13 2.1 Introduction...... 13 2.2 Usage...... 13 2.3 Scanner Output...... 14

3 rdbtool 15 3.1 Introduction...... 15 3.2 Usage...... 15 3.3 Commands...... 16

4 romtool 25 4.1 Features...... 25 4.2 General Commands...... 25 4.3 Inspect a ROM...... 26 4.4 Split a ROM into modules...... 28 4.5 Build a new ROM...... 30

5 Tools 33

6 Project Links 35

i ii CHAPTER 1

xdftool

the universal Amiga disk image file tool

1.1 Introduction

The xdftool is a tool from the amitools tool set that allows to read disk images intended for Amiga emulators like ADF or HDF files and display or extract their contents. Furthermore, you can • create new ADF or HDF images • copy files from the image • copy your own files to it • master own images • repack existing images • work on partitions inside RDISK/RDB hdf images or on real disks

1.2 Usage xdftool is a command line utility that is always called with an image file path name as the first argument and with one or more commands working on this image:

> xdftool [option]

You can issue multiple commands on a single image by concatenating them with a plus character:

> xdftool [options1] + [options2] ...

For Example::

1 amitools, Release 0.6.0

> xdftool test.adf format ``My Image`` + makedir c + write myfile c

1.3 Commands

This section describes the commands available for xdftool. You can always issue a help command to see all commands:

> xdftool test.adf help

1.3.1 Inspect Image list - Display the list of files list [] [all] [info] [detail]

This command lists the given directory in the image. The info option appends some statistics information at the end of the list including used blocks, bytes and file bytes. Each file or directory is display with name, size, protection flags, modification date and comment (if available). The detail options replaces the comment with details on the file‘‘s storage including number of data blocks and file system blocks. The all option shows a directory recursively, i.e. also its contained directories. If no is given then the full contents of the volume contained in the image will be listed. This implies the all and info options. Example::

> xdftool test.adf list ; show whole image > xdftool test.adf list / ; same command > xdftool test.adf list c all ; show 'C' directory on image type - Display the contents of a file type

The contents of the specified Amiga file will be written to the standard output. This is useful to quickly see the contents of a file in an image. Example:

> xdftool wb310.adf type s/startup-sequence > xdftool pics.adf type mycool.ilbm | ilbmtoppm > img.ppm info - Disk Image Information info

2 Chapter 1. xdftool amitools, Release 0.6.0

Display information on the disk image. This will display the number of blocks totally available in the disk image, the number of used and free blocks. Additionally, the corresponding byte values are printed. Example:

> xdftool wb310.adf info Blocks: total: 1760 used: 1698 free: 62 Bytes: total: 901120 used: 869376 free: 31744

read - Read file data or directory tree from an Image

read [sys_path]

If is a file then the file contents will be read and copied to your hosts file system. If no is given then the Amiga file will be written to the host’s current directory with the base name of the . If the is given and is a directory then the file will be written there. Otherwise the is the file name for the host file. If the is a directory then the full directory structure including files and sub directories will be transferred to the host’s file system. If no is given then the directory tree will be created in host’s current directory. If is available then the directory will be created in this path. Otherwise the directory will be named as . Example:

> xdftool wb310.adf read c/dir ; copy file 'dir' to host's current dir > xdftool wb310.adf read c/dir . ; same command > xdftool wb310.adf read c/dir a ; copy file 'dir' to host file 'a' > xdftool wb310.adf read devs ; copy 'devs' dir tree to current dir > xdftool wb310.adf read devs . ; same command > xdftool wb310.adf read devs b ; copy dir tree 'devs' to host dir 'b'

blkdev - Show information on the underlying block device

blkdev

Displays the number of cylinders, heads, and sectors available in the image‘‘s block device

open - Open existing image for processing

open [part=] [chs=,,] [h=] [s=]

This command opens an existing image for further processing. This is typically the first command in a command list as it allows all other commands to work on the selected file system. Most often you do not need to specify this command as it will be automatically prepended if its missing. In this case all parameters for opening the input disk image are determined automatically. If the parameters can’t be detected or you don’t want to use the detected values then you specify the open command explicetly. The part option is useful if you access a RDISK or RDB hdf image. In this case the image holds a full disk with multiple partitions. xdftool can only work on a single partition or file system and thus you must select which

1.3. Commands 3 amitools, Release 0.6.0

partition to work on. You can either give a number selecting the n-th partition (startin with 0, of course!) or give the device name associated with this partition (e.g. dh0) without the colon. The chs or h and s options are useful for HDF images without RDB to describe the disk geometry. xdftool has an algorithm to determine the disk geometry automatically from the byte size, but this approach might fail for some setups. In this case you can either fully specify the disk geometry with the chs option or guide the detection algorithm by giving a sector s and/or heads h value. Example:

> xdftool mydisk.rdisk open part=dh1 + list ; open partition 'dh1:' in image > xdftool disk.hdf open chs=10,1,32 + list ; open image with given geometry > xdftool disk.hdf open h=5 s=16 + list ; guide auto detection

1.3.2 Edit Image

create - Create a new image file

create [ size= [h=] [s=] | chs=,, ]

With this command you can create a new disk image file. If the disk image format has a fixed size (e.g. ADF) then you do not need to specify extra paramters to this command. For a hard disk image (HDF) file you must either give the total size in bytes or the disk geometry in cylinders, heads, and sectors. If you specify only the size then the disk geometry will be automatically derived. You can use the optional paramters h and/or s to fixate parts of the disk geometry and guide the detection of the disk layout. Please note that the create command only creates an empty disk image that is not formatted yet. You will need the format command to create a valid empty file system on it. You can’t create a RDB/RDISK image with this command. Use the rdbtool for this task. Example:

> xdftool new.hdf create size=10Mi ; create an empty HDF image with 10Mi > xdftool new.adf create ; create an empty floppy disk image > xdftool new.hdf create chs=10,1,32 ; create disk with given geometry > xdftool new.hdf create size=10Mi h=2 ; force 2 heads

format - Format an existing or create a new disk image

format [dostype] []

A new and blank OFS/FFS file system will be created on the given image file.

Warning: All data previously stored there will be lost!!!

The gives the name of the new file system. The optional dos_type gives the file system variant. Its the base type ofs or ffs combined with variant flags added with a plus + (and no spaces). Or you give a DOSx type of the file system in the range of DOS0 and DOS7. The following variant flags are recognized: • intl for international mode.

4 Chapter 1. xdftool amitools, Release 0.6.0

• dc or dircache for directory caching • ln or longname for long file name support If the disk image file you specify does not exist on disk yet then an implicit create command will be executed first. If the file already exists you must use the create command if you want to create a resized image. Example:

> xdftool empty.adf format 'My Empty Disk' ; create a blank OFS disk image > xdftool empty.hdf format Work size=10M ; create a 10M hdf image > xdftool empty.hdf format Work chs=640,1,32 ; create with given geometry > xdftool empty.hdf format Work size=10M ffs ; create an FFS hdf image > xdftool empty.hdf create size=10M + format Work ffs ; same result > xdftool empty.hdf format Work size=10M ffs+ln ; create with long name support

boot - Alter the boot block

boot show [hex] [asm] boot read boot write boot install [boot1x] boot clear

This command allows to inspect and modify the boot block of a disk. The show command displays the contents of the boot block. The hex and asm alloy you to add a hex dump display of the boot block and even a disassembly. (This requires the vda68k disassembler in the current path) The read command reads the boot code (if available) from the disk image and stores it in the given host file. The write command allows you write back boot code stored in a file to the disk image. The checksum of the block will be adjusted automatically. The install command allows to write a typical WB 2.x/3.x boot code to the disk to make it bootable. If you specify the boot1x option then a WB 1.x boot code will be written instead. The clear command will remove the boot code from the boot block and invalidates the checksum so that the disk is not bootable anymore. Example:

> xdftool my.adf boot show ; show the boot block > xdftool my.adf boot read boot.code ; read boot code from disk > xdftool my.adf boot write boot.code ; write boot code back to disk > xdftool my.adf boot install ; make disk bootable > xdftool my.adf boot clear ; make disk not bootable anymore

makedir - Create a new directory

makedir

This will create a new directory a the given . Note that all preceeding directories need to exist already otherwise an error will be issued. Example:

1.3. Commands 5 amitools, Release 0.6.0

> xdftool empty.adf makedir c ; create a new directory called 'c'

write - Write a host file or a host directory tree to the image

write [ami_path]

If the given is a file then the contents of the file will be read and stored with the same name in the top- level directory of the image’s volume. If is specified then the file will be stored there. If is a directory then the file is placed there. Otherwise the file will be renamed to the given name. If the given is a directory then this directory including all contained files will be transferred to the image. If is given and a directory then the host directory will be created there. Otherise the host directory will be renamed to the given name. Example:

> xdftool empty.adf write README ; the host file 'README' is written to ; the volume's root directory > xdftool empty.adf write README / ; same command > xdftool empty.adf write README c ; write to 'c' directory (if exists) ; or rename to file 'c' > xdftool empty.adf write mydir ; the host directory 'mydir' is written

delete - Delete a file or directory

delete [all] [wipe]

Delete the file or directory given with . If a directory is specified then it must be empty otherwise delete will fail. If you specify all then the contents of a directory is deleted first and it allows you to delete non-empty directory trees. The wipe option ensures that all freed blocks in the delete operation are erased with zero bytes. Example:

> xdftool mydisk.adf delete README ; delete the 'README' file > xdftool mydisk.adf delete c/dir ; delete file 'dir' in dir 'c' > xdftool mydisk.adf delete c ; delete 'c' dir if its empty > xdftool mydisk.adf delete c all ; delete 'c' including all contents

protect - Change the protect flags of a file or directory

protect [+/-]

This command alters the protect flags associated with the given . The flags to be set are given with any combination of the characters hsparwed. You can prefix the flags with either + or - to add or remove flags from the current flag set. If no prefix is given then the given flags erase the old ones. Example:

> xdftool mydisk.adf protect test rwe ; set the flags 'rwe' to file 'test' > xdftool mydisk.adf protect test -w ; remove the 'f' flag > xdftool mydisk.adf protect test +d ; add the 'd' flag

6 Chapter 1. xdftool amitools, Release 0.6.0

comment - Change the comment of a file or directory

comment

The given string will be written as a comment to the given file or directory. If you want to clear the comment then simply set an empty string. Example:

> xdftool mydisk.adf comment test 'what a nice comment' ; set a comment > xdftool mydisk.adf comment test '' ; remove comment/set empty one

time - Change the modification time of a file or directory

time

This command changes the modification time associated with the given file or directory. The time string must have the following notation (and needs to be quoted because of the contained spaces):

'06.07.1986 14:38:56.45' '06.07.1986 14:38:56'

The first notation allows to specify the number of ticks (1/50th s) in a time stamp. Example:

> xdftool mydisk.adf time test '06.07.1986 14:38:56.45' > xdftool mydisk.adf time mydir '06.07.1986 14:38:56'

relabel - Change the name of the volume

relabel

Set a new name for the volume. Example:

> xdftool my.adf relabel 'A New Name'

root - Change parameters of the root block

root show root create_time root disk_time root time

This command set allows to show and alter the information stored in the root block of the file system. The show command displays the contents of the root block. The create_time, disk_time, time sub commands allow you change the volume‘‘s creation, total disk and modification time respectively. All commands require a valid time string (see time command above for details). Example:

1.3. Commands 7 amitools, Release 0.6.0

> xdftool my.adf root show > xdftool my.adf root create_time '06.07.1986 14:38:56.45' > xdftool my.adf root disk_time '06.07.1986 14:38:56' > xdftool my.adf root time '06.07.1986 14:38:56.45'

1.3.3 Pack/Repack/Unpack Images

The xdftool provides advanced commands to convert the whole contents of a disk image to a host file system and allows to later on reconstruct the image from the files only.

Un/packing Explained

Unpacking a disk image means that starting from the volume’s root all directories and files contained in the image will be extracted to the host file system and the same directory tree will be recreated. The host file system structure starts with a directory named after the volume. The host file system now contains the directory tree with all files and directories. The contents of the files is also readily available. What’s still missing are the meta infos available in the Amiga disk image but not found in the host file system: protection flags, comments and modification time in tick resolution. These missing meta infos are stored in a MetaDB file called .xdfmeta. In the header line meta infos of the volume are stored including volume name, dos_type, and the root time stamps. Then for each file of the image an entry line is created that states the file or directory name followed by a colon and the meta infos: protection flags, modification time stamp and comment. If the disk image is bootable then a file called .bootcode is created. This holds the boot code that is required to make the disk bootable again. Finally, for HDF images a file called .blkdev is created that holds the disk geometry of the original HDF file. The file only contains the values ,,. With the volume’s directory tree, the meta info DB and optional bootcode and blkdev files in place you have everything on your host file system to allow the exact recreation of an disk image later on. This recreation is called packing in xdftool. You can also use packing to master Amiga disk images: Simply create a volume directory tree on your host file system and call xdftool’s pack command to create an image file from it. If you want to adjust the meta infos then add a .xdfmeta MetaDB file and everything will be set as needed on packing. Repacking allows you to combine the unpacking and repacking operations in one step. The command is useful to defragment and rebuild the whole file system in a new image with the exact same contents. It is also possible to create a new image with different size in the pack step. This allows you to expand or shrink the image. unpack - Extract a disk image to the host‘‘s file system

unpack [fsuae]

The disk image volume’s directory tree will be completely extracted to the host file system at . First a directory with the volume’s name is created and inside all files and directories of the image. Furthermore, a MetaDB file called .xdfmeta is created right next to the volume’s directory. This file stores all meta infos from the volume and the contained files. A .bootcode file is created if the disk image is bootable. A .blkdev file is created to store the disk geometry of disk image’s block device.

8 Chapter 1. xdftool amitools, Release 0.6.0

If fsuae option is given then the meta data of each file is written to a FS-UAE compatible .uaem file right next to the original file. Use this option if you want to use the unpacked directory as a volume inside FS-UAE. Example:

> xdftool mydisk.adf unpack . ; unpack full image to current directory > xdftool mydisk.hdf unpack . ; same for hard disk images > xdftool mydisk.hdf unpack . fsuae ; store meta info in .uaem files

pack - Create a disk image from host files

pack [blkdev_size]

If you have unpacked a disk image then you can pack it again with this command. Simply specify the volume’s directory. Note: All data available in the disk image will be lost and overwritten!!! If a MetaDB called .xdfmeta exists then the files in the images will be created with correct protection flags, modification time and comment. Pack automatically detects if a FS-UAE meta file with .uaem extension is available and then extracts the file’s meta info there. If a boot code file called .bootcode is available then this code is written to the image‘‘s boot block and made bootable. If a HDF image will be packed then the block device must be specified either by specifying blkdev_size (e.g. 10M or 640,1,32 see format command) or a file called .blkdev must be available with cylinder, heads, sectors settings. Example:

> xdftool newimg.adf pack WB3.1 ; pack a disk image from host dir 'WB3.1' > xdftool newimg.hdf pack Dir 10M ; pack host dir 'Dir' into a 10M HD image

repack - Repack the contents of one image into another one

repack []

This command allows you to rebuild an existing disk image by combining the unpack and pack commands on the fly without creating a host file system representation. This command is very useful to better stuff and de-fragment data on a file system that already performed lots of delete and create operations. You always specify the image from which you want to import. The target image is the image you specify on the xdftool command line. If you are repacking from a HDF image then you can add options like to the open command to specify the disk geometry or the partition in a RDB image. If nothing is specified then the target size is taken from the source size. You can prepend a create command to repack a HDF to another sized HDF. Example:

> xdftool new.adf repack old.adf ; repack 'old.adf' into 'new.adf' > xdftool new.hdf repack old.hdf chs=10,2,32; repack 'old.hdf' with given geo > xdftool new.hdf create size=10M + repack old.hdf ; repack to larger disk > xdftool new.hdf repack old.rdisk part=dh0 ; repack one partition of a disk

1.3. Commands 9 amitools, Release 0.6.0

1.3.4 Low-Level Commands xdftool also provides a set of low-level commands that let you look into details of the file system to better understand its inner workings. These commands are suitable for experts only. bitmap - Inspect the block allocation bitmap of the file system bitmap info bitmap free [brief] bitmap used [brief] bitmap find [n] bitmap all [brief] bitmap maps [brief] bitmap root [brief] bitmap node [all] [entries] [brief]

The info command calculates the free and used blocks. The free and used commands show the unallocated/allocated blocks on the disk. Use the brief option to show only bitmap lines with contents. The find command calls the block allocator and tells you what would be the next free block on the disk. Give a number n to reserve a sequence of blocks. The all command shows all allocations in the bitmap. maps shows the blocks allocated by the bitmap itself. root gives the root block. The node command requires an on the image and shows the blocks allocated for the given file or directory. If a directory is specified and the all option is given then all blocks occupied by files and sub dirs are also shown. If the entries option is given then a directory and its entries are shown. The bitmap output used different characters to code the block meaning: . no information available x reserved blocks F unallocated/free block # allocated/used block V volume dir/root block R root block D directory header block C directory cache block H file header block d file data block E file extension block b bitmap block B bitmap extension block Example:

10 Chapter 1. xdftool amitools, Release 0.6.0

> xdftool test.adf bitmap free brief > xdftool test.adf bitmap used > xdftool test.adf bitmap find 10 > xdftool test.adf bitmap all > xdftool test.adf bitmap node C entries brief block - Show blocks of the file system block boot block root block node [data] block dump

The boot and root sub commands simply show the boot and root block (similar to boot show and root show commands above). The node sub command requires an and shows all blocks associated with this file or directory. If data option is given then also data blocks of a file are included in the display. Otherwise only structure blocks are shown. The dump command requires a block number and simply gives a hex dump of the block‘‘s data Example:

> xdftool test.adf block boot > xdftool test.adf block root > xdftool test.adf block node c > xdftool test.adf block node myfile data > xdftool test.adf block dump 880

1.3. Commands 11 amitools, Release 0.6.0

12 Chapter 1. xdftool CHAPTER 2

xdfscan

scanner to validate AmigaOS file systems in disk or hard disk images

2.1 Introduction

I wrote this tool to inspect the large collection of disk (.adf) and hard disk images I gathered over the years. The scanner either runs directly on files or on a directory. The latter mode of operation then scans the directory tree recursively and checks all disk and hard disk images found there. The scanner does an in-depth check of all structures used in the AmigaOS OFS and FFS file system. If something does not fulfill the file system specification then an error or warning is generated. Warnings are usually tolerated when using this image in an emulator but errors might hint to corrupt files on the disk. Each scanned file results in a single line output that gives you a quick overview of the errors and warnings found in the image (if any). You can also enable the verbose mode. Then all errors and warnings are reported.

2.2 Usage

You can call xdfscan with a file or a directory:

> xdfscan test.adf # scan a single image file > xdfscan test.hdf # scan a single hard disk image

> xdfscan my_disks # scan all adfs and hdfs found in # the directory tree below "my_disks"

In directory scan mode you can limit the scan to either disk images or hard disk images only by using -D (skip disks) or -H (skip hard disks):

> xdfscan-H my_disks # only disk images and no hard disk images > xdfscan-D my_hdfs # only hard disk images and no disk images

13 amitools, Release 0.6.0

Normal output uses single lines and only reports the number of errors and warnings that were found. If you enable verbose mode (-v) then the warnings and errors are printed:

> xdfscan-v my_disks # show warning and error messages

The tool also generates debug and information messages while scanning an image. You can show these if you set the message level with the -l option:

> xdfscan-v-l0 my_disks # show also debug and info messages > xdfscan-v-l1 my_disks # show info messages (and warn, error)

2.3 Scanner Output

A typically scan run looks like this:

> xdfscan. E069 NOK./bookdisk/amiga_listing_03_89.adf boot ok./bookdisk/devpac.adf ok./bookdisk/gfabasic3.adf nofs./bookdisk/giana.adf boot ok./bookdisk/mut_hwtuning_1_9.adf w001 boot NOK./bookdisk/reflections_animator.adf ok./bookdisk/reflectionsv1_0.adf

On the right you can see the name of the image that was scanned. The next column to the left gives you the total result of the scan operation of the image: • ok: disk image has no errors and warnings • NOK: either errors or warnings were found in disk image • nofs: no OFS or FFS file system was found on the disk image. this is typically the case for custom track loader games. boot block is ok and bootable but no OFS/FFS root block is found. • NDOS: no valid DOS boot block was found The third column either is empty or displays boot. This row indicates if the file system contains a bootable boot block. The first two columns are empty or show the total number of warnings or errors found in the image. If you enable verbose output with -v then you can see warnings and error messages like these:

w001 boot NOK./bookdisk/reflections_animator.adf @000880:WARN :Root bitmap flag not valid (-1) ok./bookdisk/reflectionsv1_0.adf E002 boot NOK./commercial_soft/PCLink/pclink.adf ERROR:Invalid bitmap allocation (@40: #0+40) blks [1282...1313] got=00000000

˓→expect=00008000 ERROR:Invalid bitmap allocation (@45: #0+45) blks [1442...1473] got=00000000

˓→expect=80000000

The first entry in a warning or error message is the block number where the error occurred. If the message does not relate directly to a block number then the first column is omitted.

14 Chapter 2. xdfscan CHAPTER 3

rdbtool

the universal Amiga disk partition tool

3.1 Introduction

The rdbtool is a tool from the amitools tool set that allows to inspect or create hard disk partitions readable by the classic Amiga family of computers. The RDB or Rigid Disk Block is a format to describe the first blocks of a hard disk that store information of partitions and file systems used in the partitions. If you want to work with files stored in the DOS file system of a partition then have a look at the xdftool of amitools.

3.2 Usage

3.2.1 Disk Image Files rdbtool is a command line utility that is always called with an hard disk image file path name as the first argument and with one or more commands working on this image:

> rdbtool [option]

You can issue multiple commands on a single image by concatenating them with a plus character:

> rdbtool [options1]+ [options2]...

For example:

> rdbtool myimg.rdb create size=10Mi+ init+ fill

Most options in rdbtool are given as key=value pairs. Here the option size is given with value 10Mi for a 10 MiB sized disk image.

15 amitools, Release 0.6.0

3.2.2 Real Block Device

On Unix/Linux/macOS you can also use a block device of a real hard disk or a CF/SD flash card to directly work on a real device. The file names for the block device differ on the different platforms but typical names are /dev/rdisk1 or /dev/sda. Always make sure to select the block device of the whole drive (e.g. /dev/hdc) and not the device of some already existing paritioning (e.g. /dev/hdc1).

Warning: Also make sure (really, really sure!) to select the correct block device of the hard disk you want to alter with rdbtool. Otherwise you might destroy your actual system disk!!! Most OSes need a priviliged user to perform these operations so you need to run rdbtool as root or with sudo in this case.

3.3 Commands

This section describes the commands available for rdbtool. You can always issue a help command to see all com- mands:

> rdbtool test.img help

3.3.1 Open/Create an Image

In rdbtool there are two ways to access an image: open or create it. The open operation assumes that the disk image file already exists or is used for existing devices available through block device names. create - Create a new disk image create [ size=| chs=,,| from= ] [ bs=]

The create operation is used to create a new image file. The create command needs a size parameter:

> rdbtool test.img create size=10Mi

You can either specify the total size in bytes (or here with unis M=mega Mi=Ki-Units) and let rdbtool choose a suitable disk geometry automatically or you can give the geometry with:

> rdbtool test.img create chs=10,1,32

Here 10 cylinders, 1 head and 32 sectors are defined. Another way to specify the size of the new image is to give the file name of an existing image or real device. This is useful to create a new image of compatible size:

> rbdtool test.img create from=other.img

You can only use the create command if the given image file does not exist yet. If it already exists then an error message is generated. However, you can force the creation of the image file by giving the -f switch for force:

> rdbtool-f test.img create chs=10,1,32

16 Chapter 3. rdbtool amitools, Release 0.6.0

By default a disk layout with a block size of 512 bytes is created. For larger disks you may want to increase the block size to 1024, 2048, or 4096. Use the bs` option to select the block size:

> rdbtool create size=32Gi bs=4096

Note: Amigas only support RDBs with a 512 byte block size!

open - Open existing image for processing open [ chs=,,|c=h=s= ] [ bs=]

The open operation usually does not need any paramters:

> rdbtool test.img open+ info

You can even omit the open command before other commands in this case:

> rdbtool test.img info

This will implicitly open the image first. If no option is given then the disk geometry is automatically determined from the image size. If this does not work for an image you can also specify the geometry of the image in the open command:

> rdbtool test.img open chs=10,1,32

You can also only hint the geometry by giving some geometry paramters and let rdbtool guess the others:

> rdbtool test.img openc=10h=2s=32

By default the block size of the disk is assumed to be 512. If an RDB is already stored on the disk then rdbtool automatically retrieves the block size from there. You can force a block size by giving the bs option with the open command. This is useful if you want to overwrite an existing RDB with a different block size on a disk:

> rdbtool/dev/disk1 open bs=4096+ init

Note: Amigas only support RDBs with a 512 byte block size!

resize - Change size of existing image resize [ chs=,,|c=h=s=| from= ] [ bs=

˓→ ]

Similar to the create command you can specify the new size of an image. It will be either shrunk or grown.

Note: The RDB that may be already on the disk is not touched or adjusted! Use the adjust command to adjust the RDB as well.

3.3. Commands 17 amitools, Release 0.6.0

3.3.2 Inspect the Partition Layout info - Show information of the RDB data structures info [partition]

This command gives an overview of the partitions and file systems stored in the RDB blocks. It will return something like:

PhysicalDisk:0 7817 7880544 3.8Gi heads=16 sectors=63 LogicalDisk:2 7817 7878528 3.8Gi rdb_blks=[0:2015,60(60)]

˓→cyl_blks=1008 Partition: #0 'CDH0' 2 103 102816 50Mi 1.31% DOS3 bootable

˓→pri=0 Partition: #1 'DH0' 104 205 102816 50Mi 1.31% DOS3 Partition: #2 'DH1' 206 2035 1844640 900Mi 23.41% DOS3 Partition: #3 'DH2' 2036 3763 1741824 850Mi 22.11% DOS3 Partition: #4 'DH3' 3764 3909 147168 71Mi 1.87% DOS3 Partition: #5 'CDH1' 3910 3971 62496 30Mi 0.79% DOS3 Partition: #6 'DH4' 3972 4124 154224 75Mi 1.96% DOS3 Partition: #7 'DH5' 4125 5953 1843632 900Mi 23.40% DOS3 Partition: #8 'DH6' 5954 7817 1878912 917Mi 23.85% DOS3 FileSystem #0 DOS1 version=40.1

˓→size=24588

If a partition name (.e.g DH0) or index (e.g. 3) is given then only the information for a single partition is displayed:

> rdbtool test.hdf info DH0 Partition: #1 'DH0' 104 205 102816 50Mi 1.31% DOS3 show - Show internal block representation of the RDB data structures show

This command is a low-level tool that shows the blocks available in the RDB data structure with their corresponding values. Use this to debug or analyze issues with complex RDBs.

3.3.3 Create a new RDB init - Create a new and empty RDB structure init [ rdb_cyls=]

This command creates a new and initially empty RDB structure. Call this command first to start building a new RDB structure on a disk or disk image:

> rdbtool test.img create size=10Mi+ init

The default RDB occupies all the sectors of the first cylinder. If you have chosen a geometry with small cylinders then a single cylinder might not be sufficient to hold the RDB data structures. In this case use the rdb_cyls option to set the number of cylinders to reserve for RDB:

18 Chapter 3. rdbtool amitools, Release 0.6.0

> rdbtool test.img create size=10Mi+ init rdb_cyls=2

adjust - Adjust range of existing RDB structure

adjust ( auto [ force ]| [ lo= ] [ hi= ] [ phys ] )

This command changes the range on the disk that the current RDB covers. It is very handy if you copy a pre-existing image file to a real medium (e.g. compact flash card) with a larger size. You can either use the auto mode that automatically increases the RDB range to cover the full image or medium. If the cylinder number gets too large then you need to add the force option to allow the change. > rdbtool /dev/disk4 adjust auto In manual mode you have to specify the new range of the RDB by giving either the lo and/or hi cylinder. If you add the phys option then not only the logical range of the RDB will be changed but also its physical extend. > rdbtool test.img adjust hi=1000 phys The adjust command will abort with an error if the existing partitions do not fit into the new range. remap - Change geometry of existing RDB structure

remap [ s=][h=]

This command allows to change the interal geometry of the disk image. The geometry consists of cylinders, heads, and sectors. Typically, the number of heads and sectors is chosen in such a way that the number of cylinders spanning the image does not grow too large. If you want to adjust an RDB to a larger device size then the cylinder ranges might get too large. In this case use the remap command first to increase the sectors and/or heads to keep the cylinders in a reasonable range. > rdbtool image.rdb remap s=32 h=8 Note that the remap operation is only allowed if the physical and logical disk layout can be converted to the new values without any resizing. Additionally, all partition ranges must be mappable as well.

add - Add a new partition

add [ name= ] [ dostype|fs=] [ bootable[=true|false] ] [ pri=] [ automount=true|false ] [ bs=]

This command creates a new partition. You have to give the size of the partition in one of the following ways: 1. Give start and end cylinder:

start= end=

2. Give start cylinder and size:

start= size=

3. Only give size:

3.3. Commands 19 amitools, Release 0.6.0

size=

For the size you can specify a number of cylinders, a percent value, or a byte size (The percent value gives the ratio of the total logical disk size):

> rdbtool test.img add start=2 end=5 ; give start and end cylinder > rdbtool test.img add start=4 size=10 ; give start and number of cylinders > rdbtool test.img add size=10MiB ; give size in bytes > rdbtool test.img add size=50% ; use half the disk size

If no name option is given then the defaul name DH is used appended with the current partition number starting with 0: DH0, DH1. You can alter the base name by giving the -p switch (for drive prefix):

> rdbtool-p CH test.img init+ add size=10% ; create partition CH0

The dostype or fs switch can be used to select the file system you will use to format the partition. The default is DOS3, i.e. Fast Filing System with International Support. You can give the dostype with DOS or as a hex number 0x44556677 or for standard DOS file systems with ofs, ffs and append dc or dircache or intl flags:

dostype=DOS0 ; OFS dostype=ofs+dc ; OFS+ dircache dostype=ffs+intl ; FFS+ international mode dostype=0x44556677 ; give hex of dostype

You can make a partition bootable by setting the bootable flag. Additionally you can select the boot priority with pri=:

> rdbtool test.img add size=10% bootable pri=10

The bs option allows you to specify the block size of the file system. By default rdbtool uses the block size of the RDB parition itself, e.g. 512. The file system block size must be a multiple of the parition block size, e.g. 1024, 2048, 4096, or 8192. addimg - Add a new partition from an image file

addimg [ start=] [ name= ] [ dostype|fs=] [ bootable[=true|false] ] [ pri=] [ automount=true|false ] [ bs=]

This command creates a new partition from the contents of a given partition image file. The size of the partition is automatically derived from the file size. The start of the partition is either given with the start option or selected automatically from the next free range in the partition table. Note that the image size must be a multiple of the cylinder size. Otherwise the partition can’t be added. The dostype is automatically derived from the first four bytes of the image file. The file system block size can’t be detected automatically and must be given with the bs option if a non-standard (512 bytes) size is used. See the add command for an explanation of the other options.

change - Modify parameters of an existing partition

20 Chapter 3. rdbtool amitools, Release 0.6.0

change [ name= ] [ dostype|fs=] [ bootable[=true|false] ] [ pri=] [ automount=true|false ] [ bs=]

The is the number of the paritition as given in the info command. You can also use the device name to select a partition:

> rdbtool test.img change0 name=CH0 bootable=true

For options see the add command.

free - Show free cylinder range in partition layout

free

This command returns one or more cylinder ranges that are currently not occupied by partitions. You can use this command to find out the range for a new partition. If the current partition layout aready occupies the whole disk then this command will return nothing.

fill - Fill the remaining space in the partition layout

fill [ name= ] [ dostype|fs=] [ bootable[=true|false] ] [ pri=] [ automount=true|false ] [ bs=]

This command takes the free space in a partition layout and creates a new partition that fills this space. This command supports the same options as used in the add command above. If multiple holes are in the current partition layout then this command creates a new partition for each existing hole. With this command you can easily finish paritioning without the need of calculating the size of the final partition:

# create 2 partitions with 50% size each > rdbtool test.img init+ add size=50%+ fill > rdbtool test.img init+ add size=10%+ add size=20%+ fill

For options see the add command.

delete - Delete an existing partition

delete

This command removes an existing partition and frees all associated resources. The is the number of the paritition as given in the info command. You can also use the device name to select a parition:

> rdbtool mydisk.rdb delete0 > rdbtool mydisk.rdb delete dh1

3.3. Commands 21 amitools, Release 0.6.0

map - Show the allocation map of the RDB blocks

map

This command lets you look under the hood of the RDB. It will print all blocks associated with the RDB and shows their current contents. A two char code is used for each block:

-- block is empty and not used for RDB RD the main rigid disk block P? partition F? file system

Example:

> rdbtool mydisk.rdb map

3.3.4 Import/Export Partitions

export - Export Data of a Partition into a File

export

Store the raw byte contents of a partition into the given file. As a result a file system image will be written. You can use the result as a RDB-less image in xdftool. import - Import Data from a File into a Partition

import

Read the raw partition data from a given file into an existing partition. You typically use a RDB-less file system image as input.

3.3.5 Working with File System Drivers

The RDB data structure allows to store file system drivers for classic AmigaOS, so the Kickstart can load the driver before mounting a parition in the RDB. File systems are LoadSeg()able Amiga Hunk binaries directly embedded in the RDB blocks. Use the info command to see if any file systems are already stored in the RDB. In the output you can see that the file systems are numbered in rdbtool starting with 0.

fsget - Retrieve the file system driver from a RDB structure

fsget

This command extracts the file system numbered and stores the LoadSeg()able Amiga binary on your local system into a new file with the given :

# create a new file "ffs" with the first driver > rdbtool mydisk.rdb fsget0 ffs

22 Chapter 3. rdbtool amitools, Release 0.6.0 fsadd - Add a new file system driver fsadd [version=]

Add the LoadSeg()able file system driver stored in file to the current RDB. Every file system driver needs a version information given as ., e.g. 40.63. When a file is loaded the version is automatically extracted from a VER: tag inside the binary. If this tag cannot be found you can specify the version with the version option:

> rdbtool mydisk.rdb fsadd ffs version=60.32 fsflags - Change flags of file system fsflags [ clear| key=value...]

With this command you can alter the device node flags of a file system. The file system is the number of the file system as listed with the info command. The following keys are supported: type task lock handler stack_size priority startup seg_list_blk global_vec

The clear option will remove all flags first. All other commands add the corresponding flag:

> rdbtool mydisk.rdb fsflags0 clear stack_size=8192

Have a look at the output of the info command to see the flags set for a file system. fsdelete - Remove a file system fsdelete

The file system with the given number is removed. All associated blocks of the file system are free’d in the RDB structure.

3.3. Commands 23 amitools, Release 0.6.0

24 Chapter 3. rdbtool CHAPTER 4

romtool

A tool to inspect, dissect, and build Amiga Kickstart ROM images to be used with emulators, run with soft kickers or burned into flash ROMs

4.1 Features

• show detailed infos on a Kickstart ROM • dump ROM as hex • diff to ROM images • split a ROM into modules with split data from Remus/Romsplit • build a new ROM from modules • concatenate a Kickstart and Ext ROM to a 1 Meg ROM • patch a ROM • scan a ROM for residents • copy a ROM

4.2 General Commands romtool is run from the command line typically as follows: romtool [-v] [-q] [-k rom.key]... romtool always requires a sub command with arbitrary options. Use romtool -h to see a list of available commands. Use romtool -h to see help on the given command.

25 amitools, Release 0.6.0

The following options are available for all sub commands and must precede the sub command switch: • -v be verbose and show processing steps of the tool • -q be really quiet and do not print error messages • -k rom.key if you want to decrypt encrypted ROMs you have to specify the rom.key file.

4.3 Inspect a ROM

4.3.1 info command

Show detailed information of a Kickstart ROM:

$ romtool info amiga-os-310-a500.rom size ok header ok footer ok size_field ok chk_sum ok kickety_split ok magic_reset ok is_kick ok check_sum 9fdeeef6 base_addr 00f80000 boot_pc 00f800d2 rom_rev 40.63 exec_rev 40.10

The command checks various fields of a Kickstart ROM: • size checks if the ROM size is correct: 256 or 512 KiB • header checks if the ROM header was found • footer checks if a ROM footer was found • size_field checks if the size field in the footer was found • chk_sum checks if the KickSum is correct • kickety_split checks if an extra 256 KiB signature was found • magic_reset checks if magic reset opcode was found • is_kick checks if all kickstart tests were passed • check_sum shows KickSum • base_addr start address of ROM • boot_pc program counter to start ROM • rom_rev ROM revision • exec_rev Exec revision

4.3.2 dump command

Print the ROM contents as a hex dump:

26 Chapter 4. romtool amitools, Release 0.6.0

$ romtool dump amiga-os-310-a500.rom 00000000: 11 14 4e f9 00 f8 00 d2 00 00 ff ff 00 28 00 3f ..N...... (.? 00000010: 00 28 00 0a ff ff ff ff 00 41 4d 49 47 41 20 52 .(...... AMIGA R 00000020: 4f 4d 20 4f 70 65 72 61 74 69 6e 67 20 53 79 73 OM Operating Sys ...

Options: • -a show address of ROM (otherwise image file offset is shown) • -b set ROM address to be shown • -c how many bytes are shown per line

4.3.3 diff command

Compare two ROM images and show the differences as a hex dump:

$ romtool diff a.rom b.rom 00000368: ------f8 . | ------f0 . 00000370: ------f0 . | ------e0 . 00000378: ------f8 ------. | ------e8 ------. ...

Options: • -a show address of ROM (otherwise image file offset is shown) • -b set ROM address to be shown • -c how many bytes are shown per line • -f show diff even if ROM sizes differ • -s also show same bytes of two ROMs (otherwise only differences)

4.3.4 scan command

Scan the ROM for resident entries and show them:

romtool scan rom.img @000000b6+00003706 NT_LIBRARY+105 exec.library exec 40.10(15.7.93) @00003706+000037b8 NT_UNKNOWN-55 alert.hook alert.hook @000037b8+00004740 NT_DEVICE-120 audio.device audio 37.10(26.4.91) ...

Details: • @000000b6 offset of resident in ROM • +00003706 skip range given in resident • NT_LIBRARY node type of resident • +105 priority of resident • name name and id_string of resident You can also show more infos with the -i switch:

4.3. Inspect a ROM 27 amitools, Release 0.6.0

romtool scan rom.img-i @000000b6 name: exec.library id_string: exec 40.10(15.7.93) node_type: NT_LIBRARY flags: RTF_SINGLETASK version: 40 priority: 105 init off: 000004d4 skip off: 00003706 ...

4.4 Split a ROM into modules

Splitting a ROM into modules is a pre-processing step that is necessary to build new ROMs: The libraries and devices are extracted as relocatable binaries that can be placed into a new ROM. Splitting a ROM is a difficult process as the borders of the modules are not clearly marked in the ROM and furthermore the code positions that require relocation are not marked at all. Therefore splitting is done with the help of a split data catalog that describes the modules. A catalog is matched with a ROM by its KickSum. romtool currently uses the split data that is shipped with Doobrey’s fantastic Amiga tools Remus/Romsplit.

4.4.1 list command

Show a list of all ROMs that can be split, i.e. split data is available:

$ romtool list @00e00000 +00080000 sum=9ea68bc4 sum_off=0007ffe8 CD32 Extended ROM @00200000 +00040000 sum=34377fe8 sum_off=ffffffff CD32 MPEG ROM 40.30 ...

Details: • @00e00000 base address of ROM • +00080000 size of ROM (here 512 KiB) • sum= KickSum of ROM • sum_off= offset in ROM where KickSum is stored (ffffffff means that no KickSum is stored inside ROM) You can filter the list of ROMs by specifying a query that supports wildcards (* or ?):

$ romtool list -r Kick* @00fc0000 +00040000 sum=15267db3 sum_off=0003ffe8 Kickstart 34.5 (A500/A2000/

˓→A1000) @00f80000 +00080000 sum=54876dab sum_off=0007ffe8 Kickstart 37.175(A3000) ...

A list of the contained module entries is shown with the -m switch:

$ romtool list -r Kick*40.60* -m @00f80000 +00080000 sum=8f4549a5 sum_off=0007ffe8 Kickstart 40.60 (CD32 Main) @000000 +003804 =003804 relocs=# 62 exec_40.9(CD32) @003804 +000ad8 =0042dc relocs=# 12 expansion_40.2(A1200) (continues on next page)

28 Chapter 4. romtool amitools, Release 0.6.0

(continued from previous page) @0042dc +000ea4 =005180 relocs=# 11 mathieeesingbas.lib_40.4(020) ...

Details: • @000000 offset of module in ROM • +003804 size of module • =003804 end address of module in ROM • relocs=# number of relocations found in module

4.4.2 query command

Check if a given ROM image can be split with the available split data:

$ romtool query amiga-os-310-a500.rom @00f80000 +00080000 sum=9fdeeef6 sum_off=0007ffe8 Kickstart 40.63 (A500/A600/

˓→A2000) @000000 +0037b8 =0037b8 relocs=# 61 exec_40.10(A500-A600-A2000) @0037b8 +0010a0 =004858 relocs=# 28 audio.device_37.10 @004858 +001634 =005e8c relocs=# 101 input_40.1 ...

You can filter the modules shown with a wildcard given in -m :

$ romtool query amiga-os-310-a500.rom -m int* @00f80000 +00080000 sum=9fdeeef6 sum_off=0007ffe8 Kickstart 40.63 (A500/A600/

˓→A2000) @04f0c4 +0199a0 =068a64 relocs=# 2405 intuition.library_40.85

4.4.3 split command

Perform the ROM split and extract the modules as LoadSeg()able binary files. A directory named by the ROM is created and next to the modules an index file called index.txt is created that contains an ordered list of the modules taken from the ROM image:

$ romtool split amiga-os-310-a500.rom -o .

This call will create a directory called 40.63(A500-2000) named after the ROM in the current directory and fill it with the ROM’s modules. Additionally, the index.txt file will be created. Options: • -o output directory where the ROM sub directory will be created If omitted no output will be generated! • -m do not export all modules but only those that match the given wildcard • --no-version-dir do not create an extra sub directory with the ROM name • --no-index omit creating the index.txt file

4.4. Split a ROM into modules 29 amitools, Release 0.6.0

4.5 Build a new ROM

4.5.1 build command

Create a new ROM by combining a set of LoadSeg()able binary files. You can either use modules created by the split command or add your own modules. You can either give all modules on the command line or you use and index file. An index file is a simple text file with .txt extension that gives in each line a module path:

$ romtool build -o my.rom -t kick -s 512 index.txt my.library my.device

This command creates a new 512 KiB Kickstart ROM called my.rom with all modules given in index.txt. Options: • -o write generated ROM to given file. Do not forget to specify this switch otherwise no output will be generated! • -t what type of ROM to create: either kick or ext • -s size of ROM in KiB (either 256 or 512) • -a base address of Kick ROM in hex (default f80000) • -e base address of Ext ROM in hex (default e00000) • -f add a footer to Ext ROM • -r set the ROM revision field, e.g. 40.95 • -k add the kickety_split, i.e. in a 512 KiB ROM add an extra ROM header after 256 KiB to be compatible with SW assuming 256 KiB ROM. Found in the Commodore original ROMs. Will create a small hole around the split. • -b give the byte value to fill empty regions of the ROM

4.5.2 patches command

Show a list of available ROM patches in romtool:

$ romtool patches 1mb_rom Patch Kickstart to support ext ROM with 512 KiB

4.5.3 patch command

Apply one or more patches to the given ROM file and write a patched ROM image:

$ romtool patch amiga-os-310-a500.rom 1mb_rom -o out.rom

Apply the 1mb_rom patch to the given rom image and write a new out.rom. Options: • -o write generated ROM to given file. Do not forget to specify this switch otherwise no output will be generated!

30 Chapter 4. romtool amitools, Release 0.6.0

4.5.4 combine command

Concatenate a 512 KiB Kickstart and a 512 KiB Ext ROM image to create a 1 MiB ROM suitable for soft kickers or maprom tools:

$ romtool combine kick.rom ext.rom -o 1mb.rom

Create a 1mb.rom from the Kickstart kick.rom and the Ext ROM ext.rom. Options: • -o write generated ROM to given file. Do not forget to specify this switch otherwise no output will be generated!

4.5.5 copy command

Copy a rom to a new file. In the future, additional transformations may be possible:

$ romtool copy kick.rom duplicate.rom

Copy kick.rom to a new duplicate.rom file. Options: • -c, --fix-checksum after the copy fix the checksum of the written image. For example, if the source rom has been modified with a hex editor or a find/replace operation, then this option can be used to correct the checksum. The amitools are an extensive set of command line tools and Python libraries that support developers when cross- developing for the Amiga computer.

4.5. Build a new ROM 31 amitools, Release 0.6.0

32 Chapter 4. romtool CHAPTER 5

Tools

• xdftool - disk image file tool • xdfscan - scan and validate multiple disk images • rdbtool - disk partition tool • romtool - scan and edit Kickstart ROM files

33 amitools, Release 0.6.0

34 Chapter 5. Tools CHAPTER 6

Project Links

• Source is hosted on GitHub • CI runs on Travis CI • amitools packages are hosted on PyPi • docs are hosted on ReadTheDocs

35