share/man/man4/patm.4

   1 .\"
   2 .\" Copyright (c) 2003
   3 .\"     Fraunhofer Institute for Open Communication Systems (FhG Fokus).
   4 .\"     All rights reserved.
   5 .\"
   6 .\" Redistribution and use in source and binary forms, with or without
   7 .\" modification, are permitted provided that the following conditions
   8 .\" are met:
   9 .\" 1. Redistributions of source code must retain the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer.
  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 THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
  16 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  17 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  18 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
  19 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  20 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  21 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  22 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  23 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  24 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  25 .\" SUCH DAMAGE.
  26 .\"
  27 .\" Author: Hartmut Brandt <harti@FreeBSD.org>
  28 .\"
  29 .\" $FreeBSD$
  30 .\"
  31 .\" patm(4) man page
  32 .\"
  33 .Dd July 15, 2003
  34 .Dt PATM 4
  35 .Os
  36 .Sh NAME
  37 .Nm patm
  38 .Nd "device driver for IDT77252 based ATM interfaces (ProSum and IDT)"
  39 .Sh SYNOPSIS
  40 .Cd device patm
  41 .Cd device utopia
  42 .Cd device atm
  43 .Pp
  44 .Cd options NATM
  45 .Cd options LIBMBPOOL
  46 .Sh DESCRIPTION
  47 The
  48 .Nm
  49 device driver supports ATM cards based on the IDT77252 chip.
  50 It has been tested with ProSum's ProATM-155 cards and with IDT's evaluation
  51 boards.
  52 The driver interfaces with the
  53 .Xr natm 4
  54 framework,
  55 .Xr netgraph 4
  56 and HARP.
  57 It provides only PVC services.
  58 Signalling, ATMARP, ILMI and other
  59 higher layer protocols are implemented using
  60 .Xr netgraph 4
  61 or HARP.
  62 .Pp
  63 For configuring the card for IP see
  64 .Xr natmip 4 .
  65 .Pp
  66 The driver supports UBR, CBR, VBR and ABR traffic.
  67 Supported AALs are:
  68 AAL0 (cell payloads), AAL5 and raw AAL.
  69 The driver supports opening of VCI/VPI 0/0 in RX, raw AAL-mode.
  70 This VC will receive all incoming cells (even those with non-zero GFC
  71 fields and VPI/VCI values outside the allowed range) that are not
  72 claimed by other open connections.
  73 This may be used for monitoring purposes.
  74 .Pp
  75 The following sysctls are recognized by the driver additionally to those
  76 handled by
  77 .Xr utopia 4 :
  78 .Bl -tag -width indent
  79 .It Va hw.atm.patm Ns Ar N Ns Va .istats
  80 Returns a list of
  81 .Vt uint32_t
  82 statistic counters with internal driver statistics.
  83 .It Va hw.atm.patm Ns Ar N Ns Va .eeprom
  84 This is a read-only variable containing the contents of the on-board EEPROM
  85 device.
  86 .It Va hw.atm.patm Ns Ar N Ns Va .lbuf_max
  87 This puts an upper limit on the number of large receive buffers the
  88 driver will allocate.
  89 This is a read-only variable that can be set via a
  90 .Xr loader 8
  91 tunable.
  92 .It Va hw.atm.patm Ns Ar N Ns Va .tx_maxmaps
  93 This is the upper limit of transmission DMA maps the driver will allocate.
  94 This is read-only but may be set via a
  95 .Xr loader 8
  96 tunable.
  97 .It Va hw.atm.patm Ns Ar N Ns Va .debug
  98 .Bf Em
  99 (Only if debugging enabled.)
 100 .Ef
 101 These are debugging flags.
 102 See
 103 .Pa src/sys/dev/patm/if_patmvar.h
 104 for the possible flags.
 105 This may be initialized via a
 106 .Xr loader 8
 107 tunable.
 108 .It Va hw.atm.patm Ns Ar N Ns Va .regs
 109 .Bf Em
 110 (Only if debugging enabled.)
 111 .Ef
 112 Returns the current values of the card's registers.
 113 .It Va hw.atm.patm Ns Ar N Ns Va .tsq
 114 Returns the transmit status queue.
 115 .El
 116 .Pp
 117 When loaded, the driver initializes several variables from
 118 .Xr loader 8
 119 tunables:
 120 .Bl -tag -width indent
 121 .It Va hw.patm Ns Ar N Ns Va .lbuf_max
 122 This initializes the corresponding
 123 .Xr sysctl 8
 124 variable and defines an upper
 125 limit on the number of large receive buffers (mbuf clusters).
 126 .It Va hw.patm Ns Ar N Ns Va .tx_maxmaps
 127 This initializes the corresponding
 128 .Xr sysctl 8
 129 variable and is the maximum
 130 number of DMA maps for transmission that the driver will allocated.
 131 .It Va hw.patm Ns Ar N Ns Va .debug
 132 .Bf Em
 133 (Only if debugging enabled.)
 134 .Ef
 135 Initializes the debugging flags.
 136 .El
 137 .Pp
 138 The driver supports the media options
 139 .Cm sdh , noscramb
 140 and
 141 .Cm unassigned
 142 (see
 143 .Xr utopia 4 )
 144 when the card is a 155MBit card.
 145 Both PMC-Sierra S/UNI and IDT77155 PHY chips are supported for these cards.
 146 For 25MBit cards the IDT77105 is supported.
 147 .Sh DIAGNOSTICS
 148 .Bd -literal
 149 patm1: <NICStAR (77222/77252) ATM adapter> port 0xc000-0xc0ff mem 0xf8000000-0xf83fffff,0xf4000000-0xf4000fff irq 11 at device 8.0 on pci2
 150 patm1: IDT77252 155MBit interface; idt77252 Rev. G; IDT77155 PHY
 151 patm1: 128K x 32 SRAM; 4096 connections
 152 .Ed
 153 .Sh SEE ALSO
 154 .Xr natm 4 ,
 155 .Xr natmip 4 ,
 156 .Xr utopia 4
 157 .Sh ACKNOWLEDGEMENTS
 158 Thanks to Christian Bucari from ProSum for lending two of these cards to enable
 159 the development of this driver.
 160 Thanks also for answering my questions.
 161 .Sh AUTHORS
 162 .An Harti Brandt Aq harti@FreeBSD.org
 163 .Sh CAVEATS
 164 The card fails to generate an interrupt if a cell is received in AAL0 mode
 165 that has the MSB of the PTI field cleared.
 166 Therefore cells will be delivered on the next receive interrupt which can happen
 167 either when the receive status queue is full, or a cell with the last bit of
 168 the PTI set is received.
 169 .Pp
 170 Although the card supports AAL3/4 the driver does not.
 171 .Pp
 172 The rate tables used by this driver are not the tables recommended by IDT
 173 (they are wrong anyway).
 174 The driver's tables are slightly more aggressive than IDT's.
 175 That means, that the actual cell rate can be slightly higher than the
 176 specified.
 177 This is in contrast to the IDT tables where cell rates 5% less than the
 178 allowed one have been observed.
 179 This can be changed by changing the program that generates these tables,
 180 found in
 181 .Pa /usr/src/sys/dev/patm/genrtab ,
 182 and regenerating them.
 183 .Pp
 184 The reported media for the 155MBit cards will always be OC3/MM, because
 185 there is no (known to me) way to figure out the actual medium.
 186 The medium should really be coded in the EEPROM by the manufacturer.
 187 .Pp
 188 The Tx cell counter in the utopia statistics is wrong, because the chip
 189 uses idle cells for spacing and the PHY counts these cells.
 190 While there is a configuration option for the chip to switch of these cells
 191 and, according to the documentation, this should not influence cell spacing,
 192 it does, so the driver lets the chip generate idle cells.