Assertions

The UltraZohm uses assertions to handle errors.

Warning

The UltraZohm error handling follows the concept to fail loudly, i.e., all assertions stop the processor and require a power cycle (and code changes to fix the bug that caused the failing assertion).

Reference

uz_assert(Expression): Asserts that the condition is true. If false, the assertion callback executes (program is stopped).

uz_assert_not_NULL(Expression): Asserts that the argument is not a NULL pointer.

uz_assert_not_zero_uint32(Expression): Asserts that the argument of type uint32_t is not zero (!=0).

uz_assert_not_zero_int32(Expression): Asserts that the argument of type int32_t is not zero (!=0).

uz_assert_not_zero_int(Expression): Asserts that the argument of type int is not zero (!=0).

uz_assert_not_zero_unsigned_int(Expression): Asserts that the argument of type unsigned int is not zero (!=0).

uz_assert_false(Expression): Asserts that the argument is false.

How to use

Use assertions to guarantee that the conditions and limits of a function are met at runtime. Use uz_assert() or uz_assert_not_NULL() from the Hardware Abstraction Layer.

Example code:

#include "uz/HAL.h"
#define LIMIT 10

function void fnc(int *foo, int bar){
    uz_assert_not_NULL(foo);
    uz_assert(bar < LIMIT);
    // do something
};

If the assertion fails, the following message is printed to the serial console to see where the assertions failed:

Assertion in file /home/ts/Dokumente/ultrazohm_testbench/ultrazohm_sw/vitis/software/Baremetal/src/main.c on line 135

Assertion callback

The assertion callback tells the UltraZohm to execute the function uz_assertCallback if an assertion fires:

Xil_AssertSetCallback((Xil_AssertCallback) uz_assertCallback);

The function uz_assertCallback prints the file and line to the terminal in which the assertion failed. Furthermore, the callback turns the system and the ISR off. Use the Vitis Serial Terminal to display the messages. After that, the system is kept in an infinite error loop. To reset the error, you have to reboot. Note that there is no error handling / exceptions since assertions are used to prevent wrong function calls which have to be fixed in the source code. Common examples are the passing of NULL pointers or passing wrong arguments to init function (e.g. wrong base address, violation of min/max values).

Implementation

The implementation relies on xil_assert.h (part of libmetal). While xil_assert.h provides assert makros (e.g., Xil_AssertVoid), these use return in the marko. This results in multiple warnings, MISRA violations and causes bugs in functions that return a struct. Thus, we do not use them! The uz_assert makro is function like but has to be implemented as a makro to use __FILE__ and __LINE. The uz_assert makro is wraped in a do{..}while(0) statement to ensure the right behavior regarding ;

Further information: