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