Add documentation for the drvctl driver and add reference.
Fixes PR 49895.
This commit is contained in:
mlelstv
parent
14e2571904
commit
1490a7ba80
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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 @@ output.
|
|||
.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
|
||||
|
|
|
|||
|
|
@ -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 @@ MAN= aac.4 ac97.4 acardide.4 aceride.4 acphy.4 \
|
|||
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 \
|
||||
|
|
|
|||
|
|
@ -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 .
|
||||
Loading…
Reference in New Issue