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