Task Management

group OS_87x3e_Task

Define, create, and control task functions.

The Task Management function group allows to create, delete, and control tasks in the system.

Tasks can be in the following states:

  • RUNNING: The task that is currently running is in the RUNNING state. Only one task at a time can be in this state.

  • READY: Tasks which are ready to run are in the READY state. Once the RUNNING task has terminated or is WAITING, the next READY task with the highest priority becomes the RUNNING task.

  • WAITING: Tasks that are waiting for an event to occur are in the WAITING state.

  • INACTIVE: Tasks that are not created or terminated are in the INACTIVE state. These Tasks typically consume no system resources.

../../_images/OS-task-state-transition.jpg

Variables

bool (*os_task_create)(void **pp_handle, const char *p_name, void (*p_routine)(void*), void *p_param, uint16_t stack_size, uint16_t priority)

Create a new task and add it to the list of tasks that are ready to run.

os_task.h

Example usage 

// Task routine implementation.
void task_routine(void *p_param)
{
    for (;;)
    {
         // Task code goes here.
    }
}

// Task to be created.
int test(void)
{
    void *p_handle = NULL;
    uint32_t task_param;

    if (os_task_create(&p_handle, "task", task_routine,
                       &task_param, STACK_SIZE, TASK_PRIORITY) == true)
    {
        // Task created successfully.
    }
    else
    {
        // Task failed to create.
        return -1;
    }

    // Use the handle to delete the task.
    os_task_delete(p_handle);

    return 0;
}

Param pp_handle:

Used to pass back a handle by which the created task can be referenced.

Param p_name:

A descriptive name for the task.

Param p_routine:

Pointer to task routine function that must be implemented to never return.

Param p_param:

Pointer parameter passed to the task routine function.

Param stack_size:

The size of the task stack that is specified as the number of bytes.

Param priority:

The priority at which the task should run. Higher priority task has higher priority value.

Retval true:

Task was created successfully and added to task ready list.

Retval false:

Task was failed to create.

Return:

The status of the task creation.

bool (*os_task_delete)(void *p_handle)

Remove a task from RTOS’s task management. The task being deleted will be removed from RUNNING, READY or WAITING state.

os_task.h

Example usage 

// Task routine implementation.
void task_routine(void *p_param)
{
    for (;;)
    {
         // Task code goes here.
    }
}

// Task to be created and deleted.
int test(void)
{
    void *p_handle = NULL;
    uint32_t task_param;

    if (os_task_create(&p_handle, "task", task_routine,
                       &task_param, STACK_SIZE, TASK_PRIORITY) == true)
    {
        // Task created successfully.
    }
    else
    {
        // Task failed to create.
        return -1;
    }

    // Use the handle to delete the task.
    os_task_delete(p_handle);

    return 0;
}

Param p_handle:

The handle of the task to be deleted.

Retval true:

Task was deleted successfully.

Retval false:

Task was failed to delete.

Return:

The status of the task deletion.

bool (*os_task_suspend)(void *p_handle)

Suspend the task. The suspended task will not be scheduled and never get any microcontroller processing time.

os_task.h

Example usage 

// Task routine implementation.
void task_routine(void *p_param)
{
    for (;;)
    {
         // Task code goes here.
    }
}

// Task to be created and suspended.
int test(void)
{
    void *p_handle = NULL;
    uint32_t task_param;

    if (os_task_create(&p_handle, "task", task_routine,
                       &task_param, STACK_SIZE, TASK_PRIORITY) == true)
    {
        // Task created successfully.
    }
    else
    {
        // Task failed to create.
        return -1;
    }

    // Use the handle to suspend the created task.
    os_task_suspend(p_handle);

    return 0;
}

Param p_handle:

The handle of the task to be suspended.

Retval true:

Task was suspended successfully.

Retval false:

Task was failed to suspend.

Return:

The status of the task suspension.

bool (*os_task_resume)(void *p_handle)

Resume the suspended task.

os_task.h

Example usage 

// Task routine implementation.
void task_routine(void *p_param)
{
    for (;;)
    {
         // Task code goes here.
    }
}

// Task to be suspended and resumed.
int test(void)
{
    void *p_handle = NULL;
    uint32_t task_param;

    if (os_task_create(&p_handle, "task", task_routine,
                       &task_param, STACK_SIZE, TASK_PRIORITY) == true)
    {
        // Task created successfully.
    }
    else
    {
        // Task failed to create.
        return -1;
    }

    // Use the handle to suspend the created task.
    os_task_suspend(p_handle);

    // Resume the suspended task by ourselves.
    os_task_resume(p_handle);
    return 0;
}

Param p_handle:

The handle of the task to be resumed.

Retval true:

Task was resumed successfully.

Retval false:

Task was failed to resume.

Return:

The status of the task resume.

bool (*os_task_yield)(void)

Force a context swith and pass control to the next task that is in READY state.

os_task.h

Example usage 

// Task routine implementation.
void task_routine(void *p_param)
{
    for (;;)
    {
         // Force a context switch
         os_task_yield();
    }
}

