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