FreeRTOS::Kernel Namespace Reference

Kernel namespace that provides an interface to kernel functions. More...

Enumerations
enum class	SchedulerState : BaseType_t { Suspended = taskSCHEDULER_SUSPENDED , NotStarted = taskSCHEDULER_NOT_STARTED , Running = taskSCHEDULER_RUNNING }

Functions
SchedulerState	getSchedulerState ()
	Function that calls xTaskGetSchedulerState() More...
UBaseType_t	getNumberOfTasks ()
	Function that calls uxTaskGetNumberOfTasks() More...
TickType_t	getIdleRunTimeCounter ()
	Function that calls xTaskGetIdleRunTimeCounter() More...
TickType_t	getTickCount ()
	Function that calls xTaskGetTickCount() More...
TickType_t	getTickCountFromISR ()
	Function that calls xTaskGetTickCountFromISR() More...
void	yield ()
	Function that calls taskYIELD() More...
void	enterCritical ()
	Function that calls taskENTER_CRITICAL() More...
uint32_t	enterCriticalFromISR ()
	Function that calls taskENTER_CRITICAL_FROM_ISR() More...
void	exitCritical ()
	Function that calls taskEXIT_CRITICAL() More...
void	exitCriticalFromISR (const uint32_t interruptStatus)
	Function that calls taskEXIT_CRITICAL_FROM_ISR() More...
void	disableInterrupts ()
	Function that calls taskDISABLE_INTERRUPTS() More...
void	enableInterrupts ()
	Function that calls taskENABLE_INTERRUPTS() More...
void	startScheduler ()
	Function that calls vTaskStartScheduler() More...
void	endScheduler ()
	Function that calls vTaskEndScheduler() More...
void	suspendAll ()
	Function that calls vTaskSuspendAll() More...
bool	resumeAll ()
	Function that calls xTaskResumeAll() More...
void	stepTick (const TickType_t ticksToJump)
	Function that calls vTaskStepTick( const TickType_t xTicksToJump ) More...
bool	catchUpTicks (const TickType_t ticksToCatchUp)
	Function that calls xTaskCatchUpTicks( TickType_t xTicksToCatchUp ) More...

Variables
constexpr char	versionNumber [] = tskKERNEL_VERSION_NUMBER
	If versionNumber ends with + it represents the version in development after the numbered release.
constexpr BaseType_t	versionMajor = tskKERNEL_VERSION_MAJOR
constexpr BaseType_t	versionMinor = tskKERNEL_VERSION_MINOR
constexpr BaseType_t	versionBuild = tskKERNEL_VERSION_BUILD

Detailed Description

Kernel namespace that provides an interface to kernel functions.

Function Documentation

catchUpTicks()

bool FreeRTOS::Kernel::catchUpTicks ( const TickType_t  ticksToCatchUp )

inline

Function that calls xTaskCatchUpTicks( TickType_t xTicksToCatchUp )

Kernel.hpp

See also

https://www.freertos.org/vTaskStepTick.html

This function corrects the tick count value after the application code has held interrupts disabled for an extended period resulting in tick interrupts having been missed.

This function is similar to FreeRTOS::Kernel::stepTick(), however, unlike FreeRTOS::Kernel::stepTick(), FreeRTOS::Kernel::catchUpTicks() may move the tick count forward past a time at which a task should be removed from the blocked state. That means tasks may have to be removed from the blocked state as the tick count is moved.

Parameters

ticksToCatchUp

The number of tick interrupts that have been missed due to interrupts being disabled. Its value is not computed automatically, so must be computed by the application writer.

Return values

true	If moving the tick count forward resulted in a task leaving the blocked state and a context switch being performed.
false	Otherwise.

disableInterrupts()

void FreeRTOS::Kernel::disableInterrupts ( )

inline

Function that calls taskDISABLE_INTERRUPTS()

Kernel.hpp

See also

https://www.freertos.org/a00020.html#taskDISABLE_INTERRUPTS

