Kernel Task Management API#

OSTaskChangePrio()
OSTaskCreate()
OSTaskDel()
OSTaskQFlush()
OSTaskQPend()
OSTaskQPendAbort()
OSTaskQPost()
OSTaskRegGet()
OSTaskRegGetID()
OSTaskRegSet()
OSTaskResume()
OSTaskSuspend()
OSTaskSemPend()
OSTaskSemPendAbort()
OSTaskSemPost()
OSTaskSemSet()
OSTaskStkChk()
OSTaskStkRedzoneChk()
OSTaskTimeQuantaSet()

OSTaskChangePrio()#

Description#

Allows you to dynamically change the priority of a task. Note that the new priority MUST be available.

Files#

os.h/os_task.c

Prototype#

void  OSTaskChangePrio (OS_TCB    *p_tcb,
                        OS_PRIO    prio_new,
                        RTOS_ERR  *p_err)

Arguments#

p_tcb

Pointer to the TCB of the task for which to change the priority.

prio_new

The new priority.

p_err

Pointer to the variable that will receive one of the following error code(s) from this function:

RTOS_ERR_NONE
RTOS_ERR_INVALID_ARG

Returned Value#

None.

Notes / Warnings#

None.

OSTaskCreate()#

Description#

Allows the the Kernel to manage the execution of a task. Tasks can either be created prior to the start of multitasking or by a running task. A task cannot be created by an ISR.

Files#

os.h/os_task.c

Prototype#

void  OSTaskCreate (OS_TCB        *p_tcb,
                    CPU_CHAR      *p_name,
                    OS_TASK_PTR    p_task,
                    void          *p_arg,
                    OS_PRIO        prio,
                    CPU_STK       *p_stk_base,
                    CPU_STK_SIZE   stk_limit,
                    CPU_STK_SIZE   stk_size,
                    OS_MSG_QTY     q_size,
                    OS_TICK        time_quanta,
                    void          *p_ext,
                    OS_OPT         opt,
                    RTOS_ERR      *p_err)

Arguments#

p_tcb

Pointer to the task's TCB.

p_name

Pointer to an ASCII string that provides a name for the task.

p_task

Pointer to the task's code.

p_arg

Pointer to an optional data area which can pass parameters to the task when the task executes. For the task, it believes it was invoked and passed the argument 'p_arg' as follows:

void Task (void p_arg) { for (;;) { Task code; } }

prio

The task's priority. A unique priority MUST be assigned to each task. The lower the number, the higher the priority.

p_stk_base

Pointer to the base address of the stack (i.e., low address).

stk_limit

The number of stack elements to set as 'watermark' limits for the stack. This value represents the number of CPU_STK entries left before the stack is full. For example, specifying 10% of the 'stk_size' value indicates that the stack limit will be reached when the stack reaches 90% full.

stk_size

The size of the stack in number of elements. If CPU_STK is set to CPU_INT08U, the 'stk_size' corresponds to the number of bytes available. If CPU_STK is set to CPU_INT16U, the 'stk_size' contains the number of 16-bit entries available. Finally, if CPU_STK is set to CPU_INT32U, the 'stk_size' contains the number of 32-bit entries available on the stack.

q_size

The maximum number of messages that can be sent to the task.

time_quanta

Amount of time (in ticks) for a time slice when the round-robin between tasks. Set to 0 to use the default.

p_ext

Pointer to a user-supplied memory location which is used as a TCB extension. For example, this user memory can hold the contents of floating-point registers during a context switch, the time each task takes to execute, the number of times the task has been switched-in, etc.

opt

Contains additional information (or options) about the behavior of the task. See OS_OPT_TASK_xxx in OS.H. Current choices are:

OS_OPT_TASK_NONE No option selected.
OS_OPT_TASK_STK_CHK Stack checking to be allowed for the task.
OS_OPT_TASK_STK_CLR Clear the stack when the task is created.
OS_OPT_TASK_SAVE_FP If the CPU has floating-point registers, save them during a context switch.
OS_OPT_TASK_NO_TLS If the caller does not want or need TLS (Thread Local Storage) support for the task. If you do not include this option, TLS will be supported by default.

