SAFERTOS APPLICATION NOTE: #34-195-AN-001

UPGRADING FROM FreeRTOS TO

SAFERTOS® v9

Proprietary to WITTENSTEIN high integrity systems limited.

THE DATA CONTAINED IN THIS DOCUMENT IS PROPRIETARY INFORMATION AND IT IS PROVIDED UNDER LICENSE BY WITTENSTEIN high integrity systems Limited. ALL
RIGHTS TO USE, REPRODUCE AND DISTRIBUTE THE DOCUMENT ARE DEFINED IN THE LICENSE. ALL INFORMATION, TECHNICAL DATA, DESIGNS, INCLUDING BUT
NOT LIMITED TO DATA DISCLOSED AND/OR PROVIDED HEREIN, IS AND REMAINS THE EXCLUSIVE PROPERTY OF WITTENSTEIN high integrity systems Limited. IT IS
STRICTLY PROHIBITED TO DISCLOSE ANY INFORMATION TO THIRD PARTIES WITHOUT THE PRIOR WRITTEN CONSENT OF WITTENSTEIN high integrity systems Limited.
THE RECIPIENT OF THIS DOCUMENT, BY ITS RETENTION AND USE AGREES TO HOLD IN CONFIDENCE ALL PROPRIETARY INFORMATION PROVIDED WITHIN THIS
DOCUMENT.

Copyright WITTENSTEIN high integrity systems Limited, date as document, all rights reserved.

Issue 3.0 - August 25, 2023 Page 1

 CONTENTS

CONTENTS .................................................................................................................................... 2
REFERENCED DOCUMENTS ....................................................................................................... 3
CHAPTER 1 INTRODUCTION.................................................................................................... 4
1.1 KEY DIFFERENCES ............................................................................................................. 5
CHAPTER 2 MEMORY ALLOCATION ....................................................................................... 6
2.1 MEMORY ALLOCATION SCHEME ........................................................................................... 7
2.2 CHANGES TO XTASKCREATE()............................................................................................. 7
2.3 CHANGES TO XQUEUECREATE() .......................................................................................... 8
2.4 CHANGES TO XSEMAPHORECREATEBINARY() ...................................................................... 9
2.5 CHANGES TO XSEMAPHORECREATECOUNTING() .................................................................. 9
2.6 CHANGES TO XTIMERCREATE() ......................................................................................... 10
2.7 CHANGES TO XEVENTGROUPCREATE() ............................................................................. 11
2.8 CHANGES TO XMUTEXCREATE() ........................................................................................ 11
2.9 CHANGES TO XSTREAMBUFFERCREATE() .......................................................................... 13
CHAPTER 3 FUNCTIONALITY ................................................................................................. 14
3.1 RESTRICTED FUNCTIONALITY ............................................................................................ 15
3.1.1 Co-routines .............................................................................................................. 15
3.1.2 Queue Sets.............................................................................................................. 15
3.1.3 Thread Local Storage .............................................................................................. 15
3.1.4 Task Tags ................................................................................................................ 15
3.1.5 Removed API Functions .......................................................................................... 15
CHAPTER 4 FUNCTION AND MACRO NAMES ...................................................................... 16
4.1 FUNCTION AND MACRO NAMES ......................................................................................... 17
CHAPTER 5 CONFIGURATION PARAMETERS ...................................................................... 45
5.1 CONFIGURATION MACROS ................................................................................................. 46
CHAPTER 6 ERROR REPORTING .......................................................................................... 51
6.1 SIDE EFFECTS OF INCREASED ERROR REPORTING ............................................................. 52
CHAPTER 7 MISCELLANEOUS ............................................................................................... 53
7.1 HEADER FILES.................................................................................................................. 54
7.2 HOOK FUNCTIONS ............................................................................................................ 54
7.3 DIRECTORY STRUCTURE ................................................................................................... 55
7.4 DELAY CONSTANTS .......................................................................................................... 55
7.5 TICK-LESS MODE .............................................................................................................. 56

Upgrading from FreeRTOS to Issue 3.0 Page 2

SAFERTOS® v9
THE INFORMATION CONTAINED IN THIS DOCUMENT IS PROPRIETARY AND SUBJECT TO THE RESTRICTIONS ON THE COVERPAGE .
Copyright date as document date.
 REFERENCED DOCUMENTS

Ref # Document Description

1. 34-195-MAN-1-aaa Architecture Variant SAFERTOS v9 User Manual, Author
WHIS.

Upgrading from FreeRTOS to Issue 3.0 Page 3

SAFERTOS® v9
THE INFORMATION CONTAINED IN THIS DOCUMENT IS PROPRIETARY AND SUBJECT TO THE RESTRICTIONS ON THE COVERPAGE .
Copyright date as document date.
CHAPTER 1

INTRODUCTION

Upgrading from FreeRTOS to Issue 3.0 Page 4

SAFERTOS® v9
THE INFORMATION CONTAINED IN THIS DOCUMENT IS PROPRIETARY AND SUBJECT TO THE RESTRICTIONS ON THE COVERPAGE .
Copyright date as document date.
1.1 KEY DIFFERENCES

FreeRTOS and SAFERTOS share a similar usage model but are not direct drop-in replacements for
each other. This document highlights the areas requiring modification when moving an application
from FreeRTOS to SAFERTOS. These differences primarily arise from:

1. Memory allocation

Each task and queue created consumes a small amount of RAM. Under FreeRTOS the
required RAM is automatically dynamically allocated at run time. SAFERTOS does not permit
dynamic memory allocation so the required RAM must instead be statically allocated at
compile time, then manually passed into the create functions for the various kernel objects
(i.e. xTaskCreate(), xQueueCreate, xSemaphoreCreateBinary(),
xSemaphoreCreateCounting(), xTimerCreate(), xEventGroupCreate(), xMutexCreate(),
xEvtMplxCreate() and xStreamBufferCreate() API functions).

2. Function parameter checking

FreeRTOS contains very little in the way of API function input parameter checking. As a
result, many FreeRTOS API functions either just return a simple pass or fail result, or do not
return any status information at all.

SAFERTOS checks the validity of every appropriate input parameter. This means not only
do more SAFERTOS API functions return status information, but the status information
returned is also more detailed. The SAFERTOS function naming convention states that API
functions shall be prefixed with their return type – so changing the type returned by a function
also requires a small change to the function name.

3. Internal data checking

SAFERTOS performs validity and consistency tests on its key internal data – calling an
application defined error hook function should such a test fail. FreeRTOS does not require
an equivalent hook function so one must be provided when upgrading to instead use
SAFERTOS.

4. Restricted Functionality

SAFERTOS supports only a subset of FreeRTOS components, therefore some FreeRTOS

functionality has been restricted. Refer to Section 3.1 for more details.

To facilitate the upgrade processes a small SAFERTOS demonstration project is provided for your
reference. This project is the SAFERTOS equivalent to a sub-set of the standard FreeRTOS
demonstration application – allowing the two to be compared.

Upgrading from FreeRTOS to Issue 3.0 Page 5

SAFERTOS® v9
THE INFORMATION CONTAINED IN THIS DOCUMENT IS PROPRIETARY AND SUBJECT TO THE RESTRICTIONS ON THE COVERPAGE .
Copyright date as document date.
CHAPTER 2

MEMORY ALLOCATION

Upgrading from FreeRTOS to Issue 3.0 Page 6

SAFERTOS® v9
THE INFORMATION CONTAINED IN THIS DOCUMENT IS PROPRIETARY AND SUBJECT TO THE RESTRICTIONS ON THE COVERPAGE .
Copyright date as document date.
2.1 M EMORY ALLOCATION S CHEME

FreeRTOS projects must include implementations for the dynamic memory allocation functions
pvPortMalloc() and vPortFree(). The implementation would normally be contained within a file called
heap_1.c, heap_2.c, etc.

SAFERTOS does not permit any form of dynamic memory allocation so this file should be removed
from the project.

2.2 CHANGES TO X T ASK CREATE ()

The lack of dynamic memory allocation necessitates that the SAFERTOS version of xTaskCreate()
requires more parameters than its FreeRTOS counterpart. In addition, a SAFERTOS product variant
may require additional parameters when creating a task if, for example, a Memory Protection Unit
(MPU) or Memory Management Unit (MMU) is supported. Consequently, the SAFERTOS version of
xTaskCreate() accepts just 2 parameters – pxTaskParameters which is a pointer to an
xTaskParameters structure and pxCreatedTask which is used to pass back the handle of the created
task. This is similar to the FreeRTOS API function xTaskCreateRestricted().

The members of the xTaskParameter structure are specific to each product variant and are
described fully in the SAFERTOS v9 User Manual [Reference 1]. As a minimum, all product variants
require the following members to be present:

1. pvTaskCode

A pointer to the function that implements the task.

2. pcTaskName

A descriptive name for the task. This is mainly used to facilitate debugging.

3. pxTCB

A pointer to a statically declared xTCB used by the kernel to hold the task data structures.

4. pcStackBuffer

A pointer to the statically declared buffer to be used by the kernel to hold the task stack. Care
must be taken to ensure that the stack buffer is aligned correctly.

5. uxStackDepthBytes

The size of the buffer pointed to by the pcStackBuffer parameter.

6. pvParameters

A pointer that will be used as the parameter for the task being created.

Upgrading from FreeRTOS to Issue 3.0 Page 7

SAFERTOS® v9
THE INFORMATION CONTAINED IN THIS DOCUMENT IS PROPRIETARY AND SUBJECT TO THE RESTRICTIONS ON THE COVERPAGE .
Copyright date as document date.
 7. uxPriority

The priority at which the task will run.

8. pvObject

Points to the instance of the C++ object that tracks this TCB structure.

Refer to the API reference section of the SAFERTOS v9 User Manual [Reference 1] for a full
description of the xTaskCreate() function, and the accompanying demo application for some usage
examples.

2.3 CHANGES TO X Q UEUE C REATE ()

The lack of dynamic memory allocation and increased error checking necessitates that the
SAFERTOS version of xQueueCreate() requires three more parameters than its FreeRTOS
counterpart.

1. pcQueueMemory

Points to the statically declared buffer to be used by the kernel to hold the queue data
structures and storage area.

2. uxBufferLength

The size of the buffer pointed to by the pcQueueMemory parameter.

3. pxQueue

Used to return a handle to the queue being created.

The FreeRTOS xQueueCreate() function returns either a handle to the created queue, or
NULL should the function be unable to create the queue for any reason. The application
needs therefore only check the return value against NULL to know whether a valid queue
handle was returned or not. The improved error detection and reporting provided by
SAFERTOS replaces this binary pass/fail return value with a set of descriptive status codes
– necessitating that the queue handle instead be passed out of the function using this new
reference parameter.

