Intuition Engine

Three instruction sets for Amiga software

The 68020 and 68881 run AmigaOS with Alice, Lisa, Paula and the CIAs. A PowerPC 604e board runs alongside it, with powerpc.library and its PowerPC kernel supplied in the IE extended ROM for WarpOS programs.

The Amithlon compatibility layer loads Amithlon relocatable i386 ELF modules through AmigaDOS and connects x86 code to 68K library calls and callbacks. The modules run on IE's x86 CPU core with JIT compilation, not directly on the physical CPU. Extended-ROM services handle native library functions, task and process entry, interrupt servers and audio hooks. The ROM supplies amithlon.resource and umilator.resource interfaces, plus powerpci.library and atirq.resource for PCI access and interrupts. This is an Amiga application interface, not a loader for arbitrary x86 executables.

AmigaOS 3.1 is the tested system for Amithlon compatibility. The x87 uses 64-bit floating-point arithmetic, not full 80-bit precision. SSE, SSE2 and 3DNow! arithmetic are not supported. Physical audio playback through an EMU10K card has not been tested.

IE Mon inspects the Amithlon x86 registers and code and identifies calls across the 68K/x86 interface. Amiga programs can combine these instruction sets with the wider IE hardware, its sound engines and its worker CPUs.

8 MiB chip RAM and almost 1.75 GiB fast RAM

The Amiga system provides 8 MiB of chip RAM by default, with 2 MiB and 4 MiB configurations also supported. On the appliance, fast RAM can reach almost 1.75 GiB, subject to available backing memory and configuration.

The extended ROM makes this memory available to AmigaOS. Use it for larger pictures, samples, programs and working buffers.

Give the work to another processor

Amiga programs can submit jobs to the IE coprocessor service and receive completion notifications through Amiga interrupts and Exec signals. The machine has ten worker instances across IE64, IE32, 68020, Z80, 6502, x86 and PowerPC. The Amiga system controller uses IE64 instance 0, leaving nine for Amiga programs.

Use a 64-bit IE64 worker for calculations, a 6502 for a sound routine or another 68020 for rendering. Workers share memory and devices with the caller. See the worker model.

Amiga graphics and Voodoo on one machine

Use Alice and Lisa for bitplanes, sprites, HAM6, HAM8, Extra Half-Brite, AGA palettes, the Amiga blitter and copper, and genlock. The IE Picasso96 board driver adds the IE framebuffer and accelerated drawing. Picasso96 also provides CyberGraphX API compatibility for applications.

The ROM supplies separate 68K and PowerPC Warp3D hardware and graphics drivers for the Voodoo. These provide hardware-accelerated textured 3D through Warp3D, with GPU rendering through Vulkan on the live appliance. Programs can also control the IE 3D registers directly with the SDK headers.

Paula, AHI and the IE sound engines

The extended ROM carries AHI itself, the IE audio driver, audio modes and preferences, and the AUDIO: handler. The CAMD driver connects Amiga MIDI software to the internal synthesiser or configured external MIDI devices.

iesound.library opens the IE sound engines to Amiga programs: PSG, SN76489, three SIDs, POKEY, TED, AHX, MIDI, MOD and WAV. The library provides engine claims and, where supported, tune playback, subsong selection and playback status or position. It checks channel use against Paula and other sound-engine claims.

Another copper and Mode 7

iecopper.library controls the IE copper, whose lists can change registers on different chips across the bus. iemode7.library provides affine texture rotation and scaling through the IE blitter.

Drive other video chips from AmigaOS

Claim TED, ANTIC, ZX Spectrum ULA and Voodoo display layers from an Amiga program. ULA and Voodoo sit above Lisa in the fixed display stack. TED and ANTIC sit below it and can show when Lisa's output is disabled or through areas made transparent by genlock.

ielayers.library reports the layer order, register addresses and visibility relative to Lisa. Ask IELayers_Base for a chip's register address, then program it directly through the Amiga's IE register mirror at 0x01F00000. The library coordinates claims between callers; it does not draw the chip's display or enforce exclusive hardware access. IE VideoChip, VGA and Lisa are not available to claim.

