enque Kernel Service

Purpose

Sends a request queue element to a device queue.

Syntax

#include <sys/types.h> #include <sys/errno.h> #include <sys/deviceq.h> int enque ( qe) struct req_qe *qe;

Parameter

Item Description
qe Specifies the address of the request queue element.

Description

The enque kernel service is not part of the base kernel, but is provided by the device queue management kernel extension. This queue management kernel extension must be loaded into the kernel before loading any kernel extensions referencing these services.

The enque service places the queue element into a specified device queue. It is used for simple process-to-process communication within the kernel. The requester builds a copy of the queue element, indicated by the qe parameter, and passes this copy to the enque service. The kernel copies this queue element into a queue element in pinned global memory and then enqueues it on the target device queue.

The path identifier in the request queue element indicates the device queue into which the element is placed.

The enque service supports the sending of the following types of queue elements:

Queue Element Description
SEND_CMD Send command.
START_IO Start I/O.
GEN_PURPOSE General purpose.

For simple interprocess communication, general purpose queue elements are used.

The queue element priority value can range from QE_BEST_PRTY to QE_WORST_PRTY. This value is limited to the value specified when the queue was created.

The operation options in the queue element control how the queue element is processed. There are five standard operation options:

Operation Option Description
ACK_COMPLETE Acknowledge completion in all cases.
ACK_ERRORS Acknowledge completion if the operation results in an error.
SYNC_REQUEST Synchronous request.
CHAINED Chained control blocks.
CONTROL_OPT Kernel control operation.
Note: Only one of ACK_COMPLETE, ACK_ERRORS, or SYNC_REQUEST can be specified. Also, all of these options are ignored if the path specifies that no acknowledgment (NO_ACK) should be sent.

With the SYNC_REQUEST synchronous request option, control does not return from the enque service until the request queue element is acknowledged. This performs in one step what can also be achieved by sending a queue element with the ACK_COMPLETE flag on, and then calling either the et_wait or waitq kernel services.

The kernel calls the server's check routine, if one is defined, before a queue element is placed on the device queue. This routine can stop the operation if it detects an error.

The kernel notifies the device queue's server, if necessary, after a queue element is placed on the device queue. This is done by posting the server process (using the et_post kernel service) with an event control bit.

Execution Environment

The enque kernel service can be called from the process environment only.

Return Values

Item Description
RC_GOOD Indicates a successful operation.
RC_ID Indicates a path identifier that is not valid.

All other error values represent errors returned by the server.