Function to disable all maskable interrupts.

enableInterrupts()

void FreeRTOS::Kernel::enableInterrupts ( )

inline

Function that calls taskENABLE_INTERRUPTS()

Kernel.hpp

See also

https://www.freertos.org/a00020.html#taskENABLE_INTERRUPTS

Function to enable microcontroller interrupts.

endScheduler()

void FreeRTOS::Kernel::endScheduler ( )

inline

Function that calls vTaskEndScheduler()

Kernel.hpp

See also

https://www.freertos.org/a00133.html

Note

At the time of writing only the x86 real mode port, which runs on a PC in place of DOS, implements this function.

Stops the real time kernel tick. All created tasks will be automatically deleted and multitasking (either preemptive or cooperative) will stop. Execution then resumes from the point where FreeRTOS::Kernel::startScheduler() was called, as if FreeRTOS::Kernel::startScheduler() had just returned.

See the demo application file main. c in the demo/PC directory for an example that uses FreeRTOS::Kernel::endScheduler().

FreeRTOS::Kernel::endScheduler() requires an exit function to be defined within the portable layer (see vPortEndScheduler () in port. c for the PC port). This performs hardware specific operations such as stopping the kernel tick.

FreeRTOS::Kernel::endScheduler() will cause all of the resources allocated by the kernel to be freed - but will not free resources allocated by application tasks.

Example Usage

#include <FreeRTOS/Kernel.hpp>
#include <FreeRTOS/Task.hpp>
 
class MyTask : public FreeRTOS::Task {
 public:
  void taskFunction() final;
};
 
void MyTask::taskFunction() {
  for (;;) {
    // Task code goes here.
 
    // At some point we want to end the real time kernel processing so call ...
    FreeRTOS::Kernel::endScheduler();
  }
}
 
void vAFunction() {
  // Create at least one task before starting the RTOS kernel.
  MyTask task;
 
  // Start the real time kernel with preemption.
  FreeRTOS::Kernel::startScheduler();
 
  // Will only get here when MyTask::taskFunction() task has called
  // FreeRTOS::Kernel::endScheduler().  When we get here we are back to single
  // task execution.
}

enterCritical()

void FreeRTOS::Kernel::enterCritical ( )

inline

Function that calls taskENTER_CRITICAL()

Kernel.hpp

See also

https://www.freertos.org/taskENTER_CRITICAL_taskEXIT_CRITICAL.html

Function to mark the start of a critical code region. Preemptive context switches cannot occur when in a critical region.

Note

This may alter the stack (depending on the portable implementation) so must be used with care!

Example Usage

#include <FreeRTOS/Kernel.hpp>
#include <FreeRTOS/Task.hpp>
 
class MyTask : public FreeRTOS::Task {
 public:
  void taskFunction() final;
 
 private:
  void demoFunction();
};
 
void MyTask::demoFunction() {
  // Enter the critical section.  In this example, this function is itself
  // called from within a critical section, so entering this critical section
  // will result in a nesting depth of 2.
  FreeRTOS::Kernel::enterCritical();
 
  // Perform the action that is being protected by the critical section here.
 
  // Exit the critical section.  In this example, this function is itself called
  // from a critical section, so this call to FreeRTOS::Kernel::exitCritical()
  // will decrement the nesting count by one, but not result in interrupts
  // becoming enabled.
  FreeRTOS::Kernel::exitCritical();
}
 
void MyTask::taskFunction() {
  for (;;) {
    // Perform some functionality here.
 
    // Call FreeRTOS::Kernel::enterCritical() to create a critical section.
    FreeRTOS::Kernel::enterCritical();
 
    // Execute the code that requires the critical section here.
 
    // Calls to FreeRTOS::Kernel::enterCritical() can be nested so it is safe to
    // call a function that includes its own calls to
    // FreeRTOS::Kernel::enterCritical() and FreeRTOS::Kernel::exitCritical().
    demoFunction();
 
    // The operation that required the critical section is complete so exit the
    // critical section.  After this call to FreeRTOS::Kernel::exitCritical(),
    // the nesting depth will be zero, so interrupts will have been re-enabled.
    FreeRTOS::Kernel::exitCritical();
  }
}

