diff options
Diffstat (limited to 'static/netbsd/man4/drvctl.4')
| -rw-r--r-- | static/netbsd/man4/drvctl.4 | 205 |
1 files changed, 205 insertions, 0 deletions
diff --git a/static/netbsd/man4/drvctl.4 b/static/netbsd/man4/drvctl.4 new file mode 100644 index 00000000..f761e05f --- /dev/null +++ b/static/netbsd/man4/drvctl.4 @@ -0,0 +1,205 @@ +.\" $NetBSD: drvctl.4,v 1.2 2015/05/13 09:15:21 wiz Exp $ +.\" +.\" Copyright (c) 2015 Michael van Elst +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR +.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES +.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. +.\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, +.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 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 SUCH DAMAGE. +.\" +.Dd May 13, 2015 +.Dt DRVCTL 4 +.Os +.Sh NAME +.Nm drvctl +.Nd driver control device +.Sh SYNOPSIS +.Cd pseudo-device drvctl +.Sh DESCRIPTION +The +.Nm +driver allows to control some +.Xr autoconf 9 +operations from userland through the +.Pa /dev/drvctl +device and the +.Xr drvctl 8 +command. +.Pp +The driver supports the following +.Xr ioctl 2 +operations. +.Pp +.Bl -tag -width Ds -offset indent -compact +.It DRVSUSPENDDEV +.It DRVRESUMEDEV +Invoke power management functions for a named driver +that has registered itself with the +.Xr pmf 9 +framework. +The ioctl argument specifies the driver name as: +.Bd -literal -offset indent +struct devpmargs { + char devname[16]; + uint32_t flags; +}; +.Ed +.Pp +The flag +.Dv DEVPM_F_SUBTREE +lets the function recurse over all children of that driver. +.Pp +.It DRVLISTDEV +Return a list of child devices attached to the named +driver. +The ioctl argument specifies the driver name as: +.Bd -literal -offset indent +struct devlistargs { + char l_devname[16]; + char (*l_childname)[16]; + size_t l_children; +}; +.Ed +The names for up to +.Dv l_children +child devices are copied to the +.Dv l_childname +array. +If there is no error, the ioctl returns the total number of children. +Normally you would call +.Dv DRVLISTDEV +once with +.Dv l_children +set to zero, allocate a buffer for enough 16-character strings +and call +.Dv DRVLISTDEV +again to fill the buffer. +.Pp +.It DRVDETACHDEV +Detach the named driver and all its autoconfigured children. +The ioctl argument specifies the driver name as: +.Bd -literal -offset indent +struct devdetachargs { + char devname[16]; +}; +.Ed +.Pp +.It DRVSCANBUS +Invoke the rescan method of the named driver to locate child +devices. +The ioctl argument specifies the driver name as: +.Bd -literal -offset indent +struct devrescanargs { + char busname[16]; + char ifattr[16]; + unsigned int numlocators; + int *locators; +}; +.Ed +.Pp +Some device drivers attach children to specific interface +attributes, a zero length +.Dv ifattr +represents that no interface attribute should be used. +The rescan can also be limited to driver-specific locators. +.Pp +.It DRVCTLCOMMAND +Send a command formatted as a property list. +The property list includes all arguments like the driver name, +the result is again a property list. +Currently the only supported command is "get-properties", +the property list is constructed like: +.Bd -literal -offset indent +const char *device = "sd0"; +const char *command = "get-properties"; + +prop_string_t s; +prop_dictionary_t c, a; + +c = prop_dictionary_create(); +a = prop_dictionary_create(); + +s = prop_string_create_cstring_nocopy(command); +prop_dictionary_set(c, "drvctl-command", s); +prop_object_release(s); + +s = prop_string_create_cstring(device); +prop_dictionary_set(a, "device-name", s); +prop_object_release(s); + +prop_dictionary_set(c, "drvctl-arguments", a); +prop_object_release(a); +.Ed +.Pp +The command must be sent with +.Xr prop_dictionary_sendrecv_ioctl 3 . +The resulting property list contains the numeric attribute +.Dv drvctl-error , +which corresponds to an +.Dv errno +value, and the dictionary +.Dv drvctl-result-data . +The contents of the dictionary depends on the queried driver. +.Pp +.It DRVGETEVENT +Return the next queued autoconfig event formatted as a property list. +The request needs to be sent with +.Xr prop_dictionary_recv_ioctl 3 . +The resulting property list contains the string attributes +.Dv event, device +and +.Dv parent . +Currently the events "device-attach" and "device-detach" +are generated by the +.Xr autoconf 9 +framework. +.Pp +If +.Pa /dev/drvctl +was opened with +.Dv O_NONBLOCK +and there is no event queued, the call returns immediately with +.Dv EWOULDBLOCK , +otherwise it waits for the next event. +.El +.Pp +All names used in the ioctl arguments are zero-terminated strings. +A driver name is the name of a driver instance with the appended +unit number like +.Dv sd0 , atabus3 , ... +.Sh FILES +.Bl -tag +.It Pa /dev/drvctl +.Nm +access device +.El +.Sh SEE ALSO +.Xr ioctl 2 , +.Xr prop_send_ioctl 3 , +.Xr proplib 3 , +.Xr devpubd 8 , +.Xr drvctl 8 , +.Xr autoconf 9 +.Sh HISTORY +The +.Pa /dev/drvctl +device appeared in +.Nx 3.0 +but was only added to the GENERIC configuration in +.Nx 5.0 . |