PicBasic Pro Compiler Debug Monitor

PicBasic Pro version 2.2 and up includes hooks that may be used to create
a debug monitor program.  A monitor is a program that runs resident with
the user program and allows the user program to be stopped, restarted,
traced and data to be displayed.

The new On Debug instruction in PicBasic Pro allows a monitor program to
be written in BASIC.  This monitor program may use any of the PicBasic Pro
instructions, though use of the stack should be avoided (Call, Gosub or
Return).  The monitor is given control between each BASIC instruction.
Disable Debug and Enable Debug psuedo-ops may be used to control where a
program may be diverted.


Macro Change

Before this debug monitor can be used with the PicBasic Pro Compiler
(version 2.20), a change must be made to the main macro file, PBPPIC14.MAC.
Some versions may already incorporate this change.

First save a copy of the file.  Then edit the file PBPPIC14.MAC with any
text editor such as DOS EDIT or Window's Wordpad.  Search for the macro
DCALL?L.  It should look like:

DCALL?L macro Dlabel
    local label
        movlw   low label
        movwf   DEBUG_ADDRESS
        movlw   high label
        movwf   DEBUG_ADDRESS + 1
        L?GOTO  Dlabel
label
    endm
  endmod

Add the line RST?RP at the beginning as shown:

DCALL?L macro Dlabel
    local label
        RST?RP
        movlw   low label
        movwf   DEBUG_ADDRESS
        movlw   high label
        movwf   DEBUG_ADDRESS + 1
        L?GOTO  Dlabel
label
    endm
  endmod

Save the file and you are ready to use the debug monitor.


Debug Monitor

The monitor program requires very few resources from the host.  One or
two variables need to be defined: DEBUG_ADDRESS needs to be defined as
a system word variable in bank0:

DEBUG_ADDRESS   var     word bank0 system

Additionally, the stack level may be monitored by defining a second
variable:

DEBUG_STACK     var     byte bank0 system

The monitor program is enabled by using the PicBasic Pro statement:

        On Debug Goto label

where label is the name of the debug monitor routine.  Once the PicBasic
Pro Compiler sees this instruction, it will place a jump to the debug
monitor routine at the label before each PicBasic statement, in much the
same way On Interrupt Goto places its call before each statement.

        Disable Debug

may be used to stop the compiler placing the jump to the monitor in
critical sections of the code.

        Enable Debug

causes the compiler to begin placing the jump in the code once again.

The monitor code itself should be placed at the beginning of the BASIC
program preceded by a jump around it.  Or the monitor program may be a
separate file that is included at the beginning of any program to be
monitored.


Mechanics

Immediately before each instruction, the current program address is
stored into the variable DEBUG_ADDRESS and a jump to the monitor is
executed.  The monitor may then choose to display debugging information,
wait for a user command, or simply return to the main program by jumping
to the address in DEBUG_ADDRESS.

These techniques are best demonstrated in a program.  The PicBasic Pro
program DEBUGMON.BAS shows one way of writing a debug monitor.  It should
be included at the beginning of the program to be debugged.  Another
sample program, DBLINK.BAS, shows this.  DBLINK.BAS is the sample BLINK
program with the debug monitor inserted.

DEBUGMON communicates with a terminal communications program running on
a PC, such as Hyperterm.  It uses the Hserin and Hserout instructions so
it requires a PICmicro with a hardware serial port.  The default baud
rate is 2400 and the TX and RX pins are PORTC.6 and PORTC.7.

The example program has been compiled for the 16F877 but may be used
with a 16C74 or 16C77:

        PBP -p16f877 -c -ol dblink

DBLINK includes DEBUGMON at the beginning and then follows it with
simple code to turn an LED connected to PORTD.0 on and off about once a
second.


DEBUGMON Operation

DEBUGMON accepts several one letter commands.  When it is ready for a
command, it displays a "?" on the terminal screen.  Once the "?" is
displayed, a lower case letter may be typed on the terminal keyboard to
execute a command.  The current commands in DEBUGMON are as follows:

d - Display stack level and all bank 0 registers in hexadecimal.
g - Continue the program execution where it left off (Go).
h - Show a short Help screen.
m - Enter the Monitor program.
r - Start running the program at the Reset address (0).
s - Single step through one PicBasic Pro statement.
t - Trace the program by displaying each BASIC statement's address in
hexadecimal as it is executed, from where it left off.

The easiest way to understand the operation of DEBUGMON is to try it out
with the DBLINK program.  However, the "m" command may need a little
additional explanation.

Once the program is running (and the LED is blinking) using Go or Trace,
it is necessary to have a method to get control back to the monitor so
you can examine the registers or Trace addresses.  Entering "m" from the
terminal stops the program's execution and turns control over to the
monitor.

As the monitor is written in BASIC, it may be modified to provide other
functionallity, such as breakpoints or elimination of the Hser commands
to allow it to be used on PICmicros lacking a hardware serial port.

