164de8019SJohn Baldwin.\" 264de8019SJohn Baldwin.\" Copyright (c) 2014 John Baldwin <jhb@FreeBSD.org> 364de8019SJohn Baldwin.\" All rights reserved. 464de8019SJohn Baldwin.\" 564de8019SJohn Baldwin.\" Redistribution and use in source and binary forms, with or without 664de8019SJohn Baldwin.\" modification, are permitted provided that the following conditions 764de8019SJohn Baldwin.\" are met: 864de8019SJohn Baldwin.\" 1. Redistributions of source code must retain the above copyright 964de8019SJohn Baldwin.\" notice, this list of conditions and the following disclaimer. 1064de8019SJohn Baldwin.\" 2. Redistributions in binary form must reproduce the above copyright 1164de8019SJohn Baldwin.\" notice, this list of conditions and the following disclaimer in the 1264de8019SJohn Baldwin.\" documentation and/or other materials provided with the distribution. 1364de8019SJohn Baldwin.\" 1464de8019SJohn Baldwin.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND 1564de8019SJohn Baldwin.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 1664de8019SJohn Baldwin.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 1764de8019SJohn Baldwin.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE 1864de8019SJohn Baldwin.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 1964de8019SJohn Baldwin.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 2064de8019SJohn Baldwin.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 2164de8019SJohn Baldwin.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 2264de8019SJohn Baldwin.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 2364de8019SJohn Baldwin.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 2464de8019SJohn Baldwin.\" SUCH DAMAGE. 2564de8019SJohn Baldwin.\" 2664de8019SJohn Baldwin.\" $FreeBSD$ 2764de8019SJohn Baldwin.\" 28*0fd00e0cSJohn Baldwin.Dd February 2, 2016 2964de8019SJohn Baldwin.Dt DEVCTL 3 3064de8019SJohn Baldwin.Os 3164de8019SJohn Baldwin.Sh NAME 3264de8019SJohn Baldwin.Nm devctl , 3364de8019SJohn Baldwin.Nm devctl_attach , 3464de8019SJohn Baldwin.Nm devctl_detach , 3564de8019SJohn Baldwin.Nm devctl_disable , 3664de8019SJohn Baldwin.Nm devctl_enable , 3764de8019SJohn Baldwin.Nm devctl_resume , 38*0fd00e0cSJohn Baldwin.Nm devctl_set_driver , 3964de8019SJohn Baldwin.Nm devctl_suspend 4064de8019SJohn Baldwin.Nd device control library 4164de8019SJohn Baldwin.Sh LIBRARY 4264de8019SJohn Baldwin.Lb libdevctl 4364de8019SJohn Baldwin.Sh SYNOPSIS 4464de8019SJohn Baldwin.In devctl.h 4564de8019SJohn Baldwin.Ft int 4664de8019SJohn Baldwin.Fn devctl_attach "const char *device" 4764de8019SJohn Baldwin.Ft int 4864de8019SJohn Baldwin.Fn devctl_detach "const char *device" "bool force" 4964de8019SJohn Baldwin.Ft int 5064de8019SJohn Baldwin.Fn devctl_disable "const char *device" "bool force_detach" 5164de8019SJohn Baldwin.Ft int 5264de8019SJohn Baldwin.Fn devctl_enable "const char *device" 5364de8019SJohn Baldwin.Ft int 5464de8019SJohn Baldwin.Fn devctl_resume "const char *device" 5564de8019SJohn Baldwin.Ft int 5664de8019SJohn Baldwin.Fn devctl_set_driver "const char *device" "const char *driver" "bool force" 57*0fd00e0cSJohn Baldwin.Ft int 58*0fd00e0cSJohn Baldwin.Fn devctl_suspend "const char *device" 5964de8019SJohn Baldwin.Sh DESCRIPTION 6064de8019SJohn BaldwinThe 6164de8019SJohn Baldwin.Nm 6264de8019SJohn Baldwinlibrary adjusts the state of devices in the kernel's internal device 6364de8019SJohn Baldwinhierarchy. 6464de8019SJohn BaldwinEach control operation accepts a 6564de8019SJohn Baldwin.Fa device 6664de8019SJohn Baldwinargument that identifies the device to adjust. 6764de8019SJohn BaldwinThe 6864de8019SJohn Baldwin.Fa device 6964de8019SJohn Baldwinmay be specified as either the name of an existing device or as a 7064de8019SJohn Baldwinbus-specific address. 7164de8019SJohn BaldwinThe following bus-specific address formats are currently supported: 7264de8019SJohn Baldwin.Bl -tag -offset indent 7364de8019SJohn Baldwin.It Sy pci Ns Fa domain Ns : Ns Fa bus Ns : Ns Fa slot Ns : Ns Fa function 7464de8019SJohn BaldwinA PCI device with the specified 7564de8019SJohn Baldwin.Fa domain , 7664de8019SJohn Baldwin.Fa bus , 7764de8019SJohn Baldwin.Fa slot , 7864de8019SJohn Baldwinand 7964de8019SJohn Baldwin.Fa function . 8064de8019SJohn Baldwin.It Sy pci Ns Fa bus Ns : Ns Fa slot Ns : Ns Fa function 8164de8019SJohn BaldwinA PCI device in domain zero with the specified 8264de8019SJohn Baldwin.Fa bus , 8364de8019SJohn Baldwin.Fa slot , 8464de8019SJohn Baldwinand 8564de8019SJohn Baldwin.Fa function . 8664de8019SJohn Baldwin.It Fa handle 8764de8019SJohn BaldwinA device with an ACPI handle of 8864de8019SJohn Baldwin.Fa handle . 8964de8019SJohn BaldwinThe handle must be specified as an absolute path and must begin with a 9064de8019SJohn Baldwin.Dq \e . 9164de8019SJohn Baldwin.El 9264de8019SJohn Baldwin.Pp 9364de8019SJohn BaldwinThe 9464de8019SJohn Baldwin.Fn devctl_attach 9564de8019SJohn Baldwinfunction probes a device and attaches a suitable device driver if one is 9664de8019SJohn Baldwinfound. 9764de8019SJohn Baldwin.Pp 9864de8019SJohn BaldwinThe 9964de8019SJohn Baldwin.Fn devctl_detach 10064de8019SJohn Baldwinfunction detaches a device from its current device driver. 10164de8019SJohn BaldwinThe device is left detached until either a new driver for its parent 10264de8019SJohn Baldwinbus is loaded or the device is explicitly probed via 10364de8019SJohn Baldwin.Fn devctl_attach . 10464de8019SJohn BaldwinIf 10564de8019SJohn Baldwin.Fa force 10664de8019SJohn Baldwinis true, 10764de8019SJohn Baldwinthe current device driver will be detached even if the device is busy. 10864de8019SJohn Baldwin.Pp 10964de8019SJohn BaldwinThe 11064de8019SJohn Baldwin.Fn devctl_disable 11164de8019SJohn Baldwinfunction disables a device. 11264de8019SJohn BaldwinIf the device is currently attached to a device driver, 11364de8019SJohn Baldwinthe device driver will be detached from the device, 11464de8019SJohn Baldwinbut the device will retain its current name. 11564de8019SJohn BaldwinIf 11664de8019SJohn Baldwin.Fa force_detach 11764de8019SJohn Baldwinis true, 11864de8019SJohn Baldwinthe current device driver will be detached even if the device is busy. 11964de8019SJohn BaldwinThe device will remain disabled and detached until it is explicitly enabled 12064de8019SJohn Baldwinvia 12164de8019SJohn Baldwin.Fn devctl_enable . 12264de8019SJohn Baldwin.Pp 12364de8019SJohn BaldwinThe 12464de8019SJohn Baldwin.Fn devctl_enable 12564de8019SJohn Baldwinfunction re-enables a disabled device. 12664de8019SJohn BaldwinThe device will probe and attach if a suitable device driver is found. 12764de8019SJohn Baldwin.Pp 12864de8019SJohn BaldwinThe 12964de8019SJohn Baldwin.Fn devctl_suspend 13064de8019SJohn Baldwinfunction suspends a device. 13164de8019SJohn BaldwinThis may include placing the device in a reduced power state, 13264de8019SJohn Baldwinbut any device driver currently attached to the device will remain attached. 13364de8019SJohn Baldwin.Pp 13464de8019SJohn BaldwinThe 13564de8019SJohn Baldwin.Fn devctl_resume 13664de8019SJohn Baldwinfunction resumes a suspended device to a fully working state. 13764de8019SJohn Baldwin.Pp 13864de8019SJohn BaldwinThe 13964de8019SJohn Baldwin.Fn devctl_set_driver 14064de8019SJohn Baldwinfunction attaches a device driver named 14164de8019SJohn Baldwin.Fa driver 14264de8019SJohn Baldwinto a device. 14364de8019SJohn BaldwinIf the device is already attached and 14464de8019SJohn Baldwin.Fa force 14564de8019SJohn Baldwinis false, 14664de8019SJohn Baldwinthe request will fail. 14764de8019SJohn BaldwinIf the device is already attached and 14864de8019SJohn Baldwin.Fa force 14964de8019SJohn Baldwinis true, 15064de8019SJohn Baldwinthe device will be detached from its current device driver before it is 15164de8019SJohn Baldwinattached to the new device driver. 15264de8019SJohn Baldwin.Sh RETURN VALUES 15364de8019SJohn Baldwin.Rv -std devctl_attach devctl_detach devctl_disable devctl_enable \ 15464de8019SJohn Baldwindevctl_suspend devctl_resume devctl_set_driver 15564de8019SJohn Baldwin.Sh ERRORS 15664de8019SJohn BaldwinIn addition to specific errors noted below, 15764de8019SJohn Baldwinall of the 15864de8019SJohn Baldwin.Nm 15964de8019SJohn Baldwinfunctions may fail for any of the errors described in 16064de8019SJohn Baldwin.Xr open 2 16164de8019SJohn Baldwinas well as: 16264de8019SJohn Baldwin.Bl -tag -width Er 16364de8019SJohn Baldwin.It Bq Er EINVAL 16464de8019SJohn BaldwinThe device name is too long. 16564de8019SJohn Baldwin.It Bq Er ENOENT 16664de8019SJohn BaldwinNo existing device matches the specified name or location. 16764de8019SJohn Baldwin.It Bq Er EPERM 16864de8019SJohn BaldwinThe current process is not permitted to adjust the state of 16964de8019SJohn Baldwin.Fa device . 17064de8019SJohn Baldwin.El 17164de8019SJohn Baldwin.Pp 17264de8019SJohn BaldwinThe 17364de8019SJohn Baldwin.Fn devctl_attach 17464de8019SJohn Baldwinfunction may fail if: 17564de8019SJohn Baldwin.Bl -tag -width Er 17664de8019SJohn Baldwin.It Bq Er EBUSY 17764de8019SJohn BaldwinThe device is already attached. 17864de8019SJohn Baldwin.It Bq Er ENOMEM 17964de8019SJohn BaldwinAn internal memory allocation request failed. 18064de8019SJohn Baldwin.It Bq Er ENXIO 18164de8019SJohn BaldwinThe device is disabled. 18264de8019SJohn Baldwin.It Bq Er ENXIO 18364de8019SJohn BaldwinNo suitable driver for the device could be found, 18464de8019SJohn Baldwinor the driver failed to attach. 18564de8019SJohn Baldwin.El 18664de8019SJohn Baldwin.Pp 18764de8019SJohn BaldwinThe 18864de8019SJohn Baldwin.Fn devctl_detach 18964de8019SJohn Baldwinfunction may fail if: 19064de8019SJohn Baldwin.Bl -tag -width Er 19164de8019SJohn Baldwin.It Bq Er EBUSY 19264de8019SJohn BaldwinThe current device driver for 19364de8019SJohn Baldwin.Fa device 19464de8019SJohn Baldwinis busy and cannot detach at this time. 19564de8019SJohn BaldwinNote that some drivers may return this even if 19664de8019SJohn Baldwin.Fa force 19764de8019SJohn Baldwinis true. 19864de8019SJohn Baldwin.It Bq Er ENXIO 19964de8019SJohn BaldwinThe device is not attached to a driver. 20064de8019SJohn Baldwin.It Bq Er ENXIO 20164de8019SJohn BaldwinThe current device driver for 20264de8019SJohn Baldwin.Fa device 20364de8019SJohn Baldwindoes not support detaching. 20464de8019SJohn Baldwin.El 20564de8019SJohn Baldwin.Pp 20664de8019SJohn BaldwinThe 20764de8019SJohn Baldwin.Fn devctl_enable 20864de8019SJohn Baldwinfunction may fail if: 20964de8019SJohn Baldwin.Bl -tag -width Er 21064de8019SJohn Baldwin.It Bq Er EBUSY 21164de8019SJohn BaldwinThe device is already enabled. 21264de8019SJohn Baldwin.It Bq Er ENOMEM 21364de8019SJohn BaldwinAn internal memory allocation request failed. 21464de8019SJohn Baldwin.It Bq Er ENXIO 21564de8019SJohn BaldwinNo suitable driver for the device could be found, 21664de8019SJohn Baldwinor the driver failed to attach. 21764de8019SJohn Baldwin.El 21864de8019SJohn Baldwin.Pp 21964de8019SJohn BaldwinThe 22064de8019SJohn Baldwin.Fn devctl_disable 22164de8019SJohn Baldwinfunction may fail if: 22264de8019SJohn Baldwin.Bl -tag -width Er 22364de8019SJohn Baldwin.It Bq Er EBUSY 22464de8019SJohn BaldwinThe current device driver for 22564de8019SJohn Baldwin.Fa device 22664de8019SJohn Baldwinis busy and cannot detach at this time. 22764de8019SJohn BaldwinNote that some drivers may return this even if 22864de8019SJohn Baldwin.Fa force_detach 22964de8019SJohn Baldwinis true. 23064de8019SJohn Baldwin.It Bq Er ENXIO 23164de8019SJohn BaldwinThe device is already disabled. 23264de8019SJohn Baldwin.It Bq Er ENXIO 23364de8019SJohn BaldwinThe current device driver for 23464de8019SJohn Baldwin.Fa device 23564de8019SJohn Baldwindoes not support detaching. 23664de8019SJohn Baldwin.El 23764de8019SJohn Baldwin.Pp 23864de8019SJohn BaldwinThe 23964de8019SJohn Baldwin.Fn devctl_suspend 24064de8019SJohn Baldwinfunction may fail if: 24164de8019SJohn Baldwin.Bl -tag -width Er 24264de8019SJohn Baldwin.It Bq Er EBUSY 24364de8019SJohn BaldwinThe device is already suspended. 24464de8019SJohn Baldwin.It Bq Er EINVAL 24564de8019SJohn BaldwinThe device to be suspended is the root bus device. 24664de8019SJohn Baldwin.El 24764de8019SJohn Baldwin.Pp 24864de8019SJohn BaldwinThe 24964de8019SJohn Baldwin.Fn devctl_resume 25064de8019SJohn Baldwinfunction may fail if: 25164de8019SJohn Baldwin.Bl -tag -width Er 25264de8019SJohn Baldwin.It Bq Er EINVAL 25364de8019SJohn BaldwinThe device is not suspended. 25464de8019SJohn Baldwin.It Bq Er EINVAL 25564de8019SJohn BaldwinThe device to be resumed is the root bus device. 25664de8019SJohn Baldwin.El 25764de8019SJohn Baldwin.Pp 25864de8019SJohn BaldwinThe 25964de8019SJohn Baldwin.Fn devctl_set_driver 26064de8019SJohn Baldwinfunction may fail if: 26164de8019SJohn Baldwin.Bl -tag -width Er 26264de8019SJohn Baldwin.It Bq Er EBUSY 26364de8019SJohn BaldwinThe device is currently attached to a device driver and 26464de8019SJohn Baldwin.Fa force 26564de8019SJohn Baldwinis false. 26664de8019SJohn Baldwin.It Bq Er EBUSY 26764de8019SJohn BaldwinThe current device driver for 26864de8019SJohn Baldwin.Fa device 26964de8019SJohn Baldwinis busy and cannot detach at this time. 27064de8019SJohn Baldwin.It Bq Er EFAULT 27164de8019SJohn BaldwinThe 27264de8019SJohn Baldwin.Fa driver 27364de8019SJohn Baldwinargument points outside the process' allocated address space. 27464de8019SJohn Baldwin.It Bq Er ENOENT 27564de8019SJohn BaldwinNo device driver with the requested name exists. 27664de8019SJohn Baldwin.It Bq Er ENOMEM 27764de8019SJohn BaldwinAn internal memory allocation request failed. 27864de8019SJohn Baldwin.It Bq Er ENXIO 27964de8019SJohn BaldwinThe device is disabled. 28064de8019SJohn Baldwin.It Bq Er ENXIO 28164de8019SJohn BaldwinThe new device driver failed to attach. 28264de8019SJohn Baldwin.El 28364de8019SJohn Baldwin.Sh SEE ALSO 28464de8019SJohn Baldwin.Xr devinfo 3 , 28564de8019SJohn Baldwin.Xr devstat 3 , 28664de8019SJohn Baldwin.Xr devctl 8 28764de8019SJohn Baldwin.Sh HISTORY 28864de8019SJohn BaldwinThe 28964de8019SJohn Baldwin.Nm 29064de8019SJohn Baldwinlibrary first appeared in 291*0fd00e0cSJohn Baldwin.Fx 10.3 . 29264de8019SJohn Baldwin.Sh BUGS 29364de8019SJohn BaldwinIf a device is suspended individually via 29464de8019SJohn Baldwin.Fn devctl_suspend 29564de8019SJohn Baldwinand the entire machine is subsequently suspended, 29664de8019SJohn Baldwinthe device will be resumed when the machine resumes. 297