Skip to content

API Reference

This page documents the public C API in:

  • include/m68k.h
  • include/loader.h
  • include/disasm.h
  • include/rocket68.h

Header Usage

Include the umbrella header:

#include "rocket68.h"

Or include only what you need:

#include "m68k.h"
#include "loader.h"
#include "disasm.h"

Core Types

Integer Aliases

  • u8, u16, u32
  • s8, s16, s32

M68kSize

typedef enum { SIZE_BYTE = 1, SIZE_WORD = 2, SIZE_LONG = 4 } M68kSize;

M68kRegister

Register union used for D0-D7 and A0-A7. w maps to the low 16 bits of l.

M68kCpu

One complete CPU instance with registers, execution state, memory binding, and callbacks. d_regs is aligned to 64 bytes.

Host Memory Callback Types

  • M68kRead8Callback
  • M68kRead16Callback
  • M68kRead32Callback
  • M68kWrite8Callback
  • M68kWrite16Callback
  • M68kWrite32Callback

Status Register Flags

  • M68K_SR_C carry
  • M68K_SR_V overflow
  • M68K_SR_Z zero
  • M68K_SR_N negative
  • M68K_SR_X extend
  • M68K_SR_S supervisor mode

Function Code Constants

  • M68K_FC_USER_DATA
  • M68K_FC_USER_PROG
  • M68K_FC_SUPV_DATA
  • M68K_FC_SUPV_PROG
  • M68K_FC_INT_ACK

Interrupt ACK Constants

  • M68K_INT_ACK_AUTOVECTOR
  • M68K_INT_ACK_SPURIOUS

Lifecycle and State

void m68k_init(M68kCpu* cpu, u8* memory, u32 memory_size);

Initializes all CPU fields and binds a flat memory buffer. If host memory callbacks are installed later, read/write API calls dispatch through callbacks instead of this flat buffer.

void m68k_reset(M68kCpu* cpu);

Performs reset-state initialization and loads:

  • initial SSP from 0x00000000
  • initial PC from 0x00000004

void m68k_set_pc(M68kCpu* cpu, u32 pc);

Sets PC and triggers pc_changed callback if installed.

u32 m68k_get_pc(M68kCpu* cpu);

Returns PC.

void m68k_set_model(M68kCpu* cpu, M68kModel model);

Selects the CPU model profile for this instance. The default after m68k_init is M68K_MODEL_68000, where the later-family instructions MOVEC, MOVES, RTD, and BKPT raise illegal-instruction exceptions. M68K_MODEL_68010 enables those instructions.

M68kModel m68k_get_model(M68kCpu* cpu);

Returns the selected CPU model profile.

void m68k_set_sr(M68kCpu* cpu, u16 new_sr);

Sets SR with masking (0xA71F) and performs USP/SSP swap when supervisor state changes.

void m68k_set_irq(M68kCpu* cpu, int level);

Sets the asserted interrupt level (0-7), modeling the IPL lines. Levels 1-6 are level-sensitive: without an INT ACK callback the request clears automatically when serviced; with a callback installed the level stays asserted until the host sets 0 or a new level. Level 7 is edge-sensitive: each transition to 7 latches one non-maskable interrupt.

Register Accessors

  • void m68k_set_dr(M68kCpu* cpu, int reg, u32 value);
  • u32 m68k_get_dr(M68kCpu* cpu, int reg);
  • void m68k_set_ar(M68kCpu* cpu, int reg, u32 value);
  • u32 m68k_get_ar(M68kCpu* cpu, int reg);

Invalid register indexes are ignored on set and return 0 on get.

Execution API

void m68k_step_ex(M68kCpu* cpu, bool check_exceptions);

Executes one instruction with optional interrupt/trace checks.

void m68k_step(M68kCpu* cpu);

Equivalent to m68k_step_ex(cpu, true).

int m68k_execute(M68kCpu* cpu, int cycles);

Adds cycles to the timeslice, runs until cycles_remaining <= 0, and returns consumed cycles for this call.

Timeslice Helpers

  • int m68k_cycles_run(M68kCpu* cpu);
  • int m68k_cycles_remaining(M68kCpu* cpu);
  • void m68k_modify_timeslice(M68kCpu* cpu, int cycles);
  • void m68k_end_timeslice(M68kCpu* cpu);

Memory API

All memory accesses are big-endian. Addresses are masked to 24-bit internally before bounds checks.

Reads

  • u8 m68k_read_8(M68kCpu* cpu, u32 address);
  • u16 m68k_read_16(M68kCpu* cpu, u32 address);
  • u32 m68k_read_32(M68kCpu* cpu, u32 address);

Writes

  • void m68k_write_8(M68kCpu* cpu, u32 address, u8 value);
  • void m68k_write_16(M68kCpu* cpu, u32 address, u16 value);
  • void m68k_write_32(M68kCpu* cpu, u32 address, u32 value);

Behavior notes:

  • Word/long accesses on odd addresses trigger address error handling before any callback dispatch.
  • If a host memory callback is installed for the requested width, it is called for the access; addresses passed to callbacks are masked to 24 bits for data access and instruction fetch alike.
  • When callbacks are used, default flat-buffer range (bus error) checks for that access are bypassed and are expected to be handled by the host.
  • Out-of-range flat-memory accesses trigger bus error handling.

Callback API

All callbacks are per-instance.

void m68k_set_wait_bus_callback(M68kCpu* cpu, M68kWaitBusCallback callback);

