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