Refer to the API reference section in the SAFERTOS v9 User Manual [Reference 1] for a full
description and the accompanying demo application for some usage examples.

Upgrading from FreeRTOS to Issue 3.0 Page 8

SAFERTOS® v9
THE INFORMATION CONTAINED IN THIS DOCUMENT IS PROPRIETARY AND SUBJECT TO THE RESTRICTIONS ON THE COVERPAGE .
Copyright date as document date.
2.4 CHANGES TO X S EMAPHORE CREATE BINARY ()

The lack of dynamic memory allocation and increased error checking necessitates that the
SAFERTOS version of xSemaphoreCreateBinary() requires different parameters to its FreeRTOS
counterpart.

1. pcSemaphoreBuffer

Points to the statically declared buffer to be used by the kernel to hold the semaphore data
structure. The buffer must have a size of portQUEUE_OVERHEAD_BYTES and be 8-byte
aligned.

2. pxSemaphore

Used to return a handle to the semaphore being created.

It should also be noted that Binary Semaphores in SAFERTOS are created in the “given” state where
the count is equal to 1. This is unlike FreeRTOS, where Binary Semaphores are created in the empty
or “taken” state, where the count is equal to 0.

Refer to the API reference section in the SAFERTOS v9 User Manual [Reference 1] for a full
description and a list of the possible error codes returned by SAFERTOS. Refer to the accompanying
demo application for some usage examples.

2.5 CHANGES TO X S EMAPHORE CREATE COUNTING ()

The lack of dynamic memory allocation and increased error checking necessitates that the
SAFERTOS version of xSemaphoreCreateCounting() requires two more parameters than its
FreeRTOS counterpart.

1. pcSemaphoreBuffer

Points to the statically declared buffer to be used by the kernel to hold the semaphore data
structure. The buffer must have a size of portQUEUE_OVERHEAD_BYTES and be 8-byte
aligned.

2. pxSemaphore

Used to return a handle to the semaphore being created.

Refer to the API reference section in the SAFERTOS v9 User Manual [Reference 1] for a full
description and a list of the possible error codes returned by SAFERTOS. Refer to the accompanying
demo application for some usage examples.

Upgrading from FreeRTOS to Issue 3.0 Page 9

SAFERTOS® v9
THE INFORMATION CONTAINED IN THIS DOCUMENT IS PROPRIETARY AND SUBJECT TO THE RESTRICTIONS ON THE COVERPAGE .
Copyright date as document date.
2.6 CHANGES TO X T IMER CREATE ()

The lack of dynamic memory allocation and increased error checking necessitates that the
SAFERTOS version of xTimerCreate() requires more parameters than its FreeRTOS counterpart.
xTimerCreate() has a parameter, timerInitParameters, which is a struct containing all of the
information used to create the timer. The elements of this struct are as follows:

1. pcTimerName

A descriptive name for the timer, used for debugging only.

2. xTimerPeriodInTicks

The period in ticks before the timer should elapse.

3. xIsPeriodic

Boolean indicating whether the timer is a periodic timer or a one-shot timer.

4. xTimerID

Application specified tag for this timer. This is provided to allow multiple timers to be serviced
by a single callback function.

5. pxNewTimer

A pointer to a buffer that will be used to manage the timer.

6. pxCallbackFunction

This should be a function pointer if the timer should call a function upon expiring. If this is
NULL, then task notifications shall be used instead.

7. pxTimerInstance

A pointer to the timer instance that this timer will belong to. The timers modules supports the
use of multiple timer instances (e.g. running at different priorities), specifying NULL is
advised and is used to refer to the default timer instance.

8. pvObject

A pointer to user defined data to be associated with this timer. Can be set to NULL if not
needed by the user application.

9. xTaskToNotify

Task handle used to directly notify a task (using the task notification feature) when a timer
expires. If this is NULL, the callback function shall be used instead.

Note that either pxCallbackFunction or xTaskToNotify must be NULL. Both cannot be non-NULL.

Upgrading from FreeRTOS to Issue 3.0 Page 10

SAFERTOS® v9
THE INFORMATION CONTAINED IN THIS DOCUMENT IS PROPRIETARY AND SUBJECT TO THE RESTRICTIONS ON THE COVERPAGE .
Copyright date as document date.
Refer to the API reference section in the SAFERTOS v9 User Manual [Reference 1] for a full
description and a list of the possible error codes returned by SAFERTOS. Refer to the accompanying
demo application for some usage examples.

2.7 CHANGES TO X E VENT GROUP C REATE ()

The lack of dynamic memory allocation and increased error checking necessitates that the
SAFERTOS version of xEventGroupCreate() requires two more parameters than its FreeRTOS
counterpart.

1. pxEventGroup

Points to the statically declared eventGroupType structure buffer to be used by the kernel to
hold the created event group.

2. pxEventGroupHandle

Used to return a handle to the event group being created.

The FreeRTOS xEventGroupCreate() function returns either a handle to the created event
group, or NULL should the function be unable to create the event group because of
insufficient heap. The application needs therefore only check the return value against NULL
to know whether a valid event group handle was returned or not. The improved error detection
and reporting provided by SAFERTOS replaces this binary pass/fail return value with a set
of descriptive status codes – necessitating that the event group handle instead be passed
out of the function using this new reference parameter.

Refer to the API reference section in the SAFERTOS v9 User Manual [Reference 1] for a full
description and the accompanying demo application for some usage examples.

2.8 CHANGES TO X M UTEX CREATE ()

The lack of dynamic memory allocation and increased error checking necessitates that the
SAFERTOS function xMutexCreate() requires two more parameters than its FreeRTOS counterparts
(xSemaphoreCreateMutex() and xSemaphoreCreateRecursiveMutex()).

1. pcMutexBuffer

Points to the statically declared buffer to be used by the kernel to hold the data required to
manage the mutex.

2. pxMutex

Used to return a handle to the mutex being created.

The FreeRTOS xSemaphoreCreateMutex() and xSemaphoreCreateRecursiveMutex()

functions return either a handle to the created mutex, or NULL should the function be unable
to create the mutex. The application needs therefore only check the return value against

Upgrading from FreeRTOS to Issue 3.0 Page 11

SAFERTOS® v9
THE INFORMATION CONTAINED IN THIS DOCUMENT IS PROPRIETARY AND SUBJECT TO THE RESTRICTIONS ON THE COVERPAGE .
Copyright date as document date.
 NULL to know whether a valid mutex handle was returned or not. The improved error
detection and reporting provided by SAFERTOS replaces this with a set of descriptive status
codes – necessitating that the mutex handle instead be passed out of the function using this
new reference parameter.

Refer to the API reference section in the SAFERTOS v9 User Manual [Reference 1] for a full
description and the accompanying demo application for some usage examples.

Upgrading from FreeRTOS to Issue 3.0 Page 12

SAFERTOS® v9
THE INFORMATION CONTAINED IN THIS DOCUMENT IS PROPRIETARY AND SUBJECT TO THE RESTRICTIONS ON THE COVERPAGE .
Copyright date as document date.
2.9 CHANGES TO X S TREAM B UFFER C REATE ()

The lack of dynamic memory allocation and increased error checking necessitates that the
SAFERTOS function xStreamBufferCreate() requires four more parameters than its FreeRTOS
counterpart of the same name.

1. pxStreamBufferHandle

Used to return a handle to the stream buffer being created.

2. uxIsMessageBuffer

A Boolean value used to determine if discretely sized messages or continuous data streams
are to be stored on the streambuffer.

3. pucStreamBufferStorageArea

Points to the statically declared buffer used by the kernel to store the data written to the
streambuffer.

4. pxStreamBuffer

Points to the statically declared buffer used by the kernel to store the streambuffer metadata.

The FreeRTOS xStreamBufferCreate() function returns either a handle to the created mutex,
or NULL should the function be unable to create the streambuffer. The application need
therefore only check the return value against NULL to know whether a valid mutex handle
was returned or not. The improved error detection and reporting provided by SAFERTOS
replaces this with a set of descriptive status codes – necessitating that the streambuffer
handle instead be passed out of the function using this new reference parameter.

Refer to the API reference section in the SAFERTOS v9 User Manual [Reference 1] for a full
description and the accompanying demo application for some usage examples.

Upgrading from FreeRTOS to Issue 3.0 Page 13

SAFERTOS® v9
THE INFORMATION CONTAINED IN THIS DOCUMENT IS PROPRIETARY AND SUBJECT TO THE RESTRICTIONS ON THE COVERPAGE .
Copyright date as document date.
CHAPTER 3

FUNCTIONALITY

Upgrading from FreeRTOS to Issue 3.0 Page 14

SAFERTOS® v9
THE INFORMATION CONTAINED IN THIS DOCUMENT IS PROPRIETARY AND SUBJECT TO THE RESTRICTIONS ON THE COVERPAGE .
Copyright date as document date.
3.1 RESTRICTED FUNCTIONALITY

The SAFERTOS functionality has been restricted to include only the core components necessary.
This is standard practice for source code that is intended to undergo formal audit or certification as
it greatly reduces the test burden.

3.1.1 Co-routines

SAFERTOS does not provide a co-routine implementation.

3.1.2 Queue Sets

SAFERTOS does not provide an implementation of Queue Sets, but it implements the Event
Multiplex API, which supersedes the FreeRTOS Queue Sets functionality. In fact, Event Multiplex
objects are sets of events that include Queues and Queue-derived events (Semaphores and
Mutexes) as well as Task Notifications and Event Groups.

3.1.3 Thread Local Storage

FreeRTOS allows associating each task with a configurable number of pointers to Thread Local
Storage (TLS) objects. It is also possible to set this number to zero, which will exclude this feature.

SAFERTOS always implements one TLS pointer, therefore the number is not configurable and
cannot be disabled.

3.1.4 Task Tags

FreeRTOS supports the possibility of assigning an application-defined tag to each task. Task tags
are a form of thread local storage with application-defined meaning. This is an optional feature for
advanced users.

SAFERTOS does not support task tags. However, it should be possible to use the TLS pointer
instead, depending on application requirements.

3.1.5 Removed API Functions

Refer to Table 4-1 for a FreeRTOS to SAFERTOS API function cross reference.

Upgrading from FreeRTOS to Issue 3.0 Page 15

SAFERTOS® v9
THE INFORMATION CONTAINED IN THIS DOCUMENT IS PROPRIETARY AND SUBJECT TO THE RESTRICTIONS ON THE COVERPAGE .
Copyright date as document date.
CHAPTER 4

