A Human68k palette utility for reliable save and restore

Creating a Human68k Utility to Save and Restore Palette Registers is a compact project with useful results. A small command-line program can capture the current X68000 colour state, write it to a file, and restore it after a game, demo, graphics program, or hardware test has changed the display. The same tool can support software preservation and day-to-day experimentation.

The important work is not the amount of code. It is understanding how the X68000 exposes palette RAM, how Human68k handles executable programs and files, and how to avoid leaving the machine in a partially updated state. A reliable utility should be conservative, predictable, and easy to use from a floppy image, hard disk, CompactFlash setup, or networked storage system.

This project is particularly valuable when repairing or modifying an older machine. A fading monitor, replacement power supply, expansion board, or custom graphics program can make visual troubleshooting harder if the palette changes unexpectedly. Saving a known-good palette gives the operator a quick way to return to a controlled display environment.

For Australian owners, practical constraints matter as well. X68000 parts are commonly sourced through Japanese sellers, specialist retro forums, eBay, or Gumtree in Sydney, Melbourne, Brisbane, and Perth, so testing may happen on hardware assembled from several regions. A utility that records its data clearly is easier to use when replacement machines and accessories arrive at different times.

Approach	Strengths	Limitations	Suitable use
Direct palette register access	Fast, small, independent of screen contents	Requires hardware knowledge and privilege handling	A dedicated Human68k utility
IOCS or system service call	Better compatibility with software conventions	May not expose every register or mode	Applications that should cooperate with the OS
Screen image capture	Preserves visible appearance	Does not preserve palette registers themselves	Documentation and visual comparison
Fixed palette data file	Simple and reproducible	Cannot capture an unknown current state	Demo development and regression testing
Register dump with validation	Easy to inspect and diagnose	Needs a defined binary format	Hardware repair and preservation work

Understanding the X68000 palette hardware

The X68000 graphics system uses programmable palette entries rather than treating colour as a permanently fixed property of the display mode. A palette entry stores component values in a hardware-defined word. The machine can therefore change the appearance of existing pixels without rewriting the screen image, which is useful for fades, status displays, animation effects, and demos.

Before writing code, confirm the exact register map and entry count for the target graphics mode and machine documentation. X68000 references commonly describe palette registers as a block of word-sized hardware locations, but a utility should not rely on an unverified address copied from a forum post. Model differences, emulators, and documentation translations can expose small but important differences in terminology.

The colour word also needs a defined bit layout. It is tempting to treat the value as an ordinary RGB integer, yet the order and active bits must follow the X68000 hardware specification. A safe implementation names the masks and shifts explicitly, such as red mask, green mask, and blue mask, instead of scattering hexadecimal constants throughout the source.

The machine’s 68000 processor uses big-endian word ordering. If the utility writes raw 16-bit values to disk, document that the file contains high bytes followed by low bytes. This makes the file portable between Human68k programs and modern tools without confusing a valid palette with a byte-swapped one.

Designing a useful command-line format

A practical program can provide three basic operations:

PALUTIL SAVE filename
PALUTIL LOAD filename
PALUTIL INFO filename

SAVE reads every palette register and writes a complete snapshot. LOAD validates the file before changing any register. INFO displays the file version, number of entries, and perhaps a short list of decoded RGB values. Short verbs are helpful on an X68000 because the utility may be launched from a small shell, batch file, or floppy-based recovery environment.

The file should include a small header rather than containing only anonymous words. A reasonable format might include a four-byte signature such as X68P, a one-byte version, a one-byte entry count or mode identifier, a two-byte data length, and then the palette words. A checksum or 32-bit CRC makes accidental corruption visible, particularly when files are transferred through old removable media.

Do not silently accept a truncated file. The loader should check the signature, version, expected length, and checksum before touching hardware. It should also reject extra data unless the format deliberately allows extensions. A failed load must leave the current palette unchanged, which is much safer than restoring the first half of a file and then reporting an error.

A plain binary format is ideal for fast restoration, while an optional text export can help with editing and documentation. For example, a companion command could produce lines containing an index and three component values. The binary file remains the authoritative snapshot, and the text version becomes useful in a source repository or repair log.

Implementing register access under Human68k

A C program for Human68k can represent the palette block as a volatile array of 16-bit values, provided the compiler’s pointer and integer types match the target environment. The volatile qualifier tells the compiler that each read and write has hardware significance. It prevents an optimisation from removing repeated accesses or caching a value that may change outside ordinary program flow.

