Amiga DiskGen

Amiga DiskGen is a Rust command-line utility that turns a strict TOML specification into a deterministic raw Amiga hard-disk image. It plans geometry and partitions, writes Amiga Rigid Disk Block (RDB) metadata, formats empty native DOS filesystems, and independently verifies the result before publishing it.

Status

The host-side pipeline is implemented on FreeBSD: schema validation, automatic or explicit geometry, partition layout, RDB generation, deterministic empty DOS\0 through DOS\7 formatting, transactional creation, inspection, and verification.

The image generated from examples/basic.toml has also been exercised with Workbench 3.1: a user installed and ran Workbench on it with FS-UAE 3.1.66 on FreeBSD, and the resulting image booted on MiSTer Minimig. This is positive evidence for that particular original-FFS configuration, not a blanket support claim; configuration details and the wider compatibility matrix remain incomplete.

This is not yet a production-ready v1 release. Release-by-release Workbench, emulator, controller, and physical-hardware qualification remains incomplete. In particular, an implemented filesystem format is not a compatibility claim. Do not use development builds as the only copy of valuable data. See the compatibility matrix and roadmap for the exact evidence status.

The intended v1 scope is:

• 68k Amigas running official Workbench 2.00 through 3.2 releases;
• filesystem variants proven to have shipped with an applicable official Workbench release;
• raw image files no larger than 4 GiB (4,294,967,296 bytes), with nearest plausible geometry rounding;
• regular image-file output only—direct raw, block, or character device output is permanently out of scope; and
• FreeBSD as the v1-qualified build and execution host.

Installation

Build from source

Install Rust 1.85 or newer, clone the repository, and build with locked dependencies:

$ cargo build --release --locked

The executable is written to target/release/amiga-diskgen. No prebuilt binaries or package-manager installation channel is currently published. Source builds on hosts other than FreeBSD may work, but are not v1-qualified.

For local development without installing the executable, replace amiga-diskgen in the examples below with cargo run --.

Quick start

The maintained example is examples/basic.toml:

schema_version = 1
target = "3.1"

[image]
size_bytes = 104857600

[[partitions]]
name = "DH0"
size_bytes = 52428800
filesystem = "ffs"
block_size = 512
volume_label = "Workbench"
bootable = true

Validate it, preview the complete layout, create an image, inspect it, and run the verifier:

$ amiga-diskgen validate examples/basic.toml
specification is valid
$ amiga-diskgen create examples/basic.toml --dry-run
$ amiga-diskgen create examples/basic.toml --output disk.hdf
created 104857600 bytes at disk.hdf
$ amiga-diskgen inspect disk.hdf
$ amiga-diskgen verify disk.hdf
image is valid (104857600 bytes, 1 partitions)

Automatic geometry can make the represented image capacity differ from the requested capacity. Always inspect the requested bytes and represented bytes shown by --dry-run before creation.

The schema command prints the current schema-v1 template:

$ amiga-diskgen schema

Safety

Amiga DiskGen itself only creates regular image files. It rejects symbolic links, directories, and special-file destinations, validates and plans before opening output, writes into a temporary file in the destination directory, verifies and synchronizes that file, and only then publishes the final name. An existing destination is preserved unless --force is explicit.

Copying an image to physical media is a separate, destructive operation that Amiga DiskGen does not perform. A mistaken destination in an external copying tool can irreversibly overwrite the host system disk or another device. Read the image-to-device transfer safety guide in full and retain backups before attempting a transfer.

Commands

Command	Purpose	Writes data
validate <SPEC>	Parse and semantically validate a TOML specification.	No
schema	Print the maintained schema-v1 template.	No
create <SPEC> --dry-run	Build and display the image plan.	No
create <SPEC> --output <IMAGE>	Create, verify, synchronize, and publish an image.	Yes, regular image file only
inspect <IMAGE>	Decode, verify, and print image details and warnings.	No
verify <IMAGE>	Verify an image and print a concise result.	No

Global options are --quiet, -v/--verbose, and --color <auto|always|never>. The current implementation accepts --verbose and color policy for CLI-contract stability but does not yet vary output detail or emit colored diagnostics. Use --force only with create to replace an existing regular file. Full command syntax is available through --help.

Supported and unsupported features

Implemented host-side formatters accept the native discriminator sequence DOS\0 through DOS\7, named ofs, ffs, international-ofs, international-ffs, directory-cache-ofs, directory-cache-ffs, long-name-ofs, and long-name-ffs. Filesystem blocks may be 512, 1024, 2048, or 4096 bytes. See the specification reference for exact constraints and the compatibility policy before choosing a target.

The following are not supported:

• modifying or resizing existing images;
• importing files, installing Workbench, or installing a bootloader;
• PFS, SFS, other third-party filesystems, or arbitrary supplied handlers;
• direct output to physical or virtual devices;
• sparse, compressed, dynamic, or emulator-specific image containers; and
• compatibility claims outside recorded, passing evidence.

No Workbench files, ROMs, filesystem handler binaries, or other proprietary Amiga payloads are bundled. Details are in the filesystem-handler licensing policy.

Documentation

• Specification reference — every TOML field, default, constraint, and examples.
• CLI and diagnostics — commands, output, exit statuses, and error interpretation.
• Compatibility policy and evidence — targets, implemented formats, and unqualified claims.
• Architecture — planning, codecs, formatter, writer, and verifier boundaries.
• Operational and security notes — determinism, unsupported features, licensing, and threat model.
• Troubleshooting — common validation, creation, and verification failures.
• Transfer safety — prerequisites and safeguards for external image-to-device copying.
• On-disk format notes — field provenance and format rules.
• Contributing and security reporting.

Contributing

Contributor workflows for formatting, linting, tests, fixtures, fuzzing, interoperability evidence, documentation, and release preparation are in CONTRIBUTING.md. The minimum supported Rust version is 1.85, and unsafe Rust is forbidden.

License

Amiga DiskGen is licensed under the MIT License. See LICENSE.