FUNCTION AND MACRO NAMES

Upgrading from FreeRTOS to Issue 3.0 Page 16

SAFERTOS® v9
THE INFORMATION CONTAINED IN THIS DOCUMENT IS PROPRIETARY AND SUBJECT TO THE RESTRICTIONS ON THE COVERPAGE .
Copyright date as document date.
4.1 FUNCTION AND M ACRO NAMES

The SAFERTOS function naming convention requires each function name to be prefixed by a
character that describes its return type. In particular, functions that return a value of type
portBaseType are prefixed by an ‘x’, and functions that return a void are prefixed with a ‘v’. A greater
number of SAFERTOS functions than FreeRTOS functions return non void values, necessitating
that the prefixes assigned to these functions be updated accordingly.

Table 4-1 provides a cross reference between FreeRTOS API functions and macros, and their
SAFERTOS equivalents. This analysis was conducted using v10.5.1 of the FreeRTOS API and v9.4
of the SAFERTOS API.

Upgrading from FreeRTOS to Issue 3.0 Page 17

SAFERTOS® v9
THE INFORMATION CONTAINED IN THIS DOCUMENT IS PROPRIETARY AND SUBJECT TO THE RESTRICTIONS ON THE COVERPAGE .
Copyright date as document date.
 Table 4-1: FreeRTOS to SAFERTOS function name mapping

FreeRTOS Function SAFERTOS Equivalent Notes

Task and scheduler API

portSWITCH_TO_USER_MODE() vMPUTaskExecuteInUnprivilegedMode() This API function is only provided for SAFERTOS product variants that
support use of an MPU.

taskDISABLE_INTERRUPTS() Not implemented. For SAFERTOS, use safertosapiENTER_CRITICAL().

taskENABLE_INTERRUPTS() Not implemented. For SAFERTOS, use safertosapiEXIT_CRITICAL().

taskENTER_CRITICAL() safertosapiENTER_CRITICAL()

taskENTER_CRITICAL_FROM_ISR() Not implemented. For SAFERTOS, use

safertosapiSET_INTERRUPT_MASK_FROM_ISR(), which returns a
value that should be passed to the corresponding call to
safertosapiCLEAR_INTERRUPT_MASK_FROM_ISR(). The behavior
of these macros depends on the product variant. These macros will
not affect the critical nesting count and are not a precise equivalent to
the FreeRTOS functions.

taskEXIT_CRITICAL() safertosapiEXIT_CRITICAL()

Upgrading from FreeRTOS to SAFERTOS® v9 Issue 3.0 Page 18

THE INFORMATION CONTAINED IN THIS DOCUMENT IS PROPRIETARY AND SUBJECT TO THE RESTRICTIONS ON THE COVERPAGE .
Copyright date as document date.
 Table 4-1: FreeRTOS to SAFERTOS function name mapping

FreeRTOS Function SAFERTOS Equivalent Notes

taskEXIT_CRITICAL_FROM_ISR() Not implemented. For SAFERTOS, use

safertosapiCLEAR_INTERRUPT_MASK_FROM_ISR(), which takes
as its parameter the value returned by the corresponding
safertosapiSET_INTERRUPT_MASK_FROM_ISR(). The behavior of
these macros depends on the product variant. These macros will not
affect the critical nesting count and are not a precise equivalent to the
FreeRTOS functions.

vTaskAllocateMPURegions() xMPUSetTaskRegions() This API function is only provided for SAFERTOS product variants that
support use of an MPU.

xTaskAbortDelay() Not implemented.

xTaskCallApplicationTaskHook() Not implemented.

xTaskCheckForTimeOut() Not implemented.

Upgrading from FreeRTOS to SAFERTOS® v9 Issue 3.0 Page 19

THE INFORMATION CONTAINED IN THIS DOCUMENT IS PROPRIETARY AND SUBJECT TO THE RESTRICTIONS ON THE COVERPAGE .
Copyright date as document date.
 Table 4-1: FreeRTOS to SAFERTOS function name mapping

FreeRTOS Function SAFERTOS Equivalent Notes

xTaskCreate() xTaskCreate() The SAFERTOS version requires a pointer to a structure to be passed

in place of the task parameters, as detailed within this application note.
FreeRTOS returns pdPASS or
errCOULD_NOT_ALLOCATE_REQUIRED_MEMORY.
SAFERTOS also returns either pdPASS, or an error code should it not
be possible to create the task. The error codes
errNULL_PARAMETER_SUPPLIED,
errINVALID_TASK_CODE_POINTER, errINVALID_PRIORITY,
errINVALID_BYTE_ALIGNMENT and
errTASK_STACK_ALREADY_IN_USE are returned by all product
variants. Other error codes may be returned depending on the product
variant; refer to the SAFERTOS v9 User Manual [Reference 1].

xTaskCreateStatic() xTaskCreate() FreeRTOS provides this function to enable tasks to be created with a
statically allocated stack buffer. SAFERTOS tasks are by default
created with statically allocated stack buffers.

xTaskCreateRestricted() xTaskCreate() FreeRTOS only provides this API function for systems that include an
MPU implementation. The parameters supplied to the SAFERTOS
function are discussed within this application note.

vTaskDelay() xTaskDelay() SAFERTOS returns pdPASS or errSCHEDULER_IS_SUSPENDED.

vTaskDelayUntil() xTaskDelayUntil() SAFERTOS returns pdPASS, errSCHEDULER_IS_SUSPENDED,

errNULL_PARAMETER_SUPPLIED or errDID_NOT_YIELD.

Upgrading from FreeRTOS to SAFERTOS® v9 Issue 3.0 Page 20

THE INFORMATION CONTAINED IN THIS DOCUMENT IS PROPRIETARY AND SUBJECT TO THE RESTRICTIONS ON THE COVERPAGE .
Copyright date as document date.
 Table 4-1: FreeRTOS to SAFERTOS function name mapping

FreeRTOS Function SAFERTOS Equivalent Notes

xTaskDelayUntil() xTaskDelayUntil() SAFERTOS returns pdPASS, errSCHEDULER_IS_SUSPENDED,

errNULL_PARAMETER_SUPPLIED or errDID_NOT_YIELD whereas
FreeRTOS returns pdPASS or pdFAIL.

vTaskDelete() xTaskDelete() SAFERTOS returns pdPASS or errINVALID_TASK_HANDLE.

xTaskGetApplicationTaskTag() Not implemented. See Section 3.1.4.

xTaskGetCurrentTaskHandle() xTaskGetCurrentTaskHandle()

xTaskGetIdleTaskHandle() Not implemented.

xTaskGetHandle() Not implemented.

uxTaskGetNumberOfTasks() Not implemented.

vTaskGetRunTimeStats() Not implemented.

vTaskGetIdleRunTimeCounter Not implemented.

xTaskGetSchedulerState() xTaskIsSchedulerStarted() The SAFERTOS functions return pdTRUE if the scheduler has been
xTaskIsSchedulerStartedFromISR() started.

uxTaskGetStackHighWaterMark() Not implemented.

Upgrading from FreeRTOS to SAFERTOS® v9 Issue 3.0 Page 21

THE INFORMATION CONTAINED IN THIS DOCUMENT IS PROPRIETARY AND SUBJECT TO THE RESTRICTIONS ON THE COVERPAGE .
Copyright date as document date.
 Table 4-1: FreeRTOS to SAFERTOS function name mapping

FreeRTOS Function SAFERTOS Equivalent Notes

eTaskGetState() Not implemented.

uxTaskGetSystemState() Not implemented.

vTaskGetTaskInfo() Not implemented.

pvTaskGetThreadLocalStoragePointer() pvTaskTLSObjectGet() FreeRTOS provides for an array of TLS pointers, the size of which is
determined at compile time. SAFERTOS provides a single TLS object,
which is a void pointer that may be used to reference an arbitrary
structure defined, populated and maintained according to application
requirements.

pcTaskGetName() Not implemented.

xTaskGetTickCount() xTaskGetTickCount()

xTaskGetTickCountFromISR() xTaskGetTickCountFromISR()

vTaskList() Not implemented.

xTaskNotify() xTaskNotifySend() Note that SAFERTOS xTaskNotifySend() has differently ordered

parameters compared with FreeRTOS xTaskNotify().

xTaskNotifyAndQuery() Not implemented.

xTaskNotifyAndQueryFromISR() Not implemented.

Upgrading from FreeRTOS to SAFERTOS® v9 Issue 3.0 Page 22

THE INFORMATION CONTAINED IN THIS DOCUMENT IS PROPRIETARY AND SUBJECT TO THE RESTRICTIONS ON THE COVERPAGE .
Copyright date as document date.
 Table 4-1: FreeRTOS to SAFERTOS function name mapping

FreeRTOS Function SAFERTOS Equivalent Notes

xTaskNotifyFromISR() xTaskNotifySendFromISR() Note that SAFERTOS xTaskNotifySendFromISR() has differently

ordered parameters compared with FreeRTOS xTaskNotifyFromISR()
and SAFERTOS has no equivalent to pxHigherPriorityTaskWoken.

xTaskNotifyGive() Not implemented. For SAFERTOS, use xTaskNotifySend() to implement the FreeRTOS
“lightweight semaphore” task notification use case if required.

xTaskNotifyGiveFromISR() Not implemented. For SAFERTOS, use xTaskNotifySendFromISR() to implement the

FreeRTOS “lightweight semaphore” task notification use case if
required.

xTaskNotifyStateClear() Not implemented.

ulTaskNotifyTake() Not implemented. For SAFERTOS, use xTaskNotifyWait() to implement the FreeRTOS
“lightweight semaphore” task notification use case if required.

xTaskNotifyWait() xTaskNotifyWait()

uxTaskPriorityGet() xTaskPriorityGet() Whereas the FreeRTOS version returns the priority, the SAFERTOS
version passes the priority out using a reference parameter. This is to
permit the return value to provide more detailed error reporting.
SAFERTOS returns pdPASS, errNULL_PARAMETER_SUPPLIED or
errINVALID_TASK_HANDLE.

vTaskPrioritySet() xTaskPrioritySet() SAFERTOS returns pdPASS, errINVALID_PRIORITY or

errINVALID_TASK_HANDLE.

Upgrading from FreeRTOS to SAFERTOS® v9 Issue 3.0 Page 23

THE INFORMATION CONTAINED IN THIS DOCUMENT IS PROPRIETARY AND SUBJECT TO THE RESTRICTIONS ON THE COVERPAGE .
Copyright date as document date.
 Table 4-1: FreeRTOS to SAFERTOS function name mapping

FreeRTOS Function SAFERTOS Equivalent Notes

vTaskResume() xTaskResume() SAFERTOS returns pdPASS, errNULL_PARAMETER_SUPPLIED,

errINVALID_TASK_HANDLE or errTASK_WAS_NOT_SUSPENDED.

xTaskResumeAll() xTaskResumeScheduler() The name was changed to be more descriptive.

FreeRTOS returns a BaseType_t that simply indicates whether or not
a yield was performed within the function call; SAFERTOS does the
same but can also return the error code
errSCHEDULER_WAS_NOT_SUSPENDED.

xTaskResumeFromISR() Not implemented. This function is often misused under FreeRTOS and is considered
unsafe.

vTaskSetApplicationTaskTag() / Not implemented. For SAFERTOS, arbitrary thread local storage may be implemented
xTaskSetApplicationTaskTag() using the TLS object during task creation along with the
pvTaskTLSObjectGet() function. The TLS object may be used to
access thread (task) local storage structures of arbitrary size and
complexity according to application requirements.

vTaskSetThreadLocalStoragePointer() Not implemented. For SAFERTOS, arbitrary thread local storage may be implemented
using the TLS object during task creation along with the
pvTaskTLSObjectGet() function. The TLS object may be used to
access thread (task) local storage structures of arbitrary size and
complexity according to application requirements.

vTaskSetTimeOutState() Not implemented.

Upgrading from FreeRTOS to SAFERTOS® v9 Issue 3.0 Page 24

THE INFORMATION CONTAINED IN THIS DOCUMENT IS PROPRIETARY AND SUBJECT TO THE RESTRICTIONS ON THE COVERPAGE .
Copyright date as document date.
 Table 4-1: FreeRTOS to SAFERTOS function name mapping

FreeRTOS Function SAFERTOS Equivalent Notes

vTaskStartScheduler() xTaskStartScheduler() The SAFERTOS version requires a parameter that indicates whether
or not configuration checks should be performed before starting the
scheduler.
SAFERTOS also returns a number of error codes should it not be
possible to start the scheduler. The error codes
errNO_TASKS_CREATED and
errSCHEDULER_ALREADY_RUNNING are returned by all product
variants. Other error codes may be returned depending on the product
variant; refer to the SAFERTOS v9 User Manual [Reference 1].

vTaskStepTick() Not implemented. For internal use only, in SAFERTOS ports supporting ULPM.

vTaskSuspend() xTaskSuspend() SAFERTOS returns pdPASS, errSCHEDULER_IS_SUSPENDED,

errINVALID_TASK_HANDLE or errTASK_ALREADY_SUSPENDED.

vTaskSuspendAll() vTaskSuspendScheduler() The name was changed to be more descriptive.

taskYIELD() safertosapiYIELD()

portYIELD_FROM_ISR() / safertosapiYIELD_FROM_ISR() The SAFERTOS macro does not take an argument, unlike FreeRTOS.
portEND_SWITCHING_ISR() SAFERTOS will automatically determine whether a context switch is
necessary.

Queues API

vQueueAddToRegistry() Not implemented. Provided as a separate queue_register.c/h on request

Upgrading from FreeRTOS to SAFERTOS® v9 Issue 3.0 Page 25

THE INFORMATION CONTAINED IN THIS DOCUMENT IS PROPRIETARY AND SUBJECT TO THE RESTRICTIONS ON THE COVERPAGE .
Copyright date as document date.
 Table 4-1: FreeRTOS to SAFERTOS function name mapping

FreeRTOS Function SAFERTOS Equivalent Notes

xQueueAddToSet() Not implemented. See Section 3.1.2.

xQueueCreate() xQueueCreate() The SAFERTOS version requires extra parameters as detailed within
this application note.
FreeRTOS returns the handle of the created queue, or NULL if the
queue could not be created; SAFERTOS returns pdPASS,
errINVALID_BYTE_ALIGNMENT, errINVALID_QUEUE_LENGTH,
errINVALID_BUFFER_SIZE or errNULL_PARAMETER_SUPPLIED.

xQueueCreateSet() Not implemented. See Section 3.1.2.

xQueueCreateStatic() xQueueCreate() The SAFERTOS version requires parameters as detailed within this
application note.
FreeRTOS returns the handle of the created queue, or NULL if the
queue could not be created; SAFERTOS returns pdPASS,
errINVALID_BYTE_ALIGNMENT, errINVALID_QUEUE_LENGTH,
errINVALID_BUFFER_SIZE or errNULL_PARAMETER_SUPPLIED

vQueueDelete() Not implemented. The FreeRTOS version just frees the memory allocated to the queue,
whereas SAFERTOS does not dynamically allocate or free memory. It
is not considered safe to delete queues.

pcQueueGetName() Not implemented.

xQueueIsQueueEmptyFromISR() Not implemented.

xQueueIsQueueFullFromISR() Not implemented.

Upgrading from FreeRTOS to SAFERTOS® v9 Issue 3.0 Page 26

THE INFORMATION CONTAINED IN THIS DOCUMENT IS PROPRIETARY AND SUBJECT TO THE RESTRICTIONS ON THE COVERPAGE .
Copyright date as document date.
 Table 4-1: FreeRTOS to SAFERTOS function name mapping

FreeRTOS Function SAFERTOS Equivalent Notes

uxQueueMessagesWaiting() xQueueMessagesWaiting() Whereas the FreeRTOS version returns the number of messages, the
SAFERTOS version passes the number of messages out using a
reference parameter. This is to permit the return value to provide more
detailed error reporting. SAFERTOS returns pdPASS,
errNULL_PARAMETER_SUPPLIED or
errINVALID_QUEUE_HANDLE.

uxQueueMessagesWaitingFromISR() Not implemented.

xQueueOverwrite() Not implemented.

xQueueOverwriteFromISR() Not implemented.

xQueuePeek() xQueuePeek() FreeRTOS returns either pdPASS or errQUEUE_EMPTY; SAFERTOS

returns pdPASS, errSCHEDULER_IS_SUSPENDED,
errINVALID_QUEUE_HANDLE, errNULL_PARAMETER_SUPPLIED
or errQUEUE_EMPTY.

xQueuePeekFromISR() Not implemented.

xQueueReceive() xQueueReceive() FreeRTOS returns either pdPASS or errQUEUE_EMPTY; SAFERTOS

returns pdPASS, errSCHEDULER_IS_SUSPENDED,
errINVALID_QUEUE_HANDLE, errNULL_PARAMETER_SUPPLIED
or errQUEUE_EMPTY.

Upgrading from FreeRTOS to SAFERTOS® v9 Issue 3.0 Page 27

THE INFORMATION CONTAINED IN THIS DOCUMENT IS PROPRIETARY AND SUBJECT TO THE RESTRICTIONS ON THE COVERPAGE .
Copyright date as document date.
 Table 4-1: FreeRTOS to SAFERTOS function name mapping

FreeRTOS Function SAFERTOS Equivalent Notes

xQueueReceiveFromISR() xQueueReceiveFromISR() FreeRTOS returns either pdPASS or pdFAIL; SAFERTOS returns

pdPASS, errNULL_PARAMETER_SUPPLIED,
errINVALID_QUEUE_HANDLE or errQUEUE_EMPTY.

SAFERTOS has no equivalent to pxHigherPriorityTaskWoken.

xQueueRemoveFromSet() Not implemented. See Section 3.1.2.

xQueueReset() Not implemented.

xQueueSelectFromSet() Not implemented. See Section 3.1.2.

xQueueSelectFromSetFromISR() Not implemented. See Section 3.1.2.

xQueueSend() xQueueSend() FreeRTOS returns either pdPASS or errQUEUE_FULL; SAFERTOS

returns pdPASS, errSCHEDULER_IS_SUSPENDED,
errNULL_PARAMETER_SUPPLIED, errINVALID_QUEUE_HANDLE
or errQUEUE_FULL.

xQueueSendToFront() xQueueSendToFront() FreeRTOS returns either pdPASS or errQUEUE_FULL; SAFERTOS

returns pdPASS, errSCHEDULER_IS_SUSPENDED,
errNULL_PARAMETER_SUPPLIED, errINVALID_QUEUE_HANDLE
or errQUEUE_FULL.

Upgrading from FreeRTOS to SAFERTOS® v9 Issue 3.0 Page 28

THE INFORMATION CONTAINED IN THIS DOCUMENT IS PROPRIETARY AND SUBJECT TO THE RESTRICTIONS ON THE COVERPAGE .
Copyright date as document date.
 Table 4-1: FreeRTOS to SAFERTOS function name mapping

FreeRTOS Function SAFERTOS Equivalent Notes

xQueueSendToBack() xQueueSend() FreeRTOS returns either pdPASS or errQUEUE_FULL; SAFERTOS

returns pdPASS, errSCHEDULER_IS_SUSPENDED,
errNULL_PARAMETER_SUPPLIED, errINVALID_QUEUE_HANDLE
or errQUEUE_FULL.

xQueueSendToBackFromISR() xQueueSendFromISR() FreeRTOS returns either pdPASS or errQUEUE_FULL; SAFERTOS

returns pdPASS, errNULL_PARAMETER_SUPPLIED,
errINVALID_QUEUE_HANDLE or errQUEUE_FULL.

SAFERTOS has no equivalent to pxHigherPriorityTaskWoken.

xQueueSendFromISR() xQueueSendFromISR() FreeRTOS returns either pdPASS or errQUEUE_FULL; SAFERTOS

returns pdPASS, errNULL_PARAMETER_SUPPLIED,
errINVALID_QUEUE_HANDLE or errQUEUE_FULL.

SAFERTOS has no equivalent to pxHigherPriorityTaskWoken.

xQueueSendToFrontFromISR() xQueueSendToFrontFromISR() FreeRTOS returns either pdPASS or errQUEUE_FULL; SAFERTOS

returns pdPASS, errNULL_PARAMETER_SUPPLIED,
errINVALID_QUEUE_HANDLE or errQUEUE_FULL.

SAFERTOS has no equivalent to pxHigherPriorityTaskWoken.

uxQueueSpacesAvailable() Not implemented.

Upgrading from FreeRTOS to SAFERTOS® v9 Issue 3.0 Page 29

THE INFORMATION CONTAINED IN THIS DOCUMENT IS PROPRIETARY AND SUBJECT TO THE RESTRICTIONS ON THE COVERPAGE .
Copyright date as document date.
 Table 4-1: FreeRTOS to SAFERTOS function name mapping

FreeRTOS Function SAFERTOS Equivalent Notes

Semaphores API

vSemaphoreCreateBinary() xSemaphoreCreateBinary() The SAFERTOS version requires different parameters as detailed