Add a scrolling text console over the Amiga chipset or RTG display without changing its bitmap. Choose the position, ink and paper colours, and up to 80 by 32 cells in the system's default font. The chosen font, dimensions and position must fit within a 640 by 512 pixel area. One console can be open at a time. IELayers_ConsoleBuffer gives your program the RGBA buffer for a custom graphical overlay as well as text.

For textured Voodoo rendering, upload pixels from guest RAM through the chip's registers. IELayers_Memory does not expose direct access to its texture-memory aperture. The SDK for AmigaOS includes the layer and genlock examples.

Modern gamepads, Amiga game ports

Use modern gamepads with Amiga software through the Amiga hardware registers. The IE gamepad system supplies joystick directions and fire buttons, analogue readings and the seven-button CD32 controller protocol. The first gamepad feeds Amiga joystick port 1; port 0 keeps the mouse.

The extended ROM also supplies mouse-wheel and fourth-button events through the NewMouse convention for Amiga software that supports it.

New IE games can read up to four controllers directly, with a common button layout and both analogue sticks. BASIC, assembly and C use the same gamepad interface on the appliance and in the browser.

See the four-controller interface.

Sockets, Ethernet, USB and external devices

On the appliance, Amiga software can use the supplied bsdsocket.library or a separate Amiga TCP/IP stack through the SANA-II network device. The default network relay provides the device's connection. The machine checks the system directory for an installed stack and can disable its own socket library to let that stack provide the service.

The ROM also supplies openpci.library, the Poseidon hardware driver ieusb.device for the OHCI USB controller, and gpio.library for pin input, output and edge detection.

Use the appliance's device menu to select available USB, MIDI and serial devices. The GPIO and PCI interfaces are implemented, but physical GPIO and PCI passthrough are not enabled by the standard appliance setup.

Disks, CDs, clock and ports

Boot and work from floppy images, hardfiles, directory volumes and CD images. The extended ROM supplies hard-disk and directory-volume services, iecd.device and CD filesystem support. Gayle provides the IDE register interface. The machine also provides a battery-clock interface, CD audio, printer output, serial links and parallel-port sampling.

On the appliance, supported physical optical drives can also serve Amiga software through iecd.device. SCSI command passthrough lets programs send commands to a configured drive.

IE Mon inspects the CPUs and devices, steps through code and records reverse history. Whole-machine saves and IEScript automation use the same machine. The ROM also contains a clipboard driver, but Amiga clipboard integration is disabled in the standard appliance setup.

Akiko, CD audio and persistent NVRAM

Akiko provides chunky-to-planar conversion, a CD controller with DMA and interrupts, and non-volatile storage saved in cd32.nvram. ISO images supply data discs; CUE/BIN images can carry data and CD audio tracks.

The ROM menu accepts a user-supplied CD32 Kickstart and extended-ROM pair, or a combined ROM image. The IE driver ROM remains separate. These hardware features do not imply compatibility with every CD32 game.

Change media, save and reset

Press Ctrl+End to open the Amiga controller menu. Select ROMs by filename, change floppy and CD images, set floppy write protection, and adjust machine speed and the CPU instruction rate. On the appliance, device pages select available USB, serial, MIDI, disk, parallel and CD devices. Some changes take effect at the next launch.

Press Ctrl+F9 to save the machine and Ctrl+F8 to load it. A save or load can be refused while Amithlon native state is live. See the snapshot limits before relying on a save.

For an Amiga warm reset, hold Ctrl and both Amiga keys, mapped to the left and right Meta keys. F10 performs an engine hard reset to BASIC. Save your work before either reset.

Write software for the whole machine

The AmigaOS SDK supplies 16 IE-specific C headers, five WarpOS headers, the public hardware register header and ie68.inc. They cover graphics, sound, copper, Mode 7, layers, coprocessors, PowerPC, sockets, networking, clipboard, MIDI, GPIO, PCI and USB.

Five C examples demonstrate sound, display layers, copper lists, Mode 7 and genlock. Build the examples with vbcc and a separate AmigaOS NDK. The IE libraries and drivers come with the extended ROM.

