1.\" 2.\" Copyright (c) 2002 M. Warner Losh <imp@FreeBSD.org> 3.\" 4.\" Redistribution and use in source and binary forms, with or without 5.\" modification, are permitted provided that the following conditions 6.\" are met: 7.\" 1. Redistributions of source code must retain the above copyright 8.\" notice, this list of conditions and the following disclaimer. 9.\" 2. The name of the author may not be used to endorse or promote products 10.\" derived from this software without specific prior written permission. 11.\" 12.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND 13.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 14.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 15.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE 16.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 17.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 18.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 19.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 20.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 21.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 22.\" SUCH DAMAGE. 23.\" 24.\" $FreeBSD$ 25.\" 26.Dd September 21, 2020 27.Dt DEVCTL 4 28.Os 29.Sh NAME 30.Nm devctl 31.Nd "device event reporting and device control interface" 32.Sh SYNOPSIS 33The 34.Nm 35driver is automatically included in the kernel. 36.Sh DESCRIPTION 37The 38.Nm 39device is used to report device events from the kernel. 40Future versions will allow for some device control as well. 41.Sh IMPLEMENTATION NOTES 42This design allows only one reader for 43.Pa /dev/devctl . 44This is not desirable 45in the long run, but will get a lot of hair out of this implementation. 46Maybe we should make this device a clonable device. 47.Pp 48Also note: we specifically do not attach a device to the 49.Vt device_t 50tree 51to avoid potential chicken and egg problems. 52One could argue that all of this belongs to the root node. 53One could also further argue that the 54.Xr sysctl 3 55interface that we have now might more properly be an 56.Xr ioctl 2 57interface. 58.Pp 59.Dv SIGIO 60support is included in the driver. 61However, the author is not sure that the 62.Dv SIGIO 63support is done correctly. 64It was copied from a driver that had 65.Dv SIGIO 66support that likely has not been 67tested since 68.Fx 3.4 69or 70.Fx 2.2.8 ! 71.Pp 72The read channel for this device is used to report changes to 73userland in realtime. 74We return one record at a time. 75If you try to read this device a character at a time, you will lose 76the rest of the data. 77Listening programs are expected to cope. 78.Pp 79The sysctl 80.Va hw.bus.devctl_queue 81can be used to control queue length. 82It is set to 0 to disable 83.Nm 84when no 85.Xr devd 8 86is running. 87.Sh PROTOCOL 88The 89.Nm 90device 91uses an 92.Tn ASCII 93protocol. 94The driver returns one record at a time to its readers. 95Each record is terminated with a newline. 96The first character of the record is the event type. 97.Pp 98.Bl -column -compact "Type" "Description" 99.Em "Type Description" 100! A notify event, such as a link state change. 101+ Device node in tree attached. 102- Device node in tree detached. 103? Unknown device detected. 104.El 105.Ss Message Formats 106Except for the first character in the record, attach and detach 107messages have the same format. 108.Pp 109.D1 Ar T Ns Ar dev Li at Ar parent Li on Ar location 110.Pp 111.Bl -column -compact "location" "Description" 112.Em "Part Description" 113.It Ar T Ta "+ or -" 114.It Ar dev Ta "The device name that was attached/detached." 115.It Ar parent Ta "The device name of the parent bus that attached the device." 116.It Ar location Ta "Bus specific location information." 117.El 118.Pp 119The nomatch messages can be used to load devices driver. 120If you load a device driver, then one of two things can happen. 121If the device driver attaches to something, you will get a device 122attached message. 123If it does not, then nothing will happen. 124.Pp 125The attach and detach messages arrive after the event. 126This means one cannot use the attach message to load an alternate 127driver. 128The attach message driver has already claimed this device. 129One cannot use the detach messages to flush data to the device. 130The device is already gone. 131.Pp 132All values passed back are of the form 133.Sq key=value 134or 135.Sq key="value" . 136When the latter, the string 137.Dq value 138must have any internal backslashes doubled. 139It must also have any internal double quote characters 140.Sq " 141preceded by a backslash. 142All other characters should be passed through. 143.Sh SEE ALSO 144.Xr devd 8 145