In the last several posts, we have been exploring debug capabilities related to setting up and using printf along with the real-time issues associated with it. There may be times in our software where we want to verify that conditions in the software are what we expect them to be. If the conditions are different, then a bug may exist in our software. In these instances, developers can use assertions. In today’s post, we are going to explore assertions and how to use them in our Synergy applications.
An assertion is a boolean (true/false) expression at a specific point in a program that will be true unless there is a bug in the program. Assertions can be used in many ways within an application but the most common use is to verify pre-conditions and post-conditions within a function call. It is important to note that assertions are not for error handling but for detecting bugs in an application. Developers will write their error handlers for handling issues such as files not existing on a memory devices and not use assertions for those purposes.
There are several advantages to using assertions in a real-time embedded application. First, an assertion will halt the program from executing any further when a condition is evaluated to be false. This means that a developer doesn’t have to wait a few million or billion clock cycles before they finally see the bug rear its head and manifest itself in an external and visible manner. Instead, the program is halted and a simple message is printed out, using printf, that states the failed assertions file and line number. The bug is spotted immediately! For example, below is a quick screen shot that shows a failed assertion in the Renesas Debug Virtual Console:
You can clearly see the printf output from the assertion is:
File ../src/blinky_thread_entry.c, Line 43, Function blinky_thread_entry, Error Code count ==1
Bug hunting is hardly ever that explicit! We know the exact file, line number and the condition that failed. Now it’s just up to the developer to determine why the assertion failed.
Assertions can certainly be used to improve software quality and to discover bugs when they actually occur but there are several potential issues that developers need to be aware of. First, the assertion will stop program execution which means if you are running a real-time system such as a motor, actuator, etc, it’s possible that bad things could happen if the program execution just stops. Next, assertions do require a few clock cycles to evaluate the expression under test. This means that if you test with assertions and then compile them out for production, you’ve just changed the systems real-time behavior! Make sure that you test what you plan to put into production. Finally, developers should understand that assertions do not handle or check for errors! They only make sure that program conditions are as expected such as a function parameter is within a certain range or that a clock has been enabled.
Assertions can be a very powerful tool for developers to utilize in their software. In fact, the Synergy team uses their own custom assertions to verify driver and framework conditions as can be seen below in the R_IOPORT_Init function:
Notice how there is a SSP_ASSERT macro that is used to verify that the configuration pointer is not NULL along with the pin configuration data. Not populating these configuration parameters means that the pre-conditions for the R_IOPORT_Init function have not been met and that there is a bug in the application code. Also notice that the SSP_ASSERT checks can be disabled by setting the IOPORT_CFG_PARAM_CHECKING_ENABLE configuration option that is found in the driver Synergy Configurator.
In the next post, I will show you how to setup and use assertions in your own Synergy applications.
Until next time,
Live long and profit!
Hot Tip of the Week
Have you checked out the most recently published Module Guides? Remember you can always find them but accessing this web page: https://www.renesas.com/en-us/products/synergy/tools-kits.html#documents.
As of Dec 14th newly published module guides include: