Application Debugging#

The following section provides information on enabling different types of debug logs in the SDK, monitoring sockets and internal queues, collecting RAM dumps, and performing other debugging steps listed further.

Enable Debug log for the WiSeConnect 3 SDK#

The WiSeConnect 3 SDK incorporates SL_DEBUG_LOG statements within various internal functions, providing valuable insights for debugging and troubleshooting during development. The SL_DEBUG_LOG debug logs appear in the following format:

   SL_DEBUG_LOG("\r\n MAC address failed \r\n");

By incorporating the following implementation into the application enables all SL_DEBUG_LOG statements in the SDK. These debug messages, along with the application’s output, displays in the serial terminal during runtime.

   void sl_debug_log(const char *format, ...)
   {
      va_list args;
      va_start(args, format);
      vprintf(format, args);
      va_end(args);
   }

Note:#

Instead of displaying all SL_DEBUG_LOG prints, the SDK can be customized to selectively enable debug log prints from specific sections of the SDK, allowing for more focused and efficient debugging. This is explained in the following sections.

Monitoring only Tx and Rx Frames#

To track the Tx (transmit) and Rx (receive) frames between the host and NWP, replace SL_DEBUG_LOG with printf and follow the following steps:

1. Navigate to the following path in the project folders:

   components\device\silabs\si91x\wireless\threading\

2. Open the file sli_si91x_multithreaded.c.

3. To Monitor Tx Frames :

   • Open the bus_write_frame function.

   • Replace SL_DEBUG_LOG with printf statement, as shown in the following example. Make the changes as demonstrated further:

   

   

4. To Monitor Rx Frames :

   • Open the si91x_bus_thread function.

   • Replace SL_DEBUG_LOG with printf statement, as shown in the following example. Make the changes as demonstrated further:

   

   

Expected output:#

1. To Monitor Tx Data Frames :

   • Open the bus_write_data_frame function.

   • Replace SL_DEBUG_LOG with printf statement, as shown in the following example. Make the changes as demonstrated further:

   

   

Expected output:#

Monitor Specific Tx and Rx Commands#

To focus on specific Tx and Rx logs, filter them by queue_id and frame_type. For instance, to log only BLE commands, follow the following steps:

1. Navigate to the following path in the project folders:

   components\device\silabs\si91x\wireless\threading\

2. Open the file sli_si91x_multithreaded.c.

3. Filter Tx frames using queue_id and make the following changes.

1. Filter Rx frames using queue_id and make the following changes.

Expected output:#

Monitor Command payload descriptor and payload#

1. Navigate to the following path in the project folders:

   components\device\silabs\si91x\wireless\threading\

2. Open the file sli_si91x_multithreaded.c.

   • To Monitor TX Command payload descriptor and payload :

     • Open the bus_write_frame function.

     • By adding this piece of code at the start of the Tx debug log, the command descriptor and payload of the Tx frames will be displayed.

   printf("TX data:");
     for (int i = 0 ; i < 16 ; i++) {
       printf("%x ", packet->desc[i]);
       if ((i + 1) % 8 == 0) {
         printf(" ");
       }
     }
   
     for (int i = 0 ; i < length ; i++) {
       printf("%x ", packet->data[i]);
       if ((i + 1) % 16 == 0) {
         printf("\n");
       }
     }
     printf("\n");

   

   

   • To Monitor RX Command payload descriptor and payload :

     • Open the si91x_bus_thread function.

     • By adding this piece of code at the start of the Rx debug log, the command descriptor and payload of the Rx frames will be displayed.

    printf("RX data:");
    for (int i = 0; i < (data[0] | ((data[1] & 0x0F) << 4)) + 16; i++) {
        printf("%x ", data[i]);
   
        if ((i + 1) % 8 == 0) {
            printf(" ");
        }
        if ((i + 1) % 16 == 0) {
            printf("\n");
        }
    }
    printf("\n");

   

   

Enable Error Logs#

These error logs are crucial for pinpointing the file and line number where the issue arises. To enable the error logs for critical issues, define the PRINT_ERROR_LOGS macro:

1. Navigate to the following path in the project folders:

   components\common\inc\

2. Open the file sl_constants.h.

3. Enable PRINT_ERROR_LOGS MACRO as illustrated further.

   

   

