foxBMS - Unit Tests  1.2.1
The foxBMS Unit Tests API Documentation
os.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 os.h
44  * @author foxBMS Team
45  * @date 2019-08-27 (date of creation)
46  * @updated 2021-12-08 (date of last update)
47  * @ingroup OS
48  * @prefix OS
49  *
50  * @brief Declaration of the OS wrapper interface
51  * @details This module describes the interface to different operating systems
52  */
53 
54 #ifndef FOXBMS__OS_H_
55 #define FOXBMS__OS_H_
56 
57 /*========== Includes =======================================================*/
58 #include "general.h"
59 
60 #if defined(FOXBMS_USES_FREERTOS)
61 #include "FreeRTOS.h"
62 #include "queue.h"
63 #define OS_QUEUE QueueHandle_t
64 #endif
65 
66 /*========== Macros and Definitions =========================================*/
67 
68 /** stack size of the idle task */
69 #define OS_IDLE_TASK_STACK_SIZE configMINIMAL_STACK_SIZE
70 
71 #if (configUSE_TIMERS > 0) && (configSUPPORT_STATIC_ALLOCATION == 1)
72 #define OS_TIMER_TASK_STACK_SIZE configTIMER_TASK_STACK_DEPTH
73 #endif /* configUSE_TIMERS */
74 
75 /** enum to encapsulate function returns from the OS-wrapper layer */
76 typedef enum OS_STD_RETURN {
77  OS_SUCCESS, /**< OS-dependent operation successfull */
78  OS_FAIL, /**< OS-dependent operation unsuccessfull */
80 
81 /**
82  * @brief typedef for thread priority. The higher the value, the higher the
83  * priority.
84  */
85 typedef enum OS_PRIORITY {
86  OS_PRIORITY_IDLE, /**< priority: idle (lowest) */
87  OS_PRIORITY_LOW, /**< priority: low */
88  OS_PRIORITY_BELOW_NORMAL, /**< priority: below normal */
89  OS_PRIORITY_NORMAL, /**< priority: normal (default) */
90  OS_PRIORITY_ABOVE_NORMAL, /**< priority: above normal */
91  OS_PRIORITY_HIGH, /**< priority: high */
92  OS_PRIORITY_ABOVE_HIGH, /**< priority: above high */
93  OS_PRIORITY_VERY_HIGH, /**< priority: very high */
94  OS_PRIORITY_BELOW_REALTIME, /**< priority: below realtime */
95  OS_PRIORITY_REAL_TIME, /**< priority: realtime (highest) */
97 
98 /** @brief enum of OS boot states */
99 typedef enum OS_BOOT_STATE {
100  OS_OFF, /**< system is off */
101  OS_CREATE_QUEUES, /**< state right before queues are created */
102  OS_CREATE_TASKS, /**< state right before tasks are created */
103  OS_INIT_PRE_OS, /**< state right after tasks are created */
104  OS_SCHEDULER_RUNNING, /**< scheduler is running */
105  OS_ENGINE_RUNNING, /**< state right after scheduler is started and engine is initalized */
106  OS_PRECYCLIC_INIT_HAS_FINISHED, /**< state after the precyclic init has finished */
107  OS_SYSTEM_RUNNING, /**< system is running */
108  OS_INIT_OS_FATALERROR_SCHEDULER, /**< error in scheduler */
109  OS_INIT_OS_FATALERROR, /**< fatal error */
110  OS_BOOT_STATE_MAX, /**< DO NOT CHANGE, MUST BE THE LAST ENTRY */
112 
113 /** @brief OS timer */
114 typedef struct OS_TIMER {
115  uint8_t timer_1ms; /**< milliseconds */
116  uint8_t timer_10ms; /**< 10 milliseconds */
117  uint8_t timer_100ms; /**< 100 milliseconds */
118  uint8_t timer_sec; /**< seconds */
119  uint8_t timer_min; /**< minutes */
120  uint8_t timer_h; /**< hours */
121  uint16_t timer_d; /**< days */
123 
124 /** @brief struct for FreeRTOS task definition */
125 typedef struct OS_TASK_DEFINITION {
126  OS_PRIORITY_e priority; /*!< priority of the task */
127  uint32_t phase; /*!< shift in ms of the first start of the task */
128  uint32_t cycleTime; /*!< time in ms that will be waited between each task cycle */
129  uint16_t stackSize; /*!< Defines the size, in words, of the stack allocated to the task */
130  void *pvParameters; /*!< value that is passed as the parameter to the task. */
132 
133 /*========== Extern Constant and Variable Declarations ======================*/
134 /** boot state of the system */
135 extern volatile OS_BOOT_STATE_e os_boot;
136 
137 /** @brief Scheduler "zero" time for task phase control */
138 extern uint32_t os_schedulerStartTime;
139 
140 /*========== Extern Function Prototypes =====================================*/
141 
142 /**
143  * @brief Starts the operating system scheduler
144  */
145 extern void OS_StartScheduler(void);
146 
147 /**
148  * @brief Initialization the RTOS interface
149  * @details This function initializes the mutexes, eventgroups and tasks.
150  */
151 extern void OS_InitializeOperatingSystem(void);
152 
153 #if (configUSE_TIMERS > 0) && (configSUPPORT_STATIC_ALLOCATION == 1)
154 /**
155  * @brief Supplies the memory for the timer task.
156  * @details This is necessary for the combination of
157  * configSUPPORT_STATIC_ALLOCATION and configUSE_TIMERS.
158  * This is an FreeRTOS function an does not adhere to foxBMS function
159  * naming convetions.
160  * @param ppxTimerTaskTCBBuffer TODO
161  * @param ppxTimerTaskStackBuffer TODO
162  * @param pulTimerTaskStackSize TODO
163  */
164 extern void vApplicationGetTimerTaskMemory(
165  StaticTask_t **ppxTimerTaskTCBBuffer,
166  StackType_t **ppxTimerTaskStackBuffer,
167  uint32_t *pulTimerTaskStackSize);
168 #endif /* configUSE_TIMERS */
169 
170 /**
171  * @brief Hook function for the idle task
172  * @details This is an FreeRTOS function an does not adhere to foxBMS function
173  * naming convetions
174  */
175 extern void vApplicationIdleHook(void);
176 
177 /**
178  * @brief Enter Critical interface function for use in FreeRTOS-Tasks and
179  * FreeRTOS-ISR
180  * @details checks the function context (task/thread mode or interrupt
181  * (handler) mode) and calls the corresponding enter-critical
182  * function
183  */
184 extern void OS_EnterTaskCritical(void);
185 
186 /**
187  * @brief Exit Critical interface function for use in FreeRTOS-Tasks and
188  * FreeRTOS-ISR
189  * @details Checks the function context (task/thread mode or interrupt
190  * (handler) mode) and calls the corresponding exit-critical
191  * function
192  */
193 extern void OS_ExitTaskCritical(void);
194 
195 /**
196  * @brief Increments the system timer os_timer
197  * @details The os_timer is a runtime-counter, counting the time since the
198  * last reset.
199  */
200 extern void OS_IncrementTimer(void);
201 
202 /**
203  * @brief Returns OS based system tick value.
204  * @details TODO
205  * @return time stamp in milliseconds, based on the operating system time.
206  */
207 extern uint32_t OS_GetTickCount(void);
208 
209 /**
210  * @brief Delay a task until a specified time
211  * @details TODO
212  * @param pPreviousWakeTime Pointer to a variable that holds the time at
213  * which the task was last unblocked.
214  * PreviousWakeTime must be initialized with the
215  * current time prior to its first use
216  * (PreviousWakeTime = OS_osSysTick()).
217  * @param milliseconds time delay value in milliseconds
218  */
219 extern void OS_DelayTaskUntil(uint32_t *pPreviousWakeTime, uint32_t milliseconds);
220 
221 /**
222  * @brief Handles the tick increment of operating systick timer
223  * @details TODO
224  */
225 extern void OS_SystemTickHandler(void);
226 
227 /**
228  * @brief Marks the current task as requiring FPU context
229  * @details In order to avoid corruption of the registers of the floating
230  * point unit during a task switch, every task that uses the FPU has
231  * to call this function at its start.
232  *
233  * This instructs the underlying operating system to store the context
234  * of the FPU when switching a task.
235  *
236  * This function has to be called from within a task.
237  */
238 extern void OS_MarkTaskAsRequiringFpuContext(void);
239 
240 /**
241  * @brief Receive an item from a queue
242  * @details This function needs to implement the wrapper to OS specfic queue
243  * posting.
244  * The queue needs to be implement in a FreeRTOS compatible way.
245  * This function must not be called from within an interrupt service
246  * routine (due to the FreeRTOS compatibility of the the wrapper).
247  * @param xQueue FreeRTOS compatible queue handle that should be posted
248  * to
249  * @param pvBuffer Pointer to the buffer into which the received item is
250  * posted to.
251  * @param ticksToWait ticks to wait
252  * @return #OS_SUCCESS if an item was successfully received, otherwise
253  * #OS_FAIL.
254  */
255 extern OS_STD_RETURN_e OS_ReceiveFromQueue(OS_QUEUE xQueue, void *const pvBuffer, uint32_t ticksToWait);
256 
257 /**
258  * @brief Post an item to the back the provided queue
259  * @details This function needs to implement the wrapper to OS specfic queue
260  * posting.
261  * The queue needs to be implement in a FreeRTOS compatible way.
262  * @param xQueue FreeRTOS compatible queue handle that should be
263  * posted to.
264  * @param pvItemToQueue Pointer to the item to be posted in the queue.
265  * @param ticksToWait ticks to wait
266  * @return #OS_SUCCESS if the item was successfully posted, otherwise #OS_FAIL.
267  */
268 extern OS_STD_RETURN_e OS_SendToBackOfQueue(OS_QUEUE xQueue, const void *const pvItemToQueue, TickType_t ticksToWait);
269 
270 /**
271  * @brief Post an item to the back the provided queue during an ISR
272  * @details This function needs to implement the wrapper to OS specfic queue
273  * posting.
274  * The queue needs to be implement in a FreeRTOS compatible way.
275  * @param xQueue FreeRTOS compatible queue handle that
276  * should be posted to.
277  * @param pvItemToQueue Pointer to the item to be posted in the
278  * queue.
279  * @param pxHigherPriorityTaskWoken Indicates whether a context switch is
280  * required or not.
281  * If the parameter is a NULL_PTR, the
282  * context switch will happen at the next
283  * tick.
284  * @return #OS_SUCCESS if the item was successfully posted, otherwise #OS_FAIL.
285  */
287  OS_QUEUE xQueue,
288  const void *const pvItemToQueue,
289  long *const pxHigherPriorityTaskWoken);
290 
291 /**
292  * @brief This function checks if timeToPass has passed since the last timestamp to now
293  * @details This function retrieves the current time stamp with #OS_GetTickCount(),
294  * compares it to the oldTimestamp_ms and checks if more or equal of
295  * timetoPass_ms timer increments have passed.
296  * @param[in] oldTimeStamp_ms timestamp that shall be compared to the current time in ms
297  * @param[in] timeToPass_ms timer increments (in ms) that shall pass between oldTimeStamp_ms and now
298  * @returns true in the case that more than timeToPass_ms timer increments have passed, otherwise false
299  */
300 extern bool OS_CheckTimeHasPassed(uint32_t oldTimeStamp_ms, uint32_t timeToPass_ms);
301 
302 /**
303  * @brief This function checks if timeToPass has passed since the last timestamp to now
304  * @details This function is passed the current time stamp as argument currentTimeStamp_ms,
305  * compares it to the oldTimestamp_ms and checks if more or equal of
306  * timetoPass_ms timer increments have passed.
307  * @param[in] oldTimeStamp_ms timestamp that shall be compared to the current time in ms
308  * @param[in] currentTimeStamp_ms timestamp of the current time in ms
309  * @param[in] timeToPass_ms timer increments (in ms) that shall pass between oldTimeStamp_ms and now
310  * @returns true in the case that more than timeToPass_ms timer increments have passed, otherwise false
311  */
313  uint32_t oldTimeStamp_ms,
314  uint32_t currentTimeStamp_ms,
315  uint32_t timeToPass_ms);
316 
317 /**
318  * @brief Does a self check if the #OS_CheckTimeHasPassedWithTimestamp works as expected
319  * @details This functions tests some values with #OS_CheckTimeHasPassedWithTimestamp().
320  * It is intended to be side-effect free and to be callable any time to verify
321  * from the running program if this portion of the software is working as
322  * expected.
323  * returns STD_OK if the self check passes successfully, STD_NOT_OK otherwise
324  */
326 
327 /*========== Externalized Static Functions Prototypes (Unit Test) ===========*/
328 #ifdef UNITY_UNIT_TEST
330 #endif /* UNITY_UNIT_TEST */
331 
332 #endif /* FOXBMS__OS_H_ */
enum STD_RETURN_TYPE STD_RETURN_TYPE_e
General macros and definitions for the whole platform.
enum OS_PRIORITY OS_PRIORITY_e
typedef for thread priority. The higher the value, the higher the priority.
struct OS_TASK_DEFINITION OS_TASK_DEFINITION_s
struct for FreeRTOS task definition
enum OS_STD_RETURN OS_STD_RETURN_e
OS_STD_RETURN_e OS_ReceiveFromQueue(OS_QUEUE xQueue, void *const pvBuffer, uint32_t ticksToWait)
Receive an item from a queue.
Definition: os_freertos.c:163
void OS_StartScheduler(void)
Starts the operating system scheduler.
Definition: os_freertos.c:71
void OS_SystemTickHandler(void)
Handles the tick increment of operating systick timer.
Definition: os_freertos.c:148
void OS_DelayTaskUntil(uint32_t *pPreviousWakeTime, uint32_t milliseconds)
Delay a task until a specified time.
Definition: os_freertos.c:133
OS_STD_RETURN_e OS_SendToBackOfQueueFromIsr(OS_QUEUE xQueue, const void *const pvItemToQueue, long *const pxHigherPriorityTaskWoken)
Post an item to the back the provided queue during an ISR.
Definition: os_freertos.c:188
uint32_t os_schedulerStartTime
Scheduler "zero" time for task phase control.
Definition: os.c:70
void OS_MarkTaskAsRequiringFpuContext(void)
Marks the current task as requiring FPU context.
Definition: os_freertos.c:159
bool OS_CheckTimeHasPassed(uint32_t oldTimeStamp_ms, uint32_t timeToPass_ms)
This function checks if timeToPass has passed since the last timestamp to now.
Definition: os.c:140
STD_RETURN_TYPE_e OS_CheckTimeHasPassedSelfTest(void)
Does a self check if the OS_CheckTimeHasPassedWithTimestamp works as expected.
Definition: os.c:144
OS_STD_RETURN_e OS_SendToBackOfQueue(OS_QUEUE xQueue, const void *const pvItemToQueue, TickType_t ticksToWait)
Post an item to the back the provided queue.
Definition: os_freertos.c:176
bool OS_CheckTimeHasPassedWithTimestamp(uint32_t oldTimeStamp_ms, uint32_t currentTimeStamp_ms, uint32_t timeToPass_ms)
This function checks if timeToPass has passed since the last timestamp to now.
Definition: os.c:114
void OS_ExitTaskCritical(void)
Exit Critical interface function for use in FreeRTOS-Tasks and FreeRTOS-ISR.
Definition: os_freertos.c:125
void OS_InitializeOperatingSystem(void)
Initialization the RTOS interface.
Definition: os.c:78
struct OS_TIMER OS_TIMER_s
OS timer.
OS_TIMER_s * TEST_OS_GetOsTimer()
Definition: os.c:177
void vApplicationIdleHook(void)
Hook function for the idle task.
Definition: os_freertos.c:111
void OS_IncrementTimer(void)
Increments the system timer os_timer.
Definition: os.c:90
void OS_EnterTaskCritical(void)
Enter Critical interface function for use in FreeRTOS-Tasks and FreeRTOS-ISR.
Definition: os_freertos.c:121
enum OS_BOOT_STATE OS_BOOT_STATE_e
enum of OS boot states
OS_BOOT_STATE
enum of OS boot states
Definition: os.h:99
@ OS_PRECYCLIC_INIT_HAS_FINISHED
Definition: os.h:106
@ OS_CREATE_TASKS
Definition: os.h:102
@ OS_CREATE_QUEUES
Definition: os.h:101
@ OS_INIT_PRE_OS
Definition: os.h:103
@ OS_SCHEDULER_RUNNING
Definition: os.h:104
@ OS_OFF
Definition: os.h:100
@ OS_INIT_OS_FATALERROR
Definition: os.h:109
@ OS_ENGINE_RUNNING
Definition: os.h:105
@ OS_INIT_OS_FATALERROR_SCHEDULER
Definition: os.h:108
@ OS_SYSTEM_RUNNING
Definition: os.h:107
@ OS_BOOT_STATE_MAX
Definition: os.h:110
uint32_t OS_GetTickCount(void)
Returns OS based system tick value.
Definition: os_freertos.c:129
volatile OS_BOOT_STATE_e os_boot
Definition: os.c:68
OS_PRIORITY
typedef for thread priority. The higher the value, the higher the priority.
Definition: os.h:85
@ OS_PRIORITY_HIGH
Definition: os.h:91
@ OS_PRIORITY_VERY_HIGH
Definition: os.h:93
@ OS_PRIORITY_BELOW_REALTIME
Definition: os.h:94
@ OS_PRIORITY_NORMAL
Definition: os.h:89
@ OS_PRIORITY_REAL_TIME
Definition: os.h:95
@ OS_PRIORITY_ABOVE_HIGH
Definition: os.h:92
@ OS_PRIORITY_LOW
Definition: os.h:87
@ OS_PRIORITY_BELOW_NORMAL
Definition: os.h:88
@ OS_PRIORITY_IDLE
Definition: os.h:86
@ OS_PRIORITY_ABOVE_NORMAL
Definition: os.h:90
OS_STD_RETURN
Definition: os.h:76
@ OS_SUCCESS
Definition: os.h:77
@ OS_FAIL
Definition: os.h:78
struct for FreeRTOS task definition
Definition: os.h:125
OS_PRIORITY_e priority
Definition: os.h:126
void * pvParameters
Definition: os.h:130
uint32_t cycleTime
Definition: os.h:128
uint16_t stackSize
Definition: os.h:129
uint32_t phase
Definition: os.h:127
OS timer.
Definition: os.h:114
uint8_t timer_min
Definition: os.h:119
uint16_t timer_d
Definition: os.h:121
uint8_t timer_h
Definition: os.h:120
uint8_t timer_100ms
Definition: os.h:117
uint8_t timer_sec
Definition: os.h:118
uint8_t timer_1ms
Definition: os.h:115
uint8_t timer_10ms
Definition: os.h:116