.\"        $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 .