within this application note.
SAFERTOS returns pdPASS, errINVALID_BYTE_ALIGNMENT or
errNULL_PARAMETER_SUPPLIED.

xSemaphoreCreateBinary() xSemaphoreCreateBinary() The SAFERTOS version requires different parameters as detailed

within this application note.
SAFERTOS returns pdPASS, errINVALID_BYTE_ALIGNMENT or
errNULL_PARAMETER_SUPPLIED.

xSemaphoreCreateBinaryStatic() xSemaphoreCreateBinary() The SAFERTOS version requires different parameters as detailed

within this application note.
SAFERTOS returns pdPASS, errINVALID_BYTE_ALIGNMENT or
errNULL_PARAMETER_SUPPLIED.

xSemaphoreCreateCounting() xSemaphoreCreateCounting() The SAFERTOS version requires different parameters as detailed

within this application note.
FreeRTOS returns the handle of the created semaphore, or NULL if
the semaphore could not be created; SAFERTOS returns pdPASS,
errINVALID_BYTE_ALIGNMENT,
errINVALID_INITIAL_SEMAPHORE_COUNT,
errINVALID_QUEUE_LENGTH or
errNULL_PARAMETER_SUPPLIED.

Upgrading from FreeRTOS to SAFERTOS® v9 Issue 3.0 Page 30

THE INFORMATION CONTAINED IN THIS DOCUMENT IS PROPRIETARY AND SUBJECT TO THE RESTRICTIONS ON THE COVERPAGE .
Copyright date as document date.
 Table 4-1: FreeRTOS to SAFERTOS function name mapping

FreeRTOS Function SAFERTOS Equivalent Notes

xSemaphoreCreateCountingStatic() xSemaphoreCreateCounting() The SAFERTOS version requires different parameters as detailed

within this application note.
FreeRTOS returns the handle of the created semaphore, or NULL if
the semaphore could not be created; SAFERTOS returns pdPASS,
errINVALID_BYTE_ALIGNMENT,
errINVALID_INITIAL_SEMAPHORE_COUNT,
errINVALID_QUEUE_LENGTH or
errNULL_PARAMETER_SUPPLIED.

xSemaphoreCreateMutex() xMutexCreate() The SAFERTOS version requires parameters as detailed within this
application note.
FreeRTOS returns the handle of the created mutex, or NULL if the
mutex could not be created; SAFERTOS returns pdPASS,
errQUEUE_ALREADY_IN_USE, errINVALID_BYTE_ALIGNMENT or
errNULL_PARAMETER_SUPPLIED

Mutexes always support recursion in SAFERTOS, FreeRTOS provides

different APIs for recursive and non-recursive mutexes.

Upgrading from FreeRTOS to SAFERTOS® v9 Issue 3.0 Page 31

THE INFORMATION CONTAINED IN THIS DOCUMENT IS PROPRIETARY AND SUBJECT TO THE RESTRICTIONS ON THE COVERPAGE .
Copyright date as document date.
 Table 4-1: FreeRTOS to SAFERTOS function name mapping

FreeRTOS Function SAFERTOS Equivalent Notes

xSemaphoreCreateMutexStatic() xMutexCreate() The SAFERTOS version requires parameters as detailed within this
application note.
FreeRTOS returns the handle of the created mutex, or NULL if the
mutex could not be created; SAFERTOS returns pdPASS,
errQUEUE_ALREADY_IN_USE, errINVALID_BYTE_ALIGNMENT or
errNULL_PARAMETER_SUPPLIED

Mutexes always support recursion in SAFERTOS, FreeRTOS provides

different APIs for recursive and non-recursive mutexes.

xSemaphoreCreateRecursiveMutex() xMutexCreate() The SAFERTOS version requires parameters as detailed within this
application note.
FreeRTOS returns the handle of the created mutex, or NULL if the
mutex could not be created; SAFERTOS returns pdPASS,
errQUEUE_ALREADY_IN_USE, errINVALID_BYTE_ALIGNMENT or
errNULL_PARAMETER_SUPPLIED

xSemaphoreCreateRecursiveMutexStatic( xMutexCreate() The SAFERTOS version requires parameters as detailed within this
) application note.
FreeRTOS returns the handle of the created mutex, or NULL if the
mutex could not be created; SAFERTOS returns pdPASS,
errQUEUE_ALREADY_IN_USE, errINVALID_BYTE_ALIGNMENT or
errNULL_PARAMETER_SUPPLIED

vSemaphoreDelete() Not implemented.

Upgrading from FreeRTOS to SAFERTOS® v9 Issue 3.0 Page 32

THE INFORMATION CONTAINED IN THIS DOCUMENT IS PROPRIETARY AND SUBJECT TO THE RESTRICTIONS ON THE COVERPAGE .
Copyright date as document date.
 Table 4-1: FreeRTOS to SAFERTOS function name mapping

FreeRTOS Function SAFERTOS Equivalent Notes

uxSemaphoreGetCount() xSemaphoreGetCountDepth() Whereas the FreeRTOS version returns the semaphore count, the
SAFERTOS version passes the count out using a reference
parameter. This is to permit the return value to provide more detailed
error reporting. SAFERTOS returns pdPASS,
errNULL_PARAMETER_SUPPLIED or errINVALID_QUEUE_HANDLE

xSemaphoreGetMutexHolder() Not implemented.

xSemaphoreGive() xSemaphoreGive() FreeRTOS returns either pdPASS or errQUEUE_FULL; SAFERTOS

returns pdPASS, errSCHEDULER_IS_SUSPENDED,
errINVALID_SEMAPHORE_HANDLE or
errSEMAPHORE_ALREADY_GIVEN.

In FreeRTOS, xSemaphoreGive() can be used interchangeably when

addressing semaphores or mutexes whereas SAFERTOS enforces
the use of xSemaphoreGive() with semaphores only.

xSemaphoreGiveFromISR() xSemaphoreGiveFromISR() FreeRTOS returns either pdPASS or errQUEUE_FULL; SAFERTOS

returns pdPASS, errNULL_PARAMETER_SUPPLIED,
errINVALID_SEMAPHORE_HANDLE or
errSEMAPHORE_ALREADY_GIVEN.

SAFERTOS has no equivalent to pxHigherPriorityTaskWoken.

xSemaphoreGiveRecursive() xMutexGive()

Upgrading from FreeRTOS to SAFERTOS® v9 Issue 3.0 Page 33

THE INFORMATION CONTAINED IN THIS DOCUMENT IS PROPRIETARY AND SUBJECT TO THE RESTRICTIONS ON THE COVERPAGE .
Copyright date as document date.
 Table 4-1: FreeRTOS to SAFERTOS function name mapping

FreeRTOS Function SAFERTOS Equivalent Notes

xSemaphoreTake() xSemaphoreTake() FreeRTOS returns either pdPASS or errQUEUE_EMPTY; SAFERTOS

returns pdPASS, errSCHEDULER_IS_SUSPENDED,
errINVALID_SEMAPHORE_HANDLE,
errSEMAPHORE_ALREADY_TAKEN.

In FreeRTOS, xSemaphoreTake() can be used interchangeably when

addressing semaphores or mutexes whereas SAFERTOS enforces
the use of xSemaphoreTake() with semaphores only.

SAFERTOS has no equivalent to pxHigherPriorityTaskWoken.

xSemaphoreTakeFromISR() xSemaphoreTakeFromISR() FreeRTOS returns either pdPASS or pdFAIL; SAFERTOS returns

pdPASS, errNULL_PARAMETER_SUPPLIED,
errINVALID_SEMAPHORE_HANDLE or
errSEMAPHORE_ALREADY_TAKEN.

xSemaphoreTakeRecursive() xMutexTake()

Software Timer API

xTimerChangePeriod() xTimerChangePeriod() FreeRTOS returns either pdPASS or pdFAIL; SAFERTOS returns

pdPASS, errINVALID_PARAMETERS, errINVALID_TIMER_HANDLE
or a return code from xQueueSend().

Upgrading from FreeRTOS to SAFERTOS® v9 Issue 3.0 Page 34

THE INFORMATION CONTAINED IN THIS DOCUMENT IS PROPRIETARY AND SUBJECT TO THE RESTRICTIONS ON THE COVERPAGE .
Copyright date as document date.
 Table 4-1: FreeRTOS to SAFERTOS function name mapping

FreeRTOS Function SAFERTOS Equivalent Notes

xTimerChangePeriodFromISR() xTimerChangePeriodFromISR() FreeRTOS returns either pdPASS or pdFAIL; SAFERTOS returns

pdPASS, errINVALID_PARAMETERS, errINVALID_TIMER_HANDLE
or a return code from xQueueSendFromISR().

SAFERTOS has no equivalent to pxHigherPriorityTaskWoken.

xTimerCreate() xTimerCreate() FreeRTOS returns the timer handle or NULL; SAFERTOS returns
pdPASS, errINVALID_PARAMETERS, errINVALID_TIMER_HANDLE,
errNULL_PARAMETER_SUPPLIED, errTIMER_ALREADY_IN_USE,
errINVALID_TIMER_TASK_INSTANCE or a return code from
xTaskCreate().

SAFERTOS uses a structure to pass the initialisation parameters to

xTimerCreate() rather than the list of individual parameters used in
FreeRTOS.

xTimerCreateStatic() xTimerCreate() FreeRTOS returns the timer handle or NULL; SAFERTOS returns
pdPASS, errINVALID_PARAMETERS, errINVALID_TIMER_HANDLE,
errNULL_PARAMETER_SUPPLIED, errTIMER_ALREADY_IN_USE,
errINVALID_TIMER_TASK_INSTANCE or a return code from
xTaskCreate().

SAFERTOS uses a structure to pass the initialisation parameters to

xTimerCreate() rather than the list of individual parameters used in
FreeRTOS.

Upgrading from FreeRTOS to SAFERTOS® v9 Issue 3.0 Page 35

THE INFORMATION CONTAINED IN THIS DOCUMENT IS PROPRIETARY AND SUBJECT TO THE RESTRICTIONS ON THE COVERPAGE .
Copyright date as document date.
 Table 4-1: FreeRTOS to SAFERTOS function name mapping

FreeRTOS Function SAFERTOS Equivalent Notes

xTimerDelete() xTimerDelete() FreeRTOS returns pdPASS or pdFAIL; SAFERTOS returns pdPASS,

errINVALID_TIMER_HANDLE or a return code from xQueueSend().

xTimerGetExpiryTime() Not implemented.

