Declaration of the OS wrapper interface. More...

#include "fstd_types.h"
#include <stdbool.h>
#include <stdint.h>

Include dependency graph for os.h:

This graph shows which files directly or indirectly include this file:

Data Structures
struct	OS_TIMER_s
	OS timer. More...

struct	OS_TASK_DEFINITION_s
	struct for FreeRTOS task definition More...

Enumerations
enum	OS_STD_RETURN_e { OS_SUCCESS , OS_FAIL }

enum	OS_PRIORITY_e { OS_PRIORITY_IDLE , OS_PRIORITY_LOW , OS_PRIORITY_BELOW_NORMAL , OS_PRIORITY_NORMAL , OS_PRIORITY_ABOVE_NORMAL , OS_PRIORITY_HIGH , OS_PRIORITY_ABOVE_HIGH , OS_PRIORITY_VERY_HIGH , OS_PRIORITY_BELOW_REALTIME , OS_PRIORITY_REAL_TIME }
	typedef for thread priority. The higher the value, the higher the priority. More...

enum	OS_BOOT_STATE_e { OS_OFF , OS_INITIALIZE_SCHEDULER , OS_CREATE_QUEUES , OS_CREATE_TASKS , OS_INIT_PRE_OS , OS_SCHEDULER_RUNNING , OS_ENGINE_RUNNING , OS_PRE_CYCLIC_INITIALIZATION_HAS_FINISHED , OS_SYSTEM_RUNNING , OS_INIT_OS_FATALERROR_SCHEDULER , OS_INIT_OS_FATALERROR , OS_BOOT_STATE_MAX }
	enum of OS boot states More...

Functions
void	OS_InitializeScheduler (void)
	Initialization function for the scheduler. More...

void	OS_StartScheduler (void)
	Starts the operating system scheduler. More...

void	OS_InitializeOperatingSystem (void)
	Initialization the RTOS interface. More...

void	vApplicationIdleHook (void)
	Hook function for the idle task. More...

void	OS_EnterTaskCritical (void)
	Enter Critical interface function for use in FreeRTOS-Tasks and FreeRTOS-ISR. More...

void	OS_ExitTaskCritical (void)
	Exit Critical interface function for use in FreeRTOS-Tasks and FreeRTOS-ISR. More...

void	OS_IncrementTimer (void)
	Increments the system timer os_timer. More...

uint32_t	OS_GetTickCount (void)
	Returns OS based system tick value. More...

void	OS_DelayTaskUntil (uint32_t *pPreviousWakeTime, uint32_t milliseconds)
	Delay a task until a specified time. More...

void	OS_MarkTaskAsRequiringFpuContext (void)
	Marks the current task as requiring FPU context. More...

OS_STD_RETURN_e	OS_WaitForNotification (uint32_t *pNotifiedValue, uint32_t timeout)
	Wait for a notification. More...

OS_STD_RETURN_e	OS_NotifyFromIsr (TaskHandle_t taskToNotify, uint32_t notifiedValue)
	Notify a task. More...

OS_STD_RETURN_e	OS_WaitForNotificationIndexed (uint32_t indexToWaitOn, uint32_t *pNotifiedValue, uint32_t timeout)
	Wait for a notification, with index. More...

OS_STD_RETURN_e	OS_NotifyIndexedFromIsr (TaskHandle_t taskToNotify, uint32_t indexToNotify, uint32_t notifiedValue)
	Notify a task, with index. More...

OS_STD_RETURN_e	OS_ClearNotificationIndexed (uint32_t indexToClear)
	Clear pending notification of a task, with index. More...

OS_STD_RETURN_e	OS_ReceiveFromQueue (OS_QUEUE xQueue, void *const pvBuffer, uint32_t ticksToWait)
	Receive an item from a queue. More...

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. More...

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. More...

uint32_t	OS_GetNumberOfStoredMessagesInQueue (OS_QUEUE xQueue)
	Check if messages are waiting for queue. More...

