User guide

126 DC 900-1338I

Protocol Software Toolkit Programmer Guide

7.2.3.1 System Buffer Header Initialization

In the system buffer header, the sb_thse field must be set to the starting address of the

buffer. (This field is set by the system if the buffer was obtained from a partition.) The

sb_nxtb field must be set to zero. The disposition flag, sb_disp, and disposition modifier,

sb_dmod, fields must be initialized as described in the following paragraphs, but no

other fields in the system buffer header require specific initialization.

The disposition flag must be set to one of the values defined for the field as described in

Section 7.2.1 on page 121. If the requesting task obtained the buffer from a partition,

and if it does not require notification when the request has been processed by XIO, the

value

REL_BUF can be used; this causes XIO to release the buffer to its partition on

completion. However, since a post to either of the host request queue IDs specified in

the queue element fails if XIO has not yet processed the request (and created the

queues), tasks generally request completion notification. Since the queue element con-

sists of only one buffer,

POST_QE and POST_BUF are equivalent, and cause XIO to post

the queue element to a specified queue. Likewise,

FREE_QE and FREE_BUF are equiv-

alent, and cause XIO to clear the disposition modifier.

TOKEN_QE and TOKEN_BUF

are also equivalent and cause XIO to release the queue element to a specified resource.

If the disposition flag is set to

POST_QE or POST_BUF, the disposition modifier must

contain a valid queue ID. If the requesting task is the owner of that queue, it then sus-

pends its operation, and resumes when XIO posts the queue element (with a post and

resume system call) to the queue on completion.

FREE_QE or FREE_BUF is specified in the disposition flag, the disposition modifier

should be set to a non-zero value, so the requesting task can recognize the completion

when the field is cleared by XIO.

TOKEN_QE or TOKEN_BUF is specified in the disposition flag, the disposition mod-

ifier must contain a valid resource ID. The requesting task cannot use this method to

obtain completion information unless the node declaration queue element is the only