Queue Header

The queue header area contains the descriptor block for all the ZCOM subsystem queues. The first queue is used to link the free buffers in the buffer pool.

Figure 3-7 Queue Header Area

Free Queue Header (zfqh_type), queue 0, basically is the same as the other buffer queues. However, its fields are viewed and used slightly differently from the other queues. Its size is the same as a buffer queue.

QNMSG - Number on queue

Counter of the number of messages on the queue. When this is zero the queue is empty.

QALLOC - Number of allocated messages

This field is used in the free queue header to keep track of the number of buffer segments allocated for ZCOM subsystem use. A value of zero means that no buffers have been allocated for use by the ZCOM subsystem. A large value indicates heavy usage of the buffer pool.

QLIMIT - Queue limit

The maximum number of messages or bytes that may be linked to this queue. If the ZCOM_QFLAG_BLT bit in qflag is not set, this field is a limit on the number of messages. Otherwise, this value is a limit on the number of bytes that can be linked to this queue. The default queue limit is initialized from the Queue-Limit parameter in the TTGEN configuration file when the queue is initialized. The queue limit may be modified dynamically by calling the zsetql routine.

QHEAD, QTAIL - Queue head and tail pointers (zbhd_type *)

These are pointers to the first and last messages attached to this queue. If the queue is empty, these values are undefined. If the queue has only one buffer, then the values are equal.

QMMAX - Number of messages on the queue

The largest number of outstanding messages ever linked to this queue at any given point in time. This value is initialized to zero and is updated any time QNMSG is larger than this field.

QTMSG - Total number of messages through this queue

Counter of all messages that have either passed through, or are still on, this queue.

QBYTES - Number of bytes on the queue

The number of bytes on the queue is the actual number of bytes of all the buffers (messages) linked to this queue. This includes the data length and buffer header areas of each message in the queue. The sum of these fields across all queues (including the free queue) at any instant will equal the total amount of buffer space allocated in the ZCOM subsystem.

QWAITER - Number of processes waiting on this queue

This field is used to indicate whether any processes are waiting for data from this queue. If a process reads from the queue and no data is available, and it has not done a read without wait, the process is suspended (put to sleep) by the LDM and this counter is incremented. At a later time when a new message is added to this queue, the LDM or DAM will wake up all processes suspended on this queue address and set this field to zero.

QFLAG - Queue flags

This field contains some indicators which may affect the processing of a queue. The format is shown in Table 3-29 “Queue Flags”.

When the FUNC bit is set, it indicates the kernel function kept in qfunc is to be called whenever data is added to the queue. This feature may only be used by kernel drivers (via the zsetkfunc routine).

The BLT bit is set if the queue limit check is performed on the number of bytes rather than the number of messages. Currently, only the PTT unacknowledged transmit queue uses it.

Queue manipulation is allowed only when the ENB bit is set. All queues are set to disabled by TTGEN initially, and enabled by the zopen( ) call (where a buffer queue is assigned to a ZLU). During ZCOM subsystem shutdown, the LDM will disable the program queues by clearing this bit.

The SEL and COL bits are used internally for the “select-for-read” function on program ZLUs. When a program ZLU has been “selected” while it has no data, the LDM sets the SEL bit. If more than one program selects this empty ZLU, the COL bit is set. When data arrives for this ZLU the LDM uses these two bits to decide whether to wake up one or multiple programs waiting on the “select” for this ZLU.

QFDATA - Queue function data

QFUNC - Queue function

These two fields have valid data only when the ZCOM_QFLAG_FUNC bit in qflag is set. They are set up by the setkfunc routine and contain a pointer to a kernel function and a 32-bit value for use in calling the function. Each is only used by the kernel so that a kernel function is called whenever data is added to the queue.

When the ZCOM_QFLAG_FUNC bit is not set, the QFUNC field may be used by the LDM as temporary storage for the process pointer to support the program ZLU select-for-read function.