bool	OS_CheckTimeHasPassed (uint32_t oldTimeStamp_ms, uint32_t timeToPass_ms)
	This function checks if timeToPass has passed since the last timestamp to now. More...

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. More...

STD_RETURN_TYPE_e	OS_CheckTimeHasPassedSelfTest (void)
	Does a self check if the OS_CheckTimeHasPassedWithTimestamp works as expected. More...

Variables
volatile OS_BOOT_STATE_e	os_boot

uint32_t	os_schedulerStartTime
	Scheduler "zero" time for task phase control. More...

Detailed Description

Declaration of the OS wrapper interface.

Copyright: © 2010 - 2023, Fraunhofer-Gesellschaft zur Foerderung der angewandten Forschung e.V. All rights reserved.

SPDX-License-Identifier: BSD-3-Clause

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
Neither the name of the copyright holder nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

We kindly request you to use one or more of the following phrases to refer to foxBMS in your hardware, software, documentation or advertising materials:

″This product uses parts of foxBMS®″
″This product includes parts of foxBMS®″
″This product is derived from foxBMS®″

Author: foxBMS Team

Date: 2019-08-27 (date of creation)

Updated: 2023-10-12 (date of last update)

Version: v1.6.0

Prefix: OS

This module describes the interface to different operating systems

Definition in file os.h.

Enumeration Type Documentation

◆ OS_BOOT_STATE_e

enum OS_BOOT_STATE_e

enum of OS boot states

Enumerator
OS_OFF	system is off
OS_INITIALIZE_SCHEDULER	state right before initializing the scheduler
OS_CREATE_QUEUES	state right before queues are created
OS_CREATE_TASKS	state right before tasks are created
OS_INIT_PRE_OS	state right after tasks are created
OS_SCHEDULER_RUNNING	scheduler is running
OS_ENGINE_RUNNING	state right after scheduler is started and engine is initalized
OS_PRE_CYCLIC_INITIALIZATION_HAS_FINISHED	state after the pre-cyclic init has finished
OS_SYSTEM_RUNNING	system is running
OS_INIT_OS_FATALERROR_SCHEDULER	error in scheduler
OS_INIT_OS_FATALERROR	fatal error
OS_BOOT_STATE_MAX	DO NOT CHANGE, MUST BE THE LAST ENTRY

Definition at line 108 of file os.h.

◆ OS_PRIORITY_e

enum OS_PRIORITY_e

typedef for thread priority. The higher the value, the higher the priority.

Enumerator
OS_PRIORITY_IDLE	priority: idle (lowest)
OS_PRIORITY_LOW	priority: low
OS_PRIORITY_BELOW_NORMAL	priority: below normal
OS_PRIORITY_NORMAL	priority: normal (default)
OS_PRIORITY_ABOVE_NORMAL	priority: above normal
OS_PRIORITY_HIGH	priority: high
OS_PRIORITY_ABOVE_HIGH	priority: above high
OS_PRIORITY_VERY_HIGH	priority: very high
OS_PRIORITY_BELOW_REALTIME	priority: below realtime
OS_PRIORITY_REAL_TIME	priority: realtime (highest)

Definition at line 94 of file os.h.

◆ OS_STD_RETURN_e

enum OS_STD_RETURN_e

enum to encapsulate function returns from the OS-wrapper layer

Enumerator
OS_SUCCESS	OS-dependent operation successful
OS_FAIL	OS-dependent operation unsuccessful

Definition at line 85 of file os.h.

Function Documentation

◆ OS_CheckTimeHasPassed()

bool OS_CheckTimeHasPassed	(	uint32_t	oldTimeStamp_ms,
		uint32_t	timeToPass_ms
	)

This function checks if timeToPass has passed since the last timestamp to now.

This function retrieves the current time stamp with OS_GetTickCount(), compares it to the oldTimestamp_ms and checks if more or equal of timeToPass_ms timer increments have passed.

Parameters

[in]	oldTimeStamp_ms	timestamp that shall be compared to the current time in ms
[in]	timeToPass_ms	timer increments (in ms) that shall pass between oldTimeStamp_ms and now

Returns: true in the case that more than timeToPass_ms timer increments have passed, otherwise false

