foxBMS-UnitTests  1.0.0
The foxBMS Unit Tests API Documentation
database.h
Go to the documentation of this file.
1 /**
2  *
3  * @copyright © 2010 - 2021, Fraunhofer-Gesellschaft zur Foerderung der
4  * angewandten Forschung e.V. All rights reserved.
5  *
6  * BSD 3-Clause License
7  * Redistribution and use in source and binary forms, with or without
8  * modification, are permitted provided that the following conditions are met:
9  * 1. Redistributions of source code must retain the above copyright notice,
10  * this list of conditions and the following disclaimer.
11  * 2. Redistributions in binary form must reproduce the above copyright
12  * notice, this list of conditions and the following disclaimer in the
13  * documentation and/or other materials provided with the distribution.
14  * 3. Neither the name of the copyright holder nor the names of its
15  * contributors may be used to endorse or promote products derived from
16  * this software without specific prior written permission.
17  *
18  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
19  * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
20  * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
21  * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
22  * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
23  * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
24  * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
25  * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
26  * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
27  * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
28  * POSSIBILITY OF SUCH DAMAGE.
29  *
30  * We kindly request you to use one or more of the following phrases to refer
31  * to foxBMS in your hardware, software, documentation or advertising
32  * materials:
33  *
34  * ″This product uses parts of foxBMS®″
35  *
36  * ″This product includes parts of foxBMS®″
37  *
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 2019-11-21 (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 "FreeRTOS.h"
63 #include "queue.h"
64 
65 #include "os.h"
66 
67 /*========== Macros and Definitions =========================================*/
68 
69 /** helper macro for the variadic macros for read and write functions */
70 #define GET_MACRO(_1, _2, _3, _4, NAME, ...) NAME
71 /** variadic macro for read access to the database */
72 #define DATA_READ_DATA(...) \
73  GET_MACRO( \
74  __VA_ARGS__, \
75  DATA_Read_4_DataBlocks, \
76  DATA_Read_3_DataBlocks, \
77  DATA_Read_2_DataBlocks, \
78  DATA_Read_1_DataBlock, \
79  DATA_DummyFunction) \
80  (__VA_ARGS__)
81 /** variadic macro for write access to the database */
82 #define DATA_WRITE_DATA(...) \
83  GET_MACRO( \
84  __VA_ARGS__, \
85  DATA_Write_4_DataBlocks, \
86  DATA_Write_3_DataBlocks, \
87  DATA_Write_2_DataBlocks, \
88  DATA_Write_1_DataBlock, \
89  DATA_DummyFunction) \
90  (__VA_ARGS__)
91 
92 /**
93  * @brief data block access types (read or write)
94  */
95 typedef enum DATA_BLOCK_ACCESS_TYPE {
96  DATA_WRITE_ACCESS, /**< write access to data block */
97  DATA_READ_ACCESS, /**< read access to data block */
99 
100 /*========== Extern Constant and Variable Declarations ======================*/
101 
102 /*========== Extern Function Prototypes =====================================*/
103 /**
104  * @brief Dummy void function of the database module
105  * @details This function is needed in the database module in order to
106  * implement the #DATA_READ_DATA() and #DATA_WRITE_DATA() in a ISO C99
107  * standard compatible way. The invocation of a macro that accepts a
108  * variable number of arguments (and this is the case for
109  * #DATA_READ_DATA() and #DATA_WRITE_DATA()) needs more arguments in the
110  * invocation than there are parameters in the macro definition. For
111  * the most simple case, that #DATA_READ_DATA() and #DATA_WRITE_DATA() are
112  * only called with one argument, a violation of the standard would
113  * appear if the #DATA_DummyFunction() would be omitted:
114  * GET_MACRO(databaseVaribale,
115  * DATA_Read_4_DataBlocks,
116  * DATA_Read_3_DataBlocks,
117  * DATA_Read_2_DataBlocks,
118  * DATA_Read_2_DataBlocks,
119  * DATA_Read_1_DataBlock)(databaseVaribale)
120  * So the macro invocation has six parameters, but it needs seven and
121  * an ISO C99 violation would appear. Adding the #DATA_DummyFunction()
122  * fixes this violation.
123  * For details see 6.10.3 (paragraph 4) of the ISO C99 standard.
124  */
125 extern void DATA_DummyFunction(void);
126 
127 /**
128  * @brief Initialization of database manager
129  *
130  * @return #STD_OK if initialization successful, otherwise #STD_NOT_OK
131  */
132 extern STD_RETURN_TYPE_e DATA_Init(void);
133 
134 /**
135  * @brief trigger of database manager
136  * @details TODO
137  */
138 extern void DATA_Task(void);
139 
140 /**
141  * @brief Stores a datablock in database
142  * @details This function stores passed data in database and updates timestamp
143  * and previous timestamp in passed struct
144  * @warning Do not call this function from inside a critical section, as it is
145  * computationally complex.
146  * @param[in,out] pDataFromSender0 (type: void *)
147  * @return #STD_OK if access was successful, otherwise #STD_NOT_OK
148  */
149 extern STD_RETURN_TYPE_e DATA_Write_1_DataBlock(void *pDataFromSender0);
150 
151 /**
152  * @brief Stores a datablock in database
153  * @details This function stores passed data in database and updates timestamp
154  * and previous timestamp in passed struct
155  * @warning Do not call this function from inside a critical section, as it is
156  * computationally complex.
157  * @param[in,out] pDataFromSender0 (type: void *)
158  * @param[in,out] pDataFromSender1 (type: void *)
159  * @return #STD_OK if access was successful, otherwise #STD_NOT_OK
160  */
161 extern STD_RETURN_TYPE_e DATA_Write_2_DataBlocks(void *pDataFromSender0, void *pDataFromSender1);
162 /**
163  * @brief Stores a datablock 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  * @param[in,out] pDataFromSender1 (type: void *)
170  * @param[in,out] pDataFromSender2 (type: void *)
171  * @return #STD_OK if access was successful, otherwise #STD_NOT_OK
172  */
174  void *pDataFromSender0,
175  void *pDataFromSender1,
176  void *pDataFromSender2);
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  * @param[in,out] pDataFromSender3 (type: void *)
187  * @return #STD_OK if access was successful, otherwise #STD_NOT_OK
188  */
190  void *pDataFromSender0,
191  void *pDataFromSender1,
192  void *pDataFromSender2,
193  void *pDataFromSender3);
194 
195 /**
196  * @brief Reads a datablock in database by value.
197  * @details This function reads data from database and copy this content in
198  * passed struct
199  * @warning Do not call this function from inside a critical section, as it is
200  * computationally complex.
201  * @param[out] pDataToReceiver0 (type: void *)
202  * @return #STD_OK if access was successful, otherwise #STD_NOT_OK
203  */
204 extern STD_RETURN_TYPE_e DATA_Read_1_DataBlock(void *pDataToReceiver0);
205 /**
206  * @brief Reads a datablock in database by value.
207  * @details This function reads data from database and copy this content in
208  * passed struct
209  * @warning Do not call this function from inside a critical section, as it is
210  * computationally complex.
211  * @param[out] pDataToReceiver0 (type: void *)
212  * @param[out] pDataToReceiver1 (type: void *)
213  * @return #STD_OK if access was successful, otherwise #STD_NOT_OK
214  */
215 extern STD_RETURN_TYPE_e DATA_Read_2_DataBlocks(void *pDataToReceiver0, void *pDataToReceiver1);
216 /**
217  * @brief Reads a datablock in database by value.
218  * @details This function reads data from database and copy this content in
219  * passed struct
220  * @warning Do not call this function from inside a critical section, as it is
221  * computationally complex.
222  * @param[out] pDataToReceiver0 (type: void *)
223  * @param[out] pDataToReceiver1 (type: void *)
224  * @param[out] pDataToReceiver2 (type: void *)
225  * @return #STD_OK if access was successful, otherwise #STD_NOT_OK
226  */
227 extern STD_RETURN_TYPE_e DATA_Read_3_DataBlocks(void *pDataToReceiver0, void *pDataToReceiver1, void *pDataToReceiver2);
228 /**
229  * @brief Reads a datablock in database by value.
230  * @details This function reads data from database and copy this content in
231  * passed struct
232  * @warning Do not call this function from inside a critical section, as it is
233  * computationally complex.
234  * @param[out] pDataToReceiver0 (type: void *)
235  * @param[out] pDataToReceiver1 (type: void *)
236  * @param[out] pDataToReceiver2 (type: void *)
237  * @param[out] pDataToReceiver3 (type: void *)
238  * @return #STD_OK if access was successful, otherwise #STD_NOT_OK
239  */
241  void *pDataToReceiver0,
242  void *pDataToReceiver1,
243  void *pDataToReceiver2,
244  void *pDataToReceiver3);
245 
246 /**
247  * @brief Checks if passed database entry has been updated at least once.
248  * @param[in] pDatabaseEntry (type: void *)
249  * @return true if database entry has been updated at least once, otherwise false
250  */
251 extern bool DATA_DatabaseEntryUpdatedAtLeastOnce(void *pDatabaseEntry);
252 
253 /**
254  * @brief Checks if passed database entry has been updated within the last
255  * time interval
256  * @param[in] pDatabaseEntry (type: void *)
257  * @param[in] timeInterval in systicks (type: uint32_t)
258  * @return true if database entry has been updated within the time interval,
259  * otherwise false
260  */
261 extern bool DATA_DatabaseEntryUpdatedRecently(void *pDatabaseEntry, uint32_t timeInterval);
262 
263 /**
264  * @brief Checks if passed database entry has been periodically updated
265  * within the time interval
266  * @details Checks if the last update timestamp is not older than time interval
267  * and if the difference between previous timestamp and timestamp is
268  * smaller than time interval
269  * @param[in] pDatabaseEntry (type: void *)
270  * @param[in] timeInterval in systicks (type: uint32_t)
271  * @return true if database entry has been periodically updated within the time
272  * interval, otherwise false
273  */
274 extern bool DATA_DatabaseEntryUpdatedWithinInterval(void *pDatabaseEntry, uint32_t timeInterval);
275 
276 /*========== Externalized Static Functions Prototypes (Unit Test) ===========*/
277 
278 #endif /* FOXBMS__DATABASE_H_ */
os.h
Implementation of the tasks used by the system, headers.
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:255
STD_RETURN_TYPE_e
enum STD_RETURN_TYPE STD_RETURN_TYPE_e
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:245
DATA_BLOCK_ACCESS_TYPE_e
enum DATA_BLOCK_ACCESS_TYPE DATA_BLOCK_ACCESS_TYPE_e
data block access types (read or write)
DATA_Write_2_DataBlocks
STD_RETURN_TYPE_e DATA_Write_2_DataBlocks(void *pDataFromSender0, void *pDataFromSender1)
Stores a datablock in database.
Definition: database.c:289
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:299
DATA_DatabaseEntryUpdatedAtLeastOnce
bool DATA_DatabaseEntryUpdatedAtLeastOnce(void *pDatabaseEntry)
Checks if passed database entry has been updated at least once.
Definition: database.c:328
DATA_DatabaseEntryUpdatedRecently
bool DATA_DatabaseEntryUpdatedRecently(void *pDatabaseEntry, uint32_t timeInterval)
Checks if passed database entry has been updated within the last time interval.
Definition: database.c:340
DATA_WRITE_ACCESS
@ DATA_WRITE_ACCESS
Definition: database.h:96
DATA_Init
STD_RETURN_TYPE_e DATA_Init(void)
Initialization of database manager.
Definition: database.c:138
DATA_Write_1_DataBlock
STD_RETURN_TYPE_e DATA_Write_1_DataBlock(void *pDataFromSender0)
Stores a datablock in database.
Definition: database.c:284
DATA_Task
void DATA_Task(void)
trigger of database manager
Definition: database.c:189
DATA_Read_1_DataBlock
STD_RETURN_TYPE_e DATA_Read_1_DataBlock(void *pDataToReceiver0)
Reads a datablock in database by value.
Definition: database.c:240
DATA_DummyFunction
void DATA_DummyFunction(void)
Dummy void function of the database module.
Definition: database.c:237
DATA_READ_ACCESS
@ DATA_READ_ACCESS
Definition: database.h:97
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:294
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:250
DATA_BLOCK_ACCESS_TYPE
DATA_BLOCK_ACCESS_TYPE
data block access types (read or write)
Definition: database.h:95
DATA_DatabaseEntryUpdatedWithinInterval
bool DATA_DatabaseEntryUpdatedWithinInterval(void *pDatabaseEntry, uint32_t timeInterval)
Checks if passed database entry has been periodically updated within the time interval.
Definition: database.c:356
database_cfg.h
Database configuration header.