Recent changes to Task control (task.h)

Task control (task.h) modified by Stefan Gast

Stefan Gast — Mon, 02 Dec 2013 12:48:35 -0000

--- v5
+++ v6
@@ -104,7 +104,7 @@
     :::c
     void vTaskDeadlineExtend(portTickType xTicksToAdd);

-TODO!
+Extends the current absolute deadline of the calling task until it gets recalculated again. If the task is currently running with an inherited deadline because it is holding a mutex, then the extended deadline will not be applied until the task is releasing the mutex. Extending the absolute deadline with this function has no effect on future deadline recalculation and can be thought of as a one-shot increase of the current absolute deadline. A future recalculation will use the original relative deadline again. **This function should not be used in combination with queues that were created with `eDeadlineRenewSent`. (TODO: Explain why!)**

 ---

@@ -120,7 +120,9 @@
     :::c
     portTickType xTaskDeadlineGetMinimumRemaining(xTaskHandle pxTask);

-TODO!
+Returns the minimum (over the whole lifetime of the task) amount of ticks a task had left before reaching its deadline. If the task reached or exceeded its deadline at some point, then the result is `0`.
+
+This functionality comes with a performance penalty, as the minimum time has to be updated each time a deadline gets recalculated, so it should only be used during application development. To activate it, the macro `INCLUDE_xTaskDeadlineGetMinimumRemaining` has to be defined as `1`.

 Removed functions

Task control (task.h) modified by Stefan Gast

Stefan Gast — Tue, 26 Nov 2013 14:11:50 -0000

--- v4
+++ v5
@@ -111,7 +111,9 @@
     :::c
     portTickType xTaskDeadlineGetRemaining(xTaskHandle pxTask);

-TODO!
+Returns the amount of ticks left until the given task reaches its absolute deadline. If `pxTask` is NULL, then the time remaining for the calling task is returned. If the task is blocked without an absolute deadline, then `portMAX_DELAY` is returned. If the task has reached or exceeded its deadline, then this function returns `0`.
+
+The macro `INCLUDE_xTaskDeadlineGetRemaining` has to be defined as `1` for this function to be available.

 ---

Task control (task.h) modified by Stefan Gast

Stefan Gast — Fri, 22 Nov 2013 21:35:52 -0000

--- v3
+++ v4
@@ -102,7 +102,7 @@
 ---

     :::c
-    void vTaskDeadlineExtend(portTickType xTicksToAdd)
+    void vTaskDeadlineExtend(portTickType xTicksToAdd);

 TODO!

Task control (task.h) modified by Stefan Gast

Stefan Gast — Fri, 22 Nov 2013 21:29:30 -0000

--- v2
+++ v3
@@ -71,6 +71,53 @@
 New functions and macros
 ------------------------

+    :::c
+    portTickType xTaskDelayUntilDeadline(void);
+
+This function blocks the calling task until its current absolute deadline is reached. After that, a new absolute deadline will be calculated, based on the configured relative deadline. If the current absolute deadline has already been reached or exceeded, then the macro `traceTASK_DELAY_UNTIL_DEADLINE_EXCEEDED` will be executed if defined. The function returns the number of ticks that the task had left until it would have reached the deadline. It is recommended to implement periodic tasks using this function,
+
+The macro `INCLUDE_xTaskDelayUntilDeadline` has to be defined as `1` for this function to be available.
+
+---
+
+    :::c
+    portTickType xTaskDeadlineGetNext(xTaskHandle pxTask);
+
+Returns the configured relative deadline for the given task. If `pxTask` is `NULL`, then the relative deadline of the calling task is returned.
+
+---
+
+    :::c
+    portTickType xTaskDeadlineSetNext(portTickType xNextDeadline);
+
+Sets the relative deadline of the calling task to the given amount of timer ticks. **The new value will not be used until a new absolute deadline is calculated for the task!** This function returns the previous setting for the relative deadline.
+
+---
+
+    :::c
+    #define taskNEW_DEADLINE    vTaskDelay((portTickType)0U, (signed portBASE_TYPE)pdTRUE)
+
+Force a recalculation of the absolute deadline of the calling task. The new absolute deadline will be the sum of the current time and the configured relative deadline.
+
+---
+
+    :::c
+    void vTaskDeadlineExtend(portTickType xTicksToAdd)
+
+TODO!
+
+---
+
+    :::c
+    portTickType xTaskDeadlineGetRemaining(xTaskHandle pxTask);
+
+TODO!
+
+---
+
+    :::c
+    portTickType xTaskDeadlineGetMinimumRemaining(xTaskHandle pxTask);
+
 TODO!

