Debug Session Object

The Debug Session object is a special type of Session object used for debugging target devices.

Creation

The Debug Session objects are typically created by programming the target device with nsdsp_session_program_for_debug function. This function mutates the Session object into Debug Session object.

The Debug Session objects can also be created without re-programming the target device (assuming the programming has been done already) using nsdsp_start_debug_session function. In this case, a Debug Info object must be extracted from a previous Debug session with nsdsp_debug_get_info or nsdsp_debug_get_slave_info function.

Once a Debug Session is created, you should wait for a first halt with nsdsp_debug_check_for_halt or nsdsp_debug_wait_for_halt function. Once the target halts, you can debug.

Configuring Breakpoints

Hardware breakpoints are implemented in target device hardware and can be enabled or disabled with nsdsp_debug_enable_exec_bp, nsdsp_debug_enable_read_bp, nsdsp_debug_enable_write_bp, and nsdsp_debug_disable_bp functions.

Software breakpoints are available if you use assisted debugging and can be enabled or disabled with nsdsp_debug_enable_soft_bp and nsdsp_debug_disable_soft_bp functions.

All breakpoints are disabled after the first halt, so you need to enable desired breakpoints right away.

Running and Halting

Once the breakpoints are set, you can run the target with nsdsp_debug_run, nsdsp_debug_single_step, nsdsp_debug_multi_step functions.

While the target device is running, access to the target is restricted. On some of the devices, you can read memory with nsdsp_debug_read_ram or manipulate breakpoints without waiting for halt. It may also be possible to receive communications from the program being debugged using nsdsp_debug_check_for_app and nsdsp_debug_get_app_word functions.

You can check for halts with nsdsp_debug_check_for_halt or nsdsp_debug_wait_for_halt functions, or you can force the halt with nsdsp_debug_request_halt function.

Gathering Information

Once the target device halts, there is some information, such as location of the halt, available immediately. You can retrieve this information with nsdsp_debug_get_pc, nsdsp_debug_get_soft_bp, nsdsp_debug_is_partitioned, nsdsp_debug_can_swap, nsdsp_debug_is_swapped, nsdsp_debug_is_boot_swapped, and nsdsp_debug_get_flash_word functions.

Other information is not immediately available, and the requests must be sent to the NSDSP debugger to retrieve this information. Such requests may be made with read functions - nsdsp_debug_read_ram, nsdsp_debug_read_rom, nsdsp_debug_read_reg, nsdsp_debug_read_bp_state, nsdsp_debug_read_cp0, and nsdsp_debug_read_stack.

Once you send all the necessary requests, you should call nsdsp_session_flush function, and then, optionally, wait for the data to arrive with nsdsp_debug_check_for_data or nsdsp_debug_wait_for_data function. If you want to wait for data, you will need to know how many bytes of data to expect. Each read function returns the number of bytes in the expected response. You can sum these values up and pass them to nsdsp_debug_check_for_data function.

When all the data arrives, you can retrieve it with fetch functions matching in kind and order the read functions you have used previously. Here is how the functions should match:

Note that for devices with ordered halting, the nsdsp_debug_run, nsdsp_debug_single_step, and nsdsp_debug_multi_step functions must be ordered and matched as if they were read functions. For devices with unordered halting, such ordering is not needed.

Modifying Target Memory

You can write to target device memory or registers using nsdsp_debug_write_ram, nsdsp_debug_write_reg, nsdsp_debug_write_float_reg, and nsdsp_debug_write_double_reg functions.