BitMagic The Complete Development Environment for the Commander X16.

Debugging

See More

Once you press F5, BitMagic behaves like any other VSCode debugger: stepping, breakpoints, disassembly, memory and jump to cursor, all covered below. Its own views, like the memory and layer viewers, are on The Debugger.

Launch configuration

A session is configured the same way as any VSCode debugger: a type: bmasm entry in the workspace’s .vscode/launch.json. See The launch config for its properties and how to add one. debugArgs takes the same flags as the standalone emulator, for example ["--warp"].

Build errors

If a build fails, the compiler’s errors appear as problems in the editor (a red marker on the offending line and an entry in the Problems panel), with the full log in the BitMagic output channel.

Stepping

Continue, step over, step into and step out all work against your .bmasm source lines, including code generated by the template engine. Where a line generated multiple instructions, stepping walks the instructions. The exception is code built up in a string variable and output as a block: it steps into a separate generated file instead of the original lines, see Multiline Template Code.

Breakpoints

  • Source breakpoints: click the gutter next to a line.
  • Conditional, hit-count and logpoints: see Watches and Breakpoints.
  • Function breakpoints: not a named procedure, but a call typed into VSCode’s function breakpoint box. vram(0x1b000) breaks on any read or write to that VRAM address; add a second address for a range, and "R", "W" or "RW" to limit the direction, for example vram(0x1b000, 0x1b200, "W"). vsync() breaks on the next frame, and vsync(100) on a specific frame number.
  • Instruction breakpoints: set in the disassembly view.
  • Exception breakpoints: three filters in the Breakpoints panel. Code Exception fires when an .exception directive is hit (on by default), File IO Exception when a LOAD call returns an error code (on by default), and BRK Hit when a BRK instruction executes (off by default).
  • Startup breakpoints: the breakpoints array in the project file is a list of addresses to break on as soon as the machine starts.

Disassembly

Open the disassembly view to step through raw instructions, including ROM code. Symbols from the symbols files and jump tables are applied, so KERNAL calls show by name.

Memory

The Variables pane exposes CPU.Ram, VERA.VRam, the RAM and ROM banks, and the SD card as memory blocks. VSCode’s hex editor can open any of them, and memory is writable while paused. The same memory can be read as typed values in an expression, for example CPU.Ram[0x0000].Short; see Watches and Breakpoints.

Jump to cursor

“Run to cursor” and setting the next statement are supported; the CPU’s PC is moved to the chosen line.

Not available

VSCode’s native data breakpoints (right-click a variable and choose Break on Value Change) aren’t supported; a vram() function breakpoint covers the VRAM case. Editing a value directly in the Variables pane isn’t supported either; use the hex editor instead.

Running in the official emulator

The command Run Project In The Official Emulator builds the project and runs it in the official X16 emulator instead of BitMagic’s. This is useful for checking behaviour against the reference implementation. It needs the official emulator, which the extension can download for you (see Settings).