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