Logs, breaks and debugging
On this page
There are two levels of observation: what the 65C02 does (instructions, memory) and what the program asks of the firmware (API calls). The two logs match up: the write to $FF00 in the trace is the call that shows in the API log.
--trace
Syntax : --trace trace.txt
Writes every executed instruction: address, code byte, disassembly, registers A X Y S P, cycle, and ea= the operand’s effective address (- when none). API JSRs are recognised. Mind the size: one second of machine time makes millions of lines.
Example
$ phosphoneo g.neo --cycles 2000000 --trace trace.txt
0800 A9 LDA #$02 A=00 X=00 Y=00 S=FD P=24 cyc=7 ea=-
0802 8D STA $FF01 A=02 X=00 Y=00 S=FD P=24 cyc=9 ea=FF01
0805 A9 LDA #$00 A=02 X=00 Y=00 S=FD P=24 cyc=13 ea=-
--trace-from
Syntax : --trace-from CYCLES
Only traces from the given cycle: to understand a late hang without producing a giant file.
Example
$ phosphoneo g.neo --cycles 2000000 --trace-from 300 --trace tr.txt
--api-log
Syntax : --api-log journal.log[:G,G…]
Logs every API call as it is handled: cycle, instruction address, group, function, parameters before and after, error code. If groups follow a colon, only those are kept (up to group 63, so Trinity’s toolbox, groups 32 to 38, too). Not available with the co-simulation backend.
Example
$ phosphoneo graphics.neo6502@800 cold --cycles 3000000 --api-log api.log:5
cycle=67 pc=082F grp=5 fn=2 p=00000000E000E000 r=00000000E000E000 err=0
cycle=127 pc=0861 grp=5 fn=3 p=00000000E000E000 r=00000000E000E000 err=0
cycle=187 pc=0893 grp=5 fn=4 p=00000000E000E000 r=00000000E000E000 err=0
Good to know. Reading: group 5 (graphics), function 2 = draw a line, 3 = filled rectangle, 4 = filled ellipse.
err=0: no error;err=17on a missing file.
--symbols
Syntax : --symbols prog.lbl
Loads a symbol file: al ADDRESS .name lines (VICE format, produced by 64tass and cc65), name = $ADDRESS, or exports from an ld65 .map. Names show up in the trace and the monitor, and can be given to --break-at and --watch. Note: the address is written without a C: in front.
Example
$ phosphoneo g.neo --symbols g.lbl --break-at apres_couleur
phosphoneo : 2 symboles (g.lbl)
phosphoneo : point d'arret en $0805 (cycle 13) A=02 X=00 Y=00 S=FD P=24
Good to know. An unknown name stops nothing: Phosphoneo prints “symbole inconnu” and carries on.
--break-at
Syntax : --break-at ADRESSE|nom
Stops execution when the 65C02 reaches this address (hexadecimal or symbol). Repeatable. Without a monitor or gdb, Phosphoneo prints the registers and exits with code 3.
Example
$ phosphoneo graphics.neo6502@800 cold --break-at 0805
phosphoneo : point d'arret en $0805 (cycle 13) A=02 X=00 Y=00 S=FD P=24
phosphoneo : 13 cycles, 0 appels API
--watch
Syntax : --watch ADRESSE[:w|r|rw]
Watches a memory address: stops at the first write (:w, default), read (:r) or either (:rw). Like --break-at, accepts a symbol.
Example
$ phosphoneo graphics.neo6502@800 cold --watch FF01:w --cycles 100000
phosphoneo : surveillance $FF01 en $0805 (cycle 13) A=02 X=00 Y=00 S=FD P=24
--break-api
Syntax : --break-api GROUPE[,FONCTION]
Stops before the requested API call (every call in the group if the function is omitted), to look at its parameters as the program set them. Eight breaks at most. State and parameters are printed, and the exit code is 3.
Example
$ phosphoneo graphics.neo6502@800 cold --break-api 5,3
phosphoneo : appel API 5,3 en $0864 (cycle 127) A=05 X=00 Y=00 S=FD P=24 fn=3 p=00000000E000E000
phosphoneo : 127 cycles, 1 appels API
--break-dump
Syntax : --break-dump ram.bin
With --break-at, --watch or --break-api: copies the 64 KB of RAM to the file at the moment of the stop, to examine later at leisure.
Example
$ phosphoneo prog.neo --break-api 3,2 --break-dump ram.bin
--tui
Syntax : --tui
Opens an ncurses monitor: stops at reset, single-stepping (s instruction, n without entering JSRs, c continue), breakpoints and watchpoints, memory, console. Needs ncursesw at build time.
Example
$ phosphoneo prog.neo --symbols prog.lbl --break-at main --tui
--gdb
Syntax : --gdb [PORT]
Starts a gdb server (RSP protocol) on 127.0.0.1:PORT (default 1234) and waits for the debugger; execution stops at reset. Breakpoints, watchpoints, single-step, Ctrl-C.
Example
$ phosphoneo prog.neo --gdb 1234 # puis, dans gdb : target remote :1234