Human68k Executable Patching Across Memory Layouts

Writing a Human68k tool to patch game executables for different memory layouts is a useful way to keep Sharp X68000 software running on varied machines. A title that works on a 2 MB X68000 XVI may fail on an expanded system, an accelerator, an emulator with a different map, or a machine fitted with modern hardware. The executable may contain fixed addresses, assumptions about free RAM, or tables positioned differently after loading.

A practical patcher should therefore understand the Human68k executable format, Motorola 68000 instruction encoding, relocation behaviour, and the target machine’s memory map. It should change a known value for a known reason, preserve everything else, and produce a result that can be tested on both an emulator and real hardware. The goal is a repeatable preservation tool rather than a collection of fragile hexadecimal edits.

Define The Patch Before Writing Code

Start by describing the problem in terms of observable behaviour. For example, a game may reserve work RAM at a fixed address, expect a particular amount of contiguous memory, or calculate a buffer from an address that is no longer suitable. A patch specification should record the original executable hash, the expected version, the location or signature of the target code, and the replacement operation.

Avoid defining a patch as “change bytes at offset 0x1234” unless that offset has been verified against a specific file. Different releases can add copyright screens, alter compression, or change the linker layout. A robust specification might instead say: find a sequence containing a MOVE.L immediate address followed by a known branch, verify its surrounding bytes, and replace the address with a value calculated from the selected memory profile.

Keep original and modified files separate. The tool should refuse to patch a file with an unexpected checksum unless the user explicitly selects an override. This protects scarce software found through Australian auction listings, specialist retro shops, or private collections where a clean replacement disk may be difficult to locate.

Read Human68k Files Safely

Human68k executables commonly use the X format, whose header and load information must be parsed according to documented field sizes rather than guessed from a hex editor. The Motorola 68000 is big-endian, so a 16-bit value stored as bytes 12 34 represents 0x1234, while a 32-bit value 12 34 56 78 represents 0x12345678. Small helper functions for reading and writing big-endian integers should be used everywhere.

The parser should identify the header, text, data, symbol, relocation, and uninitialised areas where those fields are present. It should calculate file ranges with checked arithmetic, reject truncated input, and ensure that every offset remains within the file. A malformed header must produce a clear error rather than a partially patched binary.

Relocation information deserves special attention. A value in the file may be a link-time address that Human68k adjusts when the program loads. Patching that value as though it were a final runtime address can produce a binary that works at one load address and fails at another. The tool should either apply changes to relocation-aware fields or explicitly document that a patch targets post-relocation machine code.

Represent The Memory Layout

Treat a memory layout as data, not as a constant buried in the source. A profile could contain the lowest usable work-RAM address, the upper limit, reserved areas, video and I/O ranges, and any region unavailable to ordinary programs. It may also define alignment rules, stack headroom, and the preferred location for a relocated buffer.

On a 68000 system, address calculations are especially important because there is no general-purpose memory-management layer protecting a game from a bad absolute pointer. A value that appears harmless in a binary can point into video RAM, ROM, an expansion device, or unmapped space on another machine. The patcher should check that a proposed range fits completely inside usable RAM, not merely that its starting address looks valid.

Profiles might include a stock 2 MB machine, an expanded late-model system, and an emulator configuration. Avoid presenting these as universal maps: individual X68000 models, memory boards, accelerators, and resident utilities can change what is actually available. Hardware projects documented in the wider X68000 community, including expansion and network-related work, are a reminder that “more RAM” does not automatically mean “the same free RAM.”

Locate Code With Signatures

There are three useful ways to locate a patch site. A fixed file offset is simple and fast, but it only suits one exact executable build. A byte signature with wildcarded addresses survives some layout changes. A lightweight disassembler or instruction decoder is more flexible because it can recognise an operation such as MOVE.L #imm,D0 without depending on every neighbouring byte.

Signatures need enough context to avoid accidental matches. Include stable opcodes before and after the value, then verify that exactly one candidate was found. If there are zero matches, report that the executable version may be unsupported. If there are multiple matches, stop and ask for a more specific rule through the command-line error rather than silently patching every occurrence.

The patch rule should state the expected instruction size and operand position. On the 68000, a long immediate operand occupies four big-endian bytes, while a word displacement occupies two. A replacement that writes four bytes into a two-byte field will corrupt the next instruction. It is worth building a small instruction decoder that handles the handful of opcodes used by the target game instead of pretending every byte sequence is a plain integer.

Apply Relocation-Aware Changes

