lib/libdevctl/devctl.3

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