Human68k tools for Nintendo Famicom disk images
Nintendo's Famicom Disk System gave the Family Computer a way to load and save software beyond cartridges. Introduced in Japan in 1986, it supported read-only Disk Cards and later writable magnetic disks, mixing console convenience with removable storage. Those disks are now scarce, but their images remain valuable preservation artefacts for translation work and the study of early Japanese software.
Sharp's X68000 provides an unusually direct bridge to that hardware. Its Human68k environment provides byte-oriented file calls, command-line conventions and enough low-level control to inspect a disk image without hiding changed bytes. Creating a Human68k program to read and write Nintendo Famicom Disk System images is therefore a practical preservation exercise as well as a piece of retro software engineering.
Australian collectors regularly hunt for unobtainable FDS software through eBay Australia, Gumtree and specialist sellers, paying in Australian dollars while import GST or courier charges may apply. Swap gatherings around Sydney, Melbourne, Brisbane and Adelaide provide useful ways to examine adapters and compare dumps. A scarce RAM Adapter can cost more in Australia than an original disk, so clear photographs, tracked postage and sensible return terms matter.
Local conditions also shape the bench. Melbourne's variable humidity and Brisbane's summer heat are less forgiving than Canberra's dry winters, so magnetic media and old plastics need stable storage. Japanese FDS hardware may expect 100 volts, whereas Australian mains power is 230 volts and normally uses Type I plugs; a properly rated isolation transformer is safer than a small travel adaptor. The goal is repeatable work, not merely getting bytes onto a screen.
Why the Famicom disk system matters
An FDS image has two layers that are easy to conflate. The container records the physical layout of sides, tracks and sectors, while the logical filesystem holds directory entries, allocation information and program data. A tool may edit one without touching the other. A safe design exposes both levels and labels every operation as either container-level or filesystem-level.
Begin with a read-only inventory of a known dump: file length, detected format, sector count, non-empty ranges and any directory data that can be decoded. Then require an unchanged round trip before enabling editing. This sequence catches assumptions about offsets and record sizes early, and it gives preservationists a reproducible baseline instead of an attractive but incorrect screenshot.
Keep the hardware boundaries explicit. The X68000 tool normally reads image files, not a physical FDS disk or a Nintendo Disk Card; loading that media requires separate compatible hardware, an interface and its own software. Successful file parsing does not prove that a disk can be rewritten. The program can prepare or verify an image, but writing it back to magnetic media belongs to a tested device and a separate procedure.
Mapping the image format
Images circulated under several container formats, especially .d88 and raw or lightly structured .fds files, and community utilities do not always interpret them identically. There is no single byte count that every dump must have. The program should identify the chosen dialect, test the declared length against its record geometry and reject mismatches before opening an output file. Format names belong in the readme because a .d88 extension alone is not proof of a particular layout.
Most FDS tooling works with 256-byte sector payloads and metadata that ties sectors to sides and tracks. Some containers add per-side or per-track headers, while logical areas contain packed date fields, allocation tables and directory records. Parse those fields as bytes first, then convert them with explicit shifts or arithmetic. Blindly copying a C structure into a file can reverse an integer or introduce compiler-specific padding.
Preserve unknown regions rather than normalising them away. Copy every byte, retain ordering exactly and keep a side-by-side comparison between the source and the rebuilt file. Once the directory has been decoded, logical file extraction should follow its allocation entries back to physical sectors and restore the original data order. Test the parser against dumps made by different tools, and record disagreements rather than choosing whichever result looks tidier.
Reading images with Human68k
Human68k file access is well suited to chunked processing. Its DOS layer is reached through the X68000's trap services or SDK wrappers for opening, seeking, reading, writing and closing files, although exact names and headers differ between toolchains. Use conventional drive and directory syntax such as A:\DISK\GAME.D88 in examples, and keep path parsing separate from the image code. That makes the core testable with a small set of fixture files.
The 68000 is big-endian, while some desktop utilities and emulator formats use little-endian packed values. Work with unsigned byte arrays and convert multi-byte quantities explicitly; do not let a C int, long or structure determine the disk layout. Human68k compilers also have their own type sizes and alignment rules. A modest sector buffer is safer than trying to load an entire image into memory, particularly on a period-correct machine.
A useful command line might offer list, extract, replace, verify and raw-copy modes, with short progress messages that fit an 80-column screen. An emulator is excellent for developing the interface, but a final native run catches path, allocation and byte-order mistakes that a desktop test can hide. The tool should run on a standard X68000 and on a Nereid-X-equipped machine without requiring either one.
Writing images without losing bytes
Writing should follow the same conservative order as archiving. Copy the source to a temporary file, modify only the requested sectors, close it, reopen it and compare it with the expected result before replacing the working copy. Never treat a preserved dump as the working master. If the program must patch a directory record or allocation chain, calculate the affected sectors from the decoded structures rather than relying on a guessed fixed offset.
Human68k DOS calls make it easy to write too much or write in the wrong place, so the program should check return values after every seek and transfer. Report the human-readable path, byte offset and count involved in an error. After the final write, generate a SHA-256 digest on a modern machine and keep it beside the image; the digest identifies the exact copy even though it is not an authentic FDS checksum.
For frequent archiving, the SCSI-backed ZIP workflow provides another useful pattern: keep an immutable source image and use removable storage for a verified copy. The same principle applies when exchanging disks at an Australian swap meet, where “it boots on real hardware” is a more useful claim than an attractive screenshot. Record the dump tool, dump options and observed test results with every transfer.
Choosing a verification workflow
Verification should progress from the simplest container check to the most realistic hardware test. A byte-for-byte comparison proves that a write did not alter unselected data; it does not prove that the modified image matches what the FDS expects. Each method has a distinct role in establishing what has actually been tested.
| Method | Best use | Evidence gained | Limitation |
|---|---|---|---|
| Native Human68k on X68000 | Verify real DOS, endian and memory behaviour | Actual platform compatibility | Slower and needs suitable test media |
| X68000 emulator | Iterate on parsing and interface | Repeatable logic checks | Does not prove real-hardware behaviour |
| Modern desktop utility | Cross-check metadata and hashes | Independent comparison | May hide raw differences or normalise fields |
| Physical FDS emulator or console | Accept changed media and boot software | End-to-end system behaviour | Requires compatible hardware and writable media |
Run all four when the stakes justify it. At minimum, perform a native round trip and an emulator check for every release. Use a physical console test for images intended to boot, and label images that have passed only structural comparison. Honest labels are more useful to the next collector than a single green “verified” badge with no defined meaning.
Preserving the work and passing it on
Documenting the project is part of preserving the platform. Publish the source under a clear licence, record compiler assumptions, include small test fixtures where copyright permits, and distinguish format findings from guesses. A versioned format note should list container offsets, sector ordering, decoded fields and every unsupported feature. Maintain a change log so a later visitor to X68K.NET can understand how the utility works and why its decisions were made.
That evidence-first approach also improves how the tool is presented. The editorial pattern in writing an independent review illustrates a broader principle: describe the test environment, separate observations from judgement and disclose what could not be verified. Adapt that discipline for a Human68k utility, where a claim such as “reads FDS images” should name the supported formats and the exact test performed.
Start with one legally obtained dump, create a checksummed working copy and run a read/write round trip on native hardware or a compatible emulator. Publish the program, format notes and failure cases with the X68000 community, Australian retro-computing groups and preservationists working with Japanese console media. Reusable evidence is the most valuable contribution this tool can make.
Nereid-X Expansion Board
A personally-produced LAN+USB+Memory expansion board for Sharp X68000 series computers. Multiple production runs were offered, including a final batch and a later revival reproduction run.
Power Supply Repair
X68 power supply repair and modification services were offered by the site owner, with documentation shared through diary entries spanning 2001–2006.
Server & Networking
Notes on FreeBSD administration, ISP changes, server migration, and networking topics. The site itself ran on FreeBSD with the hns diary system and Namazu search integration.
Get in touch
X68K.NET connects Sharp X68000 enthusiasts through community links and shared projects. Reach out with questions about the Nereid project or X68 resources.