1*86d7f5d3SJohn Marino.\" 2*86d7f5d3SJohn Marino.\" Copyright (c) 2002 M. Warner Losh 3*86d7f5d3SJohn Marino.\" All rights reserved. 4*86d7f5d3SJohn Marino.\" 5*86d7f5d3SJohn Marino.\" Redistribution and use in source and binary forms, with or without 6*86d7f5d3SJohn Marino.\" modification, are permitted provided that the following conditions 7*86d7f5d3SJohn Marino.\" are met: 8*86d7f5d3SJohn Marino.\" 1. Redistributions of source code must retain the above copyright 9*86d7f5d3SJohn Marino.\" notice, this list of conditions and the following disclaimer. 10*86d7f5d3SJohn Marino.\" 2. The name of the author may not be used to endorse or promote products 11*86d7f5d3SJohn Marino.\" derived from this software without specific prior written permission. 12*86d7f5d3SJohn Marino.\" 13*86d7f5d3SJohn Marino.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND 14*86d7f5d3SJohn Marino.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 15*86d7f5d3SJohn Marino.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 16*86d7f5d3SJohn Marino.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE 17*86d7f5d3SJohn Marino.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 18*86d7f5d3SJohn Marino.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 19*86d7f5d3SJohn Marino.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 20*86d7f5d3SJohn Marino.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 21*86d7f5d3SJohn Marino.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 22*86d7f5d3SJohn Marino.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 23*86d7f5d3SJohn Marino.\" SUCH DAMAGE. 24*86d7f5d3SJohn Marino.\" 25*86d7f5d3SJohn Marino.\" $FreeBSD: src/share/man/man4/devctl.4,v 1.5 2006/08/04 07:56:32 yar Exp $ 26*86d7f5d3SJohn Marino.\" $DragonFly: src/share/man/man4/devctl.4,v 1.2 2008/10/03 10:30:43 swildner Exp $ 27*86d7f5d3SJohn Marino.\" 28*86d7f5d3SJohn Marino.Dd October 2, 2008 29*86d7f5d3SJohn Marino.Dt DEVCTL 4 30*86d7f5d3SJohn Marino.Os 31*86d7f5d3SJohn Marino.Sh NAME 32*86d7f5d3SJohn Marino.Nm devctl 33*86d7f5d3SJohn Marino.Nd "device event reporting and device control interface" 34*86d7f5d3SJohn Marino.Sh DESCRIPTION 35*86d7f5d3SJohn MarinoThe 36*86d7f5d3SJohn Marino.Nm 37*86d7f5d3SJohn Marinodevice is used to report device events from the kernel. 38*86d7f5d3SJohn MarinoFuture versions will allow for some device control as well. 39*86d7f5d3SJohn Marino.Sh IMPLEMENTATION NOTES 40*86d7f5d3SJohn MarinoThis design allows only one reader for 41*86d7f5d3SJohn Marino.Pa /dev/devctl . 42*86d7f5d3SJohn MarinoThis is not desirable 43*86d7f5d3SJohn Marinoin the long run, but will get a lot of hair out of this implementation. 44*86d7f5d3SJohn MarinoMaybe we should make this device a clonable device. 45*86d7f5d3SJohn Marino.Pp 46*86d7f5d3SJohn MarinoAlso note: we specifically do not attach a device to the 47*86d7f5d3SJohn Marino.Vt device_t 48*86d7f5d3SJohn Marinotree 49*86d7f5d3SJohn Marinoto avoid potential chicken and egg problems. 50*86d7f5d3SJohn MarinoOne could argue that all of this belongs to the root node. 51*86d7f5d3SJohn MarinoOne could also further argue that the 52*86d7f5d3SJohn Marino.Xr sysctl 3 53*86d7f5d3SJohn Marinointerface that we have now might more properly be an 54*86d7f5d3SJohn Marino.Xr ioctl 2 55*86d7f5d3SJohn Marinointerface. 56*86d7f5d3SJohn Marino.Pp 57*86d7f5d3SJohn Marino.Dv SIGIO 58*86d7f5d3SJohn Marinosupport is included in the driver. 59*86d7f5d3SJohn MarinoHowever, the author is not sure that the 60*86d7f5d3SJohn Marino.Dv SIGIO 61*86d7f5d3SJohn Marinosupport is done correctly. 62*86d7f5d3SJohn MarinoIt was copied from a driver that had 63*86d7f5d3SJohn Marino.Dv SIGIO 64*86d7f5d3SJohn Marinosupport that likely has not been 65*86d7f5d3SJohn Marinotested since 66*86d7f5d3SJohn Marino.Fx 3.4 67*86d7f5d3SJohn Marinoor 68*86d7f5d3SJohn Marino.Fx 2.2.8 ! 69*86d7f5d3SJohn Marino.Pp 70*86d7f5d3SJohn MarinoThe read channel for this device is used to report changes to 71*86d7f5d3SJohn Marinouserland in realtime. 72*86d7f5d3SJohn MarinoWe return one record at a time. 73*86d7f5d3SJohn MarinoIf you try to read this device a character at a time, you will lose 74*86d7f5d3SJohn Marinothe rest of the data. 75*86d7f5d3SJohn MarinoListening programs are expected to cope. 76*86d7f5d3SJohn Marino.Pp 77*86d7f5d3SJohn MarinoThe sysctl and boot parameter 78*86d7f5d3SJohn Marino.Va hw.bus.devctl_disable 79*86d7f5d3SJohn Marinois used to disable 80*86d7f5d3SJohn Marino.Nm 81*86d7f5d3SJohn Marinowhen no 82*86d7f5d3SJohn Marino.Xr devd 8 83*86d7f5d3SJohn Marinois running. 84*86d7f5d3SJohn Marino.Sh PROTOCOL 85*86d7f5d3SJohn MarinoThe 86*86d7f5d3SJohn Marino.Nm 87*86d7f5d3SJohn Marinodevice 88*86d7f5d3SJohn Marinouses an 89*86d7f5d3SJohn Marino.Tn ASCII 90*86d7f5d3SJohn Marinoprotocol. 91*86d7f5d3SJohn MarinoThe driver returns one record at a time to its readers. 92*86d7f5d3SJohn MarinoEach record is terminated with a newline. 93*86d7f5d3SJohn MarinoThe first character of the record is the event type. 94*86d7f5d3SJohn Marino.Pp 95*86d7f5d3SJohn Marino.Bl -column -compact "Type" "Description" 96*86d7f5d3SJohn Marino.Em "Type Description" 97*86d7f5d3SJohn Marino! A notify event, such as a link state change. 98*86d7f5d3SJohn Marino+ Device node in tree attached. 99*86d7f5d3SJohn Marino- Device node in tree detached. 100*86d7f5d3SJohn Marino? Unknown device detected. 101*86d7f5d3SJohn Marino.El 102*86d7f5d3SJohn Marino.Ss Message Formats 103*86d7f5d3SJohn MarinoExcept for the first character in the record, attach and detach 104*86d7f5d3SJohn Marinomessages have the same format. 105*86d7f5d3SJohn Marino.Pp 106*86d7f5d3SJohn Marino.D1 Ar T Ns Ar dev Li at Ar parent Li on Ar location 107*86d7f5d3SJohn Marino.Pp 108*86d7f5d3SJohn Marino.Bl -column -compact "location" "Description" 109*86d7f5d3SJohn Marino.Em "Part Description" 110*86d7f5d3SJohn Marino.It Ar T Ta "+ or -" 111*86d7f5d3SJohn Marino.It Ar dev Ta "The device name that was attached/detached." 112*86d7f5d3SJohn Marino.It Ar parent Ta "The device name of the parent bus that attached the device." 113*86d7f5d3SJohn Marino.It Ar location Ta "Bus specific location information." 114*86d7f5d3SJohn Marino.El 115*86d7f5d3SJohn Marino.Pp 116*86d7f5d3SJohn MarinoThe nomatch messages can be used to load devices driver. 117*86d7f5d3SJohn MarinoIf you load a device driver, then one of two things can happen. 118*86d7f5d3SJohn MarinoIf the device driver attaches to something, you will get a device 119*86d7f5d3SJohn Marinoattached message. 120*86d7f5d3SJohn MarinoIf it does not, then nothing will happen. 121*86d7f5d3SJohn Marino.Pp 122*86d7f5d3SJohn MarinoThe attach and detach messages arrive after the event. 123*86d7f5d3SJohn MarinoThis means one cannot use the attach message to load an alternate 124*86d7f5d3SJohn Marinodriver. 125*86d7f5d3SJohn MarinoThe attach message driver has already claimed this device. 126*86d7f5d3SJohn MarinoOne cannot use the detach messages to flush data to the device. 127*86d7f5d3SJohn MarinoThe device is already gone. 128*86d7f5d3SJohn Marino.Sh SEE ALSO 129*86d7f5d3SJohn Marino.Xr devd 8 130