User guide

132 DC 900-1338I
Protocol Software Toolkit Programmer Guide
In the header buffer, the disposition flag must be set to one of the values defined for the
field in Section 7.2.1 on page 121. If it is set to
POST_QE, FREE_QE, or TOKEN_QE, the
disposition flag in the data buffer is ignored. If the disposition flag in the header buffer
is set to
POST_BUF, FREE_BUF, TOKEN_BUF, or REL_BUF, the disposition flag in the
data buffer must also be set to one of those four values, although not necessarily the
same one. These options are described in the following paragraphs.
In general, a task requires notification of the completion of a read request so that it can
process the message received from the ICP’s host. However, it might or might not
require notification of the completion of a write request. If the task obtained the buffers
of a queue element from a partition, and if it does not require notification when the
request has been processed by XIO, the value
REL_BUF in the disposition flags of both
buffers causes XIO to release the buffers to their partitions on completion.
If the task is maintaining host request queue elements as resource tokens and does not
require notification when the request has been processed by XIO, the value
TOKEN_QE
in the disposition flag and a resource ID in the disposition modifier of the header buffer
cause XIO to release the queue element to the resource on completion. Alternatively,
the task could maintain the individual buffers of the queue element as resource tokens,
in which case
TOKEN_BUF should be stored in the disposition flag and resource ID in
the disposition modifier of both the header and data buffers.
For notification of the completion of a host request, a task can set the disposition flag in
the header buffer to
POST_QE, in which case XIO, on completion, posts the queue ele-
ment, intact, to the queue specified in the disposition modifier of the header buffer.
Alternatively, the task can set the disposition flag in the header buffer to
FREE_QE, in
which case XIO clears the disposition modifier in the header buffer on completion.
If the completion is to be processed separately for the two buffers of the queue element,
the requesting task can use the
POST_BUF, FREE_BUF, and REL_BUF values, in any
combination, for the disposition flags. For example, if the task obtained its data buffer
from a partition, but defined a fixed data structure as the header buffer, it might set the