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