foxBMS  1.5.0
The foxBMS Battery Management System API Documentation
database.h
Go to the documentation of this file.
1 /**
2  *
3  * @copyright © 2010 - 2023, 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 database.h
44  * @author foxBMS Team
45  * @date 2015-08-18 (date of creation)
46  * @updated 2023-02-03 (date of last update)
47  * @version v1.5.0
48  * @ingroup ENGINE
49  * @prefix DATA
50  *
51  * @brief Database module header
52  *
53  * @details Provides interfaces to database module
54  *
55  */
56 
57 #ifndef FOXBMS__DATABASE_H_
58 #define FOXBMS__DATABASE_H_
59 
60 /*========== Includes =======================================================*/
61 #include "database_cfg.h"
62 
63 #include "database_helper.h"
64 #include "fstd_types.h"
65 #include "os.h"
66 
67 #include <stdint.h>
68 
69 /*========== Macros and Definitions =========================================*/
70 
71 /**
72  * Maximum number of database entries that can be read or written during one
73  * access call to the database
74  */
75 #define DATA_MAX_ENTRIES_PER_ACCESS (4u)
76 
77 #define DATA_ENTRY_0 (0u)
78 #define DATA_ENTRY_1 (1u)
79 #define DATA_ENTRY_2 (2u)
80 #define DATA_ENTRY_3 (3u)
81 
82 /** helper macro for the variadic macros for read and write functions */
83 /* AXIVION Next Codeline Style Generic-NoUnsafeMacro: unsafe macro is needed for variadic macro magic */
84 #define GET_MACRO(_1, _2, _3, _4, NAME, ...) (NAME)
85 /** variadic macro for read access to the database */
86 #define DATA_READ_DATA(...) \
87  GET_MACRO( \
88  __VA_ARGS__, \
89  DATA_Read4DataBlocks, \
90  DATA_Read3DataBlocks, \
91  DATA_Read2DataBlocks, \
92  DATA_Read1DataBlock, \
93  DATA_DummyFunction) \
94  (__VA_ARGS__)
95 /** variadic macro for write access to the database */
96 #define DATA_WRITE_DATA(...) \
97  GET_MACRO( \
98  __VA_ARGS__, \
99  DATA_Write4DataBlocks, \
100  DATA_Write3DataBlocks, \
101  DATA_Write2DataBlocks, \
102  DATA_Write1DataBlock, \
103  DATA_DummyFunction) \
104  (__VA_ARGS__)
105 
106 /**
107  * @brief data block access types (read or write)
108  */
109 typedef enum {
110  DATA_WRITE_ACCESS, /**< write access to data block */
111  DATA_READ_ACCESS, /**< read access to data block */
113 
114 /** dummy value for the built-in self-test (alternating bit pattern) */
115 #define DATA_DUMMY_VALUE_UINT8_T_ALTERNATING_BIT_PATTERN ((uint8_t)0xAAu)
116 
117 /**
118  * struct for database queue, contains pointer to data, database entry and access type
119  */
120 typedef struct {
121  DATA_BLOCK_ACCESS_TYPE_e accessType; /*!< read or write access type */
122  void *pDatabaseEntry[DATA_MAX_ENTRIES_PER_ACCESS]; /*!< reference by general pointer */
124 
125 /*========== Extern Constant and Variable Declarations ======================*/
126 
127 /*========== Extern Function Prototypes =====================================*/
128 /**
129  * @brief Dummy void function of the database module
130  * @details This function is needed in the database module in order to
131  * implement the #DATA_READ_DATA() and #DATA_WRITE_DATA() in a ISO C99
132  * standard compatible way. The invocation of a macro that accepts a
133  * variable number of arguments (and this is the case for
134  * #DATA_READ_DATA() and #DATA_WRITE_DATA()) needs more arguments in the
135  * invocation than there are parameters in the macro definition. For
136  * the most simple case, that #DATA_READ_DATA() and #DATA_WRITE_DATA() are
137  * only called with one argument, a violation of the standard would
138  * appear if the #DATA_DummyFunction() would be omitted:
139  * GET_MACRO(databaseVariable,
140  * DATA_Read4DataBlocks,
141  * DATA_Read3DataBlocks,
142  * DATA_Read2DataBlocks,
143  * DATA_Read2DataBlocks,
144  * DATA_Read1DataBlock)(databaseVariable)
145  * So the macro invocation has six parameters, but it needs seven and
146  * an ISO C99 violation would appear. Adding the #DATA_DummyFunction()
147  * fixes this violation.
148  * For details see 6.10.3 (paragraph 4) of the ISO C99 standard.
149  */
150 extern void DATA_DummyFunction(void);
151 
152 /**
153  * @brief Initialization of database manager
154  *
155  * @return #STD_OK if initialization successful, otherwise #STD_NOT_OK
156  */
158 
159 /**
160  * @brief trigger of database manager
161  * @details TODO
162  */
163 extern void DATA_Task(void);
164 
165 /**
166  * @brief Stores one data block in database
167  * @details This function stores passed data in database and updates timestamp
168  * and previous timestamp in passed struct
169  * @warning Do not call this function from inside a critical section, as it is
170  * computationally complex.
171  * @param[in,out] pDataFromSender0 (type: void *)
172  * @return #STD_OK if access was successful, otherwise #STD_NOT_OK
173  */
174 extern STD_RETURN_TYPE_e DATA_Write1DataBlock(void *pDataFromSender0);
175 
176 /**
177  * @brief Stores two data blocks in database
178  * @details This function stores passed data in database and updates timestamp
179  * and previous timestamp in passed struct
180  * @warning Do not call this function from inside a critical section, as it is
181  * computationally complex.
182  * @param[in,out] pDataFromSender0 (type: void *)
183  * @param[in,out] pDataFromSender1 (type: void *)
184  * @return #STD_OK if access was successful, otherwise #STD_NOT_OK
185  */
186 extern STD_RETURN_TYPE_e DATA_Write2DataBlocks(void *pDataFromSender0, void *pDataFromSender1);
187 /**
188  * @brief Stores three data blocks in database
189  * @details This function stores passed data in database and updates timestamp
190  * and previous timestamp in passed struct
191  * @warning Do not call this function from inside a critical section, as it is
192  * computationally complex.
193  * @param[in,out] pDataFromSender0 (type: void *)
194  * @param[in,out] pDataFromSender1 (type: void *)
195  * @param[in,out] pDataFromSender2 (type: void *)
196  * @return #STD_OK if access was successful, otherwise #STD_NOT_OK
197  */
198 extern STD_RETURN_TYPE_e DATA_Write3DataBlocks(void *pDataFromSender0, void *pDataFromSender1, void *pDataFromSender2);
199 /**
200  * @brief Stores four data blocks in database
201  * @details This function stores passed data in database and updates timestamp
202  * and previous timestamp in passed struct
203  * @warning Do not call this function from inside a critical section, as it is
204  * computationally complex.
205  * @param[in,out] pDataFromSender0 (type: void *)
206  * @param[in,out] pDataFromSender1 (type: void *)
207  * @param[in,out] pDataFromSender2 (type: void *)
208  * @param[in,out] pDataFromSender3 (type: void *)
209  * @return #STD_OK if access was successful, otherwise #STD_NOT_OK
210  */
212  void *pDataFromSender0,
213  void *pDataFromSender1,
214  void *pDataFromSender2,
215  void *pDataFromSender3);
216 
217 /**
218  * @brief Reads one data block in database by value.
219  * @details This function reads data from database and copy this content in
220  * passed struct
221  * @warning Do not call this function from inside a critical section, as it is
222  * computationally complex.
223  * @param[out] pDataToReceiver0 (type: void *)
224  * @return #STD_OK if access was successful, otherwise #STD_NOT_OK
225  */
226 extern STD_RETURN_TYPE_e DATA_Read1DataBlock(void *pDataToReceiver0);
227 /**
228  * @brief Reads two data blocks in database by value.
229  * @details This function reads data from database and copy this content in
230  * passed struct
231  * @warning Do not call this function from inside a critical section, as it is
232  * computationally complex.
233  * @param[out] pDataToReceiver0 (type: void *)
234  * @param[out] pDataToReceiver1 (type: void *)
235  * @return #STD_OK if access was successful, otherwise #STD_NOT_OK
236  */
237 extern STD_RETURN_TYPE_e DATA_Read2DataBlocks(void *pDataToReceiver0, void *pDataToReceiver1);
238 /**
239  * @brief Reads three data blocks in database by value.
240  * @details This function reads data from database and copy this content in
241  * passed struct
242  * @warning Do not call this function from inside a critical section, as it is
243  * computationally complex.
244  * @param[out] pDataToReceiver0 (type: void *)
245  * @param[out] pDataToReceiver1 (type: void *)
246  * @param[out] pDataToReceiver2 (type: void *)
247  * @return #STD_OK if access was successful, otherwise #STD_NOT_OK
248  */
249 extern STD_RETURN_TYPE_e DATA_Read3DataBlocks(void *pDataToReceiver0, void *pDataToReceiver1, void *pDataToReceiver2);
250 /**
251  * @brief Reads four data blocks in database by value.
252  * @details This function reads data from database and copy this content in
253  * passed struct
254  * @warning Do not call this function from inside a critical section, as it is
255  * computationally complex.
256  * @param[out] pDataToReceiver0 (type: void *)
257  * @param[out] pDataToReceiver1 (type: void *)
258  * @param[out] pDataToReceiver2 (type: void *)
259  * @param[out] pDataToReceiver3 (type: void *)
260  * @return #STD_OK if access was successful, otherwise #STD_NOT_OK
261  */
263  void *pDataToReceiver0,
264  void *pDataToReceiver1,
265  void *pDataToReceiver2,
266  void *pDataToReceiver3);
267 
268 /**
269  * @brief Executes a built-in self-test for the database module
270  * @details This test writes and reads a database entry in order to check that
271  * the database module is working as expected. If the test fails, it
272  * will fail an assertion.
273  */
274 extern void DATA_ExecuteDataBist(void);
275 
276 /*========== Externalized Static Functions Prototypes (Unit Test) ===========*/
277 #ifdef UNITY_UNIT_TEST
278 #endif
279 
280 #endif /* FOXBMS__DATABASE_H_ */
STD_RETURN_TYPE_e DATA_Write4DataBlocks(void *pDataFromSender0, void *pDataFromSender1, void *pDataFromSender2, void *pDataFromSender3)
Stores four data blocks in database.
Definition: database.c:350
DATA_BLOCK_ACCESS_TYPE_e
data block access types (read or write)
Definition: database.h:109
@ DATA_READ_ACCESS
Definition: database.h:111
@ DATA_WRITE_ACCESS
Definition: database.h:110
void DATA_Task(void)
trigger of database manager
Definition: database.c:279
STD_RETURN_TYPE_e DATA_Read2DataBlocks(void *pDataToReceiver0, void *pDataToReceiver1)
Reads two data blocks in database by value.
Definition: database.c:305
STD_RETURN_TYPE_e DATA_Read1DataBlock(void *pDataToReceiver0)
Reads one data block in database by value.
Definition: database.c:300
void DATA_DummyFunction(void)
Dummy void function of the database module.
Definition: database.c:297
STD_RETURN_TYPE_e DATA_Write1DataBlock(void *pDataFromSender0)
Stores one data block in database.
Definition: database.c:331
STD_RETURN_TYPE_e DATA_Read3DataBlocks(void *pDataToReceiver0, void *pDataToReceiver1, void *pDataToReceiver2)
Reads three data blocks in database by value.
Definition: database.c:311
STD_RETURN_TYPE_e DATA_Write3DataBlocks(void *pDataFromSender0, void *pDataFromSender1, void *pDataFromSender2)
Stores three data blocks in database.
Definition: database.c:342
void DATA_ExecuteDataBist(void)
Executes a built-in self-test for the database module.
Definition: database.c:363
STD_RETURN_TYPE_e DATA_Read4DataBlocks(void *pDataToReceiver0, void *pDataToReceiver1, void *pDataToReceiver2, void *pDataToReceiver3)
Reads four data blocks in database by value.
Definition: database.c:318
#define DATA_MAX_ENTRIES_PER_ACCESS
Definition: database.h:75
STD_RETURN_TYPE_e DATA_Write2DataBlocks(void *pDataFromSender0, void *pDataFromSender1)
Stores two data blocks in database.
Definition: database.c:336
STD_RETURN_TYPE_e DATA_Initialize(void)
Initialization of database manager.
Definition: database.c:229
Database configuration header.
Database module header.
Definition of foxBMS standard types.
STD_RETURN_TYPE_e
Definition: fstd_types.h:82
Declaration of the OS wrapper interface.
DATA_BLOCK_ACCESS_TYPE_e accessType
Definition: database.h:121