Download the SDK for AmigaOS

Five milestones to start with

Start with these five projects:

1. First command: Chapter 1 starts you at the Ready prompt.
2. First picture on screen: Chapters 3 and 4.
3. First moving effect: Chapter 47, Your First Frame Loop.
4. First effect locked to music: Chapter 54.
5. First complete intro: Chapter 56.

Everything between the milestones is optional.

The full reference underneath

The same book documents all seven CPU architectures, the video and sound chips, the memory model and MMIO maps, timing and traps, coprocessors, IE Mon and IEScript. Part VIII covers a full game port. Part IX covers Alice, Lisa, the Amiga blitter and copper, CIA timers and Amiga peripherals. Twelve appendices hold the tables you will keep open while you code.

Chapter 55 shows how the blitter can change a copper instruction before the copper reads it. Chapter 52 develops the stopped-CPU rotozoomer. Chapter 68 builds a HAM8 colour strip from BASIC and explains how to convert an RGB picture into HAM8 bitplanes.

Common ranges

SYSINFO publishes RAM and feature bits. File I/O adds the IE64 FILE_DATA_PTR64 extension. Media load, Program Executor, terminal, keyboard, mouse and USB gamepad input, CPU wait, shared network sockets, Voodoo apertures, Bootstrap HostFS, and the gated host-command helper map as bus services. On the appliance, the socket block gives machine-language programs IPv4 TCP and UDP in recognised non-BASIC modes. These socket services are not available in the browser build.

From BASIC, HOST NET configures WiFi, HOST UPDATE updates the installed appliance packages from the signed Intuition Engine repository, verifying the engine checksum and version and restoring the previous binary if validation or the restart check fails, and HOST REBOOT and HOST POWEROFF restart or shut it down.

SYSINFO_EXIT at 0xF241C lets a guest request the end of the machine run with a signed 32-bit exit status.

Four controllers, one interface

Build games for up to four gamepads on the appliance or in the browser. Controllers with a recognised standard layout use the same button bits and stick axes, so your program reads a common layout across controller models. Each pad provides 17 button bits, including the four directional buttons, and two analogue sticks with four signed 16-bit axes.

From BASIC, PAD(n) reads the button bits. PADX(n) and PADY(n) read the left stick, and joydefs.bas supplies the button names. Assembly and C programs read the same state through the CPU's mapped gamepad registers. The browser build receives input through the browser Gamepad API.

The read-only block at 0xF25C0-0xF25FF reports connected pads and their count. Four twelve-byte records begin at 0xF25D0, each holding the button bits and both sticks. The Amiga system also maps gamepads to its joystick ports and CD32 button protocol.

Mouse buttons and wheel input

Guest programs can read four mouse buttons through MOUSE_BUTTONS at 0xF0738. Vertical wheel steps use 0xF0764; horizontal steps use 0xF0768. Each wheel register returns a signed count and clears it on read. The status register at 0xF076C reports pending steps without consuming them. Use the CPU's mapped register addresses for banked or mirrored access.

Amiga device interfaces

The Amiga profile adds a SANA-II Ethernet interface at 0xF2A80, PCI configuration registers at 0xF2B00 and the native Gayle IDE block at 0xF7640. The 68020 uses the IE aperture mirror for these addresses. Device presence and physical access depend on the configuration.

The clipboard bridge occupies 0xF2390-0xF23AF. Its Amiga driver is disabled in the standard appliance setup.

Random data and GPIO

The entropy block at 0xF2A00-0xF2A0F supplies random bytes from the host. GPIO registers at 0xF2A10-0xF2A7F provide pin input, output and edge detection when a GPIO device is configured. Check the SYSINFO feature bits before use. GPIO outputs are limited to the pins the host permits. BASIC provides GPIO MODE, GPIO EDGE and GPIO(pin). The standard appliance setup does not enable physical GPIO.

Profile bridges

