|
|
udi_cb_t(3udi)
Generic, least-common-denominator control block
#include <udi.h>typedef struct { udi_channel_t channel; void *context; void *scratch; void *initiator_context; udi_origin_t origin; } udi_cb_t;MEMBERS channel is a handle to the channel currently associated with this control block. When used in a channel operation, the main control block's channel member is used as the target channel, and must not-at that time-be UDI_NULL_CHANNEL. For environment implementation reasons, channel must never be explicitly set by the driver to UDI_NULL_CHANNEL.
context is a pointer to state information within the driver region. On entry to a channel operation, the environment sets context to the channel's current context. Drivers may change it if needed.
See udi_channel_set_context for details on how channel context is determined.
scratch is a pointer to the control block's scratch area. Drivers must not change this pointer, but may change any of the bytes in the space pointed to by scratch, up to the required scratch size specified by the appropriate udi_cb_init_t in the driver's udi_init_info.
initiator_context is a context pointer that the initiator of a request or indication operation can use to associate per-request context with this control block. If and when the control block is returned to the initiator via an acknowledgement, nak, or response operation, the initiator can use this context pointer to access any additional state it needs to complete the operation.
Any driver receiving a request or indication operation must use the same control block in its (acknowledgement, nak, or response) reply, and must not modify the initiator_context value. In fact, the value of initiator_context is unspecified except when the control block is owned by the initiating region, so must not be compared, dereferenced, or otherwise used from any other region.
origin is a handle to the origination information for the current request. This is set in the original control block by the environment; each module must copy this field from input control blocks to any other control blocks used to complete work requested by the input control block. Any control block used in an asynchronous service call or channel operation that is not associated with an incoming request control block must set origin to the UDI_NULL_ORIGIN value.
DESCRIPTION The udi_cb_t structure is used for generically handling control blocks and accessing their common members. All metalanguage-specific control blocks have a udi_cb_t structure as their first structure member.
The udi_cb_t structure is a semi-opaque type, and must only be allocated by environment service calls. Control blocks are transferable between regions, when used as the main control block for a channel operation, or chained from that control block as part of a linked list of identically-typed control blocks.
When a new control block is allocated, its context and origin members are initialized to the context value from the original control block, its channel member is initialized according to the default_channel argument block passed to udi_cb_alloc, and its initiator_context value is unspecified.
The driver that currently owns the control block may change the channel and context members at any time while the control block is not in use with an environment service call. If the control block is not already part of an in-progress request/response sequence (that is, not transferred to this region from another region as part of a request or indication operation), the controlling driver may also change the initiator_context value.
All members of udi_cb_t and other visible fields in a metalanguage-specific control block, as well as the scratch area contents, are preserved across asynchronous service calls, but not across channel operations. The only member of udi_cb_t that is preserved across a channel operation is initiator_context, and that only when the control block is returned to the initiating region.
When a control block or a chain of control blocks is passed to another region via a channel operation, the channel and context members of each control block are automatically set to the channel handle for the target region's end of the channel and the channel context for that endpoint, respectively, before the target region's entry point is invoked.