p_err

Pointer to the variable that will receive one of the following error code(s) from this function:

RTOS_ERR_NONE
RTOS_ERR_OS_ILLEGAL_RUN_TIME

Returned Value#

None.

Notes / Warnings#

OSTaskCreate() triggers a critical assert when a stack overflow is detected during stack initialization. In this case, some memory may have been corrupted and should be treated as a fatal error.

OSTaskDel()#

Description#

Allows you to delete a task. The calling task can delete itself by specifying a NULL pointer for 'p_tcb'. The deleted task is returned to the dormant state and can be re-activated by creating the deleted task again.

Files#

os.h/os_task.c

Prototype#

void  OSTaskDel (OS_TCB    *p_tcb,
                 RTOS_ERR  *p_err)

Arguments#

p_tcb

Pointer to the TCB of the task to delete.

p_err

Pointer to the variable that will receive one of the following error code(s) from this function:

RTOS_ERR_NONE
RTOS_ERR_OS_ILLEGAL_RUN_TIME
RTOS_ERR_INVALID_ARG
RTOS_ERR_INVALID_STATE

Returned Value#

None.

Notes / Warnings#

'p_err' is set to RTOS_ERR_NONE before OSSched() to allow the returned err or code to be monitored even for a task that is deleting itself. In this case, 'p_err' MUST point to a global variable that can be accessed by another task.

OSTaskQFlush()#

Description#

Flushes the task's internal message queue.

Files#

os.h/os_task.c

Prototype#

OS_MSG_QTY  OSTaskQFlush (OS_TCB   *p_tcb,
                          RTOS_ERR  *p_err)

Arguments#

p_tcb

Pointer to the task's TCB. Specifying a NULL pointer indicates that you wish to flush the message queue of the calling task.

p_err

Pointer to the variable that will receive one of the following error code(s) from this function:

RTOS_ERR_NONE

Returned Value#

The number of entries freed from the queue.

Notes / Warnings#

Use this function with great care. When you flush the queue, you lose the references to what the queue entries are pointing, which can cause 'memory leaks'. In other words, the data being pointed to that is referenced by the queue entries should, most likely, need to be de-allocated (i.e., freed).

OSTaskQPend()#

Description#

This function causes the current task to wait for a message to be posted to it.

Files#

os.h/os_task.c

Prototype#

void  *OSTaskQPend (OS_TICK       timeout,
                    OS_OPT        opt,
                    OS_MSG_SIZE  *p_msg_size,
                    CPU_TS       *p_ts,
                    RTOS_ERR     *p_err)

Arguments#

timeout

Optional timeout period (in clock ticks). If non-zero, your task will wait for a message to arrive up to the amount of time specified by this argument. If you specify 0, your task will wait forever, or until a message arrives.

opt

Determines if the user wants to block if the task's queue is empty or not:

OS_OPT_PEND_BLOCKING Task will block.
OS_OPT_PEND_NON_BLOCKING Task will NOT block.

p_msg_size

Pointer to a variable that will receive the size of the message.

p_ts

Pointer to a variable that will receive the timestamp of when the message was received. If you pass a NULL pointer (i.e., (CPU_TS *)0), you will not get the timestamp. In other words, passing a NULL pointer is valid and indicates that you don't need the timestamp.

p_err

Pointer to the variable that will receive one of the following error code(s) from this function:

RTOS_ERR_NONE
RTOS_ERR_NOT_FOUND
RTOS_ERR_WOULD_BLOCK
RTOS_ERR_OS_SCHED_LOCKED
RTOS_ERR_ABORT
RTOS_ERR_TIMEOUT

Returned Value#

A pointer to the message received or a NULL pointer upon error.

Notes / Warnings#

It is possible to receive a NULL pointer when there are no errors.

OSTaskQPendAbort()#

Description#

Aborts and readies the task specified. Use this function to fault-abort the wait for a message, rather than to normally post the message to the task via OSTaskQPost().