enterCriticalFromISR()

uint32_t FreeRTOS::Kernel::enterCriticalFromISR ( )

inline

Function that calls taskENTER_CRITICAL_FROM_ISR()

Kernel.hpp

See also

https://www.freertos.org/taskENTER_CRITICAL_FROM_ISR_taskEXIT_CRITICAL_FROM_ISR.html

Return values

uint32_t

the interrupt mask state as it was before the macro was called. The value returned by FreeRTOS::Kernel::enterCriticalFromISR() must be used as the interruptStatus parameter in the matching call to FreeRTOS::Kernel::exitCriticalFromISR().

Function to mark the start of a critical code region. Preemptive context switches cannot occur when in a critical region.

Note

This may alter the stack (depending on the portable implementation) so must be used with care!

Example Usage

#include <FreeRTOS/Kernel.hpp>
 
void demoFunction() {
  uint32_t savedInterruptStatus;
 
  // Enter the critical section.  In this example, this function is itself
  // called from within a critical section, so entering this critical section
  // will result in a nesting depth of 2. Save the value returned by
  // FreeRTOS::Kernel::enterCriticalFromISR() into a local stack variable so it
  // can be passed into FreeRTOS::Kernel::exitCriticalFromISR().
  savedInterruptStatus = FreeRTOS::Kernel::enterCriticalFromISR();
 
  // Perform the action that is being protected by the critical section here.
 
  // Exit the critical section.  In this example, this function is itself called
  // from a critical section, so interrupts will have already been disabled
  // before a value was stored in savedInterruptStatus, and therefore passing
  // savedInterruptStatus into FreeRTOS::Kernel::exitCriticalFromISR() will not
  // result in interrupts being re-enabled.
  FreeRTOS::Kernel::exitCriticalFromISR(savedInterruptStatus);
}
 
void demoISR() {
  uint32_t savedInterruptStatus;
 
  // Call FreeRTOS::Kernel::enterCriticalFromISR() to create a critical section,
  // saving the returned value into a local stack variable.
  savedInterruptStatus = FreeRTOS::Kernel::enterCriticalFromISR();
 
  // Execute the code that requires the critical section here.
 
  // Calls to FreeRTOS::Kernel::enterCriticalFromISR() can be nested so it is
  // safe to call a function that includes its own calls to
  // FreeRTOS::Kernel::enterCriticalFromISR() and
  // FreeRTOS::Kernel::exitCriticalFromISR().
  demoFunction();
 
  // The operation that required the critical section is complete so exit the
  // critical section.  Assuming interrupts were enabled on entry to this ISR,
  // the value saved in savedInterruptStatus will result in interrupts being
  // re-enabled.
  FreeRTOS::Kernel::exitCriticalFromISR(savedInterruptStatus);
}

exitCritical()

void FreeRTOS::Kernel::exitCritical ( )

inline

Function that calls taskEXIT_CRITICAL()

Kernel.hpp

See also

https://www.freertos.org/taskENTER_CRITICAL_taskEXIT_CRITICAL.html

Function to mark the end of a critical code region. Preemptive context switches cannot occur when in a critical region.

Note

This may alter the stack (depending on the portable implementation) so must be used with care!

Example Usage

#include <FreeRTOS/Kernel.hpp>
#include <FreeRTOS/Task.hpp>
 
class MyTask : public FreeRTOS::Task {
 public:
  void taskFunction() final;
 
 private:
  void demoFunction();
};
 
