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