Device Access -- Programmed I/O

The Solaris operating environment provides driver developers with a comprehensive set of interfaces for accessing device memory. These interfaces are designed to shield the driver from platform-specific dependencies by handling mismatches between processor and device endianness as well as enforcing any data ordering dependencies the device might have. By using these interfaces, a single source driver can be developed that runs on both that SPARC and IA (Intel architecture) processor architectures as well as the various platforms from each respective processor family.

This chapter provides information on the following subjects:

• "Managing Differences in Device and Host Endianness"

• "Managing Data Ordering Requirements"

• "ddi_device_acc_attr Structure"

• "Mapping Device Memory"

• "Mapping Setup Example"

• "Alternate Device Access Interfaces"

Device Memory

Devices that support programmed I/O are assigned one or more regions of bus address space that map to addressable regions of the device. These mappings are described as pairs of values in the reg property associated with the device. Each value pair describes a segment of a bus address.

Drivers identify a particular bus address mapping by specifying the register number, or regspec, which is an index into the devices'reg property that identifies a (busaddr, size) pair. Drivers pass the register number when making calls to DDI functions such as ddi_regs_map_setup(9F). Drivers can determine how many mappable regions have been assigned to the device by calling ddi_dev_nregs(9F).

Managing Differences in Device and Host Endianness

The data format of the host can have different endian characteristics than the data format of the device. If this is the case, data transferred between the host and device needs to be byte swapped to conform to the data format requirements of the destination location. Other devices can have the same endian characteristics of the host and require no byte swapping of the data.

Drivers specify the endian characteristics of the device by setting the appropriate flag in the ddi_device_acc_attr(9S) structure that is passed to ddi_regs_map_setup(9F). The DDI framework then performs any required byte swapping when the driver calls a ddi_getX routine (such as ddi_get8(9F)) or a ddi_putX routine (such as ddi_put16(9F)) to read or write device memory.

Managing Data Ordering Requirements

Platforms can choose to reorder loads and stores of data to optimize performance of the platform. Because reordering might not be allowed by certain devices, the driver is required to specify the device's ordering requirements when setting up mappings to the device.

ddi_device_acc_attr Structure

This structure describes the endian and data ordering requirements of the device. The driver is required to initialize and pass one of these structures as an argument to ddi_regs_map_setup(9F).

typedef struct ddi_device_acc_attr {
        ushort_t       devacc_attr_version;
        uchar_t        devacc_attr_endian_flags;
        uchar_t        devacc_attr_dataorder;
} ddi_device_acc_attr_t;

Note - The system can access data more strictly than the driver specified in devacc_attr_dataorder. The restriction to the host diminishes while moving from strict data ordering to cache storing in terms of data accesses by the driver.

Mapping Device Memory

Drivers typically map all regions of a device during attach(9E). The driver maps a region of device memory by calling ddi_regs_map_setup(9F), specifying the register number of the region to map, the device access attributes for the region, an offset, and size. The DDI framework sets up the mappings for the device region and returns an opaque handle to the driver. This data access handle is passed as an argument to the ddi_get8(9F) or ddi_put8(9F) family of routines when reading or writing data to that region of the device.

The driver verifies that the shape of the device mappings match what the driver is expecting by checking the number of mappings exported by the device. It calls ddi_dev_nregs(9F) and then verifies the size of each mapping by calling ddi_dev_regsize(9F).

Mapping Setup Example

Example 6-1 is a simple example demonstrating the setup and use of the DDI data access interfaces. This driver is for a fictional little endian device that accepts one character at a time and generates an interrupt when ready for another. This device implements two register sets: the first is an 8-bit CSR register, and the second is an 8-bit data register.

Example 6-1 Mapping Setup

    #define CSR_REG 0
    #define DATA_REG 1

    /*
     * Initialize the device access attributes for the register
     * mapping
     */
    dev_acc_attr.devacc_attr_version = DDI_DEVICE_ATTR_V0;
    dev_acc_attr.devacc_attr_endian_flags = DDI_STRUCTURE_LE_ACC;
    dev_acc_attr.devacc_attr_dataorder = DDI_STRICTORDER_ACC;

    /*
     * Map in the csr register (register 0)
     */
    if (ddi_regs_map_setup(dip, CSR_REG, (caddr_t *)&(pio_p->csr), 0,
      sizeof (Pio_csr), &dev_acc_attr, &pio_p->csr_handle) != DDI_SUCCESS) {
        mutex_destroy(&pio_p->mutex);
        ddi_soft_state_free(pio_softstate, instance);
        return (DDI_FAILURE);
    }

    /*
     * Map in the data register (register 1)
     */
    if (ddi_regs_map_setup(dip, DATA_REG, (caddr_t *)&(pio_p->data), 0,
      sizeof (uchar_t), &dev_acc_attr, &pio_p->data_handle) \
                    != DDI_SUCCESS) {
        mutex_destroy(&pio_p->mutex);
        ddi_regs_map_free(&pio_p->csr_handle);
        ddi_soft_state_free(pio_softstate, instance);
        return (DDI_FAILURE);
    }