1Intro(9E) Driver Entry Points Intro(9E)
2
6 Intro, intro - overview of device driver interfaces and introduction to
7 driver entry points
8
10 This page provides an overview of device driver interfaces and all of
11 the Section 9 man pages (9E, 9F, 9P, and 9S). This overview is followed
12 by an introduction to Section 9E, the driver entry-point routines.
13 Overview of Device Driver Interfaces
15 Section 9 provides reference information needed to write device drivers
16 for the Solaris operating environment. It describes the interfaces pro‐
17 vided by the Device Driver Interface and the Driver-Kernel Interface
18 (DDI/DKI).
19 Porting
21 Software is usually considered portable if it can be adapted to run in
22 a different environment more cheaply than it can be rewritten. The new
23 environment may include a different processor, operating system, and
24 even the language in which the program is written, if a language trans‐
25 lator is available. Likewise the new environment might include multiple
26 processors. More often, however, software is ported between environ‐
27 ments that share an operating system, processor, and source language.
28 The source code is modified to accommodate the differences in compilers
29 or processors or releases of the operating system.
30 In the past, device drivers did not port easily for one or more of the
33 following reasons:
34 o To enhance functionality, members had been added to kernel
36 data structures accessed by drivers, or the sizes of exist‐
37 ing members had been redefined.
38 o The calling or return syntax of kernel functions had
40 changed.
41 o Driver developers did not use existing kernel functions
43 where available, or relied on undocumented side effects that
44 were not maintained in the next release.
45 o Architecture-specific code had been scattered throughout the
47 driver when it could have been isolated.
48 Operating systems are periodically reissued to customers as a way to
51 improve performance, fix bugs, and add new features. This is probably
52 the most common threat to compatibility encountered by developers
53 responsible for maintaining software. Another common problem is upgrad‐
54 ing hardware. As new hardware is developed, customers occasionally
55 decide to upgrade to faster, more capable computers of the same family.
56 Although they may run the same operating system as those being
57 replaced, architecture-specific code may prevent the software from
58 porting.
59 Scope of Interfaces
61 Although application programs have all of the porting problems men‐
62 tioned, developers attempting to port device drivers have special chal‐
63 lenges. Before describing the DDI/DKI, it is necessary to understand
64 the position of device drivers in operating systems.
65 Device drivers are kernel modules that control data transferred to and
68 received from peripheral devices but are developed independently from
69 the rest of the kernel. If the goal of achieving complete freedom in
70 modifying the kernel is to be reconciled with the goal of binary com‐
71 patibility with existing drivers, the interaction between drivers and
72 the kernel must be rigorously regulated. This driver/kernel service
73 interface is the most important of the three distinguishable interfaces
74 for a driver, summarized as follows:
75 o Driver-Kernel. I/O System calls result in calls to driver
77 entry point routines. These make up the kernel-to-driver
78 part of the service interface, described in Section 9E.
79 Drivers may call any of the functions described in Section
80 9F. These are the driver-to-kernel part of the interface.
81 o Driver-Hardware. All drivers (except software drivers) must
83 include code for interrupt handling, and may also perform
84 direct memory access (DMA). These and other hardware-spe‐
85 cific interactions make up the driver/hardware interface.
86 o Driver-Boot/Configuration Software. The interaction between
88 the driver and the boot and configuration software is the
89 third interface affecting drivers.
90 Scope of the DDI/DKI
92 The primary goal of the DDI/DKI is to facilitate both source and binary
93 portability across successive releases of the operating systems on a
94 particular machine. In addition, it promotes source portability across
95 implementations of UNIX on different machines, and applies only to
96 implementations based on System V Release 4. The DDI/DKI consists of
97 several sections:
98 o DDI/DKI Architecture Independent - These interfaces are sup‐
100 ported on all implementations of System V Release 4.
101 o DKI-only - These interfaces are part of System V Release 4,
103 and may not be supported in future releases of System V.
104 There are only two interfaces in this class, segmap(9E) and
105 hat_getkpfnum(9F)
106 o Solaris DDI - These interfaces specific to Solaris.
108 o Solaris SPARC specific DDI - These interfaces are specific
110 to the SPARC processor, and may not be available on other
111 processors supported by Solaris.
112 o Solaris x86 specific DDI - These interfaces are specific to
114 the x86 processor, and may not be available on other proces‐
115 sors supported by Solaris.
116 To achieve the goal of source and binary compatibility, the functions,
119 routines, and structures specified in the DDI/DKI must be used accord‐
120 ing to these rules.
121 o Drivers cannot access system state structures (for example,
123 u and sysinfo) directly.
124 o For structures external to the driver that may be accessed
126 directly, only the utility functions provided in Section 9F
127 should be used. More generally, these functions should be
128 used wherever possible.
129 o The headers <sys/ddi.h> and <sys/sunddi.h> must be the last
131 header files included by the driver.
132 Audience
134 Section 9 is for software engineers responsible for creating, modify‐
135 ing, or maintaining drivers that run on this operating system and
136 beyond. It assumes that the reader is familiar with system internals
137 and the C programming language.
138 PCMCIA Standard
140 The PC Card 95 Standard is listed under the SEE ALSO heading in some
141 Section 9 reference pages. This refers to documentation published by
142 the Personal Computer Memory Card International Association (PCMCIA)
143 and the Japan Electronic Industry Development Association (JEIDA).
144 How to Use Section 9
146 Section 9 is divided into the following subsections:
147 9E Driver Entry Points - contains reference pages for all driver
149 entry point routines.
150 9F Kernel Functions - contains reference pages for all driver sup‐
153 port routines.
154 9P Driver Properties - contains reference pages for driver proper‐
157 ties.
158 9S Data Structures - contains reference pages for driver-related
161 structures.
162 Compatibility Note
165 Sun Microsystem's implementation of the DDI/DKI was designed to provide
166 binary compatibility for third-party device drivers across currently
167 supported hardware platforms across minor releases of the operating
168 system. However, unforeseen technical issues may force changes to the
169 binary interface of the DDI/DKI. We cannot therefore promise or in any
170 way assure that DDI/DKI-compliant device drivers will continue to oper‐
171 ate correctly on future releases.
172 Introduction to Section 9E
174 Section 9E describes the entry-point routines a developer can include
175 in a device driver. These are called entry-point because they provide
176 the calling and return syntax from the kernel into the driver. Entry-
177 points are called, for instance, in response to system calls, when the
178 driver is loaded, or in response to STREAMS events.
179 Kernel functions usable by the driver are described in section 9F.
182 In this section, reference pages contain the following headings:
185 o NAME describes the routine's purpose.
187 o SYNOPSIS summarizes the routine's calling and return syntax.
189 o INTERFACE LEVEL describes any architecture dependencies. It
191 also indicates whether the use of the entry point is
192 required, optional, or discouraged.
193 o ARGUMENTS describes each of the routine's arguments.
195 o DESCRIPTION provides general information about the routine.
197 o RETURN VALUES describes each of the routine's return values.
199 o SEE ALSO gives sources for further information.
201 Overview of Driver Entry-Point Routines and Naming Conventions
203 By convention, a prefix string is added to the driver routine names.
204 For a driver with the prefix prefix, the driver code may contain rou‐
205 tines named prefixopen, prefixclose, prefixread, prefixwrite, and so
206 forth. All global variables associated with the driver should also use
207 the same prefix.
208 All routines and data should be declared as static.
211 Every driver MUST include <sys/ddi.h> and <sys/sunddi.h>, in that
214 order, and after all other include files.
215 The following table summarizes the STREAMS driver entry points
218 described in this section.
219 Routine Type
224 ───────────────────────────────────────────────────────────
225 put DDI/DKI
226 srv DDI/DKI
227 The following table summarizes the driver entry points described in
231 this section.
232 Routine Type
237 ───────────────────────────────────────────────────────────
238 _fini Solaris DDI
239 _info Solaris DDI
240 _init Solaris DDI
241 aread Solaris DDI
242 attach Solaris DDI
243 awrite Solaris DDI
244 chpoll DDI/DKI
245 close DDI/DKI
246 detach Solaris DDI
247 devmap Solaris DDI
248 devmap_access Solaris DDI
249 devmap_contextmgt Solaris DDI
250 devmap_dup Solaris DDI
251 devmap_map Solaris DDI
252 devmap_unmap Solaris DDI
253 dump Solaris DDI
254 getinfo Solaris DDI
255 identify Solaris DDI
256 ioctl DDI/DKI
257 ks_update Solaris DDI
258 mapdev_access Solaris DDI
259 mapdev_dup Solaris DDI
260 mapdev_free Solaris DDI
261 mmap DKI only
262 open DDI/DKI
263 power Solaris DDI
264 print DDI/DKI
265 probe Solaris DDI
266 prop_op Solaris DDI
268 read DDI/DKI
269 segmap DKI only
270 strategy DDI/DKI
271 tran_abort Solaris DDI
272 tran_destroy_pkt Solaris DDI
273 tran_dmafree Solaris DDI
274 tran_getcap Solaris DDI
275 tran_init_pkt Solaris DDI
276 tran_reset Solaris DDI
277 tran_reset_notify Solaris DDI
278 tran_setcap Solaris DDI
279 tran_start Solaris DDI
280 tran_sync_pkt Solaris DDI
281 tran_tgt_free Solaris DDI
282 tran_tgt_init Solaris DDI
283 tran_tgt_probe Solaris DDI
284 write DDI/DKI
285 The following table lists the error codes returned by a driver routine
289 when it encounters an error. The error values are listed in alphabetic
290 order and are defined in sys/errno.h. In the driver open(9E),
291 close(9E), ioctl(9E), read(9E), and write(9E) routines, errors are
292 passed back to the user by calling bioerror(9F) to set b_flags to the
293 proper error code. In the driver strategy(9E) routine, errors are
294 passed back to the user by setting the b_error member of the buf(9S)
295 structure to the error code. For STREAMS ioctl routines, errors should
296 be sent upstream in an M_IOCNAK message. For STREAMS read() and write()
297 routines, errors should be sent upstream in an M_ERROR message. The
298 driver print routine should not return an error code because the func‐
299 tion that it calls, cmn_err(9F), is declared as void (no error is
300 returned).
301 Error Value Error Description
306 ───────────────────────────────────────────────────────────
307 EAGAIN Kernel resources, such as the buf
308 structure or cache memory, are not
309 available at this time (device may be
310 busy, or the system resource is not
311 available). This is used in open,
312 ioctl, read, write, and strategy.
313 ───────────────────────────────────────────────────────────
314 EFAULT An invalid address has been passed as
315 an argument; memory addressing error.
316 This is used in open, close, ioctl,
317 read, write, and strategy.
318 ───────────────────────────────────────────────────────────
319 EINTR Sleep interrupted by signal. This is
320 used in open, close, ioctl, read,
321 write, and strategy.
322 ───────────────────────────────────────────────────────────
323 EINVAL An invalid argument was passed to the
324 routine. This is used in open, ioctl,
325 read, write, and strategy.
326 ───────────────────────────────────────────────────────────
327 EIO A device error occurred; an error con‐
335 dition was detected in a device status
336 register (the I/O request was valid,
337 but an error occurred on the device).
338 This is used in open, close, ioctl,
339 read, write, and strategy.
340 ───────────────────────────────────────────────────────────
341 ENXIO An attempt was made to access a device
342 or subdevice that does not exist (one
343 that is not configured); an attempt
344 was made to perform an invalid I/O
345 operation; an incorrect minor number
346 was specified. This is used in open,
347 close, ioctl, read, write, and strat‐
348 egy.
349 ───────────────────────────────────────────────────────────
350 EPERM A process attempting an operation did
351 not have required permission. This is
352 used in open, ioctl, read, write, and
353 strategy.
354 ───────────────────────────────────────────────────────────
355 EROFS An attempt was made to open for writ‐
356 ing a read-only device. This is used
357 in open.
358 The table below cross references error values to the driver routines
362 from which the error values can be returned.
363 ┌────────────┬─────────────┬──────────────┬─────────────────────────┐
368 │ open │ close │ ioctl │read, write and strategy │
369 ├────────────┼─────────────┼──────────────┼─────────────────────────┤
370 │EAGAIN │ EFAULT │ EAGAIN │EAGAIN │
371 │EFAULT │ EINTR │ EFAULT │EFAULT │
372 │EINTR │ EIO │ EINTR │EINTR │
373 │EINVAL │ ENXIO │ EINVAL │EINVAL │
374 │EIO │ │ EIO │EIO │
375 │ENXIO │ │ ENXIO │ENXIO │
376 │EPERM │ │ EPERM │ │
377 │EROFS │ │ │ │
378 └────────────┴─────────────┴──────────────┴─────────────────────────┘
379
381 Intro(9F), Intro(9S)
382SunOS 5.11 15 May 2001 Intro(9E)