Usage instructions  -  ATM on Linux, release 0.5 (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 using the clip program
mechanism. 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.

For a better but still immature mechanism see the section "ATMARP demon"
at the end of this file.

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 [-b] [-d] [-n]

    -b  background. Run in a forked child process after initializing.
    -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.1 yet. 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. You can
silence it by changing the line

#define DPRINTK printk

to

#define DPRINTK (void)

in net/atm/svc.c and net/atm/signaling.c


ATMARP demon
------------

The ATMARP demon is started as follows

  # atmarpd [-b] [-d]

    -b  background. Run in a forked child process after initializing.
    -d  enables (lots of) debugging output. By default, atmarpd is
	comparably quiet.

atmsigd must already be running when atmarpd is started. Use the -b
option to make sure they're properly synchronized, e.g.

  #!/bin/sh
  atmsigd -b
  atmarpd -b
  atmarp ...

works, but

  #!/bin/sh
  atmsigd &
  atmarpd &
  atmarp ...

frequently doesn't.

atmarpd implements something like ATMARP as defined in RFC1577 and
RFC1755. There are still several known errors and protocol violations.
(And probably a lot of unknown problems too.)

The atmarp program is used to configure ATMARP. First, you have to
start atmsigd and armarpd, then create an IP interface and configure
it:

  # atmarp -c <interface_name>
  # ifconfig atm0 <local_address> <possibly_more_options> up
  # route add -net <network_address>

e.g.

  # atmarp -c atm0
  # ifconfig atm0 1.2.3.3 up
  # route add -net 1.0.0.0

If only PVCs will be used, they can now be created with

  # atmarp -s <ip_address> <pvc_address> [perm|null]

e.g.

  # atmarp -s 1.2.3.4 0.0.70 perm

(Note: "null" to indicate NULL encapsulation is not implemented yet.)
Permanent entries will never time out and therefore do not generate any
ARP traffic.

When using SVCs, some additional configuration work is necessary. First,
you have to set the local ATM address. This is done by creating an
ATMARP entry with the IP address set to the network address and the
local ATM address:

  # atmarp -s <network_address> <local_atm_address>

e.g.

  # atmarp -s 1.0.0.0 47.0005.80.ffe100.0000.f215.1065.0020EA000755.00

If the machine is acting as an ATMARP server on that LIS, no additional
configuration is necessary. Otherwise, the ATM address of the ATMARP
server has to be configured. This is done by creating an entry for the
network address with the option "atmarp" set:

  # atmarp -s <network_address> <atm_address_of_server> arpsrv

e.g.

  # atmarp -s 1.0.0.0 47.0005.80.ffe100.0000.f215.1065.0020EA000756.00

Note that the ATMARP server currently has to be started and configured
_before_ any clients are configured.

Additional SVC entries can be created with

  # atmarp -s <ip_address> <atm_address>

There is also a "perm" option for SVCs, but that one doesn't work yet.
Therefore, manually added SVC entries aren't very useful.

  # atmarp -d <ip_address>

deletes ARP entries.

The kernel ATMARP table can be read via /proc/atm/arp (the "ATM address"
field is always empty.) The table used by atmarpd is regularly printed if
atmarpd is started with the -d option.
