| blob | e4070bbde17175835e9d01b19a65b6272c101bab |
1 '\" te
2 .\" Copyright (c) 2009, 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 UPDATE_DRV 1M "Feb 10, 2009"
7 .SH NAME
8 update_drv \- modify device driver attributes
9 .SH SYNOPSIS
10 .LP
11 .nf
12 \fBupdate_drv\fR [\fB-f\fR | \fB-v\fR] [\fB-n\fR] \fIdriver_module\fR
13 .fi
15 .LP
16 .nf
17 \fBupdate_drv\fR [\fB-b\fR \fIbasedir\fR] [\fB-f\fR | \fB-v\fR] [\fB-n\fR] \fB-a\fR [\fB-m\fR '\fIpermission\fR']
18 [\fB-i\fR '\fIidentify-name\fR'] [\fB-P\fR '\fIprivilege\fR'] [\fB-p\fR '\fIpolicy\fR'] \fIdriver_module\fR
19 .fi
21 .LP
22 .nf
23 \fBupdate_drv\fR [\fB-b\fR \fIbasedir\fR] [\fB-f\fR | \fB-v\fR] [\fB-n\fR] \fB-d\fR [\fB-m\fR '\fIpermission\fR']
24 [\fB-i\fR '\fIidentify-name\fR'] [\fB-P\fR '\fIprivilege\fR'] [\fB-p\fR '\fIpolicy\fR'] \fIdriver_module\fR
25 .fi
27 .SH DESCRIPTION
28 .sp
29 .LP
30 The \fBupdate_drv\fR command informs the system about attribute changes to an
31 installed device driver. It can be used to re-read the \fBdriver.conf\fR(4)
32 file, or to add, modify, or delete a driver's minor node permissions or
33 aliases.
34 .sp
35 .LP
36 Without options, \fBupdate_drv\fR reloads the \fBdriver.conf\fR file.
37 .sp
38 .LP
39 Upon successfully updating the aliases, the driver binding takes effect upon
40 reconfig boot or hotplug of the device.
41 .sp
42 .LP
43 Upon successfully updating the permissions, only the new driver minor nodes get
44 created with the modified set of file permissions. Existing driver minor nodes
45 do not get modified.
46 .SH OPTIONS
47 .sp
48 .LP
49 The following options are supported:
50 .sp
51 .ne 2
52 .na
53 \fB\fB-a\fR\fR
54 .ad
55 .sp .6
56 .RS 4n
57 Add a \fIpermission\fR, \fIaliases\fR, \fIprivilege\fR or \fIpolicy\fR entry.
58 .sp
59 With the \fB-a\fR option specified, a permission entry (using the \fB-m\fR
60 option), or a driver's aliases entry (using the \fB-i\fR option), a device
61 privilege (using the \fB-P\fR option) or a a device policy (using the \fB-p\fR
62 option), can be added or updated. If a matching minor node permissions entry is
63 encountered (having the same driver name and the minor node), it is replaced.
64 If a matching aliases entry is encountered (having a different driver name and
65 the same alias), an error is reported.
66 .sp
67 The \fB-a\fR and \fB-d\fR options are mutually exclusive.
68 .RE
70 .sp
71 .ne 2
72 .na
73 \fB\fB-b\fR \fIbasedir\fR\fR
74 .ad
75 .sp .6
76 .RS 4n
77 Installs or modifies the driver on the system with a root directory of basedir
78 rather than installing on the system executing \fBupdate_drv\fR.
79 .LP
80 Note -
81 .sp
82 .RS 2
83 The root file system of any non-global zones must not be referenced with the
84 \fB-b\fR option. Doing so might damage the global zone's file system, might
85 compromise the security of the global zone, and might damage the non-global
86 zone's file system. See \fBzones\fR(5).
87 .RE
88 .RE
90 .sp
91 .ne 2
92 .na
93 \fB\fB-d\fR\fR
94 .ad
95 .sp .6
96 .RS 4n
97 Delete a \fIpermission\fR, \fIaliases\fR, \fIprivilege\fR or \fIpolicy\fR
98 entry.
99 .sp
100 The \fB-m\fR \fIpermission\fR, \fB-i\fR \fIidentify-name\fR, \fB-P\fR
101 \fIprivilege\fR or the \fB-p\fR \fIpolicy\fR option needs to be specified with
102 the \fB-d\fR option.
103 .sp
104 The \fB-d\fR and \fB-a\fR options are mutually exclusive.
105 .sp
106 If the entry doesn't exist \fBupdate_drv\fR returns an error.
107 .RE
109 .sp
110 .ne 2
111 .na
112 \fB\fB-f\fR\fR
113 .ad
114 .sp .6
115 .RS 4n
116 Force the system to reread the \fBdriver.conf\fR file even if the driver module
117 cannot be unloaded. See \fBNOTES\fR section for details.
118 .sp
119 \fBWithout\fR this option, when removing an alias for a driver,
120 \fBupdate_drv\fR updates the binding files for the next boot, but returns an
121 error if one or more devices that reference the driver-alias binding remains.
122 \fBWith\fR the \fB-f\fR option, \fBupdate_drv\fR does not return an error if
123 such devices remain.
124 .RE
126 .sp
127 .ne 2
128 .na
129 \fB\fB-i\fR '\fIidentify-name\fR'\fR
130 .ad
131 .sp .6
132 .RS 4n
133 A white-space separated list of aliases for the driver. If \fB-a\fR or \fB-d\fR
134 option is not specified then this option is ignored. The \fIidentify-name\fR
135 string is mandatory. If all aliases need to be removed, \fBrem_drv\fR(1M) is
136 recommended.
137 .RE
139 .sp
140 .ne 2
141 .na
142 \fB\fB-m\fR '\fIpermission\fR'\fR
143 .ad
144 .sp .6
145 .RS 4n
146 Specify a white-space separated list of file system permissions for the device
147 node of the device driver. If \fB-a\fR or \fB-d\fR option is not specified
148 then, this option is ignored. The permission string is mandatory.
149 .RE
151 .sp
152 .ne 2
153 .na
154 \fB\fB-n\fR\fR
155 .ad
156 .sp .6
157 .RS 4n
158 Do not try to load and attach \fIdevice_driver\fR, just modify the system
159 configuration files for that driver.
160 .RE
162 .sp
163 .ne 2
164 .na
165 \fB\fB-p\fR '\fIpolicy\fR'\fR
166 .ad
167 .sp .6
168 .RS 4n
169 With the \fB-a\fR option, policy is a white-space separated list of complete
170 device policies. For the \fB-d\fR option, policy is a white space separated
171 list of minor device specifications. The minor device specifications are
172 matched exactly against the entries in \fB/etc/security/device_policy\fR, that
173 is., no wildcard matching is performed.
174 .RE
176 .sp
177 .ne 2
178 .na
179 \fB\fB-P\fR '\fIprivilege\fR'\fR
180 .ad
181 .sp .6
182 .RS 4n
183 With the \fB-a\fR option, privilege is a comma separated list of additional
184 driver privileges. For the \fB-d\fR option, privilege is a single privilege.
185 The privileges are added to or removed from the \fB/etc/security/extra_privs\fR
186 file.
187 .RE
189 .sp
190 .ne 2
191 .na
192 \fB\fB-v\fR\fR
193 .ad
194 .sp .6
195 .RS 4n
196 Verbose.
197 .RE
199 .SH EXAMPLES
200 .LP
201 \fBExample 1 \fRAdding or Modifying an Existing Minor Permissions Entry
202 .sp
203 .LP
204 The following command adds or modifies the exisitng minor permissions entry of
205 the \fBclone\fR driver:
207 .sp
208 .in +2
209 .nf
210 example# update_drv -a -m 'llc1 777 joe staff' clone
211 .fi
212 .in -2
213 .sp
215 .LP
216 \fBExample 2 \fRRemoving All Minor Permissions Entries
217 .sp
218 .LP
219 The following command removes all minor permission entries of the \fBusbprn\fR
220 driver, the USB printer driver:
222 .sp
223 .in +2
224 .nf
225 example# update_drv -d -m '* 0666 root sys' usbprn
226 .fi
227 .in -2
228 .sp
230 .LP
231 \fBExample 3 \fRAdding a Driver Aliases Entry
232 .sp
233 .LP
234 The following command adds a driver aliases entry of the \fBugen\fR driver with
235 the identity string of \fBusb459,20\fR:
237 .sp
238 .in +2
239 .nf
240 example# update_drv -a -i '"usb459,20"' ugen
241 .fi
242 .in -2
243 .sp
245 .LP
246 \fBExample 4 \fRRe-reading the \fBdriver.conf\fR File For the \fBohci\fR Driver
247 .sp
248 .LP
249 The following command re-reads the \fBdriver.conf\fR(4) file.
251 .sp
252 .in +2
253 .nf
254 example# update_drv ohci
255 .fi
256 .in -2
257 .sp
259 .LP
260 \fBExample 5 \fRRequiring a Self-defined Privilege to Open a tcp Socket
261 .sp
262 .LP
263 The following command requires a self-defined privilege to open a tcp socket:
265 .sp
266 .in +2
267 .nf
268 example# update_drv -a -P net_tcp -p \e
269 'write_priv_set=net_tcp read_priv_set=net_tcp' tcp
270 .fi
271 .in -2
272 .sp
274 .LP
275 \fBExample 6 \fREstablishing a Path-oriented Alias
276 .sp
277 .LP
278 The following command establishes a path-oriented alias to force a specific
279 driver, \fBqlt\fR, to be used for a particular device path:
281 .sp
282 .in +2
283 .nf
284 example# update_drv -a -i '"/pci@8,600000/SUNW,qlc@4"' qlt
285 .fi
286 .in -2
287 .sp
289 .SH EXIT STATUS
290 .sp
291 .LP
292 The following exit values are returned:
293 .sp
294 .ne 2
295 .na
296 \fB\fB0\fR\fR
297 .ad
298 .sp .6
299 .RS 4n
300 Successful completion.
301 .RE
303 .sp
304 .ne 2
305 .na
306 \fB>\fB0\fR\fR
307 .ad
308 .sp .6
309 .RS 4n
310 An error occurred.
311 .RE
313 .SH SEE ALSO
314 .sp
315 .LP
316 \fBadd_drv\fR(1M), \fBmodunload\fR(1M), \fBrem_drv\fR(1M),
317 \fBdriver.conf\fR(4), \fBattributes\fR(5), \fBprivileges\fR(5)
318 .SH NOTES
319 .sp
320 .LP
321 If \fB-a\fR or \fB-d\fR options are specified, \fBupdate_drv\fR does not reread
322 the \fBdriver.conf\fR file.
323 .sp
324 .LP
325 A forced update of the \fBdriver.conf\fR file reloads the \fBdriver.conf\fR
326 file without reloading the driver binary module. In this case, devices which
327 cannot be detached reference driver global properties from the old
328 \fBdriver.conf\fR file, while the remaining driver instances reference global
329 properties in the new \fBdriver.conf\fR file.
330 .sp
331 .LP
332 It is possible to add an alias , which changes the driver binding of a device
333 already being managed by a different driver. A force update with the \fB-a\fR
334 option tries to bind to the new driver and report error if it cannot. If you
335 specify more than one of the \fB-m\fR, \fB-i\fR, \fB-P\fR or \fB-p\fR options,
336 a force flag tries to modify aliases or permissions. This is done even if the
337 other operation fails and vice-versa.