1add_drv(1M)             System Administration Commands             add_drv(1M)
2
3
4

NAME

6       add_drv - add a new device driver to the system
7

SYNOPSIS

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

DESCRIPTION

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

OPTIONS

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

EXAMPLES

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

EXIT STATUS

338       add_drv returns 0 on success and 1 on failure.
339

FILES

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

ATTRIBUTES

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

SEE ALSO

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

NOTES

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

BUGS

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)
Impressum