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