Usage instructions  -  ATM on Linux, release 0.3 (pre-alpha)
------------------------------------------------------------

This is experimental software. There are known major bugs and certainly
even many more yet unknown problems. Internal and external interfaces are
far from being stable. In fact, they change daily. Use at your own risk.


ATM over TCP setup
------------------

If you have no real ATM hardware, you can still exercise the API by using
the ATM over TCP "driver". It emulates ATM devices which are directly
wired to remote devices (i.e. there is no VPI/VCI swapping).

To establish one (bidirectional) "wire", become root on both systems
(or run both sides on the same system to create two connected "interfaces")
and run the following command on one of them:

  # atmtcp -l

Then, on the other system, run

  # atmtcp -c <address_of_other_system>

Both atmtcps will report on their progress and the kernel should display
a message like

  atm1: atmtcp/0 is ready

on each system. Note that atmtcp keeps running and that is must not be
interrupted.

Multiple "wires" can be attached to the same machine by specifying a
port number (default is 8401).


Traffic tools
-------------

aread/awrite and br/bw are simple programs to access the ATM API. awrite
sends the text string passed as its fourth argument in an AAL5 PDU.
aread receives one AAL5 PDU and displays it in hex. Both programs also
display the return values of the corresponding system calls and the
current values of errno.

bw either sends its standard input or a stream of blocks containing
arbitrary data (if a number is passed as its fourth argument) in 8 kB
AAL5 PDUs. br receives AAL5 PDUs and writes them to standard output.

The first three arguments of aread, awrite, br and bw are always the
ATM interface number, the VPI and the VCI number, e.g.

  % atm/awrite 0 0 42 hi

Note that the ENI adapter only supports VPI == 0 and VCIs in the range
0 to 1023. The interface number can be obtained from the initialization
message the driver printed during startup. atm0 is interface 0, atm1 is
interface 1, etc. The ENI155p is normally atm0.

For "real" tests, you should use ttcp. A modified version can be found
in lrcftp.epfl.ch:/pub/linux/atm/ttcp.atm.c  It supports the following
new options:

  -a      use native ATM instead of UDP/TCP. (The address must be in
	  the format vpi.vci  The interface is always 0)
  -P num  use a CBR connection with a peak cell rate of "num" cells per
	  second. Default is to use UBR.
  -C      disable (UDP) checksums

Example:

  %a ttcp.atm -r -a -s 0.90
  %b ttcp.atm -t -a -s 0.90

Additionally, individual cells can be composed and received with the
atmdump program. See the corresponding man page for details.


IP over ATM
-----------

Limited IP over ATM is supported in this release. Please be aware that
it might not interoperate with other implementations, because:

 - InARP is not supported

VCCs are used as IP point to point links, so contrary to what RFC1577
suggests, VCC selection is a routing decision and not a matter of
address resolution.

First, the VCCs have to be established. Become root on both machines
and run the clip program (see also on the man page) on each of them:

  # clip <interface> <vpi> <vci>

e.g.

  a# clip 0 0 40
  b# clip 0 0 40

For CBR connections, specify the desired peak cell rate as the fourth
argument.

Next, the interfaces have to be configured:

  # /sbin/ifconfig atm0 up <src_addr> dstaddr <dst_addr>

e.g.

  a# /sbin/ifconfig atm0 up 1.2.3.4 dstaddr 1.2.3.5
  b# /sbin/ifconfig atm0 up 1.2.3.5 dstaddr 1.2.3.4

Finally, you have to add the routes:

  a# /sbin/route add 1.2.3.5
  b# /sbin/route add 1.2.3.4

Test the connection with ping:

  a% ping 1.2.3.5


ATM diagnostics
---------------

Various counters of the ATM device drivers can be queried with the
atmdiag  program. See the corresponding man page for details.


SONET diagnostics
-----------------

The SONET diagnostics tool can be used to monitor link performance
and to simulate errors. In order to get current SONET statistics,
run it with the interface name as the argument, e.g.

  % sonetdiag atm0

The counters can be reset with the -z option:

  # sonetdiag -z atm0

The following network failures can be simulated:

  sbip	 insert section errors (B1)
  lbip	 insert line errors (B2)
  pbip	 insert path errors (B3)
  frame	 force (RX) frame loss
  los	 insert loss of signal
  lais   insert line alarm indication signal
  pais   insert path alarm indication signal
  hcs    insert HCS errors

A failure is enabled by adding the corresponding keyword on the
command line. The failure is cleared by prefixing the keyword with
a minus sign, e.g.

  a# sonetdiag -z atm0 >/dev/null
  b# sonetdiag -z atm0 >/dev/null
  a# sonetdiag atm0 los
  a# sonetdiag atm0 -los
  b# sonetdiag atm0 | grep BIP
  Section BIP errors:      56200
  Line BIP errors:           342
  Path BIP errors:           152
  a# sonetdiag atm0 | grep FEBE
  Line FEBE:                 342
  Path FEBE:                 152

If any diagnostic error insertions are active, their keywords are
shown when sonetdiag is used to obtain statistics.
