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