1 files changed, 192 insertions, 0 deletions
diff --git a/share/man/man4/patm.4 b/share/man/man4/patm.4
new file mode 100644
index 000000000000..443b9f7a8d43
--- /dev/null
+++ b/share/man/man4/patm.4
@@ -0,0 +1,192 @@
+.\"
+.\" Copyright (c) 2003
+.\"	Fraunhofer Institute for Open Communication Systems (FhG Fokus).
+.\" 	All rights reserved.
+.\"
+.\" Redistribution and use in source and binary forms, with or without
+.\" modification, are permitted provided that the following conditions
+.\" are met:
+.\" 1. Redistributions of source code must retain the above copyright
+.\"    notice, this list of conditions and the following disclaimer.
+.\" 2. Redistributions in binary form must reproduce the above copyright
+.\"    notice, this list of conditions and the following disclaimer in the
+.\"    documentation and/or other materials provided with the distribution.
+.\"
+.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
+.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
+.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
+.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
+.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
+.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
+.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
+.\" SUCH DAMAGE.
+.\"
+.\" Author: Hartmut Brandt <harti@FreeBSD.org>
+.\"
+.\" $FreeBSD$
+.\"
+.\" patm(4) man page
+.\"
+.Dd July 15, 2003
+.Dt PATM 4
+.Os
+.Sh NAME
+.Nm patm
+.Nd "device driver for IDT77252 based ATM interfaces (ProSum and IDT)"
+.Sh SYNOPSIS
+.Cd device patm
+.Cd device utopia
+.Cd device atm
+.Pp
+.Cd options NATM
+.Cd options LIBMBPOOL
+.Sh DESCRIPTION
+The
+.Nm
+device driver supports ATM cards based on the IDT77252 chip.
+It has been tested with ProSum's ProATM-155 cards and with IDT's evaluation
+boards.
+The driver interfaces with the
+.Xr natm 4
+framework,
+.Xr netgraph 4
+and HARP.
+It provides only PVC services.
+Signalling, ATMARP, ILMI and other
+higher layer protocols are implemented using
+.Xr netgraph 4
+or HARP.
+.Pp
+For configuring the card for IP see
+.Xr natmip 4 .
+.Pp
+The driver supports UBR, CBR, VBR and ABR traffic.
+Supported AALs are:
+AAL0 (cell payloads), AAL5 and raw AAL.
+The driver supports opening of VCI/VPI 0/0 in RX, raw AAL-mode.
+This VC will receive all incoming cells (even those with non-zero GFC
+fields and VPI/VCI values outside the allowed range) that are not
+claimed by other open connections.
+This may be used for monitoring purposes.
+.Pp
+The following sysctls are recognized by the driver additionally to those
+handled by
+.Xr utopia 4 :
+.Bl -tag -width indent
+.It Va hw.atm.patm Ns Ar N Ns Va .istats
+Returns a list of
+.Vt uint32_t
+statistic counters with internal driver statistics.
+.It Va hw.atm.patm Ns Ar N Ns Va .eeprom
+This is a read-only variable containing the contents of the on-board EEPROM
+device.
+.It Va hw.atm.patm Ns Ar N Ns Va .lbuf_max
+This puts an upper limit on the number of large receive buffers the
+driver will allocate.
+This is a read-only variable that can be set via a
+.Xr loader 8
+tunable.
+.It Va hw.atm.patm Ns Ar N Ns Va .tx_maxmaps
+This is the upper limit of transmission DMA maps the driver will allocate.
+This is read-only but may be set via a
+.Xr loader 8
+tunable.
+.It Va hw.atm.patm Ns Ar N Ns Va .debug
+.Bf Em
+(Only if debugging enabled.)
+.Ef
+These are debugging flags.
+See
+.Pa src/sys/dev/patm/if_patmvar.h
+for the possible flags.
+This may be initialized via a
+.Xr loader 8
+tunable.
+.It Va hw.atm.patm Ns Ar N Ns Va .regs
+.Bf Em
+(Only if debugging enabled.)
+.Ef
+Returns the current values of the card's registers.
+.It Va hw.atm.patm Ns Ar N Ns Va .tsq
+Returns the transmit status queue.
+.El
+.Pp
+When loaded, the driver initializes several variables from
+.Xr loader 8
+tunables:
+.Bl -tag -width indent
+.It Va hw.patm Ns Ar N Ns Va .lbuf_max
+This initializes the corresponding
+.Xr sysctl 8
+variable and defines an upper
+limit on the number of large receive buffers (mbuf clusters).
+.It Va hw.patm Ns Ar N Ns Va .tx_maxmaps
+This initializes the corresponding
+.Xr sysctl 8
+variable and is the maximum
+number of DMA maps for transmission that the driver will allocated.
+.It Va hw.patm Ns Ar N Ns Va .debug
+.Bf Em
+(Only if debugging enabled.)
+.Ef
+Initializes the debugging flags.
+.El
+.Pp
+The driver supports the media options
+.Cm sdh , noscramb
+and
+.Cm unassigned
+(see
+.Xr utopia 4 )
+when the card is a 155MBit card.
+Both PMC-Sierra S/UNI and IDT77155 PHY chips are supported for these cards.
+For 25MBit cards the IDT77105 is supported.
+.Sh DIAGNOSTICS
+.Bd -literal
+patm1: <NICStAR (77222/77252) ATM adapter> port 0xc000-0xc0ff mem 0xf8000000-0xf83fffff,0xf4000000-0xf4000fff irq 11 at device 8.0 on pci2
+patm1: IDT77252 155MBit interface; idt77252 Rev. G; IDT77155 PHY
+patm1: 128K x 32 SRAM; 4096 connections
+.Ed
+.Sh SEE ALSO
+.Xr natm 4 ,
+.Xr natmip 4 ,
+.Xr utopia 4
+.Sh ACKNOWLEDGEMENTS
+Thanks to Christian Bucari from ProSum for lending two of these cards to enable
+the development of this driver.
+Thanks also for answering my questions.
+.Sh AUTHORS
+.An Harti Brandt Aq harti@FreeBSD.org
+.Sh CAVEATS
+The card fails to generate an interrupt if a cell is received in AAL0 mode
+that has the MSB of the PTI field cleared.
+Therefore cells will be delivered on the next receive interrupt which can happen
+either when the receive status queue is full, or a cell with the last bit of
+the PTI set is received.
+.Pp
+Although the card supports AAL3/4 the driver does not.
+.Pp
+The rate tables used by this driver are not the tables recommended by IDT
+(they are wrong anyway).
+The driver's tables are slightly more aggressive than IDT's.
+That means, that the actual cell rate can be slightly higher than the
+specified.
+This is in contrast to the IDT tables where cell rates 5% less than the
+allowed one have been observed.
+This can be changed by changing the program that generates these tables,
+found in
+.Pa /usr/src/sys/dev/patm/genrtab ,
+and regenerating them.
+.Pp
+The reported media for the 155MBit cards will always be OC3/MM, because
+there is no (known to me) way to figure out the actual medium.
+The medium should really be coded in the EEPROM by the manufacturer.
+.Pp
+The Tx cell counter in the utopia statistics is wrong, because the chip
+uses idle cells for spacing and the PHY counts these cells.
+While there is a configuration option for the chip to switch of these cells
+and, according to the documentation, this should not influence cell spacing,
+it does, so the driver lets the chip generate idle cells.