1.\" 2.\" Copyright (c) 2014 John Baldwin <[email protected]> 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 April 4, 2019 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_reset , 42.Nm devctl_resume , 43.Nm devctl_set_driver , 44.Nm devctl_suspend , 45.Nm devctl_thaw 46.Nd device control library 47.Sh LIBRARY 48.Lb libdevctl 49.Sh SYNOPSIS 50.In devctl.h 51.Ft int 52.Fn devctl_attach "const char *device" 53.Ft int 54.Fn devctl_clear_driver "const char *device" "bool force" 55.Ft int 56.Fn devctl_delete "const char *device" "bool force" 57.Ft int 58.Fn devctl_detach "const char *device" "bool force" 59.Ft int 60.Fn devctl_disable "const char *device" "bool force_detach" 61.Ft int 62.Fn devctl_enable "const char *device" 63.Ft int 64.Fn devctl_freeze "void" 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_freeze 204function freezes probe and attach processing initiated in response to 205drivers being loaded. 206.Pp 207The 208.Fn devctl_thaw 209function resumes (thaws the freeze) probe and attach processing 210initiated in response to drivers being loaded. 211.Pp 212The 213.Fn devctl_reset 214function resets the specified device using bus-specific reset method. 215The 216.Fa detach 217argument, if true, specifies that the device driver is detached before 218the reset, and re-attached afterwards. 219If false, the device is suspended before the reset, and resumed after. 220.Sh RETURN VALUES 221.Rv -std devctl_attach devctl_clear_driver devctl_delete devctl_detach \ 222devctl_disable devctl_enable devctl_suspend devctl_rescan devctl_resume \ 223devctl_set_driver 224.Sh ERRORS 225In addition to specific errors noted below, 226all of the 227.Nm 228functions may fail for any of the errors described in 229.Xr open 2 230as well as: 231.Bl -tag -width Er 232.It Bq Er EINVAL 233The device name is too long. 234.It Bq Er ENOENT 235No existing device matches the specified name or location. 236.It Bq Er EPERM 237The current process is not permitted to adjust the state of 238.Fa device . 239.El 240.Pp 241The 242.Fn devctl_attach 243function may fail if: 244.Bl -tag -width Er 245.It Bq Er EBUSY 246The device is already attached. 247.It Bq Er ENOMEM 248An internal memory allocation request failed. 249.It Bq Er ENXIO 250The device is disabled. 251.It Bq Er ENXIO 252No suitable driver for the device could be found, 253or the driver failed to attach. 254.El 255.Pp 256The 257.Fn devctl_detach 258function may fail if: 259.Bl -tag -width Er 260.It Bq Er EBUSY 261The current device driver for 262.Fa device 263is busy and cannot detach at this time. 264Note that some drivers may return this even if 265.Fa force 266is true. 267.It Bq Er ENXIO 268The device is not attached to a driver. 269.It Bq Er ENXIO 270The current device driver for 271.Fa device 272does not support detaching. 273.El 274.Pp 275The 276.Fn devctl_enable 277function may fail if: 278.Bl -tag -width Er 279.It Bq Er EBUSY 280The device is already enabled. 281.It Bq Er ENOMEM 282An internal memory allocation request failed. 283.It Bq Er ENXIO 284No suitable driver for the device could be found, 285or the driver failed to attach. 286.El 287.Pp 288The 289.Fn devctl_disable 290function may fail if: 291.Bl -tag -width Er 292.It Bq Er EBUSY 293The current device driver for 294.Fa device 295is busy and cannot detach at this time. 296Note that some drivers may return this even if 297.Fa force_detach 298is true. 299.It Bq Er ENXIO 300The device is already disabled. 301.It Bq Er ENXIO 302The current device driver for 303.Fa device 304does not support detaching. 305.El 306.Pp 307The 308.Fn devctl_suspend 309function may fail if: 310.Bl -tag -width Er 311.It Bq Er EBUSY 312The device is already suspended. 313.It Bq Er EINVAL 314The device to be suspended is the root bus device. 315.El 316.Pp 317The 318.Fn devctl_resume 319function may fail if: 320.Bl -tag -width Er 321.It Bq Er EINVAL 322The device is not suspended. 323.It Bq Er EINVAL 324The device to be resumed is the root bus device. 325.El 326.Pp 327The 328.Fn devctl_set_driver 329function may fail if: 330.Bl -tag -width Er 331.It Bq Er EBUSY 332The device is currently attached to a device driver and 333.Fa force 334is false. 335.It Bq Er EBUSY 336The current device driver for 337.Fa device 338is busy and cannot detach at this time. 339.It Bq Er EFAULT 340The 341.Fa driver 342argument points outside the process' allocated address space. 343.It Bq Er ENOENT 344No device driver with the requested name exists. 345.It Bq Er ENOMEM 346An internal memory allocation request failed. 347.It Bq Er ENXIO 348The device is disabled. 349.It Bq Er ENXIO 350The new device driver failed to attach. 351.El 352.Pp 353The 354.Fn devctl_clear_driver 355function may fail if: 356.Bl -tag -width Er 357.It Bq Er EBUSY 358The device is currently attached to a device driver and 359.Fa force 360is false. 361.It Bq Er EBUSY 362The current device driver for 363.Fa device 364is busy and cannot detach at this time. 365.It Bq Er EINVAL 366The device is not configured for a specific device driver name. 367.It Bq Er ENXIO 368The device driver chosen after reprobing failed to attach. 369.El 370.Pp 371The 372.Fn devctl_rescan 373function may fail if: 374.Bl -tag -width Er 375.It Bq Er ENXIO 376The device is not attached to a driver. 377.It Bq Er ENXIO 378The bus driver does not support rescanning. 379.El 380.Pp 381The 382.Fn devctl_delete 383function may fail if: 384.Bl -tag -width Er 385.It Bq Er EBUSY 386The device is physically present and 387.Fa force 388is false. 389.It Bq Er EINVAL 390.Fa dev 391is the root device of the device tree. 392.El 393.Pp 394The 395.Fn devctl_reset 396function may fail if: 397.Bl -tag -width Er 398.It Bq Er ENXIO 399The bus does not implement the reset method. 400.It Bq Er ETIMEDOUT 401The device failed to respond after the reset in the time limits 402specific to the bus. 403.El 404The 405.Fn devctl_reset 406function may also return errors caused by the attach, detach, suspend, 407and resume methods of the device driver. 408.Sh SEE ALSO 409.Xr devinfo 3 , 410.Xr devstat 3 , 411.Xr devctl 8 412.Sh HISTORY 413The 414.Nm 415library first appeared in 416.Fx 10.3 . 417.Sh BUGS 418If a device is suspended individually via 419.Fn devctl_suspend 420and the entire machine is subsequently suspended, 421the device will be resumed when the machine resumes. 422.Pp 423Similarly, if the device is suspended, and 424.Fn devctl_reset 425is called on the device with 426.Fa detach 427set to 428.Va false , 429the device is resumed by the 430.Fn devctl_reset 431call. 432Or, if the driver for the device is detached manually, and 433.Fn devctl_reset 434is called on the device with 435.Fa detach 436set to 437.Va true , 438device reset re-attaches the driver. 439