xdftool

xdftool – the universal Amiga disk image file tool

last update: 12.02.2012

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 and copy your own files to it, master own images or repack existing images. It also allows you to work on partitions of a RDISK/RDB hdf image.

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 <image.adf|image.hdf> <command> [option]

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

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

3.1 Inspect Image

‘list’ – Display the list of files

SYNTAX:

list [<ami_path>] [all] [info] [detail]

DESCRIPTION:

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 <ami_path> is given then the full contents of the volume contained in the image will be listed. This implies the “all” and “info” options.

‘info’ – Disk Image Information

SYNTAX:

info

DESCRIPTION:

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.

‘read’ – Read file data or directory tree from an Image

SYNTAX:

read <ami_path> [sys_path]

DESCRIPTION:

If <ami_path> is a file then the file contents will be read and copied to your hosts file system. If no <sys_path> is given then the Amiga file will be written to the host’s current directory with the base name of the <ami_path>. If the <sys_path> is given and is a directory then the file will be written there. Otherwise the <syspath> is the file name for the host file.

If the <ami_path> is a directory then the full directory structure including files and sub directories will be transferred to the host’s file system. If no <sys_path> is given then the directory tree will be created in host’s current directory. If <sys_path> is available then the directory will be created in this path. Otherwise the directory will be named as <sys_path>.

‘open’ – Open existing image for processing

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 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” “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.

3.2 Edit Image

‘create’ – Create a new image file

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 fix 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.

‘format’ – Format an existing or create a new disk image

SYNTAX:

format <volume_name> [ffs] [intl] [dircache] [<create_options>]

DESCRIPTION:

A new and blank OFS/FFS file system will be created on the given image file. All data previously stored there will be lost!!! The <volume_name> gives the name of the new file system. The options “ffs”, “intl”, and or “dircache” allow to select the type of file system you want to create.

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 in order to create a resized image.

‘boot’ – Alter the boot block

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.

‘makedir’ – Create a new directory

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

EXAMPLE:

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

‘write’ – Write a host file or a host directory tree to the image

SYNTAX:

write <sys_path> [ami_path]

DESCRIPTION:

If the given <sys_path> 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 <ami_path> is specified then the file will be stored there. If <ami_path> is a directory then the file is placed there. Otherwise the file will be renamed to the given name.

If the given <sys_path> is a directory then this directory including all contained files will be transferred to the image. If <ami_path> is given and a directory then the host directory will be created there. Otherise the host directory will be renamed to the given name.

‘delete’ – Delete a file or directory

SYNTAX:

delete <ami_path> [all] [wipe]

DESCRIPTION:

Delete the file or directory given with <ami_path>. 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.

‘protect’ – Change the protect flags of a file or directory

SYNTAX:

protect <ami_path> [+/-]<flags>

DESCRIPTION:

This command alters the protect flags associated with the given <ami_path>. 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.

‘time’ – Change the modification time of a file or directory

SYNTAX:

time <ami_path> <time_string>

DESCRIPTION:

This command changes the modification time associated with the given <ami_path> 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 t45" or
"06.07.1986 14:38:56"

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

‘root’ – Change parameters of the root block

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).

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.

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 <volume>.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 <volume>.bootcode is created. This holds the boot code that is required to make the disk bootable again.

Finally, for HDF images a file called <volume>.blkdev is created that holds the disk geometry of the original HDF file. The file only contains the values
<cylinder>,<heads>,<sectors>.

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.

‘unpack’ – Extract a disk image to the host’s file system

SYNTAX:

unpack <sys_dir>

DESCRIPTION:

The disk image volume’s directory tree will be completely extracted to the host file system at <sys_dir>. First a directory with the volume’s name is created and inside all files and directories of the image.

Furthermore, a MetaDB file called <volume_name>.xdfmeta is created right next to the volume’s directory. This file stores all meta infos from the volume and the contained files.

A <volume_name>.bootcode file is created if the disk image is bootable. A <volume_name>.blkdev file is created to store the disk geometry of disk image’s block device.

‘pack’ – Create a disk image from host files

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 <volume_dir>.xdfmeta exists then the files in the images will be created with correct protection flags, modification time and comment.

If a boot code file called <volume_dir>.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 <volume_dir>.blkdev must be available with cylinder, heads, sectors settings.

‘bitmap’ – Inspect the block allaction bitmap of the file system

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 and <ami_path> 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:

‘block’ – Show blocks of the file system

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 <ami_path> 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