Oricutron
To access Oricutron's debugger you need to press the F2 key. This will show you this screen:
In the monitor, number arguments are decimal by default, or prefixed with $ for hex or % for binary. Pretty much everything is output in hex.
In most places where you can enter a number or address, you can pass a CPU or VIA register. (VIA registers are prefixed with V, e.g. VDDRA). Anywhere you can pass an address, you can also use a symbol.
To use Oricutron's debugger, you need to know some keys:
- F2: Return to the emulator
- F3: Toggle console/debug output/memwatch
- F4: Toggle VIA/AY information
- F9: Reset cycle count
- F10: Step over code
- F11: Step over code without tracing into subroutines.
- F12: Skip instruction
Since OSDK 2.0, Oricutron also embeds a GDB compatible debug stub. Instead of using the built-in monitor described above, an external debugger can connect to Oricutron over TCP and drive it using the standard GDB remote protocol: set and clear breakpoints, single step, run and halt, and read or write both memory and CPU registers.
The stub is enabled by giving Oricutron a port to listen on:
oricutron --gdb_port 6502 mygame.dsk
This is what the Visual Studio Code extension uses to offer source level debugging of Oric programs. Combined with a program built using OSDKDEBUG=-g1, which makes the compiler emit source line and type information, and the extended symbol file produced by the assembler, the debugger can show you C source lines and typed variables rather than raw disassembly.
There is also a KVM protocol (Keyboard and Video, there is no mouse on an Oric), which exposes the emulated screen buffer and accepts keyboard input, so external tooling can display the running program and interact with it.
You also have some more advanced commands:
- ? : Help
- a [addr] : Assemble
- bc [bp id] : Clear breakpoint
- bcm [bp id] : Clear mem breakpoint
- bl : List breakpoints
- blm : List mem breakpoints
- bs [addr] : Set breakpoint
- bsm [addr] [rwc] : Set mem breakpoint
- bz : Zap breakpoints
- bzm : Zap mem breakpoints
- d [addr] : Disassemble
- fd [addr] [end] [file]: Disassemble to file
- fw [addr]
[file] : Write memory to file - fr [addr] [file] : Read file to memory
- m [addr] : Dump memory
- mm [addr] [value] : Modify memory
- mw [addr] : Memory watch at addr
- nl [file] : Load snapshot
- ns [file] : Save snapshot
- r [reg] [value] : Set a value to a register
- q, x or qm : Quit monitor
- qe : Quit emulator
- sa [name] [addr] : Add or move user symbol
- sk [name] : Kill user symbol
- sc : Symbols not case-sensitive
- sC : Symbols case-sensitive
- sl [file] : Load user symbols
- sx [file] : Export user symbols
- sz : Zap user symbols
Upstream Oricutron has been called version 1.2 since November 2014. Development moved to git and releases are now identified by commit hash, which makes it impossible to tell which version was released when. The build shipped with the OSDK therefore uses its own scheme, and names itself after its compile date instead:
Oricutron 2026.07.25 OSDK (SDL1)
That string appears in the title bar and in the "About Oricutron" dialog. It tells you the compile date, that this is the OSDK variant rather than an upstream build, and which major version of SDL it was linked against. Please quote it when reporting a problem. Upstream builds are unaffected and keep reporting 1.2.
The window title can be replaced with the --title option, so that each window says what it is running. That matters when you have a lot of them open at the same time, a test bench for instance, where otherwise every window looks identical:
oricutron --title "Playing Encounter" mygame.dsk
It can also be changed while the program is running, through the debug stub. Only the window title changes, the "About Oricutron" dialog keeps reporting the build identity above.
Issue #34: Tap file that crash on first load but not on second:
Details: This does not happen for all program files but sometimes Oricutron will not properly execute a loaded .tap file and instead display the Monitor window showing the PC stuck at address $24D. When using the monitor to examine disassembled memory, the code is correctly present at address $600.
When that happens, issuing a RESET from Oricutron and typing manually CLOAD"" and re-inserting the proper .tap file is enough for the program to run normally.
For some reason, the first run always fail as described above but after a reset everything works as expected.
As noted, this happens only for one of my program, a 23,370 bytes long .tap file.
I can provide that .tap file and associated symbols file if needed.
Fixed in OSDK 1.12
Details: If the project is not located on the same drive as the OSDK; Oricutron will fail to launch because osdk_oricutron.bat does not point it to the right location. Using START /d "%OSDK%\Oricutron" %OSDKORICUTRON% instead fixes it.
comments powered by Disqus
