foxBMS - Unit Tests  1.2.0
The foxBMS Unit Tests API Documentation
fassert.h File Reference

Assert macro implementation. More...

#include <stdint.h>
#include "CException.h"
Include dependency graph for fassert.h:
This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Data Structures

struct  ASSERT_LOC
 Struct for storing assert information. More...
 

Macros

#define FAS_TRAP   (0u == 1u)
 Define that evaluates to essential boolean false thus tripping an assert. More...
 
#define ASSERT_LEVEL_INF_LOOP_AND_DISABLE_INTERRUPTS   (0u)
 This assert level traps the complete program by going into an infinite loop and disabling all interrupts. More...
 
#define ASSERT_LEVEL_INF_LOOP_FOR_DEBUG   (1u)
 This assert level traps the current task by going into an infinite loop. More...
 
#define ASSERT_LEVEL_NO_OP   (2u)
 This assert level does nothing (except for the standard recording of the assert location which does every level). More...
 
#define ASSERT_LEVEL   ASSERT_LEVEL_INF_LOOP_AND_DISABLE_INTERRUPTS
 Set the assert level to a standard value if not set by the build. More...
 
#define FAS_ASSERT_RECORD()
 Record the assert location. More...
 
#define FAS_ASSERT(x)
 Assertion macro that asserts that x is true. More...
 
#define static_assert(cond, msg)   _Static_assert(cond, msg)
 static assertion macro More...
 

Typedefs

typedef struct ASSERT_LOC ASSERT_LOC_s
 Struct for storing assert information. More...
 

Functions

void FAS_DisableInterrupts (void)
 Disable interrupts. More...
 
void fas_storeAssertLoc (uint32_t *pc, uint32_t line)
 Copy the assert location into the assert struct. More...
 
static void FAS_infiniteLoop ()
 
static uint32_t __curpc (void)
 

Variables

ASSERT_LOC_s fas_assertLocation
 Stores the information on the last assert. More...
 

Detailed Description

Assert macro implementation.

SPDX-License-Identifier: BSD-3-Clause

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

  1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
  2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
  3. Neither the name of the copyright holder nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

We kindly request you to use one or more of the following phrases to refer to foxBMS in your hardware, software, documentation or advertising materials:

  • ″This product uses parts of foxBMS®″
  • ″This product includes parts of foxBMS®″
  • ″This product is derived from foxBMS®″
Author
foxBMS Team
Date
2020-03-20 (date of creation)
Updated
2020-05-26 (date of last update)
Prefix
FAS

The default implementation accommodates three behaviors, based on ASSERT_LEVEL symbol:

  • When the ASSERT_LEVEL symbol is defined as ASSERT_LEVEL_INF_LOOP_AND_DISABLE_INTERRUPTS, the FAS_ASSERT macro is implemented as an infinite loop in which all interrupts are disabled. This will definitely trigger a watchdog reset.
  • When ASSERT_LEVEL symbol is defined as ASSERT_LEVEL_INF_LOOP_FOR_DEBUG, the validation performed by the FAS_ASSERT macro is enabled, and a failed validation triggers an infinite loop. This configuration is recommended for development environments, as it prevents further execution. Depending on the configuration this might lead to a watchdog reset. This mode is intended for investigation of problems by a developer.
  • When ASSERT_LEVEL symbol is defined as ASSERT_LEVEL_NO_OP, the FAS_ASSERT macro is defined as empty and does nothing. It might be necessary to activate this mode in ressource-constrained situations. Generally it is not recommended to use this option as it will not notice the undefined system-states that the assert should catch.

    Generally assertions should be used for asserting states and values that should occur when the program is executed correctly. Do not assert anything that might be false. As an example it is perfectly good practice to assert that the input to a function is not a null pointer if the function is not designed to accept null pointers, but it is not good to check if a communication error has occurred somewhere. Assertions should never trip in a bug-free program.

    Usage is FAS_ASSERT(condition that should be true).

Definition in file fassert.h.

Macro Definition Documentation

◆ ASSERT_LEVEL

Set the assert level to a standard value if not set by the build.

Definition at line 161 of file fassert.h.

