Source-Changes-HG archive
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index][Old Index]
[src/trunk]: src Add documentation for the drvctl driver and add reference.
details: https://anonhg.NetBSD.org/src/rev/a93b38ca080f
branches: trunk
changeset: 338169:a93b38ca080f
user: mlelstv <mlelstv%NetBSD.org@localhost>
date: Wed May 13 07:28:49 2015 +0000
description:
Add documentation for the drvctl driver and add reference.
Fixes PR 49895.
diffstat:
distrib/sets/lists/man/mi | 4 +-
sbin/drvctl/drvctl.8 | 4 +-
share/man/man4/Makefile | 4 +-
share/man/man4/drvctl.4 | 205 ++++++++++++++++++++++++++++++++++++++++++++++
4 files changed, 212 insertions(+), 5 deletions(-)
diffs (270 lines):
diff -r 25e7f16c5e1b -r a93b38ca080f distrib/sets/lists/man/mi
--- a/distrib/sets/lists/man/mi Wed May 13 07:07:36 2015 +0000
+++ b/distrib/sets/lists/man/mi Wed May 13 07:28:49 2015 +0000
@@ -1,4 +1,4 @@
-# $NetBSD: mi,v 1.1500 2015/05/04 02:43:45 pgoyette Exp $
+# $NetBSD: mi,v 1.1501 2015/05/13 07:28:49 mlelstv Exp $
#
# Note: don't delete entries from here - mark them as "obsolete" instead.
#
@@ -4064,6 +4064,7 @@
./usr/share/man/html4/dreamcast/pvr.html man-sys-htmlman html
./usr/share/man/html4/drm.html man-sys-htmlman html
./usr/share/man/html4/drum.html man-sys-htmlman html
+./usr/share/man/html4/drvctl.html man-sys-htmlman html
./usr/share/man/html4/dtide.html man-sys-htmlman html
./usr/share/man/html4/dtv.html man-sys-htmlman html
./usr/share/man/html4/dtviic.html man-sys-htmlman html
@@ -6897,6 +6898,7 @@
./usr/share/man/man4/dreamcast/pvr.4 man-sys-man .man
./usr/share/man/man4/drm.4 man-sys-man .man
./usr/share/man/man4/drum.4 man-sys-man .man
+./usr/share/man/man4/drvctl.4 man-sys-man .man
./usr/share/man/man4/dtide.4 man-sys-man .man
./usr/share/man/man4/dtv.4 man-sys-man .man
./usr/share/man/man4/dtviic.4 man-sys-man .man
diff -r 25e7f16c5e1b -r a93b38ca080f sbin/drvctl/drvctl.8
--- a/sbin/drvctl/drvctl.8 Wed May 13 07:07:36 2015 +0000
+++ b/sbin/drvctl/drvctl.8 Wed May 13 07:28:49 2015 +0000
@@ -1,4 +1,4 @@
-.\" $NetBSD: drvctl.8,v 1.15 2015/02/25 09:01:08 wiz Exp $
+.\" $NetBSD: drvctl.8,v 1.16 2015/05/13 07:28:49 mlelstv Exp $
.\"
.\" Copyright (c) 2004
.\" Matthias Drochner. All rights reserved.
@@ -150,7 +150,7 @@
.Pa /dev/drvctl
.Sh SEE ALSO
.Xr proplib 3 ,
-.\" .Xr drvctl 4 ,
+.Xr drvctl 4 ,
.Xr autoconf 9
.Sh BUGS
Currently, there is no good way to get information about locator
diff -r 25e7f16c5e1b -r a93b38ca080f share/man/man4/Makefile
--- a/share/man/man4/Makefile Wed May 13 07:07:36 2015 +0000
+++ b/share/man/man4/Makefile Wed May 13 07:28:49 2015 +0000
@@ -1,4 +1,4 @@
-# $NetBSD: Makefile,v 1.619 2015/02/08 16:44:09 wiz Exp $
+# $NetBSD: Makefile,v 1.620 2015/05/13 07:28:49 mlelstv Exp $
# @(#)Makefile 8.1 (Berkeley) 6/18/93
MAN= aac.4 ac97.4 acardide.4 aceride.4 acphy.4 \
@@ -21,7 +21,7 @@
clockctl.4 cmdide.4 cmpci.4 cms.4 cnw.4 \
com.4 coram.4 crypto.4 cs80bus.4 cuda.4 cypide.4 cxdtv.4 \
ddb.4 ddc.4 de.4 dge.4 dk.4 dm.4 dmoverio.4 \
- dmphy.4 dpt.4 dpti.4 drm.4 drum.4 dtv.4 dtviic.4 dwctwo.4 \
+ dmphy.4 dpt.4 dpti.4 drm.4 drum.4 drvctl.4 dtv.4 dtviic.4 dwctwo.4 \
eap.4 ebus.4 edc.4 elmc.4 emuxki.4 en.4 envsys.4 ep.4 esh.4 \
esa.4 esiop.4 esm.4 eso.4 et.4 etherip.4 etphy.4 exphy.4 \
fast_ipsec.4 fd.4 filemon.4 finsio.4 flash.4 fpa.4 fms.4 fss.4 fujbp.4 fxp.4 \
diff -r 25e7f16c5e1b -r a93b38ca080f share/man/man4/drvctl.4
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/share/man/man4/drvctl.4 Wed May 13 07:28:49 2015 +0000
@@ -0,0 +1,205 @@
+.\" $NetBSD: drvctl.4,v 1.1 2015/05/13 07:28:49 mlelstv 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 autoconfig 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 contructed 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 proplib 3 ,
+.Xr prop_send_ioctl 3 ,
+.Xr drvctl 8 ,
+.Xr devpubd 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 .
Home |
Main Index |
Thread Index |
Old Index