xref: /freebsd/lib/libdevctl/devctl.3 (revision 0fd00e0caa889111fc31617db9cd9aa52e9c5eec)
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