◆ ASSERT_LEVEL_INF_LOOP_AND_DISABLE_INTERRUPTS

#define ASSERT_LEVEL_INF_LOOP_AND_DISABLE_INTERRUPTS   (0u)

This assert level traps the complete program by going into an infinite loop and disabling all interrupts.

Definition at line 152 of file fassert.h.

◆ ASSERT_LEVEL_INF_LOOP_FOR_DEBUG

#define ASSERT_LEVEL_INF_LOOP_FOR_DEBUG   (1u)

This assert level traps the current task by going into an infinite loop.

Definition at line 153 of file fassert.h.

◆ ASSERT_LEVEL_NO_OP

#define ASSERT_LEVEL_NO_OP   (2u)

This assert level does nothing (except for the standard recording of the assert location which does every level).

Definition at line 154 of file fassert.h.

◆ FAS_ASSERT

#define FAS_ASSERT (   x)
Value:
if (!(x)) \
Throw(0)

Assertion macro that asserts that x is true.

This macro asserts the taken argument x. If the assertion fails it calls FAS_ASSERT_RECORD() and then FAS_infiniteLoop().

In unit tests this is replace by an exception that is thrown in order to be able to test for a failed assertion.

Use this macro if you want to assert. If the assertion fails the macro will take action based on the configuration of this module. See ASSERT_LEVEL for reference.

If the macro passes, it is just ignored. If you want to definitely fail, you can use the value FAS_TRAP as an argument which is designed to fail in all cases.

Definition at line 233 of file fassert.h.

◆ FAS_ASSERT_RECORD

#define FAS_ASSERT_RECORD ( )
Value:
do { \
void *pc = __curpc(); \
fas_storeAssertLoc(pc, __LINE__); \
} while (0)
static uint32_t __curpc(void)
Definition: fassert.h:194

Record the assert location.

Retrieves the program counter (with __curpc()) and line-number at the current location and passes it to fas_storeAssertLoc().

It is important that this is a macro in order to insert it directly at he assert location in the code

Definition at line 207 of file fassert.h.

◆ FAS_TRAP

#define FAS_TRAP   (0u == 1u)

Define that evaluates to essential boolean false thus tripping an assert.

Call FAS_ASSERT() with this define in order to stop the code and trip an assertion.

Definition at line 108 of file fassert.h.

◆ static_assert

#define static_assert (   cond,
  msg 
)    _Static_assert(cond, msg)

static assertion macro

This macro maps static_assert to a compiler intrinsic. This will fail during compilation if the condition is not true.

Definition at line 252 of file fassert.h.

Typedef Documentation

◆ ASSERT_LOC_s

typedef struct ASSERT_LOC ASSERT_LOC_s

Struct for storing assert information.

This struct is intended for storing, information on the place in the code where an assert has been violated.

Function Documentation

◆ __curpc()

static uint32_t __curpc ( void  )
inlinestatic

Definition at line 194 of file fassert.h.

◆ FAS_DisableInterrupts()

void FAS_DisableInterrupts ( void  )

Disable interrupts.

This alias is mapped to an ASM function and disables all interrupts by writing to the SPSR (Saved Program Status Register) register through the control field mask byte PSR[7:0] (privileged software execution)

◆ FAS_infiniteLoop()

static void FAS_infiniteLoop ( )
inlinestatic

Assert macro will trigger a watchdog reset

Definition at line 167 of file fassert.h.

Here is the call graph for this function:

◆ fas_storeAssertLoc()

void fas_storeAssertLoc ( uint32_t *  pc,
uint32_t  line 
)

Copy the assert location into the assert struct.

Takes the location of the last assertion and writes it into fas_assertLocation. This definition has to be at this position in order to be used by the macros below. If you get issues in a unit test with this being not defined, try to add this header to the unit tests includes explicitely.

Parameters
[in]pcaddress of the program counter where the assertion occurred
[in]lineline where the assertion occurred

Definition at line 70 of file fassert.c.

Variable Documentation

◆ fas_assertLocation

ASSERT_LOC_s fas_assertLocation
extern

Stores the information on the last assert.

Definition at line 63 of file fassert.c.