NAME

Intro − introduction to device driver interfaces

DESCRIPTION

Section 9 provides reference information needed to write Solaris 2.0 SPARC DDI/DKI device drivers.  It describes two device driver interface specifications:  the Device Driver Interface (DDI) and the Driver–Kernel Interface (DKI).  Drivers written to conform to one or both of these interfaces are more likely to be portable to other environments.  DDI and DKI address different aspects of the compatibility problem. These are summarized in Figure 1-1. 

Scope of DDI and DKI scale=100 define t1376 | [ box invis ht 48 wid 47 with .sw at 0,0 "DKI" at 0,40 ljust "only" at 0,24 ljust ] |
 
define t1372 | [ box invis ht 32 wid 81 with .sw at 0,0 "supported" at 0,24 ljust "after SVR4" at 0,8 ljust ] |
 
define t1369 | [ box invis ht 32 wid 97 with .sw at 0,0 "supported" at 0,24 ljust "through SVR4" at 0,8 ljust ] |
 
define t1393 | [ box invis ht 48 wid 69 with .sw at 0,0 "architecture" at 0,40 ljust "specific" at 0,24 ljust "routines" at 0,8 ljust ] |
 
define t1389 | [ box invis ht 48 wid 47 with .sw at 0,0 "SPARC" at 0,40 ljust "DDI" at 0,24 ljust ] |
 
define t1385 | [ box invis ht 48 wid 82 with .sw at 0,0 "architecture" at 0,40 ljust "independent" at 0,24 ljust "routines" at 0,8 ljust ] |
 
define t1381 | [ box invis ht 64 wid 58 with .sw at 0,0 "DDI" at 0,56 ljust "and" at 0,40 ljust "DKI" at 0,24 ljust ] |
 
box invis ht 144 wid 288 with .sw at 0,0 t1376 with .nw at 208,70 t1372 with .nw at 100,-2 t1369 with .nw at 200,-2 line  from 96,144 to 96,80 line  from 192,144 to 96,144 line  from 192,80 to 192,144 line  from 192,8 to 288,8 line  from 192,80 to 288,80 box ht 72 wid 96 with .nw at 96,80 line  from 288,80 to 288,8 t1393 with .nw at 4,138 t1389 with .nw at 120,138 t1385 with .nw at 0,70 t1381 with .nw at 116,74

Each box in Figure 1-1 represents a different set of interfaces.  The “SPARC DDI” ­set—identified throughout section 9 as “SPARC architecture specific ­(SPARC DDI)”—is intended to be supported in future releases.  The “DKI only” set—identified as “Architecture independent level 2 (DKI only)”—is not guaranteed to be supported in the next major release. 

Most of the routines, functions, and structures described in section 9 are part of both DDI and DKI—identified as “Architecture independent level 1 (DDI/DKI).” Drivers written to conform to both interfaces are portable to all platforms that conform to Solaris 2.0 SPARC DDI/DKI, and they will be compatible through and beyond the current release.  To understand more completely what is meant by “portable” and “compatible” for DDI and DKI, the scope of each interface must be more thoroughly explained. 

The goals of DDI and DKI overlap, and are not in any way mutually exclusive.  That is, a driver may be written to conform to both interfaces, increasing the chances that driver code can be ported and can remain compatible with future releases of the operating system. 

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 differences between DDI and 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 Device Driver Interface (DDI)

The primary goal of DDI is to facilitate both source and binary portability across successive releases of the operating systems on a particular machine.  Implicit in this goal is an important fact.  Although there is only one DKI, SPARC architectures have their own version of DDI (SPARC DDI).  Therefore, if a driver is ever to be ported to different platform, special attention must be paid to the architecture-specific routines that make up the “SPARC DDI” part of a driver.  These include but are not confined to the driver/hardware interface (as described in the previous section).  Some architecture-specific functionality also may belong to the driver/kernel interface, and may not be easy to locate. 

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

• Drivers cannot access system state structure (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 included at the end of the list of headers.  This header “undefines” several macros that are reimplemented as functions. 

Scope of the Driver-Kernel Interface (DKI)

As its name implies, the DKI (Driver–Kernel Interface) is a defined service interface for the entry point routines and utility functions specified for communication between the driver and kernel.  It does not encompass the driver/hardware or the driver/boot software interface. 

Information is exchanged between the driver and kernel in the form of data structures.  The DKI specifies the contents of these structures as well as the calling and return syntax of the entry points and utility functions. 

The intent of DKI is to promote source portability across implementations of UNIX on different machines, and applies only to implementations based on System V Release 4.  Because DKI applies only to the driver/kernel interface, it must be understood that the sections of driver code affecting the hardware and boot/configuration interfaces may need to be rewritten, and should be isolated in subroutines as much as possible. 

Note: Certain interfaces documented in the DKI are not part of the DDI.  Driver writers should be aware that the use of these interfaces is not guaranteed to be supported in future releases. 

Interface Members

As noted before, most entry points (Section 9E), functions (Section 9F), and structures (Section 9S) belong to both DDI and DKI.  Table 1-1 lists some of those that are exclusive either to DDI or DKI. 

Exclusive Entry Points, Functions, and Structures

Audience

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

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 functions used in DDI/DKI drivers. 

9S Data Structures − contains reference pages for structures used in DDI/DKI drivers. 

SEE ALSO

Intro(9E), Intro(9F), Intro(9S)

NOTES

SunSoft’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. 

Furthermore, future releases may contain additions to the DDI/DKI to support future platforms.  At that time device drivers wishing to operate across the new set of supported platforms may require these additions. 

SunOS 5.1/SPARC  —  Last change: 6 Apr 1992