Kernel Control

taskYIELD

task. h

Macro for forcing a context switch.

taskENTER_CRITICAL

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!

taskEXIT_CRITICAL

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!

taskDISABLE_INTERRUPTS

task. h

Macro to disable all maskable interrupts.

taskENABLE_INTERRUPTS

task. h

Macro to enable microcontroller interrupts.

vTaskStartScheduler

task. h

 void vTaskStartScheduler( void ); 

Starts the real time kernel tick processing. After calling the kernel has control over which tasks are executed and when. This function does not return until an executing task calls vTaskEndScheduler ().

At least one task should be created via a call to xTaskCreate () before calling vTaskStartScheduler (). The idle task is created automatically when the first application task is created.

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 ()
 }

vTaskEndScheduler

task. h

 void vTaskEndScheduler( void ); 

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.

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

vTaskSuspendAll

task. h

 void vTaskSuspendAll( void ); 

Suspends all real time kernel activity while keeping interrupts (including the kernel tick) enabled.

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

task. h

 char xTaskResumeAll( void ); 

Resumes real time kernel activity following a call to vTaskSuspendAll (). After a call to vTaskSuspendAll () the kernel will take control of which task is executing at any time.

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 ();
   }
  }
 }