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