foxBMS  1.1.0
The foxBMS Battery Management System 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-07-23 (date of last update)
47  * @ingroup OS
48  * @prefix OS
49  *
50  * @brief Implementation of the tasks used by the system, headers
51  *
52  */
53 
54 #ifndef FOXBMS__OS_H_
55 #define FOXBMS__OS_H_
56 
57 /*========== Includes =======================================================*/
58 #include "general.h"
59 
60 #include "FreeRTOS.h"
61 #include "event_groups.h"
62 #include "semphr.h"
63 #include "task.h"
64 
65 /*========== Macros and Definitions =========================================*/
66 
67 /** @brief Number of mutexes for the engine TODO engine what?! */
68 #define OS_NUM_OF_MUTEXES 0
69 /** @brief Number of events for the engine TODO engine what?! */
70 #define OS_NUM_OF_EVENTS 0
71 
72 /**
73  * @brief typedef for thread priority. The higher the value, the higher the
74  * priority.
75  */
76 typedef enum OS_PRIORITY {
77  OS_PRIORITY_IDLE, /**< priority: idle (lowest) */
78  OS_PRIORITY_LOW, /**< priority: low */
79  OS_PRIORITY_BELOW_NORMAL, /**< priority: below normal */
80  OS_PRIORITY_NORMAL, /**< priority: normal (default) */
81  OS_PRIORITY_ABOVE_NORMAL, /**< priority: above normal */
82  OS_PRIORITY_HIGH, /**< priority: high */
83  OS_PRIORITY_ABOVE_HIGH, /**< priority: above high */
84  OS_PRIORITY_VERY_HIGH, /**< priority: very high */
85  OS_PRIORITY_BELOW_REALTIME, /**< priority: below realtime */
86  OS_PRIORITY_REAL_TIME, /**< priority: realtime (highest) */
88 
89 /** @brief enum of OS boot states */
90 typedef enum OS_BOOT_STATE {
91  OS_OFF, /**< system is off */
92  OS_CREATE_QUEUES, /**< state right before queues are created */
93  OS_CREATE_TASKS, /**< state right before tasks are created */
94  OS_INIT_PRE_OS, /**< state right after tasks are created */
95  OS_SCHEDULER_RUNNING, /**< scheduler is running */
96  OS_ENGINE_RUNNING, /**< state right after scheduler is started and engine is initalized */
97  OS_PRECYCLIC_INIT_HAS_FINISHED, /**< state after the precyclic init has finished */
98  OS_SYSTEM_RUNNING, /**< system is running */
99  OS_INIT_OS_FATALERROR_SCHEDULER, /**< error in scheduler */
100  OS_INIT_OS_FATALERROR, /**< fatal error */
101  OS_BOOT_STATE_MAX, /**< DO NOT CHANGE, MUST BE THE LAST ENTRY */
103 
104 /** @brief OS timer */
105 typedef struct OS_TIMER {
106  uint8_t timer_1ms; /**< milliseconds */
107  uint8_t timer_10ms; /**< 10 milliseconds */
108  uint8_t timer_100ms; /**< 100 milliseconds */
109  uint8_t timer_sec; /**< seconds */
110  uint8_t timer_min; /**< minutes */
111  uint8_t timer_h; /**< hours */
112  uint16_t timer_d; /**< days */
114 
115 /** @brief struct for FreeRTOS task definition */
116 typedef struct OS_TASK_DEFINITION {
117  uint32_t phase; /**< TODO (ms) */
118  uint32_t cycleTime; /**< TODO (ms) */
119  UBaseType_t priority; /**< TODO */
120  uint16_t stackSize; /**< Defines the size, in words, of the stack
121  allocated to the idle task. */
123 
124 /*========== Extern Constant and Variable Declarations ======================*/
125 /** boot state of the system */
126 extern volatile OS_BOOT_STATE_e os_boot;
127 /** os timer for counting the system ticks */
128 extern volatile OS_TIMER_s os_timer;
129 
130 /** @brief Scheduler "zero" time for task phase control */
131 extern uint32_t os_schedulerStartTime;
132 
133 /** handles for OS objects @{*/
134 extern SemaphoreHandle_t os_mutexes[];
135 extern EventGroupHandle_t os_events[];
136 /**@}*/
137 
138 /*========== Extern Function Prototypes =====================================*/
139 
140 /**
141  * @brief Starts the operating system scheduler
142  */
143 extern void OS_StartScheduler(void);
144 
145 /**
146  * @brief Initialization the RTOS interface
147  * @details This function initializes the mutexes, eventgroups and tasks.
148  */
149 extern void OS_InitializeOperatingSystem(void);
150 
151 /**
152  * @brief Supplies the memory for the idle task.
153  * @details This is needed due to the usage of configSUPPORT_STATIC_ALLOCATION.
154  * This is an FreeRTOS function an does not adhere to foxBMS function
155  * naming convetions.
156  * @param ppxIdleTaskTCBBuffer TODO
157  * @param ppxIdleTaskStackBuffer TODO
158  * @param pulIdleTaskStackSize TODO
159  */
161  StaticTask_t **ppxIdleTaskTCBBuffer,
162  StackType_t **ppxIdleTaskStackBuffer,
163  uint32_t *pulIdleTaskStackSize);
164 
165 #if (configUSE_TIMERS > 0) && (configSUPPORT_STATIC_ALLOCATION == 1)
166 /**
167  * @brief Supplies the memory for the timer task.
168  * @details This is necessary for the combination of
169  * configSUPPORT_STATIC_ALLOCATION and configUSE_TIMERS.
170  * This is an FreeRTOS function an does not adhere to foxBMS function
171  * naming convetions.
172  * @param ppxTimerTaskTCBBuffer TODO
173  * @param ppxTimerTaskStackBuffer TODO
174  * @param pulTimerTaskStackSize TODO
175  */
176 extern void vApplicationGetTimerTaskMemory(
177  StaticTask_t **ppxTimerTaskTCBBuffer,
178  StackType_t **ppxTimerTaskStackBuffer,
179  uint32_t *pulTimerTaskStackSize);
180 #endif /* configUSE_TIMERS */
181 
182 /**
183  * @brief Hook function for the idle task
184  * @details This is an FreeRTOS function an does not adhere to foxBMS function
185  * naming convetions
186  */
187 extern void vApplicationIdleHook(void);
188 
189 /**
190  * @brief Hook function for StackOverflowHandling.
191  * @details This handler is used when the operation system encounters a
192  * stackoverflow in a task.
193  * This is an FreeRTOS function an does not adhere to foxBMS function
194  * naming convetions
195  * @param xTask TODO
196  * @param pcTaskName TODO
197  */
198 extern void vApplicationStackOverflowHook(TaskHandle_t xTask, char *pcTaskName);
199 
200 /**
201  * @brief Enter Critical interface function for use in FreeRTOS-Tasks and
202  * FreeRTOS-ISR
203  * @details checks the function context (task/thread mode or interrupt
204  * (handler) mode) and calls the corresponding enter-critical
205  * function
206  */
207 extern void OS_EnterTaskCritical(void);
208 
209 /**
210  * @brief Exit Critical interface function for use in FreeRTOS-Tasks and
211  * FreeRTOS-ISR
212  * @details Checks the function context (task/thread mode or interrupt
213  * (handler) mode) and calls the corresponding exit-critical
214  * function
215  */
216 extern void OS_ExitTaskCritical(void);
217 
218 /**
219  * @brief Increments the system timer os_timer
220  * @details The os_timer is a runtime-counter, counting the time since the
221  * last reset.
222  * @param timer TODO
223  */
224 extern void OS_TriggerTimer(volatile OS_TIMER_s *timer);
225 
226 /**
227  * @brief Returns OS based system tick value.
228  * @details TODO
229  * @return time stamp in milliseconds, based on the operating system time.
230  */
231 extern uint32_t OS_GetTickCount(void);
232 
233 /**
234  * @brief Delays a task in milliseconds
235  * @details TODO
236  * @param delay_ms time delay value
237  */
238 extern void OS_DelayTask(uint32_t delay_ms);
239 
240 /**
241  * @brief Delay a task until a specified time
242  * @details TODO
243  * @param pPreviousWakeTime Pointer to a variable that holds the time at
244  * which the task was last unblocked.
245  * PreviousWakeTime must be initialized with the
246  * current time prior to its first use
247  * (PreviousWakeTime = OS_osSysTick()).
248  * @param milliseconds time delay value in milliseconds
249  */
250 extern void OS_DelayTaskUntil(uint32_t *pPreviousWakeTime, uint32_t milliseconds);
251 
252 /**
253  * @brief Handles the tick increment of operating systick timer
254  * @details TODO
255  */
256 extern void OS_SystemTickHandler(void);
257 
258 /*========== Externalized Static Functions Prototypes (Unit Test) ===========*/
259 
260 #endif /* FOXBMS__OS_H_ */
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
void vApplicationGetIdleTaskMemory(StaticTask_t **ppxIdleTaskTCBBuffer, StackType_t **ppxIdleTaskStackBuffer, uint32_t *pulIdleTaskStackSize)
Supplies the memory for the idle task.
Definition: os.c:113
EventGroupHandle_t os_events[]
void OS_StartScheduler(void)
Starts the operating system scheduler.
Definition: os.c:100
void OS_SystemTickHandler(void)
Handles the tick increment of operating systick timer.
Definition: os.c:206
SemaphoreHandle_t os_mutexes[]
void OS_DelayTaskUntil(uint32_t *pPreviousWakeTime, uint32_t milliseconds)
Delay a task until a specified time.
Definition: os.c:196
uint32_t os_schedulerStartTime
Scheduler "zero" time for task phase control.
Definition: os.c:76
void vApplicationStackOverflowHook(TaskHandle_t xTask, char *pcTaskName)
Hook function for StackOverflowHandling.
Definition: os.c:137
void OS_ExitTaskCritical(void)
Exit Critical interface function for use in FreeRTOS-Tasks and FreeRTOS-ISR.
Definition: os.c:178
void OS_InitializeOperatingSystem(void)
Initialization the RTOS interface.
Definition: os.c:104
struct OS_TIMER OS_TIMER_s
OS timer.
void vApplicationIdleHook(void)
Hook function for the idle task.
Definition: os.c:133
volatile OS_TIMER_s os_timer
Definition: os.c:74
void OS_TriggerTimer(volatile OS_TIMER_s *timer)
Increments the system timer os_timer.
Definition: os.c:141
void OS_EnterTaskCritical(void)
Enter Critical interface function for use in FreeRTOS-Tasks and FreeRTOS-ISR.
Definition: os.c:174
enum OS_BOOT_STATE OS_BOOT_STATE_e
enum of OS boot states
void OS_DelayTask(uint32_t delay_ms)
Delays a task in milliseconds.
Definition: os.c:186
OS_BOOT_STATE
enum of OS boot states
Definition: os.h:90
@ OS_PRECYCLIC_INIT_HAS_FINISHED
Definition: os.h:97
@ OS_CREATE_TASKS
Definition: os.h:93
@ OS_CREATE_QUEUES
Definition: os.h:92
@ OS_INIT_PRE_OS
Definition: os.h:94
@ OS_SCHEDULER_RUNNING
Definition: os.h:95
@ OS_OFF
Definition: os.h:91
@ OS_INIT_OS_FATALERROR
Definition: os.h:100
@ OS_ENGINE_RUNNING
Definition: os.h:96
@ OS_INIT_OS_FATALERROR_SCHEDULER
Definition: os.h:99
@ OS_SYSTEM_RUNNING
Definition: os.h:98
@ OS_BOOT_STATE_MAX
Definition: os.h:101
uint32_t OS_GetTickCount(void)
Returns OS based system tick value.
Definition: os.c:182
volatile OS_BOOT_STATE_e os_boot
Definition: os.c:72
OS_PRIORITY
typedef for thread priority. The higher the value, the higher the priority.
Definition: os.h:76
@ OS_PRIORITY_HIGH
Definition: os.h:82
@ OS_PRIORITY_VERY_HIGH
Definition: os.h:84
@ OS_PRIORITY_BELOW_REALTIME
Definition: os.h:85
@ OS_PRIORITY_NORMAL
Definition: os.h:80
@ OS_PRIORITY_REAL_TIME
Definition: os.h:86
@ OS_PRIORITY_ABOVE_HIGH
Definition: os.h:83
@ OS_PRIORITY_LOW
Definition: os.h:78
@ OS_PRIORITY_BELOW_NORMAL
Definition: os.h:79
@ OS_PRIORITY_IDLE
Definition: os.h:77
@ OS_PRIORITY_ABOVE_NORMAL
Definition: os.h:81
struct for FreeRTOS task definition
Definition: os.h:116
UBaseType_t priority
Definition: os.h:119
uint32_t cycleTime
Definition: os.h:118
uint16_t stackSize
Definition: os.h:120
uint32_t phase
Definition: os.h:117
OS timer.
Definition: os.h:105
uint8_t timer_min
Definition: os.h:110
uint16_t timer_d
Definition: os.h:112
uint8_t timer_h
Definition: os.h:111
uint8_t timer_100ms
Definition: os.h:108
uint8_t timer_sec
Definition: os.h:109
uint8_t timer_1ms
Definition: os.h:106
uint8_t timer_10ms
Definition: os.h:107