pcTimerGetName() Not implemented. For SAFERTOS, an arbitrary “timer local” storage object, present for
each software timer, may be initialized when a timer is created, and is
accessible via the pvTimerTLSObjectGet() function. This object is of
type void pointer and could be used to point to any arbitrary timer-
specific data structure, so timer names may be implemented as part of
such a structure, if required.

xTimerGetPeriod() Not implemented.

xTimerGetTimerDaemonTaskHandle() Not implemented.

pvTimerGetTimerID() xTimerGetTimerID() FreeRTOS returns the timer ID, SAFERTOS returns pdPASS,
errNULL_PARAMETER_SUPPLIED or errINVALID_TIMER_HANDLE

xTimerIsTimerActive() xTimerIsTimerActive() FreeRTOS returns either pdPASS or pdFAIL; SAFERTOS returns

pdTRUE, pdFALSE or errINVALID_TIMER_HANDLE

xTimerPendFunctionCall() Not implemented.

xTimerPendFunctionCallFromISR() Not implemented.

Upgrading from FreeRTOS to SAFERTOS® v9 Issue 3.0 Page 36

THE INFORMATION CONTAINED IN THIS DOCUMENT IS PROPRIETARY AND SUBJECT TO THE RESTRICTIONS ON THE COVERPAGE .
Copyright date as document date.
 Table 4-1: FreeRTOS to SAFERTOS function name mapping

FreeRTOS Function SAFERTOS Equivalent Notes

xTimerReset() xTimerStart() FreeRTOS returns pdPASS or pdFAIL; SAFERTOS returns pdPASS,

errINVALID_TIMER_HANDLE or a return code from xQueueSend().

xTimerResetFromISR() xTimerStartFromISR() FreeRTOS returns pdPASS or pdFAIL; SAFERTOS returns pdPASS,

errINVALID_TIMER_HANDLE or a return code from
xQueueSendFromISR().

SAFERTOS has no equivalent to pxHigherPriorityTaskWoken.

vTimerSetTimerID() Not implemented. In SAFERTOS, the timer ID is set when the timer is created. Arbitrary
timer-specific storage may be implemented via the timer local storage
object, accessible using pvTimerTLSObjectGet ()

xTimerStart() xTimerStart() FreeRTOS returns pdPASS or pdFAIL; SAFERTOS returns pdPASS,

errINVALID_TIMER_HANDLE or a return code from xQueueSend().

xTimerStartFromISR() xTimerStartFromISR() FreeRTOS returns pdPASS or pdFAIL; SAFERTOS returns pdPASS,

errINVALID_TIMER_HANDLE or a return code from
xQueueSendFromISR().

SAFERTOS has no equivalent to pxHigherPriorityTaskWoken.

xTimerStop() xTimerStop() FreeRTOS returns pdPASS or pdFAIL; SAFERTOS returns pdPASS,

errINVALID_TIMER_HANDLE or a return code from xQueueSend().

Upgrading from FreeRTOS to SAFERTOS® v9 Issue 3.0 Page 37

THE INFORMATION CONTAINED IN THIS DOCUMENT IS PROPRIETARY AND SUBJECT TO THE RESTRICTIONS ON THE COVERPAGE .
Copyright date as document date.
 Table 4-1: FreeRTOS to SAFERTOS function name mapping

FreeRTOS Function SAFERTOS Equivalent Notes

xTimerStopFromISR() xTimerStopFromISR() FreeRTOS returns pdPASS or pdFAIL; SAFERTOS returns pdPASS,

errINVALID_TIMER_HANDLE or a return code from
xQueueSendFromISR().

SAFERTOS has no equivalent to pxHigherPriorityTaskWoken.

vTimerSetReloadMode() Not implemented.

Event Groups API

xEventGroupClearBits() xEventGroupClearBits() FreeRTOS returns pdPASS or pdFALSE, SAFERTOS returns

pdPASS, errNULL_PARAMETER_SUPPLIED,
errINVALID_EVENT_GROUP_HANDLE or
errINVALID_PARAMETERS

xEventGroupClearBitsFromISR() xEventGroupClearBitsFromISR() FreeRTOS returns pdPASS or pdFALSE, SAFERTOS returns

pdPASS, errNULL_PARAMETER_SUPPLIED,
errINVALID_EVENT_GROUP_HANDLE or
errINVALID_PARAMETERS

xEventGroupCreate() xEventGroupCreate() The SAFERTOS version requires different parameters as detailed

within this application note.

FreeRTOS returns an event group handle or NULL. SAFERTOS

returns pdPASS, errNULL_PARAMETER_SUPPLIED,
errINVALID_EVENT_GROUP_HANDLE or
errEVENT_GROUP_ALREADY_IN_USE

Upgrading from FreeRTOS to SAFERTOS® v9 Issue 3.0 Page 38

THE INFORMATION CONTAINED IN THIS DOCUMENT IS PROPRIETARY AND SUBJECT TO THE RESTRICTIONS ON THE COVERPAGE .
Copyright date as document date.
 Table 4-1: FreeRTOS to SAFERTOS function name mapping

FreeRTOS Function SAFERTOS Equivalent Notes

xEventGroupCreateStatic() xEventGroupCreate() The SAFERTOS version requires different parameters as detailed

within this application note.

FreeRTOS returns an event group handle or NULL. SAFERTOS

returns pdPASS, errNULL_PARAMETER_SUPPLIED or
errINVALID_EVENT_GROUP_HANDLE.

vEventGroupDelete() xEventGroupDelete() FreeRTOS returns no value (void function), SAFERTOS returns

pdPASS or errNULL_PARAMETER_SUPPLIED.

xEventGroupGetBits() xEventGroupGetBits() FreeRTOS returns the event group bits that are set, or NULL.
SAFERTOS returns pdPASS, errNULL_PARAMETER_SUPPLIED or
errINVALID_EVENT_GROUP_HANDLE

xEventGroupGetBitsFromISR() xEventGroupGetBitsFromISR() FreeRTOS returns the event group bits that are set, or NULL.
SAFERTOS returns pdPASS, errNULL_PARAMETER_SUPPLIED or
errINVALID_EVENT_GROUP_HANDLE

xEventGroupSetBits() xEventGroupSetBits() FreeRTOS returns pdPASS or pdFALSE. SAFERTOS returns

pdPASS, errNULL_PARAMETER_SUPPLIED,
errINVALID_PARAMETERS or
errINVALID_EVENT_GROUP_HANDLE

xEventGroupSetBitsFromISR() xEventGroupSetBitsFromISR() FreeRTOS returns pdPASS or pdFALSE. SAFERTOS returns

pdPASS, errNULL_PARAMETER_SUPPLIED,
errINVALID_PARAMETERS or
errINVALID_EVENT_GROUP_HANDLE.
SAFERTOS has no equivalent to pxHigherPriorityTaskWoken.

Upgrading from FreeRTOS to SAFERTOS® v9 Issue 3.0 Page 39

THE INFORMATION CONTAINED IN THIS DOCUMENT IS PROPRIETARY AND SUBJECT TO THE RESTRICTIONS ON THE COVERPAGE .
Copyright date as document date.
 Table 4-1: FreeRTOS to SAFERTOS function name mapping

FreeRTOS Function SAFERTOS Equivalent Notes

xEventGroupSync() Not implemented.

xEventGroupWaitBits() xEventGroupWaitBits() FreeRTOS returns the value of the event group at the time the function
returns. SAFERTOS returns pdPASS,
errSCHEDULER_IS_SUSPENDED,
errNULL_PARAMETER_SUPPLIED, errINVALID_PARAMETERS,
errINVALID_EVENT_GROUP_HANDLE,
errEVENT_GROUP_DELETED or
errEVENT_GROUP_BITS_NOT_SET

Stream Buffer API

xStreamBufferBytesAvailable() xStreamBufferBytesAvailable() FreeRTOS returns the number of bytes available, SAFERTOS returns
the status code: pdPASS, errSB_NULL_HANDLE,
errSB_INVALID_HANDLE.

xStreamBufferCreate() xStreamBufferCreate() See Section 2.9 ‘Changes to xStreamBufferCreate()’.

xStreamBufferCreateStatic() xStreamBufferCreate() See Section 2.9 ‘Changes to xStreamBufferCreate()’.

vStreamBufferDelete() Not implemented.

xStreamBufferIsEmpty() xStreamBufferIsEmpty() FreeRTOS returns either pdTRUE or pdFALSE, depending on whether

the stream buffer is full. SAFERTOS returns the same values or
errSB_NULL_HANDLE or errSB_INVALID_HANDLE if there is an
error.

Upgrading from FreeRTOS to SAFERTOS® v9 Issue 3.0 Page 40

THE INFORMATION CONTAINED IN THIS DOCUMENT IS PROPRIETARY AND SUBJECT TO THE RESTRICTIONS ON THE COVERPAGE .
Copyright date as document date.
 Table 4-1: FreeRTOS to SAFERTOS function name mapping

FreeRTOS Function SAFERTOS Equivalent Notes

xStreamBufferIsFull() xStreamBufferIsFull() FreeRTOS returns either pdTRUE or pdFALSE, depending on whether

the stream buffer is full. SAFERTOS returns the same values or
errSB_NULL_HANDLE or errSB_INVALID_HANDLE if there is an
error.

xStreamBufferReceive() xStreamBufferReceive() FreeRTOS returns the number of bytes read by the API function.
SAFERTOS instead returns pdPASS if the operation was successful,
or errSB_NULL_HANDLE, errSB_SMALL_BUFFER,
errSB_NOTIFICATION_TIMEOUT, errSB_INVALID_HANDLE,
errSCHEDULER_IS_NOT_RUNNING if the operation failed.
The number of bytes read is passed out using the parameter
puxTotalBytesRead.

xStreamBufferReceiveFromISR() xStreamBufferReceiveFromISR() FreeRTOS returns the number of bytes read by the API function.
SAFERTOS instead returns pdPASS if the operation was successful,
or errSB_NULL_HANDLE, errSB_SMALL_BUFFER,
errSB_INVALID_HANDLE, errSCHEDULER_IS_NOT_RUNNING if
the operation failed.
The number of bytes read is passed out using the parameter
puxTotalBytesRead.

xStreamBufferReset() xStreamBufferReset() FreeRTOS returns pdPASS or pdFAIL. SAFERTOS can also return
errSB_NULL_HANDLE, errSB_INVALID_HANDLE.

Upgrading from FreeRTOS to SAFERTOS® v9 Issue 3.0 Page 41

THE INFORMATION CONTAINED IN THIS DOCUMENT IS PROPRIETARY AND SUBJECT TO THE RESTRICTIONS ON THE COVERPAGE .
Copyright date as document date.
 Table 4-1: FreeRTOS to SAFERTOS function name mapping