AROS maps DOS packets, Paula-style audio DMA, clipboard access, IRQ diagnostics, and live MIDI through a CAMD driver (DEVS:Midi/ie) under camd.library. It also supplies guest-side integration for the shared network-socket block. EmuTOS uses an Atari MIDI ACIA shim that feeds the live-MIDI engine.

The native SoundChip synthesiser

The native SoundChip provides ten FLEX voices and 32 SFX sample channels. Each FLEX voice has its own oscillator (square/pulse, triangle, sine, sawtooth and nine noise modes), ADSR envelope, sweep, PWM, ring modulation, hard sync and signed 8-bit DAC input. The mixed signal passes through overdrive, a global filter and reverb, followed by auto-levelling, compression and limiting.

It also carries RawlandMini, a built-in GM-style patch table, so Standard MIDI Files, Doom MUS and live MIDI play straight through the chip across 16 MIDI channels and 10 active voices, with GM-style instrument families and a drum channel.

FLEX ch0-3   0xF0A80-0xF0B7F
SID2 ch4-6   0xF0C40-0xF0CFF
SID3 ch7-9   0xF0D40-0xF0DFF
SFX ch0-31   0xF2600-0xF29FF

Separate chip clocks

Final output renders at 44100 samples per second with global filter, overdrive, reverb, and limiting. PSG defaults to 2000000 Hz. SN76489 uses 3579545 Hz NTSC and 3546893 Hz PAL; SID uses 985248/1022727 Hz; TED audio runs at 110840/111860 Hz; Paula/MOD period timing uses 3546895 Hz.

SoundChip/SFX mixer   44100 Hz
AHX song ticks         50/100/150/200 Hz
MOD and Paula periods  3546895 Hz source clock
WAV and MIDI/MUS       parsed, scheduled, mixed

Live MIDI

Live MIDI maps a byte-stream port on MachineBus. EmuTOS reaches it through an output-only Atari ACIA bridge. AROS and the Amiga profile provide a CAMD driver, DEVS:Midi/ie. In the Amiga profile, output plays through the internal synthesiser by default; external MIDI input and output require a configured MIDI device on the appliance. IntuitionOS does not yet have a MIDI driver.

Cadences and compositing

The CPUs, 60 Hz compositor and 44.1 kHz audio mixer run separately. The compositor combines video layers into one frame. Each layer has its own dimensions, position and opacity. Several of the real chips can be on screen at once, each on its own layer.

CPU state, live

IE Mon switches focus between registered CPUs and disassembles all seven instruction sets, including PowerPC 604e. It single-steps one core while the rest stay frozen, or thaws chosen cores to run alongside it, evaluates address expressions such as pc+$20, interleaves source when available, sets conditional breakpoints, intercepts faults, and assembles one IE64 instruction at an address.

cpu
r
d /s pc 8
b main+0x10 if R1==$10 && hitcount>2
s
g

Memory and MMIO traces

SoftICE-style bpm* watchpoints cover byte, word, long, and quad accesses in read, write, or read/write mode. Page guards, access logs, who, bfirst, and trace mmio identify bus activity from recorded access data. A built-in hex editor edits memory in place, memory regions export to and import from disk, and a stack-trace command shows the call chain.

bpmqw $f0000
pg add $f0000 $f0fff rw cpu=current
accesslog on 1024
who wrote $f0004
trace mmio mmio 16

Back through snapshots

rs restores the focussed CPU from local step history. rg, rt, tl, and history horizon use retained whole-machine snapshots for registered CPUs, bus RAM, sparse IE64 backing pages, and versioned device blobs. A whole-machine restore reports any missing registered device rather than passing over it in silence.

history horizon
tl 12
rg
rt PC==$2000
ss checkpoint.ie64state
sl checkpoint.ie64state

ss and sl save and load CPU-local snapshots. Use sm and lm for a file containing guest CPU state, RAM and registered device state:

sm checkpoint.iems
lm checkpoint.iems

A whole-machine load checks the machine profile, RAM configuration and media. Keep the required disk images with the save; changed or incompatible media can prevent a load.

External connections are not restored. Restoring the Amiga network interface drops existing connections. Saves and loads are refused while Amithlon native state is live or a physical PCI device is assigned to the Amiga.

