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