1.\" $NetBSD: drvctl.4,v 1.2 2015/05/13 09:15:21 wiz Exp $ 2.\" 3.\" Copyright (c) 2015 Michael van Elst 4.\" All rights reserved. 5.\" 6.\" Redistribution and use in source and binary forms, with or without 7.\" modification, are permitted provided that the following conditions 8.\" are met: 9.\" 1. Redistributions of source code must retain the above copyright 10.\" notice, this list of conditions and the following disclaimer. 11.\" 2. Redistributions in binary form must reproduce the above copyright 12.\" notice, this list of conditions and the following disclaimer in the 13.\" documentation and/or other materials provided with the distribution. 14.\" 15.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR 16.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES 17.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. 18.\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, 19.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT 20.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, 21.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY 22.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 23.\" INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF 24.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 25.\" 26.Dd May 13, 2015 27.Dt DRVCTL 4 28.Os 29.Sh NAME 30.Nm drvctl 31.Nd driver control device 32.Sh SYNOPSIS 33.Cd pseudo-device drvctl 34.Sh DESCRIPTION 35The 36.Nm 37driver allows to control some 38.Xr autoconf 9 39operations from userland through the 40.Pa /dev/drvctl 41device and the 42.Xr drvctl 8 43command. 44.Pp 45The driver supports the following 46.Xr ioctl 2 47operations. 48.Pp 49.Bl -tag -width Ds -offset indent -compact 50.It DRVSUSPENDDEV 51.It DRVRESUMEDEV 52Invoke power management functions for a named driver 53that has registered itself with the 54.Xr pmf 9 55framework. 56The ioctl argument specifies the driver name as: 57.Bd -literal -offset indent 58struct devpmargs { 59 char devname[16]; 60 uint32_t flags; 61}; 62.Ed 63.Pp 64The flag 65.Dv DEVPM_F_SUBTREE 66lets the function recurse over all children of that driver. 67.Pp 68.It DRVLISTDEV 69Return a list of child devices attached to the named 70driver. 71The ioctl argument specifies the driver name as: 72.Bd -literal -offset indent 73struct devlistargs { 74 char l_devname[16]; 75 char (*l_childname)[16]; 76 size_t l_children; 77}; 78.Ed 79The names for up to 80.Dv l_children 81child devices are copied to the 82.Dv l_childname 83array. 84If there is no error, the ioctl returns the total number of children. 85Normally you would call 86.Dv DRVLISTDEV 87once with 88.Dv l_children 89set to zero, allocate a buffer for enough 16-character strings 90and call 91.Dv DRVLISTDEV 92again to fill the buffer. 93.Pp 94.It DRVDETACHDEV 95Detach the named driver and all its autoconfigured children. 96The ioctl argument specifies the driver name as: 97.Bd -literal -offset indent 98struct devdetachargs { 99 char devname[16]; 100}; 101.Ed 102.Pp 103.It DRVSCANBUS 104Invoke the rescan method of the named driver to locate child 105devices. 106The ioctl argument specifies the driver name as: 107.Bd -literal -offset indent 108struct devrescanargs { 109 char busname[16]; 110 char ifattr[16]; 111 unsigned int numlocators; 112 int *locators; 113}; 114.Ed 115.Pp 116Some device drivers attach children to specific interface 117attributes, a zero length 118.Dv ifattr 119represents that no interface attribute should be used. 120The rescan can also be limited to driver-specific locators. 121.Pp 122.It DRVCTLCOMMAND 123Send a command formatted as a property list. 124The property list includes all arguments like the driver name, 125the result is again a property list. 126Currently the only supported command is "get-properties", 127the property list is constructed like: 128.Bd -literal -offset indent 129const char *device = "sd0"; 130const char *command = "get-properties"; 131 132prop_string_t s; 133prop_dictionary_t c, a; 134 135c = prop_dictionary_create(); 136a = prop_dictionary_create(); 137 138s = prop_string_create_cstring_nocopy(command); 139prop_dictionary_set(c, "drvctl-command", s); 140prop_object_release(s); 141 142s = prop_string_create_cstring(device); 143prop_dictionary_set(a, "device-name", s); 144prop_object_release(s); 145 146prop_dictionary_set(c, "drvctl-arguments", a); 147prop_object_release(a); 148.Ed 149.Pp 150The command must be sent with 151.Xr prop_dictionary_sendrecv_ioctl 3 . 152The resulting property list contains the numeric attribute 153.Dv drvctl-error , 154which corresponds to an 155.Dv errno 156value, and the dictionary 157.Dv drvctl-result-data . 158The contents of the dictionary depends on the queried driver. 159.Pp 160.It DRVGETEVENT 161Return the next queued autoconfig event formatted as a property list. 162The request needs to be sent with 163.Xr prop_dictionary_recv_ioctl 3 . 164The resulting property list contains the string attributes 165.Dv event, device 166and 167.Dv parent . 168Currently the events "device-attach" and "device-detach" 169are generated by the 170.Xr autoconf 9 171framework. 172.Pp 173If 174.Pa /dev/drvctl 175was opened with 176.Dv O_NONBLOCK 177and there is no event queued, the call returns immediately with 178.Dv EWOULDBLOCK , 179otherwise it waits for the next event. 180.El 181.Pp 182All names used in the ioctl arguments are zero-terminated strings. 183A driver name is the name of a driver instance with the appended 184unit number like 185.Dv sd0 , atabus3 , ... 186.Sh FILES 187.Bl -tag 188.It Pa /dev/drvctl 189.Nm 190access device 191.El 192.Sh SEE ALSO 193.Xr ioctl 2 , 194.Xr prop_send_ioctl 3 , 195.Xr proplib 3 , 196.Xr devpubd 8 , 197.Xr drvctl 8 , 198.Xr autoconf 9 199.Sh HISTORY 200The 201.Pa /dev/drvctl 202device appeared in 203.Nx 3.0 204but was only added to the GENERIC configuration in 205.Nx 5.0 . 206