A safe patcher separates file addresses, load addresses, and effective runtime addresses. If the text segment begins at a known load address, a file offset can be translated to a runtime location by adding the segment base after accounting for the executable header and preceding sections. Data and BSS need separate treatment because BSS consumes memory but has no corresponding bytes in the file.

For a buffer relocation, the program may need more than a single pointer replacement. The original address could appear in an instruction, a table, a bounds check, and a cleanup routine. Search for all references within the relevant code range, classify each one, and patch only those proven to refer to the moved object. If the game uses PC-relative addressing or computes the pointer at runtime, changing an absolute constant may have no useful effect.

A command-line interface can make the workflow understandable:

x68kpatch game.x --profile 4mb --patch save-buffer --output game-4mb.x

The tool should print the input hash, selected profile, matched signature, old value, new value, and output hash. A dry-run mode is valuable when examining an unfamiliar title. Keep patch definitions in a readable format such as JSON, TOML, or a small domain-specific file so that another enthusiast can audit the reasoning without recompiling the program.

Test In Emulation And On Hardware

Testing should begin with a clean original and a reproducible emulator configuration. Confirm that the unmodified game reaches the same point each time, then apply one patch and test loading, saving, level changes, sound, menus, and exit paths. Memory errors often appear only after a long play session because a buffer is reused or cleared well after startup.

A useful diagnostic build can write a marker to an unused diagnostic area, display the selected layout profile, or log a compact event code to a file. Do not leave debug writes aimed at guessed hardware addresses in a release patch. The X68000’s video and I/O regions are real devices, not harmless placeholders, and an incorrect write can lock the machine.

Real hardware remains important. Emulators may be forgiving about timing, bus behaviour, or illegal accesses. Test on the actual target family when possible, with a known-good disk or hard-disk image and a method for restoring it. For enthusiasts in Melbourne, Sydney, Brisbane, or Perth, local retrocomputing groups can provide access to models that are expensive or uncommon in the Australian second-hand market. Photograph or record the machine model, RAM configuration, accelerator, and resident software for every test result.

The X68K.NET diary is a useful model for recording this kind of practical history: document the input file, hardware, symptoms, patch revision, and result rather than preserving only the final binary.

Package The Tool For Preservation

A preservation-oriented release should contain the source code, build instructions, patch definitions, test vectors, and a short technical note explaining each changed address. Include hashes for supported executables and state whether the tool expects an X-format file, a disk image, or an extracted program. This makes future maintenance possible when a compiler or operating system changes.

For Australian users, the distribution format matters. The 68000 toolchain may be built on Linux, macOS, or Windows, while the resulting executable must run under Human68k. A cross-compiled command-line utility can generate the patch on a modern machine, then the output can be copied through an emulator, CompactFlash workflow, SCSI2SD setup, or network transfer. Keep the process independent of a proprietary editor so the work remains usable when old software disappears.

Copyright also needs careful handling. In Australia, the Copyright Act 1968 (Cth) governs copying and communication of software, and the exceptions are limited. Work from a legally obtained copy, retain the original, and distribute patch data or source instructions rather than a complete commercial executable unless permission has been obtained. This approach is safer for a public archive and still gives owners a practical way to reproduce a modification.

Compare Patching Strategies

Different games call for different levels of analysis. A static byte replacement is appropriate when the executable is fixed and the target has been verified. A signature-based patch is usually a better default for a small preservation project. A relocation-aware transformation takes longer to implement but is justified when the same title must run across several memory configurations or releases.

Strategy	Layout Awareness	Implementation Effort	Main Risk	Suitable Use
Fixed file offset	None	Low	Wrong release or shifted file	One verified executable
Exact byte signature	Limited	Low to medium	Ambiguous or fragile match	Small set of known versions
Wildcard signature	Moderate	Medium	Incorrect wildcard placement	Builds with changed addresses
Instruction-aware scan	High	Medium to high	Decoder bug	Several related executable versions
Relocation-aware rewrite	Very high	High	Incorrect load-time assumptions	Multiple memory layouts and loaders

A good first release can support one game, one executable format, and two well-defined profiles. Add features only when a real title requires them. Every new patch rule should come with an original hash, a before-and-after byte range, a reason for the change, and at least one successful runtime test.

Build the utility as a preservation instrument rather than a one-off hack. A deterministic parser, explicit memory profiles, verified signatures, and clear logs will let another X68000 owner reproduce the result years later. That is especially valuable when machines, disks, and replacement parts are scattered across a small Australian enthusiast market.

Download the source, test it against a clean Human68k executable, and record the machine configuration beside every result. Share reproducible patch definitions with the X68000 community, keep modified binaries clearly separated from originals, and expand the profile set only after each new layout has been tested on suitable hardware or a documented emulator configuration.