1.\" 2.\" Copyright (c) 2002 M. Warner Losh 3.\" All rights reserved. 4.\" 5.\" Redistribution and use in source and binary forms, with or without 6.\" modification, are permitted provided that the following conditions 7.\" are met: 8.\" 1. Redistributions of source code must retain the above copyright 9.\" notice, this list of conditions and the following disclaimer. 10.\" 2. The name of the author may not be used to endorse or promote products 11.\" derived from this software without specific prior written permission. 12.\" 13.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND 14.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 15.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 16.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE 17.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 18.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 19.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 20.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 21.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 22.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 23.\" SUCH DAMAGE. 24.\" 25.\" $FreeBSD$ 26.\" 27.Dd February 11, 2003 28.Dt DEVCTL 4 29.Os 30.Sh NAME 31.Nm devctl 32.Nd Device event reporting and device control interface. 33.Sh DESCRIPTION 34The 35.Nm 36device is used to report device events from the kernel. 37Future versions will allow for some device control as well. 38.Sh IMPLEMENTATION NOTES 39This design allows only one reader for /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 device_t tree 45to avoid potential chicken and egg problems. 46One could argue that all of this belongs to the root node. 47One could also further argue that the sysctl interface that we have 48not might more properly be an ioctl interface. 49.Pp 50SIGIO support is included in the driver. 51However, the author is not sure that the SIGIO support is done correctly. 52It was copied from a driver that had SIGIO support that likely hasn't been 53tested since 3.4 or 2.2.8! 54.Pp 55The read channel for this device is used to report changes to 56userland in realtime. 57We return one record at a time. 58If you try to read this device a character at a time, you will loose 59the rest of the data. 60Listening programs are expected to cope. 61.Pp 62The sysctl and boot parameter hw.bus.devctl_disable is used to disable 63.Nm 64when no devd is running. 65.Sh PROTOCOL 66.Nm 67uses an ASCII protocol. 68The driver returns one record at a time to its readers. 69Each record is terminated with a newline. 70The first character of the record is the event type. 71.Pp 72.Bl -column -compact "Type" "Description" 73.Em "Type Description" 74+ Device node in tree attached 75- Device node in tree detached 76? Unknown device detected 77.El 78.Ss Message formats 79Except for the first character in the record, attach and detach 80messages have the same format. 81.D1 Tdev at parent on location 82.Bl -column -compact "Part" "Description" 83.Em "Part Description" 84T + or - 85dev The device name that was attached/detached 86parent The device name of the parent bus that attached the device 87location Bus specific location information 88.El 89.Pp 90The nomatch messages can be used to load devices driver. 91If you load a device driver, then one of two things can happen. 92If the device driver attaches to something, you'll get a device 93attached message. 94If it doesn't, then nothing will happen. 95.Pp 96The attach and detach messages arrive after the event. 97This means one cannot use the attach message to load an alternate 98driver. 99The attach message driver has already claimed this device. 100One cannot use the detach messages to flush data to the device. 101The device is already gone. 102.Sh SEE ALSO 103.Xr devd 8 104 105