foxBMS  1.0.0
The foxBMS Battery Management System API Documentation
sbc_fs8x_assert.h
Go to the documentation of this file.
1 /*
2  * Copyright (c) 2015, Freescale Semiconductor, Inc.
3  * Copyright 2016-2018 NXP
4  * All rights reserved.
5  *
6  * THIS SOFTWARE IS PROVIDED BY NXP "AS IS" AND ANY EXPRESSED OR
7  * IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
8  * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
9  * IN NO EVENT SHALL NXP OR ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT,
10  * INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
11  * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
12  * SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
13  * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
14  * STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING
15  * IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF
16  * THE POSSIBILITY OF SUCH DAMAGE.
17  */
18 
19 /** @file sbc_fs8x_assert.h
20  * @brief Assertion macro definition, for debugging purposes.
21  *
22  * @author nxf44615
23  * @version 1.1
24  * @date 9-Oct-2018
25  * @copyright Copyright (c) 2016 - 2018, NXP Semiconductors, Inc.
26  *
27  * @updated 2020-03-18 (date of last update)
28  * Adapted driver to pass interface configuration as parameter into the
29  * functions to enable the usage of multiple ICs in the system.
30  */
31 
32 #ifndef SBC_FS8X_ASSERT_H_
33 #define SBC_FS8X_ASSERT_H_
34 
35 #include <stdbool.h>
36 
37 /** @page misra_violations MISRA-C:2012 violations
38  *
39  * Violates MISRA 2012 Advisory Rule 2.5, global macro not referenced.
40  * The macro is defined to be used by drivers to validate input parameters and can be disabled.
41  *
42  * Violates MISRA 2012 Advisory Directive 4.9, Function-like macro defined.
43  * The macros are used to validate input parameters to driver functions.
44  *
45  */
46 
47 /** @page Error_detection_and_reporting Error detection and reporting
48 
49 FS8x driver can use a mechanism to validate data coming from upper software layers (application code) by performing
50 a number of checks on input parameters' range or other invariants that can be statically checked (not dependent on
51 runtime conditions). A failed validation is indicative of a software bug in application code, therefore it is important
52 to use this mechanism during development.
53 
54 The validation is performed by using FS_ASSERT macro.
55 A default implementation of this macro is provided in this file. However, application developers can provide their own
56 implementation in a custom file. This requires defining the CUSTOM_DEVASSERT symbol with the specific file name in the
57 project configuration (for example: -DCUSTOM_DEVASSERT="custom_devassert.h")
58 
59 The default implementation accommodates two behaviors, based on DEV_ERROR_DETECT symbol:
60  - When DEV_ERROR_DETECT symbol is defined in the project configuration (for example: -DDEV_ERROR_DETECT), the validation
61  performed by the FS_ASSERT macro is enabled, and a failed validation triggers an infinite loop.
62  This configuration is recommended for development environments, as it prevents further execution and allows investigating
63  potential problems from the point of error detection.
64  - When DEV_ERROR_DETECT symbol is not defined, the FS_ASSERT macro is implemented as no-op, therefore disabling all validations.
65  This configuration can be used to eliminate the overhead of development-time checks.
66 
67 It is the application developer's responsibility to decide the error detection strategy for production code: one can opt to
68 disable development-time checking altogether (by not defining DEV_ERROR_DETECT symbol), or one can opt to keep the checks
69 in place and implement a recovery mechanism in case of a failed validation, by defining CUSTOM_DEVASSERT to point
70 to the file containing the custom implementation.
71 */
72 
73 /**
74  * @def FS_ASSERT(x)
75  * @brief Assert macro for the SBC
76  */
77 #if defined CUSTOM_DEVASSERT
78  /* If the CUSTOM_DEVASSERT symbol is defined, then add the custom implementation */
79  #include "custom_devassert.h"
80 #elif defined (DEV_ERROR_DETECT)
81  /* Implement default assert macro */
82 static inline void FsDevAssert(volatile bool x)
83 {
84  if(x) { } else { for(;;) {} }
85 }
86  #define FS_ASSERT(x) FsDevAssert(x)
87 #else
88  /* Assert macro does nothing */
89  #define FS_ASSERT(x) ((void)0)
90 #endif
91 
92 
93 #endif /* SBC_FS8X_ASSERT_H_ */