Debugging emulator

Prepare the workspace and build the program

Follow this wiki page and the build wiki page

Create a debug configuration and debug !

Copper debugging

You may debug the copper list like a normal assembly program and add breakpoints. Some fs-uae internals make the stepping jump over some lines, and the breakpoints may be hit after the selected line.

Change the type of variables display

You may change the format used to display of the variables.

Add a memory watch breakpoint on WinUAE

You may add a breakpoint on memory read, write or read/write access. The address used is the symbol location or the address pointed by a register. An input field will help you to set the size of the memory location watched.

Add a conditional breakpoint

Right click on the line where you want to set the breakpoint and select 'Add conditional breakpoint...'. You can also create log points from this menu.

Enter an expression to be evaluated to determine whether the breakpoint should apply. This can include register names, symbols and standard operators. Numbers can be decimal (default), hex ($ or 0x), binary (% or 0b) or octal (@ or 0o).

Execution will stop when the condition is met.

Add a logpoint

Logpoints are like breakpoints, but they output text instead of stopping the program, a bit like doing print debugging using console.log etc. The text can include expressions:

You can see the output in the debug console:

Memory edition

Memory can be edited from the addresses in the variables.

Debugger commands

• '$' is used for the address of a symbol
• '#' is used for the address pointed by a symbol

Memory dump

• m address, size[, wordSizeInBytes, rowSizeInWords, ab] with a: show ascii output, b: show bytes output

  example: m $5c50,10,2,4

• m $|#{register|symbol}, size[, wordSizeInBytes, rowSizeInWords]

  example: m ${mycopperlabel},10,2,4

Disassembled Memory

• m address|$|#{register|symbol},size,d

  example: m ${pc},10,d

---

Example

if copperlist is a symbol indicating address $1fc (after program load) and containing value $5f0.

copperlist:   DC.L        $5f0

There is different ways to set the starting address of a memory dump:

• using the memory address: m 01fc,300, 2, 5 will dump starting at $01fc
• starting with ${copperlist}: will dump using starting at copperlist address (position of the symbol in memory) -> $1fc
• starting with #{copperlist}: will dump using starting at copperlist value (value of the copperlist symbol in memory -> $5f0

To have the memory grouped by 2 bytes with 5 groups by line:

m #{copperlist},300, 2, 5

This will display:

>01fc 0000 0100 0200 0180 | .ü........
     00005850:01fc 0000 0100 0200 0180 | .ü........
     0000585a:0349 2b07 fffe 0180 056c | .I+.ÿþ...l
     00005864:2c07 fffe 0180 0113 8007 | ,.ÿþ......

---

The memory dumps commands can be added to the WATCH view

It will display the updates in real time

Symbols addresses will be dumped in the hover or can be added to the watch view. Adding an address register to the watch view will dump the contents.

These dumps can be customized in the settings

setting	description
Display › Memory Format: Hover	Default format 'm ${symbol},24,2,4' for a memory dump in hover ('symbol' is replaced)
Display › Memory Format: Watch	Default format 'm ${symbol},104,2,4' for a memory dump in watch ('symbol' is replaced)

Set Memory

• M address=bytes example: M $5c50=0ff534

• M ${register|symbol}=bytes example: M ${mycopperlabel}=0ff534

Launch configurations

The debugger communicates with the emulator with tcp/ip socket.

Example for FS-UAE

{
    "version": "0.2.0",
    "configurations": [
        {
            "type": "amiga-assembly",
            "request": "launch",
            "name": "FS-UAE Debug",
            "stopOnEntry": true,
            "trace": true,
            "program": "${workspaceFolder}/uae/dh0/gencop",
            "remoteProgram": "SYS:gencop",
            "emulatorType": "fs-uae",
            "emulatorArgs": [
                "--hard_drive_0=${workspaceFolder}/uae/dh0",
            ],
            "preLaunchTask": "amigaassembly: build"
        }
    ]
}

Example for WinUAE

{
    "version": "0.2.0",
    "configurations": [
        {
            "type": "amiga-assembly",
            "request": "launch",
            "name": "WinUAE Debug",
            "stopOnEntry": true,
            "program": "${workspaceFolder}/uae/dh0/gencop",
            "remoteProgram": "SYS:gencop",
            "emulatorType": "winuae",
            "emulatorArgs": [
                "-s",
                "quickstart=a1200,1",
                "-r",
                "C:/Users/paulr/workspace/amiga/kickstarts/Kickstart3.1.rom",
                "-s",
                "filesystem=rw,dh0:${workspaceFolder}/uae/dh0",
            ],
            "preLaunchTask": "amigaassembly: build"
        }
    ]
}

Parameters

option	description
type	type if debug server: 'amiga-assembly'
request	type of debugging method must be 'launch'
name	Name of the configuration
stopOnEntry	If true the program will stop on the first instruction
serverName	Name of the server containing the fs-uae emulator
serverPort	Socket port number opened for debug by the emulator
trace	If true logs will be added to the output console (communication protocol)
emulatorType	Type of the emulator : 'winuae' or 'fs-uae'
program	Local path of target Amiga binary
remoteProgram	Remote path of target Amiga binary
sourceFileMap	Sources paths replacements (useful if the build was done in a another directory)
rootSourceFileMap	Additional paths for sources
emulatorArgs	Options to send to the emulator (see fs-uae options)
exceptionMask	Binary mask to trigger exceptions catch during debug (see table below)
emulatorStartDelay	Delay before starting the emulator
noDebug	Run without debugging
preLaunchTask	(replacement of buildWorkspace) : Set to "amigaassembly: build" to build the workspace before launch

Traps (68000 Exception Vector Numbers - source)

Bit	description
2	Bus error access of nonexistent memory
3	Address error long/word access of odd address (68000)
4	Illegal instruction illegal opcode (other than Axxx or Fxxx)
5	Zero divide processor division by zero
6	CHK instruction register bounds error trap by CHK
7	TRAPV instruction overflow error trap by TRAPV
8	Privilege violation user execution of supervisor opcode
9	Trace status register TRACE bit trap
10	Line 1010 emulator execution of opcode beginning with $A
11	Line 1111 emulator execution of opcode beginning with $F
32-47	Trap instructions TRAP N instruction where N = 0 to 15

WinUAE configuration details

WinUAE runtime configuration is the concatenation of two things : the ${config:amiga-assembly.binDir}/default.uae file and the .vscode/launch.json options.

• Example of default.uae :

use_gui=no
win32.start_not_captured=yes
win32.nonotificationicon=yes
boot_rom_uae=min
cpu_cycle_exact=true
cpu_memory_cycle_exact=true
blitter_cycle_exact=true
cycle_exact=true
input.config=1
input.1.keyboard.0.friendlyname=WinUAE keyboard
input.1.keyboard.0.name=NULLKEYBOARD
input.1.keyboard.0.empty=false
input.1.keyboard.0.disabled=false
input.1.keyboard.0.button.41.GRAVE=SPC_SINGLESTEP.0
input.1.keyboard.0.button.201.PREV=SPC_WARP.0

All these options can be mixed and a better comprehension of WinUAE can be useful.

Other debug features

Custom registers in variables

We now list the values of the Amiga hardware registers in the variables panel. It splits them into fields to describe each bit-range and group related registers where appropriate.

Additional formats visualization for variables, including signed and size variants

This gives you additional views of formatted variable values.

Label offset annotations for address registers

This displays the offset from a label in your source code alongside address registers where possible.