OSQCreate

Description

Creates a message queue. A message queue allows tasks or ISRs to send pointer-sized variables (messages) to one or more tasks. The meaning of the messages sent are application specific.

Files

os.h/os_q.c

Prototype

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

Arguments

p_q

is a pointer to the message queue control block. It is assumed that storage for the message queue will be allocated in the application. The user will need to declare a “global” variable as follows, and pass a pointer to this variable to OSQCreate():

OS_Q  MyMsgQ;

p_name

is a pointer to an ASCII string used to name the message queue. The name can be displayed by debuggers or µC/Probe.

msg_qty

indicates the maximum size of the message queue (must be non-zero). If the user intends to not limit the size of the queue, simply pass a very large number. Of course, if there are not enough OS_MSGs in the pool of OS_MSGs, the post call (i.e., OSQPost()) will simply fail and an error code will indicate that there are no more OS_MSGs to use.

p_err

is a pointer to a variable that is used to hold an error code:

OS_ERR_NONE

If the call is successful and the mutex has been created.

OS_ERR_CREATE_ISR

If OS_CFG_CALLED_FROM_ISR_CHK_EN set to DEF_ENABLED in os_cfg.h: if attempting to create the message queue from an ISR.

OS_ERR_ILLEGAL_CREATE_RUN_TIME

If OS_SAFETY_CRITICAL_IEC61508 is defined: you called this after calling OSStart() and thus you are no longer allowed to create additional kernel objects.

OS_ERR_OBJ_PTR_NULL

If OS_CFG_ARG_CHK_EN is set to DEF_ENABLED in os_cfg.h: if p_q is a NULL pointer.

OS_ERR_Q_SIZE

If OS_CFG_ARG_CHK_EN is set to DEF_ENABLED in os_cfg.h: if the size specified is 0.

Returned Value

None

Required Configuration

OS_CFG_Q_EN must be enabled in os_cfg.h. Refer to µC-OS-III Configuration Manual.

Callers

Application.

Notes/Warnings

1. Queues must be created before they are used.

Example Usage

          OS_Q   CommQ;
           
           
          void main (void)
          {
              OS_ERR   err;
           
           
              OSInit(&err);                          /* Initialize µC/OS-III  */
              :
              :
              OSQCreate(&CommQ,
                        "Comm Queue",
                         10,
                        &err);                       /* Create COMM Q         */
              /* Check "err" */
              :
              :
              OSStart();                             /* Start Multitasking    */
          }