In This Chapter
We describe the Queue kernel services in detail. The Queue services provide a method of passing multiple-byte packets of information between tasks with automatic task synchronization of queue-full and queue-empty conditions.
KS_CloseQueue... 124 KS_DefQueueName... 126 KS_DefQueueProp ... 128 KS_DefQueueSema... 130 KS_GetQueueClassProp ... 134 KS_GetQueueData ... 136 KS_GetQueueDataT...138 KS_GetQueueDataW... 140 KS_GetQueueName... 142 KS_GetQueueProp ... 144 KS_GetQueueSema... 146 INIT_QueueClassProp ... 148 KS_LookupQueue ... 150 KS_OpenQueue...152 KS_PutQueueData ... 156 KS_PutQueueDataT ...158 KS_PutQueueDataW...160
KS_CloseQueue
KS_CloseQueue
End the use of a dynamic queue.
Synopsis
KSRC KS_CloseQueue (QUEUE queue)Input
Description
The KS_CloseQueue kernel service ends the Current Task’s use of the specified dynamic queue. When closing the queue, the service detaches the caller’s use of it. If the caller is the last user of the queue, the service releases the queue to the free pool of dynamic queues for reuse. If there is at least one other task still using the queue, the service does not release the queue to the free pool but the service completes successfully.Be careful when closing a queue on which multiple tasks may be waiting. Closing the queue may cause waiters to be lost. However, you can avoid this problem if each task that uses the queue makes a KS_UseQueue call before it begins using the queue and then makes a KS_CloseQueue call when it is done using the queue.
Note: To use this service, you must enable the Dynamics attribute of the Queue class during system generation.
Output
This service returns a KSRC value as follows:` RC_GOOD if the service is successful.
` RC_STATIC_OBJECT if the specified queue is not dynamic.
` RC_OBJECT_NOT_INUSE if the specified queue does not correspond to an active dynamic queue.
` RC_OBJECT_INUSE if the Current Task’s use of the specified queue is closed but the queue remains open for use by other tasks.
queue The handle of the queue to close.
KS_CloseQueue
Note: RC_OBJECT_INUSE does not necessarily indicate an error condition. The calling task must interpret its meaning.
Error
This service may generate the following fatal error code:FE_ILLEGAL_QUEUE if the specified queue ID is not valid.
Example
In Example 4-1, the Current Task waits for a signal from another task indicating that it is time to close a dynamic queue. The handle of the dynamic queue is specified in dynqueue. When the signal is received, the Current Task closes the associated queue.Example 4-1. Close Queue
#include "rtxcapi.h" /* RTXC Kernel Service prototypes */
QUEUE dynqueue; /* handle of queue to be closed */
SEMA dynsema;
KS_TestSemaW (dynsema); /* wait for signal */
KS_CloseQueue (dynqueue); /* then close the queue */
See Also
KS_OpenQueue, page 152 KS_UseQueue, page 162KS_DefQueueName
KS_DefQueueName
Define the name of a previously opened dynamic queue.
Synopsis
KSRC KS_DefQueueName (QUEUE queue, const char *pname)Inputs
Description
The KS_DefQueueName kernel service names or renames the specified dynamic queue. The service uses the null-terminated string pointed to by pname for the queue’s new name.Static queues cannot be named or renamed under program control.
Note: To use this service, you must enable the Dynamics attribute of the Queue class during system generation.
This service does not check for duplicate queue names.
Output
This service returns a KSRC value as follows:` RC_GOOD if the service completes successfully.
` RC_STATIC_OBJECT if the queue being named is static.
` RC_OBJECT_NOT_FOUND if the Dynamics attribute of the Queue class is not enabled.
` RC_OBJECT_NOT_INUSE if the specified queue does not correspond to an active dynamic queue.
Error
This service may generate the following fatal error code:FE_ILLEGAL_QUEUE if the specified queue ID is not valid.
queue The handle of the queue being defined.
pname A pointer to a null-terminated name string.
KS_DefQueueName
Example
In Example 4-2, the dynqueue variable contains the handle of a previously opened queue. Assign the name NewQueue to that queue so other users may reference it by name.Example 4-2. Assign Queue Name
#include "rtxcapi.h" /* RTXC Kernel Service prototypes */
QUEUE dynqueue;
if (KS_DefQueueName (dynqueue, "NewQueue") != RC_GOOD) {
... Error in naming the queue. Deal with it here }
... naming operation was successful. Continue
See Also
KS_OpenQueue, page 152 KS_GetQueueName, page 142 KS_LookupQueue, page 150 KS_UseQueue, page 162KS_DefQueueProp
KS_DefQueueProp
Define the properties of a queue.
Synopsis
void KS_DefQueueProp (QUEUE queue, const QUEUEPROP *pqueueprop)Inputs
Description
The KS_DefQueueProp kernel service defines the properties of the specified queue using the values contained in the QUEUEPROP structure pointed to by pqueueprop.Example 4-3 shows the organization of the QUEUEPROP structure.
Example 4-3. Queue Properties Structure typedef struct
KCOUNT current_size; /* Current # of entries in the queue */
} QUEUEPROP;
You may define the following queue attribute value:
Output
This service does not return a value.queue The handle of the queue being defined.
pqueueprop A pointer to a Queue properties structure.
Waiting Order Indicates the ordering of tasks waiting for access to the queue. The default order is by priority. Waiting Order can be changed to chronological ordering by ORing the ATTR_FIFO_ORDER constant into the attributes field.
The default value for the Waiting Order attribute can be restored by ANDing the attributes field with
~ATTR_FIFO_ORDER.
KS_DefQueueProp
Errors
This service may generate one of the following fatal error codes:` FE_ILLEGAL_QUEUE if the specified queue ID is not valid.
` FE_UNINITIALIZED_QUEUE if the specified queue has not yet been initialized.
` FE_NULL_QUEUEBASE if the specified queue base address is null.
` FE_ZERO_QUEUEWIDTH if the specified queue width is zero.
` FE_ZERO_QUEUEDEPTH if the specified queue depth is zero.
Example
During system initialization, the startup code must create and initialize the Queue kernel object class and then define all of the static queues to the system before the first use of queues by any task.Example 4-4 illustrates this process.
Example 4-4. Define Queue Object Class Properties
#include "rtxcapi.h" /* RTXC Kernel Service prototypes */
extern const KCLASSPROP queueclassprop;
extern const QUEUEPROP queueprop[];
static char buf[128];
int objnum;
if ((ksrc = INIT_QueueClassProp (&queueclassprop)) != RC_GOOD) {
putline ("Queue class initialization failed");
return (ksrc);
}
/* if class inits successfully, define the queues to the system */
for (objnum = 1; objnum <= queueclassprop.n_statics; objnum++) KS_DefQueueProp (objnum, &queueprop[objnum]);
See Also
KS_GetQueueProp, page 144 INIT_QueueClassProp, page 148 KS_OpenQueue, page 152KS_DefQueueSema
KS_DefQueueSema
Associate a semaphore with a queue condition event.
Synopsis
void KS_DefQueueSema (QUEUE queue, SEMA sema, QEVENT event)Inputs
Description
The KS_DefQueueSema kernel service associates the semaphore specified in sema with an event, either Queue_Not_Empty (QNE) or Queue_Not_Full (QNF), of the specified queue. This action allows a task to synchronize with the occurrence of the queue event among a group of other events through the use of the KS_TestSemaM service or one of its variants.The Queue_Not_Empty and Queue_Not_Full events have enumerated values of QNE and QNF, respectively. You should use one of these values when specifying the event argument.
Note: To use this service, you must enable the Semaphores attribute of the Queue class during system generation.
You do not need to use a semaphores to synchronize with the queue events when using KS_GetQueueData, KS_PutQueueData or their variants. The RTXC Kernel provides that synchronization automatically and
transparently.
Output
This service does not return a value.Errors
This service may generate one of the following fatal error codes:` FE_ILLEGAL_QUEUE if the specified queue ID is not valid.
queue The handle of the queue with which to associate the semaphore.
sema The handle of the semaphore to associate with the queue.
event The queue event with which to associate the semaphore.
KS_DefQueueSema
` FE_UNINITIALIZED_QUEUE if the specified queue has not yet been initialized.
` FE_ILLEGAL_SEMA if the specified semaphore ID is not valid.
` FE_UNINITIALIZED_SEMA if the specified semaphore has not yet been initialized.
` FE_INVALID_QEVENT if the specified queue event value is not either QNF or QNE.
Example
In Example 4-5 on page 132, the Current Task needs to associate the Queue_Not_Empty condition for the DATAQ1 and DATAQ2 queues with the GOT1 and GOT2 semaphores, respectively.Notice that the example does not check the return value of KS_GetQueueData. This procedure is acceptable because the example associates the QNE event with the semaphores. Because the QNE event indicates that data must be in the queue, the KSRC value of RC_QUEUE_EMPTY cannot occur.
KS_DefQueueSema
Example 4-5. Associate Queue Event with Semaphore
#include "rtxcapi.h" /* RTXC Kernel Service prototypes */
#include "kqueue.h" /* defines DATAQ1 and DATAQ2 */
const SEMA semalist[] = {
KS_DefQueueSema (DATAQ1, GOT1, QNE);
KS_DefQueueSema (DATAQ2, GOT2, QNE);
cause = KS_TestSemaMW (semalist);
switch (cause) {
case GOT1:
KS_GetQueueData (DATAQ1, &entry);
... do some processing break;
case GOT2:
KS_GetQueueData (DATAQ2, &entry);
... do some processing break;
} /* end of switch */
...continue
KS_DefQueueSema
See Also
KS_GetQueueSema, page 146 KS_TestSema, page 106 KS_TestSemaT, page 108 KS_TestSemaW, page 118 KS_TestSemaM, page 110 KS_TestSemaMT, page 112 KS_TestSemaMW, page 115KS_GetQueueClassProp
KS_GetQueueClassProp
Get the Queue object class properties.
Synopsis
const KCLASSPROP * KS_GetQueueClassProp (int *pint)Input
Description
The KS_GetQueueClassProp kernel service obtains a pointer to the KCLASSPROP structure used by the INIT_QueueClassProp service during system initialization to initialize the Queue object class properties. If pint is not null ((int *)0), the service returns the number of available dynamic queues in the variable pointed to by pint.Example 2-22 on page 62 shows the organization of the KCLASSPROP structure.
The attributes element of the Queue KCLASSPROP structure supports the class property attributes and masks listed in Table 4-1 on page 135.
Output
If successful, this service returns a pointer to a KCLASSPROP structure.If the Queue class is not initialized, the service returns a null pointer ((KCLASSPROP *)0).
If pint is not null, the service returns the number of available dynamic queues in the variable pointed to by pint.
pint A pointer to a variable in which to store the number of available dynamic queues.
KS_GetQueueClassProp
Example
In Example 4-6, the Current Task needs access to the information contained in the KCLASSPROP structure for the Queue object class.Example 4-6. Read Queue Object Class Properties
#include "rtxcapi.h" /* RTXC Kernel Service prototypes */
KCLASSPROP *pqueueclassprop;
int free_dyn;
/* Get the queue kernel object class properties */
if ((pqueueclassprop = KS_GetQueueClassProp (&free_dyn)) == (KCLASSPROP const *)0)
{
putline ("Queue Class not initialized");
} else {
... queue object class properties are available for use free_dyn contains the number of available dynamic queues }
See Also
INIT_QueueClassProp, page 148 Table 4-1. Queue Class Attributes and MasksAttribute Mask
Static Names ATTR_STATIC_NAMES
Dynamics ATTR_DYNAMICS
Semaphores ATTR_SEMAPHORES
KS_GetQueueData
KS_GetQueueData
Get the next entry from a queue.
Synopsis
KSRC KS_GetQueueData (QUEUE queue, void *pdest)Inputs
Description
The KS_GetQueueData kernel service moves an entry from the specified queue to the destination buffer beginning at the address specified in pdest. Because the queue is a FIFO construct, this service moves the oldest entry from the queue.If the queue is empty, nothing can be moved from the queue and the service immediately returns a KSRC value with the appropriate indicator.
Output
This service returns a KSRC value of:` RC_GOOD if the service completes successfully.
` RC_QUEUE_EMPTY if the queue is empty at the time of the kernel service request.
Errors
This service may generate one of the following fatal error codes:` FE_ILLEGAL_QUEUE if the specified queue ID is not valid.
` FE_UNINITIALIZED_QUEUE if the specified queue has not yet been initialized.
` FE_NULL_DESTBUFFER if the pointer to the destination buffer is null.
Example
In Example 4-7 on page 137, the Current Task needs to get an entry containing several bytes of data from the DATAQ queue.queue The handle of the queue being queried.
pdest A pointer to the destination buffer.
KS_GetQueueData
Example 4-7. Read Queue Entry
#include "rtxcapi.h" /* RTXC Kernel Service prototypes */
#include "kqueue.h" /* defines DATAQ1 */
struct {
int count;
int values[8];
} entry;
if (KS_GetQueueData (DATAQ1, &entry) == RC_GOOD) {
... do some processing }
else {
... no data available, do something else }
See Also
KS_GetQueueDataT, page 138 KS_GetQueueDataW, page 140 KS_DefQueueSema, page 130KS_GetQueueDataT
KS_GetQueueDataT
Get the next entry from a queue. If the queue is empty, wait a specified number of ticks on a specified counter for an entry to become available.
Synopsis
KSRC KS_GetQueueDataT (QUEUE queue, void *pdest, COUNTER counter, TICKS ticks)Inputs
Description
The KS_GetQueueDataT kernel service moves an entry from the specified queue to the destination buffer beginning at the address specified in pdest. Because the queue is a FIFO construct, this service moves the oldest entry from the queue.If the queue is empty, the service blocks the Current Task and starts an internal alarm for the interval specified in ticks on the specified counter. The task remains blocked until one of two conditions occurs:
` Another task puts an entry into the queue through one of the kernel services, or
` The specified number of ticks elapses.
Output
This service returns a KSRC value of:` RC_GOOD if the service completes successfully. If pevent is not null, the service stores the event indicators for any queue events that occur during the data movement in the variable pointed to by pevent.
` RC_TICKOUT if the specified number of ticks elapses before the empty queue receives an entry.
queue The handle of the queue being queried.
pdest A pointer to the destination buffer.
counter The counter associated with the interval defined by ticks. ticks The number of ticks on the specified counter to wait for a
queue entry.
KS_GetQueueDataT
Errors
This service may generate one of the following fatal error codes:` FE_ILLEGAL_QUEUE if the specified queue ID is not valid.
` FE_UNINITIALIZED_QUEUE if the specified queue has not yet been initialized.
` FE_ILLEGAL_COUNTER if the specified counter ID is not valid.
` FE_UNINITIALIZED_COUNTER if the specified counter has not yet been initialized.
` FE_NULL_DESTBUFFER if the pointer to the destination buffer is null.
Example
Example 4-8 gets an entry from the DATAQ queue and stores it in the structure called entry. If DATAQ is empty, the task waits no longer than 250 msec relative to CLKCOUNTER for data to become available before proceeding.Example 4-8. Read Queue Entry—Wait Number of Ticks If Necessary
#include "rtxcapi.h" /* RTXC Kernel Service prototypes */
#include "kqueue.h" /* defines DATAQ */
#include "kcounter.h" /* defines CLKCOUNTER
#include "kproject.h" /* defines CLKTICK */
struct /* structure for receiving the dequeued entry */
int type;
int value;
} entry;
/* get data from DATAQ */
if (KS_GetQueueDataT (DATAQ, &entry, CLKCOUNTER, (TICKS)250/CLKTICK) == RC_GOOD)
{
KS_GetQueueDataW
KS_GetQueueDataW
Get the next entry from a queue. If the queue is empty, wait for an entry to become available.
Synopsis
void KS_GetQueueDataW (QUEUE queue, void *pdest)Inputs
Description
The KS_GetQueueDataW kernel service moves an entry from the specified queue to the destination buffer beginning at the address specified in pdest. Because the queue is a FIFO construct, this service moves the oldest entry from the queue.If the queue is empty, the service blocks the Current Task. The Current Task remains blocked until a queue entry becomes available.
Output
This service does not return a value.Errors
This service may generate one of the following fatal error codes:` FE_ILLEGAL_QUEUE if the specified queue ID is not valid.
` FE_UNINITIALIZED_QUEUE if the specified queue has not yet been initialized.
` FE_NULL_DESTBUFFER if the pointer to the destination buffer is null.
Example
Example 4-9 on page 141 gets an entry from the DATAQ static queue and stores it in the structure called entry. If DATAQ is empty, the task waits for data to become available before proceeding.queue The handle of the queue being queried.
pdest A pointer to the destination buffer.
KS_GetQueueDataW
Example 4-9. Read Queue Entry—Wait If Necessary
#include "rtxcapi.h" /* RTXC Kernel Service prototypes */
#include "kqueue.h" /* defines DATAQ */
struct /* structure for receiving the dequeued entry */
{
int type;
int value;
} entry;
/* get data from DATAQ */
KS_GetQueueDataW (DATAQ, &entry);
... continue
See Also
KS_GetQueueData, page 136 KS_GetQueueDataT, page 138KS_GetQueueName
KS_GetQueueName
Get the name of a queue.
Synopsis
char * KS_GetQueueName (QUEUE queue)Input
Description
The KS_GetQueueName kernel service obtains a pointer to the null-terminated string containing the name of the specified queue.The queue may be static or dynamic.
Note: To use this service on static queues, you must enable the Static Names attribute of the Queue class during system generation.
Output
If the queue has a name, this service returns a pointer to the null-terminated name string.If the queue has no name, the service returns a null pointer ((char *)0).
Error
This service may generate the following fatal error code:FE_ILLEGAL_QUEUE if the specified queue ID is not valid.
Example
In Example 4-10 on page 143, the Current Task needs to report the name of the dynamic queue specified in dynqueue.queue The handle of the queue being queried.
KS_GetQueueName
Example 4-10. Read Dynamic Queue Name
#include <stdio.h> /* standard i/o */
#include "rtxcapi.h" /* RTXC Kernel Service prototypes */
static char buf[128];
QUEUE dynqueue;
char *pname;
if ((pname = KS_GetQueueName (dynqueue)) == (char *)0) sprintf (buf, "Queue %d has no name", queueID);
else
sprintf (buf, "Queue %d name is %s", dynqueue, pname);
putline (buf);
See Also
KS_DefQueueName, page 126 KS_OpenQueue, page 152KS_GetQueueProp
KS_GetQueueProp
Get the properties of a queue.
Synopsis
void KS_GetQueueProp (QUEUE queue, QUEUEPROP *pqueueprop)Inputs
Description
The KS_GetQueueProp kernel service obtains all of the property values of the specified queue in a single call. The service stores the property values in the QUEUEPROP structure pointed to bypqueueprop.
Example 4-3 on page 128 shows the organization of the QUEUEPROP structure.
This service does not return any information concerning queue event semaphores. For information about obtaining queue event semaphores, see “KS_GetQueueSema” on page 146.
The value returned in attributes indicates the ordering of tasks waiting on the queue.
If (attributes & ATTR_FIFO_ORDER) is not equal to 0, the service orders waiters chronologically.
If (attributes & ATTR_FIFO_ORDER) equals 0, the service orders waiters by priority.
Output
This service does not return a value. It stores the properties of the queue in the properties structure pointed to by pqueueprop.Errors
This service may generate one of the following fatal error codes:` FE_ILLEGAL_QUEUE if the specified queue ID is not valid.
` FE_UNINITIALIZED_QUEUE if the specified queue has not yet been initialized.
queue The handle of the queue being queried.
pqueueprop A pointer to a Queue properties structure.
KS_GetQueueProp
Example
Example 4-11 looks at the current size of the CHARQ static queue and signals the XOFF semaphore if the queue contains more than 20 entries. It signals the XON semaphore if the current size of the queue is less than 4 entries.Example 4-11. Read Queue Properties
#include "rtxcapi.h" /* RTXC Kernel Service prototypes */
#include "kqueue.h" /* defines CHARQ */
#include "ksema.h" /* defines XOFF and XON */
QUEUEPROP qprop;
KS_GetQueueProp (CHARQ, &qprop);/* get CHARQ properties */
if (qprop.current_size > 20) KS_SignalSema (XOFF);
if (qprop.current_size < 4) KS_SignalSema (XON);
... continue
See Also
KS_DefQueueProp, page 128KS_GetQueueSema
KS_GetQueueSema
Get the semaphore handle associated with a queue event.