svcadm(8)을 검색하려면 섹션에서 8 을 선택하고, 맨 페이지 이름에 svcadm을 입력하고 검색을 누른다.
Intro(9e)
Intro(9E) Driver Entry Points Intro(9E)
NAME
Intro, intro - overview of device driver interfaces and introduction to
driver entry points
DESCRIPTION
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 Oracle Solaris operating system. It describes the interfaces
provided by the Device Driver Interface and the Driver-Kernel Interface
(DDI/DKI).
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 trans‐
lator is available. Likewise the new environment might include multiple
processors. More often, however, software is ported between environ‐
ments 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:
o To enhance functionality, members had been added to kernel
data structures accessed by drivers, or the sizes of exist‐
ing members had been redefined.
o The calling or return syntax of kernel functions had
changed.
o Driver developers did not use existing kernel functions
where available, or relied on undocumented side effects that
were not maintained in the next release.
o 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 re‐
sponsible 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. Al‐
though 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 men‐
tioned, developers attempting to port device drivers have special chal‐
lenges. 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 com‐
patibility with existing drivers, the interaction between drivers and
the kernel must be rigorously regulated. This driver/kernel service in‐
terface is the most important of the three distinguishable interfaces
for a driver, summarized as follows:
o 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. Dri‐
vers may call any of the functions described in Section 9F.
These are the driver-to-kernel part of the interface.
o 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-spe‐
cific interactions make up the driver/hardware interface.
o 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 im‐
plementations based on System V Release 4. The DDI/DKI consists of sev‐
eral sections:
o DDI/DKI Architecture Independent - These interfaces are sup‐
ported on all implementations of System V Release 4.
o 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)
o Solaris DDI - These interfaces specific to Solaris.
o Solaris SPARC specific DDI - These interfaces are specific
to the SPARC processor, and may not be available on other
processors supported by Solaris.
o Solaris x86 specific DDI - These interfaces are specific to
the x86 processor, and may not be available on other proces‐
sors 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 accord‐
ing to these rules.
o Drivers cannot access system state structures (for example,
u and sysinfo) directly.
o 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.
o 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, modify‐
ing, or maintaining drivers that run on this operating system and be‐
yond. 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 en‐
try point routines.
9F Kernel Functions - contains reference pages for all driver sup‐
port routines.
9P Driver Properties - contains reference pages for driver proper‐
ties.
9S Data Structures - contains reference pages for driver-related
structures.
Compatibility Note
The Solaris implementation of the DDI/DKI was designed to provide bi‐
nary compatibility for third-party device drivers across currently sup‐
ported hardware platforms across minor releases of the operating sys‐
tem. However, unforeseen technical issues may force changes to the bi‐
nary interface of the DDI/DKI. We cannot therefore promise or in any
way assure that DDI/DKI-compliant device drivers will continue to oper‐
ate 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:
o NAME describes the routine's purpose.
o SYNOPSIS summarizes the routine's calling and return syntax.
o INTERFACE LEVEL describes any architecture dependencies. It
also indicates whether the use of the entry point is re‐
quired, optional, or discouraged.
o ARGUMENTS describes each of the routine's arguments.
o DESCRIPTION provides general information about the routine.
o RETURN VALUES describes each of the routine's return values.
o SEE ALSO gives sources for further information.
Overview of Driver Entry-Point Routines and Naming Conventions
By convention, driver routines use the name of the driver as a prefix.
For example, a driver named test will contain routines named test_open,
test_close, test_read, test_write, 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 or‐
der, and after all other include files.
The following table summarizes the STREAMS driver entry points de‐
scribed in this section.
tab(); lw(2.75i) lw(2.75i) lw(2.75i) lw(2.75i) RoutineType _ putDDI/DKI
srvDDI/DKI
The following table summarizes the driver entry points described in
this section.
tab(); lw(2.18i) lw(3.32i) lw(2.18i) lw(3.32i) RoutineType _ _finiSo‐
laris DDI _infoSolaris DDI _initSolaris DDI areadSolaris DDI attachSo‐
laris DDI awriteSolaris DDI chpollDDI/DKI closeDDI/DKI 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 ioctlDDI/DKI
ks_updateSolaris DDI mapdev_accessSolaris DDI mapdev_dupSolaris DDI
mapdev_freeSolaris DDI mmapDKI only openDDI/DKI powerSolaris DDI print‐
DDI/DKI probeSolaris DDI prop_opSolaris DDI readDDI/DKI segmapDKI only
strategyDDI/DKI 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 writeDDI/DKI
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).
tab(); cw(1.69i) cw(3.81i) lw(1.69i) lw(3.81i) Error ValueError De‐
scription _ EAGAINT{ 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. T} _ EFAULTT{ An invalid address has been
passed as an argument; memory addressing error. This is used in open,
close, ioctl, read, write, and strategy. T} _ EINTRT{ Sleep inter‐
rupted by signal. This is used in open, close, ioctl, read, write, and
strategy. T} _ EINVALT{ An invalid argument was passed to the routine.
This is used in open, ioctl, read, write, and strategy. T} _ EIOT{ A
device error occurred; an error condition was detected in a device sta‐
tus 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.
T} _ ENXIOT{ 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 speci‐
fied. This is used in open, close, ioctl, read, write, and strategy.
T} _ EPERMT{ A process attempting an operation did not have required
permission. This is used in open, ioctl, read, write, and strategy. T}
_ EROFST{ An attempt was made to open for writing a read-only device.
This is used in open. T}
The table below cross references error values to the driver routines
from which the error values can be returned.
tab() box; cw(1.08i) |cw(1.11i) |cw(1.12i) |cw(2.18i) lw(1.08i)
|lw(1.11i) |lw(1.12i) |lw(2.18i) opencloseioctlread, write and strategy
_ EAGAINEFAULTEAGAINEAGAIN EFAULTEINTREFAULTEFAULT EINTREIOEINTREINTR
EINVALENXIOEINVALEINVAL EIOEIOEIO ENXIOENXIOENXIO EPERMEPERM EROFS
SEE ALSO
Intro(9F), Intro(9S)
Writing Device Drivers in Oracle Solaris 11.4
Oracle Solaris 11.4 9 September 2024 Intro(9E)