Definition at line 150 of file os.c.

Here is the call graph for this function:

◆ OS_CheckTimeHasPassedSelfTest()

STD_RETURN_TYPE_e OS_CheckTimeHasPassedSelfTest ( void )

Does a self check if the OS_CheckTimeHasPassedWithTimestamp works as expected.

This functions tests some values with OS_CheckTimeHasPassedWithTimestamp(). It is intended to be side-effect free and to be callable any time to verify from the running program if this portion of the software is working as expected. returns STD_OK if the self check passes successfully, STD_NOT_OK otherwise

Definition at line 154 of file os.c.

Here is the call graph for this function:

◆ OS_CheckTimeHasPassedWithTimestamp()

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.

This function is passed the current time stamp as argument currentTimeStamp_ms, compares it to the oldTimestamp_ms and checks if more or equal of timeToPass_ms timer increments have passed.

Parameters

[in]	oldTimeStamp_ms	timestamp that shall be compared to the current time in ms
[in]	currentTimeStamp_ms	timestamp of the current time in ms
[in]	timeToPass_ms	timer increments (in ms) that shall pass between oldTimeStamp_ms and now

Returns: true in the case that more than timeToPass_ms timer increments have passed, otherwise false

Definition at line 124 of file os.c.

◆ OS_ClearNotificationIndexed()

OS_STD_RETURN_e OS_ClearNotificationIndexed ( uint32_t indexToClear )

Clear pending notification of a task, with index.

This function needs to implement the wrapper to OS specific task notification clearing. It clears the pending notification for the calling task. This function must not be called from within an interrupt service routine (due to the FreeRTOS compatibility of the the wrapper). This function clears a pending notification corresponding to the index passed as parameter.

Parameters

indexToClear Index of the notification to clear

Returns: OS_SUCCESS if a notification was pending, otherwise OS_FAIL

Definition at line 251 of file os_freertos.c.

◆ OS_DelayTaskUntil()

void OS_DelayTaskUntil	(	uint32_t *	pPreviousWakeTime,
		uint32_t	milliseconds
	)

Delay a task until a specified time.

TODO

Parameters

pPreviousWakeTime	Pointer to a variable that holds the time at which the task was last unblocked. PreviousWakeTime must be initialized with the current time prior to its first use (PreviousWakeTime = OS_osSysTick()).
milliseconds	time delay value in milliseconds

Definition at line 162 of file os_freertos.c.

◆ OS_EnterTaskCritical()

void OS_EnterTaskCritical ( void )

Enter Critical interface function for use in FreeRTOS-Tasks and FreeRTOS-ISR.

checks the function context (task/thread mode or interrupt (handler) mode) and calls the corresponding enter-critical function

Definition at line 150 of file os_freertos.c.

◆ OS_ExitTaskCritical()

void OS_ExitTaskCritical ( void )

Exit Critical interface function for use in FreeRTOS-Tasks and FreeRTOS-ISR.

Checks the function context (task/thread mode or interrupt (handler) mode) and calls the corresponding exit-critical function

Definition at line 154 of file os_freertos.c.

◆ OS_GetNumberOfStoredMessagesInQueue()

uint32_t OS_GetNumberOfStoredMessagesInQueue ( OS_QUEUE xQueue )

Check if messages are waiting for queue.

This function needs to implement the wrapper to OS specific queue posting.

Parameters

xQueue queue handle that should be posted to.

Returns: number of message currently stored in xQueue

Definition at line 305 of file os_freertos.c.

◆ OS_GetTickCount()

uint32_t OS_GetTickCount ( void )

Returns OS based system tick value.

TODO

Returns: time stamp in milliseconds, based on the operating system time.

Definition at line 158 of file os_freertos.c.

◆ OS_IncrementTimer()

void OS_IncrementTimer ( void )

Increments the system timer os_timer.

The os_timer is a runtime-counter, counting the time since the last reset.

Definition at line 99 of file os.c.

Here is the call graph for this function:

◆ OS_InitializeOperatingSystem()