void MyTask::demoFunction() {
  // Enter the critical section.  In this example, this function is itself
  // called from within a critical section, so entering this critical section
  // will result in a nesting depth of 2.
  FreeRTOS::Kernel::enterCritical();
 
  // Perform the action that is being protected by the critical section here.
 
  // Exit the critical section.  In this example, this function is itself called
  // from a critical section, so this call to FreeRTOS::Kernel::exitCritical()
  // will decrement the nesting count by one, but not result in interrupts
  // becoming enabled.
  FreeRTOS::Kernel::exitCritical();
}
 
void MyTask::taskFunction() {
  for (;;) {
    // Perform some functionality here.
 
    // Call FreeRTOS::Kernel::enterCritical() to create a critical section.
    FreeRTOS::Kernel::enterCritical();
 
    // Execute the code that requires the critical section here.
 
    // Calls to FreeRTOS::Kernel::enterCritical() can be nested so it is safe to
    // call a function that includes its own calls to
    // FreeRTOS::Kernel::enterCritical() and FreeRTOS::Kernel::exitCritical().
    demoFunction();
 
    // The operation that required the critical section is complete so exit the
    // critical section.  After this call to FreeRTOS::Kernel::exitCritical(),
    // the nesting depth will be zero, so interrupts will have been re-enabled.
    FreeRTOS::Kernel::exitCritical();
  }
}

exitCriticalFromISR()

void FreeRTOS::Kernel::exitCriticalFromISR ( const uint32_t  interruptStatus )

inline

Function that calls taskEXIT_CRITICAL_FROM_ISR()

Kernel.hpp

See also

https://www.freertos.org/taskENTER_CRITICAL_FROM_ISR_taskEXIT_CRITICAL_FROM_ISR.html

Parameters

interruptStatus

The value used as the interruptStatus parameter must be the value returned from the matching call to FreeRTOS::Kernel::enterCriticalFromISR().

Function to mark the end of a critical code region. Preemptive context switches cannot occur when in a critical region.

Note

This may alter the stack (depending on the portable implementation) so must be used with care!

Example Usage

#include <FreeRTOS/Kernel.hpp>
 
void demoFunction() {
  uint32_t savedInterruptStatus;
 
  // Enter the critical section.  In this example, this function is itself
  // called from within a critical section, so entering this critical section
  // will result in a nesting depth of 2. Save the value returned by
  // FreeRTOS::Kernel::enterCriticalFromISR() into a local stack variable so it
  // can be passed into FreeRTOS::Kernel::exitCriticalFromISR().
  savedInterruptStatus = FreeRTOS::Kernel::enterCriticalFromISR();
 
  // Perform the action that is being protected by the critical section here.
 
  // Exit the critical section.  In this example, this function is itself called
  // from a critical section, so interrupts will have already been disabled
  // before a value was stored in savedInterruptStatus, and therefore passing
  // savedInterruptStatus into FreeRTOS::Kernel::exitCriticalFromISR() will not
  // result in interrupts being re-enabled.
  FreeRTOS::Kernel::exitCriticalFromISR(savedInterruptStatus);
}
 
void demoISR() {
  uint32_t savedInterruptStatus;
 
  // Call FreeRTOS::Kernel::enterCriticalFromISR() to create a critical section,
  // saving the returned value into a local stack variable.
  savedInterruptStatus = FreeRTOS::Kernel::enterCriticalFromISR();
 
  // Execute the code that requires the critical section here.
 
  // Calls to FreeRTOS::Kernel::enterCriticalFromISR() can be nested so it is
  // safe to call a function that includes its own calls to
  // FreeRTOS::Kernel::enterCriticalFromISR() and
  // FreeRTOS::Kernel::exitCriticalFromISR().
  demoFunction();
 
  // The operation that required the critical section is complete so exit the
  // critical section.  Assuming interrupts were enabled on entry to this ISR,
  // the value saved in savedInterruptStatus will result in interrupts being
  // re-enabled.
  FreeRTOS::Kernel::exitCriticalFromISR(savedInterruptStatus);
}

getIdleRunTimeCounter()

TickType_t FreeRTOS::Kernel::getIdleRunTimeCounter ( )

inline

Function that calls xTaskGetIdleRunTimeCounter()

