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