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