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 March 26, 2014 27.Dt DEVCTL 4 28.Os 29.Sh NAME 30.Nm devctl 31.Nd "device event reporting and device control interface" 32.Sh DESCRIPTION 33The 34.Nm 35device is used to report device events from the kernel. 36Future versions will allow for some device control as well. 37.Sh IMPLEMENTATION NOTES 38This design allows only one reader for 39.Pa /dev/devctl . 40This is not desirable 41in the long run, but will get a lot of hair out of this implementation. 42Maybe we should make this device a clonable device. 43.Pp 44Also note: we specifically do not attach a device to the 45.Vt device_t 46tree 47to avoid potential chicken and egg problems. 48One could argue that all of this belongs to the root node. 49One could also further argue that the 50.Xr sysctl 3 51interface that we have now might more properly be an 52.Xr ioctl 2 53interface. 54.Pp 55.Dv SIGIO 56support is included in the driver. 57However, the author is not sure that the 58.Dv SIGIO 59support is done correctly. 60It was copied from a driver that had 61.Dv SIGIO 62support that likely has not been 63tested since 64.Fx 3.4 65or 66.Fx 2.2.8 ! 67.Pp 68The read channel for this device is used to report changes to 69userland in realtime. 70We return one record at a time. 71If you try to read this device a character at a time, you will lose 72the rest of the data. 73Listening programs are expected to cope. 74.Pp 75The sysctl 76.Va hw.bus.devctl_queue 77can be used to control queue length. 78It is set to 0 to disable 79.Nm 80when no 81.Xr devd 8 82is running. 83.Sh PROTOCOL 84The 85.Nm 86device 87uses an 88.Tn ASCII 89protocol. 90The driver returns one record at a time to its readers. 91Each record is terminated with a newline. 92The first character of the record is the event type. 93.Pp 94.Bl -column -compact "Type" "Description" 95.Em "Type Description" 96! A notify event, such as a link state change. 97+ Device node in tree attached. 98- Device node in tree detached. 99? Unknown device detected. 100.El 101.Ss Message Formats 102Except for the first character in the record, attach and detach 103messages have the same format. 104.Pp 105.D1 Ar T Ns Ar dev Li at Ar parent Li on Ar location 106.Pp 107.Bl -column -compact "location" "Description" 108.Em "Part Description" 109.It Ar T Ta "+ or -" 110.It Ar dev Ta "The device name that was attached/detached." 111.It Ar parent Ta "The device name of the parent bus that attached the device." 112.It Ar location Ta "Bus specific location information." 113.El 114.Pp 115The nomatch messages can be used to load devices driver. 116If you load a device driver, then one of two things can happen. 117If the device driver attaches to something, you will get a device 118attached message. 119If it does not, then nothing will happen. 120.Pp 121The attach and detach messages arrive after the event. 122This means one cannot use the attach message to load an alternate 123driver. 124The attach message driver has already claimed this device. 125One cannot use the detach messages to flush data to the device. 126The device is already gone. 127.Sh SEE ALSO 128.Xr devd 8 129