void OS_InitializeOperatingSystem ( void )

Initialization the RTOS interface.

This function initializes the scheduler and then creates queues and tasks.

Definition at line 84 of file os.c.

Here is the call graph for this function:

◆ OS_InitializeScheduler()

void OS_InitializeScheduler ( void )

Initialization function for the scheduler.

Definition at line 76 of file os_freertos.c.

◆ OS_MarkTaskAsRequiringFpuContext()

void OS_MarkTaskAsRequiringFpuContext ( void )

Marks the current task as requiring FPU context.

In order to avoid corruption of the registers of the floating point unit during a task switch, every task that uses the FPU has to call this function at its start.

This instructs the underlying operating system to store the context of the FPU when switching a task.

This function has to be called from within a task.

Definition at line 172 of file os_freertos.c.

◆ OS_NotifyFromIsr()

OS_STD_RETURN_e OS_NotifyFromIsr	(	TaskHandle_t	taskToNotify,
		uint32_t	notifiedValue
	)

Notify a task.

This function needs to implement the wrapper to OS specific task notification. This function is to be called from within an interrupt service routine (due to the FreeRTOS compatibility of the the wrapper). This function makes a notification to the task whose handle is is passed as parameter. Typically the notification is made in an interrupt. The value to notify is passed to the notified task.

Parameters

taskToNotify	Handle of task to notify.
notifiedValue	Value to pass to the notified task

Returns: OS_SUCCESS if a notification was successfully made, otherwise OS_FAIL

Definition at line 192 of file os_freertos.c.

◆ OS_NotifyIndexedFromIsr()

OS_STD_RETURN_e OS_NotifyIndexedFromIsr	(	TaskHandle_t	taskToNotify,
		uint32_t	indexToNotify,
		uint32_t	notifiedValue
	)

Notify a task, with index.

This function needs to implement the wrapper to OS specific task notification. This function is to be called from within an interrupt service routine (due to the FreeRTOS compatibility of the the wrapper). This function makes a notification with an index to the task whose handle is passed as parameter. Typically the notification is made in an interrupt. The value to notify and the index are passed to the notified task.

Parameters

taskToNotify	Handle of task to notify
indexToNotify	Index to notify
notifiedValue	Value to pass to the notified task

Returns: OS_SUCCESS if a notification was successfully made, otherwise OS_FAIL.

Definition at line 230 of file os_freertos.c.

◆ OS_ReceiveFromQueue()

OS_STD_RETURN_e OS_ReceiveFromQueue	(	OS_QUEUE	xQueue,
		void *const	pvBuffer,
		uint32_t	ticksToWait
	)

Receive an item from a queue.

This function needs to implement the wrapper to OS specific queue posting. The queue needs to be implement in a FreeRTOS compatible way. This function must not be called from within an interrupt service routine (due to the FreeRTOS compatibility of the the wrapper).

Parameters

xQueue	FreeRTOS compatible queue handle that should be posted to
pvBuffer	Pointer to the buffer into which the received item is posted to.
ticksToWait	ticks to wait

Returns: OS_SUCCESS if an item was successfully received, otherwise OS_FAIL.

Definition at line 264 of file os_freertos.c.

◆ OS_SendToBackOfQueue()

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.

This function needs to implement the wrapper to OS specific queue posting. The queue needs to be implement in a FreeRTOS compatible way.

Parameters

xQueue	FreeRTOS compatible queue handle that should be posted to.
pvItemToQueue	Pointer to the item to be posted in the queue.
ticksToWait	ticks to wait

Returns: OS_SUCCESS if the item was successfully posted, otherwise OS_FAIL.

Definition at line 277 of file os_freertos.c.

◆ OS_SendToBackOfQueueFromIsr()

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.

This function needs to implement the wrapper to OS specific queue posting.

Parameters

xQueue	queue handle that should be posted to.
pvItemToQueue	Pointer to the item to be posted in the queue.
pxHigherPriorityTaskWoken	Indicates whether a context switch is required or not. If the parameter is a NULL_PTR, the context switch will happen at the next tick.

