share/man/man4/man4.i386/pbio.4

   1 .\" Copyright (c) 2000-2002
   2 .\"         Diomidis D. Spinellis, Athens, Greece
   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 as
  10 .\"    the first lines of this file unmodified.
  11 .\" 2. Redistributions in binary form must reproduce the above copyright
  12 .\"    notice, this list of conditions and the following disclaimer in the
  13 .\"    documentation and/or other materials provided with the distribution.
  14 .\"
  15 .\" THIS SOFTWARE IS PROVIDED BY Diomidis D. Spinellis ``AS IS'' AND ANY
  16 .\" EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  17 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
  18 .\" PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL Diomidis D. Spinellis BE
  19 .\" LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
  20 .\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
  21 .\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR
  22 .\" BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
  23 .\" WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE
  24 .\" OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
  25 .\" EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  26 .\"
  27 .\" $FreeBSD$
  28 .\"
  29 .Dd January 14, 2005
  30 .Dt PBIO 4 i386
  31 .Os
  32 .Sh NAME
  33 .Nm pbio
  34 .Nd 8255 parallel peripheral interface basic
  35 .Tn I/O
  36 driver
  37 .Sh SYNOPSIS
  38 .Cd "device pbio"
  39 .Pp
  40 In
  41 .Pa /boot/device.hints :
  42 .Cd hint.pbio.0.at="isa"
  43 .Cd hint.pbio.0.port="0x360"
  44 .Pp
  45 .In dev/pbio/pbioio.h
  46 .Sh DESCRIPTION
  47 The
  48 .Nm
  49 driver supports direct access to the Intel 8255A programmable
  50 peripheral interface (PPI) chip running in mode 0 (simple
  51 .Tn I/O ) .
  52 Such an interface provides 24 digital
  53 .Tn I/O
  54 lines.
  55 The driver is designed for performing
  56 .Tn I/O
  57 under program control using
  58 peripherals such as the
  59 .Tn Advantech
  60 .Tn PCL-724
  61 card, which emulates the Intel 8255A PPI in mode 0.
  62 Other 8255A-based peripherals such as the
  63 .Tn BMC
  64 Messsysteme
  65 .Tn PIO24II
  66 card have also been reported to work.
  67 .Pp
  68 The PPI provides two 8-bit ports (port A and port B) and
  69 two 4-bit ports (port C upper, port C lower).
  70 Each port can be individually programmed for input and
  71 (latched) output,
  72 and appears at a different offset of the device's base
  73 .Tn I/O
  74 address.
  75 .Pp
  76 A separate register allows the configuration of ports for input
  77 or output.
  78 The device is so simple, that reliably probing for it when
  79 input data arrives at its terminals is impossible;
  80 therefore the kernel configuration has to specify the
  81 device's base address.
  82 The device driver provides four character devices that
  83 correspond to the peripheral's
  84 .Tn I/O
  85 ports.
  86 Opening a device for read or write automatically configures
  87 the corresponding hardware port for input or output.
  88 At boot time all ports are set configured for input to avoid damaging
  89 external circuitry.
  90 .Pp
  91 A set of
  92 .Xr ioctl 2
  93 requests allow polled input and paced output to be
  94 efficiently performed at the driver level without expensive
  95 user/kernel context switching.
  96 The driver can perform
  97 .Tn I/O
  98 in three different ways:
  99 .Bl -tag -width ".No Differential"
 100 .It Basic
 101 The read or write operation returns immediately after reading
 102 or writing the data to the port at bus speed.
 103 .It Paced
 104 Data is transferred from or to the port at intervals specified
 105 by a separate
 106 .Xr ioctl 2
 107 call.
 108 .It Differential
 109 (Input only.)
 110 Only port values that differ from the previous port value are returned.
 111 .El
 112 .Pp
 113 The pacing interval is specified in
 114 .Em Hz
 115 unit increments.
 116 Setting a pace of
 117 .Ar n
 118 seconds
 119 will result in no more than one value being read or written every
 120 .Ar n
 121 seconds.
 122 Single byte read/write operations will take at least
 123 .Ar n
 124 seconds to complete.
 125 .Pp
 126 The following
 127 .Xr ioctl 2
 128 calls are supported:
 129 .Bl -tag -width ".Dv PBIO_SETIPACE"
 130 .It Dv PBIO_SETDIFF
 131 accepts a pointer to an integer as the third argument,
 132 and sets the driver for differential input if the integer is non-zero.
 133 The input pace speed determines the periodic interval the driver will use to
 134 examine the port for a changed value.
 135 .It Dv PBIO_GETDIFF
 136 accepts a pointer to an integer as the third argument,
 137 and sets the integer to the last set value for differential input.
 138 .It Dv PBIO_SETIPACE
 139 accepts a pointer to an integer as the third argument,
 140 and sets the driver's input pacing speed to the value of that integer.
 141 .It Dv PBIO_GETIPACE
 142 accepts a pointer to an integer as the third argument,
 143 and sets the integer to the last set value for the input pace.
 144 .It Dv PBIO_SETOPACE
 145 accepts a pointer to an integer as the third argument,
 146 and sets the driver's output pacing speed to the value of that integer.
 147 .It Dv PBIO_GETOPACE
 148 accepts a pointer to an integer as the third argument,
 149 and sets the integer to the last set value for the output pace.
 150 .El
 151 .Sh FILES
 152 .Bl -tag -width ".Pa /dev/pbio0ch" -compact
 153 .It Pa /dev/pbio0a
 154 Port A (8 bit
 155 .Tn I/O ) .
 156 .It Pa /dev/pbio0b
 157 Port B (8 bit
 158 .Tn I/O ) .
 159 .It Pa /dev/pbio0ch
 160 Port C upper (4 bit
 161 .Tn I/O ) .
 162 .It Pa /dev/pbio0cl
 163 Port C lower (4 bit
 164 .Tn I/O ) .
 165 .El
 166 .Sh SEE ALSO
 167 .Rs
 168 .%A "Diomidis Spinellis"
 169 .%T "The information furnace: Consolidated home control"
 170 .%D "2003"
 171 .%J "Personal and Ubiquitous Computing"
 172 .%N 1
 173 .%V 7
 174 .%P "53-69"
 175 .Re
 176 .Sh HISTORY
 177 The
 178 .Nm
 179 device was first used under
 180 .Fx 4.1 .
 181 .Sh AUTHORS
 182 .An "Diomidis D. Spinellis" Aq dds@aueb.gr
 183 .Sh BUGS
 184 One of the
 185 .Tn PCL-724
 186 card's inputs can optionally be wired to generate an interrupt.
 187 This feature is not supported.