Files#

os.h/os_task.c

Prototype#

CPU_BOOLEAN  OSTaskQPendAbort (OS_TCB    *p_tcb,
                               OS_OPT     opt,
                               RTOS_ERR  *p_err)

Arguments#

p_tcb

Pointer to the TCB of the task to pend abort.

opt

Provides options for this function:

OS_OPT_POST_NONE No option specified.
OS_OPT_POST_NO_SCHED Indicates that the scheduler will not be called.

p_err

Pointer to the variable that will receive one of the following error code(s) from this function:

RTOS_ERR_NONE
RTOS_ERR_NONE_WAITING

Returned Value#

== DEF_FALSE If task was not waiting for a message, or upon error.
== DEF_TRUE If task was waiting for a message and was readied and informed.

Notes / Warnings#

None.

OSTaskQPost()#

Description#

Sends a message to a task.

Files#

os.h/os_task.c

Prototype#

void  OSTaskQPost (OS_TCB       *p_tcb,
                   void         *p_void,
                   OS_MSG_SIZE   msg_size,
                   OS_OPT        opt,
                   RTOS_ERR     *p_err)

Arguments#

p_tcb

Pointer to the TCB of the task receiving a message. If you specify a NULL pointer, the message will be posted to the task's queue of the calling task. In other words, you'd be posting a message to yourself.

p_void

Pointer to the message to send.

msg_size

The size of the message sent (in bytes).

opt

Specifies whether the post will be FIFO or LIFO:

OS_OPT_POST_FIFO Post at the end of the queue.
OS_OPT_POST_LIFO Post at the front of the queue.
OS_OPT_POST_NO_SCHED Do not run the scheduler after the post.

Note(s):

OS_OPT_POST_NO_SCHED can be added with one of the other options.

p_err

Pointer to the variable that will receive one of the following error code(s) from this function:

RTOS_ERR_NONE
RTOS_ERR_WOULD_OVF
RTOS_ERR_NO_MORE_RSRC
RTOS_ERR_INVALID_STATE

Returned Value#

None.

Notes / Warnings#

None.

OSTaskRegGet()#

Description#

Obtains the current value of a task register. Task registers are application specific and can be used to store task specific values such as 'error numbers' (i.e., errno), statistics, etc.

Files#

os.h/os_task.c

Prototype#

OS_REG  OSTaskRegGet (OS_TCB     *p_tcb,
                      OS_REG_ID   id,
                      RTOS_ERR   *p_err)

Arguments#

p_tcb

Pointer to the TCB of the task from which you want to read the register. If 'p_tcb' is a NULL pointer, you will get the register of the current task.

id

The 'id' of the desired task variable. Note that the 'id' must be less than OS_CFG_TASK_REG_TBL_SIZE.

p_err

Pointer to the variable that will receive one of the following error code(s) from this function:

RTOS_ERR_NONE

Returned Value#

The current value of the task's register, or 0 if an error is detected.

Notes / Warnings#

None.

OSTaskRegGetID()#

Description#

This function obtains a task register ID. This function allows task register IDs to be allocated dynamically instead of statically.

Files#

os.h/os_task.c

Prototype#

OS_REG_ID  OSTaskRegGetID (RTOS_ERR  *p_err)

Arguments#

p_err

Pointer to the variable that will receive one of the following error code(s) from this function:

RTOS_ERR_NONE
RTOS_ERR_NO_MORE_RSRC

Returned Value#

The next available task register 'id' or OS_CFG_TASK_REG_TBL_SIZE if an error is detected.

Notes / Warnings#

None.

OSTaskRegSet()#

Description#

Changes the current value of a task register. Task registers are application specific and can be used to store task specific values such as error numbers (i.e., errno), statistics, etc.

Files#

os.h/os_task.c

Prototype#

void  OSTaskRegSet (OS_TCB     *p_tcb,
                    OS_REG_ID   id,
                    OS_REG      value,
                    RTOS_ERR   *p_err)

Arguments#

p_tcb