Enabling error logging will capture errors whenever the following SDK functions are called. The following listed functions should be used in areas where an issue is suspected. This identifies the specific functions where the problem occurs.

1. SL_VERIFY_POINTER_OR_RETURN

2. VERIFY_STATUS_AND_RETURN

3. VERIFY_STATUS_AND_GOTO

Monitor Sockets in the SDK#

To view all the sockets, add the sli_si91x_sockets variable to the debugger’s watch window (for example, in Simplicity Studio).

1. Navigate to the following path in the project folders:

   components\device\silabs\si91x\wireless\socket\src\

2. Open the file sl_si91x_socket_utility.c.

3. Right-click on the sli_si91x_sockets variable, as shown below. To monitor its value during debugging, add the sli_si91x_sockets variable to the watch window.

Socket Configuration and State Information#

• Each socket can be accessed using the sli_si91x_sockets[i] structure, where i stands for the socket File Descriptor (FD).

• If the socket is in a closed state, it indicates that the information provided by this structure is invalid or garbage.

Internal Queue Types in the SDK#

The SDK includes five distinct types of internal command queues. The following are the queues listed with their specific purpose or functionality:

1. Common - cmd_queues[0]

2. Wi-Fi - cmd_queues[1]

3. Network - cmd_queues[2]

4. BLE - cmd_queues[3]

5. Socket - cmd_queues[4]

Each of these command types has a corresponding instance in global data memory, represented by the sli_si91x_command_queue_t structure.

Role of the sli_si91x_command_queue_t Structure#

• The sli_si91x_command_queue_t structure plays an essential role in managing and tracking the internal command queues within the SDK. It helps to efficiently monitor the communication between the host and NWP through the respective command types.

Key Variables in the sli_si91x_command_queue_t Structure:#

• tx_queue: TX command queue.

• rx_queue: RX command queue.

• event_queue: Event queue.

• frame_type: Indicates the latest command sent to the NWP.

• tx_counter: Tracks the total number of transmitted commands between the host and NWP for this queue type.

• rx_counter: Tracks the total number of received commands between the host and NWP for this queue type.

• packet_id: Represents the packet ID of the latest command sent to the NWP.

• flags: Indicates whether the last command sent to the NWP was synchronous or asynchronous.

• command_tickcount: Represents the tick count when the command was added by the application thread.

• command_timeout: Specifies the maximum timeout that the application thread should wait for a response.

These variables help to efficiently manage and track the communication between the host and NWP through the internal queues.

Monitor Internal Queues#

To track internal SDK queues, add the cmd_queues variable to the watch window in the debugger.

1. Navigate to the following path in the project folders:

   wiseconnect\components\device\silabs\si91x\wireless\threading\

2. Open the file sli_si91x_multithreaded.c.

3. Right-click on the cmd_queues variable, as shown below, add it to the watch window for monitoring its value during debugging.

Procedure for Capturing NWP RAM Dump#

Enabling NWP Debug Logs#

• To capture NWP logs via UART, enable the SL_SI91X_EXT_FEAT_UART_SEL_FOR_DEBUG_PRINTS bit (BIT(27)) in the ext_custom_feature_bit_map of the device configuration. This allows the NWP logs to be redirected to the UART port.

Identifying Memory Configuration for SOC and NCP#

• For RAM dump logs, it's essential to know the memory configuration used in the application, as it determines the NWP RAM size. There are different configurations for SOC and NCP.

SOC Memory Configurations:#

• Memory Configuration 1: NWP RAM size = 480 KB

• Memory Configuration 2: NWP RAM size = 416 KB

• Memory Configuration 3: NWP RAM size = 352 KB

NCP Memory Configuration:#

• Memory Configuration: NWP RAM size = 672 KB

• Memory Configuration: NWP RAM size = 352 KB

Determine the memory configuration in the application and use the corresponding API to capture the RAM dump.

API for Capturing NWP RAM Dump:#

Use the sl_si91x_get_ram_log API to capture the NWP RAM dump.

   sl_si91x_get_ram_log(uint32_t address, uint32_t length);

• Address: Use 0 for the base address.

• Length: Use the appropriate value based on the memory configuration (for example, 480 KB for Memory Configuration 1).

