DDI/DKI Facilities

This section discusses design considerations necessary for using the DDI/DKI interfaces.

Device IDs

The Solaris DDI provides interfaces that allow drivers to provide a persistent, unique identifier for a device. The device ID can be used to identify or locate a device and is independent of the device's name or number (dev_t). Applications can use the functions defined in libdevid(3LIB) to read and manipulate the device IDs registered by the drivers.

Device Properties

The attributes of a device or device driver are specified by properties. A property is a name-value pair. The name is a string that identifies the property with an associated value. Properties can be defined by the FCode of a self-identifying device, by a hardware configuration file (see the driver.conf(4) man page), or by the driver itself using the ddi_prop_update(9F) family of routines.

Interrupt Handling

The Solaris 9 DDI/DKI addresses these aspects of device interrupt handling:

• Registering device interrupts with the system

• Removing device interrupts

• Dispatching interrupts to interrupt handlers

Device interrupt sources are contained in a property called interrupt, which is either provided by the PROM of a self-identifying device, in a hardware configuration file, or by the booting system on the IA platform.

Callback Functions

Certain DDI mechanisms provide a callback mechanism. DDI functions provide a mechanism for scheduling a callback when a condition is met. Conditions for which callback functions are used include:

• When a transfer has completed

• When a resource might have become available

• When a time-out period has expired

In some sense, callback functions are similar to entry points—interrupt handlers, for example. DDI functions that allow callbacks expect the callback function to perform certain tasks. In the case of DMA routines, a callback function must return a value indicating whether the callback function needs to be rescheduled in case of a failure.

Callback functions execute as a separate interrupt thread and must handle all the usual multithreading issues.

A driver must cancel all scheduled callback functions before detaching a device.

Software State Management

To assist device driver writers in allocating state structures, the Solaris 9 DDI/DKI provides a set of memory management routines called the software state management routines (also known as the soft state routines). These routines dynamically allocate, retrieve, and destroy memory items of a specified size, and hide the details of list management. An instance number is used to identify the desired memory item; this number can be (and usually is) the instance number assigned by the system.

Routines are provided to:

• Initialize a driver's soft state list

• Allocate space for an instance of a driver's soft state

• Retrieve a pointer to an instance of a driver's soft state

• Free the memory for an instance of a driver's soft state

• Finish using a driver's soft state list

See Loadable Driver Interfaces for an example of how to use these routines.

Programmed I/O Device Access

Programmed I/O device access is the act of reading and writing of device registers or device memory by the host CPU. The Solaris DDI provides interfaces for mapping a device's registers or memory by the kernel as well as interfaces for reading and writing to device memory from the driver. These interfaces are designed to enable drivers to be developed that are platform and bus independent, by automatically managing any difference in device and host endianness as well as enforcing any memory-store ordering requirements imposed by the device.

Direct Memory Access (DMA)

Solaris defines a high-level, architecture-independent model for supporting DMA-capable devices. The Solaris DDI is designed to shield drivers from platform-specific details, which enables a common driver to be developed that runs across multiple platforms and architectures.

Driver and Device Statistics

Solaris provides a rich set of interfaces for maintaining and exporting kernel-level statistics, or kstats. Drivers are free to use these interfaces to export driver and device statistics that can be used by user applications to observe the internal state of the driver. See the kstat_create(9F) and kstat(3KSTAT) man pages for additional information.