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