Usage instructions  -  ATM on Linux, release 0.6 (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 argument of aread, awrite, br and bw is always the PVC address,
i.e. the ATM interface number, the VPI and the VCI number, with a dot
between each element. The interface number can be omitted if it is zero.
Example:

  % 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.40
  b# clip 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.

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


ILMI demon
----------

The ILMI demon is started as follows:

  # ilmid [-b] [-d]

    -b  background. Run in a forked child process after initializing.
    -d  enables debugging output. By default, ilmid is very quiet.

atmsigd should already be running when ilmid is started, Use the -b
option to make sure they're properly synchronized (see below).

The agent supports only the address registration procedures specified
in section 5.8 of the ATM Forum's UNI 3.1 specification.  These
procedures involve the switch registering the network prefix on the
host and the host registering the final ATM address back on the
switch.  The host accomplishes this by appending an ESI (End System
Identifier) and a null selector byte to the network prefix registered
by the switch.  The ESI is the physical or MAC address of the ATM
interface.

If your switch doesn't support ILMI, you have to set the ATM address
manually on the switch and on the PC(s). Under Linux, use the
atmaddr command to set the address, e.g.

  # atmaddr 47.0005.80.ffe100.0000.f215.1065.0020EA000755.00

atmaddr without arguments shows the current address.

Manual configuration of ATM addresses on the switch depends on the brand.
On a Fore ASX-200, it 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.


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 and ilmid 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
  ilmid -b
  atmarpd -b
  ...

works, but

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

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, ilmid, and atmarpd, 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. 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 arpsrv

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.
