Kernel Message Queue API#

OSQCreate()#

Description#

Called by your application to create a message queue. Message queues MUST be created before they can be used.

Files#

os.h/os_q.c

Prototype#

void  OSQCreate (OS_Q        *p_q,
                 CPU_CHAR    *p_name,
                 OS_MSG_QTY   max_qty,
                 RTOS_ERR    *p_err)

Arguments#

p_q

Pointer to the message queue.

p_name

Pointer to an ASCII string used to name the message queue.

max_qty

Indicates the maximum size of the message queue (must be non-zero). Note that it is not possible to have a size higher than the maximum number of OS_MSGs available.

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#

None.

OSQDel()#

Description#

This function deletes a message queue and readies all tasks pending on the queue.

Files#

os.h/os_q.c

Prototype#

OS_OBJ_QTY  OSQDel (OS_Q      *p_q,
                    OS_OPT     opt,
                    RTOS_ERR  *p_err)

Arguments#

p_q

Pointer to the message queue to delete.

opt

Determines delete options as follows:

  • OS_OPT_DEL_NO_PEND Deletes the queue ONLY if no task is pending.

  • OS_OPT_DEL_ALWAYS Deletes the queue even if tasks are waiting. In this case, all pending tasks will be readied.

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_OS_TASK_WAITING

Returned Value#

  • == 0 If no tasks were waiting on the queue, or upon error.

  • > 0 If one or more tasks waiting on the queue are now readied and informed.

Notes / Warnings#

(1) Use this function with care. Tasks that would normally expect the presence of the queue MUST check the return code of OSQPend().

(2) Because ALL tasks pending on the queue will be readied, you MUST be careful handling resources in applications where the queue is used for mutual exclusion because these resource will no longer be guarded by the queue.

OSQFlush()#

Description#

Flushes the contents of the message queue.

Files#

os.h/os_q.c

Prototype#

OS_MSG_QTY  OSQFlush (OS_Q      *p_q,
                      RTOS_ERR  *p_err)

Arguments#

p_q

Pointer to the message queue to flush.

p_err

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

  • RTOS_ERR_NONE

Returned Value#

  • == 0 If no entries were freed, or upon error.

  • > 0 The number of freed entries.

Notes / Warnings#

(1) Use great care with this function because when you flush the queue, you LOSE the references to what the queue entries are pointing, potentially causing 'memory leaks'. In other words, the data to which you are pointing that are being referenced by the queue entries should, most likely, be de-allocated (i.e., freed).

OSQPend()#

Description#

Waits for a message to be sent to a queue.

Files#

os.h/os_q.c

Prototype#

void  *OSQPend (OS_Q         *p_q,
                OS_TICK       timeout,
                OS_OPT        opt,
                OS_MSG_SIZE  *p_msg_size,
                CPU_TS       *p_ts,
                RTOS_ERR     *p_err)

Arguments#

p_q

Pointer to the message queue.

timeout

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

opt

Determines whether the user wants to block if the 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 receives the size of the message.

p_ts

Pointer to a variable that receives the timestamp of when the message was received, pend aborted, or the message queue was deleted, 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 do not 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_OS_OBJ_DEL

  • RTOS_ERR_NOT_FOUND

  • RTOS_ERR_WOULD_BLOCK

  • RTOS_ERR_OS_SCHED_LOCKED

  • RTOS_ERR_ABORT

  • RTOS_ERR_TIMEOUT

Returned Value#

  • != (void *)0 Pointer to the message received.

  • == (void *)0 If you received a NULL pointer message, or if no message was received, or if 'p_q' is a NULL pointer, or if you didn't pass a pointer to a queue.

Notes / Warnings#

None.

OSQPendAbort()#

Description#

Aborts and readies any tasks currently waiting on a queue. Use this function to fault-abort the wait on the queue, rather than the normal signaling of the queue via OSQPost().

Files#

os.h/os_q.c

Prototype#

OS_OBJ_QTY  OSQPendAbort (OS_Q      *p_q,
                          OS_OPT     opt,
                          RTOS_ERR  *p_err)

Arguments#

p_q

Pointer to the message queue.

opt

Determines the type of ABORT performed:

  • OS_OPT_PEND_ABORT_1 ABORT wait for a single task (HPT) waiting on the message queue.

  • OS_OPT_PEND_ABORT_ALL ABORT wait for ALL tasks that are waiting on the message queue.

  • 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_NONE_WAITING

Returned Value#

  • == 0 If no tasks were waiting on the queue, or upon error.

  • > 0 If one or more tasks waiting on the queue are now readied and informed.

Notes / Warnings#

None.

OSQPost()#

Description#

Sends a message to a queue. With the 'opt' argument, you can specify if the message is broadcast to all waiting tasks and/or if you post the message to the front of the queue (LIFO) or normally (FIFO) at the end of the queue.

Files#

os.h/os_q.c

Prototype#

void  OSQPost (OS_Q         *p_q,
               void         *p_void,
               OS_MSG_SIZE   msg_size,
               OS_OPT        opt,
               RTOS_ERR     *p_err)

Arguments#

p_q

Pointer to a message queue.

p_void

Pointer to the message to send.

msg_size

Specifies the size of the message (in bytes).

opt

Determines the type of POST performed:

  • OS_OPT_POST_ALL POST to ALL tasks that are waiting on the queue. This option can be added to either OS_OPT_POST_FIFO or OS_OPT_POST_LIFO.

  • OS_OPT_POST_FIFO POST message to end of queue (FIFO) and wake up a single waiting task.

  • OS_OPT_POST_LIFO POST message to the front of the queue (LIFO) and wake up a single waiting task.

  • OS_OPT_POST_NO_SCHED Do not call the scheduler.

  • OS_OPT_POST_NO_SCHED can be added (OR'd) with other options.

  • OS_OPT_POST_ALL can be added (OR'd) with other options.

    The possible combinations of options are:

  • OS_OPT_POST_FIFO

  • OS_OPT_POST_LIFO

  • OS_OPT_POST_FIFO + OS_OPT_POST_ALL

  • OS_OPT_POST_LIFO + OS_OPT_POST_ALL

  • OS_OPT_POST_FIFO + OS_OPT_POST_NO_SCHED

  • OS_OPT_POST_LIFO + OS_OPT_POST_NO_SCHED

  • OS_OPT_POST_FIFO + OS_OPT_POST_ALL + OS_OPT_POST_NO_SCHED

  • OS_OPT_POST_LIFO + OS_OPT_POST_ALL + OS_OPT_POST_NO_SCHED

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

Returned Value#

None.

Notes / Warnings#

None.