1add_drv(1M) System Administration Commands add_drv(1M)
2
3
4
6 add_drv - add a new device driver to the system
7
9 add_drv [-b basedir] [-c class_name]
10 [-i 'identify_name...'] [-m 'permission','...']
11 [-p 'policy'] [-P privilege] [-n] [-f] [-v] device_driver
12
13
15 The add_drv command is used to inform the system about newly installed
16 device drivers.
17
18
19 Each device on the system has a name associated with it. This name is
20 represented by the name property for the device. Similarly, the device
21 may also have a list of driver names associated with it. This list is
22 represented by the compatible property for the device.
23
24
25 The system determines which devices will be managed by the driver being
26 added by examining the contents of the name property and the compatible
27 property (if it exists) on each device. If the value in the name prop‐
28 erty does not match the driver being added, each entry in the compati‐
29 ble property is tried, in order, until either a match occurs or there
30 are no more entries in the compatible property.
31
32
33 In some cases, adding a new driver may require a reconfiguration boot.
34 See the NOTES section.
35
36
37 Aliases might require quoting (with double-quotes) if they contain num‐
38 bers. See EXAMPLES.
39
40 The /etc/minor_perm File
41 add_drv and update_drv(1M) read the /etc/minor_perm file to obtain per‐
42 mission information. The permission specified is applied to matching
43 minor nodes created when a device bound to the driver is attached. A
44 minor node's permission may be manually changed by chmod(1). For such
45 nodes, the specified permissions apply, overriding the default per‐
46 missions specified via add_drv or update_drv(1M).
47
48
49 The format of the /etc/minor_perm file is as follows:
50
51 name:minor_name permissions owner group
52
53
54
55
56 minor_name may be the actual name of the minor node, or contain shell
57 metacharacters to represent several minor nodes (see sh(1)).
58
59
60 For example:
61
62 sd:* 0640 root sys
63 zs:[a-z],cu 0600 uucp uucp
64 mm:kmem 0640 root bin
65
66
67
68
69 The first line sets all devices exported by the sd node to 0640 permis‐
70 sions, owned by root, with group sys. In the second line, devices such
71 as a,cu and z,cu exported by the zs driver are set to 0600 permission,
72 owned by uucp, with group uucp. In the third line the kmem device
73 exported by the mm driver is set to 0640 permission, owned by root,
74 with group bin.
75
76 Running add_drv from a postinstall Script
77 When running add_drv from within the context of a package's postinstall
78 script, you must consider whether the package is being added to a sys‐
79 tem image or to a running system. When a package is being installed on
80 a system image, such as occurs with the Live Upgrade or flash features
81 (see live_upgrade(5) and flarcreate(1M)), the BASEDIR variable refers
82 to the image's base directory. In this situation, add_drv should be
83 invoked with -b $BASEDIR. This causes add_drv only to update the
84 image's system files; a reboot of the system or client would be
85 required to make the driver operational.
86
87
88 When a package is being installed on the running system itself, the
89 system files need to be updated, as in the case above. However, the
90 running kernel can be informed of the existence of the new driver with‐
91 out requiring a reboot. To accomplish this, the postinstall script must
92 invoke add_drv without the -b option. Accordingly, postinstall scripts
93 invoking add_drv should be written thusly:
94
95 if [ "${BASEDIR:=/}" = "/" ]
96 then
97 ADD_DRV="add_drv"
98 else
99 ADD_DRV="add_drv -b ${BASEDIR}"
100 fi
101 $ADD_DRV [<options>] <driver>
102
103
104
105
106 ...or, alternatively:
107
108 if [ "${BASEDIR:=/}" != "/" ]
109 then
110 BASEDIR_OPT="-b $BASEDIR"
111 fi
112 add_drv $BASEDIR_OPT [<options>] <driver>
113
114
115
116
117 The -b option is described below.
118
120 -b basedir Installs the driver on the system with a root
121 directory of basedir rather than installing
122 on the system executing add_drv. This option
123 is typically used in package post-installa‐
124 tion scripts when the package is not being
125 installed on the system executing the pkgadd
126 command. The system using basedir as its root
127 directory must reboot to complete the driver
128 installation.
129
130 Note -
131
132 The root file system of any non-global
133 zones must not be referenced with the -b
134 option. Doing so might damage the global
135 zone's file system, might compromise the
136 security of the global zone, and might dam‐
137 age the non-global zone's file system. See
138 zones(5).
139
140
141 -c class_name The driver being added to the system exports
142 the class class_name.
143
144
145 -f Normally if a reconfiguration boot is
146 required to complete the configuration of the
147 driver into the system, add_drv will not add
148 the driver. The force flag forces add_drv to
149 add the driver even if a reconfiguration boot
150 is required. See the -v flag.
151
152
153 -i 'identify_name' A white-space separated list of aliases for
154 the driver device_driver.
155
156
157 -m 'permission' Specify the file system permissions for
158 device nodes created by the system on behalf
159 of device_driver.
160
161
162 -n Do not try to load and attach device_driver,
163 just modify the system configuration files
164 for the device_driver.
165
166
167 -p 'policy' Specify an additional device security policy.
168
169 The device security policy constists of sev‐
170 eral whitespace separated tokens:
171
172 {minorspec {token=value}+}+
173
174
175 minorspec is a simple wildcard pattern for a
176 minor device. A single * matches all minor
177 devices. Only one * is allowed in the pat‐
178 tern.
179
180 Patterns are matched in the following order:
181
182 o entries without a wildcard
183
184 o entries with wildcards, longest
185 wildcard first
186 The following tokens are defined:
187 read_priv_set and write_priv_set.
188 read_priv_set defines the privileges that
189 need to be asserted in the effective set of
190 the calling process when opening a device for
191 reading. write_priv_set defines the privi‐
192 leges that need to be asserted in the effec‐
193 tive set of the calling process when opening
194 a device for writing. See privileges(5).
195
196 A missing minor spec is interpreted as a *.
197
198
199 -P 'privilege' Specify additional, comma separated, privi‐
200 leges used by the driver. You can also use
201 specific privileges in the device's policy.
202
203
204 -v The verbose flag causes add_drv to provide
205 additional information regarding the success
206 or failure of a driver's configuration into
207 the system. See the EXAMPLES section.
208
209
211 Example 1 Adding SUNW Example Driver to the System
212
213
214 The following example adds the SUNW,example driver to a 32-bit system,
215 with an alias name of SUNW,alias. It assumes the driver has already
216 been copied to /usr/kernel/drv.
217
218
219 example# add_drv -m '* 0666 bin bin','a 0644 root sys' \
220 -p 'a write_priv_set=sys_config * write_priv_set=none' \
221 -i 'SUNW,alias' SUNW,example
222
223
224
225
226 Every minor node created by the system for the SUNW,example driver will
227 have the permission 0666, and be owned by user bin in the group bin,
228 except for the minor device a, which will be owned by root, group sys,
229 and have a permission of 0644. The specified device policy requires no
230 additional privileges to open all minor nodes, except minor device a,
231 which requires the sys_config privilege when opening the device for
232 writing.
233
234
235 Example 2 Adding Driver to the Client /export/root/sun1
236
237
238 The following example adds the driver to the client /export/root/sun1.
239 The driver is installed and loaded when the client machine, sun1, is
240 rebooted. This second example produces the same result as the first,
241 except the changes are on the diskless client, sun1, and the client
242 must be rebooted for the driver to be installed.
243
244
245 example# add_drv -m '* 0666 bin bin','a 0644 root sys' \
246 -i 'SUNW,alias' -b /export/root/sun1 \
247 SUNW,example
248
249
250
251
252 See the note in the description of the -b option, above, specifying the
253 caveat regarding the use of this option with the Solaris zones feature.
254
255
256 Example 3 Adding Driver for a Device Already Managed by an Existing
257 Driver
258
259
260 The following example illustrates the case where a new driver is added
261 for a device that is already managed by an existing driver. Consider a
262 device that is currently managed by the driver dumb_framebuffer. The
263 name and compatible properties for this device are as follows:
264
265
266 name="display"
267 compatible="whizzy_framebuffer", "dumb_framebuffer"
268
269
270
271
272 If add_drv is used to add the whizzy_framebuffer driver, the following
273 will result.
274
275
276 example# add_drv whizzy_framebuffer
277 Error: Could not install driver (whizzy_framebuffer)
278 Device managed by another driver.
279
280
281
282
283 If the -v flag is specified, the following will result.
284
285
286 example# add_drv -v whizzy_framebuffer
287 Error: Could not install driver (whizzy_framebuffer)
288 Device managed by another driver.
289 Driver installation failed because the following
290 entries in /devices would be affected:
291
292 /devices/iommu@f,e0000000/sbus@f,e0001000/display[:*]
293 (Device currently managed by driver "dumb_framebuffer")
294
295 The following entries in /dev would be affected:
296
297 /dev/fbs/dumb_framebuffer0
298
299
300
301
302 If the -v and -f flags are specified, the driver will be added result‐
303 ing in the following.
304
305
306 example# add_drv -vf whizzy_framebuffer
307 A reconfiguration boot must be performed to complete the
308 installation of this driver.
309
310 The following entries in /devices will be affected:
311
312 /devices/iommu@f,e0000000/sbus@f,e0001000/display[:*]
313 (Device currently managed by driver "dumb_framebuffer"
314
315 The following entries in /dev will be affected:
316
317 /dev/fbs/dumb_framebuffer0
318
319
320
321
322 The above example is currently only relevant to devices exporting a
323 generic device name.
324
325
326 Example 4 Use of Double Quotes in Specifying Driver Alias
327
328
329 The following example shows the use of double quotes in specifying a
330 driver alias that contains numbers.
331
332
333 example# add_drv -i '"pci10c5,25"' smc
334
335
336
338 add_drv returns 0 on success and 1 on failure.
339
341 /kernel/drv
342
343 32-bit boot device drivers
344
345
346 /kernel/drv/sparcv9
347
348 64-bit SPARC boot device drivers
349
350
351 /kernel/drv/amd64
352
353 64-bit x86 boot device drivers
354
355
356 /usr/kernel/drv
357
358 other 32-bit drivers that could potentially be shared between plat‐
359 forms
360
361
362 /usr/kernel/drv/sparcv9
363
364 other 64-bit SPARC drivers that could potentially be shared between
365 platforms
366
367
368 /usr/kernel/drv/amd64
369
370 other 64-bit x86 drivers that could potentially be shared between
371 platforms
372
373
374 /platform/`uname -i`/kernel/drv
375
376 32-bit platform-dependent drivers
377
378
379 /platform/`uname -i`/kernel/drv/sparcv9
380
381 64-bit SPARC platform-dependent drivers
382
383
384 /platform/`uname -i`/kernel/drv/amd64
385
386 64-bit x86 platform-dependent drivers
387
388
389 /etc/driver_aliases
390
391 driver aliases file
392
393
394 /etc/driver_classes
395
396 driver classes file
397
398
399 /etc/minor_perm
400
401 minor node permissions
402
403
404 /etc/name_to_major
405
406 major number binding
407
408
409 /etc/security/device_policy
410
411 device policy
412
413
414 /etc/security/extra_privs
415
416 device privileges
417
418
420 See attributes(5) for descriptions of the following attributes:
421
422
423
424
425 ┌─────────────────────────────┬─────────────────────────────┐
426 │ ATTRIBUTE TYPE │ ATTRIBUTE VALUE │
427 ├─────────────────────────────┼─────────────────────────────┤
428 │Availability │SUNWcsu │
429 └─────────────────────────────┴─────────────────────────────┘
430
432 boot(1M), chmod(1), devfsadm(1M), flarcreate(1M), kernel(1M), mod‐
433 info(1M), rem_drv(1M), update_drv(1M), driver.conf(4), system(4),
434 attributes(5), live_upgrade(5), privileges(5), devfs(7FS), ddi_cre‐
435 ate_minor_node(9F)
436
437
438
439
441 It is possible to add a driver for a device already being managed by a
442 different driver, where the driver being added appears in the device's
443 compatible list before the current driver. In such cases, a reconfigu‐
444 ration boot is required (see boot(1M) and kernel(1M)). After the recon‐
445 figuration boot, device links in /dev and references to these files may
446 no longer be valid (see the -v flag). If a reconfiguration boot would
447 be required to complete the driver installation, add_drv will fail
448 unless the -f option is specified. See Example 3 in the EXAMPLES sec‐
449 tion.
450
451
452 With the introduction of the device policy several drivers have had
453 their minor permissions changed and a device policy instated. The typi‐
454 cal network driver should use the following device policy:
455
456 add_drv -p 'read_priv_set=net_rawaccess\
457 write_priv_set=net_rawaccess' -m '* 666 root sys'\
458 mynet
459
460
461
462
463 This document does not constitute an API. /etc/minor_perm,
464 /etc/name_to_major, /etc/driver_classes, and /devices may not exist or
465 may have different contents or interpretations in a future release. The
466 existence of this notice does not imply that any other documentation
467 that lacks this notice constitutes an API.
468
469
470 /etc/minor_perm can only be updated by add_drv(1M), rem_drv(1M) or
471 update_drv(1M).
472
473
474 In the current version of add_drv, the use of double quotes to specify
475 an alias is optional when used from the command line. However, when
476 using add_drv from packaging scripts, you should continue to use double
477 quotes to specify an alias.
478
480 Previous versions of add_drv accepted a pathname for device_driver.
481 This feature is no longer supported and results in failure.
482
483
484
485SunOS 5.11 1 Dec 2005 add_drv(1M)