share/man/man4/hatm.4

   1 .\"
   2 .\" Copyright (c) 2001-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 .\" hatm(4) man page
  32 .\"
  33 .Dd May 15, 2003
  34 .Dt HATM 4
  35 .Os
  36 .Sh NAME
  37 .Nm hatm
  38 .Nd "device driver for Fore/Marconi HE155 and HE622 ATM interfaces"
  39 .Sh SYNOPSIS
  40 .Cd device hatm
  41 .Cd device utopia
  42 .Cd device atm
  43 .Pp
  44 .Cd options NATM
  45 .Sh DESCRIPTION
  46 The
  47 .Nm
  48 device driver supports the FORE (now Marconi) HE155 and HE622 ATM interface
  49 cards.
  50 The driver interfaces with the
  51 .Xr natm 4
  52 framework,
  53 .Xr netgraph 4
  54 and the HARP ATM stack.
  55 It provides only PVC services.
  56 Signalling, ATMARP, ILMI and other
  57 higher layer protocols are implemented using
  58 .Xr netgraph 4
  59 or HARP.
  60 .Pp
  61 For configuring the card for IP see
  62 .Xr natmip 4 .
  63 .Pp
  64 The following sysctls are recognized by the driver additionally to those
  65 handled by
  66 .Xr utopia 4 :
  67 .Bl -tag -width indent
  68 .It Va hw.atm.hatm.natm_traffic
  69 This is the traffic type to be used for NATM pvc connections.
  70 The type of
  71 this variable is integer and it must have one of the values 0 (UBR) or 1 (CBR).
  72 .It Va hw.atm.hatm.natm_pcr
  73 This is the peak cell rate to be used for NATM CBR connections.
  74 .It Va hw.atm.hatm Ns Ar N Ns Va .stats
  75 Contains an array of
  76 .Vt uint32_t
  77 with device specific statistics.
  78 .It Va hw.atm.hatm Ns Ar N Ns Va .istats
  79 Contains an array of
  80 .Vt uint32_t
  81 with internal driver statistics.
  82 .It Va hw.atm.hatm Ns Ar N Ns Va .debug
  83 .Bf Em
  84 (Only if debugging enabled.)
  85 .Ef
  86 These are the debugging flags.
  87 See
  88 .Pa src/sys/dev/hatm/if_hatmvar.h
  89 for the possible flags.
  90 .It Va hw.atm.hatm Ns Ar N Ns Va .tsr
  91 .Bf Em
  92 (Only if debugging enabled.)
  93 .Ef
  94 This is an array containing all transmission status registers.
  95 For each of the
  96 4096 possible VCCs there are 15 32-bit registers.
  97 .It Va hw.atm.hatm Ns Ar N Ns Va .tpd
  98 .Bf Em
  99 (Only if debugging enabled.)
 100 .Ef
 101 This is an array containing all on card current transmission packet descriptors.
 102 For each of the 4096 possible VCCs there are 16 32-bit registers.
 103 .It Va hw.atm.hatm Ns Ar N Ns Va .mbox
 104 .Bf Em
 105 (Only if debugging enabled.)
 106 .Ef
 107 This is an array containing the mbox registers.
 108 .It Va hw.atm.hatm Ns Ar N Ns Va .cm
 109 .Bf Em
 110 (Only if debugging enabled.)
 111 .Ef
 112 This is an array containing all connection memory registers.
 113 The first 32-bit integer of this array is the ABR base address.
 114 .It Va hw.atm.hatm Ns Ar N Ns Va .heregs
 115 .Bf Em
 116 (Only if debugging enabled.)
 117 .Ef
 118 This is an array containing all card registers including SUNI and the FLASH ROM.
 119 .It Va hw.atm.hatm Ns Ar N Ns Va .lbmem
 120 .Bf Em
 121 (Only if debugging enabled.)
 122 .Ef
 123 Returns the contents of the local memory.
 124 .El
 125 .Pp
 126 The driver supports the media options
 127 .Cm sdh , noscramb
 128 and
 129 .Cm unassigned
 130 (see
 131 .Xr utopia 4 ) .
 132 .Sh ENVIRONMENT
 133 When attaching to a device the driver checks the kernel environment
 134 (see
 135 .Xr kenv 1 )
 136 to see if the default queues sizes should be overwritten or not.
 137 The
 138 following variables are checked and interpreted as unsigned integer
 139 values (in either radix):
 140 .Bl -tag -width indent
 141 .It Va hw.hatm Ns Ar N Ns Va .rbps0_size
 142 Size of the small receive buffer pool 0.
 143 This pool is used for all
 144 except raw AAL connections.
 145 The pool size must be a power of two between
 146 4 and 8192 inclusive.
 147 When attaching the driver allocates this number
 148 of mbufs.
 149 .It Va hw.hatm Ns Ar N Ns Va .rbps0_thresh
 150 Interrupt threshold for small receive buffer pool 0.
 151 When the number of free
 152 buffers in the pool falls below this threshold it generates an interrupt
 153 so that the driver can refill the pool.
 154 .It Va hw.hatm Ns Ar N Ns Va .rbpl0_thresh
 155 Size of the large receive buffer pool 0.
 156 This pool is used for all
 157 except raw AAL connections.
 158 The pool size must be a power of two between
 159 4 and 8192 inclusive.
 160 When attaching the driver allocates this number
 161 of mbufs with clusters.
 162 .It Va hw.hatm Ns Ar N Ns Va .rbpl0_thresh
 163 Interrupt threshold for large receive buffer pool 0.
 164 When the number of free
 165 buffers in the pool falls below this threshold it generates an interrupt
 166 so that the driver can refill the pool.
 167 .It Va hw.hatm Ns Ar N Ns Va .rbrq0_size
 168 Size of receive buffer return queue 0.
 169 This queue is used to return buffers
 170 filled with received frames to the driver.
 171 The size must be a power of 2
 172 between 1 and 16384 inclusive.
 173 .It Va hw.hatm Ns Ar N Ns Va .rbrq0_thresh
 174 Interrupt threshold for receive buffer return queue 0.
 175 This threshold
 176 should only be triggered in exceptional cases.
 177 .It Va hw.hatm Ns Ar N Ns Va .rbrq0_tout
 178 Interrupt timeout for receive buffer return queue 0.
 179 An interrupt is generated
 180 after this time if the queue is not empty.
 181 The number is in internal card
 182 ticks.
 183 .It Va hw.hatm Ns Ar N Ns Va .rbrq0_pcnt
 184 Packet count threshold for receive buffer return queue 0.
 185 An interrupt
 186 is generated if this number of packets is in the queue.
 187 .It Va hw.hatm Ns Ar N Ns Va .rbps1_size
 188 Size of the small receive buffer pool 1.
 189 This pool is used for all
 190 raw AAL connections.
 191 The pool size must be a power of two between
 192 4 and 8192 inclusive.
 193 When attaching the driver allocates this number
 194 of mbufs.
 195 .It Va hw.hatm Ns Ar N Ns Va .rbps1_thresh
 196 Interrupt threshold for small receive buffer pool 1.
 197 When the number of free
 198 buffers in the pool falls below this threshold it generates an interrupt
 199 so that the driver can refill the pool.
 200 .It Va hw.hatm Ns Ar N Ns Va .rbrq1_size
 201 Size of receive buffer return queue 1.
 202 This queue is used to return buffers
 203 filled with received cells to the driver.
 204 The size must be a power of 2
 205 between 1 and 16384 inclusive.
 206 .It Va hw.hatm Ns Ar N Ns Va .rbrq1_thresh
 207 Interrupt threshold for receive buffer return queue 1.
 208 This threshold
 209 should only be triggered in exceptional cases.
 210 .It Va hw.hatm Ns Ar N Ns Va .rbrq1_tout
 211 Interrupt timeout for receive buffer return queue 1.
 212 An interrupt is generated
 213 after this time if the queue is not empty.
 214 The number is in internal card
 215 ticks.
 216 .It Va hw.hatm Ns Ar N Ns Va .rbrq1_pcnt
 217 Packet count threshold for receive buffer return queue 0.
 218 An interrupt
 219 is generated if this number of cells is in the queue.
 220 .It Va hw.hatm Ns Ar N Ns Va .irq0_size
 221 Size of interrupt queue 0.
 222 This must be a number between 1 and 1023 inclusive.
 223 .It Va hw.hatm Ns Ar N Ns Va .irq0_thresh
 224 Interrupt retrigger threshold of interrupt queue 0.
 225 A new interrupt is trigger
 226 if the queue fill state reaches this threshold and the interrupt was no
 227 served.
 228 .It Va hw.hatm Ns Ar N Ns Va .tbrq0_size
 229 Transmit buffer return queue 0 size.
 230 This queue is used to feed back empty
 231 buffers of transmitted frames back to the driver.
 232 It must be a power of 2
 233 between 1 and 4096 inclusive.
 234 .It Va hw.hatm Ns Ar N Ns Va .tbrq0_thresh
 235 Transmit buffer return queue 0 threshold.
 236 An interrupt is generated if the
 237 queue fill state reaches this point.
 238 .It Va hw.hatm Ns Ar N Ns Va .tpdrq_size
 239 Transmit descriptor ready queue size.
 240 This queue is used by the driver
 241 to feed transmit descriptors into the card.
 242 The size must be a power of 2
 243 between 1 and 16384 inclusive.
 244 .It Va hw.hatm Ns Ar N Ns Va .tpdmax
 245 Maximum number of active TPDs per connection.
 246 This controls the maximum
 247 number of outstanding packet chunks per connection and thus the maximum
 248 delay packets can have because of queueing on the adapter.
 249 If set to 0,
 250 a connection can eat up all available TPDs.
 251 .It Va hw.hatm Ns Ar N Ns Va .mbuf_max_pages
 252 Maximum number of memory pages allocated to small external mbufs.
 253 This must not be zero and not larger than 65536.
 254 .El
 255 .Sh DIAGNOSTICS
 256 .Bd -literal
 257 hatm0: <FORE HE> mem 0xd2600000-0xd26fffff irq 9 at device 15.0 on pci2
 258 hatm0: ForeRunnerHE 622, Rev. D, S/N 2949834, MAC=00:20:48:2d:02:ca
 259 .Ed
 260 .Sh SEE ALSO
 261 .Xr natm 4 ,
 262 .Xr natmip 4 ,
 263 .Xr utopia 4 ,
 264 .Xr ifconfig 8 ,
 265 .Xr route 8
 266 .Sh AUTHORS
 267 .An Harti Brandt Aq harti@FreeBSD.org
 268 .Sh CAVEATS
 269 When putting a HE155 into a 64-bit 66MHz PCI slot the machine may hang.
 270 This occurs very early in the POST so that even the display does not turn on.
 271 The HE155 runs only in 33MHz slots (either 32 or 64-bit).
 272 HE622 cards work just fine in 64-bit slots.
 273 .Pp
 274 The driver may not work with bounce buffer, because of
 275 .Xr bus_dmamap_sync 9
 276 missing the
 277 .Fa offset
 278 and
 279 .Fa len
 280 arguments the
 281 .Nx
 282 function has.