Pointer to the TCB of the task for which you want to set the register. If 'p_tcb' is a NULL pointer, change the register of the current task.

id

The 'id' of the desired task register. Note that the 'id' must be less than OS_CFG_TASK_REG_TBL_SIZE.

value

The desired value for the task register.

p_err

Pointer to the variable that will receive one of the following error code(s) from this function:

RTOS_ERR_NONE

Returned Value#

None.

Notes / Warnings#

None.

OSTaskResume()#

Description#

Resumes a previously suspended task. This is the only call that removes an explicit task suspension.

Files#

os.h/os_task.c

Prototype#

void  OSTaskResume (OS_TCB    *p_tcb,
                    RTOS_ERR  *p_err)

Arguments#

p_tcb

Pointer to the TCB of the task to resume.

p_err

Pointer to the variable that will receive one of the following error code(s) from this function:

RTOS_ERR_NONE
RTOS_ERR_INVALID_STATE

Returned Value#

None.

Notes / Warnings#

None.

OSTaskSuspend()#

Description#

This function is called to suspend a task. The task can be the calling task if 'p_tcb' is a NULL pointer or the pointer to the TCB of the calling task.

Files#

os.h/os_task.c

Prototype#

void   OSTaskSuspend (OS_TCB    *p_tcb,
                      RTOS_ERR  *p_err)

Arguments#

p_tcb

Pointer to the TCB of the task to resume. If p_tcb is a NULL pointer, suspend the current task.

p_err

Pointer to the variable that will receive one of the following error code(s) from this function:

RTOS_ERR_NONE
RTOS_ERR_WOULD_OVF
RTOS_ERR_OS
RTOS_ERR_NOT_READY
RTOS_ERR_INVALID_STATE
RTOS_ERR_OS_SCHED_LOCKED

Returned Value#

None.

Notes / Warnings#

Use this function with great care. If you suspend a task that is waiting for an event (i.e., a message, a semaphore, a queue, etc.) you will prevent this task from running when the event arrives.

OSTaskSemPend()#

Description#

Blocks the current task until a signal is sent by another task or ISR.

Files#

os.h/os_task.c

Prototype#

OS_SEM_CTR  OSTaskSemPend (OS_TICK    timeout,
                           OS_OPT     opt,
                           CPU_TS    *p_ts,
                           RTOS_ERR  *p_err)

Arguments#

timeout

The amount of time you will wait for the signal.

opt

Determines if the user wants to block if a semaphore post was not received:

OS_OPT_PEND_BLOCKING Task will block.
OS_OPT_PEND_NON_BLOCKING Task will NOT block.

p_ts

Pointer to a variable that will receive the timestamp of when the semaphore was posted or pend aborted. If you pass a NULL pointer (i.e., (CPU_TS *)0), you will not get the timestamp. In other words, passing a NULL pointer is valid and indicates that you don't need the timestamp.

p_err

Pointer to the variable that will receive one of the following error code(s) from this function:

RTOS_ERR_NONE
RTOS_ERR_WOULD_BLOCK
RTOS_ERR_OS_SCHED_LOCKED
RTOS_ERR_ABORT
RTOS_ERR_TIMEOUT

Returned Value#

The current count of signals the task received, 0 if none.

Notes / Warnings#

None.

OSTaskSemPendAbort()#

Description#

Aborts and readies the task specified. This function should be used to fault-abort the wait for a signal, rather than to normally post the signal to the task via OSTaskSemPost().

Files#

os.h/os_task.c

Prototype#

CPU_BOOLEAN  OSTaskSemPendAbort (OS_TCB    *p_tcb,
                                 OS_OPT     opt,
                                 RTOS_ERR  *p_err)

Arguments#

p_tcb

Pointer to the TCB of the task to pend abort.

opt

Provides options for this function:

OS_OPT_POST_NONE No option selected.
OS_OPT_POST_NO_SCHED Indicates that the scheduler will not be called.

p_err

Pointer to the variable that will receive one of the following error code(s) from this function:

RTOS_ERR_NONE
RTOS_ERR_NONE_WAITING