Example:

For Memory Configuration 1 (480 KB):

   sl_si91x_get_ram_log(0, 480 * 1024);

Note:#

• Once the sl_si91x_get_ram_log API is executed, the NWP RAM content is displayed on the console of TeraTerm/Docklight via the NWP UART port.

Retrieving NWP Thread Program Counter and Register values#

NWP runs with four threads. When an issue occurs, capturing the Program Counter (PC) value and the register values for each thread helps in identifying the source of the problem.

Program Counter values for NWP Threads:#

Each thread has a specific PC located at a calculated address. The following formula is used to retrieve the PC values for each thread.

• Program Counter address (PC):

  • The Program Counter address in the NWP is calculated using the thread number (thread_no), with four available threads (0, 1, 2, 3).

  • Calculate the Program Counter address based on the thread number using the following formula, and use this address with the sl_si91x_get_ram_log API to capture the Program Counter value for the respective thread.

  program counter address = 0x22000420 + (0x80 * thread_no)

  • API is called to retrieve the Program Counter value:

  program counter value = sl_si91x_get_ram_log(Program counter address, 4);

Note:#

• The Program Counter for each thread is 4 bytes in size.

Register values for NWP Threads:#

To calculate the register values stored at specified addresses for each NWP thread, the following approach is used:

• Register address:

  `0x2200047c + (0x80 * thread_no)`

  • Threads 0, 1, 2, and 3 are used in the NWP.

• Register content address:

  `0x22000440 + (0x80 * thread_no) + (Register Number * 4)`

  • API is called to retrieve the register values.

  sl_si91x_get_ram_log(Register address, 4);

Note:#

• Each thread contains 16 registers (R0-R15), with each register being 4 bytes in size.

• The R15 register works as a Stack Pointer (SP).

Considerations for NWP Hang#

• If NWP gets stuck (hang) and no further responses are received from the sl_si91x_get_ram_log API call, it will not capture the RAM dump.

Conclusion#

By following the procedure, you can capture the essential debugging information such as, RAM dumps, program counter values, and register values for all NWP threads. This helps in re-engineering the debugging process, and resolve issues more efficiently. Further, enable the debug logs, filtering specific logs, and monitoring key components such as frames, error logs, sockets, and internal queues which make it familiar to identify and address the issues within the SDK.

Platform Application Debugging Guide#

Powersave Application Debug#

• Introduction

• Debugging Modes

• GPIO based Debug

• UART based Debugging

• Using J-Link Commander

  1. Install J-Link Software

  2. Launch J-Link Commander

  3. Connect to the Target Device

  4. Monitor CPU current states

• Ozone Debugger

• ETM Debugging on SiWx917

Introduction#

Power-save mode debugging is a specialized process for analyzing and troubleshooting applications designed to minimize power consumption on microcontrollers like the Cortex-M4. These applications often operate in ultra-low-power states, transitioning between active and sleep modes to conserve energy. Debugging in such scenarios requires careful attention to avoid disrupting the low-power functionality.

Key challenges in power-save debugging include:

• Limited Debug Control: Accessing the microcontroller without causing wake-ups or interrupting the power-save state.

• Sleep/Wake Transitions: Ensuring the application properly enters and exits low-power modes.

• Peripheral Behavior: Verifying peripherals are correctly configured to shut down or remain functional as required.

To address these challenges, developers employ techniques such as using energy-efficient debugging interfaces (for example, SWD and, ITM), monitoring power consumption with energy profiling tools, and analyzing system behavior using hardware or software breakpoints. Additionally, firmware instrumentation and external tools like oscilloscopes can provide valuable insights.

By leveraging the right tools and methods, debugging power-save modes ensures optimal power efficiency while maintaining application reliability.

Debugging Modes#

GPIO based Debug:#

Debugging in power-save applications presents unique challenges due to the limited availability of traditional debugging interfaces in low-power states. To address these limitations, GPIO-based debugging techniques provide an efficient and reliable alternative. By leveraging GPIOs that remain operational across various power states, developers can trace program execution and monitor critical events without disrupting the application's low-power operation.

This approach involves initializing specific GPIO pins at the start of the application and using them strategically to signal, log, or trace key events or transitions during execution. With proper configuration, GPIOs can serve as versatile tools to gain insights into program flow, identify bottlenecks, and resolve issues while maintaining the integrity of power-saving features.