Called before each memory/fetch bus access. The callback receives the 24-bit address, access size, and a write flag, and returns extra cycles to deduct for bus contention or wait states.

void m68k_set_int_ack_callback(M68kCpu* cpu, M68kIntAckCallback callback);

Called when an interrupt is acknowledged. Return vector number, M68K_INT_ACK_AUTOVECTOR, or M68K_INT_ACK_SPURIOUS.

void m68k_set_fc_callback(M68kCpu* cpu, M68kFcCallback callback);

Called before bus/program accesses with the active FC value.

void m68k_set_instr_hook_callback(M68kCpu* cpu, M68kInstrHookCallback callback);

Called before each instruction decode/execute (not during STOP-idle cycles).

void m68k_set_pc_changed_callback(M68kCpu* cpu, M68kPcChangedCallback callback);

Called when PC changes through m68k_set_pc.

void m68k_set_reset_callback(M68kCpu* cpu, M68kResetCallback callback);

Called by execution of the RESET instruction. This is separate from m68k_reset().

void m68k_set_tas_callback(M68kCpu* cpu, M68kTasCallback callback);

Called by TAS; non-zero return allows write-back, zero blocks write-back.

void m68k_set_illg_callback(M68kCpu* cpu, M68kIllgCallback callback);

Registers an illegal-opcode callback pointer. The callback fires before the illegal-instruction exception (vector 4) is taken, and receives the offending opcode. A nonzero return claims the instruction: the exception is suppressed and execution continues after the opcode. A zero return lets the exception proceed. Line-A and line-F opcodes take vectors 10 and 11 without invoking this callback.

Host Memory Callbacks

  • void m68k_set_read8_callback(M68kCpu* cpu, M68kRead8Callback callback);
  • void m68k_set_read16_callback(M68kCpu* cpu, M68kRead16Callback callback);
  • void m68k_set_read32_callback(M68kCpu* cpu, M68kRead32Callback callback);
  • void m68k_set_write8_callback(M68kCpu* cpu, M68kWrite8Callback callback);
  • void m68k_set_write16_callback(M68kCpu* cpu, M68kWrite16Callback callback);
  • void m68k_set_write32_callback(M68kCpu* cpu, M68kWrite32Callback callback);

Use these to route memory access to a host bus implementation (for mapped IO/peripherals or custom memory models). Pass NULL to disable a callback and fall back to default flat-memory behavior for that access width.

Context Save/Restore

unsigned int m68k_context_size(void);

Returns context blob size in bytes.

void m68k_get_context(M68kCpu* cpu, void* dst);

Copies CPU context into dst (m68k_context_size() bytes).

void m68k_set_context(M68kCpu* cpu, const void* src);

Restores context from src, while preserving destination-instance runtime bindings:

  • memory pointer and memory size
  • internal fault trap storage
  • installed callbacks, including the host memory read/write callbacks

size_t m68k_serialize(const M68kCpu* cpu, u8* buffer, size_t capacity);

Serializes architectural CPU state into a portable save state. Returns the number of bytes written, the required size when buffer is NULL, or 0 when the buffer is too small. The format is versioned, tagged, and big-endian, so blobs are stable across builds, compilers, and host architectures. Host bindings and transient fault latches are not serialized; serializing in the middle of exception processing is not supported.

bool m68k_deserialize(M68kCpu* cpu, const u8* buffer, size_t length);

Restores architectural CPU state from a portable save state, keeping the destination's memory binding and callbacks. Returns false when the data is malformed, truncated, or has an unsupported version. Fields with unknown tags are skipped, so states written by newer library versions restore their known fields.

Loader API (loader.h)

bool m68k_load_srec(M68kCpu* cpu, const char* filename);

Loads Motorola S-record data into memory. Returns false only when the file cannot be opened. Malformed records, including records with checksum mismatches, are reported to stderr and skipped. Data bytes are written directly into bound flat memory; loading does not run emulated bus cycles, invoke host memory callbacks, or raise bus errors. When a record reaches an address outside bound memory, the first out-of-range byte is reported to stderr, the rest of that record is skipped, and parsing continues with the next record. Entry-point records (S7/S8/S9) set the program counter through m68k_set_pc, so the PC-changed callback fires.

bool m68k_load_bin(M68kCpu* cpu, const char* filename, u32 address, u32* size_out);

Loads raw binary bytes into memory starting at address. Returns false only when the file cannot be opened. Bytes are written directly into bound flat memory; loading stops at the first out-of-range byte, which is reported to stderr. When size_out is not NULL, it receives the number of bytes written into emulated memory, or 0 when the file cannot be opened. A reported size smaller than the file size indicates the load stopped at the end of bound memory.

bool m68k_load_ihex(M68kCpu* cpu, const char* filename);

Loads Intel HEX data into memory. Returns false only when the file cannot be opened. Data records honor the extended segment and extended linear base records, and start address records set the program counter through m68k_set_pc. Malformed records, including records with checksum mismatches, are reported to stderr and skipped.

Disassembler API (disasm.h)

int m68k_disasm(M68kCpu* cpu, u32 pc, char* buffer, int buf_size);

Disassembles one instruction at pc into buffer. Returns number of bytes consumed by that instruction. Disassembly is side-effect free: it does not charge wait states or cycles, and it does not raise address or bus errors.

Version

ROCKET68_VERSION_STR

Semantic version string in include/rocket68.h.