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