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