share/man/man4/utopia.4

   1 .\" Copyright (c) 2003
   2 .\"     Fraunhofer Institute for Open Communication Systems (FhG Fokus).
   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.
  10 .\" 2. Redistributions in binary form must reproduce the above copyright
  11 .\"    notice, this list of conditions and the following disclaimer in the
  12 .\"    documentation and/or other materials provided with the distribution.
  13 .\"
  14 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
  15 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  16 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  17 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
  18 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  19 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  20 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  21 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  22 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  23 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  24 .\" SUCH DAMAGE.
  25 .\"
  26 .\" Author: Hartmut Brandt <harti@FreeBSD.org>
  27 .\"
  28 .\" $FreeBSD$
  29 .\"
  30 .Dd May 8, 2003
  31 .Dt UTOPIA 4
  32 .Os
  33 .Sh NAME
  34 .Nm utopia
  35 .Nd "driver module for ATM PHY chips"
  36 .Sh SYNOPSIS
  37 .Cd device utopia
  38 .Sh DESCRIPTION
  39 This module is used by all ATM drivers for cards that use
  40 PMC-Sierra S/Uni and IDT77105/IDT77155
  41 chips to provide uniform functionality.
  42 The module implements status monitoring
  43 in either interrupt or polling mode, media option handling and application
  44 access to chip registers.
  45 .Pp
  46 The driver implements several sysctls that are accessible under the
  47 .Va hw.atm. Ns Ao Ar iface Ac Ns Va .\&
  48 tree, where
  49 .Ar iface
  50 is the name of the ATM interface:
  51 .Bl -tag -width indent
  52 .It Va phy_regs
  53 When reading this sysctl an array of 8-bit unsigned integers is returned
  54 containing all accessible chip registers starting at register 0.
  55 A register can be written by writing three 8-bit unsigned integers to the
  56 sysctl: the register number, the new value and a bit mask.
  57 This changes all bits in the register for which the corresponding bit in the
  58 mask is one to the bit values from value.
  59 Note that not all registers may
  60 be writeable.
  61 .It Va phy_loopback
  62 allows to put the interface in one of several loopback modes.
  63 Not all modes and all combinations of modes are supported on all chips.
  64 The possible modes are:
  65 .Bl -tag -width indent
  66 .It Dv UTP_LOOP_NONE Pq No 0x00
  67 No loopback, normal operation.
  68 .It Dv UTP_LOOP_TIME Pq No 0x01
  69 Timing source loopback.
  70 When this is set the transmitter's clock is
  71 derived from the receiver's clock.
  72 .It Dv UTP_LOOP_DIAG Pq No 0x02
  73 Diagnostic loopback.
  74 In this mode the receiver's input is connected to the
  75 transmitter's output.
  76 The receiver gets back everything that is sent.
  77 The
  78 transmitter operates normally.
  79 .It Dv UTP_LOOP_LINE Pq No 0x04
  80 Serial line loopback.
  81 This connects the line receiver to the line transmitter.
  82 The chip transmits all cells back that it receives.
  83 The receiver operates
  84 normally.
  85 .It Dv UTP_LOOP_PARAL Pq No 0x08
  86 Parallel diagnostic loopback.
  87 This feeds back all transmitted cells into the
  88 receiver between the parallel/serial converters.
  89 The transmitter
  90 operates normally.
  91 .It Dv UTP_LOOP_TWIST Pq No 0x10
  92 Twisted pair diagnostic loopback.
  93 Connects the high speed receive data to the
  94 high speed transmit data.
  95 All received data is sent back.
  96 The receiver
  97 operates normally.
  98 .It Dv UTP_LOOP_PATH Pq No 0x20
  99 Diagnostic path loopback.
 100 This connects the receiver input to the transmitter
 101 output just between the path overhead processor and the byte mux.
 102 The
 103 transmitter operates normally.
 104 .El
 105 .It Va phy_type
 106 This is the detected type of the phy chip.
 107 Currently the following chips are
 108 supported:
 109 .Bl -tag -width indent
 110 .It Dv UTP_TYPE_UNKNOWN Pq No 0
 111 The module could not determine the type of the PHY chip.
 112 .It Dv UTP_TYPE_SUNI_LITE Pq No 1
 113 PMC-5346 (S/Uni-Lite)
 114 .It Dv UTP_TYPE_SUNI_ULTRA Pq No 2
 115 PMC-5350 (S/Uni-Ultra)
 116 .It Dv UTP_TYPE_SUNI_622 Pq No 3
 117 PMC-5355 (S/Uni-622)
 118 .It Dv UTP_TYPE_IDT77105 Pq No 4
 119 IDT77105 (25.6MBit UTP interface)
 120 .It Dv UTP_TYPE_IDT77155 Pq No 5
 121 IDT77155 (155MBit interface)
 122 .El
 123 .It Va phy_name
 124 This is a string describing the type of the PHY chip.
 125 .It Va phy_stats
 126 Physical and some ATM layer statistics.
 127 These are the statistics usually
 128 provided by the chip.
 129 The data is a returned in the following structure:
 130 .Bd -literal
 131 struct utopia_stats1 {
 132         uint32_t version;       /* version of this struct */
 133         uint32_t fill;
 134         uint64_t rx_sbip;       /* rx section BIP errors */
 135         uint64_t rx_lbip;       /* rx line BIP errors */
 136         uint64_t rx_lfebe;      /* rx line far end block errors */
 137         uint64_t rx_pbip;       /* rx path BIP errors */
 138         uint64_t rx_pfebe;      /* rx path far end block errors */
 139         uint64_t rx_cells;      /* received cells */
 140         uint64_t rx_corr;       /* correctable cell errors */
 141         uint64_t rx_uncorr;     /* uncorrectable cell errors */
 142         uint64_t rx_symerr;     /* symbol errors */
 143         uint64_t tx_cells;      /* transmitted cells */
 144 };
 145 .Ed
 146 .Pp
 147 The current version is 1.
 148 The statistics are updated from the chip once
 149 a second.
 150 On overflow the counters wrap to zero.
 151 Note that not all counters
 152 are meaningful for all PHY chips.
 153 The statistics are cleared by writing an
 154 arbitrary new value (the value is ignored).
 155 .El
 156 .Pp
 157 The
 158 .Nm
 159 module also interfaces with the ifmedia system.
 160 The module reports the current state of the carrier and will issue a
 161 warning message when the carrier state changes.
 162 While the physical media itself cannot be changed, several media options can:
 163 .Bl -tag -width indent
 164 .It Cm SDH
 165 If the PHY is a Sonet/SDH chip this flag switches the interface into SDH mode.
 166 If this option is not set (the default) the interface is in Sonet mode.
 167 .It Cm noscramb
 168 If the PHY is a Sonet/SDH chip disable scrambling.
 169 This may be useful for debugging purposes.
 170 .It Cm unassigned
 171 Normally the interface emits idle cells when there are no other cells to
 172 transmit.
 173 This changes the default cell type to unassigned cells.
 174 This
 175 may be needed for interworking with public networks.
 176 .El
 177 .Sh SEE ALSO
 178 .Xr en 4 ,
 179 .Xr fatm 4 ,
 180 .Xr hatm 4 ,
 181 .Xr patm 4 ,
 182 .Xr utopia 9
 183 .Sh AUTHORS
 184 .An Harti Brandt Aq harti@FreeBSD.org