Named register groups

io reads named I/O views at native width: audio, video, SYSINFO, cpu_wait, Voodoo, live and player MIDI, and other MMIO devices. Trusted .iemonrc files, aliases, macros, scripts, and the IEScript dbg.* API reuse those machine monitor commands.

io all
io sfx
io voodoo
rc list
rc trust .iemonrc
macro frame d pc 8; r

Press F9

Press F9 to freeze the running machine, including every CPU and the current audio state. IE Mon then opens over the frozen display. Press Esc to close the machine monitor and resume execution.

Names and source lines

IE Mon loads symbols for guest binaries and shows source lines alongside disassembly: VICE label files, .iesym sidecars and ELF symbol tables, kept per CPU and rebased to the load address. Drop a .lbl beside a SID, AY, MOD or PRG and it loads on its own, so a raw retro binary disassembles with real names.

Script launch paths

.ies files run from BASIC with RUN "demo.ies", through Program Executor dispatch, or from the F8 IEScript REPL overlay. Frame and timer waits provide synchronisation points.

RUN "demo.ies"

Frames, hashes, recordings

Scripts can wait for frames, pixel colours, unchanged frame hashes or conditions you define. Use these checks to capture and compare output; they do not guarantee identical timing or pictures across runs. Scripts can select flat, curved or off CRT presentation, and fit or stretch scaling. They can capture either the composed guest image before CRT and host overlays or the final displayed frame after presentation. Screenshots need no external tools. MP4 recording with audio requires FFmpeg.

sys.wait_frames(2)
video.wait_stable(3, 120)
hash = video.frame_hash()
video.set_crt_mode("curved")
rec.screenshot_composed("guest.png")
rec.screenshot_screen("screen.png")
rec.start_screen("run.mp4")
rec.stop()

MMIO from IEScript

IEScript reaches memory and MMIO directly, plus dedicated modules for each chip: PSG, SID, TED, POKEY, AHX and MIDI on the audio side, and VGA, ULA, ANTIC, GTIA, TED and Voodoo, with the copper and blitter, on the video side. It also injects keyboard input through term.key_press with the keys scancode table, and mouse movement and clicks through term.mouse_press and term.mouse_click. The shipped rotozoomer script stages data with mem.write_block, writes VideoChip and blitter registers, and starts MIDI through MMIO.

cpu.freeze()
mem.write_block(texturePtr, texture)
cpu.resume()
video.write_reg(983040, 1)
video.blit_fill(1048576, 320, 200, 255, 1280)
video.blit_wait()

Automate an Amiga session

media.cd_insert, media.cd_eject and media.cd_status change and inspect CD media. media.hdf_eject, media.hdf_insert and media.hdf_status remove, reconnect and inspect a hardfile unit backed by an attached physical block device. They do not select a new hardfile image.

term.raw_key sends a press and release to the guest's raw-key queue. For the Amiga, it takes Amiga rawkey codes. audio.output_rms measures the recent mixed sound level; audio.output_rms_lr measures each stereo channel. Scripts can check sound as well as pictures.

Machine monitor API

With dbg, scripts open the machine monitor, step or continue, set breakpoints and watchpoints, add page guards, intercept faults, read registers and memory, disassemble and trace, inspect I/O views, snapshot devices and switch between CPUs. dbg.save_machine("checkpoint.iems") and dbg.load_machine("checkpoint.iems") save and restore the whole machine, with profile and media checks on load. CPU-local snapshots remain available separately. Raw RAM access requires an explicit freeze; MMIO access does not. cpu.jit_stats() reports statistics for the selected CPU across all seven architectures, including native execution, fallbacks, invalidations and cache activity where recorded.

dbg.open()
dbg.set_bp(0x2000)
dbg.step()
regs = dbg.get_regs()
io = dbg.io("midilive")
snap = dbg.device_snapshot("video")
dbg.close()

Compiler and transpiler

RUN AOT
COMPILE "name"
TRANSPILE "name"
ASSEMBLE "name"

