Content-type: text/html Man page of Intro


Section: Driver Entry Points (9E)
Updated: 21 Dec 2004
Index Return to Main Contents


Intro, intro - overview of device driver interfaces and introduction to driver entry points  


This page provides an overview of device driver interfaces and all of the Section 9 man pages (9E, 9F, 9P, and 9S). This overview is followed by an introduction to Section 9E, the driver entry-point routines.  

Overview of Device Driver Interfaces

Section 9 provides reference information needed to write device drivers for the Solaris operating environment. It describes the interfaces provided by the Device Driver Interface and the Driver-Kernel Interface (DDI/DKI).  


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 Solaris.

• Solaris SPARC specific DDI - These interfaces are specific to the SPARC processor, and may not be available on other processors supported by Solaris.

• Solaris x86 specific DDI - These interfaces are specific to the x86 processor, and may not be available on other processors supported by Solaris.

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.



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.  

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 the following 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.

9P Driver Properties - contains reference pages for driver properties.

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


Compatibility Note

Sun Microsystem'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.  

Introduction to Section 9E

Section 9E describes the entry-point routines a developer can include in a device driver. These are called entry-point because they provide the calling and return syntax from the kernel into the driver. Entry-points are called, for instance, in response to system calls, when the driver is loaded, or in response to STREAMS events.

Kernel functions usable by the driver are described in section 9F.

In this section, reference pages contain the following headings:

NAME describes the routine's purpose.

SYNOPSIS summarizes the routine's calling and return syntax.

INTERFACE LEVEL describes any architecture dependencies. It also indicates whether the use of the entry point is required, optional, or discouraged.

ARGUMENTS describes each of the routine's arguments.

DESCRIPTION provides general information about the routine.

RETURN VALUES describes each of the routine's return values.

SEE ALSO gives sources for further information.


Overview of Driver Entry-Point Routines and Naming Conventions

By convention, a prefix string is added to the driver routine names. For a driver with the prefix prefix, the driver code may contain routines named prefixopen, prefixclose, prefixread, prefixwrite, and so forth. All global variables associated with the driver should also use the same prefix.

All routines and data should be declared as static.

Every driver MUST include <sys/ddi.h> and <sys/sunddi.h>, in that order, and after all other include files.

The following table summarizes the STREAMS driver entry points described in this section.


The following table summarizes the driver entry points described in this section.

_finiSolaris DDI
_infoSolaris DDI
_initSolaris DDI
areadSolaris DDI
attachSolaris DDI
awriteSolaris DDI
detachSolaris DDI
devmapSolaris DDI
devmap_accessSolaris DDI
devmap_contextmgtSolaris DDI
devmap_dupSolaris DDI
devmap_mapSolaris DDI
devmap_unmapSolaris DDI
dumpSolaris DDI
getinfoSolaris DDI
identifySolaris DDI
ks_updateSolaris DDI
mapdev_accessSolaris DDI
mapdev_dupSolaris DDI
mapdev_freeSolaris DDI
mmapDKI only
powerSolaris DDI
probeSolaris DDI
prop_opSolaris DDI
segmapDKI only
tran_abortSolaris DDI
tran_destroy_pktSolaris DDI
tran_dmafreeSolaris DDI
tran_getcapSolaris DDI
tran_init_pktSolaris DDI
tran_resetSolaris DDI
tran_reset_notifySolaris DDI
tran_setcapSolaris DDI
tran_startSolaris DDI
tran_sync_pktSolaris DDI
tran_tgt_freeSolaris DDI
tran_tgt_initSolaris DDI
tran_tgt_probeSolaris DDI

The following table lists the error codes returned by a driver routine when it encounters an error. The error values are listed in alphabetic order and are defined in sys/errno.h. In the driver open(9E), close(9E), ioctl(9E), read(9E), and write(9E) routines, errors are passed back to the user by calling bioerror(9F) to set b_flags to the proper error code. In the driver strategy(9E) routine, errors are passed back to the user by setting the b_error member of the buf(9S) structure to the error code. For STREAMS ioctl routines, errors should be sent upstream in an M_IOCNAK message. For STREAMS read() and write() routines, errors should be sent upstream in an M_ERROR message. The driver print routine should not return an error code because the function that it calls, cmn_err(9F), is declared as void (no error is returned).