In this document, we explore practical techniques and use cases for employing GPIOs in debugging power-save applications, ensuring developers can maintain performance and efficiency throughout the debugging process.

#define PIN_NUMBER 0 // This is the UULP pin number being used for debugging
MCU_RET->NPSS_GPIO_CNTRL[PIN_NUMBER].NPSS_GPIO_CTRLS_b.NPSS_GPIO_MODE = 0;  // Mode 0 as GPIO
MCU_RET->NPSS_GPIO_CNTRL[PIN_NUMBER].NPSS_GPIO_CTRLS_b.NPSS_GPIO_OEN = 0;   // Configuring direction as output
MCU_RET->NPSS_GPIO_CNTRL[PIN_NUMBER].NPSS_GPIO_CTRLS_b.NPSS_GPIO_OUT = 1;   // This is to set/clear GPIO level

1. Add GPIO control logic In sleep wakeup path at rsi_deepsleep_soc source file, before and after wakeup to identify system is in sleep or wake up

MCU_RET->NPSS_GPIO_CNTRL[PIN_NUMBER].NPSS_GPIO_CTRLS_b.NPSS_GPIO_OUT = 0; // Indicating device in sleep state
/*Enter sleep with retention*/
  if (sleepType == SLEEP_WITH_RETENTION) {
    /*If retention mode is enabled save the CPU context*/
    RSI_PS_SaveCpuContext();
  } else {
    /*Clear RAM retentions*/
    RSI_PS_ClrRamRetention(M4ULP_RAM16K_RETENTION_MODE_EN | TA_RAM_RETENTION_MODE_EN | M4ULP_RAM_RETENTION_MODE_EN
                           | M4SS_RAM_RETENTION_MODE_EN);
    /*do not save CPU context and go to deep sleep */
    __asm("WFI");
  }
MCU_RET->NPSS_GPIO_CNTRL[PIN_NUMBER].NPSS_GPIO_CTRLS_b.NPSS_GPIO_OUT = 1;  //indicating device in wakeup state

• In the above scenario a GPIO logic HIGH indicates that the device is in an active state, allowing the user to connect any debugging tool and trace the application. Conversely, if the GPIO is at logic LOW, it signifies that the device is not accessible for debugging, as the debugging interface is unavailable.

1. Debugging tickless idle application is difficult as it trigger sleep function when device in idle state. To debug the pre-condition status before entering sleep mode, add GPIO controls in the sl_si91x_low_power_tickless_mode source file to investigate