RUN AOT compiles the stored program to native IE64 code and runs it straight away. COMPILE writes a standalone .ie64 image with a matching assembly listing. TRANSPILE emits IE64 assembly text on its own, and ASSEMBLE turns that source back into a flat image. COMPILE rejects direct-mode-only commands and stored forms a standalone image cannot support.

Hardware from BASIC

10 POKE32 &H000F0800,1
20 SOUND 0,440,200,0,128
30 ENVELOPE 0,50,100,200,100
40 GATE 0,ON
50 VSYNC

BASIC controls the mixer, FLEX voices, envelopes, frame timing, blitter, sprites, tiles, Voodoo, files and media players.

Audio from BASIC

Direct BASIC audio covers SOUND, envelopes, filters, waveform/noise control, chip-specific commands such as PSG, SID, POKEY, and TED, plus raw SFX POKE32 writes.

SOUND PLAY "TITLE.MOD"
SOUND PLAY "INTRO.SID",0
SOUND PLAY "TUNE.AHX",1
SOUND PLAY "SONG.MID"

SDK and debug tools

The live image carries the full Host SDK archives and checksums under SDK/Toolchains. They are the supported downloads for the first-party assemblers, converter and IE64 C toolchain. IE Mon supplies the debugger.

Host SDKs

C is not limited to IE64. You can use a freestanding C compiler that targets 68020, Z80, 6502, 32-bit x86 or PowerPC 604e, provided you link or convert its output to the flat image format expected by that CPU: .ie68, .ie80, .ie65, .ie86 or .ieppc. The SDK supplies the public intuitionengine.h hardware header for video, audio, media, input, file, network, coprocessor and Voodoo access, with compiler-specific target support. IE32 is the only CPU without a C compiler target.

Each Host SDK includes ie64-cproc, a freestanding C23 toolchain for the ie64-unknown-none target. It uses cproc, QBE and Picolibc, with the V3 IE64 ABI, scalar floating point, static archives and C atomics. It is not a hosted POSIX environment and does not provide dynamic linking, threads or C++.

ie64-cproc -o demo.ie64 demo.c

Copy demo.ie64 to the machine's file area, then type this at the BASIC prompt:

RUN "demo.ie64"

The downloadable Linux x86-64, Linux ARM64 and Windows x86-64 Host SDKs include ie32asm, ie32to64, ie64-cproc, QBE, ie64asm, ie64dis, ie64ld, ie64-ar, ie64-ranlib, headers, documentation and the bare-metal libraries. They also include Amiga development headers under include/amiga, including WarpOS headers. Amiga library calls use vbcc; headers that include AmigaOS definitions require the separate AmigaOS NDK.

SDK for AmigaOS

Write AmigaOS programs for the IE hardware and extended-ROM services. The .lha contains 16 IE-specific C headers, five WarpOS headers for tasks, memory, ports and semaphores, intuitionengine.h and ie68.inc.

The headers cover 3D and Warp3D, Picasso96, sound, copper, Mode 7, display layers, coprocessors, PowerPC, sockets, networking, clipboard, MIDI, GPIO, PCI and USB. Five example programs demonstrate sound, layers, copper, Mode 7 and genlock, with a vbcc Makefile.

The kit supports vbcc. Supply the compiler and AmigaOS NDK separately. The IE libraries and drivers come with the extended ROM.

Unpack the archive into SYS: to create SYS:IE-SDK. Add the supplied S/User-Startup-IE lines to S:User-Startup to define IE: and add IE:Include to the include path. The kit is supplied under GPL-3.0-or-later; its licence is in Doc/LICENSE.

Native assembly for all seven CPU architectures

Every CPU architecture has a hardware-definition include: ie32.inc and ie64.inc for the IE cores, and ie65.inc, ie68.inc, ie80.inc, ie86.inc and ieppc.inc for 6502, M68K, Z80, x86 and PowerPC. IE32 and IE64 use ie32asm and ie64asm. The other targets use ca65, vasm or NASM, with the PowerPC version of vasm for .ieppc images.

ie64dis disassembles IE64 and ie32to64 translates IE32 source towards IE64. Both are included in the Host SDK with the relevant documentation.