186d7f5d3SJohn Marino.\" 286d7f5d3SJohn Marino.\" Copyright (c) 2002 M. Warner Losh 386d7f5d3SJohn Marino.\" All rights reserved. 486d7f5d3SJohn Marino.\" 586d7f5d3SJohn Marino.\" Redistribution and use in source and binary forms, with or without 686d7f5d3SJohn Marino.\" modification, are permitted provided that the following conditions 786d7f5d3SJohn Marino.\" are met: 886d7f5d3SJohn Marino.\" 1. Redistributions of source code must retain the above copyright 986d7f5d3SJohn Marino.\" notice, this list of conditions and the following disclaimer. 1086d7f5d3SJohn Marino.\" 2. The name of the author may not be used to endorse or promote products 1186d7f5d3SJohn Marino.\" derived from this software without specific prior written permission. 1286d7f5d3SJohn Marino.\" 1386d7f5d3SJohn Marino.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND 1486d7f5d3SJohn Marino.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 1586d7f5d3SJohn Marino.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 1686d7f5d3SJohn Marino.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE 1786d7f5d3SJohn Marino.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 1886d7f5d3SJohn Marino.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 1986d7f5d3SJohn Marino.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 2086d7f5d3SJohn Marino.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 2186d7f5d3SJohn Marino.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 2286d7f5d3SJohn Marino.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 2386d7f5d3SJohn Marino.\" SUCH DAMAGE. 2486d7f5d3SJohn Marino.\" 2586d7f5d3SJohn Marino.\" $FreeBSD: src/share/man/man4/devctl.4,v 1.5 2006/08/04 07:56:32 yar Exp $ 2686d7f5d3SJohn Marino.\" $DragonFly: src/share/man/man4/devctl.4,v 1.2 2008/10/03 10:30:43 swildner Exp $ 2786d7f5d3SJohn Marino.\" 2886d7f5d3SJohn Marino.Dd October 2, 2008 2986d7f5d3SJohn Marino.Dt DEVCTL 4 3086d7f5d3SJohn Marino.Os 3186d7f5d3SJohn Marino.Sh NAME 3286d7f5d3SJohn Marino.Nm devctl 3386d7f5d3SJohn Marino.Nd "device event reporting and device control interface" 3486d7f5d3SJohn Marino.Sh DESCRIPTION 3586d7f5d3SJohn MarinoThe 3686d7f5d3SJohn Marino.Nm 3786d7f5d3SJohn Marinodevice is used to report device events from the kernel. 3886d7f5d3SJohn MarinoFuture versions will allow for some device control as well. 3986d7f5d3SJohn Marino.Sh IMPLEMENTATION NOTES 4086d7f5d3SJohn MarinoThis design allows only one reader for 4186d7f5d3SJohn Marino.Pa /dev/devctl . 4286d7f5d3SJohn MarinoThis is not desirable 4386d7f5d3SJohn Marinoin the long run, but will get a lot of hair out of this implementation. 4486d7f5d3SJohn MarinoMaybe we should make this device a clonable device. 4586d7f5d3SJohn Marino.Pp 4686d7f5d3SJohn MarinoAlso note: we specifically do not attach a device to the 4786d7f5d3SJohn Marino.Vt device_t 4886d7f5d3SJohn Marinotree 4986d7f5d3SJohn Marinoto avoid potential chicken and egg problems. 5086d7f5d3SJohn MarinoOne could argue that all of this belongs to the root node. 5186d7f5d3SJohn MarinoOne could also further argue that the 5286d7f5d3SJohn Marino.Xr sysctl 3 5386d7f5d3SJohn Marinointerface that we have now might more properly be an 5486d7f5d3SJohn Marino.Xr ioctl 2 5586d7f5d3SJohn Marinointerface. 5686d7f5d3SJohn Marino.Pp 5786d7f5d3SJohn Marino.Dv SIGIO 5886d7f5d3SJohn Marinosupport is included in the driver. 5986d7f5d3SJohn MarinoHowever, the author is not sure that the 6086d7f5d3SJohn Marino.Dv SIGIO 6186d7f5d3SJohn Marinosupport is done correctly. 6286d7f5d3SJohn MarinoIt was copied from a driver that had 6386d7f5d3SJohn Marino.Dv SIGIO 6486d7f5d3SJohn Marinosupport that likely has not been 6586d7f5d3SJohn Marinotested since 6686d7f5d3SJohn Marino.Fx 3.4 6786d7f5d3SJohn Marinoor 6886d7f5d3SJohn Marino.Fx 2.2.8 ! 6986d7f5d3SJohn Marino.Pp 7086d7f5d3SJohn MarinoThe read channel for this device is used to report changes to 7186d7f5d3SJohn Marinouserland in realtime. 7286d7f5d3SJohn MarinoWe return one record at a time. 7386d7f5d3SJohn MarinoIf you try to read this device a character at a time, you will lose 7486d7f5d3SJohn Marinothe rest of the data. 7586d7f5d3SJohn MarinoListening programs are expected to cope. 7686d7f5d3SJohn Marino.Pp 7786d7f5d3SJohn MarinoThe sysctl and boot parameter 7886d7f5d3SJohn Marino.Va hw.bus.devctl_disable 7986d7f5d3SJohn Marinois used to disable 8086d7f5d3SJohn Marino.Nm 8186d7f5d3SJohn Marinowhen no 8286d7f5d3SJohn Marino.Xr devd 8 8386d7f5d3SJohn Marinois running. 8486d7f5d3SJohn Marino.Sh PROTOCOL 8586d7f5d3SJohn MarinoThe 8686d7f5d3SJohn Marino.Nm 8786d7f5d3SJohn Marinodevice 8886d7f5d3SJohn Marinouses an 8986d7f5d3SJohn Marino.Tn ASCII 9086d7f5d3SJohn Marinoprotocol. 9186d7f5d3SJohn MarinoThe driver returns one record at a time to its readers. 9286d7f5d3SJohn MarinoEach record is terminated with a newline. 9386d7f5d3SJohn MarinoThe first character of the record is the event type. 9486d7f5d3SJohn Marino.Pp 9586d7f5d3SJohn Marino.Bl -column -compact "Type" "Description" 9686d7f5d3SJohn Marino.Em "Type Description" 9786d7f5d3SJohn Marino! A notify event, such as a link state change. 9886d7f5d3SJohn Marino+ Device node in tree attached. 9986d7f5d3SJohn Marino- Device node in tree detached. 10086d7f5d3SJohn Marino? Unknown device detected. 10186d7f5d3SJohn Marino.El 10286d7f5d3SJohn Marino.Ss Message Formats 10386d7f5d3SJohn MarinoExcept for the first character in the record, attach and detach 10486d7f5d3SJohn Marinomessages have the same format. 10586d7f5d3SJohn Marino.Pp 10686d7f5d3SJohn Marino.D1 Ar T Ns Ar dev Li at Ar parent Li on Ar location 10786d7f5d3SJohn Marino.Pp 10886d7f5d3SJohn Marino.Bl -column -compact "location" "Description" 10986d7f5d3SJohn Marino.Em "Part Description" 11086d7f5d3SJohn Marino.It Ar T Ta "+ or -" 11186d7f5d3SJohn Marino.It Ar dev Ta "The device name that was attached/detached." 11286d7f5d3SJohn Marino.It Ar parent Ta "The device name of the parent bus that attached the device." 11386d7f5d3SJohn Marino.It Ar location Ta "Bus specific location information." 11486d7f5d3SJohn Marino.El 11586d7f5d3SJohn Marino.Pp 11686d7f5d3SJohn MarinoThe nomatch messages can be used to load devices driver. 11786d7f5d3SJohn MarinoIf you load a device driver, then one of two things can happen. 11886d7f5d3SJohn MarinoIf the device driver attaches to something, you will get a device 11986d7f5d3SJohn Marinoattached message. 12086d7f5d3SJohn MarinoIf it does not, then nothing will happen. 12186d7f5d3SJohn Marino.Pp 12286d7f5d3SJohn MarinoThe attach and detach messages arrive after the event. 12386d7f5d3SJohn MarinoThis means one cannot use the attach message to load an alternate 12486d7f5d3SJohn Marinodriver. 12586d7f5d3SJohn MarinoThe attach message driver has already claimed this device. 12686d7f5d3SJohn MarinoOne cannot use the detach messages to flush data to the device. 12786d7f5d3SJohn MarinoThe device is already gone. 12886d7f5d3SJohn Marino.Sh SEE ALSO 12986d7f5d3SJohn Marino.Xr devd 8 130