| blob | 8376e3326e5c630876cf7f0899484b519083b386 |
1 '\" te
2 .\" Copyright (c) 2005 Sun Microsystems, Inc. All Rights Reserved.
3 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License.
4 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License.
5 .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
6 .TH ADD_DRV 1M "May 13, 2017"
7 .SH NAME
8 add_drv \- add a new device driver to the system
9 .SH SYNOPSIS
10 .LP
11 .nf
12 \fBadd_drv\fR [\fB-b\fR \fIbasedir\fR] [\fB-c\fR \fIclass_name\fR]
13 [\fB-i\fR '\fIidentify_name\fR...'] [\fB-m\fR '\fIpermission\fR','...']
14 [\fB-p\fR '\fIpolicy\fR'] [\fB-P\fR \fIprivilege\fR] [\fB-n\fR] [\fB-f\fR] [\fB-v\fR] \fIdevice_driver\fR
15 .fi
17 .SH DESCRIPTION
18 .LP
19 The \fBadd_drv\fR command is used to inform the system about newly installed
20 device drivers.
21 .sp
22 .LP
23 Each device on the system has a name associated with it. This name is
24 represented by the \fBname\fR property for the device. Similarly, the device
25 may also have a list of driver names associated with it. This list is
26 represented by the \fBcompatible\fR property for the device.
27 .sp
28 .LP
29 The system determines which devices will be managed by the driver being added
30 by examining the contents of the \fBname\fR property and the \fBcompatible\fR
31 property (if it exists) on each device. If the value in the \fBname\fR property
32 does not match the driver being added, each entry in the \fBcompatible\fR
33 property is tried, in order, until either a match occurs or there are no more
34 entries in the \fBcompatible\fR property.
35 .sp
36 .LP
37 In some cases, adding a new driver may require a reconfiguration boot. See the
38 \fBNOTES\fR section.
39 .sp
40 .LP
41 Aliases might require quoting (with double-quotes) if they contain numbers. See
42 \fBEXAMPLES\fR.
43 .SS "The \fB/etc/minor_perm\fR File"
44 .LP
45 \fBadd_drv\fR and \fBupdate_drv\fR(1M) read the \fB/etc/minor_perm\fR file to
46 obtain permission information. The permission specified is applied to matching
47 minor nodes created when a device bound to the driver is attached. A minor
48 node's permission may be manually changed by \fBchmod\fR(1). For such nodes,
49 the specified permissions apply, overriding the default permissions specified
50 via \fBadd_drv\fR or \fBupdate_drv\fR(1M).
51 .sp
52 .LP
53 The format of the \fB/etc/minor_perm\fR file is as follows:
54 .sp
55 .in +2
56 .nf
57 \fIname\fR\fB:\fR\fIminor_name permissions owner group\fR
58 .fi
59 .in -2
60 .sp
62 .sp
63 .LP
64 \fIminor_name\fR may be the actual name of the minor node, or contain shell
65 metacharacters to represent several minor nodes (see \fBsh\fR(1)).
66 .sp
67 .LP
68 For example:
69 .sp
70 .in +2
71 .nf
72 sd:* 0640 root sys
73 zs:[a-z],cu 0600 uucp uucp
74 mm:kmem 0640 root bin
75 .fi
76 .in -2
77 .sp
79 .sp
80 .LP
81 The first line sets all devices exported by the \fBsd\fR node to \fB0640\fR
82 permissions, owned by \fBroot\fR, with group \fBsys\fR. In the second line,
83 devices such as \fBa,cu\fR \fBand\fR \fBz,cu\fR exported by the \fBzs\fR driver
84 are set to \fB0600\fR permission, owned by \fBuucp\fR, with group \fBuucp\fR.
85 In the third line the \fBkmem\fR device exported by the \fBmm\fR driver is set
86 to \fB0640\fR permission, owned by \fBroot\fR, with group \fBbin\fR.
87 .SS "Running \fBadd_drv\fR from a \fBpostinstall\fR Script"
88 .LP
89 When running \fBadd_drv\fR from within the context of a legacy SVR4
90 package's postinstall
91 script, you must consider whether the package is being added to a system image
92 or to a running system. When a package is being installed on a system image,
93 the \fBBASEDIR\fR variable refers to the image's base directory. In this
94 situation, \fBadd_drv\fR should be invoked with \fB-b\fR \fB$BASEDIR\fR. This
95 causes \fBadd_drv\fR only to update the image's system files; a reboot of the
96 system or client would be required to make the driver operational.
97 .sp
98 .LP
99 When a package is being installed on the running system itself, the system
100 files need to be updated, as in the case above. However, the running kernel can
101 be informed of the existence of the new driver without requiring a reboot. To
102 accomplish this, the postinstall script must invoke \fBadd_drv\fR without the
103 \fB-b\fR option. Accordingly, \fBpostinstall\fR scripts invoking \fBadd_drv\fR
104 should be written thusly:
105 .sp
106 .in +2
107 .nf
108 if [ "${BASEDIR:=/}" = "/" ]
109 then
110 ADD_DRV="add_drv"
111 else
112 ADD_DRV="add_drv -b ${BASEDIR}"
113 fi
114 $ADD_DRV [<options>] \fI<driver>\fR
115 .fi
116 .in -2
117 .sp
119 .sp
120 .LP
121 \&...or, alternatively:
122 .sp
123 .in +2
124 .nf
125 if [ "${BASEDIR:=/}" != "/" ]
126 then
127 BASEDIR_OPT="-b $BASEDIR"
128 fi
129 add_drv $BASEDIR_OPT [<options>] \fI<driver>\fR
130 .fi
131 .in -2
132 .sp
134 .sp
135 .LP
136 The \fB-b\fR option is described below.
137 .SH OPTIONS
138 .ne 2
139 .na
140 \fB\fB-b\fR \fIbasedir\fR\fR
141 .ad
142 .RS 26n
143 Installs the driver on the system with a root directory of \fIbasedir\fR rather
144 than installing on the system executing \fBadd_drv\fR. This option was typically
145 used in package post-installation scripts. The system using
146 \fIbasedir\fR as its root directory must reboot to complete the driver
147 installation.
148 .LP
149 Note -
150 .sp
151 .RS 2
152 The root file system of any non-global zones must not be referenced with the
153 \fB-b\fR option. Doing so might damage the global zone's file system, might
154 compromise the security of the global zone, and might damage the non-global
155 zone's file system. See \fBzones\fR(5).
156 .RE
157 .RE
159 .sp
160 .ne 2
161 .na
162 \fB\fB-c\fR \fIclass_name\fR\fR
163 .ad
164 .RS 26n
165 The driver being added to the system exports the class \fIclass_name\fR.
166 .RE
168 .sp
169 .ne 2
170 .na
171 \fB\fB-f\fR\fR
172 .ad
173 .RS 26n
174 Normally if a reconfiguration boot is required to complete the configuration of
175 the driver into the system, \fBadd_drv\fR will not add the driver. The force
176 flag forces \fBadd_drv\fR to add the driver even if a reconfiguration boot is
177 required. See the \fB-v\fR flag.
178 .RE
180 .sp
181 .ne 2
182 .na
183 \fB\fB-i\fR \fB\&'\fR\fIidentify_name\fR\fB\&'\fR\fR
184 .ad
185 .RS 26n
186 A white-space separated list of aliases for the driver \fIdevice_driver\fR.
187 .RE
189 .sp
190 .ne 2
191 .na
192 \fB\fB-m\fR \fB\&'\fR\fIpermission\fR\fB\&'\fR\fR
193 .ad
194 .RS 26n
195 Specify the file system permissions for device nodes created by the system on
196 behalf of \fIdevice_driver\fR.
197 .RE
199 .sp
200 .ne 2
201 .na
202 \fB\fB-n\fR\fR
203 .ad
204 .RS 26n
205 Do not try to load and attach \fIdevice_driver\fR, just modify the system
206 configuration files for the \fIdevice_driver\fR.
207 .RE
209 .sp
210 .ne 2
211 .na
212 \fB\fB-p\fR '\fIpolicy\fR\fB\&'\fR\fR
213 .ad
214 .RS 26n
215 Specify an additional device security policy.
216 .sp
217 The device security policy constists of several whitespace separated tokens:
218 .sp
219 .in +2
220 .nf
221 {\fIminorspec\fR {token=value}+}+
222 .fi
223 .in -2
224 .sp
226 \fIminorspec\fR is a simple wildcard pattern for a minor device. A single
227 \fB*\fR matches all minor devices. Only one \fB*\fR is allowed in the pattern.
228 .sp
229 Patterns are matched in the following order:
230 .RS +4
231 .TP
232 .ie t \(bu
233 .el o
234 entries without a wildcard
235 .RE
236 .RS +4
237 .TP
238 .ie t \(bu
239 .el o
240 entries with wildcards, longest wildcard first
241 .RE
242 The following tokens are defined: \fBread_priv_set\fR and \fBwrite_priv_set\fR.
243 \fBread_priv_set\fR defines the privileges that need to be asserted in the
244 effective set of the calling process when opening a device for reading.
245 \fBwrite_priv_set\fR defines the privileges that need to be asserted in the
246 effective set of the calling process when opening a device for writing. See
247 \fBprivileges\fR(5).
248 .sp
249 A missing minor spec is interpreted as a \fB*\fR.
250 .RE
252 .sp
253 .ne 2
254 .na
255 \fB\fB-P\fR '\fIprivilege\fR\fB\&'\fR\fI\fR\fR
256 .ad
257 .RS 26n
258 Specify additional, comma separated, privileges used by the driver. You can
259 also use specific privileges in the device's policy.
260 .RE
262 .sp
263 .ne 2
264 .na
265 \fB\fB-v\fR\fR
266 .ad
267 .RS 26n
268 The verbose flag causes \fBadd_drv\fR to provide additional information
269 regarding the success or failure of a driver's configuration into the system.
270 See the \fBEXAMPLES\fR section.
271 .RE
273 .SH EXAMPLES
274 .LP
275 \fBExample 1 \fRAdding SUNW Example Driver to the System
276 .sp
277 .LP
278 The following example adds the \fBSUNW,example\fR driver to a 32-bit system,
279 with an alias name of \fBSUNW,alias\fR. It assumes the driver has already been
280 copied to \fB/usr/kernel/drv\fR.
282 .sp
283 .in +2
284 .nf
285 example# add_drv \fB-m\fR '* 0666 bin bin','a 0644 root sys' \e
286 \fB-p\fR 'a write_priv_set=sys_config * write_priv_set=none' \e
287 \fB-i\fR 'SUNW,alias' SUNW,example
288 .fi
289 .in -2
290 .sp
292 .sp
293 .LP
294 Every minor node created by the system for the \fBSUNW,example\fR driver will
295 have the permission \fB0666\fR, and be owned by user \fBbin\fR in the group
296 \fBbin\fR, except for the minor device \fBa\fR, which will be owned by
297 \fBroot\fR, group \fBsys\fR, and have a permission of \fB0644\fR. The specified
298 device policy requires no additional privileges to open all minor nodes, except
299 minor device \fBa\fR, which requires the \fBsys_config\fR privilege when
300 opening the device for writing.
302 .LP
303 \fBExample 2 \fRAdding Driver to the Client \fB/export/root/sun1\fR
304 .sp
305 .LP
306 The following example adds the driver to the client \fB/export/root/sun1\fR.
307 The driver is installed and loaded when the client machine, \fBsun1\fR, is
308 rebooted. This second example produces the same result as the first, except the
309 changes are on the diskless client, \fBsun1\fR, and the client must be
310 rebooted for the driver to be installed.
312 .sp
313 .in +2
314 .nf
315 example# add_drv \fB-m\fR '* 0666 bin bin','a 0644 root sys' \e
316 \fB-i\fR 'SUNW,alias' -b /export/root/sun1 \e
317 SUNW,example
318 .fi
319 .in -2
320 .sp
322 .sp
323 .LP
324 See the note in the description of the \fB-b\fR option, above, specifying the
325 caveat regarding the use of this option with the Solaris zones feature.
327 .LP
328 \fBExample 3 \fRAdding Driver for a Device Already Managed by an Existing
329 Driver
330 .sp
331 .LP
332 The following example illustrates the case where a new driver is added for a
333 device that is already managed by an existing driver. Consider a device that is
334 currently managed by the driver \fBdumb_framebuffer\fR. The \fBname\fR and
335 \fBcompatible\fR properties for this device are as follows:
337 .sp
338 .in +2
339 .nf
340 name="display"
341 compatible="whizzy_framebuffer", "dumb_framebuffer"
342 .fi
343 .in -2
344 .sp
346 .sp
347 .LP
348 If \fBadd_drv\fR is used to add the \fBwhizzy_framebuffer\fR driver, the
349 following will result.
351 .sp
352 .in +2
353 .nf
354 example# add_drv whizzy_framebuffer
355 Error: Could not install driver (whizzy_framebuffer)
356 Device managed by another driver.
357 .fi
358 .in -2
359 .sp
361 .sp
362 .LP
363 If the \fB-v\fR flag is specified, the following will result.
365 .sp
366 .in +2
367 .nf
368 example# add_drv -v whizzy_framebuffer
369 Error: Could not install driver (whizzy_framebuffer)
370 Device managed by another driver.
371 Driver installation failed because the following
372 entries in /devices would be affected:
374 /devices/iommu@f,e0000000/sbus@f,e0001000/display[:*]
375 (Device currently managed by driver "dumb_framebuffer")
377 The following entries in /dev would be affected:
379 /dev/fbs/dumb_framebuffer0
380 .fi
381 .in -2
382 .sp
384 .sp
385 .LP
386 If the \fB-v\fR and \fB-f\fR flags are specified, the driver will be added
387 resulting in the following.
389 .sp
390 .in +2
391 .nf
392 example# add_drv -vf whizzy_framebuffer
393 A reconfiguration boot must be performed to complete the
394 installation of this driver.
396 The following entries in /devices will be affected:
398 /devices/iommu@f,e0000000/sbus@f,e0001000/display[:*]
399 (Device currently managed by driver "dumb_framebuffer"
401 The following entries in /dev will be affected:
403 /dev/fbs/dumb_framebuffer0
404 .fi
405 .in -2
406 .sp
408 .sp
409 .LP
410 The above example is currently only relevant to devices exporting a generic
411 device name.
413 .LP
414 \fBExample 4 \fRUse of Double Quotes in Specifying Driver Alias
415 .sp
416 .LP
417 The following example shows the use of double quotes in specifying a driver
418 alias that contains numbers.
420 .sp
421 .in +2
422 .nf
423 example# add_drv -i '"pci10c5,25"' smc
424 .fi
425 .in -2
426 .sp
428 .SH EXIT STATUS
429 .LP
430 \fBadd_drv\fR returns \fB0\fR on success and \fB1\fR on failure.
431 .SH FILES
432 .ne 2
433 .na
434 \fB\fB/kernel/drv\fR\fR
435 .ad
436 .sp .6
437 .RS 4n
438 32-bit boot device drivers
439 .RE
441 .sp
442 .ne 2
443 .na
444 \fB\fB/kernel/drv/sparcv9\fR\fR
445 .ad
446 .sp .6
447 .RS 4n
448 64-bit SPARC boot device drivers
449 .RE
451 .sp
452 .ne 2
453 .na
454 \fB\fB/kernel/drv/amd64\fR\fR
455 .ad
456 .sp .6
457 .RS 4n
458 64-bit x86 boot device drivers
459 .RE
461 .sp
462 .ne 2
463 .na
464 \fB\fB/usr/kernel/drv\fR\fR
465 .ad
466 .sp .6
467 .RS 4n
468 other 32-bit drivers that could potentially be shared between platforms
469 .RE
471 .sp
472 .ne 2
473 .na
474 \fB\fB/usr/kernel/drv/sparcv9\fR\fR
475 .ad
476 .sp .6
477 .RS 4n
478 other 64-bit SPARC drivers that could potentially be shared between platforms
479 .RE
481 .sp
482 .ne 2
483 .na
484 \fB\fB/usr/kernel/drv/amd64\fR\fR
485 .ad
486 .sp .6
487 .RS 4n
488 other 64-bit x86 drivers that could potentially be shared between platforms
489 .RE
491 .sp
492 .ne 2
493 .na
494 \fB\fB/platform/`uname\fR \fB-i`/kernel/drv\fR\fR
495 .ad
496 .sp .6
497 .RS 4n
498 32-bit platform-dependent drivers
499 .RE
501 .sp
502 .ne 2
503 .na
504 \fB\fB/platform/`uname\fR \fB-i`/kernel/drv/sparcv9\fR\fR
505 .ad
506 .sp .6
507 .RS 4n
508 64-bit SPARC platform-dependent drivers
509 .RE
511 .sp
512 .ne 2
513 .na
514 \fB\fB/platform/`uname\fR \fB-i`/kernel/drv/amd64\fR\fR
515 .ad
516 .sp .6
517 .RS 4n
518 64-bit x86 platform-dependent drivers
519 .RE
521 .sp
522 .ne 2
523 .na
524 \fB\fB/etc/driver_aliases\fR\fR
525 .ad
526 .sp .6
527 .RS 4n
528 driver aliases file
529 .RE
531 .sp
532 .ne 2
533 .na
534 \fB\fB/etc/driver_classes\fR\fR
535 .ad
536 .sp .6
537 .RS 4n
538 driver classes file
539 .RE
541 .sp
542 .ne 2
543 .na
544 \fB\fB/etc/minor_perm\fR\fR
545 .ad
546 .sp .6
547 .RS 4n
548 minor node permissions
549 .RE
551 .sp
552 .ne 2
553 .na
554 \fB\fB/etc/name_to_major\fR\fR
555 .ad
556 .sp .6
557 .RS 4n
558 major number binding
559 .RE
561 .sp
562 .ne 2
563 .na
564 \fB\fB/etc/security/device_policy\fR\fR
565 .ad
566 .sp .6
567 .RS 4n
568 device policy
569 .RE
571 .sp
572 .ne 2
573 .na
574 \fB\fB/etc/security/extra_privs\fR\fR
575 .ad
576 .sp .6
577 .RS 4n
578 device privileges
579 .RE
581 .SH SEE ALSO
582 .LP
583 \fBboot\fR(1M), \fBchmod\fR(1), \fBdevfsadm\fR(1M), \fBkernel\fR(1M),
584 \fBmodinfo\fR(1M), \fBrem_drv\fR(1M), \fBupdate_drv\fR(1M),
585 \fBdriver.conf\fR(4), \fBsystem\fR(4), \fBattributes\fR(5),
586 \fBprivileges\fR(5), \fBdevfs\fR(7FS), \fBddi_create_minor_node\fR(9F)
587 .sp
588 .LP
589 \fI\fR
590 .SH NOTES
591 .LP
592 It is possible to add a driver for a device already being managed by a
593 different driver, where the driver being added appears in the device's
594 \fBcompatible\fR list before the current driver. In such cases, a
595 reconfiguration boot is required (see \fBboot\fR(1M) and \fBkernel\fR(1M)).
596 After the reconfiguration boot, device links in \fB/dev\fR and references to
597 these files may no longer be valid (see the \fB-v\fR flag). If a
598 reconfiguration boot would be required to complete the driver installation,
599 \fBadd_drv\fR will fail unless the \fB-f\fR option is specified. See
600 \fBExample\fR \fB3\fR in the \fBEXAMPLES\fR section.
601 .sp
602 .LP
603 With the introduction of the device policy several drivers have had their minor
604 permissions changed and a device policy instated. The typical network driver
605 should use the following device policy:
606 .sp
607 .in +2
608 .nf
609 add_drv -p 'read_priv_set=net_rawaccess\e
610 write_priv_set=net_rawaccess' -m '* 666 root sys'\e
611 mynet
612 .fi
613 .in -2
614 .sp
616 .sp
617 .LP
618 This document does not constitute an API. \fB/etc/minor_perm\fR,
619 \fB/etc/name_to_major\fR, \fB/etc/driver_classes\fR, and \fB/devices\fR may not
620 exist or may have different contents or interpretations in a future release.
621 The existence of this notice does not imply that any other documentation that
622 lacks this notice constitutes an API.
623 .sp
624 .LP
625 \fB/etc/minor_perm\fR can only be updated by \fBadd_drv\fR(1M),
626 \fBrem_drv\fR(1M) or \fBupdate_drv\fR(1M).
627 .sp
628 .LP
629 In the current version of \fBadd_drv\fR, the use of double quotes to specify an
630 alias is optional when used from the command line. However, when using
631 \fBadd_drv\fR from packaging scripts, you should continue to use double quotes
632 to specify an alias.
633 .SH BUGS
634 .LP
635 Previous versions of \fBadd_drv\fR accepted a pathname for \fIdevice_driver\fR.
636 This feature is no longer supported and results in failure.