FreeRTOS Function SAFERTOS Equivalent Notes

xStreamBufferSend() xStreamBufferSend() FreeRTOS returns pdPASS or pdFAIL. SAFERTOS can also return
errSB_NULL_HANDLE, errSB_INVALID_HANDLE,
errSB_SMALL_BUFFER, errSCHEDULER_IS_NOT_RUNNING,
errSB_NOTIFICATION_TIMEOUT.
FreeRTOS returns the number of bytes written to the streambuffer.
SAFERTOS passes this value out via the puxBytesWritten parameter.

xStreamBufferSendFromISR() xStreamBufferSendFromISR() FreeRTOS returns pdPASS or pdFAIL. SAFERTOS can also return
errSB_NULL_HANDLE, errSB_INVALID_HANDLE,
errSB_SMALL_BUFFER, errSCHEDULER_IS_NOT_RUNNING,
errSB_NOTIFICATION_TIMEOUT.
FreeRTOS returns the number of bytes written to the streambuffer.
SAFERTOS passes this value out via the puxBytesWritten parameter.

xStreamBufferSetTriggerLevel() xStreamBufferSetTriggerLevel() FreeRTOS returns whether the new trigger level has been met, as
pdTRUE or pdFALSE.
SAFERTOS returns pdPASS if no error has occurred, or an error
code: errSB_ZERO_TRIGGER, errSB_TRIGGER_TOO_HIGH,
errSB_INVALID_HANDLE, errSB_NULL_HANDLE.
SAFERTOS does not indicate whether the new trigger level has been
met.

Upgrading from FreeRTOS to SAFERTOS® v9 Issue 3.0 Page 42

THE INFORMATION CONTAINED IN THIS DOCUMENT IS PROPRIETARY AND SUBJECT TO THE RESTRICTIONS ON THE COVERPAGE .
Copyright date as document date.
 Table 4-1: FreeRTOS to SAFERTOS function name mapping

FreeRTOS Function SAFERTOS Equivalent Notes

xStreamBufferSpacesAvailable() xStreamBufferSpacesAvailable() FreeRTOS returns the number of bytes that can be written to the
stream buffer before the stream buffer would be full.
SAFERTOS returns a status code; pdPASS if the operation was
successful, otherwise it will return errSB_NULL_HANDLE or
errSB_INVALID_HANDLE.
SAFERTOS passes the number of bytes that can be written to the
stream buffer before the stream buffer would be full back via the
parameter puxSpace.

Message Buffer API

xMessageBufferCreate() xStreamBufferCreate() SAFERTOS uses the streambuffer API functions to implement

message buffers. See Section 2.9 ‘Changes to xStreamBufferCreate()’
for more details on xStreamBufferCreate().

xMessageBufferCreateStatic() xStreamBufferCreate() SAFERTOS uses the streambuffer API functions to implement

message buffers. See Section 2.9 ‘Changes to xStreamBufferCreate()’
for more details on xStreamBufferCreate().

vMessageBufferDelete() Not implemented.

xMessageBufferIsEmpty() xStreamBufferIsEmpty() See the comparison for the FreeRTOS xStreamBufferIsEmpty().

xMessageBufferIsFull() xStreamBufferIsFull() See the comparison for the FreeRTOS xStreamBufferIsFull().

xMessageBufferReceive() xStreamBufferReceive(). See the comparison for the FreeRTOS xStreamBufferReceive().

Upgrading from FreeRTOS to SAFERTOS® v9 Issue 3.0 Page 43

THE INFORMATION CONTAINED IN THIS DOCUMENT IS PROPRIETARY AND SUBJECT TO THE RESTRICTIONS ON THE COVERPAGE .
Copyright date as document date.
 Table 4-1: FreeRTOS to SAFERTOS function name mapping

FreeRTOS Function SAFERTOS Equivalent Notes

xMessageBufferReceiveFromISR() xStreamBufferReceiveFromISR() See the comparison for the FreeRTOS

xStreamBufferReceiveFromISR().

xMessageBufferReset() xStreamBufferReset() See the comparison for the FreeRTOS xStreamBufferReset().

xMessageBufferSend() xStreamBufferSend() See the comparison for the FreeRTOS xStreamBufferSend().

xMessageBufferSendFromISR() xStreamBufferSendFromISR() See the comparison for the FreeRTOS xStreamBufferSendFromISR().

xMessageBufferSpacesAvailable() xStreamBufferSpacesAvailable() See the comparison for the FreeRTOS

xStreamBufferSpacesAvailable().

Upgrading from FreeRTOS to SAFERTOS® v9 Issue 3.0 Page 44

THE INFORMATION CONTAINED IN THIS DOCUMENT IS PROPRIETARY AND SUBJECT TO THE RESTRICTIONS ON THE COVERPAGE .
Copyright date as document date.
CHAPTER 5

CONFIGURATION PARAMETERS

Upgrading from FreeRTOS to Issue 3.0 Page 45

SAFERTOS® v9
THE INFORMATION CONTAINED IN THIS DOCUMENT IS PROPRIETARY AND SUBJECT TO THE RESTRICTIONS ON THE COVERPAGE.
Copyright date as document date.
5.1 CONFIGURATION M ACROS

While FreeRTOS offers a large number of configuration parameters via the FreeRTOSConfig.h
header file, SAFERTOS implements a fixed configuration, with a restricted number of configuration
macros. These are listed on Table 5-1.

Upgrading from FreeRTOS to Issue 3.0 Page 46

SAFERTOS® v9
THE INFORMATION CONTAINED IN THIS DOCUMENT IS PROPRIETARY AND SUBJECT TO THE RESTRICTIONS ON THE COVERPAGE .
Copyright date as document date.
 Table 5-1: FreeRTOS to SAFERTOS configuration macros mapping

FreeRTOS configuration parameter SAFERTOS equivalent Notes

All SAFERTOS ports with MPU support allow
configALLOW_UNPRIVILEGED_CRITICAL_SECTIONS N/A
unprivileged critical sections.
SAFERTOS does not use dynamic memory
configAPPLICATION_ALLOCATED_HEAP N/A
allocation.
Most FreeRTOS asserts map into runtime
configASSERT N/A
checks in SAFERTOS.
configCHECK_FOR_STACK_OVERFLOW Always ON
Passed as a parameter to
configCPU_CLOCK_HZ N/A
xTaskInitializeScheduler().
configDEINIT_TLS_BLOCK N/A See Section 3.1.3.
configENABLE_BACKWARD_COMPATIBILITY N/A This is specific to FreeRTOS.
configENABLE_ERRATA_837070_WORKAROUND configENABLE_ERRATA_837070_WORKAROUND Specific to ARM Cortex M7 ports.
configENFORCE_SYSTEM_CALLS_FROM_KERNEL_ONLY N/A Not supported.
configGENERATE_RUN_TIME_STATS Debug only, supplied on request
SAFERTOS does not use dynamic memory
configHEAP_CLEAR_MEMORY_ON_FREE N/A
allocation.
configIDLE_SHOULD_YIELD Always ON
configINCLUDE_APPLICATION_DEFINED_PRIVILEGED_FUNCTIONS N/A Not required by SAFERTOS.
configINIT_TLS_BLOCK N/A See Section 3.1.3.
configKERNEL_INTERRUPT_PRIORITY when
configKERNEL_INTERRUPT_PRIORITY
applicable
configMAX_SYSCALL_INTERRUPT_PRIORITY
configMAX_SYSCALL_INTERRUPT_PRIORITY
when applicable
configMAX_API_CALL_INTERRUPT_PRIORITY N/A
configMAX_CO_ROUTINE_PRIORITIES N/A See Section 3.1.1.
configMAX_PRIORITIES configMAX_PRIORITIES
configMAX_TASK_NAME_LEN N/A No limit, task name passed via a pointer.
configMESSAGE_BUFFER_LENGTH_TYPE configMESSAGE_BUFFER_LENGTH_TYPE

Upgrading from FreeRTOS to SAFERTOS® v9 Issue 3.0 Page 47

THE INFORMATION CONTAINED IN THIS DOCUMENT IS PROPRIETARY AND SUBJECT TO THE RESTRICTIONS ON THE COVERPAGE .
Copyright date as document date.
FreeRTOS configuration parameter SAFERTOS equivalent Notes
Not required on SAFERTOS, usually defined
configMINIMAL_STACK_SIZE N/A
within the host application
configNUM_THREAD_LOCAL_STORAGE_POINTERS Always 1 See Section 3.1.3.
configQUEUE_REGISTRY_SIZE configQUEUE_REGISTRY_SIZE Debug feature only.
configRECORD_STACK_HIGH_ADDRESS Always OFF Not supported by SAFERTOS.
configSET_TLS_BLOCK N/A See Section 3.1.3.
SAFERTOS does not use dynamic memory
configSTACK_ALLOCATION_FROM_SEPARATE_HEAP Always OFF
allocation.
configSTACK_DEPTH_TYPE N/A Stack depth is always in bytes.
SAFERTOS does not use dynamic memory
configSUPPORT_DYNAMIC_ALLOCATION Always OFF
allocation.
SAFERTOS does not use dynamic memory
configSUPPORT_STATIC_ALLOCATION Always ON
allocation.
Passed as a parameter to
configSYSTICK_CLOCK_HZ N/A
xTaskInitializeScheduler().
configTASK_NOTIFICATION_ARRAY_ENTRIES N/A SAFERTOS only supports 1 notification value.
configTEX_S_C_B_FLASH N/A FreeRTOS MPU specific setting.
configTEX_S_C_B_SRAM N/A FreeRTOS MPU specific setting.
Passed as a parameter to
configTICK_RATE_HZ N/A
xTaskInitializeScheduler().
Passed as a parameter to
configTIMER_QUEUE_LENGTH N/A
xTaskInitializeScheduler().
Passed as a parameter to
configTIMER_TASK_PRIORITY N/A
xTaskInitializeScheduler().
Passed as a parameter to
configTIMER_TASK_STACK_DEPTH N/A
xTaskInitializeScheduler().
configTLS_BLOCK_TYPE N/A Related to Newlib or Runtime TLS
SAFERTOS does not use dynamic memory
configTOTAL_HEAP_SIZE N/A
allocation.
configTOTAL_MPU_REGIONS configNUM_MPU_REGIONS Only applicable to some ports.
configUSE_16_BIT_TICKS Always OFF

Upgrading from FreeRTOS to Issue 3.0 Page 48

