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