|
|
| |
|
|
|
Introduction to UDI Metalanguages
23.1 Overview
A metalanguage defines a communication protocol for use over a UDI channel. Metalanguages allow two drivers or a driver and the environment to communicate with each other in a strongly-typed manner. Driver writers may define their own metalanguages, for intra-driver communication (between multiple regions within a driver instance) or between layers in a driver stack, but a number of metalanguages are defined within the UDI specifications. These latter metalanguages are called standard metalanguages, while other metalanguages are referred to as custom metalanguages. Note that for complete portability a custom metalanguage must be implemented using the interfaces defined in Section 4: MEI Services.
Two generally applicable metalanguages are defined in the Core Specification: the Management Metalanguage, which is needed by all UDI drivers for configuration and system management purposes; and the Generic I/O Metalanguage, which is available for use as a generic pass-through metalanguage. Other metalanguages are defined in separate UDI specification books; e.g., the Bus Bridge Metalanguage in the "UDI Physical I/O Specification", the SCSI Metalanguage in the "UDI SCSI Driver Specification", etc.
The remainder of this chapter describes conventions and requirements common to all metalanguages.
23.2 Standard Metalanguage Functions and Parameters
See Chapter 7, "Calling Sequence and Naming Conventions" for requirements and conventions on metalanguage interfaces and their names.
In addition to the required channel operation functions, metalanguages may also provide proxy routines for events that will never occur for some drivers, or for operations that require no action by the driver. For example, if a driver has no children to enumerate, it may set its udi_enumerate_req_op_t to udi_enumerate_no_children instead of providing its own routine that always just responds immediately with udi_enumerate_ack.
23.3 Channel Operation Suffixes
Channel operations generally operate in pairs: e.g., a request and a corresponding acknowledgment, or an event and a corresponding response. The corresponding handshake operation tends to be generally useful in the UDI model to cycle the control block back to the requestor or event initiator or to cycle back buffers and other transferable objects. As a result, metalanguage operations tend to fall into the following categories. (The term "driver" below may also refer to the Management Agent in the case of the Management Metalanguage).
The suffixes listed in the above table are conventionally used in names of channel operation that belong to the corresponding categories.
23.4 General Rules for Handling Channel Operations
This section provides general information on the handling of channel operations performed on a driver.
Upon receipt of a channel operation, a driver may handle it in one of the following ways, depending on the relationship of the request to the driver's current state:
- Normal: the driver knows how to handle the operation, and can handle it in its present state.
- Not understood: the driver doesn't understand how to handle the operation, given its parameters.
- Not supported: the driver understands the operation, but chooses not to support it.
- Invalid state: the driver knows how to handle the operation, but is not in a correct state for such a request.
- Mistaken identity: the driver understands the operation, but its parameters are out of range for the associated object.
For all but the normal case, the driver must respond with an appropriate status code as defined in this Section and also log the error using udi_log_write. (See udi_log_write.) These status codes may be specified by the driver for any metalanguage operation, even if not explicitly listed as a valid status return value for that metalanguage operation.
23.4.1 Normal Operation Handling
Under normal circumstances, a driver is called to handle a request, does some processing, and performs an acknowledge operation. (Processing an operation may or may not involve performing operations on other drivers.) If the operation was an indication that came from a parent driver, the driver may have to interrogate its hardware about the interrupt and/or perform an operation on its child (or parent) driver.
23.4.2 Operations That Are Not Understood
When a driver receives an operation that is not understood because the parameters or associated data are not appropriate, the driver must reply back with a status value of UDI_STAT_NOT_UNDERSTOOD indicating that the operation is not understood.
23.4.3 Operations That Are Not Supported
When a driver receives an operation that it recognizes, but for which it has not implemented the specified function, the driver must reply back with a status value of UDI_STAT_NOT_SUPPORTED indicating that the operation is not supported.
23.4.4 Operations Received In An Invalid State
When a driver receives an operation that is understood and implemented, but is not valid in the driver's current state with respect to the sequence rules of the metalanguage, the driver must reply back with a status value of UDI_STAT_INVALID_STATE.
23.4.5 Operations With Mistaken Identity
When a driver receives an operation that is understood, implemented, and received in the correct state, but with a range of values not appropriate for the corresponding device or other object, the driver must reply back with a status value of UDI_STAT_MISTAKEN_IDENTITY.
23.4.6 Extended Channel Error Handling
When a driver receives a channel error indication as part of a status code associated with a channel operation, the receiving driver must handle the error in accordance with the description of the udi_status_t type. Specifically, if the receiving driver does not recover from the error as part of normal operations, it should:
- preserve the correlation value in the udi_status_t
- change the status code to an appropriate status code for the problem encountered (with UDI_STAT_PARENT_DRV_ERROR available in lieu of a more specific indication)
- log the error with udi_log_write
- pass along the error indication as needed to any children or other requestors.
| |
|
|
|