udi_channel_event_cb_t(3udi)

---

Channel event control block

SYNOPSIS

#include <udi.h>

typedef struct {

	udi_cb_t gcb;

	udi_ubit8_t event;

	union {

		struct {

			udi_cb_t *bind_cb;

		} internal_bound;

		struct {

			udi_cb_t *bind_cb;

			udi_ubit8_t parent_ID;

			udi_buf_path_t *path_handles;

		} parent_bound;

		udi_cb_t *orig_cb;

	} params;

} udi_channel_event_cb_t;
 
/* Channel event types */
 

#define  UDI_CHANNEL_CLOSED				0
 
#define  UDI_CHANNEL_BOUND				1
 
#define  UDI_CHANNEL_OP_ABORTED				2
 

MEMBERS gcb is the standard control block section providing scratch space and context information.

event is the type of event that is being indicated:

UDI_CHANNEL_CLOSED indicates that the remote end of the channel has been closed. The driver receiving this event must clean up any channel-related resources and call udi_channel_close on its end of the channel after calling udi_channel_event_complete.

UDI_CHANNEL_BOUND indicates that another region has been bound to this region as a result of a "parent_bind_ops" or "internal_bind_ops" declaration from this driver's static driver properties (see Chapter 30, "Static Driver Properties"), and that this channel was created as a result of that binding. The driver receiving this event may now begin using the channel for normal operations, usually beginning with a metalanguage-specific bind request. (For internal bindings, only the region using the initiator role in the corresponding metalanguage receives the UDI_CHANNEL_BOUND indication.)

For parent bindings, the parent_ID field will contain an environment-assigned parent ID that identifies the particular parent instance. The parent_ID value will never be zero; zero is reserved for environment use. Single-parent drivers can ignore this field.

The driver must not call udi_channel_event_complete for this event until its entire bind sequence has completed.

See Chapter 24, "Management Metalanguage", for more details on the bind sequence.

UDI_CHANNEL_OP_ABORTED indicates that an abort request has been generated (using udi_channel_op_abort) by the driver on the other end of the channel, with respect to a previous metalanguage-specific abortable request (the original request). The driver receiving this event must abort any outstanding processing for the original request and fail it with a status code of UDI_STAT_ABORTED; it may do this before or after calling udi_channel_event_complete. The orig_cb field will point to the control block for the original request, which is guaranteed to be an abortable control block currently owned by this region (though it may be in use with an environment service call on behalf of this region). Drivers receiving abortable control blocks must not free them but must (eventually) return them over the same channel on which they were received.

orig_cb is a pointer to the control block for the original request being aborted by a UDI_CHANNEL_OP_ABORTED channel event. For all other channel events, the value of orig_cb is unspecified and must not be used by the driver.

bind_cb is a pointer to the pre-allocated control block for the metalanguage-specific bind request that the driver will issue as a result of the UDI_CHANNEL_BOUND event. This control block type is indicated by the <bind_cb_idx> value of the corresponding "parent_bind_ops" declaration (see Section 30.6.3) or "internal_bind_ops" declaration (see Section 30.6.4). For all other channel events or if <bind_cb_idx> was zero then no control block will be allocated and the value of bind_cb is unspecified and must not be used by the driver.

parent_ID is a unique non-zero value supplied by the MA during a UDI_CHANNEL_BOUND event on a parent bind channel, to explicitly identify the parent driver instance being bound. Drivers that have multiple parents will be assigned a unique parent_ID value for each parent. This parent_ID is used for any operations that need to identify a specific parent to which those operations are related (e.g. the enumeration and device management operations of the Management Metalanguage). If the event was not for a parent binding, this member's value is unspecified and must be ignored.

The MA may assign parent IDs in any order.

path_handles is a pointer to an array of udi_buf_path_t handles that may be used by the driver when allocating buffers on behalf of the parent being bound. These handles are maintained in an inline array associated with the channel event control block and must be copied to instance-internal storage before the control block is passed to udi_channel_event_complete. If the event was not for a parent binding, this member's value is unspecified and must be ignored.

DESCRIPTION The udi_channel_event_cb_t control block is a semi-opaque object used between the environment and the driver in channel event indication operations. When passed to the target driver, this control block provides a context for the operation and must be returned to the environment by calling udi_channel_event_complete.

Unlike with other control blocks, the value of gcb.channel for a channel event control block is unspecified and must not be modified.

Unlike with other control blocks, there is no way to list attributes of a udi_channel_event_cb_t in a udi_cb_init_t initialization structure, so the scratch space size for udi_channel_event_cb_t control blocks is always zero.

Drivers cannot allocate udi_channel_event_cb_t control blocks.

REFERENCES udi_channel_event_complete, udi_channel_close, udi_channel_op_aborted, udi_constraints_propagate, udi_layout_t