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