Returned Value#

== DEF_FALSE If task was not waiting for a message, or upon error.
== DEF_TRUE If task was waiting for a message and was readied and informed.

Notes / Warnings#

None.

OSTaskSemPost()#

Description#

Signals a task waiting for a signal.

Files#

os.h/os_task.c

Prototype#

OS_SEM_CTR  OSTaskSemPost (OS_TCB    *p_tcb,
                           OS_OPT     opt,
                           RTOS_ERR  *p_err)

Arguments#

p_tcb

The pointer to the TCB of the task to signal. A NULL pointer indicates that you are sending a signal to yourself.

opt

Determines the type of POST performed:

OS_OPT_POST_NONE No option.
OS_OPT_POST_NO_SCHED Do not call the scheduler.

p_err

Pointer to the variable that will receive one of the following error code(s) from this function:

RTOS_ERR_NONE
RTOS_ERR_WOULD_OVF
RTOS_ERR_INVALID_STATE

Returned Value#

The current value of the task's signal counter, or 0 if called from an ISR.

Notes / Warnings#

None.

OSTaskSemSet()#

Description#

Clears the signal counter.

Files#

os.h/os_task.c

Prototype#

OS_SEM_CTR  OSTaskSemSet (OS_TCB      *p_tcb,
                          OS_SEM_CTR   cnt,
                          RTOS_ERR    *p_err)

Arguments#

p_tcb

Pointer to the TCB of the task to clear the counter. If you specify a NULL pointer, the signal counter of the current task will be cleared.

cnt

The desired value of the semaphore counter.

p_err

Pointer to the variable that will receive one of the following error code(s) from this function:

RTOS_ERR_NONE
RTOS_ERR_OS_TASK_WAITING

Returned Value#

The value of the signal counter before being set, or 0 on error.

Notes / Warnings#

None.

OSTaskStkChk()#

Description#

Calculates the amount of free memory left on the specified task's stack.

Files#

os.h/os_task.c

Prototype#

void  OSTaskStkChk (OS_TCB        *p_tcb,
                    CPU_STK_SIZE  *p_free,
                    CPU_STK_SIZE  *p_used,
                    RTOS_ERR      *p_err)

Arguments#

p_tcb

Pointer to the TCB of the task to check. If you specify a NULL pointer, you are specifying that you want to check the stack of the current task.

p_free

Pointer to a variable that will receive the number of free 'entries' on the task's stack.

p_used

Pointer to a variable that will receive the number of used 'entries' on the task's stack.

p_err

Pointer to the variable that will receive one of the following error code(s) from this function:

RTOS_ERR_NONE
RTOS_ERR_INVALID_ARG
RTOS_ERR_NOT_SUPPORTED

Returned Value#

None.

Notes / Warnings#

None.

OSTaskStkRedzoneChk()#

Description#

Verifies a task's stack redzone.

Files#

os.h/os_task.c

Prototype#

CPU_BOOLEAN  OSTaskStkRedzoneChk (OS_TCB  *p_tcb)

Arguments#

p_tcb

Pointer to the TCB of the task to check or null for the current task.

Returned Value#

DEF_FAIL If the stack is corrupted.
DEF_OK If the stack is NOT corrupted.

Notes / Warnings#

(1) This function is INTERNAL to Micrium OS Kernel and your application CAN call it.

OSTaskTimeQuantaSet()#

Description#

Changes the value of the task's specific time slice.

Files#

os.h/os_task.c

Prototype#

void  OSTaskTimeQuantaSet (OS_TCB    *p_tcb,
                           OS_TICK    time_quanta,
                           RTOS_ERR  *p_err)

Arguments#

p_tcb

Pointer to the TCB of the task to change. If you specify a NULL pointer, the current task is assumed.

time_quanta

The number of ticks before the CPU is taken away when round-robin scheduling is enabled.

p_err

Pointer to the variable that will receive one of the following error code(s) from this function:

RTOS_ERR_NONE

Returned Value#

None.

Notes / Warnings#

None.