|
|
| |
|
|
|
Generic I/O Metalanguage
25.1 Overview
This chapter defines the channel operations and associated service calls for the Generic I/O Metalanguage, which is available for use as a generic pass-through metalanguage.
Each subsection defines the channel operations, associated control blocks, the rationale for the operation's existence, constraints and guidelines for the use of each operation, and error conditions that can occur.
The Generic I/O Metalanguage can be used as a "top-side" metalanguage for drivers when a more specific metalanguage does not (yet) exist. Some of the ways this might be used are:
- as a prototyping vehicle, until a more specific metalanguage can be constructed;
- as a "super pass-through", for vendor-specific applications to talk to their own drivers;
- as a way for diagnostic applications to invoke diagnostic operations in the driver;
- and as a top-side metalanguage for pseudo-drivers that are so specialized, and possibly even OS-specific, that they don't deserve the investment in a custom metalanguage.
The Generic I/O Metalanguage can also be used as an internal metalanguage between a multi-region driver's primary and secondary regions or between secondary regions.
The Generic I/O Metalanguage provides the following functionality:
- the ability to send and receive data buffers to/from the driver;
- the ability to send control operations to the driver;
- and the ability to send event notifications from the driver "upward."
Note - The GIO client must use udi_channel_op_abort to abort outstanding GIO transfer requests. Only the udi_gio_xfer_req operation is abortable in GIO; therefore for a GIO channel, the orig_cb parameter to udi_channel_op_abort must point to a udi_gio_xfer_cb_t control block that was previously passed on the GIO channel from the client to the provider.
The only operation in the Generic I/O Metalanguage that is recoverable (see Section 4.10, "Driver Faults/Recovery") is udi_gio_xfer_req.
25.1.1 Versioning
All functions and structures defined in this chapter are part of the "udi_gio" interface, currently at version "0x101". A driver that conforms to and uses the Generic I/O Metalanguage of the UDI Core Specification, Version 1.01, must include the following declaration in its udiprops.txt file (see Chapter 30, "Static Driver Properties"):
requires udi_gio 0x101Compile-time versioning and header files for the Generic I/O Metalanguage are covered by the general requirements for the UDI Core Specification defined in Chapter 8, "General Requirements".
A portable implementation of the Generic I/O Metalanguage must include a corresponding "provides" declaration in its udiprops.txt file, must conform to the same compile-time versioning and header file requirements as for drivers, and must conform to the requirements specified in the Metalanguage-to-Environment (MEI) interface defined in Chapter 27, "Introduction to MEI" and Chapter 28, "Metalanguage-to-Environment Interface" of the UDI Core Specification.
25.1.2 Roles
There are two roles to the Generic I/O Metalanguage: the "client" and the "provider." When this metalanguage is used between drivers, the client is always a child of the provider. When used as an internal metalanguage, the client and provider are both in the same driver, but in different regions.
To keep things simple, the initial bind channel is also used for all I/O operations. As a result, there is just one channel between the client and the provider.
25.2 Metalanguage Bindings
25.2.1 Bindings for Static Driver Properties
Some of the bindings for the static driver properties are defined in Section 25.1.1, "Versioning". This includes the definition of the relevant interface name(s) (i.e., the <interface_name> parameter on the "requires" and "provides" and other property declarations), and the definition of the interface version number for this version of this Specification.
The driver category to be used with the "category" declaration (see Section 30.5.3, "Category Declaration") by a portable implementation of the GIO Metalangauge Library shall be "Miscellaneous".
25.2.2 Bindings for Instance Attributes
In each of the attribute tables below, the ATTRIBUTE NAME is a null-terminated string (see "Instance Attribute Names"); the TYPE column specifies an attribute data type as defined in udi_instance_attr_type_t; and the SIZE column specifies the valid sizes, in bytes, for each attribute.
25.2.2.1 Enumeration Attributes
The driver that enumerates GIO clients must create the following enumeration attributes and pass them to the Management Agent in the attr_list parameter of the udi_enumerate_ack operation (see "Device Management Operations").
Table 25-1 GIO Enumeration Attributes ATTRIBUTE NAME TYPE SIZE DESCRIPTION The "gio_type" attribute specifies the type of GIO client driver being enumerated. The size of the "gio_type" attribute must be in the range 1..32, including the null-terminator character. If enumerating a GIO client to be a Diagnostics child, the value for this attribute is defined in Chapter 26, "Diagnostics Support". Otherwise, the contents of "gio_type" strings are driver-defined.
The "gio_privileged_ops" and "gio_destructive_ops" attributes may be used to specify which GIO opcodes are either privileged or destructive. These enumeration attributes are optional and do not need to be specified by the GIO service provider. The meaning of a privileged or destructive operation must be documented by the individual service provider, but in general terms, a privileged operation is one which has a system-wide impact or may allow access to sensitive data or control over the device configuration and therefore should be limited to requestors that are "privileged". A destructive operation is one which can cause data loss or will reconfigure the device in such a way that future use of the device is incompatible with current use (e.g. formatting a disk drive). The GIO service provider should determine a policy for handling both privileged and destructive operations, possibly including: ignoring the indicators entirely, checking application privileges before delivering the operations to the service provider, providing exclusive access to the service provider for the duration of the operation, and logging operations of this type.
25.2.2.2 Filter Attributes
There are no filter attributes defined for the GIO Metalanguage.
25.2.2.3 Generic Enumeration Attributes
As defined in "Enumeration Attributes", there are four generically-accessible enumeration attributes: "identifier", "address_locator", physical_locator", and "physical_label". These attributes, of type UDI_ATTR_STRING, are defined so as to allow environments to use these attributes in generic algorithms to identify and compare information about the devices in the system. This is useful in keeping the UDI environment isolated from the specifics of metalanguages and bus bindings.
In GIO, the "identifier" attribute must have the same value as the "gio_type" attribute. The "address_locator" attribute must have the same value as the "gio_instance" attribute. The "physical_locator" and "physical_label" attributes are not defined for the GIO metalanguage and must not be set by the enumerating driver.
25.2.3 Enumeration Attribute Ranking
To support the ranking of enumerated devices against available drivers for the udi_mei_enumerate_rank_func_t, the following combinations of enumeration attribute matches yield the corresponding ranking values. Attribute combinations not specified return a relative rank of 0 (the lowest possible rank). The combinations are unchanged by matches against non-rankable attributes.
Table 25-2 GIO Enumeration Attribute Ranking Rank Value Rankable Attributes1 2 1 2 3 identifier Y Y Y address_locator Y Y Y gio_type Y Y Y gio_instance Y Y Y
1Y indicates the valid match of the attribute, * indicates that the attribute may or may not be a valid match (i.e. will be ignored if matched). 2Only the attributes listed are rankable; all other enumeration attributes have no effect on the ranking value. Thus, if a GIO provider enumerates a child and specifies either or both of the gio_instance or the address_locator attributes, the ranking value will be one; if it also specifies the identifier attribute then the ranking value will be three.
25.2.4 Bindings for Trace Events
The following defines the rules and conventions in the GIO Metalanguage for the use of the metalanguage-selectable trace events (see the "Metalanguage-Selectable Trace Events" #defines in udi_trevent_t).
- UDI_TREVENT_IO_SCHEDULED
- The provider should trace at least the corresponding GIO transfer control block pointer and GIO opcode.
- UDI_TREVENT_IO_COMPLETED
- The provider should trace at least the corresponding GIO transfer control block pointer, GIO opcode, and status.
- UDI_TREVENT_META_SPECIFIC_1,
UDI_TREVENT_META_SPECIFIC_2,
UDI_TREVENT_META_SPECIFIC_3,
UDI_TREVENT_META_SPECIFIC_4,
UDI_TREVENT_META_SPECIFIC_5Note - All returned status values other than UDI_OK that indicate exceptional conditions must be logged and, when enabled, may also be traced, even if such events are expected.
25.3 Metalanguage State Diagram
See "Driver Instantiation" for the general configuration sequence of UDI drivers. The following state diagram shows the GIO metalanguage state diagram, which illustrates the set of states specific to use of the GIO metalanguage. This same state diagram applies to both GIO clients and GIO providers.
25.3.1 GIO Metalanguage States
UNBOUND A GIO channel in the unbound state has been established between the two regions but has not yet been initialized in those regions for general use. The client side of the GIO channel should initiate the GIO bind operation when in this state.
BINDING This indicates that the client side of the GIO channel has initiated a bind operation and is waiting for the provider side of the GIO channel to complete its initialization and acknowledge that bind request.
ACTIVE This indicates that the GIO channel is fully bound between the two regions and that it may be used for GIO transfer operations or event indications.
UNBINDING This indicates that the GIO channel is being shut down. The client driver can cause this state to be entered by issuing a udi_gio_unbind_req. When the unbind operation is acknowledged, both the client and the provider return to the UNBOUND state.
25.4 Channel Ops Vectors
This section defines the channel ops vector types for use with the Generic I/O Metalanguage. There are two ops vector types in the Generic I/O Metalanguage: one that a GIO provider uses on its end of a GIO channel (udi_gio_provider_ops_t) and one that a GIO client uses on its end of a GIO channel (udi_gio_client_ops_t).
NAME udi_gio_provider_ops_t
Provider entry point ops vector
#include <udi.h>typedef const struct { udi_channel_event_ind_op_t *channel_event_ind_op; udi_gio_bind_req_op_t *gio_bind_req_op; udi_gio_unbind_req_op_t *gio_unbind_req_op; udi_gio_xfer_req_op_t *gio_xfer_req_op; udi_gio_event_res_op_t *gio_event_res_op; } udi_gio_provider_ops_t; /* Ops Vector Number */#define UDI_GIO_PROVIDER_OPS_NUM 1DESCRIPTION A Generic I/O provider uses the udi_gio_provider_ops_t structure in a udi_ops_init_t as part of its udi_init_info in order to register its entry points for receiving generic I/O bind and transfer requests, and event responses.
EXAMPLE The driver's udi_init_info might include the following:
#define MY_GIO_OPS 1 /* Ops for my child GIO client */
#define MY_GIO_META 1 /* Meta index for GIO meta */ static const udi_gio_provider_ops_t ddd_gio_provider_ops = { ddd_gio_channel_event_ind, ddd_gio_bind_req, ddd_gio_unbind_req, ddd_gio_xfer_req, ddd_gio_event_res }; ... static const udi_ops_init_t ddd_ops_init_list[] = { { MY_GIO_OPS, MY_GIO_META, UDI_GIO_PROVIDER_OPS_NUM, 0, /* chan_context_size */ (udi_ops_vector_t *)&ddd_gio_provider_ops }, { 0 } };NAME udi_gio_client_ops_t
Client entry point ops vector
#include <udi.h>typedef const struct { udi_channel_event_ind_op_t *channel_event_ind_op; udi_gio_bind_ack_op_t *gio_bind_ack_op; udi_gio_unbind_ack_op_t *gio_unbind_ack_op; udi_gio_xfer_ack_op_t *gio_xfer_ack_op; udi_gio_xfer_nak_op_t *gio_xfer_nak_op; udi_gio_event_ind_op_t *gio_event_ind_op; } udi_gio_client_ops_t; /* Ops Vector Number */#define UDI_GIO_CLIENT_OPS_NUM 2DESCRIPTION A Generic I/O client uses the udi_gio_provider_ops_t structure in a udi_ops_init_t as part of its udi_init_info in order to register its entry points for receiving generic I/O bind and transfer acknowledgements, and event indications.
EXAMPLE The driver's udi_init_info might include the following:
#define MY_GIO_OPS 1 /* Ops for my parent GIO provider */
#define MY_GIO_META 1 /* Meta index for GIO meta */ static const udi_gio_client_ops_t ddd_gio_client_ops = { ddd_gio_channel_event_ind, ddd_gio_bind_ack, ddd_gio_unbind_ack, ddd_gio_xfer_ack, ddd_gio_xfer_nak, ddd_gio_event_ind }; ... static const udi_ops_init_t ddd_ops_init_list[] = { { MY_GIO_OPS, MY_GIO_META, UDI_GIO_CLIENT_OPS_NUM, 0, /* chan_context_size */ (udi_ops_vector_t *)&ddd_gio_client_ops }, { 0 } };25.5 Binding and Unbinding Operations
NAME udi_gio_bind_cb_t
Control block for GIO binding operations
#include <udi.h>typedef struct { udi_cb_t gcb; udi_xfer_constraints_t xfer_constraints; } udi_gio_bind_cb_t; /* Control Block Group Number */#define UDI_GIO_BIND_CB_NUM 1MEMBERS gcb is a generic control block header, which includes a pointer to the scratch space associated with this control block. The driver may use the scratch space while it owns the control block, but the values are not guaranteed to persist across channel operations.
xfer_constraints is a structure describing the transfer constraints required by the provider driver. (See udi_xfer_constraints_t.) These constraints apply only to the standard read/write operations, UDI_GIO_OP_READ and UDI_GIO_OP_WRITE. This field is ignored on the udi_gio_bind_req and is filled in by the provider for returning information in the udi_gio_bind_ack operation.
DESCRIPTION The Generic I/O bind control block is used between the GIO client and the GIO provider to complete initial binding over the bind channel.
In order to use this type of control block it must be associated with a control block index by including UDI_GIO_BIND_CB_NUM in a udi_cb_init_t in the driver's udi_init_info.
REFERENCES udi_init_info, udi_cb_init_t, udi_cb_alloc
NAME udi_gio_bind_req
Request a binding to a GIO provider
#include <udi.h>void udi_gio_bind_req ( udi_gio_bind_cb_t *cb );ARGUMENTS cb is a pointer to a GIO bind control block.
TARGET CHANNEL The target channel for this operation is the bind channel connecting a GIO client to a GIO provider.
DESCRIPTION A Generic I/O client uses this operation to bind to a Generic I/O provider.
The client must prepare for the udi_gio_bind_req operation by allocating a GIO bind control block (calling udi_cb_alloc with a cb_idx that was previously associated with UDI_GIO_BIND_CB_NUM).
Next, the client sends the GIO bind control block to the provider with a udi_gio_bind_req operation.
The udi_gio_bind_req operation must be the first channel operation sent on the bind channel. The GIO client must not send any further operations on the bind channel until it receives the corresponding udi_gio_bind_ack from the GIO provider.
REFERENCES udi_gio_bind_cb_t, udi_gio_bind_ack
NAME udi_gio_bind_ack
Acknowledge a GIO binding
#include <udi.h>void udi_gio_bind_ack ( udi_gio_bind_cb_t *cb, udi_ubit32_t device_size_lo, udi_ubit32_t device_size_hi, udi_status_t status );ARGUMENTS cb is a pointer to a GIO bind control block.
device_size_lo is the least-significant 32 bits of the (logical) device size, in bytes. This affects the behavior of standard read/write operations; its effect on custom operations, if any, is defined by the GIO provider.
device_size_hi is the next-most-significant 32 bits of the (logical) device size, in bytes. This affects the behavior of standard read/write operations; its effect on custom operations, if any, is defined by the GIO provider.
status indicates whether or not the binding was successful.
TARGET CHANNEL The target channel for this operation is the bind channel connecting a GIO provider to a GIO client.
DESCRIPTION The udi_gio_bind_ack operation is used by a Generic I/O provider to acknowledge binding with a Generic I/O client (or failure to do so, as indicated by status), as requested by a udi_gio_bind_req operation.
If device_size_lo or device_size_hi are non-zero, the standard read/write operations, UDI_GIO_OP_READ and UDI_GIO_OP_WRITE, are treated as random-access operations; that is, the offset_lo and offset_hi members of udi_gio_rw_params_t indicate the starting device offset for each transfer and transfers may be sent to the provider in any order. The client must not send any such requests that would extend beyond the end of the device as indicated by device_size_lo and device_size_hi.
If device_size_lo and device_size_hi are both zero, and the client uses standard read/write operations, then it must send them to the provider in device order, and offset_lo and offset_hi must be ignored by the provider.
WARNINGS The control block must be the same control block as passed to the driver in the corresponding udi_gio_bind_req operation.
REFERENCES udi_gio_bind_cb_t, udi_gio_bind_req
NAME udi_gio_unbind_req
Request to unbind from a GIO provider
#include <udi.h>void udi_gio_unbind_req ( udi_gio_bind_cb_t *cb );ARGUMENTS cb is a pointer to a GIO bind control block.
TARGET CHANNEL The target channel for this operation is the bind channel connecting a GIO client to a GIO provider.
DESCRIPTION A Generic I/O client uses this operation to unbind from a Generic I/O provider.
The GIO client must prepare for the udi_gio_unbind_req operation by allocating a GIO bind control block (calling udi_cb_alloc with a cb_idx that was previously associated with UDI_GIO_BIND_CB_NUM).
Next, the GIO client sends the GIO bind control block to the GIO provider with a udi_gio_unbind_req operation.
REFERENCES udi_gio_bind_cb_t, udi_gio_unbind_ack
NAME udi_gio_unbind_ack
Acknowledge a GIO unbind request
#include <udi.h>void udi_gio_unbind_ack ( udi_gio_bind_cb_t *cb );ARGUMENTS cb is a pointer to a GIO bind control block.
TARGET CHANNEL The target channel for this operation is the bind channel connecting a GIO provider to a GIO client.
DESCRIPTION The udi_gio_unbind_ack operation is used by a Generic I/O provider to acknowledge unbinding from a Generic I/O client as requested by a udi_gio_unbind_req operation.
WARNINGS The control block must be the same control block as passed to the driver in the corresponding udi_gio_unbind_req operation.
REFERENCES udi_gio_bind_cb_t, udi_gio_unbind_req
25.6 Data Transfer and Control Operations
NAME udi_gio_xfer_cb_t
Control block for GIO transfer operations
#include <udi.h>typedef struct { udi_cb_t gcb; udi_gio_op_t op; void *tr_params; udi_buf_t *data_buf; } udi_gio_xfer_cb_t; /* Control Block Group Number */#define UDI_GIO_XFER_CB_NUM 2MEMBERS gcb is a generic control block header, which includes a pointer to the scratch space associated with this control block. The driver may use the scratch space while it owns the control block, but the values are not guaranteed to persist across channel operations.
op is a code designating the specific operation to be performed. Operation codes may be used to indicate different operation semantics. Custom operations are supported, as well as standard operations. See udi_gio_xfer_req for a description of these operations.
tr_params is a pointer to an inline memory structure that is used to hold operation-specific parameters. The pointer itself is set by the environment when the control block is allocated, and must not be modified by the driver.
data_buf is a pointer to a buffer used to carry the data portion of a transfer. See udi_gio_xfer_req and udi_gio_xfer_ack for details on buffer usage.
DESCRIPTION The Generic I/O transfer control block is used between a GIO client and a GIO provider to process a data or control transfer.
In order to use this type of control block it must be associated with a control block index by including UDI_GIO_XFER_CB_NUM in a udi_cb_init_t in the driver's udi_init_info.
The size and layout of the tr_params structure must be specified using the inline_size and inline_layout members of that udi_cb_init_t structure (i.e. tr_params is a UDI_DL_INLINE_DRIVER_TYPED field).
REFERENCES udi_init_info, udi_cb_init_t, udi_cb_alloc, udi_gio_op_t
NAME udi_gio_op_t
GIO operation type
#include <udi.h>typedef udi_ubit8_t udi_gio_op_t; /* Limit values for udi_gio_op_t */#define UDI_GIO_OP_CUSTOM 16 #define UDI_GIO_OP_MAX 64/* Direction flag values for op */#define UDI_GIO_DIR_READ (1U<<6) #define UDI_GIO_DIR_WRITE (1U<<7)/* Standard Operation Codes */#define UDI_GIO_OP_READ UDI_GIO_DIR_READ #define UDI_GIO_OP_WRITE UDI_GIO_DIR_WRITEDESCRIPTION This type is used to hold an operation code, including direction flags, for a Generic I/O transfer control block.
The data_buf parameter is used to specify the data buffer to be read or written in this GIO transfer operation. The data_buf->buf_size field indicates the number of bytes that are to be transferred; if no actual data is to be transferred then data_buf may be NULL.
The operation code includes a bitmask of zero, one, or both direction flags from the following list:
UDI_GIO_DIR_READ - from provider to client
UDI_GIO_DIR_WRITE - from client to provider
These indicate the direction of data flow for the data_buf buffer. They do not imply any particular operation semantics.
The standard operation codes listed above are defined below with specific semantics. Additional, optional, standard operation codes are defined for device diagnostics in Chapter 26, "Diagnostics Support". The GIO provider may define additional custom operations, whose semantics and parameters are completely defined by the GIO provider. However, the basic rules for use of data_buf, data_buf->buf_size, and the direction flags must be followed in all cases. Driver-defined custom operations must use op values of UDI_GIO_OP_CUSTOM or greater.
The UDI_GIO_OP_READ and UDI_GIO_OP_WRITE operations use a udi_gio_rw_params_t structure for tr_params in the transfer control block.
The UDI_GIO_OP_READ operation reads data from the device at the offset indicated by offset_lo and offset_hi (if applicable). If there are fewer than data_buf->buf_size bytes remaining on the device at the time the request is processed, then those bytes that are present must be returned and data_buf->buf_size adjusted accordingly. If there are no data bytes available, and the possibility exists of more data arriving eventually, the provider must wait until at least one byte becomes available before responding.
The UDI_GIO_OP_WRITE operation writes data to the device at the offset indicated by offset_lo and offset_hi (if applicable). If the device cannot hold data_buf->buf_size additional bytes at the time the request is processed, then those bytes that fit must be sent to the device and data_buf->buf_size must be set to that value. Note that if the device is just temporarily unable to accept more data (for example, due to flow control), and can reasonably be expected to be eventually able to accept more data without external action, then the provider must continue to process the write operation once the device is no longer busy, and must not respond early with a short count.
Transfer constraints (see udi_xfer_constraints_t) apply to the standard read/write operations, but not to any other standard or custom operations.
REFERENCES udi_gio_xfer_cb_t, udi_gio_rw_params_t
NAME udi_gio_rw_params_t
Parameters for standard GIO read/write ops
#include <udi.h>typedef struct { udi_ubit32_t offset_lo; udi_ubit32_t offset_hi; } udi_gio_rw_params_t;MEMBERS offset_lo is the least-significant 32 bits of an offset in bytes from the beginning of the (logical) device. This value is ignored if device_size_lo and device_size_hi were set to zero in the call to udi_gio_bind_ack.
offset_hi is the next-most-significant 32 bits of an offset in bytes from the beginning of the (logical) device. This value is ignored if device_size_lo and device_size_hi were set to zero in the call to udi_gio_bind_ack.
DESCRIPTION This structure is used to hold additional parameters for the standard GIO read/write operations: UDI_GIO_OP_READ and UDI_GIO_OP_WRITE. It is passed to a udi_gio_xfer_req operation using the tr_params inline memory structure of the udi_gio_xfer_cb_t, which must have been initialized with an inline_size of sizeof(udi_gio_rw_params_t).
The tr_params pointer itself must not be changed; instead it should be cast to (udi_gio_rw_params_t *) and then the structure may be read or written through the resulting pointer.
REFERENCES udi_gio_xfer_cb_t, udi_gio_xfer_req, udi_gio_xfer_ack
NAME udi_gio_xfer_req
Request a Generic I/O transfer
#include <udi.h>void udi_gio_xfer_req ( udi_gio_xfer_cb_t *cb );ARGUMENTS cb is a pointer to a GIO transfer control block.
TARGET CHANNEL The target channel for this operation is the bind channel connecting a GIO client to a GIO provider.
DESCRIPTION A Generic I/O client uses this operation to send a transfer request to a Generic I/O provider.
The GIO client must prepare for the udi_gio_xfer_req operation by allocating a GIO transfer control block (calling udi_cb_alloc with a cb_idx that was previously associated with UDI_GIO_XFER_CB_NUM) and filling in all of its members.
The client driver must then set data_buf->buf_size to the amount of data to be transferred via data_buf in the direction(s) indicated by the setting of the direction flags in op: UDI_GIO_DIR_READ and/or UDI_GIO_DIR_WRITE. If no data is to be transferred in either direction, the client may set data_buf to NULL.
Finally, the client sends the GIO transfer control block to the provider with a udi_gio_xfer_req operation.
The particular semantics and parameters for the request depend on the op value in the udi_gio_xfer_cb_t transfer control block. See udi_gio_op_t for descriptions of valid operation codes.
This operation is abortable with udi_channel_op_abort if op is UDI_GIO_OP_READ or UDI_GIO_OP_WRITE.
This operation is recoverable upon abrupt termination of the target region (see Section 4.10, "Driver Faults/Recovery").
If op does not include UDI_GIO_DIR_WRITE, any data in data_buf is not guaranteed to be preserved by this channel operation. That is, when the provider driver receives this operation, the contents (but not the size) of the buffer are unspecified unless UDI_GIO_DIR_WRITE is set.
REFERENCES udi_gio_xfer_cb_t, udi_gio_op_t, udi_gio_xfer_ack
NAME udi_gio_xfer_ack
Acknowledge a GIO transfer request
#include <udi.h>void udi_gio_xfer_ack ( udi_gio_xfer_cb_t *cb );ARGUMENTS cb is a pointer to a GIO transfer control block.
TARGET CHANNEL The target channel for this operation is the bind channel connecting a GIO provider to a GIO client.
DESCRIPTION The udi_gio_xfer_ack operation is used by a Generic I/O provider to acknowledge a transfer request back to a Generic I/O client (indicating success), as requested by a udi_gio_xfer_req operation. The udi_gio_xfer_nak operation is used to indicate failure or other exceptional conditions.
The op member of the control block must have the same value as at the time of the udi_gio_xfer_req operation. The contents of the tr_params inline memory are ignored for udi_gio_xfer_ack.
If data_buf is not NULL, data_buf->buf_size must be the same as in the original request and must equal the number of bytes actually transferred (overruns and underruns are handled with udi_gio_xfer_nak). The data_buf pointer must either be the same as in the original request, or a direct "descendant" of the original buffer (i.e. results from a chain of one or more service calls such as udi_buf_write that replace the original buffer with a modified version).
If op does not include UDI_GIO_DIR_READ, any data in data_buf is not guaranteed to be preserved by this channel operation. That is, when the client driver receives this operation, the contents (but not the size) of the buffer are unspecified unless UDI_GIO_DIR_READ is set.
WARNINGS The control block must be the same control block as passed to the driver in the corresponding udi_gio_xfer_req operation.
REFERENCES udi_gio_xfer_cb_t, udi_gio_xfer_req, udi_gio_xfer_nak, udi_buf_copy
NAME udi_gio_xfer_nak
Abnormal completion of a GIO transfer request
#include <udi.h>void udi_gio_xfer_nak ( udi_gio_xfer_cb_t *cb, udi_status_t status );ARGUMENTS cb is a pointer to a GIO transfer control block.
status indicates why the transfer was unsuccessful.
TARGET CHANNEL The target channel for this operation is the bind channel connecting a GIO provider to a GIO client.
DESCRIPTION The udi_gio_xfer_nak operation is used by a Generic I/O provider to send a negative acknowledgement of a transfer request (indicating failure, overruns, and underruns) back to the Generic I/O client that requested the transfer using a udi_gio_xfer_req operation. Whether or not overruns and underruns are considered errors is defined by the semantics of the particular op used and the needs of the client.
The op member of the control block must have the same value as at the time of the udi_gio_xfer_req operation. The contents of the tr_params inline memory are ignored for udi_gio_xfer_nak.
If data_buf is not NULL, the provider driver must set data_buf->buf_size to the number of bytes actually transferred, which must be less than or equal to the requested size. The data_buf pointer must either be the same as in the original request, or a direct "descendant" of the original buffer (i.e. results from a chain of one or more service calls such as udi_buf_write that replace the original buffer with a modified version).
If flags in the control block include UDI_GIO_DIR_WRITE, the contents of the data buffer must be the same as in the original request. This allows the client driver to retry failed operations if it so chooses.
Data in data_buf is always preserved by this channel operation.
WARNINGS The control block must be the same control block as passed to the driver in the corresponding udi_gio_xfer_req operation.
REFERENCES udi_gio_xfer_cb_t, udi_gio_xfer_req, udi_gio_xfer_ack, udi_buf_copy
25.7 Event Handling Operations
NAME udi_gio_event_cb_t
Control block for GIO event operations
#include <udi.h>typedef struct { udi_cb_t gcb; udi_ubit8_t event_code; void *event_params; } udi_gio_event_cb_t; /* Control Block Group Number */#define UDI_GIO_EVENT_CB_NUM 3MEMBERS gcb is a generic control block header, which includes a pointer to the scratch space associated with this control block. The driver may use the scratch space while it owns the control block, but the values are not guaranteed to persist across channel operations.
event_code is a driver-specific code that indicates the type of event which occured.
event_params is a pointer to additional parameters for this type of event. The structure and size of these parameters are defined by the GIO provider. The pointer itself is set by the environment when the control block is allocated, and must not be modified by the driver.
DESCRIPTION The Generic I/O event control block is used between a GIO client and a GIO provider to notify the client of an asynchronous event.
In order to use this type of control block it must be associated with a control block index by including UDI_GIO_EVENT_CB_NUM in a udi_cb_init_t in the driver's udi_init_info.
The size and layout of the event_params structure must be specified using the inline_size and inline_layout members of that udi_cb_init_t structure (i.e. event_params is a UDI_DL_INLINE_DRIVER_TYPED field).
If there are no parameters for this type of event, event_params must be NULL and inline_size must be zero.
REFERENCES udi_init_info, udi_cb_init_t, udi_cb_alloc
NAME udi_gio_event_ind
GIO event indication
#include <udi.h>void udi_gio_event_ind ( udi_gio_event_cb_t *cb );ARGUMENTS cb is a pointer to a GIO event control block.
TARGET CHANNEL The target channel for this operation is the bind channel connecting a GIO provider to GIO client.
PROXIES udi_gio_event_ind_unused
Proxy for udi_gio_event_ind
udi_gio_event_ind_op_t udi_gio_event_ind_unused;udi_gio_event_ind_unused may be used as a GIO client's udi_gio_event_ind entry point if the client expects that the GIO provider will never send it any event indications.
DESCRIPTION A Generic I/O provider uses this operation to send an event notification to a Generic I/O client.
The GIO provider must prepare for the udi_gio_event_ind operation by allocating a GIO event control block (calling udi_cb_alloc with a cb_idx that was previously associated with UDI_GIO_EVENT_CB_NUM).
Next, the provider sends the GIO event control block to the GIO client with a udi_gio_event_ind operation. The provider does not need to wait to receive a response before sending another udi_gio_event_ind; multiple indications may be pending at once.
Whether or not a provider supports event notification, and whether or not the client must enable events explicitly (via custom operations), is defined by the GIO provider. There are no standard events.
REFERENCES udi_gio_event_cb_t, udi_gio_event_res
NAME udi_gio_event_res
GIO event response
#include <udi.h>void udi_gio_event_res ( udi_gio_event_cb_t *cb );ARGUMENTS cb is a pointer to a GIO event control block.
TARGET CHANNEL The target channel for this operation is the bind channel connecting a GIO client to a GIO provider.
PROXIES udi_gio_event_res_unused
Proxy for udi_gio_event_res
udi_gio_event_res_op_t udi_gio_event_res_unused;udi_gio_event_res_unused may be used as a GIO provider's udi_gio_event_res entry point if the provider never sends any event indications (and therefore expects no responses).
DESCRIPTION The udi_gio_event_res operation is used by a Generic I/O client to acknowledge an event indication from a Generic I/O provider, as delivered by a udi_gio_event_ind operation.
WARNINGS The control block must be the same control block as passed to the driver in the corresponding udi_gio_event_ind operation.
| |
|
|
|
