fassert.h File Reference

Assert macro implementation. More...

#include <stdbool.h>
#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	FAS_ASSERT_LOCATION_s
	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	FAS_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	FAS_ASSERT_LEVEL_INF_LOOP_FOR_DEBUG   (1u)
	This assert level traps the current task by going into an infinite loop. More...
#define	FAS_ASSERT_LEVEL_NO_OPERATION   (2u)
	This assert level does nothing (except for the standard recording of the assert location which does every level). More...
#define	FAS_ASSERT_LEVEL   FAS_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	FAS_STATIC_ASSERT(cond, msg)

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

Detailed Description

Assert macro implementation.

Copyright

© 2010 - 2023, Fraunhofer-Gesellschaft zur Foerderung der angewandten Forschung e.V. All rights reserved.

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

2023-02-03 (date of last update)

Version

v1.5.0

Prefix

FAS

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

• When the FAS_ASSERT_LEVEL symbol is defined as FAS_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 FAS_ASSERT_LEVEL symbol is defined as FAS_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 FAS_ASSERT_LEVEL symbol is defined as FAS_ASSERT_LEVEL_NO_OPERATION, the FAS_ASSERT macro is defined as empty and does nothing. It might be necessary to activate this mode in resource-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

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 FAS_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 250 of file fassert.h.

FAS_ASSERT_LEVEL

#define FAS_ASSERT_LEVEL   FAS_ASSERT_LEVEL_INF_LOOP_AND_DISABLE_INTERRUPTS

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

Definition at line 177 of file fassert.h.

FAS_ASSERT_LEVEL_INF_LOOP_AND_DISABLE_INTERRUPTS

#define FAS_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 168 of file fassert.h.

FAS_ASSERT_LEVEL_INF_LOOP_FOR_DEBUG

#define FAS_ASSERT_LEVEL_INF_LOOP_FOR_DEBUG   (1u)

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

Definition at line 169 of file fassert.h.

FAS_ASSERT_LEVEL_NO_OPERATION

#define FAS_ASSERT_LEVEL_NO_OPERATION   (2u)

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

Definition at line 170 of file fassert.h.

FAS_ASSERT_RECORD

#define FAS_ASSERT_RECORD

(

)

Value:

    do {                                       \
        uint32_t *pc = (uint32_t *)__curpc();  \
        FAS_StoreAssertLocation(pc, __LINE__); \
    } while (false)

Record the assert location.

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

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

Definition at line 224 of file fassert.h.

FAS_STATIC_ASSERT

#define FAS_STATIC_ASSERT	(		cond,
			msg
	)

Definition at line 284 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 129 of file fassert.h.

Function Documentation

__curpc()

static uint32_t __curpc ( void  )

inlinestatic

Definition at line 210 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 ( void  )

inlinestatic

Assert macro will trigger a watchdog reset

Definition at line 183 of file fassert.h.

Here is the call graph for this function:

FAS_StoreAssertLocation()

void FAS_StoreAssertLocation	(	uint32_t *	pc,
		uint32_t	line
	)

Copy the assert location into the assert struct.

Takes the location of the last assertion and stores it into the static 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 explicitly.

Parameters

[in]	pc	address of the program counter where the assertion occurred
[in]	line	line where the assertion occurred

Definition at line 72 of file fassert.c.