Kernel.hpp

See also

https://www.freertos.org/a00021.html#vTaskGetIdleRunTimeCounter

Return values

TickType_t

The run-time counter for the Idle task.

This function can be used to determine how much CPU time the idle task receives. See the Run Time Stats page for a full description of the run-time-stats feature.

configGENERATE_RUN_TIME_STATS and INCLUDE_xTaskGetIdleTaskHandle must both be defined as 1 for this function to be available. The application must also then provide definitions for portCONFIGURE_TIMER_FOR_RUN_TIME_STATS() and portGET_RUN_TIME_COUNTER_VALUE to configure a peripheral timer/counter and return the timer's current count value respectively. It is recommended to make the timer at least 10 times the frequency of the tick count.

getNumberOfTasks()

UBaseType_t FreeRTOS::Kernel::getNumberOfTasks ( )

inline

Function that calls uxTaskGetNumberOfTasks()

Kernel.hpp

See also

https://www.freertos.org/a00021.html#usTaskGetNumberOfTasks

Return values

UBaseType_t

The number of tasks that the real time kernel is currently managing. This includes all ready, blocked and suspended tasks. A task that has been deleted but not yet freed by the idle task will also be included in the count.

getSchedulerState()

SchedulerState FreeRTOS::Kernel::getSchedulerState ( )

inline

Function that calls xTaskGetSchedulerState()

Kernel.hpp

See also

https://www.freertos.org/a00021.html#xTaskGetSchedulerState

Return values

SchedulerState

Returns the scheduler state as Running, NotStarted, or Suspended.

getTickCount()

TickType_t FreeRTOS::Kernel::getTickCount ( )

inline

Function that calls xTaskGetTickCount()

Kernel.hpp

See also

https://www.freertos.org/a00021.html#xTaskGetTickCount

Return values

TickType_t

The count of ticks since FreeRTOS::Kernel::startScheduler() was called.

getTickCountFromISR()

TickType_t FreeRTOS::Kernel::getTickCountFromISR ( )

inline

Function that calls xTaskGetTickCountFromISR()

Kernel.hpp

See also

https://www.freertos.org/a00021.html#xTaskGetTickCountFromISR

Return values

TickType_t

The count of ticks since FreeRTOS::Kernel::startScheduler() was called.

This is a version of FreeRTOS::Kernel::getTickCount() that is safe to be called from an ISR - provided that TickType_t is the natural word size of the microcontroller being used or interrupt nesting is either not supported or not being used.

resumeAll()

bool FreeRTOS::Kernel::resumeAll ( )

inline

Function that calls xTaskResumeAll()

Kernel.hpp

See also

https://www.freertos.org/a00135.html

Resumes scheduler activity after it was suspended by a call to FreeRTOS::Kernel::suspendAll().

FreeRTOS::Kernel::resumeAll() only resumes the scheduler. It does not unsuspend tasks that were previously suspended by a call to FreeRTOS::Task::suspend().

Return values

true	If resuming the scheduler caused a context switch.
false	Otherwise.

Example Usage

#include <FreeRTOS/Kernel.hpp>
#include <FreeRTOS/Task.hpp>
 
class MyTask : public FreeRTOS::Task {
 public:
  void taskFunction() final;
};
 
void MyTask::taskFunction() {
  for (;;) {
    // Task code goes here.
 
    // ...
 
    // At some point the task wants to perform an operation during which it does
    // not want to get swapped out, or it wants to access data which is also
    // accessed from another task (but not from an interrupt).  It cannot use
    // FreeRTOS::Task::enterCritical() or FreeRTOS::Task::exitCritical() as the
    // length of the operation may cause interrupts to be missed.
 
    // Prevent the real time kernel swapping out the task.
    FreeRTOS::Kernel::suspendAll();
 
    // Perform the operation here.  There is no need to use critical sections as
    // we have all the microcontroller processing time.  During this time
    // interrupts will still operate and the kernel tick count will be
    // maintained.
 
    // ...
 
    // The operation is complete.  Restart the kernel.  We want to force a
    // context switch - but there is no point if resuming the scheduler caused a
    // context switch already.
    if (!FreeRTOS::Kernel::resumeAll()) {
      FreeRTOS::Kernel::yield();
    }
  }
}

