mega65/m65dbg

An enhanced remote serial debugger/monitor for the mega65 project

m65dbg

The “m65dbg” tool is a command-line based enhanced remote serial debugger/monitor for the mega65 project. In brief, some of its facilities include:

• Capable of being a symbolic debugger (for code compiled with Ophis, ACME or CC65)
• Disassemble any point of memory (showing original file-listing, if available)
• Print out memory values in byte, word, dword or string form
• Watch such memory values continuously as you debug and step through code
• Save and load chunks of memory between the MEGA65 and your local PC
• Provide a backtrace that you can comfortably move up and down through
• Search through memory for a sequence of bytes or string
• Take petscii screenshots of current screen context (borrowed from m65 tool)
• Remote-typing mode (borrowed from m65 tool)
• FTP access to SD-card (borrowed from mega65_ftp tool)
• You can also connect m65dbg to the serial-monitor provided by the xemu mega65 emulator

Latest documentation

Latest detailed documentation can be found here:

• https://docs.google.com/document/d/1cEhHvvc1E47UgSoXvKPpwnf43l20sLPY-y-ZuQ4b_ng/edit

The raw monitor

The m65dbg app adds enhanced commands on-top of the existing commands provided by the raw monitor.

Documentation for this raw monitor exists for it in the following locations:

• The MEGA65 Compendium: https://mega65.org/docs
• C65GS System Notes
  • https://docs.google.com/document/d/1fmEUg6hDdWRb2tFZ3n4LG7S1mNP04_SUAW5DrE8zRpk/edit#
  • See the “4.3 Remote Serial Monitor (handy for debugging)” section
• https://github.com/Ben-401/c65gs/blob/dockit/doc/monitor.md
  • Some extra usage info exists in this page of Ben's fork of the github repo
• Typing “?” within the monitor (via your terminal app) to see a list of slightly outdated commands

The source for the m65dbg app is available here:

• https://github.com/MEGA65/m65dbg

Video walkthroughs of m65dbg

These videos are highly-recommended watching, in order to get quickly acquainted with the facilities available in the m65dbg tool:

• m65dbg walkthrough
  • https://www.youtube.com/watch?v=2VT8yB3odhg
• m65dbg updates
  • https://www.youtube.com/watch?v=Rumti6AzsKY

For a youtube video walkthrough, please visit:

• https://www.youtube.com/watch?v=2VT8yB3odhg

Walkthrough

Here's some written points below:

• Should build fine in Windows+Cygwin and Linux.
• Mac OSX presently doesn't support the 2,000,000 bps serial speed. So as an alternative, you can make m65dbg instead talk to the xemu mega65 emulator via a unix socket.
  • More info at:
