xref: /freebsd/lib/libdevctl/devctl.3 (revision 9c067b844f85a224f0416e6eb46ba3ef82aec5c4)
1.\"
2.\" Copyright (c) 2014 John Baldwin <jhb@FreeBSD.org>
3.\"
4.\" Redistribution and use in source and binary forms, with or without
5.\" modification, are permitted provided that the following conditions
6.\" are met:
7.\" 1. Redistributions of source code must retain the above copyright
8.\"    notice, this list of conditions and the following disclaimer.
9.\" 2. Redistributions in binary form must reproduce the above copyright
10.\"    notice, this list of conditions and the following disclaimer in the
11.\"    documentation and/or other materials provided with the distribution.
12.\"
13.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
14.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
15.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
16.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
17.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
18.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
19.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
20.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
21.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
22.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
23.\" SUCH DAMAGE.
24.\"
25.\" $FreeBSD$
26.\"
27.Dd April 4, 2019
28.Dt DEVCTL 3
29.Os
30.Sh NAME
31.Nm devctl ,
32.Nm devctl_attach ,
33.Nm devctl_clear_driver ,
34.Nm devctl_delete ,
35.Nm devctl_detach ,
36.Nm devctl_disable ,
37.Nm devctl_enable ,
38.Nm devctl_freeze ,
39.Nm devctl_getpath ,
40.Nm devctl_rescan ,
41.Nm devctl_reset ,
42.Nm devctl_resume ,
43.Nm devctl_set_driver ,
44.Nm devctl_suspend ,
45.Nm devctl_thaw
46.Nd device control library
47.Sh LIBRARY
48.Lb libdevctl
49.Sh SYNOPSIS
50.In devctl.h
51.Ft int
52.Fn devctl_attach "const char *device"
53.Ft int
54.Fn devctl_clear_driver "const char *device" "bool force"
55.Ft int
56.Fn devctl_delete "const char *device" "bool force"
57.Ft int
58.Fn devctl_detach "const char *device" "bool force"
59.Ft int
60.Fn devctl_disable "const char *device" "bool force_detach"
61.Ft int
62.Fn devctl_enable "const char *device"
63.Ft int
64.Fn devctl_freeze "void"
65.Ft int
66.Fn devctl_getpath "const char *device" "const char *locator" "char **buffer"
67.Ft int
68.Fn devctl_rescan "const char *device"
69.Ft int
70.Fn devctl_reset "const char *device" "bool detach"
71.Ft int
72.Fn devctl_resume "const char *device"
73.Ft int
74.Fn devctl_set_driver "const char *device" "const char *driver" "bool force"
75.Ft int
76.Fn devctl_suspend "const char *device"
77.Ft int
78.Fn devctl_thaw "void"
79.Sh DESCRIPTION
80The
81.Nm
82library adjusts the state of devices in the kernel's internal device
83hierarchy.
84Each control operation accepts a
85.Fa device
86argument that identifies the device to adjust.
87The
88.Fa device
89may be specified as either the name of an existing device or as a
90bus-specific address.
91The following bus-specific address formats are currently supported:
92.Bl -tag -offset indent
93.It Sy pci Ns Fa domain Ns : Ns Fa bus Ns : Ns Fa slot Ns : Ns Fa function
94A PCI device with the specified
95.Fa domain ,
96.Fa bus ,
97.Fa slot ,
98and
99.Fa function .
100.It Sy pci Ns Fa bus Ns : Ns Fa slot Ns : Ns Fa function
101A PCI device in domain zero with the specified
102.Fa bus ,
103.Fa slot ,
104and
105.Fa function .
106.It Fa handle
107A device with an ACPI handle of
108.Fa handle .
109The handle must be specified as an absolute path and must begin with a
110.Dq \e .
111.El
112.Pp
113The
114.Fn devctl_attach
115function probes a device and attaches a suitable device driver if one is
116found.
117.Pp
118The
119.Fn devctl_detach
120function detaches a device from its current device driver.
121The device is left detached until either a new driver for its parent
122bus is loaded or the device is explicitly probed via
123.Fn devctl_attach .
124If
125.Fa force
126is true,
127the current device driver will be detached even if the device is busy.
128.Pp
129The
130.Fn devctl_delete
131function deletes a device from the device tree.
132No
133If
134.Fa force
135is true,
136the device is deleted even if the device is physically present.
137.Pp
138The
139.Fn devctl_disable
140function disables a device.
141If the device is currently attached to a device driver,
142the device driver will be detached from the device,
143but the device will retain its current name.
144If
145.Fa force_detach
146is true,
147the current device driver will be detached even if the device is busy.
148The device will remain disabled and detached until it is explicitly enabled
149via
150.Fn devctl_enable .
151.Pp
152The
153.Fn devctl_enable
154function re-enables a disabled device.
155The device will probe and attach if a suitable device driver is found.
156.Pp
157The
158.Fn devctl_suspend
159function suspends a device.
160This may include placing the device in a reduced power state,
161but any device driver currently attached to the device will remain attached.
162.Pp
163The
164.Fn devctl_resume
165function resumes a suspended device to a fully working state.
166.Pp
167The
168.Fn devctl_set_driver
169function attaches a device driver named
170.Fa driver
171to a device.
172If the device is already attached and
173.Fa force
174is false,
175the request will fail.
176If the device is already attached and
177.Fa force
178is true,
179the device will be detached from its current device driver before it is
180attached to the new device driver.
181.Pp
182The
183.Fn devctl_clear_driver
184function resets a device so that it can be attached to any valid device
185driver rather than only drivers with a previously specified name.
186This function is used to undo a previous call to
187.Fn devctl_set_driver .
188If the device is already attached and
189.Fa force
190is false,
191the request will fail.
192If the device is already attached and
193.Fa force
194is true,
195the device will be detached from its current device driver.
196After the device's name is reset,
197it is reprobed and attached to a suitable device driver if one is found.
198.Pp
199The
200.Fn devctl_rescan
201function rescans a bus device checking for devices that have been added or
202removed.
203.Pp
204The
205.Fn devctl_getpath
206retrieves the path to the
207.Fa device
208from the kernel using the
209.Fa locator
210method to construct the path.
211The
212.Fa buffer
213pointer is updated with an allocated buffer that must be freed with
214.Xr free .
215.Pp
216The
217.Fn devctl_freeze
218function freezes probe and attach processing initiated in response to
219drivers being loaded.
220.Pp
221The
222.Fn devctl_thaw
223function resumes (thaws the freeze) probe and attach processing
224initiated in response to drivers being loaded.
225.Pp
226The
227.Fn devctl_reset
228function resets the specified device using bus-specific reset method.
229The
230.Fa detach
231argument, if true, specifies that the device driver is detached before
232the reset, and re-attached afterwards.
233If false, the device is suspended before the reset, and resumed after.
234.Sh RETURN VALUES
235.Rv -std devctl_attach devctl_clear_driver devctl_delete devctl_detach \
236devctl_disable devctl_enable devctl_suspend devctl_rescan devctl_resume \
237devctl_set_driver
238.Sh ERRORS
239In addition to specific errors noted below,
240all of the
241.Nm
242functions may fail for any of the errors described in
243.Xr open 2
244as well as:
245.Bl -tag -width Er
246.It Bq Er EINVAL
247The device name is too long.
248.It Bq Er ENOENT
249No existing device matches the specified name or location.
250.It Bq Er EPERM
251The current process is not permitted to adjust the state of
252.Fa device .
253.El
254.Pp
255The
256.Fn devctl_attach
257function may fail if:
258.Bl -tag -width Er
259.It Bq Er EBUSY
260The device is already attached.
261.It Bq Er ENOMEM
262An internal memory allocation request failed.
263.It Bq Er ENXIO
264The device is disabled.
265.It Bq Er ENXIO
266No suitable driver for the device could be found,
267or the driver failed to attach.
268.El
269.Pp
270The
271.Fn devctl_detach
272function may fail if:
273.Bl -tag -width Er
274.It Bq Er EBUSY
275The current device driver for
276.Fa device
277is busy and cannot detach at this time.
278Note that some drivers may return this even if
279.Fa force
280is true.
281.It Bq Er ENXIO
282The device is not attached to a driver.
283.It Bq Er ENXIO
284The current device driver for
285.Fa device
286does not support detaching.
287.El
288.Pp
289The
290.Fn devctl_enable
291function may fail if:
292.Bl -tag -width Er
293.It Bq Er EBUSY
294The device is already enabled.
295.It Bq Er ENOMEM
296An internal memory allocation request failed.
297.It Bq Er ENXIO
298No suitable driver for the device could be found,
299or the driver failed to attach.
300.El
301.Pp
302The
303.Fn devctl_disable
304function may fail if:
305.Bl -tag -width Er
306.It Bq Er EBUSY
307The current device driver for
308.Fa device
309is busy and cannot detach at this time.
310Note that some drivers may return this even if
311.Fa force_detach
312is true.
313.It Bq Er ENXIO
314The device is already disabled.
315.It Bq Er ENXIO
316The current device driver for
317.Fa device
318does not support detaching.
319.El
320.Pp
321The
322.Fn devctl_suspend
323function may fail if:
324.Bl -tag -width Er
325.It Bq Er EBUSY
326The device is already suspended.
327.It Bq Er EINVAL
328The device to be suspended is the root bus device.
329.El
330.Pp
331The
332.Fn devctl_resume
333function may fail if:
334.Bl -tag -width Er
335.It Bq Er EINVAL
336The device is not suspended.
337.It Bq Er EINVAL
338The device to be resumed is the root bus device.
339.El
340.Pp
341The
342.Fn devctl_set_driver
343function may fail if:
344.Bl -tag -width Er
345.It Bq Er EBUSY
346The device is currently attached to a device driver and
347.Fa force
348is false.
349.It Bq Er EBUSY
350The current device driver for
351.Fa device
352is busy and cannot detach at this time.
353.It Bq Er EFAULT
354The
355.Fa driver
356argument points outside the process' allocated address space.
357.It Bq Er ENOENT
358No device driver with the requested name exists.
359.It Bq Er ENOMEM
360An internal memory allocation request failed.
361.It Bq Er ENXIO
362The device is disabled.
363.It Bq Er ENXIO
364The new device driver failed to attach.
365.El
366.Pp
367The
368.Fn devctl_clear_driver
369function may fail if:
370.Bl -tag -width Er
371.It Bq Er EBUSY
372The device is currently attached to a device driver and
373.Fa force
374is false.
375.It Bq Er EBUSY
376The current device driver for
377.Fa device
378is busy and cannot detach at this time.
379.It Bq Er EINVAL
380The device is not configured for a specific device driver name.
381.It Bq Er ENXIO
382The device driver chosen after reprobing failed to attach.
383.El
384.Pp
385The
386.Fn devctl_rescan
387function may fail if:
388.Bl -tag -width Er
389.It Bq Er ENXIO
390The device is not attached to a driver.
391.It Bq Er ENXIO
392The bus driver does not support rescanning.
393.El
394.Pp
395The
396.Fn devctl_delete
397function may fail if:
398.Bl -tag -width Er
399.It Bq Er EBUSY
400The device is physically present and
401.Fa force
402is false.
403.It Bq Er EINVAL
404.Fa dev
405is the root device of the device tree.
406.El
407.Pp
408The
409.Fn devctl_reset
410function may fail if:
411.Bl -tag -width Er
412.It Bq Er ENXIO
413The bus does not implement the reset method.
414.It Bq Er ETIMEDOUT
415The device failed to respond after the reset in the time limits
416specific to the bus.
417.El
418The
419.Fn devctl_reset
420function may also return errors caused by the attach, detach, suspend,
421and resume methods of the device driver.
422.Sh SEE ALSO
423.Xr devinfo 3 ,
424.Xr devstat 3 ,
425.Xr devctl 8
426.Sh HISTORY
427The
428.Nm
429library first appeared in
430.Fx 10.3 .
431.Sh BUGS
432If a device is suspended individually via
433.Fn devctl_suspend
434and the entire machine is subsequently suspended,
435the device will be resumed when the machine resumes.
436.Pp
437Similarly, if the device is suspended, and
438.Fn devctl_reset
439is called on the device with
440.Fa detach
441set to
442.Va false ,
443the device is resumed by the
444.Fn devctl_reset
445call.
446Or, if the driver for the device is detached manually, and
447.Fn devctl_reset
448is called on the device with
449.Fa detach
450set to
451.Va true ,
452device reset re-attaches the driver.
453