man pages section 9: Device Driver Interfaces

Intro(9)

NAME

Intro- introduction to device driver interfaces

DESCRIPTION

Section 9 provides reference information needed to write device drivers for Solaris 2, Solaris 7, Solaris 8, and Trusted Solaris versions 2.5.1, 7, 8, and 8 4/01. It describes the interfaces provided by the Device Driver Interface Driver-Kernel Interface (DDI/DKI).

This reference information can be:

Information that is unique to and originates in the Trusted Solaris environment, such as tsol_get_strattr(9F).
SunOS 5.8 device drivers that have been modified to work within Trusted Solaris security policy, such as copyb(9F). Man pages for modified device drivers have been rewritten to remove information that is not accurate for how the system call behaves within the Trusted Solaris environment. Modified man pages also have added descriptions for Trusted Solaris security features.
SunOS 5.8 device drivers that remain unchanged from the Solaris 8 release.

Note -

The printed Trusted Solaris 8 4/01 Reference Manual includes only those man pages that have been modified or originate in the Trusted Solaris environment. Printed versions of unchanged SunOS 5.8 man pages are found in the SunOS 5.8 Reference Manual.

Trusted Solaris drivers can call any of the functions described in 9E, 9F, or 9S.

Porting

Software is usually considered portable if it can be adapted to run in a different environment more cheaply than it can be rewritten. The new environment may include a different processor, operating system, and even the language in which the program is written, if a language translator is available. Likewise the new environment might include multiple processors. More often, however, software is ported between environments that share an operating system, processor, and source language. The source code is modified to accommodate the differences in compilers or processors or releases of the operating system.

In the past, device drivers did not port easily for one or more of the following reasons:

To enhance functionality, members had been added to kernel data structures accessed by drivers, or the sizes of existing members had been redefined.
The calling or return syntax of kernel functions had changed.
Driver developers did not use existing kernel functions where available, or relied on undocumented side effects that were not maintained in the next release.
Architecture-specific code had been scattered throughout the driver when it could have been isolated.

Operating systems are periodically reissued to customers as a way to improve performance, fix bugs, and add new features. This is probably the most common threat to compatibility encountered by developers responsible for maintaining software. Another common problem is upgrading hardware. As new hardware is developed, customers occasionally decide to upgrade to faster, more capable computers of the same family. Although they may run the same operating system as those being replaced, architecture-specific code may prevent the software from porting.

Scope of Interfaces

Although application programs have all of the porting problems mentioned, developers attempting to port device drivers have special challenges. Before describing the DDI/DKI, it is necessary to understand the position of device drivers in operating systems.

Device drivers are kernel modules that control data transferred to and received from peripheral devices but are developed independently from the rest of the kernel. If the goal of achieving complete freedom in modifying the kernel is to be reconciled with the goal of binary compatibility with existing drivers, the interaction between drivers and the kernel must be rigorously regulated. This driver/kernel service interface is the most important of the three distinguishable interfaces for a driver, summarized as follows:

Driver-Kernel. I/O System calls result in calls to driver entry point routines. These make up the kernel-to-driver part of the service interface, described in Section 9E. Drivers may call any of the functions described in Section 9F. These are the driver-to-kernel part of the interface.
Driver-Hardware. All drivers (except software drivers) must include code for interrupt handling, and may also perform direct memory access (DMA). These and other hardware-specific interactions make up the driver/hardware interface.
Driver-Boot/Configuration Software. The interaction between the driver and the boot and configuration software is the third interface affecting drivers.

Scope of the DDI/DKI

The primary goal of the DDI/DKI is to facilitate both source and binary portability across successive releases of the operating systems on a particular machine. In addition, it promotes source portability across implementations of UNIX on different machines, and applies only to implementations based on System V Release 4. The DDI/DKI consists of several sections:

DDI/DKI Architecture Independent - These interfaces are supported on all implementations of System V Release 4.
DKI-only - These interfaces are part of System V Release 4, and may not be supported in future releases of System V. There are only two interfaces in this class, segmap(9E) and hat_getkpfnum(9F)
Solaris DDI - These interfaces specific to the Solaris environment.
Solaris SPARC specific DDI - These interfaces are specific to the SPARC processor, and may not be available on other processors supported by Solaris software.
Solaris IA specific DDI - These interfaces are specific to the IA processor, and may not be available on other processors supported by Solaris software.

To achieve the goal of source and binary compatibility, the functions, routines, and structures specified in the DDI/DKI must be used according to these rules.

Drivers cannot access system state structures (for example, u and sysinfo) directly.
For structures external to the driver that may be accessed directly, only the utility functions provided in Section 9F should be used. More generally, these functions should be used wherever possible.
The headers <sys/ddi.h> and <sys/sunddi.h> must be the last header files included by the driver.

Audience

Section 9 is for software engineers responsible for creating, modifying, or maintaining drivers that run in this operating environment and later versions. It assumes that the reader is familiar with system internals and the C Programming Language.

PCMCIA Standard

The PC Card 95 Standard is listed under the SEE ALSO heading in some Section 9 reference pages. This refers to documentation published by the Personal Computer Memory Card International Association (PCMCIA) and the Japan Electronic Industry Development Association (JEIDA).

How to Use Section 9

Section 9 is divided into three subsections:

9E

Driver Entry Points - contains reference pages for all driver entry point routines.

9F

Kernel Functions - contains reference pages for all driver support routines.

The Trusted Solaris environment modifies some routines and adds its own.

9S

Data Structures - contains reference pages for driver-related structures.

Trusted Solaris 8 4/01 Reference Manual

intro(9F)

SunOS 5.8 Reference Manual

intro(9E), intro(9S)

NOTES

The Solaris environment's implementation of the DDI/DKI was designed to provide binary compatibility for third-party device drivers across currently supported hardware platforms across minor releases of the operating system.

However, unforeseen technical issues may force changes to the binary interface of the DDI/DKI. We cannot therefore promise or in any way assure that DDI/DKI-compliant device drivers will continue to operate correctly on future releases.

Trusted Solaris 8 4/01 Last Revised 26 Jul 2001

NAME | DESCRIPTION | SEE ALSO | NOTES