Introduction to Physical I/O

1

1.1 Overview

The UDI Physical I/O Specification specifies the services and metalanguage interfaces required to support a UDI physical I/O driver. A physical I/O driver is one that controls a directly-attached device (aka a physical device), which can be programmed without indirect access through another device. Physical devices typically interface to the host system via an I/O bridge (aka I/O bus) and have registers that are accessed by the host CPU via Programmed I/O (PIO). Physical devices may also generate interrupts to the I/O bridge and/or support direct access to system memory via the I/O bridge (aka DMA).

Section 1 introduces the general requirements, static driver property extensions, and additional UDI services required in order to support physical I/O. Section 2 defines the Bus Bridge Metalanguage, which is used by a physical I/O driver to communicate with its parent bus bridge driver. Section 3 defines the requirements for Bus Binding specifications.

1.2 General Requirements

Certain basic rules apply to all UDI Physical I/O drivers. In order to be UDI-compliant, a driver must follow all of these rules. UDI Physical I/O drivers must also follow the rules specified in the UDI Core Specification. Rules specific to Physical I/O drivers are listed here.

1.2.1 Versioning

All functions and structures defined in the UDI Physical I/O Specification, except for those defined in Chapter 5, "Bus Bridge Metalanguage", are part of the "udi_physio" interface, currently at version "0x101". A driver that conforms to and uses the UDI Physical I/O Specification, Version 1.01, must include the following declaration in its udiprops.txt file (see Chapter 30, "Static Driver Properties", of the UDI Core Specification):

requires udi_physio 0x101
 

In each UDI physical I/O driver source file, before including any UDI header files, the driver must define the preprocessor symbol, UDI_PHYSIO_VERSION, to indicate the version of the UDI Physical I/O Specification to which it conforms, which must be the same as the interface version defined above:

#define  UDI_PHYSIO_VERSION
 
0x101
 

As defined in Section 30.4.6, "Requires Declaration," on page 30-6 of the UDI Core Specification, the two least-significant hexadecimal digits of the interface version represent the minor number; the rest of the hex digits represent the major number. Versions that have the same "major version number" as an earlier version shall be backward compatible with that earlier version (i.e. a strict superset).¹

1.2.2 Header Files

Each device driver source file must include the file "udi_physio.h" after it includes "udi.h", as follows:

#include <udi.h>
 
#include <udi_physio.h>
 

These header files contain environment-specific definitions of standard UDI structures and types, as well as all function prototypes and other definitions needed to use the core and physical I/O UDI interfaces and services. Additional include files may be needed for other non-core services and metalanguages as defined in other UDI Specifications.

To maintain portability across UDI supportive platforms, device driver writers shall not assume any knowledge of the contents of these header files with respect to implementation-dependent aspects of the UDI interfaces (such as the definition of handles or abstract types). Similarly, drivers shall not access any functions or objects external to the driver except those defined in the UDI Specifications to which they conform.

1.2.3 Endianness Requirements

In general, UDI allows communicating drivers to run with different driver endianness (see Section 3.2.2, "Common Terms", in the UDI Core Specification), with the environment automatically handling endianness conversions across channels, except for the contents of UDI buffers (whose endianness is unknown to the environment). However, since the only mechanism for interrupt preprocessing (see udi_intr_attach_req on page 4-13) to pass significant amounts of data to a device driver's interrupt handler is via UDI buffers, and since this mechanism processes that data in the bus bridge driver's endianness, the bus bridge driver (which is the parent of the device driver) must be running with the same driver endianness as the device driver.

Therefore, any physical I/O driver shall be run with the same driver endianness as its parent.

1.3 Normative References

The UDI Physical I/O Specification references the UDI specifications listed below. These specifications contain provisions that, through reference in this document, constitute provisions of the UDI Physical I/O Specification.

1. UDI Core Specification, Version 1.01.

The UDI Physical I/O Specification also references the IEEE 1212.1 standard for Direct Memory Access Devices, but these references are informational and do not constitute provisions of the UDI Physical I/O Specification.

1.4 Extensions to Static Driver Properties

The UDI Physical I/O Specification defines the following extensions to the Static Driver Properties file, udiprops.txt (see Chapter 30, "Static Driver Properties" in the UDI Core Specification). These extensions are enabled by the presence of the following declaration anywhere in the file:

requires udi_physio 0x101
 

Any driver that uses functions or structures from the UDI Physical I/O Specification must include the above declaration in its Static Driver Properties.

The "region" declaration is extended to support the following additional region attributes:

Table 1-1 Physical I/O Region Attributes

<region_attribute>	<value>	Meaning
type	interrupt	An interrupt region. See udi_intr_attach_req.
pio_probe	no	Regions of this type never use udi_pio_probe. This is the default value for this attribute.
pio_probe	yes	Regions of this type may use udi_pio_probe. (See udi_pio_probe.)

A "nonsharable_interrupt" declaration is added:

nonsharable_interrupt <msgnum> [ <intr_idx> ]
 

At most one "nonsharable_interrupt" declaration must be included for each interrupt source of each supported device. If present, this indicates that the specified interrupt source does not support sharing, so must not be configured on the same interrupt line as another interrupt source. The <msgnum> must match <msgnum> in a "device" declaration, and indicates that this declaration applies to that device. The <intr_idx>, if present, selects one of several interrupt sources for the device, starting from zero; if not present, all interrupt sources for the device are affected. This declaration may indicate that the interrupt source is electrically non-sharable, or it may indicate a logically non-sharable interrupt source (one for which there is no way for the driver to determine if the interrupt has actually been asserted).

A "pio_serialization_limit" declaration is added:

pio_serialization_limit <max_idx>
 

The "pio_serialization_limit" declaration specifies the maximum serialization_domain index value that may be passed to udi_pio_map by the associated driver. A serialization domain is used to insure that all PIO handles defined for that domain will be serialized (i.e. execution of one PIO trans list must complete before execution of the next PIO trans list can be started). The driver developer must decide the number of serialization domains required for the implementation of the driver and declare that count in this declaration. Registering a PIO handle with a serialization domain index greater than the value specified in this declaration is a driver error (i.e. the value specified by the driver for the serialization_domain argument for the udi_pio_map operation must be in the range of 0..<max_idx>). If this declaration is not specified in the static properties file, the serialization limit defaults to zero (a single serialization domain) and all PIO handles (if any) must be registered with a serialization_domain index of 0. The maximum value for this declaration is 255.

1.5 Bus Bindings

The UDI Physical I/O Specification must be used in conjunction with one or more Bus Binding definitions for the type(s) of physical I/O bus on which a driver's device is supported. A UDI Bus Binding definition provide the usage details that are specific to a particular bus type.

Chapter 6, "Introduction to Bus Bindings", defines the general requirements on UDI Bus Binding definitions. The actual Bus Binding definitions are found in other specifications, such as the UDI PCI Bus Binding Specification.

¹As an exception to this version compatibility, version 1.0 (0x100) is not forward compatible with any other versions bearing the major number of 1; version 1.0 of the specification cannot be wholly implemented as a functional product.