SAFERTOS® v9
THE INFORMATION CONTAINED IN THIS DOCUMENT IS PROPRIETARY AND SUBJECT TO THE RESTRICTIONS ON THE COVERPAGE .
Copyright date as document date.
FreeRTOS configuration parameter SAFERTOS equivalent Notes
configUSE_ALTERNATIVE_API Always OFF Deprecated on FreeRTOS.
configUSE_APPLICATION_TASK_TAG Always OFF See Section 3.1.4.
SAFERTOS does not make calls to runtime
configUSE_C_RUNTIME_TLS_SUPPORT N/A
libraries.
configUSE_CO_ROUTINES Always OFF See Section 3.1.1.
configUSE_COUNTING_SEMAPHORES Always ON
configUSE_DAEMON_TASK_STARTUP_HOOK Always OFF
Implemented via weak function:
configUSE_IDLE_HOOK Always ON vApplicationIdleHook(). See section 7.2 for more
details.
configUSE_LIST_DATA_INTEGRITY_CHECK_BYTES Always OFF
SAFERTOS does not use dynamic memory
configUSE_MALLOC_FAILED_HOOK N/A
allocation.
configUSE_MINI_LIST_ITEM Always ON.
configUSE_MUTEXES Always ON
SAFERTOS does not make calls to runtime
configUSE_NEWLIB_REENTRANT N/A
libraries.
configUSE_PORT_OPTIMISED_TASK_SELECTION Always OFF FreeRTOS specific.
configUSE_POSIX_ERRNO Always OFF
configUSE_PREEMPTION Always ON Preemption cannot be disabled in SAFERTOS.
configUSE_QUEUE_SETS Always OFF See Section 3.1.2.
configUSE_RECURSIVE_MUTEXES Always ON
configUSE_SB_COMPLETED_CALLBACK Always ON
configUSE_STATS_FORMATTING_FUNCTIONS Always OFF
configUSE_TASK_NOTIFICATIONS Always ON
Implemented via weak function:
configUSE_TICK_HOOK Always ON vApplicationTickHook().See section 7.2 for more
details.
configUSE_TICKLESS_IDLE N/A See section 7.5.

Upgrading from FreeRTOS to Issue 3.0 Page 49

SAFERTOS® v9
THE INFORMATION CONTAINED IN THIS DOCUMENT IS PROPRIETARY AND SUBJECT TO THE RESTRICTIONS ON THE COVERPAGE .
Copyright date as document date.
FreeRTOS configuration parameter SAFERTOS equivalent Notes
configUSE_TIME_SLICING Always ON
configUSE_TIMERS Always ON
configUSE_TRACE_FACILITY configUSE_TRACE_FACILITY Debug only, supplied on request
secureconfigMAX_SECURE_CONTEXTS N/A Not required by SAFERTOS.
INCLUDE_<function> N/A See Table 4-1.

Upgrading from FreeRTOS to Issue 3.0 Page 50

SAFERTOS® v9
THE INFORMATION CONTAINED IN THIS DOCUMENT IS PROPRIETARY AND SUBJECT TO THE RESTRICTIONS ON THE COVERPAGE .
Copyright date as document date.
CHAPTER 6

ERROR REPORTING

Upgrading from FreeRTOS to Issue 3.0 Page 51

SAFERTOS® v9
THE INFORMATION CONTAINED IN THIS DOCUMENT IS PROPRIETARY AND SUBJECT TO THE RESTRICTIONS ON THE COVERPAGE .
Copyright date as document date.
6.1 S IDE E FFECTS OF I NCREASED E RROR REPORTING

SAFERTOS functions generally return an error code or pdPASS, and those that need to have an
extra reference parameter in which to return data.

Care must be taken that application code is updated to correctly interpret the increased number of
function return values. For example, under FreeRTOS the code depicted by Listing 1 is valid because
xQueueSend() only returns one of two values indicating either success or failure. Under SAFERTOS
the code must be changed to that depicted by Listing 2 as only a value of pdPASS would indicate
success – whereas one of a number of values are used to indicate the cause of failure.

if( xQueueSend( xQueue, &ucItemToSend, 0 ) == pdFAIL )

{
/* Could not send to the queue. */
}

Listing 1: Checking a function return value for an error under FreeRTOS

if( xQueueSend( xQueue, &ucItemToSend, 0 ) != pdPASS )

{
/* Could not send to the queue. */
}

Listing 2: Checking a function return value for an error under SAFERTOS

Upgrading from FreeRTOS to Issue 3.0 Page 52

SAFERTOS® v9
THE INFORMATION CONTAINED IN THIS DOCUMENT IS PROPRIETARY AND SUBJECT TO THE RESTRICTIONS ON THE COVERPAGE .
Copyright date as document date.
CHAPTER 7

MISCELLANEOUS

Upgrading from FreeRTOS to Issue 3.0 Page 53

SAFERTOS® v9
THE INFORMATION CONTAINED IN THIS DOCUMENT IS PROPRIETARY AND SUBJECT TO THE RESTRICTIONS ON THE COVERPAGE .
Copyright date as document date.
7.1 HEADER F ILES

SAFERTOS uses SafeRTOS.h and SafeRTOSConfig.h in place of FreeRTOS.h and

FreeRTOSConfig.h

In order for an application to call a SAFERTOS API function, the source file simply needs to include
the SafeRTOS_API.h header file – so long as the compiler can locate the other SAFERTOS header
files, the required header files will be automatically included.

7.2 HOOK FUNCTIONS

The host application (the application that uses SAFERTOS) is required to provide an "Error Hook"
(or callback) function. In addition, the host application can optionally supply other hook functions: an
"Idle Hook", "Task Delete Hook", “System Call Hook” (or similar, depending on the specific port layer
used), "Tick Hook", a function to set up the tick interrupt timer and other architecture-specific hooks.

SAFERTOS calls the Error Hook function upon the detection of a fatal error – either a corruption
within the scheduler data structures or a potential stack overflow while performing a context switch.
The purpose of the Error Hook function is to allow the host application to place the system into a
‘safe state’.

Typically, SAFERTOS contains ‘weak’ definitions of optional hook functions, which can therefore be
overridden by alternative definitions in the host application. A pointers to the “System Call Hook”
function is passed to SAFERTOS as part of the xPORT_INIT_PARAMETERS structure referenced
in the call to xTaskInitializeScheduler(). Refer to the Architecture Variant SAFERTOS User Manual
[Reference 1] for a full description, and SafeRTOSConfig.c of the accompanying demonstration
application for further information.

NOTE: some FreeRTOS ports support a Task Switch Hook, which is called at every context switch.
This is not part of the official API for either FreeRTOS or SAFERTOS, and it is only supported on a
restricted number of SAFERTOS ports. Refer to the Architecture Variant SAFERTOS User Manual
[Reference 1] to confirm whether a Task Switch Hook is supported.

Upgrading from FreeRTOS to Issue 3.0 Page 54

SAFERTOS® v9
THE INFORMATION CONTAINED IN THIS DOCUMENT IS PROPRIETARY AND SUBJECT TO THE RESTRICTIONS ON THE COVERPAGE .
Copyright date as document date.
7.3 DIRECTORY S TRUCTURE

FreeRTOS has a directory, ‘include’ with all its .h files, contained within the kernel source directory.
SAFERTOS v9 has a more complex directory structure:

• SafeRTOS

o config – contains SafeRTOSConfig.h;

o kernel – contains the common .c files;

▪ include_api – contains the .h files intended to be included by the host

application;

▪ include_prv – contains the .h files for internal use;

o api – contains the files with the api related functionality of the portable layer. This is
where the SafeRTOS_API.h file is, which should be included by the host application
to use SAFERTOS;

o portable – contains the architecture and compiler specific code to support the
common files.

Some similar files have different names in FreeRTOS and SAFERTOS:

The FreeRTOS file tasks.c is called task.c under SAFERTOS.

The FreeRTOS file event_groups.c is called eventgroups.c under SAFERTOS.

The Ferrets file stream_buffer.c is called streambuffer.c under SAFERTOS.

FreeRTOS does not have a semaphore, mutex .c or evtmplx.c file. SAFERTOS has semaphore.c,
mutex.c and evtmplx.c.

7.4 DELAY CONSTANTS

The safertosapiMAX_DELAY macro is defined as the maximum number of ticks that can be
expressed (e.g. on a 32-bit platform it is usually defined as 0xFFFFFFFF).

However, under FreeRTOS, passing the portMAX_DELAY macro to a blocking function as

xTicksToWait parameter means that the task will block indefinitely. Under SAFERTOS, instead,
portMAX_DELAY is simply interpreted as its actual value in ticks.

This means that, under SAFERTOS, task cannot block forever. The maximum block time is
determined by the size of portTickType. For example, on a 32-bit platform, this is equal to
4294967295 ticks; if the tick rate is 1 kHz, this value translates into about 49 days.

Upgrading from FreeRTOS to Issue 3.0 Page 55

SAFERTOS® v9
THE INFORMATION CONTAINED IN THIS DOCUMENT IS PROPRIETARY AND SUBJECT TO THE RESTRICTIONS ON THE COVERPAGE .
Copyright date as document date.
7.5 T ICK - LESS M ODE

FreeRTOS includes the tick-less mode feature, which allows the system to enter a low-power mode
when no tasks are in the Ready state. The implementation of this feature is platform-specific and
should be implemented in the domain of the host application.

SAFERTOS includes some ports that implement tick-less mode, also called Ultra Low-Power Mode
(ULPM). On such ports the ULPM feature is always enabled, but it is possible to inhibit the transition
to low power mode. Check the architecture variant SAFERTOS v9 User Manual [Reference 1] for
more details.

Upgrading from FreeRTOS to Issue 3.0 Page 56

SAFERTOS® v9
THE INFORMATION CONTAINED IN THIS DOCUMENT IS PROPRIETARY AND SUBJECT TO THE RESTRICTIONS ON THE COVERPAGE .
Copyright date as document date.
 CONTACT INFORMATION

User feedback is essential to the continued maintenance and development of SAFERTOS. Please
provide all software and documentation comments and suggestions to the most convenient contact
point listed below.

Address: WITTENSTEIN high integrity systems Limited

Brown’s Court, Long Ashton Business Park
Yanley Lane, Long Ashton
Bristol, BS41 9LB
England
Phone: +44 (0)1275 395 600
Email: [email protected]

Website www.HighIntegritySystems.com

All Trademarks acknowledged.

Upgrading from FreeRTOS to Issue 3.0 Page 57

SAFERTOS® v9
THE INFORMATION CONTAINED IN THIS DOCUMENT IS PROPRIETARY AND SUBJECT TO THE RESTRICTIONS ON THE COVERPAGE .
Copyright date as document date.