DOC HOME SITE MAP MAN PAGES GNU INFO SEARCH PRINT BOOK
 
TOC PREV NEXT INDEX

Introduction to UDI Metalanguages

23

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).
Table 23-1 Channel Operation Categories
Suffix Category Description
_req Request Operations sent by a driver to request service from another driver
_ack Acknowledgement Operations returned to handshake a request and indicate results and status (normal completion, warning, or failure)
_nak Negative Acknowledgement Operations returned to handshake a request and specifically indicate non-normal status; used in performance-critical cases to keep status checks out of the normal path
_ind Event Indication Operations sent by a driver to notify another driver of an event
_res Event Response Operations returned in response to event indications
_rdy Ready for Event Operation submitted "against the flow" to prime the initiator with a set of control blocks for it to use, in order to have flow control.

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:

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:


TOC PREV NEXT INDEX