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