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 November 22, 2006
  31 .Dt UTOPIA 4
  32 .Os
  33 .Sh NAME
  34 .Nm utopia
  35 .Nd "driver module for ATM PHY chips"
  36 .Sh SYNOPSIS
  37 To compile this driver into the kernel,
  38 place the following line in your
  39 kernel configuration file:
  40 .Bd -ragged -offset indent
  41 .Cd "device utopia"
  42 .Ed
  43 .Pp
  44 Alternatively, to load the driver as a
  45 module at boot time, place the following line in
  46 .Xr loader.conf 5 :
  47 .Bd -literal -offset indent
  48 utopia_load="YES"
  49 .Ed
  50 .Sh DESCRIPTION
  51 This module is used by all ATM drivers for cards that use
  52 PMC-Sierra S/Uni and IDT77105/IDT77155
  53 chips to provide uniform functionality.
  54 The module implements status monitoring
  55 in either interrupt or polling mode, media option handling and application
  56 access to chip registers.
  57 .Pp
  58 The driver implements several sysctls that are accessible under the
  59 .Va hw.atm. Ns Ao Ar iface Ac Ns Va .\&
  60 tree, where
  61 .Ar iface
  62 is the name of the ATM interface:
  63 .Bl -tag -width indent
  64 .It Va phy_regs
  65 When reading this sysctl an array of 8-bit unsigned integers is returned
  66 containing all accessible chip registers starting at register 0.
  67 A register can be written by writing three 8-bit unsigned integers to the
  68 sysctl: the register number, the new value and a bit mask.
  69 This changes all bits in the register for which the corresponding bit in the
  70 mask is one to the bit values from value.
  71 Note that not all registers may
  72 be writeable.
  73 .It Va phy_loopback
  74 allows to put the interface in one of several loopback modes.
  75 Not all modes and all combinations of modes are supported on all chips.
  76 The possible modes are:
  77 .Bl -tag -width indent
  78 .It Dv UTP_LOOP_NONE Pq No 0x00
  79 No loopback, normal operation.
  80 .It Dv UTP_LOOP_TIME Pq No 0x01
  81 Timing source loopback.
  82 When this is set the transmitter's clock is
  83 derived from the receiver's clock.
  84 .It Dv UTP_LOOP_DIAG Pq No 0x02
  85 Diagnostic loopback.
  86 In this mode the receiver's input is connected to the
  87 transmitter's output.
  88 The receiver gets back everything that is sent.
  89 The
  90 transmitter operates normally.
  91 .It Dv UTP_LOOP_LINE Pq No 0x04
  92 Serial line loopback.
  93 This connects the line receiver to the line transmitter.
  94 The chip transmits all cells back that it receives.
  95 The receiver operates
  96 normally.
  97 .It Dv UTP_LOOP_PARAL Pq No 0x08
  98 Parallel diagnostic loopback.
  99 This feeds back all transmitted cells into the
 100 receiver between the parallel/serial converters.
 101 The transmitter
 102 operates normally.
 103 .It Dv UTP_LOOP_TWIST Pq No 0x10
 104 Twisted pair diagnostic loopback.
 105 Connects the high speed receive data to the
 106 high speed transmit data.
 107 All received data is sent back.
 108 The receiver
 109 operates normally.
 110 .It Dv UTP_LOOP_PATH Pq No 0x20
 111 Diagnostic path loopback.
 112 This connects the receiver input to the transmitter
 113 output just between the path overhead processor and the byte mux.
 114 The
 115 transmitter operates normally.
 116 .El
 117 .It Va phy_type
 118 This is the detected type of the phy chip.
 119 Currently the following chips are
 120 supported:
 121 .Bl -tag -width indent
 122 .It Dv UTP_TYPE_UNKNOWN Pq No 0
 123 The module could not determine the type of the PHY chip.
 124 .It Dv UTP_TYPE_SUNI_LITE Pq No 1
 125 PMC-5346 (S/Uni-Lite)
 126 .It Dv UTP_TYPE_SUNI_ULTRA Pq No 2
 127 PMC-5350 (S/Uni-Ultra)
 128 .It Dv UTP_TYPE_SUNI_622 Pq No 3
 129 PMC-5355 (S/Uni-622)
 130 .It Dv UTP_TYPE_IDT77105 Pq No 4
 131 IDT77105 (25.6MBit UTP interface)
 132 .It Dv UTP_TYPE_IDT77155 Pq No 5
 133 IDT77155 (155MBit interface)
 134 .El
 135 .It Va phy_name
 136 This is a string describing the type of the PHY chip.
 137 .It Va phy_stats
 138 Physical and some ATM layer statistics.
 139 These are the statistics usually
 140 provided by the chip.
 141 The data is a returned in the following structure:
 142 .Bd -literal
 143 struct utopia_stats1 {
 144         uint32_t version;       /* version of this struct */
 145         uint32_t fill;
 146         uint64_t rx_sbip;       /* rx section BIP errors */
 147         uint64_t rx_lbip;       /* rx line BIP errors */
 148         uint64_t rx_lfebe;      /* rx line far end block errors */
 149         uint64_t rx_pbip;       /* rx path BIP errors */
 150         uint64_t rx_pfebe;      /* rx path far end block errors */
 151         uint64_t rx_cells;      /* received cells */
 152         uint64_t rx_corr;       /* correctable cell errors */
 153         uint64_t rx_uncorr;     /* uncorrectable cell errors */
 154         uint64_t rx_symerr;     /* symbol errors */
 155         uint64_t tx_cells;      /* transmitted cells */
 156 };
 157 .Ed
 158 .Pp
 159 The current version is 1.
 160 The statistics are updated from the chip once
 161 a second.
 162 On overflow the counters wrap to zero.
 163 Note that not all counters
 164 are meaningful for all PHY chips.
 165 The statistics are cleared by writing an
 166 arbitrary new value (the value is ignored).
 167 .El
 168 .Pp
 169 The
 170 .Nm
 171 module also interfaces with the ifmedia system.
 172 The module reports the current state of the carrier and will issue a
 173 warning message when the carrier state changes.
 174 While the physical media itself cannot be changed, several media options can:
 175 .Bl -tag -width indent
 176 .It Cm SDH
 177 If the PHY is a Sonet/SDH chip this flag switches the interface into SDH mode.
 178 If this option is not set (the default) the interface is in Sonet mode.
 179 .It Cm noscramb
 180 If the PHY is a Sonet/SDH chip disable scrambling.
 181 This may be useful for debugging purposes.
 182 .It Cm unassigned
 183 Normally the interface emits idle cells when there are no other cells to
 184 transmit.
 185 This changes the default cell type to unassigned cells.
 186 This
 187 may be needed for interworking with public networks.
 188 .El
 189 .Sh SEE ALSO
 190 .Xr en 4 ,
 191 .Xr fatm 4 ,
 192 .Xr hatm 4 ,
 193 .Xr patm 4 ,
 194 .Xr utopia 9
 195 .Sh AUTHORS
 196 .An Harti Brandt Aq harti@FreeBSD.org