// Task to be created.
int test(void)
{
    void *p_handle = NULL;
    uint32_t task_param;

    if (os_task_create(&p_handle, "task", task_routine,
                       &task_param, STACK_SIZE, TASK_PRIORITY) == true)
    {
        // Task created successfully.
    }
    else
    {
        // Task failed to create.
        return -1;
    }

    return 0;
}

Param None.:

Retval true:

Task was yielded successfully.

Retval false:

Task was failed to yield.

Return:

The status of the task resume.

bool (*os_task_handle_get)(void **pp_handle)

Get the handle of the current running task.

os_task.h

Example usage 

// Get current task handle.
int test(void)
{
    void *p_handle = NULL;

    os_task_handle_get(&p_handle);

    return 0;
}

Param pp_handle:

Used to pass back a handle by which the current task can be referenced.

Retval true:

Task handle was got successfully.

Retval false:

Task handle was failed to get.

Return:

The status of getting the current task handle.

bool (*os_task_priority_get)(void *p_handle, uint16_t *p_priority)

Get the priority of the specified task.

os_task.h

Example usage 

int test(void)
{
    void *p_handle = NULL;
    uint16_t priority;

    if (os_task_create(&p_handle, "task", task_routine,
                       NULL, STACK_SIZE, TASK_PRIORITY) == true)
    {
        // Task created successfully.
    }
    else
    {
        // Task failed to create.
        return -1;
    }

    // Get the task priority.
    os_task_priority_get(p_handle, &priority);

    return 0;
}

Param p_handle:

The handle of the task to be queried. Passing a NULL handle means querying the priority of the current task.

Param p_priority:

Used to pass back the priority of the task.

Retval true:

Task priority was got successfully.

Retval false:

Task priority was failed to get.

Return:

The status of getting the task priority.

bool (*os_task_priority_set)(void *p_handle, uint16_t priority)

Set the priority of the specified task.

os_task.h

Example usage 

int test(void)
{
    void *p_handle = NULL;
    uint16_t priority;

    if (os_task_create(&p_handle, "task", task_routine,
                       NULL, STACK_SIZE, TASK_PRIORITY) == true)
    {
        // Task created successfully.
    }
    else
    {
        // Task failed to create.
        return -1;
    }

    // Use the handle to raise the created task priority.
    os_task_priority_set(p_handle, TASK_PRIORITY + 1);

    // Use a NULL handle to raise the current task priority.
    os_task_priority_set(NULL, TASK_PRIORITY + 1);

    return 0;
}

Param p_handle:

The handle of the task for which the priority is being set. Passing a NULL handle means setting the priority of the current task.

Param priority:

The priority to which the task will be set.

Retval true:

Task priority was set successfully.

Retval false:

Task priority was failed to set.

Return:

The status of setting the task priority.

bool (*os_task_signal_send)(void *p_handle, uint32_t signal)

Send a notification signal to the specified task.

os_task.h

The notification signal sent to a task will remain pending until it is cleared by the task calling os_task_signal_recv(). If the task was already in the WAITING state to wait for the singal, then the task will be removed from WAITING state and the signal cleared.

Example usage 

int test(void)
{
    void *p_handle = NULL;
    uint32_t signal;

    if (os_task_create(&p_handle, "task", task_routine,
                       NULL, STACK_SIZE, TASK_PRIORITY) == true)
    {
        // Task created successfully.
    }
    else
    {
        // Task failed to create.
        return -1;
    }

    // Send signal to the created task.
    singal = 1;
    os_task_signal_send(p_handle, signal);

    return 0;
}

Param p_handle:

The handle of the task to which the signal is sent.

Param signal:

The signal to be sent.

Retval true:

Task signal was sent successfully.

Retval false:

Task signal was failed to send.

Return:

The status of sending the signal.

bool (*os_task_signal_recv)(uint32_t *p_signal, uint32_t wait_ms)

Wait for a notification signal.

os_task.h

Example usage 

int test(void)
{
    uint32_t signal;

    // Block to wait for the signal sent from other tasks.
    os_task_signal_recv(&signal, 0xFFFFFFFF);

    return 0;
}

Param p_signal:

Used to pass back the received signal.

Param wait_ms:

The timeout in milliseconds to wait for the signal.

  • 0 No blocking and return immediately.

  • 0xFFFFFFFF Block infinitely until the signal received.

  • others The timeout value in milliseconds.

Retval true:

Task signal was received successfully.

Retval false:

Task signal was failed to receive.

Return:

The status of receiving the signal.

bool (*os_task_signal_clear)(void *p_handle)

Clear the signal of the specified task.

os_task.h

Example usage 

int test(void)
{
    void *p_handle = NULL;
    uint32_t signal;

    if (os_task_create(&p_handle, "task", task_routine,
                       NULL, STACK_SIZE, TASK_PRIORITY) == true)
    {
        // Task created successfully.
    }
    else
    {
        // Task failed to create.
        return -1;
    }

    // Send signal to the created task.
    singal = 1;
    os_task_signal_send(p_handle, signal);

    // Clear signal of the created task.
    os_task_signal_clear(p_handle);

    return 0;
}

Param p_handle:

The handle of the task to which the signal is clear.

Retval true:

Task signal was cleared successfully.

Retval false:

Task signal was failed to clear.

Return:

The status of clearing the signal.