RTOS Kernel Control

Group that contains macros & functions to control the FreeRTOS kernel. More...

Collaboration diagram for RTOS Kernel Control:

Macros
#define	taskYIELD()   portYIELD()
	Macro for forcing a context switch.
#define	taskENTER_CRITICAL()   portENTER_CRITICAL()
	Macro to mark the start of a critical code region. Preemptive context switches cannot occur when in a critical region. More...
#define	taskENTER_CRITICAL_FROM_ISR()   portSET_INTERRUPT_MASK_FROM_ISR()
	Implementation of taskENTER_CRITICAL(), safe to be called from within an ISR. More...
#define	taskEXIT_CRITICAL()   portEXIT_CRITICAL()
	Macro to mark the end of a critical code region. Preemptive context switches cannot occur when in a critical region. More...
#define	taskEXIT_CRITICAL_FROM_ISR(x)   portCLEAR_INTERRUPT_MASK_FROM_ISR( x )
	Implementation of taskEXIT_CRITICAL(), safe to be called from within an ISR. More...
#define	taskDISABLE_INTERRUPTS()   portDISABLE_INTERRUPTS()
	Macro to disable all maskable interrupts.
#define	taskENABLE_INTERRUPTS()   portENABLE_INTERRUPTS()
	Macro to enable microcontroller interrupts.

Functions
void	vTaskStartScheduler (void) PRIVILEGED_FUNCTION
	Starts the real time kernel tick processing. After calling the kernel has control over which tasks are executed and when. More...
void	vTaskEndScheduler (void) PRIVILEGED_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 vTaskStartScheduler() was called, as if vTaskStartScheduler() had just returned. More...
void	vTaskSuspendAll (void) PRIVILEGED_FUNCTION
	Suspends the scheduler without disabling interrupts. Context switches will not occur while the scheduler is suspended. More...
BaseType_t	xTaskResumeAll (void) PRIVILEGED_FUNCTION
	Resumes scheduler activity after it was suspended by a call to vTaskSuspendAll(). More...

Detailed Description

Group that contains macros & functions to control the FreeRTOS kernel.

Macro Definition Documentation

taskENTER_CRITICAL

#define taskENTER_CRITICAL

(

)

portENTER_CRITICAL()

#include <task.h>

Macro 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!

taskENTER_CRITICAL_FROM_ISR

#define taskENTER_CRITICAL_FROM_ISR

(

)

portSET_INTERRUPT_MASK_FROM_ISR()

#include <task.h>

Implementation of taskENTER_CRITICAL(), safe to be called from within an ISR.

Note

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

taskEXIT_CRITICAL

#define taskEXIT_CRITICAL

(

)

portEXIT_CRITICAL()

#include <task.h>

Macro 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!

taskEXIT_CRITICAL_FROM_ISR

#define taskEXIT_CRITICAL_FROM_ISR

(

x

)

portCLEAR_INTERRUPT_MASK_FROM_ISR( x )

#include <task.h>

Implementation of taskEXIT_CRITICAL(), safe to be called from within an ISR.

Note

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

Function Documentation

vTaskEndScheduler()

void vTaskEndScheduler

(

void

)

#include <task.h>

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 vTaskStartScheduler() was called, as if vTaskStartScheduler() had just returned.

Note

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

See the demo application file main.c in the demo/PC directory for an example that uses vTaskEndScheduler().

vTaskEndScheduler() 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.

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

Example usage:

void vTaskCode( void * pvParameters )
{
    for( ;; )
    {
        // Task code goes here.
 
        // At some point we want to end the real time kernel processing
        // so call ...
        vTaskEndScheduler ();
    }
}
 
void vAFunction( void )
{
    // Create at least one task before starting the kernel.
    xTaskCreate( vTaskCode, "NAME", STACK_SIZE, NULL, tskIDLE_PRIORITY, NULL );
 
    // Start the real time kernel with preemption.
    vTaskStartScheduler ();
 
    // Will only get here when the vTaskCode () task has called
    // vTaskEndScheduler ().  When we get here we are back to single task
    // execution.
}

vTaskStartScheduler()

void vTaskStartScheduler

(

void

)

#include <task.h>

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

See the demo application file main.c for an example of creating tasks and starting the kernel.

Example usage:

void vAFunction( void )
{
    // Create at least one task before starting the kernel.
    xTaskCreate( vTaskCode, "NAME", STACK_SIZE, NULL, tskIDLE_PRIORITY, NULL );
 
    // Start the real time kernel with preemption.
    vTaskStartScheduler ();
 
    // Will not get here unless a task calls vTaskEndScheduler ()
}

vTaskSuspendAll()

void vTaskSuspendAll

(

void

)

#include <task.h>

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

After calling vTaskSuspendAll() the calling task will continue to execute without risk of being swapped out until a call to xTaskResumeAll() has been made.

API functions that have the potential to cause a context switch (for example, vTaskDelayUntil(), xQueueSend(), etc.) must not be called while the scheduler is suspended.

Example usage:

void vTask1( void * pvParameters )
{
    for( ;; )
    {
        // Task code goes here.
 
        // ...
 
        // At some point the task wants to perform a long operation during
        // which it does not want to get swapped out.  It cannot use
        // taskENTER_CRITICAL ()/taskEXIT_CRITICAL () as the length of the
        // operation may cause interrupts to be missed - including the
        // ticks.
 
        // Prevent the real time kernel swapping out the task.
        vTaskSuspendAll ();
 
        // 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.
        xTaskResumeAll ();
    }
}

xTaskResumeAll()

BaseType_t xTaskResumeAll

(

void

)

#include <task.h>

Resumes scheduler activity after it was suspended by a call to vTaskSuspendAll().

xTaskResumeAll() only resumes the scheduler. It does not unsuspend tasks that were previously suspended by a call to vTaskSuspend().

Returns

If resuming the scheduler caused a context switch then pdTRUE is returned, otherwise pdFALSE is returned.

Example usage:

void vTask1( void * pvParameters )
{
    for( ;; )
    {
        // Task code goes here.
 
        // ...
 
        // At some point the task wants to perform a long operation during
        // which it does not want to get swapped out.  It cannot use
        // taskENTER_CRITICAL ()/taskEXIT_CRITICAL () as the length of the
        // operation may cause interrupts to be missed - including the
        // ticks.
 
        // Prevent the real time kernel swapping out the task.
        vTaskSuspendAll ();
 
        // 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 real
        // time 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( !xTaskResumeAll () )
        {
            taskYIELD ();
        }
    }
}