-----------------------------------------------------------------------------
 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 the debugger applet size from the configuration file.


Known problems
--------------

- 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 2000h
  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 : Add breakpoint
 B LIST                : List breakpoints
 B REMOVE n            : Remove breakpoint
 B ENABLE/DISABLE n    : Enable/disable breakpoint
 B CLEAR               : Clear breakpoints
 W [access] [bus] addr : Add watchpoint
-- Inspect:
 M [addr] [len]        : Memory dump at <addr>
 D [addr] [cnt]        : Disassembly at <addr>
 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 0100h
 0003: LD HL, 1FFFh
 # 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 0000h (reset)
 J 1000        ; Jump to 1000h


Debugger command - B
--------------------
B/BREAK: Manage breakpoints
Usage:
 B address                 ; Add CPU R/W breakpoint
 B [access] [bus] address  ; Add breakpoint (advanced)
 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:
 access  : access to trap, any from r/w/x (rwx)
 bus     : bus to watch, one from cpu/io/vram/pal (cpu)
 address : breakpoint address, can be a range
 id      : breakpoint identifier
Examples:
 B 0038         ; break when CPU access 0038h
 B w io 7f      ; break on IO write to 7Fh
 B rx e000-ffff ; break on CPU read/exec from E000h+
 B w vram 3f00- ; break on VRAM write to SAT


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


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)


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)


-----------------------------------------------------------------------------
 2. Palette
-----------------------------------------------------------------------------

 ...

-----------------------------------------------------------------------------
 3. Tile Viewer
-----------------------------------------------------------------------------

 ...
 
-----------------------------------------------------------------------------
 4. Technical Information
-----------------------------------------------------------------------------

 ...

-----------------------------------------------------------------------------
 5. Memory Editor
-----------------------------------------------------------------------------

 Allows viewing and writing to memory:
 - Z80 memory map
 - ROM
 - RAM
 - VRAM
 - PAL (if any)
 - SaveRAM (if any)
 
 Tips:
 - Use mouse wheel, arrow keys or cursor to navigate.
 - Using the address box, you can jump to a given address.
 - In some case, you may want to pause the game (F12) while editing,
   in some other case you may want it running.
 - Z80 memory map is what the Z80 CPU see and access thru its buses.
   Refer to technical documentation about the machine memory map to know 
   how this work. Understand the difference:
   - Writing to Z80 FFFC-FFFF trigger mapping + write to RAM.
     But writing to RAM FFFC-FFFF only write to RAM.
   - Writing to Z80 0000-3FFF is ignored.
     But writing to ROM 0000-3FFF works.
 - Beware that pressing "BackSpace" may reset the game. Use the "Delete" 
   key instead. (I should hack a way so that BackSpace is disabled 
   but other controller keys still enabled).

-----------------------------------------------------------------------------
 6. Data Dumping
-----------------------------------------------------------------------------

 ...

-----------------------------------------------------------------------------
 7. Patching
-----------------------------------------------------------------------------

 Refer to MEKA.PAT file.

-----------------------------------------------------------------------------
 8. More ?
-----------------------------------------------------------------------------

 Please suggest features you may want to help development/hacking activity!
 Please report bugs!
 
 I can also point out that in the absence of a given feature, you can always
 hack into MEKA source code and add custom code/printing/hacks to help you.
 
 The TODO.TXT file provided along with the source code list several notes
 and ideas related to future development of debugging/hacking features.

-----------------------------------------------------------------------------
