Assisted Debugging

Assisted debugging refers to the situation where you add special debugging code to the project being debugged. This special code does three things:

• It reserves memory if required by the debugger
• It indicates where the code should be halted after entering the debugging mode
• It provides mechanism for software breakpoints

If, for some reason, you cannot or do not want to use assisted debugging, you need to set up debugging manually

To use assisted debugging, you need to use files provided within the "debug" directory in the library distribution package. Inside the "debug" directory, there are sub-directories for specific target devices and compilers. Locate the sub-directory for your target device, and read the "README.txt" for the instructions.

Target Device	Use sub-directory
dsPIC33A	pic33a
dsPIC33C	pic24
dsPIC33E	pic24
dsPIC33F	pic24
PIC12	pic16
PIC16	pic16
PIC18	pic18
PIC24	pic24
PIC32A	pic33a
PIC32M	pic32m

Make sure you use the file that came with the version of NSDSP Interface library you are using. Different versions may require different files.

Typically, there will be one file which you need to add to your project so that it gets compiled and linked with it. The other file will need to be included into your files where you plan to use debugging macros. For example:

#include <xc.h>
#include "nsdsp_dbg.h"

The include file will define two macros - NSDSP_DBG_ENTRY and NSDSP_DBG_BP.

NSDSP_DBG_ENTRY

This macro marks the place where the first halt should happen - typically at the beginning of your program.

If you switch clock at the beginning of your program, place the macro after the clock switch. This will make sure that the clock frequency at the time of execution of the NSDSP_DBG_ENTRY is the same as the clock frequency of the program being debugged. For example:

void main(void) {
  CLKDIV = 1;
  PLLFBD = 100;
  PLLDIV = 0x21;
  __builtin_write_OSCCONH(0x01);
  __builtin_write_OSCCONL(1);
  while (OSCCON & 1);
  
  NSDSP_DBG_ENTRY;
   ...

The NSDSP_DBG_ENTRY macro also contains a data table for the debugger which is used to find locations of memory reserved for the debugger and for software breakpoints.

It is possible to define several NSDSP_DBG_ENTRY macros inside the same program, although there is no practical purpose in doing so.

NSDSP_DBG_BP

This macro marks the location of a software breakpoint. It has one parameter - the id of the software breakpoints. The id must be a constant integer number. When debugging, you can use the id to enable and disable the breakpoint. For example:

for (i = 0; i < n; i++) {
  // Some processing here
  NSDSP_DBG_BP(5);
}
NSDSP_DBG_BP(7);

In this example, if you enable id 5, the target device will halt at every pass of the loop. If you enable id 7, the target device will halt after the loop.

It is possible to have multiple macros with the same id, but all the breakpoints having the same id will be enabled and disabled simultaneously.

Macros in assembler

If you program your target device in assembler, you can use the macros as well, only the syntax is different.

#include "xc.inc"
#include "nsdsp_dbg.inc"

  ...

  movlw 0x70
  iorwf OSCCON,f,a
  bsf OSCTUNE,6,a

  NSDSP_DBG_ENTRY

  banksel LATA
  bsf LATA,4,b

  NSDSP_DBG_BP 7

  bcf LATA,5,b

Building the project

After you include the macros, you will need to build your project. Make sure you build for production. If you build for debug, then your IDE will do its own changes which may interfere when debugging with NSDSP.

Once you build your project, you can program and run it. The NSDSP debugging macros will not have any effect, as if they were not there. However, the macros do take some space and the memory for the memory for the debugger is still reserved.

If you want to get rid of the NSDSP debugging overhead completely, define NSDSP_DBG_OFF.

Debugging

To debug the project with NSDSP Interface library, you need to load the HEX file and program it for debug (which is different from regular programming). The pseudo-code for debugging session may look like this:

  hexMap.read("your_hex_file.hex")
  NSDSP.create(serial)
  Session = NSDSP.startProgSession(mcu, readOnly = false)
  Session.checkId(adjustRate = true)

  debugSession = Session.programForDebug(hexMap, tcy)

  // Debugging here

  NSDSP.endSession
  NSDSP.free