startScheduler()

void FreeRTOS::Kernel::startScheduler ( )

inline

Function that calls vTaskStartScheduler()

Kernel.hpp

See also

https://www.freertos.org/a00132.html

Starts the real time kernel tick processing. After calling the kernel has control over which tasks are executed and when.

Example Usage

#include <FreeRTOS/Kernel.hpp>
#include <FreeRTOS/Task.hpp>
 
class MyTask : public FreeRTOS::Task {
 public:
  void taskFunction() final;
};
 
void vAFunction() {
  // Create a task before starting the kernel.
  MyTask task;
 
  // Start the real time kernel with preemption.
  FreeRTOS::Kernel::startScheduler();
 
  // Will not get here unless a task calls FreeRTOS::Kernel::endScheduler()
}

stepTick()

void FreeRTOS::Kernel::stepTick ( const TickType_t  ticksToJump )

inline

Function that calls vTaskStepTick( const TickType_t xTicksToJump )

Kernel.hpp

See also

https://www.freertos.org/vTaskStepTick.html

Only available when configUSE_TICKLESS_IDLE is set to 1. If tickless mode is being used, or a low power mode is implemented, then the tick interrupt will not execute during idle periods. When this is the case, the tick count value maintained by the scheduler needs to be kept up to date with the actual execution time by being skipped forward by a time equal to the idle period.

Parameters

ticksToJump

The number of RTOS ticks that have passed since the tick interrupt was stopped.

suspendAll()

void FreeRTOS::Kernel::suspendAll ( )

inline

Function that calls vTaskSuspendAll()

Kernel.hpp

See also

https://www.freertos.org/a00134.html

Suspends the scheduler without disabling interrupts. Context switches will not occur while the scheduler is suspended.

After calling FreeRTOS::Kernel::suspendAll() the calling task will continue to execute without risk of being swapped out until a call to FreeRTOS::Kernel::resumeAll() has been made.

API functions that have the potential to cause a context switch (for example, FreeRTOS::Task::delayUntil(), FreeRTOS::Queue::send(), etc.) must not be called while the scheduler is suspended.

Example Usage

#include <FreeRTOS/Kernel.hpp>
#include <FreeRTOS/Task.hpp>
 
class MyTask : public FreeRTOS::Task {
 public:
  void taskFunction() final;
};
 
void MyTask::taskFunction() {
  for (;;) {
    // Task code goes here.
 
    // ...
 
    // At some point the task wants to perform an operation during which it does
    // not want to get swapped out, or it wants to access data which is also
    // accessed from another task (but not from an interrupt).  It cannot use
    // FreeRTOS::Task::enterCritical() or FreeRTOS::Task::exitCritical() as the
    // length of the operation may cause interrupts to be missed.
 
    // Prevent the real time kernel swapping out the task.
    FreeRTOS::Kernel::suspendAll();
 
    // Perform the operation here.  There is no need to use critical sections as
    // we have all the microcontroller processing time.  During this time
    // interrupts will still operate and the kernel tick count will be
    // maintained.
 
    // ...
 
    // The operation is complete.  Restart the kernel.
    FreeRTOS::Kernel::resumeAll();
  }
}

yield()

void FreeRTOS::Kernel::yield ( )

inline

Function that calls taskYIELD()

Kernel.hpp

See also

https://www.freertos.org/a00020.html#taskYIELD

FreeRTOS::Kernel::yield() is used to request a context switch to another task. However, if there are no other tasks at a higher or equal priority to the task that calls FreeRTOS::Kernel::yield() then the RTOS scheduler will simply select the task that called FreeRTOS::Kernel::yield() to run again.