// Checking the pre-sleep conditions. If these conditions are met, the core does not enter sleep mode.
  if ((eTaskConfirmSleepModeStatus() == sl_eAbortSleep) || (sl_si91x_power_manager_is_ok_to_sleep() == false)) {
    xExpectedIdleTime = 0;
    // Enable the NVIC interrupts.
    __asm volatile("cpsie i" ::: "memory");
	MCU_RET->NPSS_GPIO_CNTRL[PIN_NUMBER].NPSS_GPIO_CTRLS_b.NPSS_GPIO_OUT = 0;  //indicating pre sleep condition false
  } else {
    // Disable the chip level interrupt
	MCU_RET->NPSS_GPIO_CNTRL[PIN_NUMBER].NPSS_GPIO_CTRLS_b.NPSS_GPIO_OUT = 1;  //indicating pre sleep condition true and triggers sleep

The two scenarios mentioned above are provided as examples, but you can utilize these controls for further debugging since these GPIOs remain functional across all power states.

UART based Debugging#

• Debugging power-save applications presents unique challenges, especially when traditional debugging interfaces are unavailable in low-power modes. UART-based debugging techniques offer a valuable solution, allowing developers to monitor and trace application behavior without compromising the device’s power-saving features. By using UART communication, developers can transmit debug information such as error logs, status messages, and execution traces, all while the device operates in low-power states.

• This approach involves configuring the UART interface to send critical information during key events, enabling efficient monitoring and troubleshooting. UART-based debugging ensures minimal impact on power consumption, making it an ideal choice for applications that require both performance optimization and real-time debugging.

• In this document, we explore the key techniques, benefits, and best practices for using UART in power-save applications to enhance the debugging process and streamline development.

  Note: The Si91X features a ULP UART that remains available in all active and standby states, except for sleep and shutdown modes. You can utilize this interface to debug low-power states such as PS2 and PS1. After the device enters sleep mode, the UART must be reconfigured by the user once it wakes up.

• You can implement printing the status information of any API or register status in their application by simply adding the following code snippet 

  #include "rsi_debug.h" //this requires only in files where you wants to print the data through DEBUG_UART 
  
  uint32_t reg_status= P2P_STATUS_REG;  
  DEBUGOUT("\r\n P2P reg Status:%ld\r\n", reg_status); // printing the P2P status register status 

• You can determine where the code is blocked or halted during execution by using a printf statement, as shown below

     printf("%s,%d\r\n",__FILE__,__LINE__);  // Prints file name and line number of code it executed 
     sli_iot_power_set_expected_idle(xExpectedIdleTime);
     printf("%s,%d\r\n",__FILE__,__LINE__);  // Prints file name and line number of code it executed 
     expected_sleep_ticks = xExpectedIdleTime;
     total_slept_os_ticks = 0;	
     sl_si91x_power_manager_sleep();
     printf("%s,%d\r\n",__FILE__,__LINE__);  // Prints file name and line number of code it executed 
     sl_power_manager_sleep_on_isr_exit();
     ```

Using J-Link Commander#

• J-Link Commander is a tool provided by SEGGER that allows low-level interaction with Cortex-M4 microcontroller using a J-Link debug probe. It is particularly useful for debugging power-save applications because it provides fine-grained control and debugging capabilities without disrupting the microcontroller's low-power states.

• Here’s a step-by-step guide on how to use J-Link Commander for this purpose:

1. Install J-Link Software#

• Download and install the SEGGER J-Link Software and Documentation pack from the SEGGER website.

• Ensure you have the latest version for optimal support.

2. Launch J-Link Commander#

• Connect your J-Link probe to the target microcontroller and to your PC via USB. Open J-Link Commander app and enter then we will see below prompt for connecting.

3. Connect to the Target Device#

• Enter connect command to establish connection with target device. Once after establishing the connection it prompts you to select device

• Specify the target device and interface by typing the following command, by default it is SI917, if we require other device/core we need to enter "device < NAME >" in commander

4. Monitor CPU current states#

Use the halt command to stop the CPU and inspect its current state.

• Use the regs command to view CPU registers, including control registers for power management.

• Use the mem command to inspect specific memory locations, such as power configuration registers or peripheral states.

By utilizing commands such as step, which executes a single instruction, and go, which resumes CPU execution, we can proceed with debugging.

When device halts after wake up and doesn't proceed further please investigate below memory/reg locations through mem32 command through J-Link Commander

mem32 0x46008174 1

  BIT 0 ----- M4_WAKEUP_TA   This bit is used to wake up NWP from sleep.    

  BIT 1 ----- M4_is_active         This bit is used to indicate NWP that MCU is active 

  BIT 2 ----- TA_wakeup_M4    This bit is used to indicate MCU that it should wakeup from sleep (read only)

  BIT 3 ----- TA_IS_ACTIVE       This bit is used to indicate MCU that NWP is active (read only)

mem32 0x46008170 1

  BIT 1 ------ RX_BUFFER_VALID    This bit indicates TA that M4 is ready to accept incoming packets

  BIT 3 ------ M4_USING_FLASH    This bit indicates TA that M4 is using Flash and not off the Flash in common flash mode

Ozone Debugger#

• Ozone Debugger is a powerful, full-featured debugging tool developed by SEGGER for use with J-Link debug probes. It is designed to help developers debug, analyze, and optimize embedded applications efficiently. Ozone supports a wide range of microcontroller architectures, including ARM Cortex-M, Cortex-A, RISC-V, and more.

Ozone Setup for SiWx917 SoC Debugging#

• To debug the SiWx917 SoC using the Ozone IDE, follow these steps:

Manual Configuration#

• Install Ozone

• Download sl_si917.jdebug and SiWx917.svd files.

• Ensure the neccessary adjustments to the "sl_si917.jdebug" file should be made as outlined below:

  • Update the path for the SiWx917.svd file and also the Serial no of the device which will appear in the debug adapters pane in Simplicity studio.

    

    For Serial no. of the device.

    

• Before starting the debugging process, flash the both TA firmware and the Application binary which you intend to debug onto the SiWx917 SoC using Simplicity Commander.

  Note: Check the following procedure for flashing TA and Application binary.

  • Update SiWx91x Connectivity Firmware

  • Flash an application binary

Steps to Configure the SiWx917 SoC on the Ozone Debugger#

1. Launch Ozone.

2. Open the sl_si917.jdebug file from the File tab.

   

3. A window prompts you to open either the .axf or .out file for debugging the SiWx917 SoC example.

   

4. If any Diagnostics Warning may be displayed about FreeRTOS being detected. Click Continue.

5. Select Attach & Halt program in the dropdown next to the Power button on the top-left hand corner of the page.

   

6. Click Reset & Break at symbol next to the Play/Pause button on the top-left hand corner of the page.

   

   Note: This resets the MCU.

7. Run the image by clicking the Resume/Halt button on the top-left hand corner of the page.

Troubleshooting#

• Ignore the following window while reopening the Ozone Application and follow from step 2 to check for the SiWG917 debugging.

ETM Debugging on SiWx917#

Overview:#

The Embedded Trace Macrocell (ETM) is a specialized hardware block in some ARM processors. It's designed to assist in debugging and performance analysis of software running on the processor. The Embedded Trace Macrocell (ETM) is a valuable tool for software developers working with ARM processors.  An Embedded Trace Macrocell(ETM) is a real-time trace module providing instruction execution flow and data access patterns, for debugging and optimization. The operating frequency of the ETM in SiWx917 is greater than  or equal to 40 MHz. It is configured to operate at 120 MHz by default. The following page basically give an overview about ETM, and how to use it for debugging.

Functionality:#

The primary function of the ETM is to capture trace information about the program's execution as it runs on the processor. This trace information includes details about the instructions executed, the order in which they were executed, and sometimes additional data such as memory accesses and events.

Features:#

• Instruction Trace: The ETM captures a trace of the instructions executed by the processor. This allows developers to reconstruct the program's execution path.

• Branch Trace: It provides information about branches and other control flow changes in the program. This helps to understand the program behavior and optimize its performance.

• Timestamps: Some ETM implementations include timestamp information, which helps correlate events with specific points in time during program execution.

• Data Trace (Optional): In some configurations, the ETM also captures data accesses, providing insight into memory reads and writes during execution.

• Debugging Support: ETM greatly aids in post-mortem debugging. When a program crashes or exhibits unexpected behavior, the trace data can be invaluable for understanding what led to the issue.

Hardware Requirements:#

• A Windows PC

• Silicon Labs SiWx917 PK6030A SoC Kit which includes

  • BRD4001A/BRD4002A Wireless Starter Kit Mainboard

  • SiWx917 Radio Board Radio Board

• Segger J-Trace Pro

Software Requirements:#

• Simplicity Studio IDE

  • To download and install the Simplicity Studio IDE, refer to the Simplicity Studio IDE Set up section in Getting started with SiWx91x SoC guide.

  • SiWx917_WiSeConnect_SDK.x.x.x.x

• Ozone Debugger and performance analyzer Download here.

Configuration and Execution of the Application:#

The application can be configured to suit your requirements and development environment.

• First, add the ETM component on the respective project. Open the .slcp file. Under software component search ETM.

  

• Install the ETM component.

  

• After installing the ETM component you will be able to see ETM initialization function under sl_service_init().

  

• Build your application. For connecting the Ozone Debugger we need the .out file which is automatically generated upon building the application on simplicity studio.

• Make your board on "IN" mode.

  

• Open Ozone and you will see the following window. Click on Next.

  

• Choose your J-Trace PRO Cortex. Click on next.

  

• Give the path of your .out file which is generated upon building the application.

  

• Add the location of PC as 0x300001 and Stack pointer as 0x20000

  

• Now, click on View window and open the "Instruction Trace" window.

  

• Now open the Trace Settings and add the following configuration as shown in the figure.

  

• Now click on "Attach & Halt Program" option.

  

• Now click on Play button. You will be able to see Instruction Trace as shown below.