Returns: OS_SUCCESS if the item was successfully posted, otherwise OS_FAIL.

Definition at line 289 of file os_freertos.c.

◆ OS_StartScheduler()

void OS_StartScheduler ( void )

Starts the operating system scheduler.

Definition at line 82 of file os_freertos.c.

◆ OS_WaitForNotification()

OS_STD_RETURN_e OS_WaitForNotification	(	uint32_t *	pNotifiedValue,
		uint32_t	timeout
	)

Wait for a notification.

This function needs to implement the wrapper to OS specific blocking task and waiting for notification. This function must not be called from within an interrupt service routine (due to the FreeRTOS compatibility of the the wrapper). This function blocks the current tasks and wait for a notification. Typically the notification is made in an interrupt. The notified value is passed by the notifying function. The tasks unblocks when the notification is received or when timeout milliseconds have passed.

Parameters

pNotifiedValue	Value passed by the notify function
timeout	ticks to wait before unblocking task if no notification is received

Returns: OS_SUCCESS if a notification was successfully received, otherwise OS_FAIL

Definition at line 176 of file os_freertos.c.

◆ OS_WaitForNotificationIndexed()

OS_STD_RETURN_e OS_WaitForNotificationIndexed	(	uint32_t	indexToWaitOn,
		uint32_t *	pNotifiedValue,
		uint32_t	timeout
	)

Wait for a notification, with index.

This function needs to implement the wrapper to OS specific blocking task and waiting for notification. This function must not be called from within an interrupt service routine (due to the FreeRTOS compatibility of the the wrapper). This function blocks the current tasks and wait for a notification and a specific index. Typically the notification is made in an interrupt. The notified value and index are passed by the notifying function. The tasks unblocks when the notification is received or when timeout milliseconds have passed.

Parameters

indexToWaitOn	index to wait on
pNotifiedValue	Value passed by the notify function
timeout	ticks to wait before unblocking task if no notification is received

Returns: OS_SUCCESS if a notification was successfully received, otherwise OS_FAIL

Definition at line 210 of file os_freertos.c.

◆ vApplicationIdleHook()

void vApplicationIdleHook ( void )

Hook function for the idle task.

This is an FreeRTOS function an does not adhere to foxBMS function naming conventions

Definition at line 124 of file os_freertos.c.

Here is the call graph for this function:

Variable Documentation

◆ os_boot

volatile OS_BOOT_STATE_e os_boot

extern

boot state of the system

boot state of the OS

Definition at line 74 of file os.c.

◆ os_schedulerStartTime

uint32_t os_schedulerStartTime

extern

Scheduler "zero" time for task phase control.

timestamp of the scheduler start

Definition at line 76 of file os.c.

Data Structures

Enumerations

Functions

Variables

Detailed Description

Enumeration Type Documentation

◆ OS_BOOT_STATE_e

◆ OS_PRIORITY_e

◆ OS_STD_RETURN_e

Function Documentation

◆ OS_CheckTimeHasPassed()

◆ OS_CheckTimeHasPassedSelfTest()

◆ OS_CheckTimeHasPassedWithTimestamp()

◆ OS_ClearNotificationIndexed()

◆ OS_DelayTaskUntil()

◆ OS_EnterTaskCritical()

◆ OS_ExitTaskCritical()

◆ OS_GetNumberOfStoredMessagesInQueue()

◆ OS_GetTickCount()

◆ OS_IncrementTimer()

◆ OS_InitializeOperatingSystem()

◆ OS_InitializeScheduler()

◆ OS_MarkTaskAsRequiringFpuContext()

◆ OS_NotifyFromIsr()

◆ OS_NotifyIndexedFromIsr()

◆ OS_ReceiveFromQueue()

◆ OS_SendToBackOfQueue()

◆ OS_SendToBackOfQueueFromIsr()

◆ OS_StartScheduler()

◆ OS_WaitForNotification()

◆ OS_WaitForNotificationIndexed()

◆ vApplicationIdleHook()

Variable Documentation

◆ os_boot

◆ os_schedulerStartTime