share/man/man4/devctl.4

   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
  33 The
  34 .Nm
  35 driver is automatically included in the kernel.
  36 .Sh DESCRIPTION
  37 The
  38 .Nm
  39 device is used to report device events from the kernel.
  40 Future versions will allow for some device control as well.
  41 .Sh IMPLEMENTATION NOTES
  42 This design allows only one reader for
  43 .Pa /dev/devctl .
  44 This is not desirable
  45 in the long run, but will get a lot of hair out of this implementation.
  46 Maybe we should make this device a clonable device.
  47 .Pp
  48 Also note: we specifically do not attach a device to the
  49 .Vt device_t
  50 tree
  51 to avoid potential chicken and egg problems.
  52 One could argue that all of this belongs to the root node.
  53 One could also further argue that the
  54 .Xr sysctl 3
  55 interface that we have now might more properly be an
  56 .Xr ioctl 2
  57 interface.
  58 .Pp
  59 .Dv SIGIO
  60 support is included in the driver.
  61 However, the author is not sure that the
  62 .Dv SIGIO
  63 support is done correctly.
  64 It was copied from a driver that had
  65 .Dv SIGIO
  66 support that likely has not been
  67 tested since
  68 .Fx 3.4
  69 or
  70 .Fx 2.2.8 !
  71 .Pp
  72 The read channel for this device is used to report changes to
  73 userland in realtime.
  74 We return one record at a time.
  75 If you try to read this device a character at a time, you will lose
  76 the rest of the data.
  77 Listening programs are expected to cope.
  78 .Pp
  79 The sysctl
  80 .Va hw.bus.devctl_queue
  81 can be used to control queue length.
  82 It is set to 0 to disable
  83 .Nm
  84 when no
  85 .Xr devd 8
  86 is running.
  87 .Sh PROTOCOL
  88 The
  89 .Nm
  90 device
  91 uses an
  92 .Tn ASCII
  93 protocol.
  94 The driver returns one record at a time to its readers.
  95 Each record is terminated with a newline.
  96 The 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
 106 Except for the first character in the record, attach and detach
 107 messages 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
 119 The nomatch messages can be used to load devices driver.
 120 If you load a device driver, then one of two things can happen.
 121 If the device driver attaches to something, you will get a device
 122 attached message.
 123 If it does not, then nothing will happen.
 124 .Pp
 125 The attach and detach messages arrive after the event.
 126 This means one cannot use the attach message to load an alternate
 127 driver.
 128 The attach message driver has already claimed this device.
 129 One cannot use the detach messages to flush data to the device.
 130 The device is already gone.
 131 .Pp
 132 All values passed back are of the form
 133 .Sq key=value
 134 or
 135 .Sq key="value" .
 136 When the latter, the string
 137 .Dq value
 138 must have any internal backslashes doubled.
 139 It must also have any internal double quote characters
 140 .Sq "
 141 preceded by a backslash.
 142 All other characters should be passed through.
 143 .Sh SEE ALSO
 144 .Xr devd 8