Changeset View
Changeset View
Standalone View
Standalone View
lib/libdevctl/devctl.3
Show All 18 Lines | |||||
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) | .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) | ||||
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT | .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT | ||||
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY | .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY | ||||
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF | .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF | ||||
.\" SUCH DAMAGE. | .\" SUCH DAMAGE. | ||||
.\" | .\" | ||||
.\" $FreeBSD$ | .\" $FreeBSD$ | ||||
.\" | .\" | ||||
.Dd August 22, 2018 | .Dd April 4, 2019 | ||||
imp: should bump this date, no need for a round trip through phab, though, for that :)
| |||||
.Dt DEVCTL 3 | .Dt DEVCTL 3 | ||||
.Os | .Os | ||||
.Sh NAME | .Sh NAME | ||||
.Nm devctl , | .Nm devctl , | ||||
.Nm devctl_attach , | .Nm devctl_attach , | ||||
.Nm devctl_clear_driver , | .Nm devctl_clear_driver , | ||||
.Nm devctl_delete , | .Nm devctl_delete , | ||||
.Nm devctl_detach , | .Nm devctl_detach , | ||||
.Nm devctl_disable , | .Nm devctl_disable , | ||||
.Nm devctl_enable , | .Nm devctl_enable , | ||||
.Nm devctl_freeze , | .Nm devctl_freeze , | ||||
.Nm devctl_rescan , | .Nm devctl_rescan , | ||||
.Nm devctl_reset , | |||||
.Nm devctl_resume , | .Nm devctl_resume , | ||||
.Nm devctl_set_driver , | .Nm devctl_set_driver , | ||||
.Nm devctl_suspend , | .Nm devctl_suspend , | ||||
.Nm devctl_thaw | .Nm devctl_thaw | ||||
.Nd device control library | .Nd device control library | ||||
.Sh LIBRARY | .Sh LIBRARY | ||||
.Lb libdevctl | .Lb libdevctl | ||||
.Sh SYNOPSIS | .Sh SYNOPSIS | ||||
Show All 10 Lines | |||||
.Fn devctl_disable "const char *device" "bool force_detach" | .Fn devctl_disable "const char *device" "bool force_detach" | ||||
.Ft int | .Ft int | ||||
.Fn devctl_enable "const char *device" | .Fn devctl_enable "const char *device" | ||||
.Ft int | .Ft int | ||||
.Fn devctl_freeze "void" | .Fn devctl_freeze "void" | ||||
.Ft int | .Ft int | ||||
.Fn devctl_rescan "const char *device" | .Fn devctl_rescan "const char *device" | ||||
.Ft int | .Ft int | ||||
.Fn devctl_reset "const char *device" "bool detach" | |||||
.Ft int | |||||
.Fn devctl_resume "const char *device" | .Fn devctl_resume "const char *device" | ||||
.Ft int | .Ft int | ||||
.Fn devctl_set_driver "const char *device" "const char *driver" "bool force" | .Fn devctl_set_driver "const char *device" "const char *driver" "bool force" | ||||
.Ft int | .Ft int | ||||
.Fn devctl_suspend "const char *device" | .Fn devctl_suspend "const char *device" | ||||
.Ft int | .Ft int | ||||
.Fn devctl_thaw "void" | .Fn devctl_thaw "void" | ||||
.Sh DESCRIPTION | .Sh DESCRIPTION | ||||
▲ Show 20 Lines • Show All 125 Lines • ▼ Show 20 Lines | |||||
.Fn devctl_freeze | .Fn devctl_freeze | ||||
function freezes probe and attach processing initiated in response to | function freezes probe and attach processing initiated in response to | ||||
drivers being loaded. | drivers being loaded. | ||||
.Pp | .Pp | ||||
The | The | ||||
.Fn devctl_thaw | .Fn devctl_thaw | ||||
function resumes (thaws the freeze) probe and attach processing | function resumes (thaws the freeze) probe and attach processing | ||||
initiated in response to drivers being loaded. | initiated in response to drivers being loaded. | ||||
.Pp | |||||
The | |||||
.Fn devctl_reset | |||||
function resets the specified device using bus-specific reset method. | |||||
The | |||||
.Fa detach | |||||
argument, if true, specifies that the device driver is detached before | |||||
the reset, and re-attached afterwards. | |||||
If false, the device is suspended before the reset, and resumed after. | |||||
.Sh RETURN VALUES | .Sh RETURN VALUES | ||||
.Rv -std devctl_attach devctl_clear_driver devctl_delete devctl_detach \ | .Rv -std devctl_attach devctl_clear_driver devctl_delete devctl_detach \ | ||||
devctl_disable devctl_enable devctl_suspend devctl_rescan devctl_resume \ | devctl_disable devctl_enable devctl_suspend devctl_rescan devctl_resume \ | ||||
devctl_set_driver | devctl_set_driver | ||||
.Sh ERRORS | .Sh ERRORS | ||||
In addition to specific errors noted below, | In addition to specific errors noted below, | ||||
all of the | all of the | ||||
.Nm | .Nm | ||||
▲ Show 20 Lines • Show All 156 Lines • ▼ Show 20 Lines | |||||
.Bl -tag -width Er | .Bl -tag -width Er | ||||
.It Bq Er EBUSY | .It Bq Er EBUSY | ||||
The device is physically present and | The device is physically present and | ||||
.Fa force | .Fa force | ||||
is false. | is false. | ||||
.It Bq Er EINVAL | .It Bq Er EINVAL | ||||
.Fa dev | .Fa dev | ||||
is the root device of the device tree. | is the root device of the device tree. | ||||
.El | .El | ||||
.Pp | |||||
The | |||||
.Fn devctl_reset | |||||
function may fail if: | |||||
.Bl -tag -width Er | |||||
.It Bq Er ENXIO | |||||
The bus does not implement the reset method. | |||||
.It Bq Er ETIMEDOUT | |||||
The device failed to respond after the reset in the time limits | |||||
specific to the bus. | |||||
.El | |||||
The | |||||
.Fn devctl_reset | |||||
function may also return errors caused by the attach, detach, suspend, | |||||
and resume methods of the device driver. | |||||
Done Inline ActionsAre there any devctl_reset-specific error values (not the EINVAL for a bad flags since the function only passes valid flags to the ioctl) that need to be documented here? jhb: Are there any devctl_reset-specific error values (not the EINVAL for a bad flags since the… | |||||
.Sh SEE ALSO | .Sh SEE ALSO | ||||
.Xr devinfo 3 , | .Xr devinfo 3 , | ||||
.Xr devstat 3 , | .Xr devstat 3 , | ||||
.Xr devctl 8 | .Xr devctl 8 | ||||
.Sh HISTORY | .Sh HISTORY | ||||
The | The | ||||
.Nm | .Nm | ||||
library first appeared in | library first appeared in | ||||
.Fx 10.3 . | .Fx 10.3 . | ||||
.Sh BUGS | .Sh BUGS | ||||
If a device is suspended individually via | If a device is suspended individually via | ||||
.Fn devctl_suspend | .Fn devctl_suspend | ||||
and the entire machine is subsequently suspended, | and the entire machine is subsequently suspended, | ||||
the device will be resumed when the machine resumes. | the device will be resumed when the machine resumes. | ||||
.Pp | |||||
Similarly, if the device is suspended, and | |||||
.Fn devctl_reset | |||||
is called on the device with | |||||
.Fa detach | |||||
set to | |||||
.Va false , | |||||
the device is resumed by the | |||||
.Fn devctl_reset | |||||
call. | |||||
Or, if the driver for the device is detached manually, and | |||||
.Fn devctl_reset | |||||
is called on the device with | |||||
.Fa detach | |||||
set to | |||||
.Va true , | |||||
device reset re-attaches the driver. | |||||
Done Inline ActionsWould be good to add a second paragraph here about a reset always resuming/re-attaching devices. jhb: Would be good to add a second paragraph here about a reset always resuming/re-attaching devices. |
should bump this date, no need for a round trip through phab, though, for that :)