Debugging

NSDSP library provides many debugging functions which is enough to integrate it with a debugger, or use it for automated tests.

The target chip must be prepared for debugging. This may include programming a debugging executive onto the chip, setting the debugging configuration bits, changing other configuration bits so that they do not prevent debugging, possibly other tasks. Once the chip is prepared for debugging, it may be debugged, but it cannot run without the debugger.

Programming for Debug

To prepare the chip, you need to open a programming session and program it for debugging. The library will prepare the chip and will start debugging session. You can then start debugging. The pseudo-code below shows how to start the debugging session.

  NSDSP.create(serial)
  Session = NSDSP.startProgSession(mcu, readOnly = false)
  Session.checkId(adjustRate = true)

  debugSession = Session.programForDebug(hexMap, tcy)

  // Debugging here

  NSDSP.endSession
  NSDSP.free

You can also re-start the debugging session without re-programming the chip as explained here

Allocating memory for debugging

Depending on the target device, the debugger may require memory (ROM and/or RAM), in which case you need to reserve the necessary memory resources. The easiest way to do this, is to use assisted debugging which will automatically reserve all the necessary resources, and also will provide access to software breakpoints. Alternatively, you may manually reserve debugging resources.

Debugging speed

The target device runs at certain speed. The debugger must adjust its own speed to match the speed of the device. Therefore, when you program your device for debug, you must specify TCY - time interval (in ns) of the instruction clock - how long it takes for a single instruction to execute. For example, for PIC18 with 64 MHz oscillator, the instruction clock runs at 16 MHz and thus, TCY is 1/16 μs, or 63 ns.

If you specify TCY shorter than it is, the debugging will fail. The symptom is inability to halt or halting at address 0. If this happens, try to increase TCY.

If you specify TCY longer than it is, the debugging will be slow. Moreover, if the difference between the real TCY and the TCY you have specified is too big, the debugger may also fail.

If the program at the target device runs at distinctly different speeds (for example, periods of lower speed for saving power are altered with periods of higher speed), select one speed which you want to debug. Make sure that the target device never halts when the speed is different from what you have selected.

If your program switches clock at the beginning, select the TCY which the target will have after the clock switch, and place your debugger entry point after the clock switch (not before).

Running and Halting

Device being debugged can be in one of two states. It is either running or being halted. When the device runs, it executes the same as it would without debugging. When the device is halted, the CPU stops execution, and is under debugger control.

Note that when device is halted, the peripheral modules may continue to work.

When you start a debugging session, the device is running, but it should halt soon after. Therefore the first thing you need to do is to wait for the first halt. If the device is not halting, the debugger is not working. If you use assisted debugging the first halt will be at the entry point, otherwise the first halt will be at or shortly after the reset vector.

Once the device is halted, you may issue a run command and let the target code execute. The target will continue to execute until it encounters a breakpoint. You can also halt the target manually. See Communications.

There are two different mechanisms to handle halts. Ordered halting is used for the devices that allow debugger access only when halted. Unordered halting is implemented for the devices capable of accepting debugging commands at run time. You can use an MCU object to find out if your device supports ordered or unordered halting.

Running and Single Stepping

While the target device is halted, there are two different methods to run it. One method is running, when the target runs indefinitely unless it encounters a breakpoint or a manual halt. The other method, called single stepping, will make target execute a single instruction and then halt again.

NSDSP also provides a command multi-step execution, which is the same as many single steps taken consecutively, but the target halts only after all the steps are executed. Multi-stepping is faster than doing the same amount of single steps consecutively. For some targets multi-stepping may be a thousand times faster than single steps, for others it may be just slightly faster.

Breakpoints

Breakpoints provide mechanisms to halt the target when certain conditions are met. NSDSP Interface Library supports two types of breakpoints.

Hardware breakpoints are part of the target device hardware. They can be used to halt the target when:

• The targeted processor executes an instruction at the specified address.
• Memory at the specified address is read.
• Memory at the specified address is written.

Software breakpoints use special processor instruction which cause halt. You can install software breakpoints in your code when you use assisted debugging. They are disabled when a debugging session starts, but you can enable or disable them later.

Memory and Register Access

NSDSP Interface library contains functions to read various types of memory, or various CPU registers. To read something from the target device, you first need to use a read function. Then you need to use the corresponding fetch function to retrieve the data received. As explained here, it is much more efficient to issue first all the necessary read functions and then use the fetch functions to retrieve all the data.

For more details about data access see Communications.

Flash memory can be read for some target devices, but not for all. Instead of reading flash memory, you can retrieve the data which were programmed on the chip using a get function. The result should be the same unless the target code has reprogrammed the flash. Flash memory cannot be written.

Some information does not require sending commands to the target and is available immediately, for example the Program Counter(PC) of the last halt. To access this information use get functions (as opposed to read and fetch).

Application IO

Some of the target devices support communications between the debugger and the application being debugged. For such devices, NSDSP can collect the data from the application. NSDSP library provides functions to access application data.

Special Cases

Devices with swappable partitions

Multi-core devices