foxBMS  1.1.2
The foxBMS Battery Management System API Documentation
general.h
Go to the documentation of this file.
1 /**
2  *
3  * @copyright © 2010 - 2021, Fraunhofer-Gesellschaft zur Foerderung der angewandten Forschung e.V.
4  * All rights reserved.
5  *
6  * SPDX-License-Identifier: BSD-3-Clause
7  *
8  * Redistribution and use in source and binary forms, with or without
9  * modification, are permitted provided that the following conditions are met:
10  *
11  * 1. Redistributions of source code must retain the above copyright notice, this
12  * list of conditions and the following disclaimer.
13  *
14  * 2. Redistributions in binary form must reproduce the above copyright notice,
15  * this list of conditions and the following disclaimer in the documentation
16  * and/or other materials provided with the distribution.
17  *
18  * 3. Neither the name of the copyright holder nor the names of its
19  * contributors may be used to endorse or promote products derived from
20  * this software without specific prior written permission.
21  *
22  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
23  * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
24  * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
25  * DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
26  * FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
27  * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
28  * SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
29  * CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
30  * OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
31  * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
32  *
33  * We kindly request you to use one or more of the following phrases to refer to
34  * foxBMS in your hardware, software, documentation or advertising materials:
35  *
36  * - ″This product uses parts of foxBMS®″
37  * - ″This product includes parts of foxBMS®″
38  * - ″This product is derived from foxBMS®″
39  *
40  */
41 
42 /**
43  * @file general.h
44  * @author foxBMS Team
45  * @date 2019-09-24 (date of creation)
46  * @updated 2021-07-29 (date of last update)
47  * @ingroup GENERAL_CONF
48  * @prefix NONE
49  *
50  * @brief General macros and definitions for the whole platform.
51  *
52  */
53 
54 #ifndef FOXBMS__GENERAL_H_
55 #define FOXBMS__GENERAL_H_
56 
57 /*========== Includes =======================================================*/
58 #include "HL_sys_common.h"
59 
60 #include "fassert.h"
61 #include "fstd_types.h"
62 
63 #include <stdbool.h>
64 #include <stdint.h>
65 
66 /*========== Macros and Definitions =========================================*/
67 
68 /**
69  * @brief largest pin number that exists in TMS570LC4357
70  * @details Checked in the datasheet spnu563a: The largest pin number that is
71  * used is 31.
72 */
73 #define LARGEST_PIN_NUMBER (31u)
74 
75 /**
76  * @brief sets a bit to 1u
77  * @param[in,out] register register on which to set the bit
78  * @param[in] bit number of the bit that should be set to 1u
79  */
80 #define SETBIT(register, bit) ((register) |= (uint32)((uint32)1U << (bit)))
81 /**
82  * @brief clears a bit to 0u
83  * @param[in,out] register register on which to clear the bit
84  * @param[in] bit number of the bit that should be cleared to 0u
85  */
86 #define CLEARBIT(register, bit) ((register) &= ~(uint32)((uint32)1U << (bit)))
87 
88 /**
89  * @brief Allows functions to generate warnings in GCC for unused returns.
90  *
91  * This attribute allows to mark that a function return value must be used.
92  * The compiler will generate a warning when the return value of a function
93  * with this marker is not used in subsequent code.
94  */
95 #define must_check_return __attribute__((warn_unused_result))
96 
97 /** This attribute tells the compiler that the function should always be inlined */
98 #define always_inline __attribute__((always_inline))
99 
100 /** allow implementations to be weak for unit tests */
101 #ifdef UNITY_UNIT_TEST
102 #define UNIT_TEST_WEAK_IMPL __attribute__((weak))
103 #else
104 #define UNIT_TEST_WEAK_IMPL
105 #endif
106 
107 /* assert that the basic datatypes in fstd_types.h are intact */
108 /* AXIVION Disable Style MisraC2012-10.4: These assertions have to check the actual values of the enums and defines. */
109 static_assert(false == 0, "false seems to have been modified.");
110 static_assert(true != false, "true seems to have been modified.");
111 static_assert(true == 1, "true seems to have been modified.");
112 
113 static_assert(STD_OK == 0, "STD_OK seems to have been modified.");
114 static_assert(STD_OK != STD_NOT_OK, "STD_OK or STD_NOT_OK seem to have been modified.");
115 static_assert(STD_NOT_OK == 1, "STD_NOT_OK seems to have been modified.");
116 /* AXIVION Enable Style MisraC2012-10.4: */
117 
118 /**
119  * Internal macros for the implementation of #REPEAT_U(). Do not use outside.
120  * @{
121  */
122 /* AXIVION Disable Style Generic-NoUnsafeMacro MisraC2012Directive-4.9: Due to the nature of these macros
123  it is impossible to wrap the REPEAT_Uxu(x) token in parentheses. With these
124  function-like Macros repeating a token is implemented. */
125 #define REPEAT_U1u(x) (x)
126 #define REPEAT_U2u(x) REPEAT_U1u(x), (x)
127 #define REPEAT_U3u(x) REPEAT_U2u(x), (x)
128 #define REPEAT_U4u(x) REPEAT_U3u(x), (x)
129 #define REPEAT_U5u(x) REPEAT_U4u(x), (x)
130 #define REPEAT_U6u(x) REPEAT_U5u(x), (x)
131 #define REPEAT_U7u(x) REPEAT_U6u(x), (x)
132 #define REPEAT_U8u(x) REPEAT_U7u(x), (x)
133 #define REPEAT_U9u(x) REPEAT_U8u(x), (x)
134 #define REPEAT_U10u(x) REPEAT_U9u(x), (x)
135 #define REPEAT_U11u(x) REPEAT_U10u(x), (x)
136 #define REPEAT_U12u(x) REPEAT_U11u(x), (x)
137 #define REPEAT_U13u(x) REPEAT_U12u(x), (x)
138 #define REPEAT_U14u(x) REPEAT_U13u(x), (x)
139 #define REPEAT_U15u(x) REPEAT_U14u(x), (x)
140 #define REPEAT_U16u(x) REPEAT_U15u(x), (x)
141 #define REPEAT_U17u(x) REPEAT_U16u(x), (x)
142 #define REPEAT_U18u(x) REPEAT_U17u(x), (x)
143 #define REPEAT_U19u(x) REPEAT_U18u(x), (x)
144 #define REPEAT_U20u(x) REPEAT_U19u(x), (x)
145 #define REPEAT_U21u(x) REPEAT_U20u(x), (x)
146 #define REPEAT_U22u(x) REPEAT_U21u(x), (x)
147 #define REPEAT_U23u(x) REPEAT_U22u(x), (x)
148 #define REPEAT_U24u(x) REPEAT_U23u(x), (x)
149 #define REPEAT_U25u(x) REPEAT_U24u(x), (x)
150 #define REPEAT_U26u(x) REPEAT_U25u(x), (x)
151 #define REPEAT_U27u(x) REPEAT_U26u(x), (x)
152 #define REPEAT_U28u(x) REPEAT_U27u(x), (x)
153 #define REPEAT_U29u(x) REPEAT_U28u(x), (x)
154 #define REPEAT_U30u(x) REPEAT_U29u(x), (x)
155 #define REPEAT_U31u(x) REPEAT_U30u(x), (x)
156 #define REPEAT_U32u(x) REPEAT_U31u(x), (x)
157 #define REPEAT_U33u(x) REPEAT_U32u(x), (x)
158 #define REPEAT_U34u(x) REPEAT_U33u(x), (x)
159 #define REPEAT_U35u(x) REPEAT_U34u(x), (x)
160 #define REPEAT_U36u(x) REPEAT_U35u(x), (x)
161 #define REPEAT_U37u(x) REPEAT_U36u(x), (x)
162 #define REPEAT_U38u(x) REPEAT_U37u(x), (x)
163 #define REPEAT_U39u(x) REPEAT_U38u(x), (x)
164 #define REPEAT_U40u(x) REPEAT_U39u(x), (x)
165 #define REPEAT_U41u(x) REPEAT_U40u(x), (x)
166 #define REPEAT_U42u(x) REPEAT_U41u(x), (x)
167 #define REPEAT_U43u(x) REPEAT_U42u(x), (x)
168 #define REPEAT_U44u(x) REPEAT_U43u(x), (x)
169 #define REPEAT_U45u(x) REPEAT_U44u(x), (x)
170 #define REPEAT_U46u(x) REPEAT_U45u(x), (x)
171 #define REPEAT_U47u(x) REPEAT_U46u(x), (x)
172 #define REPEAT_U48u(x) REPEAT_U47u(x), (x)
173 #define REPEAT_U49u(x) REPEAT_U48u(x), (x)
174 #define REPEAT_U50u(x) REPEAT_U49u(x), (x)
175 #define REPEAT_U51u(x) REPEAT_U50u(x), (x)
176 #define REPEAT_U52u(x) REPEAT_U51u(x), (x)
177 #define REPEAT_U53u(x) REPEAT_U52u(x), (x)
178 #define REPEAT_U54u(x) REPEAT_U53u(x), (x)
179 #define REPEAT_U55u(x) REPEAT_U54u(x), (x)
180 #define REPEAT_U56u(x) REPEAT_U55u(x), (x)
181 #define REPEAT_U57u(x) REPEAT_U56u(x), (x)
182 #define REPEAT_U58u(x) REPEAT_U57u(x), (x)
183 #define REPEAT_U59u(x) REPEAT_U58u(x), (x)
184 #define REPEAT_U60u(x) REPEAT_U59u(x), (x)
185 #define REPEAT_U61u(x) REPEAT_U60u(x), (x)
186 #define REPEAT_U62u(x) REPEAT_U61u(x), (x)
187 #define REPEAT_U63u(x) REPEAT_U62u(x), (x)
188 #define REPEAT_U64u(x) REPEAT_U63u(x), (x)
189 #define REPEAT_U65u(x) REPEAT_U64u(x), (x)
190 #define REPEAT_U66u(x) REPEAT_U65u(x), (x)
191 #define REPEAT_U67u(x) REPEAT_U66u(x), (x)
192 #define REPEAT_U68u(x) REPEAT_U67u(x), (x)
193 #define REPEAT_U69u(x) REPEAT_U68u(x), (x)
194 #define REPEAT_U70u(x) REPEAT_U69u(x), (x)
195 #define REPEAT_U71u(x) REPEAT_U70u(x), (x)
196 #define REPEAT_U72u(x) REPEAT_U71u(x), (x)
197 #define REPEAT_U73u(x) REPEAT_U72u(x), (x)
198 #define REPEAT_U74u(x) REPEAT_U73u(x), (x)
199 #define REPEAT_U75u(x) REPEAT_U74u(x), (x)
200 #define REPEAT_U76u(x) REPEAT_U75u(x), (x)
201 #define REPEAT_U77u(x) REPEAT_U76u(x), (x)
202 #define REPEAT_U78u(x) REPEAT_U77u(x), (x)
203 #define REPEAT_U79u(x) REPEAT_U78u(x), (x)
204 #define REPEAT_U80u(x) REPEAT_U79u(x), (x)
205 #define REPEAT_U81u(x) REPEAT_U80u(x), (x)
206 #define REPEAT_U82u(x) REPEAT_U81u(x), (x)
207 #define REPEAT_U83u(x) REPEAT_U82u(x), (x)
208 #define REPEAT_U84u(x) REPEAT_U83u(x), (x)
209 #define REPEAT_U85u(x) REPEAT_U84u(x), (x)
210 #define REPEAT_U86u(x) REPEAT_U85u(x), (x)
211 #define REPEAT_U87u(x) REPEAT_U86u(x), (x)
212 #define REPEAT_U88u(x) REPEAT_U87u(x), (x)
213 #define REPEAT_U89u(x) REPEAT_U88u(x), (x)
214 #define REPEAT_U90u(x) REPEAT_U89u(x), (x)
215 #define REPEAT_U91u(x) REPEAT_U90u(x), (x)
216 #define REPEAT_U92u(x) REPEAT_U91u(x), (x)
217 #define REPEAT_U93u(x) REPEAT_U92u(x), (x)
218 #define REPEAT_U94u(x) REPEAT_U93u(x), (x)
219 #define REPEAT_U95u(x) REPEAT_U94u(x), (x)
220 #define REPEAT_U96u(x) REPEAT_U95u(x), (x)
221 #define REPEAT_U97u(x) REPEAT_U96u(x), (x)
222 #define REPEAT_U98u(x) REPEAT_U97u(x), (x)
223 #define REPEAT_U99u(x) REPEAT_U98u(x), (x)
224 
225 /* AXIVION Disable Style MisraC2012-20.10: Usage allowed as long as remarks in documentation are honored. */
226 #define REPEAT_Ux(x, n) REPEAT_U##n(x)
227 /* AXIVION Enable Style Generic-NoUnsafeMacro MisraC2012Directive-4.9 MisraC2012-20.10: */
228 /**@}*/
229 
230 /** Maximum number of supported repetitions in #REPEAT_U(). Adapt if you change implementation.*/
231 #define REPEAT_MAXIMUM_REPETITIONS (99u)
232 
233 /**
234  * @brief Macro that helps to generate a series of literals (for array initializers).
235  * @details This macro generates a series of literals for array initializers.
236  * This can be used for initializing arrays to arbitrary non-null values
237  * when their size is defined with a macro. If the array shall be initialized
238  * to null the standard {0} should be used.
239  *
240  * @param x token that should be repeated, e.g. true
241  * @param n Times that it should be repeated (stripped of parenthesis with
242  * #STRIP() and described as unsigned integer literal) (maximum 16,
243  * #REPEAT_MAXIMUM_REPETITIONS, repetitions)
244  *
245  * Example usage:
246  \verbatim
247  #define ARRAY_SIZE (4u)
248  bool variable[ARRAY_SIZE] = {REPEAT_U(false, STRIP(ARRAY_SIZE))};
249  \endverbatim
250  * This will expand to:
251  \verbatim
252  bool variable[ARRAY_SIZE] = {false, false, false, false};
253  \endverbatim
254  */
255 /* AXIVION Disable Style MisraC2012Directive-4.9: Function-like macro needed for this feature. */
256 #define REPEAT_U(x, n) REPEAT_Ux(x, n)
257 /* AXIVION Enable Style MisraC2012Directive-4.9: */
258 
259 /** Internal helper macros for #STRIP(). Do not use outside.
260  * @{
261  */
262 /* AXIVION Disable Style MisraC2012Directive-4.9 MisraC2012-20.7 Generic-NoUnsafeMacro: Function-like macro needed for
263  this feature. Parenthesis stripping is intended here. */
264 #define GET_ARGS(...) __VA_ARGS__
265 #define STRIP_PARENS(x) x
266 /**@}*/
267 /** Strips a token of its surrounding parenthesis. */
268 #define STRIP(x) STRIP_PARENS(GET_ARGS x)
269 /* AXIVION Enable Style MisraC2012Directive-4.9 MisraC2012-20.7 Generic-NoUnsafeMacro: */
270 
271 /*========== Extern Constant and Variable Declarations ======================*/
272 
273 /*========== Extern Function Prototypes =====================================*/
274 
275 /*========== Externalized Static Functions Prototypes (Unit Test) ===========*/
276 
277 #endif /* FOXBMS__GENERAL_H_ */
Assert macro implementation.
#define static_assert(cond, msg)
static assertion macro
Definition: fassert.h:252
Definition of foxBMS standard types.
@ STD_NOT_OK
Definition: fstd_types.h:73
@ STD_OK
Definition: fstd_types.h:72