Skip to end of metadata
Go to start of metadata

The Common module offers assert capabilities that can be used in various situations in your application. For more information on asserts in general, please refer to Assertions.

Macro Calls

The APP_RTOS_ASSERT_CRITICAL() and APP_RTOS_ASSERT_DBG() macros check if a given expression is evaluated with a positive result. If the result is not positive, the macro will do one of the following operations:

  • If RTOS_CFG_RTOS_ASSERT_CRITICAL_FAILED_END_CALL(ret_val) and/or RTOS_CFG_RTOS_ASSERT_DBG_FAILED_END_CALL(ret_val) are defined, the macro will call these.
  • If they are not defined, CPU_SW_EXCEPTION(ret_val) will be called.

The debug asserts typically check for conditions that are caused by invalid parameters or invalid configurations. They are used to notify the developer that something is not correct with the way the code is being used. Those can and should be disabled once development is completed.

The critical asserts typically check for conditions from which it is practically impossible to recover at run-time. Therefore, if such a condition is detected, the program's execution should be suspended before any more damage occurs.

An example of an assert using the macros is provided below.

#include  <rtos/common/include/rtos_utils.h>
 
                                                          /* These are the only valid values for this example. */
#define  VALUE_FIRST    1u
#define  VALUE_SECOND   2u
#define  VALUE_THIRD    3u
 
void  *ExAssert (CPU_INT08U  value)
{
                                                          /* Make sure arg passed is one of the valid values.  */
    APP_RTOS_ASSERT_DBG(((value == VALUE_FIRST)  ||
                         (value == VALUE_SECOND) ||
                         (value == VALUE_THIRD)), DEF_NULL);
                                                          /* Indicate a value to return in case of failure.    */
 
    /* ... */
 
    return (DEF_NULL);
}
Listing - Assert call example

Macro Fail Calls

These macro calls are intended to be used when an assert must be triggered without checking any additional expression results.

For example, ending in the default case of a switch statement when all known types have their specific case could be considered a critical failure. In these cases, you should use the APP_RTOS_ASSERT_CRITICAL_FAIL() and APP_RTOS_ASSERT_DBG_FAIL() macros. An example is provided below.

#include  <rtos/common/include/rtos_utils.h>

                                                       /* These are the only valid values for this example.    */
#define  VALUE_FIRST    1u
#define  VALUE_SECOND   2u
#define  VALUE_THIRD    3u
 
void  ExAssertFail (CPU_INT08U  value)
{
    CPU_INT08U  flag;

    switch (value) {
        case VALUE_FIRST:
        case VALUE_SECOND:
             flag = DEF_YES;
             break;
 
        case VALUE_THIRD:
             flag = DEF_NO;
             break;
 
        default:                                       /* Dflt case reached means an invalid arg was passed.   */
                                                       /* Call APP_RTOS_ASSERT_DBG_FAIL() to indicate err.     */
            APP_RTOS_ASSERT_DBG_FAIL(;);               /* Indicate ; as return value if function returns void. */
    }
    /* ... */
}
Listing - Assert fail call example

  • No labels