Writing A Human68k Utility For Direct Disk Image Editing

A small text editor that works directly inside an X68000 disk image can be more useful than a full desktop conversion workflow. It lets you correct configuration files, update documentation, repair startup scripts, or change a game’s text resources without repeatedly moving files between a modern computer and a physical Japanese floppy disk.

The project sits at the intersection of Human68k programming, FAT12 filesystem handling, and preservation practice. The most important design decision is to treat the image as a filesystem container rather than as an ordinary text file. Once the utility understands sectors, clusters, directory entries, and Japanese character encoding, it can make precise changes while preserving the rest of the disk.

Choosing The Image Model

Begin by identifying the disk image formats your utility will accept. A raw image is usually the easiest target because its bytes correspond directly to sectors. Other formats can contain headers, geometry information, or metadata around the floppy contents. X68000 enthusiasts commonly encounter images associated with XDF, DIM, D88, and similar conventions, so a program that assumes every file begins with sector zero will eventually damage an image or display nonsense.

A sensible first version should support one well-defined raw format and reject everything else with a clear error. Add format detection later, based on file size, known signatures, and geometry checks. Silent guessing is risky when the same file might be a 2HD image, a hard-disk partition, or a container with an external header.

Human68k can access an image stored on a hard disk, SCSI device, CompactFlash adapter, or network-mounted resource, depending on the machine and setup. The utility should use ordinary DOS file operations to open the image, obtain its length, seek to an offset, read a sector, and write it back. This is different from talking directly to the floppy controller: the program is editing a file that represents a disk, so the host filesystem must also have enough free space and reliable write support.

Working Within Human68k

A practical Human68k build can be written in C, with a small command-line interface suited to the X68000’s text consoles. Avoid assuming modern C library behaviour. Older compilers may have limited support for prototypes, long filenames, buffered I/O, and standard integer types. Define fixed-width types yourself when necessary, and keep buffers modest so the program remains comfortable on machines with limited memory.

The command syntax should make accidental edits difficult. A useful pattern is:

IMGEDIT IMAGE.XDF READ README.TXT
IMGEDIT IMAGE.XDF WRITE README.TXT UPDATE.TXT
IMGEDIT IMAGE.XDF REPLACE CONFIG.SYS CONFIG.NEW

The read command extracts a file to the current directory. The write command updates an existing path, while replace can require the destination to exist before changing it. A --dry-run equivalent is helpful, although a short option such as /N may feel more natural to users of classic DOS software. Always print the image name, internal path, original size, new size, and number of changed clusters before committing.

Character encoding needs an explicit policy. Human68k software may use Shift-JIS, while an editor on a modern Australian workstation may save UTF-8. Converting automatically can corrupt half-width katakana, box-drawing characters, or byte sequences that are meaningful to an application. A safer first release should offer binary-preserving mode and separate conversion options, with Shift-JIS treated as a deliberate choice rather than an invisible assumption.

Parsing FAT12 Safely

Most floppy disk images used with Human68k employ a FAT12-style layout, though the exact geometry and filesystem details must be read from the boot sector instead of hard-coded. Important fields include bytes per sector, sectors per cluster, reserved sectors, the number of FAT copies, root-directory entry count, total sectors, and sectors per FAT. Calculate the positions of the FAT, root directory, and data region from those values.

FAT12 entries are packed across twelve bits, so an entry cannot be read with a simple sixteen-bit array index. For cluster number n, the byte offset is approximately n + n / 2. Even-numbered and odd-numbered entries use different half-word masks. A helper such as fat12_get() and its matching fat12_set() makes this detail easier to test and prevents directory code from becoming cluttered with bit manipulation.

The root directory is generally a fixed region in classic FAT12 media. Each 32-byte entry contains an eight-character base name, a three-character extension, attribute flags, timestamps, starting cluster, and file size. Skip volume labels, subdirectories, deleted entries, and long-name metadata unless the target image demonstrably uses them. Human68k-era disk layouts often reward conservative handling: preserve every field you do not need to change.

When resolving a path, compare names using the filesystem’s short-name rules rather than relying on the host operating system. Case handling, padding with spaces, and the distinction between a directory and a regular file all matter. If the requested file does not exist, return a useful diagnostic instead of creating a new directory entry automatically. Creating files safely requires free-entry allocation, cluster-chain construction, timestamp policy, and possibly directory growth.

Editing Text Without Breaking Files

The safest update strategy is read, transform, validate, allocate, write, and commit. First, load the existing cluster chain into memory or a temporary host file. Check that the chain does not loop, point outside the data area, or overlap another allocation. Then apply the requested line or byte changes while retaining the original file if the new content is invalid.

If the replacement fits within the current allocation, the program can overwrite the existing data and update the size field. If it grows, find a free cluster chain, write the new content there, update the directory entry, and release the old chain only after the new chain has been verified. If it shrinks, retain the existing chain until the directory size and terminating FAT entry are safely written, then free surplus clusters.

Do not use ordinary newline conversion unless the user requests it. Human68k text may use carriage-return and line-feed pairs, while a modern editor may produce line-feed-only files. A configuration parser might tolerate one form and reject the other. The utility can provide explicit modes such as RAW, DOS, and SJIS, reporting the number of bytes before and after conversion.

Power failure is a real preservation concern. A two-phase approach reduces the chance of leaving an image with a new directory entry pointing to incomplete data. Write the replacement clusters first, flush the host file, update the FAT chain, flush again, then update the directory entry. Make a backup copy before modifying the original, using a distinct extension such as .BAK. This is especially worthwhile when the image contains a rare game or an irreplaceable personal disk.

Handling X68000 Hardware Realities

A disk image utility is often used because the original hardware is inconvenient to access. X68000 machines are uncommon in Australia, and importing one from Japan can involve expensive freight, voltage concerns, and a long wait for replacement parts. A working image-editing workflow lets an owner prepare software on a modern computer before transferring it through SCSI, CompactFlash, a Gotek-style device, or a network bridge.

Power work deserves care. Japanese X68000 systems were designed around Japanese mains conditions, so Australian owners should verify the rating and use suitable isolation or conversion equipment rather than assuming a plug adapter is enough. Battery leakage is another common preservation issue; the documented RTC battery repair is a useful reminder that a small hardware failure can damage surrounding traces and turn a software project into board-level repair.

The tool should therefore support a “prepare elsewhere, verify on machine” workflow. On a Linux, Windows, or macOS workstation, make a copy of the image, run structural checks, edit the file, and calculate a checksum. Transfer that copy to the X68000 and use a lightweight verification command there. If the machine is being demonstrated at a retrocomputing meet in Melbourne or Sydney, this process is far less stressful than experimenting on the only physical disk while a queue forms behind you.

Australia’s second-hand market also changes the economics. Shipping a replacement floppy from Japan can cost more than the media itself, and local listings may describe an item as “untested” when it simply lacks the correct cable or display. Image-first editing preserves scarce originals and makes it practical to keep a known-good master while using a working copy for daily experimentation.

Testing The Utility Properly

Testing should begin with synthetic images, not valuable software. Generate small FAT12 images containing empty files, one-cluster files, files that end exactly at a cluster boundary, fragmented files, and files that span several FAT sectors. Compare the modified image against expected bytes and verify that unrelated directory entries, timestamps, and free-space counts remain unchanged.

Include malformed cases deliberately. Test an invalid boot signature, impossible sector size, FAT entries pointing beyond the image, circular cluster chains, duplicate allocation, truncated directory entries, and a file size larger than its chain. The correct response is a refusal to edit, with an error that identifies the problem. A preservation tool should fail closed rather than attempt to repair structures during a text replacement.

Real hardware testing should use disposable media or a copy of a known image. Boot the X68000, list the directory, read the edited file with a native viewer, and run any affected program. Check Japanese characters, line endings, file attributes, and startup behaviour. A file that looks correct when extracted on a workstation may still fail because an application expects a particular encoding or because its size field was updated incorrectly.

Keep a small test archive with checksums and notes about the compiler, emulator, and target machine. Emulators are excellent for repeatable tests, while an actual X68000 exposes timing, device-driver, and display assumptions that an emulator may hide. For community sharing, document the image format, expected command line, and whether the utility edits an image in place or creates a new output file. Project notes collected on X68K.NET fit naturally alongside this kind of practical preservation record.

Choosing A Safe Workflow

There are three useful approaches: extract and edit with a modern filesystem tool, edit through a mounted or emulated disk, or run a dedicated Human68k utility against the image file. The last option is valuable when the correction must happen on the X68000 itself, when a legacy encoding must remain untouched, or when the project aims to preserve an authentic machine-side workflow.

Approach	Strengths	Risks	Best Use
Modern extraction tool	Fast development and strong scripting support	Encoding and metadata may be normalised	Large batch changes
Mounted or emulated image	Convenient visual inspection	Behaviour can differ from real hardware	Routine testing
Human68k image editor	Native paths, bytes, and conventions	More difficult compiler and filesystem work	Authentic repairs and field use
Direct physical-disk editing	Closest to original media	High risk from hardware or power failure	Only with verified backups

A compact first release should edit existing short-name files only, preserve file length unless explicitly asked to resize, and create a backup before every write. Later versions can add recursive paths, new-file creation, checksums, sector viewers, and support for additional image containers. Keep the filesystem engine separate from the command parser so those additions do not weaken the core safety checks.

The finished program should make its actions visible: image geometry, target path, original byte count, replacement byte count, cluster count, and final checksum. That output is useful when comparing a disk preserved in Perth with a copy shared in Brisbane, or when recording exactly what changed before uploading a patched image to an enthusiast archive. Clear logs turn a one-off experiment into reproducible technical history.

Build the smallest reliable version first, test it against disposable images, and publish the source, format assumptions, and sample files with the executable. A careful Human68k disk-image editor can keep fragile software usable for years while giving the X68000 community a practical way to repair and document its own collection. Share the finished utility and test results with fellow enthusiasts, and keep a verified untouched image beside every working copy.