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