Debugging Renesas Synergy™ Software Applications: Understanding Error Codes

Debugging a real-time application can be a daunting task for embedded software developers. In the good old days, systems were simple and bare-metal. A single developer could easily write every line of code for the application and still get the project delivered on-time. Embedded systems have changed. Products have become extraordinarily complex not just in their feature sets but in their timing and connectivity requirements. Leveraging platforms such as the Renesas Synergy™ Platform is a huge relief for developers but at the same time, the abstractions leave developers in the dark on much of the low-level code. These challenges can make debugging stressful and time consuming if developers haven’t mastered debugging skills. In this blog and series, we will discuss and explore how to quickly and efficiently debug Synergy Software Package based applications and fine tune the readers debugging skills.

Thinking back to software 101, the first concepts that are drilled into a developer’s mind are that they should

  • Check their inputs
  • Verify their output
  • Validate return values

These three concepts are great software engineering advice and the Synergy Software Package adheres to these concepts. For example, drivers and frameworks use SSP assertions to verify that inputs and preconditions have been met before running the code in each function. What is even more important, is that these functions return an error code.

The first line of defense for any developer is to check the error code that is returned by calling an SSP function. Capturing the return value is simple. A developer can use the following steps:

  • Declare a variable of type ssp_err_t
  • Use that variable to capture a function return value
  • Check the return value against SSP_SUCCESS or a desired error code

For example, if a developer were trying initialize the downloader software framework that is included in the flashloader application project, they would check whether the initialization was successful or not by doing the following:

    ssp_err_t err;

    err = g_sf_downloader0.p_api->open(g_sf_downloader0.p_ctrl, g_sf_downloader0.p_cfg);

    if (SSP_SUCCESS != err) { __BKPT(0); }

In this example, if the downloader is unable to initialize successfully, then a breakpoint instruction is Using a break-point instruction in this manner is a great way to detect errors during development. In a production system, a developer would want to replace these instructions with an error recovery mechanism to handle the error. The exact strategy used will vary based on the application.

The Synergy Platform has several different error code types. These include:

  • Common errors
  • Module specific errors

The common errors are defined in ssp_common_api.h which is located in Synergy > SSP. These common errors are used across the entire Synergy Platform. For example, SSP_SUCCESS is returned if the operation was performed without issues. If an assertion has failed, a module would return SSP_ERR_ASSERTION. There are several dozen error codes defined in ssp_common_api.h that all belong to the e_ssp_err enumeration. A few examples can be seen below:

 

The enumeration e_ssp_err contains all the common errors that might be returned by a module. Specific drivers or frameworks may have additional return values or error codes that they return. For example, the flash driver defines a few additional results that its own functions might return as shown below:

 

Any module specific return codes will be defined in the modules API header file. For example, the flashloader framework api file, sf_firmware_image_api.h, defines several addition error codes that are typecast to ssp_err_t. These error definitions can be seen below:

 

The best way to find these uncommon error codes is to either review the api header file or review the modules documentation.

Checking and acting on return variables is the first step Synergy developers should take to catching potential bugs and errors in their application code. Error codes can illuminate an issue the second that it occurs rather than waiting for the entire application to crash and attempting to trace back the cause. Synergy error codes are specific and will help developers discover where potential configuration issues have occurred which they can then resolve.

In the next post, we’ll discuss the break-point capabilities that are built into the Synergy development environment and how they can be used to quickly and efficiently navigate code in real-time.

 

Until next time,

Live long and profit!

Professor_IoT

 

Hot Tip of the Week

If you are interested in learning more about using Breakpoints when debugging Synergy projects you can read over this application note: https://www.renesas.com/en-us/doc/products/renesas-synergy/apn/r11an0062eu0100-synergy-uses-of-breakpoints.pdf

This document provides the best hints on how to debug your application faster and make use of each one of the available breakpoints and covers code, conditional, data, read and write, log and power breakpoints. It is an invaluable introduction of the powerful capabilities breakpoints provide when debugging.