xref: /freebsd/lib/libdevctl/devctl.3 (revision 7a0c41d5d7d4e9770ef6f5d56f893efc8f18ab7c) 
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 April 27, 2016
29.Dt DEVCTL 3
30.Os
31.Sh NAME
32.Nm devctl ,
33.Nm devctl_attach ,
34.Nm devctl_delete ,
35.Nm devctl_detach ,
36.Nm devctl_disable ,
37.Nm devctl_enable ,
38.Nm devctl_rescan ,
39.Nm devctl_resume ,
40.Nm devctl_set_driver ,
41.Nm devctl_suspend
42.Nd device control library
43.Sh LIBRARY
44.Lb libdevctl
45.Sh SYNOPSIS
46.In devctl.h
47.Ft int
48.Fn devctl_attach "const char *device"
49.Ft int
50.Fn devctl_delete "const char *device" "bool force"
51.Ft int
52.Fn devctl_detach "const char *device" "bool force"
53.Ft int
54.Fn devctl_disable "const char *device" "bool force_detach"
55.Ft int
56.Fn devctl_enable "const char *device"
57.Ft int
58.Fn devctl_rescan "const char *device"
59.Ft int
60.Fn devctl_resume "const char *device"
61.Ft int
62.Fn devctl_set_driver "const char *device" "const char *driver" "bool force"
63.Ft int
64.Fn devctl_suspend "const char *device"
65.Sh DESCRIPTION
66The
67.Nm
68library adjusts the state of devices in the kernel's internal device
69hierarchy.
70Each control operation accepts a
71.Fa device
72argument that identifies the device to adjust.
73The
74.Fa device
75may be specified as either the name of an existing device or as a
76bus-specific address.
77The following bus-specific address formats are currently supported:
78.Bl -tag -offset indent
79.It Sy pci Ns Fa domain Ns : Ns Fa bus Ns : Ns Fa slot Ns : Ns Fa function
80A PCI device with the specified
81.Fa domain ,
82.Fa bus ,
83.Fa slot ,
84and
85.Fa function .
86.It Sy pci Ns Fa bus Ns : Ns Fa slot Ns : Ns Fa function
87A PCI device in domain zero with the specified
88.Fa bus ,
89.Fa slot ,
90and
91.Fa function .
92.It Fa handle
93A device with an ACPI handle of
94.Fa handle .
95The handle must be specified as an absolute path and must begin with a
96.Dq \e .
97.El
98.Pp
99The
100.Fn devctl_attach
101function probes a device and attaches a suitable device driver if one is
102found.
103.Pp
104The
105.Fn devctl_detach
106function detaches a device from its current device driver.
107The device is left detached until either a new driver for its parent
108bus is loaded or the device is explicitly probed via
109.Fn devctl_attach .
110If
111.Fa force
112is true,
113the current device driver will be detached even if the device is busy.
114.Pp
115The
116.Fn devctl_delete
117function deletes a device from the device tree.
118No
119If
120.Fa force
121is true,
122the device is deleted even if the device is physically present.
123.Pp
124The
125.Fn devctl_disable
126function disables a device.
127If the device is currently attached to a device driver,
128the device driver will be detached from the device,
129but the device will retain its current name.
130If
131.Fa force_detach
132is true,
133the current device driver will be detached even if the device is busy.
134The device will remain disabled and detached until it is explicitly enabled
135via
136.Fn devctl_enable .
137.Pp
138The
139.Fn devctl_enable
140function re-enables a disabled device.
141The device will probe and attach if a suitable device driver is found.
142.Pp
143The
144.Fn devctl_suspend
145function suspends a device.
146This may include placing the device in a reduced power state,
147but any device driver currently attached to the device will remain attached.
148.Pp
149The
150.Fn devctl_resume
151function resumes a suspended device to a fully working state.
152.Pp
153The
154.Fn devctl_set_driver
155function attaches a device driver named
156.Fa driver
157to a device.
158If the device is already attached and
159.Fa force
160is false,
161the request will fail.
162If the device is already attached and
163.Fa force
164is true,
165the device will be detached from its current device driver before it is
166attached to the new device driver.
167.Pp
168The
169.Fn devctl_rescan
170function rescans a bus device checking for devices that have been added or
171removed.
172.Sh RETURN VALUES
173.Rv -std devctl_attach devctl_delete devctl_detach devctl_disable \
174devctl_enable devctl_suspend devctl_rescan devctl_resume devctl_set_driver
175.Sh ERRORS
176In addition to specific errors noted below,
177all of the
178.Nm
179functions may fail for any of the errors described in
180.Xr open 2
181as well as:
182.Bl -tag -width Er
183.It Bq Er EINVAL
184The device name is too long.
185.It Bq Er ENOENT
186No existing device matches the specified name or location.
187.It Bq Er EPERM
188The current process is not permitted to adjust the state of
189.Fa device .
190.El
191.Pp
192The
193.Fn devctl_attach
194function may fail if:
195.Bl -tag -width Er
196.It Bq Er EBUSY
197The device is already attached.
198.It Bq Er ENOMEM
199An internal memory allocation request failed.
200.It Bq Er ENXIO
201The device is disabled.
202.It Bq Er ENXIO
203No suitable driver for the device could be found,
204or the driver failed to attach.
205.El
206.Pp
207The
208.Fn devctl_detach
209function may fail if:
210.Bl -tag -width Er
211.It Bq Er EBUSY
212The current device driver for
213.Fa device
214is busy and cannot detach at this time.
215Note that some drivers may return this even if
216.Fa force
217is true.
218.It Bq Er ENXIO
219The device is not attached to a driver.
220.It Bq Er ENXIO
221The current device driver for
222.Fa device
223does not support detaching.
224.El
225.Pp
226The
227.Fn devctl_enable
228function may fail if:
229.Bl -tag -width Er
230.It Bq Er EBUSY
231The device is already enabled.
232.It Bq Er ENOMEM
233An internal memory allocation request failed.
234.It Bq Er ENXIO
235No suitable driver for the device could be found,
236or the driver failed to attach.
237.El
238.Pp
239The
240.Fn devctl_disable
241function may fail if:
242.Bl -tag -width Er
243.It Bq Er EBUSY
244The current device driver for
245.Fa device
246is busy and cannot detach at this time.
247Note that some drivers may return this even if
248.Fa force_detach
249is true.
250.It Bq Er ENXIO
251The device is already disabled.
252.It Bq Er ENXIO
253The current device driver for
254.Fa device
255does not support detaching.
256.El
257.Pp
258The
259.Fn devctl_suspend
260function may fail if:
261.Bl -tag -width Er
262.It Bq Er EBUSY
263The device is already suspended.
264.It Bq Er EINVAL
265The device to be suspended is the root bus device.
266.El
267.Pp
268The
269.Fn devctl_resume
270function may fail if:
271.Bl -tag -width Er
272.It Bq Er EINVAL
273The device is not suspended.
274.It Bq Er EINVAL
275The device to be resumed is the root bus device.
276.El
277.Pp
278The
279.Fn devctl_set_driver
280function may fail if:
281.Bl -tag -width Er
282.It Bq Er EBUSY
283The device is currently attached to a device driver and
284.Fa force
285is false.
286.It Bq Er EBUSY
287The current device driver for
288.Fa device
289is busy and cannot detach at this time.
290.It Bq Er EFAULT
291The
292.Fa driver
293argument points outside the process' allocated address space.
294.It Bq Er ENOENT
295No device driver with the requested name exists.
296.It Bq Er ENOMEM
297An internal memory allocation request failed.
298.It Bq Er ENXIO
299The device is disabled.
300.It Bq Er ENXIO
301The new device driver failed to attach.
302.El
303.Pp
304The
305.Fn devctl_rescan
306function may fail if:
307.Bl -tag -width Er
308.It Bq Er ENXIO
309The device is not attached to a driver.
310.It Bq Er ENXIO
311The bus driver does not support rescanning.
312.El
313.Pp
314The
315.Fn devctl_delete
316function may fail if:
317.Bl -tag -width Er
318.It Bq Er EBUSY
319The device is physically present and
320.Fa force
321is false.
322.It Bq Er EINVAL
323.Fa dev
324is the root device of the device tree.
325.El
326.Sh SEE ALSO
327.Xr devinfo 3 ,
328.Xr devstat 3 ,
329.Xr devctl 8
330.Sh HISTORY
331The
332.Nm
333library first appeared in
334.Fx 10.3 .
335.Sh BUGS
336If a device is suspended individually via
337.Fn devctl_suspend
338and the entire machine is subsequently suspended,
339the device will be resumed when the machine resumes.
340