Conceptually, the save routine looks like this:

for (i = 0; i < PALETTE_COUNT; i++) {
    value = palette_registers[i];
    put_be16(file, value);
}

The load routine should first read the complete file into a buffer, validate it, and only then perform:

for (i = 0; i < PALETTE_COUNT; i++) {
    palette_registers[i] = get_be16(buffer + i * 2);
}

The actual declaration of palette_registers depends on the compiler and hardware header being used. Keep the address in one platform-specific source file, with comments citing the technical reference that established it. This makes it easier to adapt the program for an emulator or a different X68000 configuration without rewriting file handling.

Hardware access may require supervisor mode or a system-supported transition into a privileged context. The utility should handle that deliberately rather than crashing with an address error. If the chosen development environment provides a supervisor-call wrapper, use it. If direct access is only safe in a specific execution mode, document the requirement in the help screen and refuse to proceed when it cannot be met.

Updating one register at a time can produce a short visible colour change while the display is active. For a simple palette restore this may be acceptable, but a polished version can coordinate the operation with vertical blanking or temporarily suppress the relevant display activity if the system services allow it. Avoid broad interrupt manipulation unless the exact consequences are understood; an old machine can become unresponsive if interrupts are disabled for too long.

Making snapshots safe for real projects

The most useful workflow is to save the palette immediately before running a program that is known to modify it. A batch file can invoke the utility, start the target program, and then restore the saved values when the program exits. This is especially helpful for development sessions where a demo repeatedly changes palette entries during testing.

A restore utility should offer a dry-run or inspection mode. It can print the number of entries, show the first and last few values, and report whether the file matches the current machine mode. A FORCE option may be appropriate for experienced users, but the default should reject mismatched data rather than guessing.

Hardware failures should be considered part of the design. If a machine has unstable power, a register read may return nonsense, and a write may behave unpredictably. Many Australian owners work on systems connected to modern replacement power supplies or step-down equipment from 240-volt mains. The palette tool cannot compensate for an unsafe or noisy supply, so electrical repairs should be completed with the machine unplugged and handled by someone competent with mains safety.

The utility can become a useful diagnostic companion to projects such as the Nereid-X expansion board. A saved palette before and after an expansion test helps separate a graphics-state change from a broader system fault. It also provides a small, repeatable test artefact that can be copied between a stock machine, a modified unit, and an emulator.

Testing, distribution, and preservation

Begin testing in an emulator when possible, then verify behaviour on real hardware. Test a palette containing black, white, primary colours, alternating values, and entries with only one active component. These patterns reveal incorrect masks, reversed component order, byte swapping, and off-by-one errors much faster than a typical game screen.

Test interruption and failure paths as carefully as successful loads. Try a missing file, a zero-length file, a truncated header, a wrong signature, an unsupported version, and a deliberately altered checksum. The program should return a useful error code and preserve the existing display state. Keep output short enough that it remains readable on a narrow text screen.

Distribution should include the executable, source code, a format note, and a small sample palette. Human68k users may run software from floppy disks, SCSI or IDE storage, CompactFlash adapters, or network transfers, so avoid assuming a modern directory structure. Use filenames that are comfortable within the target environment and provide a usage message that does not depend on Unicode or Japanese-capable fonts.

Preservation also means recording the conditions of each snapshot. Note the machine model, graphics mode, emulator version if relevant, and whether the palette was captured before or after a program ran. Australian hobbyists often buy hardware from overseas and test it across different displays, so this metadata can explain why an identical file appears different on a later setup.

Distribution should respect software rights. A palette dump created from your own test program is straightforward to share, while assets extracted from commercial games may be covered by the Copyright Act 1968. Share the utility, source, format specification, and original test data where possible, and keep commercial palettes for personal documentation unless permission allows wider publication.

A compact implementation can grow in stages. Start with save and load, add validation, then add human-readable inspection and optional vertical-blank synchronisation. Keep the core conservative: read the complete snapshot, validate it, and only then write the hardware registers. That approach produces a tool useful for daily development as well as long-term X68000 preservation.

Build the utility around a documented register map, a versioned binary format, and clear error handling. Test it in an emulator and on a real machine, record the hardware conditions, and publish the source with a small set of legally shareable sample files. A dependable palette snapshot tool can then become part of every Human68k development disk, repair kit, and retrocomputing archive.