----------------------------------------------------------------------------- MEKA - Debugger / Hacking tools ----------------------------------------------------------------------------- Note: this documentation is yet incomplete. ----------------------------------------------------------------------------- ----------------------------------------------------------------------------- 1. Debugger ----------------------------------------------------------------------------- To enable the debugger, set 'debug_mode' to 1 in the configuration file. Else, you can enable the debugger for a session by executing MEKA with the '-DEBUG' command-line parameter. In debug mode, an additionnal menu is added to the top, with access to the debugger and data dumping facilities. The debugger can also be switched on and off using the Scroll Lock key. You can configure some part of the debugger from the configuration file, search for the following variables: debug_mode (enable debug mode) debugger_console_lines (number of console lines) debugger_disassembly_lines (number of disassembly lines) debugger_disassembly_display_labels (enable label display) debugger_log (enable log of debugger output) All debugger output are logged by default. The log is located in the 'DEBUG/DEBUGLOG.TXT' file. Symbols Loading --------------- The debugger attempt to load symbols in NO$GMB format, as generated by the WLA DX linker (-s option). The filename must be the same as the ROM image filename, replaced by or post pended with the ".SYM" extension. - eg: ROM is "PsychoFox.sms", -> MEKA will look for symbols in "PsychoFox.sym" or "PsychoFox.sms.sym" Completion ---------- Pressing TAB in the debugger command line performs contextual completion. If more than one item matches, possible matches are displayed. History ------- Command are logged into an history buffer. Pressing Up/Down allows navigating in the history buffer. Additionnally, the HI/HISTORY allows listing or searching for a given word in the history buffer. Expression evaluator -------------------- Mathematical expression can be evaluated by the debugger. Supported features are: - Values: - Immediate hexadecimal integer (eg: 1234, or $1234 or 0x1234) - Immediate binary integer (eg: %00101010) - Immediate decimal integer (eg: #256) - Symbols gets replaced by their address. (eg: function_label) - Z80 registers names gets replaced by their current value. (eg: PC, SP, AF, A, BC, B, C, DE, D, E, HL, H, L, IX, IY) Pay attention that some registers names are ambiguous with hexadecimal constants ('A' is a 10 in hexadecimal). Z80 registers name are always given priority over hexadecimal constants. Uses the 'Ox' or '$' prefixes to resolve ambiguity. - Operators: - Integer operators: + - / * (eg: 1+2*3 returns 7) - Binary operators: & | ^ (eg: 0xF0 | 0x0F returns 0xFF) - Parenthesis: (), forcing priority (eg: (1+2)*3 returns 9) Known problems -------------- - Beware of clashes between Z80 registers names and hexadecimal constants. 'AF','BC','DE','A','B','C','D','E' by default refers to Z80 registers. Uses $ or 0x hexadecimal prefixes to resolve ambiguities. - Reseting or loading save states may trigger strange behavior, such as breakpoints being ignored for a frame or so. - Execution breakpoints only function for the leading byte of the opcode. eg: 1234 - C3 00 20 - JP $2000 Adding an X breakpoint at $1234 will work, but not at $1235 or $1236. However, adding a R breakpoint will work. So usually, you end just adding default RWX or RW breakpoints. Debugger commands summary ------------------------- -- Flow: <CR> : Step into S : Step over C : Continue C addr : Continue up to <addr> J addr : Jump to <addr> -- Breakpoints: B [access] [bus] addr [=value] : Add breakpoint W [access] [bus] addr [=value] : Add watchpoint B LIST : List breakpoints B REMOVE id : Remove breakpoint B ENABLE id ; Enable breakpoint B DISABLE id : Disable breakpoint B CLEAR : Clear breakpoints -- Inspect/Modify: R : Dump Z80 registers P expr : Print evaluated expression M [addr] [len] : Memory dump at <addr> D [addr] [cnt] : Disassembly at <addr> SYM [name] : List symbols SET register=value : Set Z80 register CLOCK [RESET] : Display Z80 cycle counter -- Miscellaenous: MEMEDIT [lines] [cols] : Spawn memory editor HISTORY [word] : Print/search history H,? [command] : Help Debugger command - H -------------------- H/HELP: Online help Usage: H ; Get general help H command ; Get detailed help on a command Debugger command - S -------------------- S: Step over Usage: S ; Step over current instruction Examples: 0000: CALL $0100 0003: LD HL, $1FFF S ; Resume execution after the call Debugger command - C -------------------- C/CONT: Continue execution Usage: C ; Continue C address ; Continue up to reaching <address> Debugger command - J -------------------- J/JUMP: Jump Usage: J address ; Jump to <address> Examples: J 0 ; Jump back to $0000 (reset) J 1000 ; Jump to $1000 Note: Equivalent to SET PC=address Debugger command - B -------------------- B/BREAK: Manage breakpoints Usage: B address [..address2] ; Add CPU breakpoint B [access] [bus] address [=xx] ; Add breakpoint B LIST ; List breakpoints B REMOVE id ; Remove breakpoint <id> B ENABLE id ; Enable breakpoint <id> B DISABLE id ; Disable breakpoint <id> B CLEAR ; Clear breakpoints Parameters: address : breakpoint address, can be a range access : access to trap, any from r/w/x (rwx) bus : bus/event, one from cpu/io/vram/pal/line (cpu) xx ; byte to compare to, for conditionnal break id : breakpoint identifier Examples: B 0038 ; break when CPU access $0038 B w io 7f ; break on IO write to $7F B rx e000..ffff ; break on CPU read/exec from $E000+ B x =0,0,C9 ; break on CPU execution of NOP NOP RET B w vram 3f00.. ; break on VRAM write to SAT B w pram 0 =03 ; break on PRAM write of color 0 as $03 B line #13 ; break on display line 13 You can add a description to breakpoints, by ending the command line with a string: B 0038 "interrupt" As a shortcut: B nopnop Is equivalent to: B x=0,0 "NOP NOP" Debugger command - W -------------------- W/WATCH: Manage watchpoints Usage: Same as B/BREAK. Watchpoints will display value but won't break. Examples: W r io dd ; watch and log all IO read from DDh W w pal 0.. ; watch and log all palette write Debugger command - P -------------------- P/PRINT: Print expression Usage: P expr P expr[,expr,...] Examples: P IX,IY ; print IX and IY registers P 1200+34 ; print $1234 P %00101010 ; print 42 P HL+(BC*4) ; print HL+BC*4 P label ; print label Debugger command - SET ---------------------- SET: Set Z80 register Usage: SET register=value [,...] Parameters: register : Z80 register name value : value to assign to register Examples: SET BC=$1234 ; set BC register to $1234 SET DE=HL,HL=0 ; set DE=HL, then zero HL Debugger command - CLOCK ------------------------ CLOCK: Display Z80 cycle accumulator Usage: CLOCK ; Display cycle accumulator CLOCK R[ESET] ; Reset cycle accumulator Debugger command - SYM ---------------------- SYM/SYMBOLS: List symbols Usage: SYM [name] Parameters: name : symbol name to search for (*) Examples: SYM vdp SYM obj*update Debugger command - M -------------------- M/MEM: Dump memory Usage: M [address] [len] Parameters: address : address to dump memory from (PC) len : length to dump, in byte (128) Examples: M ; dump 128 bytes at PC M HL BC ; dump BC bytes at HL Debugger command - D -------------------- D/DASM: Disassemble instructions Usage: D [address] [cnt] Parameters: address : address to disassemble from (PC) cnt : number of instruction to disassemble (10) Debugger command - R -------------------- R/REGS: Dump Z80 registers Usage: R Debugger command - MEMEDIT -------------------------- MEMEDIT: Spawn memory editor Usage: MEMEDIT [lines] [cols] Parameters: lines : number of lines cols : number of columns Debugger command - HISTORY -------------------------- HI/HISTORY: Print/search history Usage: HISTORY ; Print history HISTORY word ; Search history ----------------------------------------------------------------------------- 2. Palette ----------------------------------------------------------------------------- ... ----------------------------------------------------------------------------- 3. Tile Viewer ----------------------------------------------------------------------------- ... ----------------------------------------------------------------------------- 4. Tilemap Viewer -------------------------------------------------------------------------...
majeron