lib/libdevctl/devctl.3

   1 .\"
   2 .\" Copyright (c) 2014 John Baldwin <jhb@FreeBSD.org>
   3 .\" All rights reserved.
   4 .\"
   5 .\" Redistribution and use in source and binary forms, with or without
   6 .\" modification, are permitted provided that the following conditions
   7 .\" are met:
   8 .\" 1. Redistributions of source code must retain the above copyright
   9 .\"    notice, this list of conditions and the following disclaimer.
  10 .\" 2. Redistributions in binary form must reproduce the above copyright
  11 .\"    notice, this list of conditions and the following disclaimer in the
  12 .\"    documentation and/or other materials provided with the distribution.
  13 .\"
  14 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
  15 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  16 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  17 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
  18 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  19 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  20 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  21 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  22 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  23 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  24 .\" SUCH DAMAGE.
  25 .\"
  26 .\" $FreeBSD$
  27 .\"
  28 .Dd April 4, 2019
  29 .Dt DEVCTL 3
  30 .Os
  31 .Sh NAME
  32 .Nm devctl ,
  33 .Nm devctl_attach ,
  34 .Nm devctl_clear_driver ,
  35 .Nm devctl_delete ,
  36 .Nm devctl_detach ,
  37 .Nm devctl_disable ,
  38 .Nm devctl_enable ,
  39 .Nm devctl_freeze ,
  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_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_freeze
 204 function freezes probe and attach processing initiated in response to
 205 drivers being loaded.
 206 .Pp
 207 The
 208 .Fn devctl_thaw
 209 function resumes (thaws the freeze) probe and attach processing
 210 initiated in response to drivers being loaded.
 211 .Pp
 212 The
 213 .Fn devctl_reset
 214 function resets the specified device using bus-specific reset method.
 215 The
 216 .Fa detach
 217 argument, if true, specifies that the device driver is detached before
 218 the reset, and re-attached afterwards.
 219 If false, the device is suspended before the reset, and resumed after.
 220 .Sh RETURN VALUES
 221 .Rv -std devctl_attach devctl_clear_driver devctl_delete devctl_detach \
 222 devctl_disable devctl_enable devctl_suspend devctl_rescan devctl_resume \
 223 devctl_set_driver
 224 .Sh ERRORS
 225 In addition to specific errors noted below,
 226 all of the
 227 .Nm
 228 functions may fail for any of the errors described in
 229 .Xr open 2
 230 as well as:
 231 .Bl -tag -width Er
 232 .It Bq Er EINVAL
 233 The device name is too long.
 234 .It Bq Er ENOENT
 235 No existing device matches the specified name or location.
 236 .It Bq Er EPERM
 237 The current process is not permitted to adjust the state of
 238 .Fa device .
 239 .El
 240 .Pp
 241 The
 242 .Fn devctl_attach
 243 function may fail if:
 244 .Bl -tag -width Er
 245 .It Bq Er EBUSY
 246 The device is already attached.
 247 .It Bq Er ENOMEM
 248 An internal memory allocation request failed.
 249 .It Bq Er ENXIO
 250 The device is disabled.
 251 .It Bq Er ENXIO
 252 No suitable driver for the device could be found,
 253 or the driver failed to attach.
 254 .El
 255 .Pp
 256 The
 257 .Fn devctl_detach
 258 function may fail if:
 259 .Bl -tag -width Er
 260 .It Bq Er EBUSY
 261 The current device driver for
 262 .Fa device
 263 is busy and cannot detach at this time.
 264 Note that some drivers may return this even if
 265 .Fa force
 266 is true.
 267 .It Bq Er ENXIO
 268 The device is not attached to a driver.
 269 .It Bq Er ENXIO
 270 The current device driver for
 271 .Fa device
 272 does not support detaching.
 273 .El
 274 .Pp
 275 The
 276 .Fn devctl_enable
 277 function may fail if:
 278 .Bl -tag -width Er
 279 .It Bq Er EBUSY
 280 The device is already enabled.
 281 .It Bq Er ENOMEM
 282 An internal memory allocation request failed.
 283 .It Bq Er ENXIO
 284 No suitable driver for the device could be found,
 285 or the driver failed to attach.
 286 .El
 287 .Pp
 288 The
 289 .Fn devctl_disable
 290 function may fail if:
 291 .Bl -tag -width Er
 292 .It Bq Er EBUSY
 293 The current device driver for
 294 .Fa device
 295 is busy and cannot detach at this time.
 296 Note that some drivers may return this even if
 297 .Fa force_detach
 298 is true.
 299 .It Bq Er ENXIO
 300 The device is already disabled.
 301 .It Bq Er ENXIO
 302 The current device driver for
 303 .Fa device
 304 does not support detaching.
 305 .El
 306 .Pp
 307 The
 308 .Fn devctl_suspend
 309 function may fail if:
 310 .Bl -tag -width Er
 311 .It Bq Er EBUSY
 312 The device is already suspended.
 313 .It Bq Er EINVAL
 314 The device to be suspended is the root bus device.
 315 .El
 316 .Pp
 317 The
 318 .Fn devctl_resume
 319 function may fail if:
 320 .Bl -tag -width Er
 321 .It Bq Er EINVAL
 322 The device is not suspended.
 323 .It Bq Er EINVAL
 324 The device to be resumed is the root bus device.
 325 .El
 326 .Pp
 327 The
 328 .Fn devctl_set_driver
 329 function may fail if:
 330 .Bl -tag -width Er
 331 .It Bq Er EBUSY
 332 The device is currently attached to a device driver and
 333 .Fa force
 334 is false.
 335 .It Bq Er EBUSY
 336 The current device driver for
 337 .Fa device
 338 is busy and cannot detach at this time.
 339 .It Bq Er EFAULT
 340 The
 341 .Fa driver
 342 argument points outside the process' allocated address space.
 343 .It Bq Er ENOENT
 344 No device driver with the requested name exists.
 345 .It Bq Er ENOMEM
 346 An internal memory allocation request failed.
 347 .It Bq Er ENXIO
 348 The device is disabled.
 349 .It Bq Er ENXIO
 350 The new device driver failed to attach.
 351 .El
 352 .Pp
 353 The
 354 .Fn devctl_clear_driver
 355 function may fail if:
 356 .Bl -tag -width Er
 357 .It Bq Er EBUSY
 358 The device is currently attached to a device driver and
 359 .Fa force
 360 is false.
 361 .It Bq Er EBUSY
 362 The current device driver for
 363 .Fa device
 364 is busy and cannot detach at this time.
 365 .It Bq Er EINVAL
 366 The device is not configured for a specific device driver name.
 367 .It Bq Er ENXIO
 368 The device driver chosen after reprobing failed to attach.
 369 .El
 370 .Pp
 371 The
 372 .Fn devctl_rescan
 373 function may fail if:
 374 .Bl -tag -width Er
 375 .It Bq Er ENXIO
 376 The device is not attached to a driver.
 377 .It Bq Er ENXIO
 378 The bus driver does not support rescanning.
 379 .El
 380 .Pp
 381 The
 382 .Fn devctl_delete
 383 function may fail if:
 384 .Bl -tag -width Er
 385 .It Bq Er EBUSY
 386 The device is physically present and
 387 .Fa force
 388 is false.
 389 .It Bq Er EINVAL
 390 .Fa dev
 391 is the root device of the device tree.
 392 .El
 393 .Pp
 394 The
 395 .Fn devctl_reset
 396 function may fail if:
 397 .Bl -tag -width Er
 398 .It Bq Er ENXIO
 399 The bus does not implement the reset method.
 400 .It Bq Er ETIMEDOUT
 401 The device failed to respond after the reset in the time limits
 402 specific to the bus.
 403 .El
 404 The
 405 .Fn devctl_reset
 406 function may also return errors caused by the attach, detach, suspend,
 407 and resume methods of the device driver.
 408 .Sh SEE ALSO
 409 .Xr devinfo 3 ,
 410 .Xr devstat 3 ,
 411 .Xr devctl 8
 412 .Sh HISTORY
 413 The
 414 .Nm
 415 library first appeared in
 416 .Fx 10.3 .
 417 .Sh BUGS
 418 If a device is suspended individually via
 419 .Fn devctl_suspend
 420 and the entire machine is subsequently suspended,
 421 the device will be resumed when the machine resumes.
 422 .Pp
 423 Similarly, if the device is suspended, and
 424 .Fn devctl_reset
 425 is called on the device with
 426 .Fa detach
 427 set to
 428 .Va false ,
 429 the device is resumed by the
 430 .Fn devctl_reset
 431 call.
 432 Or, if the driver for the device is detached manually, and
 433 .Fn devctl_reset
 434 is called on the device with
 435 .Fa detach
 436 set to
 437 .Va true ,
 438 device reset re-attaches the driver.