lr-vm/docs/debugging.md

# Debugging
Run the vm with the debug option to enable breakpoints and debugging features: `./main -f myprogram.bin -d`. 

## Breakpoints
Create a breakpoint with `break;` in vaporlang and `BRKP` in assembly. Break instructions are a no-op when running without the debug option.

## Keyboard controls
- F2: Continue: Resume normal execution
- F3: Break All: Enter break state 
- F4: Step: Execute one instruction
- F9: Print program counter, disassemble current instruction, print register values
- F10: Dump memory segments 0 through 63 (inclusive)
- F11: Dump memory segments 64 through 127 (inclusive)
- F12: Disassemble next 16 instructions

## Understanding the Output
### F9
Program counter: The segment and offset address of the current instruction, first in decimal, then hexidecimal.

    PC:  036.009 0x24.0x09
    
Disassembly: The assembly for the current instruction. Decimal constants include comments for their hexadecimal value.

    ASM: LRC r02 #036 ; (0x0024)
    
Registers: Values of registers in decimal and then hexadecimal

    r00: 001 (0x01)
    r01: 001 (0x01)
    ...

### F10
16 bytes of memory per row (32 hex digits). This example contains the x y locations of pieces in tetris.

    0x00.0x00: 0x070E060F050F070F020E010F000F020F
    0x00.0x10: 0x070C070D060D060E0000000000000000
    ...

Segment 63 contains the return addresses of functions for vaporlang programs. 
The first byte `0x04` is the call stack size in bytes. The next 2 bytes `0x02` and `0x1E` are a segment and offset return address. The next `0x21.0x55` is another return address and explains the callstack size (4 bytes). The highest order return address is the current one at the time of execution.

    0x3F.0x00: 0x04021E21550000000000000000000000
    
Looking up `0x02.0x1E` in the assembly (with instruction address logging) shows that this address is directly after a call to the render function.

    LRL r0 r1 @render              ; 002.027  0x02.0x1B
    JMP r0 r1                      ; 002.029  0x02.0x1D
    LRC r0 #63                     ; 002.030  0x02.0x1E <- The stored return address
    
At `0x21.0x55` is the return address from the renderTile function. The call stack shows that the program has called render and render has called renderTile.

### F12
Disassembly of the next 16 instructions. The * marks the current instruction.

    * LRC r02 #035 ; (0x0023)        ; 036.016 0x24.0x10
      JEQ r00 r01 r02                ; 036.017 0x24.0x11
      LRC r01 #127 ; (0x007F)        ; 036.018 0x24.0x12
      LRC r02 #017 ; (0x0011)        ; 036.019 0x24.0x13
      ...