Error ValueError Description
EAGAIN Kernel resources, such as the buf structure or cache memory, are not available at this time (device may be busy, or the system resource is not available). This is used in open, ioctl, read, write, and strategy.
EFAULT An invalid address has been passed as an argument; memory addressing error. This is used in open, close, ioctl, read, write, and strategy.
EINTR Sleep interrupted by signal. This is used in open, close, ioctl, read, write, and strategy.
EINVAL An invalid argument was passed to the routine. This is used in open, ioctl, read, write, and strategy.
EIO A device error occurred; an error condition was detected in a device status register (the I/O request was valid, but an error occurred on the device). This is used in open, close, ioctl, read, write, and strategy.
ENXIO An attempt was made to access a device or subdevice that does not exist (one that is not configured); an attempt was made to perform an invalid I/O operation; an incorrect minor number was specified. This is used in open, close, ioctl, read, write, and strategy.
EPERM A process attempting an operation did not have required permission. This is used in open, ioctl, read, write, and strategy.
EROFS An attempt was made to open for writing a read-only device. This is used in open.

The table below cross references error values to the driver routines from which the error values can be returned.

opencloseioctlread, write and strategy



intro(9F), intro(9S)  


Name Description

_fini(9E) loadable module configuration entry points

_info(9E) See _fini(9E)

_init(9E) See _fini(9E)

aread(9E) asynchronous read from a device

attach(9E) Attach a device to the system, or resume it

awrite(9E) asynchronous write to a device

chpoll(9E) poll entry point for a non-STREAMS character driver

close(9E) relinquish access to a device

csx_event_handler(9E) PC Card driver event handler

detach(9E) detach or suspend a device

devmap(9E) validate and translate virtual mapping for memory mapped device

devmap_access(9E) device mapping access entry point

devmap_contextmgt(9E) driver callback function for context management

devmap_dup(9E) device mapping duplication entry point

devmap_map(9E) device mapping create entry point

devmap_unmap(9E) device mapping unmap entry point

dump(9E) dump memory to device during system failure

getinfo(9E) get device driver information

gld(9E) Generic LAN Driver entry points

gldm_get_stats(9E) See gld(9E)

gldm_intr(9E) See gld(9E)

gldm_ioctl(9E) See gld(9E)

gldm_reset(9E) See gld(9E)

gldm_send(9E) See gld(9E)

gldm_set_mac_addr(9E) See gld(9E)

gldm_set_multicast(9E) See gld(9E)

gldm_set_promiscuous(9E) See gld(9E)

gldm_start(9E) See gld(9E)

gldm_stop(9E) See gld(9E)

identify(9E) determine if a driver is associated with a device

ioctl(9E) control a character device

ks_snapshot(9E) take a snapshot of kstat data

ks_update(9E) dynamically update kstats

mmap(9E) check virtual mapping for memory mapped device

open(9E) gain access to a device

power(9E) power a device attached to the system

print(9E) display a driver message on system console

probe(9E) determine if a non-self-identifying device is present

prop_op(9E) report driver property information

put(9E) receive messages from the preceding queue

read(9E) read data from a device

segmap(9E) map device memory into user space

srv(9E) service queued messages

strategy(9E) perform block I/O

tran_abort(9E) abort a SCSI command

tran_bus_reset(9e) reset a SCSI bus

tran_destroy_pkt(9E) See tran_init_pkt(9E)

tran_dmafree(9E) SCSI HBA DMA deallocation entry point

tran_getcap(9E) get/set SCSI transport capability

tran_init_pkt(9E) SCSI HBA packet preparation and deallocation

tran_quiesce(9e) quiesce and unquiesce a SCSI bus

tran_reset(9E) reset a SCSI bus or target

tran_reset_notify(9E) request to notify SCSI target of bus reset

tran_setcap(9E) See tran_getcap(9E)

tran_start(9E) request to transport a SCSI command

tran_sync_pkt(9E) SCSI HBA memory synchronization entry point

tran_tgt_free(9E) request to free HBA resources allocated on behalf of a target

tran_tgt_init(9E) request to initialize HBA resources on behalf of a particular target

tran_tgt_probe(9E) request to probe SCSI bus for a particular target

tran_unquiesce(9e) See tran_quiesce(9e)

write(9E) write data to a device



Overview of Device Driver Interfaces
Scope of Interfaces
Scope of the DDI/DKI
PCMCIA Standard
How to Use Section 9
Compatibility Note
Introduction to Section 9E
Overview of Driver Entry-Point Routines and Naming Conventions

This document was created by man2html, using the manual pages.
Time: 02:39:36 GMT, October 02, 2010