Introducing jzIntv's Debugger

From Intellivision Wiki
Revision as of 00:55, 8 October 2007 by Mr z (talk | contribs) (Introducing the Registers)
Jump to: navigation, search

jzIntv offers a simple command-line oriented debugger. It should be familiar in style to anyone who has used the Apple ][ Monitor or DOS's DEBUG.EXE.

Debugger Overview

Invoking the Debugger

To invoke the debugger, add the "-d" flag to jzIntv's command line. For example, using "hello2.rom" from the Hello World Tutorial:

    jzintv -d hello2.rom

This will invoke jzIntv, and present you with a prompt:

Loading:
  hello2.rom
jzintv:  Initializing Master Component and peripherals...
gfx:  Searching for video modes near 320x200x8 with:
gfx:      Hardware surf, Double buf, Sync blit, Software pal, Windowed
gfx:  Selected:  320x200x8 with:
gfx:      Software surf, Single buf, Sync blit, Hardware pal, Windowed
snd:  buf_size: wanted 2048, got 2048
ay8910:  Automatic sliding-window setting: 10
CP-1610          [0x0000...0x0000]
PSG0 AY8914      [0x01F0...0x01FF]
[Graphics]       [0x0000...0x0000]
[Sound]          [0x0000...0x0000]
Scratch RAM      [0x0100...0x01EF]
System RAM       [0x0200...0x035F]
EXEC ROM         [0x1000...0x1FFF]
Pad Pair 0       [0x01F0...0x01FF]
STIC             [0x0000...0x007F]
STIC             [0x4000...0x403F]
STIC             [0x8000...0x803F]
STIC             [0xC000...0xC03F]
STIC (BTAB)      [0x0200...0x02EF]
STIC (GRAM)      [0x3000...0x3FFF]
[Event]          [0x0000...0x0000]
[Rate Ctrl]      [0x0000...0x0000]
ICart   [R   ]   [0x5000...0x50FF]
CP-1610 Snoop    [0x0200...0x035F]
[Debugger]       [0x0000...0xFFFF]
 0000 0000 0000 0000 0000 0000 0000 1000 -------Q  JSRD R5,$1026             0
>

Most of this output is jzIntv's initialization. The last portion is the debugger prompt.

The Debugger Prompt

 0000 0000 0000 0000 0000 0000 0000 1000 -------Q  JSRD R5,$1026             0
>

The prompt shown above is the debugger's input prompt. From here, you can tell the debugger what to do next. Before each prompt, jzIntv reports specific information about the state of the machine. The following diagram illustrates:

Jzintv debugger status line.png

R0 through R7 are the CPU's 8 registers. Each register is 16 bits wide. jzIntv's debugger shows their values in hexadecimal.

The "flags" field shows what CPU flags are currently set. jzIntv tracks 8 separate flags:

  S   Sign Flag
  C   Carry Flag
  O   Overflow Flag
  Z   Zero Flag
  I   Interrupt Enable Flag
  D   Double Byte Data Flag
  i   Previous instruction was interruptible

When a flag is set, jzIntv shows the letter for that flag. When the flag is clear, jzIntv shows a dash. This makes it easy to see what flags are currently set, without having to remember their exact order. The last flag position is special. It shows the current interrupt status:

  q  Interrupt asserted
  b  BUSRQ asserted
  Q  Interrupt being taken
  B  CPU halted by BUSRQ

In the example above, jzIntv shows the CPU as taking an interrupt. Really, it's coming out of reset, which is similar. Don't worry too much about interrupts for the moment.

Introducing the Registers

The CPU's registers act as a scratch pad, holding values for instructions to operate on. Some registers have special purposes. All the registers can be used for general purpose computation. Here's a quick reference to what each register can be used for.

RegisterGeneral PurposeShift InstructionsIndirect PointerReturn Address
R0 X X   
R1 X X X  
R2 X X X  
R3 X X X  
R4 X  Auto-incrementX
R5 X  Auto-incrementX
R6 X  StackX
R7 *  Program Counter 

R6 and R7 are special. R6 is the stack pointer. R7 is the program counter. The assembler accepts SP and PC as aliases for R6 and R7. You can perform arbitrary arithmetic on either, although performing math on the program counter usually is a bad idea unless you really know what you're doing.

You will want to pay attention to R7 to know where you are at in your program. You can use the listing file, as described in the Hello World tutorial to relate what you wrote to what the debugger shows you.

Debugger Commands

The debugger offers a series of single-letter commands. You can find a full summary here. For this tutorial, we will focus on a small subset of these.

CommandDescription
R <#> Run for <#> cycles. If no argument given, runs "forever"
S <#> Step for <#> cycles. If no argument given, steps "forever"
B <#> set Breakpoint at location <#>
M <A> <B> show Memory at location <A>. Show at least <B> locations.
U <A> <B> Unassemble memory at location <A>. Show at least <B> instrs.
Q Quit jzIntv

The commands are case-insensitive. That is, "R 100" (run 100 instructions) is the same as "r 100". The debugger also offers a short-cut: Pressing enter alone on a line is the same as "s 1". That is, it steps a single instruction.