Task control (task.h) modified by Stefan Gast

Stefan Gast — Thu, 21 Nov 2013 20:52:48 -0000

--- v1
+++ v2
@@ -65,7 +65,7 @@
     :::c
     void vTaskList(signed char *pcWriteBuffer);

-Instead of writing the priority of each task the function now writes the absolute deadline of each task into the buffer. Please note that this requires a larger buffer: Currently each task requires 'configMAX_TASK_NAME_LEN + 52` bytes.
+Instead of writing the priority of each task the function now writes the absolute deadline of each task into the buffer. Please note that this requires a larger buffer: Currently each task requires `configMAX_TASK_NAME_LEN + 52` bytes.

 New functions and macros

Task control (task.h) modified by Stefan Gast

Stefan Gast — Thu, 21 Nov 2013 20:32:25 -0000

Task control (task.h)

Modified functions

portBASE_TYPE xTaskCreate(pdTASK_CODE pvTaskCode,
    const signed char * const pcName,
    unsigned short usStackDepth,
    void *pvParameters,
    portTickType xInitialDeadline,
    unsigned portBASE_TYPE uxFlags,
    xTaskHandle *pvCreatedTask);

Instead of expecting a priority value, the xTaskCreate function now requires the initial relative deadline of the task in ticks (xInitialDeadline). If the scheduler has already been started, the deadline runs from the time the task has been created, otherwise the deadline starts at the time the scheduler begins to run.

The original FreeRTOS allows the portPRIVILEGED_BIT to be ORed with the priority. Since we need each bit of the initial deadline, we cannot do this for the deadline parameter. Instead uxFlags is used, which can either be 0 or portPRIVILEGE_BIT.

typedef struct xTASK_PARAMETERS
{
    pdTASK_CODE pvTaskCode;
    const signed char * const pcName;
    unsigned short usStackDepth;
    void *pvParameters;
    portTickType xInitialDeadline;    /* <-- */
    unsigned portBASE_TYPE uxFlags;   /* <-- */
    portSTACK_TYPE *puxStackBuffer;
    xMemoryRegion xRegions[portNUM_CONFIGURABLE_REGIONS];
} xTaskParameters;

portBASE_TYPE xTaskCreateRestricted(xTaskParameters *pxTaskParameters,
    xTaskHandle *pxCreatedTask);

The changes in the xTaskParameters struct match those in the parameters of xTaskCreate. For the starting time of initial deadline, the same applies as with xTaskCreate.

void vTaskDelay(portTickType xTicksToDelay,
    signed portBASE_TYPE xRenewDeadline);

The new parameter xRenewDeadline determines whether the absolute deadline of the calling should be removed during the delay and a new absolute deadline should be calculated after waiting. If this is set to pdTRUE, then the new absolute deadline of the task will be the sum of the time the task was scheduled to wake up plus the relative deadline of the task. Otherwise the old absolute deadline will be kept.

void vTaskDelayUntil(portTickType *pxPreviousWakeTime,
    portTickType xTimeIncrement);

This function has been modified to always recalculate the absolute deadline after blocking, in the same manner as vTaskDelay does if xRenewDeadline is pdTRUE. If the function does not block because the desired wake up time has already been reached (or passed), then xTaskDelayUntil executes the traceTASK_DELAY_UNTIL_NONBLOCK macro and recalculates the new absolute deadline as the sum of the current time and the relative deadline of the task. If this happens, it usually means that the desired wake up frequency cannot be kept, so consider this to be a processing overflow!

void vTaskSuspend(xTaskHandle pxTaskToSleep);

If a task puts itself to sleep using vTaskSuspend, then this is considered to be voluntarily and the absolute deadline of the task gets removed. A new absolute deadline will be calculated upon resuming of the task (via vTaskResume or xTaskResumeFromISR). If this function is used to suspend another task than the calling one, then the absolute deadline will remain active.

void vTaskList(signed char *pcWriteBuffer);

Instead of writing the priority of each task the function now writes the absolute deadline of each task into the buffer. Please note that this requires a larger buffer: Currently each task requires 'configMAX_TASK_NAME_LEN + 52` bytes.

New functions and macros

TODO!

Removed functions

In the original FreeRTOS API following functions are used to manage fixed priorities. They are not needed for EDF scheduling and thus they have been removed from deadlineRTOS:

unsigned portBASE_TYPE uxTaskPriorityGet(xTaskHandle pxTask);
void vTaskPrioritySet(xTaskHandle pxTask, unsigned portBASE_TYPE uxNewPriority);