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