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