• Specify your serial port with the "-l" (or "--device) parameter, E.g., "m65dbg -l /dev/ttyUSB1"

Try the following steps:

• ./m65dbg -l /dev/ttyUSB1
• r (to print out current registers)
• b = a raw command to set a hardware breakpoint
• t1 (to turn trace mode on, a bit like ctrl-c breaking inside gdb)
• t0 (to turn trace mode off, a bit like doing 'c'/continue in gdb)
• n (my 'next'/step-over command, which uses the hardware's step-into command multiple times, can be very slow)
• s (my 'step-into' command, which just calls the hardware's step-into)
• [ENTER] key will repeat the last command
• finish (my 'step-out-of' command, which calls 'n'/next multiple times, can be very slow, depending on how busy the current function is)
• pb/pw/pd/ps = prints byte/word/dword/string values at the given address
• typing “help” will give you the list of m65dbg commands, while typing “?” will give you the list of raw commands.

m65dbg's Issues

provide awareness of alias values in debugger

There are some text-based alias terms such as "dos_filedescriptor_offset_currentcluster" that aren't in the symbols described in the "*.map" file.

They appear in the source in this form:

.alias dos_filedescriptor_offset_currentcluster 6

It'd be good to be able to parse such info out of the .a65 files and make use of it within the debugger and the readline library too.

Monitor : Corrupted Register Info

I'm aware that it's more a Monitor Issue, but it's so specific and related that perhaps someone had this problem before and can give me a hint to where look at.

I get "garbage" on the Register Info, just the same byte again and again, sometimes it changes betteen R executions.

What puzzles me is that the dissambled final line it's for the correct PC, not the PC showed, and both seems to came from the same memory addres of the Monitor :

     .alias      monitor_mem         $8000
...
      .alias      monitor_PCLo        $8005
      .alias      monitor_PCHi        $8006

This for print Registers :

print_history:
      `printstr   history_msg
      ldy         #$ff
_history_loop:
      iny
      lda         history_fmt,y
      bmi         _history_space          ; print space first
_history_lookup:
      cmp         #$20
      bcs         _history_jmp            ; >= 32, do jump table lookup
      tax
      lda         monitor_mem,x
      jsr         print_hex_byte
      bra         _history_loop

....
history_fmt:
      ; $00 - $1f : Offset into memory to print hex value from
      ; >= $20    : Table lookup to jump table
      ; $20 - Disassemble instruction and end
      ; $21 - Opcode
      ; $22 - IO
      ; $23 - Flags0
      ; $24 - Flags1
      ; $25 - Hypervisor
      ; $26 - ROM enables
      ; $27 - print five spaces
      ; High bit set implies printing a space first.       
      .byte       $06,$05,$81,$82,$83,$84,$8a,$8c,$0b,$90,$11,$8d,$0e,$80+$21,$15,$27
      .byte       $80+$00,$80+$23,$80+$24,$88,$80+$22,$89,$80+$25,$00+$26,$20

And this for Disassembly :

_history_end_of_display:
	jsr	print_crlf
	; Now display the next instruction that would be executed
	; We copy the PC to mem_addr, set the upper part of the address to $0777
	; for CPU context, and then call disassemble_one_instruction
	lda   monitor_mem+$05
	sta   mem_addr+0
	lda   monitor_mem+$06
	sta   mem_addr+1
	lda   #$77
	sta   mem_addr+2
	lda   #$07
	sta   mem_addr+3
	jmp   disassemble_one_instruction

Sample out :

PC   A  X  Y  Z  B  SP   MAPH MAPL LAST-OP In     P  P-FLAGS   RGP uS IO ws h RECA8LHC
ABAB AB AB AB AB AB ABAB 0606 ABAB         06     AB ........ .... AB R  AB H ........
,0777F612  07 A9     RMB0  $A9
   $A9

<dbg>r

PC   A  X  Y  Z  B  SP   MAPH MAPL LAST-OP In     P  P-FLAGS   RGP uS IO ws h RECA8LHC
ACAC AC AC AC AC AC ACAC 0606 ACAC         06     AC ........ .... AC R  AC H ........
,0777FB00  22 22 40  JSR   ($4022)

<dbg>

PC   A  X  Y  Z  B  SP   MAPH MAPL LAST-OP In     P  P-FLAGS   RGP uS IO ws h RECA8LHC
ACAC AC AC AC AC AC ACAC 0606 ACAC         06     AC ........ .... AC R  AC H ........
,0777F210  20 3F FC  JSR   $FC3F

<dbg>r

PC   A  X  Y  Z  B  SP   MAPH MAPL LAST-OP In     P  P-FLAGS   RGP uS IO ws h RECA8LHC
ACAC AC AC AC AC AC ACAC 0606 ACAC         06     AC ........ .... AC R  AC H ........
,0777FA12  00 00     BRK   $00

<dbg>r

PC   A  X  Y  Z  B  SP   MAPH MAPL LAST-OP In     P  P-FLAGS   RGP uS IO ws h RECA8LHC
ABAB AB AB AB AB AB ABAB 0606 ABAB         06     AB ........ .... AB R  AB H ........
,0777F113  FB        PLZ

<dbg>r

PC   A  X  Y  Z  B  SP   MAPH MAPL LAST-OP In     P  P-FLAGS   RGP uS IO ws h RECA8LHC
ACAC AC AC AC AC AC ACAC 0606 ACAC         06     AC ........ .... AC R  AC H ........
,0777FB12  22 1E 40  JSR   ($401E)

<dbg>r

PC   A  X  Y  Z  B  SP   MAPH MAPL LAST-OP In     P  P-FLAGS   RGP uS IO ws h RECA8LHC
ABAB AB AB AB AB AB ABAB 0606 ABAB         06     AB ........ .... AB R  AB H ........
,0777F800  00 00     BRK   $00

M65Dbg uses results from R to it's own commands, as dis...

Any hint?
Thanks in Advance

Best Regards

Edit : Well, it seems it could be a problem in the vdhl side of the monitor, it's like the info it's not ready when printing registers but it's when have to do the disassembly...

add some metrics

Following on from this forum thread post:

https://groups.google.com/d/msg/c65gs-development/FESl92s4vEM/ssr_u0cDAQAJ

We've got some concerns about the speed of debugging over the USB serial port interface, so it would be good to get some accurate measurements on where the delays are occurring.

I was thinking of printing out some debug timestamp information at key moments:

• upon pressing ENTER key on a command
• prior to sending out the command packet
• upon receiving the 1st byte of the result packet
• upon receiving the last byte of the result packet
• upon completion of my visual processing of the result packet

software breakpoints

Let the app auto-step through code and stop upon hitting one of a list of software breakpoints the user has added.

For software breakpoint support:

• the system must be in trace mode, as set by the "t1" raw command.
• use the "break {addr}" command for adding software breakpoints
• use "breaks" to list all breakpoints
• use "bdel {breakno}" to delete a breakpoint
• use "cont" to let the app do its auto-step mode
• let CTRL-C break out of the "cont" loop

As for the hardware breakpoint support, I'll consider doing it this way:

• for the hardware breakpoint to trigger, the system must not be in trace mode, so assure it is turned off with the "t0" raw command. Once the hardware break hits, the system will automatically pause and switch to trace mode (t1).
• use the "hbreak {addr}" command for setting the single hardware breakpoint
• use "hbreaks" to list the current hardware breakpoint (there's only one)
• use "hbreak" or "hbdel" to delete it

clean up tabs

The indention in my source is looking pretty horrid.

It's a result of a modest blackhole in my vim-knowledge relating to tab settings.

At some stage, when I'm ready to take on that learning curve, I'll clean the tabs up.

I'll aim for 2-space tabs (not hard tabs)

let ctrl-c break a few more commands

Some commands can possibly produce lengthy output.

Eg.

• dis c000 1000
• dump c000 3000
• mdump c000 3000

It would be nice to be able to press CTRL-C to kill these commands mid-way too.

seg faults in mac osx

Ralph reported that he gets freezes and segmentation faults when running under mac osx.

I've been able to replicate the problem on my macbook, so will investigate.

My gut feeling says it might be due to the macbook using a different c-compiler (LVVM/clang?). Ah well, I'll try debug it on os x to see what's going on...

Dissassembly doesn't distinguish between the RMBx, BBRx, RMBx and BBRx instructions.

When disassembling, RMBx, BBRx, RMBx and BBRx are dissembled as RMB, BBR, RMB and BBR without the last digit clarifying which bit is involved.

assess github's .md wiki system

I had a few reservations on this method, described here:

https://groups.google.com/d/msg/c65gs-development/mgGiiBxLe58/m853nmYaAQAJ

But I still want to get familiar with it and develop my understanding and assessment of it.

ty: pick up new keyboard scanner workaround from m65

The new keyboard scanner in the latest development core and ROM is too fast for the virtual keyboard registers as used by m65 and m65dbg. In m65, I was able to work around this like so, separating the Shift and key settings into separate s commands:

MEGA65/mega65-tools@4ca0bd2

m65dbg will need a similar change. There are currently no plans to fix the virtual keyboard registers to support the other method. (They ought to be, I just don't know anyone who is working on it.)

backtrace commands

• I want a gdb-like "back" backtrace command
• I also want "up" and "down" commands, to jump between frames in the backtrace.

settings/init files

It might be nice to have a "~/.m65dbg_settings" file to preserve configuration information, such as the serial-port device name.

Maybe a "~/.m65dbg_init" file would be nice one day too, as a place to store:

• your preferred initialisation steps (eg, "autocls 1", "autowatch 1")
• a place to store user-defined functions/macros that you need regularly

Building on my Linux box requires -lm and -ldl

Sorry for dropping this in an issue and not a PR, I'm rushing: I noticed that on my Arch Linux box, I needed explicit LDFLAGS for gcc math libraries:

LDFLAGS+=-lpng -lm -ldl

Without these the link failed looking for the pow() function.

load/save commands

I'd like to:

• create a "load {binfile} {addr}" method to load a binary file direct to memory
• create a "save {binfile} {addr} {count}" method to save a chunk of memory to a binary file on your pc

I'm hoping these functions will help me when making comparisons between original rom/.bin contents and what's found in the memory after loading from the sd-card.

compile error - vista cygwin

also refer to https://groups.google.com/forum/#!topic/c65gs-development/FEVkgRqs8Dg

$ make
gcc -c -Wall -g main.c -o main.o
main.c:7:31: fatal error: readline/readline.h: No such file or directory
compilation terminated.
Makefile:24: recipe for target 'main.o' failed
make: *** [main.o] Error 1

$ gcc commands.c gs4510.c main.c serial.c
main.c:7:31: fatal error: readline/readline.h: No such file or directory
compilation terminated.
serial.c: In function ‘serialFlush’:
serial.c:118:13: error: ‘FIONREAD’ undeclared (first use in this function)
ioctl(fd, FIONREAD, &bytes_available);
^
serial.c:118:13: note: each undeclared identifier is reported only once for each function it appears in

'c' command no longer works reliably

The 'c' command was intended to permit for behaviour similar to gdb's 'c' (continue) command, where:

• the debugger no longer provides you a command-prompt.
  • internally, I do a 't0' to turn off trace, then keep polling the registers to see if PC is repeatedly stuck at the same location.
  • if so, I assume a hard breakpoint is hit and provide the command-prompt again for the user to type the next command.
• If the program is running endlessly, I instead wait for the user to press CTRL-C, and then display the command-prompt.
  • Internally, this will send a 't1' command to begin trace-mode

From my debugging on this last night (in cygwin and ubuntu), it seems to be choking on this continuous polling of the registers. On some occasions, it isn't receiving the proper string back to parse them, so the parser is exceeding the length of the string that does return.

Not sure when this issue popped or what may have triggered it as yet.