Differential D6019 Diff 15663 head/lib/libdevctl/devctl.3

Changeset View

Standalone View

head/lib/libdevctl/devctl.3

	Show All 25 Lines
	.\" $FreeBSD$			.\" $FreeBSD$
	.\"			.\"
	.Dd April 27, 2016			.Dd April 27, 2016
	.Dt DEVCTL 3			.Dt DEVCTL 3
	.Os			.Os
	.Sh NAME			.Sh NAME
	.Nm devctl ,			.Nm devctl ,
	.Nm devctl_attach ,			.Nm devctl_attach ,
				.Nm devctl_delete ,
	.Nm devctl_detach ,			.Nm devctl_detach ,
	.Nm devctl_disable ,			.Nm devctl_disable ,
	.Nm devctl_enable ,			.Nm devctl_enable ,
	.Nm devctl_rescan ,			.Nm devctl_rescan ,
	.Nm devctl_resume ,			.Nm devctl_resume ,
	.Nm devctl_set_driver ,			.Nm devctl_set_driver ,
	.Nm devctl_suspend			.Nm devctl_suspend
	.Nd device control library			.Nd device control library
	.Sh LIBRARY			.Sh LIBRARY
	.Lb libdevctl			.Lb libdevctl
	.Sh SYNOPSIS			.Sh SYNOPSIS
	.In devctl.h			.In devctl.h
	.Ft int			.Ft int
	.Fn devctl_attach "const char *device"			.Fn devctl_attach "const char *device"
	.Ft int			.Ft int
				.Fn devctl_delete "const char *device" "bool force"
				.Ft int
	.Fn devctl_detach "const char *device" "bool force"			.Fn devctl_detach "const char *device" "bool force"
	.Ft int			.Ft int
	.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_rescan "const char *device"			.Fn devctl_rescan "const char *device"
	.Ft int			.Ft int
	▲ Show 20 Lines • Show All 48 Lines • ▼ Show 20 Lines
	bus is loaded or the device is explicitly probed via			bus is loaded or the device is explicitly probed via
	.Fn devctl_attach .			.Fn devctl_attach .
	If			If
	.Fa force			.Fa force
	is true,			is true,
	the current device driver will be detached even if the device is busy.			the current device driver will be detached even if the device is busy.
	.Pp			.Pp
	The			The
				.Fn devctl_delete
				function deletes a device from the device tree.
				No
				If
				.Fa force
				is true,
				the device is deleted even if the device is physically present.
				.Pp
				The
	.Fn devctl_disable			.Fn devctl_disable
	function disables a device.			function disables a device.
	If the device is currently attached to a device driver,			If the device is currently attached to a device driver,
	the device driver will be detached from the device,			the device driver will be detached from the device,
	but the device will retain its current name.			but the device will retain its current name.
	If			If
	.Fa force_detach			.Fa force_detach
	is true,			is true,
	Show All 32 Lines
	the device will be detached from its current device driver before it is			the device will be detached from its current device driver before it is
	attached to the new device driver.			attached to the new device driver.
	.Pp			.Pp
	The			The
	.Fn devctl_rescan			.Fn devctl_rescan
	function rescans a bus device checking for devices that have been added or			function rescans a bus device checking for devices that have been added or
	removed.			removed.
	.Sh RETURN VALUES			.Sh RETURN VALUES
	.Rv -std devctl_attach devctl_detach devctl_disable devctl_enable \			.Rv -std devctl_attach devctl_delete devctl_detach devctl_disable \
	devctl_suspend devctl_rescan devctl_resume devctl_set_driver			devctl_enable devctl_suspend devctl_rescan devctl_resume 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
	functions may fail for any of the errors described in			functions may fail for any of the errors described in
	.Xr open 2			.Xr open 2
	as well as:			as well as:
	.Bl -tag -width Er			.Bl -tag -width Er
	▲ Show 20 Lines • Show All 121 Lines • ▼ Show 20 Lines
	The			The
	.Fn devctl_rescan			.Fn devctl_rescan
	function may fail if:			function may fail if:
	.Bl -tag -width Er			.Bl -tag -width Er
	.It Bq Er ENXIO			.It Bq Er ENXIO
	The device is not attached to a driver.			The device is not attached to a driver.
	.It Bq Er ENXIO			.It Bq Er ENXIO
	The bus driver does not support rescanning.			The bus driver does not support rescanning.
				.El
				.Pp
				The
				.Fn devctl_delete
				function may fail if:
				.Bl -tag -width Er
				.It Bq Er EBUSY
				The device is physically present and
				.Fa force
				is false.
				.It Bq Er EINVAL
				.Fa dev
				is the root device of the device tree.
	.El			.El
	.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.