Usage instructions  -  ATM on Linux, release 0.4 (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

  atmtcp/0 (itf 1) 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 the modified version of ttcp that comes
with this package. The original is on ftp.sgi.com in /sgi/src/ttcp. The
following options have been added:

  -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 ATM interface number as the argument, e.g.

  % sonetdiag 0

The counters can be reset with the -z option:

  # sonetdiag -z 0

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 0 >/dev/null
  b# sonetdiag -z 0 >/dev/null
  a# sonetdiag 0 los
  a# sonetdiag 0 -los
  b# sonetdiag 0 | grep BIP
  Section BIP errors:      56200
  Line BIP errors:           342
  Path BIP errors:           152
  a# sonetdiag 0 | 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.


Signaling demon
---------------

The signaling demon is started as follows

  # atmsigd [-d] [-n]

    -d  enables (lots of) debugging output. By default, atmsigd is
	comparably quiet.
    -n  makes atmsigd behave like the network side of the UNI (useful
	if you have two PCs but no switch). Normally, it acts as the
	user side.

If atmsigd is killed, all system calls requiring interaction with it
will return errors.

Note that atmsigd provides only very limited functionality and not all
messages conform to UNI 3.0 yet (e.g. it never generates a Cause IE,
it never sends the calling party number, it doesn't generate BLLI,
etc.). Signaling is known to work with a Fore ASX-200 switch.

Note that atmsigd is configured to be paraniod. If it detects any
unusual problems, it terminates. This will (obviously) change in the
future.

atmsigd also uses a configuration file, but that hasn't been tested
yet.

Note that ILMI is not supported yet, so you have to assign NSAP
addresses manually. The NSAP address(s) of the PC(s) have to be
configured at the switch. On a Fore ASX-200, this can be done with the
following command:

  conf nsap route new <nsap_addr> 152 <port> <vpi>

E.g.

  conf nsap route new 47000580ffe1000000f21510650020ea000ee000 152 1a2 0
		      |<---- NSAP prefix ----->||<--ESI--->|^^
							    SEL

The entire NSAP address always has to have a length of 40 characters.
Note you can also use addresses with a different prefix and an ESI that
doesn't correspond to any ESI your adapters have. The value of the
selector byte (SEL) is ignored.

The svc program is used to test SVCs:

  svc <nsap_addr>

attempts to set up a call to the specified destination (BHLI and BLLI
are omitted, so most end system will refuse such calls).

  svc

listens for incoming calls (with any BHLI/BLLI) and accepts them.

Note that the kernel generates a lot of debugging messages (e.g.
"sigd_send ...", "sigd_enq ...") when signaling is used.
