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