PROSUM
PROATM Adapters on Linux


1. Introduction
===============

The PROATM-V155 and PROATM-E155 adapters are based on the IDT77252 SAR. The
IDT77252 driver provided by the Linux distribution has been developed for 
a competitor card model and does not fully support the Prosum 155 Mbps cards. 
We don't discourage the use of this driver if it can fit your requirements, 
but of course we cannot provide any technical support concerning its usage 
with our cards.

Prosum provides the proatm driver, which is an adaptation of the nicstar
driver. Be aware that this README does not apply to the former nicstar2
driver. 
The proatm driver is compatible with kernel versions 2.6.xx and 3.0.xx.
It supports the following features:

	- all Prosum ATM card models,
	- 16384 VC's
	- vpi_base and vci_base parameters permitting to use any VPI/VCI
	- UBR, CBR, ABR and VBR traffics,
	- AAL5 and AAL0 (IDT AAL0 or raw cells),
	- OAM cells (automatic responses sent by the driver)
	- x86_64 architecture
 
We permanently work to improve the quality of this driver and to follow the 
evolutions of the Linux kernel, so there are frequent updates. We recommend you 
download the latest version of this driver from our web site. You can contact us
at the address below for any problem, or to know the state of the pending 
version.

There are 2 ways for building and installing the proatm driver.

  * The fastest, simplest, and recommended method: building and installing
  	the module from an external folder. The only inconvenience of this method
  	is the module must be built each time you recompile your kernel or drivers. 
  	With this method you cannot statically link the module with the kernel. 

  * Patching the kernel source, configuring and recompiling the kernel and
	modules. This is the cleanest solution, but you need to recompile a lot
	of things and reboot the machine. However the module is perfectly
	integrated into the system.

2. Fast Installation
====================

Copy the files from the CDROM or decompress proatm-linux.tgz into a working
folder. Open a root console into this folder and type:
	
	# make install

Normally, this is enough for building and installing the proatm module. However
there may be some missing files:

- if you get a message telling that the kernel header files are not in any of the
expected locations, into /usr/src, add a link named linux and pointing to the
source of your kernel. For example, suppose the kernel source is into 
/home/alex/linux, then type:

	# cd /usr/src
	# ln -s /home/alex/linux linux 

- if you get a message telling "missing version header file" or
"missing autoconf.h", open a console in the linux kernel folder and type:

	# make prepare
	# make scripts

After "make install" has been successfully completed, the driver is installed
into the current kernel. Load the module typing:

	# modprobe proatm

and check that "lsmod" shows the proatm module.

That's it. You can skip sections 3, and 4. 


3. Building the Kernel and Modules
==================================

NOTE: Please see the Linux Kernel HOWTO if you are not familiar with building
and installing a new kernel,

Follow the procedure below to add proatm to your kernel. We recommend you 
install proatm as loadable module and not statically linked with the kernel,
so that you can easily unload and reload the module.

If you have a recent PROATM CDROM, copy the proatm files from the CDROM
folder "/drivers/Linux/V3xx" into the "drivers/atm" folder of the kernel source
directory (usually /usr/src/linux).
 
If you don't have the CDROM, decompress "proatm-linux.tgz" into linux kernel
folder "drivers/atm".

Into the root of the directory of your kernel source or headers, try
to retrieve the .config file of your current kernel by typing:

	# make oldconfig (or "make cloneconfig" for SUSE)

Check that the .config file you got is somewhat compatible with the running
kernel by comparing its first lines with the print of "uname -r" 

Into the "drivers/atm" folder of the kernel source, open a console and type: 

	# patch < proatm.diff

Make sure that the package ncurses-dev or libncurses5-dev is installed, and
into the root of the kernel source, open a console and type 

	# make menuconfig (or "make xconfig")

Proceed to the kernel configuration as explained into next section 4
"Configuring the kernel".

Then type

	# make prepare
	# make modules_prepare
	# make modules && make modules_install
	# make install

Reboot the machine, select the new kernel. Then, in a console, type 
	
	# modprobe proatm
	# lsmod" 

You should see the proatm module in the printed list.

4. Configuring the Kernel
=========================

In order to have access to the ATM features, enable "Prompt for development
and/or incomplete code/drivers" in Code maturity level options
(CONFIG_EXPERIMENTAL). Enable the options as indicated below.

Into Networking support ---> Networking, enable "Asynchronous Transfer
Mode" (ATM) (EXPERIMENTAL) (CONFIG_ATM)

Select CLIP (recommended), LANE and MPOA according to your needs.

Into Device Drivers ---> Network device support ---> ATM drivers, if the proatm
patch as been applied successfully, you should see:

	"Prosum PROATM-V155 and PROATM-E155" 

Select M (recommended) or * for this option.

We recommend you disable all other ATM drivers if you don't have the
corresponding adapters, especially idt77252 to prevent any conflict with proatm.


5. Driver Compilation Options
=============================

GENERAL_DEBUG in proatm.c allows printing traces for debug purpose.
EXTRA_DEBUG prints even more traces. Don't forget to "undef"  these options and
recompile as soon as the problem is fixed.

Look for the "Options" section in proatm.h.


PROATM_VPIBITS
--------------
Defines the number of bits used to code the VP number.
Default value is 2. Authorized values are 0, 1, 2, or 8. Refer to the table
below giving the VPI and VCI ranges depending on the card memory size and 
the value of PROATM_VPI_BITS:

PROATM_VPIBITS  VPI            VCI (128KB)       VCI (512KB)        VCI (2MB)
------------------------------------------------------------------------------
0               0              0 to 1023         0 to 4095          0 to 16383
1               0, 1           0 to 511          0 to 2047          0 to 8191
2               0, 1, 2, 3     0 to 255          0 to 1023          0 to 4047
8               0 to 255       0 to 3            0 to 15            0 to 63

NOTE: The cards equipped with 128KB memory can support 1024 VCs. The cards
equipped with 512KB memory can support 4096 VCs. The new cards equipped with
2MB memory can support 16384 VCs.


PROATM_VPIBASE and PROATM_VCIBASE
---------------------------------
You cannot transmit and receive on any VCs. The VPI/VCI must be chosen
with regard to PROATM_VPIBITS and the card memory size. (Refer to the above
table). However in certain special cases you may need to use
normally-unreachable VPI/VCI couples such as 8.35 for example. To do that, set
PROATM_VCIBASE and PROATM_VPIBASE according to your needs. For example setting
PROATM_VPIBASE to 8 and PROATM_VCIBASE to 0 would allow you to play with the
8.35 VC.

WARNING: Please be aware that VPIs below PROATM_VPIBASE and VCIs below
PROATM_VCIBASE
are not reachable anymore when you set them to non-zero values.

PROATM_VPIBASE is smaller than 256. It must be a multiple (0 included) of the
number
of VPIs, which depends on PROATM_VPIBITS.

For example, if PROATM_VPIBITS = 2:
	the number of VPIs is limited to 4,
	PROATM_VPIBASE can be set to 0, 4, 8, 12 ... 254.

PROATM_VCIBASE plays for the VCs the same role as PROATM_VPIBASE for the VPs. It
is smaller than 64536 and must be a multiple of the number of VC's that the card
is able to manage.
For example let's suppose the card has 128 KB memory and PROATM_VPIBITS = 2, the
number of VCI bits is 8 (10-2) and thus the number of VCIs is 256, then
PROATM_VPIBASE may be set to any value from among 0, 256, 512 ... 64280.


PROATM_RCQ_SUPPORT
------------------
Enable RAW CELL receipt. You can implement and add your own raw-cell process
into ns_rsqe_process ().

PROATM_BUILD_AAL0_HEADER
------------------------
Specify that the header of AAL0 cells is automatically built by the driver,
according to connection information.
When this option is NOT set (default), according to the Linux ATM API, the
header is simply extracted from the first 4 bytes of each SKB data. The header
is under the application responsibility. Please note that incorrect headers may
hang the driver and the computer. 
When this option is set, the header of AAL0 cells is built by the driver the
same way as the header of AAL5 cells. The first 4 bytes of packets are ignored 
except the GFC and PTI fields.

PROATM_AAL0_TO_RCQ
------------------
Enable all incoming AAL0 cells to produce a receive interrupt regardless of 
the value of the PTI bit. Otherwise only incoming cells with PTI = 1 can trigger
a receive interrupt.


PROATM_PRINT_RAW_CELL_MESSAGE
-----------------------------
Enable raw cell warning message.


PROATM_TST_RESERVED
-------------------
Number of Schedule Table entries (over 2048) that are reserved for non-CBR VCs
(UBR/VBR/ABR)


PROATM_B0BUFSIZE and PROATM_B1BUFSIZE
-------------------------------------
Small buffers and large buffers size. Don't modified these options unless you
know exactly why.


PROATM_SUNI_FULL_SDH
--------------------
By default, the physical interface of PROATM-155 cards implements OC3 and 
partial SDH. This works in most cases. Set this option (#define) to make the 
physical interface implement full SDH - no more OC3 compatible. 

PROATM_OAM_SUPPORT
-----------------
Enable support of F4 and F5, end-to-end and segment OAM cells.

PROATM_LLID
-----------
If you need it, you can write here the 16 bytes of the specific "Loopback
Location ID". Otherwise don't touch this option.

PROATM_USE_WORKQUEUE
--------------------
Use a workqueue to transmit SKBs to upper ATM network layers outside the
interrupt context. This option degrades the ping response-time but improves
the average throughput of small packets. It may also prevent some hardlock 
problems on some architectures. By default this option is NOT enabled.


6. Module Parameters
====================

vpibits, vpibase and vcibase can be assigned at load time by insmod or modprobe.
When specified, these parameters overwrite the default values set by
PROATM_VPIBITS,PROATM_VPIBASE and PROATM_VCIBASE.

    example: modprobe proatm vpibits=1 vpibase=16 vcibase=512

SDH framing can be forced or cleared by using fullsdh. If used, this parameter 
overwrites the PROATM_SUNI_FULL_SDH compilation option.

    example: modprobe proatm fullsdh=1


7. ATM on Linux
===============

Download and install the linux-ATM package from your distribution or from
linux-ATM.sourceforge.net. Do not hesitate to install lib-atm and atm-devel.
Please, carefully read the HOWTO in /usr/share/doc/linux-atm-x.x.x/doc/. 

You can also find a linux-ATM package on Prosum web site. It is basically the
same as which one you can find on linux-ATM.sourceforge.net but it includes a
few options and tools we added for our own needs or for some customers. It
also uses to hang less easily that the distribution or official packages,
especially if the proatm card has been wrongly automatically mounted by the
system at boot time.


8. Using PVC's
==============

If you are NOT using an ATM switch, ie, your PCs are connected 'back-to-back',
you can base your configuration on examples below to quickly start a CLIP
connection on PVC 0.0.32 (UBR).

Note that without an ATM switch, some ATM features such as LAN Emulation and
SVCs are not available. Therefore, only classical IP over ATM, remote PPP
Services and PVC functions are available.

script atmstart on computer1:

 #!/bin/sh
 modprobe proatm
 atmarpd -b
 atmarp -c atm0
 ifconfig atm0 192.168.1.1
 sleep 1
 atmarp -s 192.168.1.2 0.0.32

script atmstart on computer2:

 #!/bin/sh
 modprobe proatm
 atmarpd -b
 atmarp -c atm0
 ifconfig atm0 192.168.1.2
 sleep 1
 atmarp -s 192.168.1.1 0.0.32


Run atmstart on each computer, then you should be able to run any IP application
such as FTP or NFS. Start by "pinging" each computer from the other one.

Note that the two last lines are not mandatory. You may type as many "atmarp -s"
commands by hand as you need. The scripts build a UBR connection with
unspecified PCR. You could type for example something more complex like:

	# atmarp -s 192.168.2.1 0.0.32 qos ubr:pcr=20Mbps 

or

	# atmarp -s 192.168.2.1 0.0.32 qos ubr:pcr=1Mbps

To change the QoS of a connection, first delete it by typing

	# atmarp -d 192.168.2.1

Refer to atmarp(8) and qos(7) man pages to get more explanation.


9. Note on VBR usage
====================

VBR QoS is characterized by using pcr, scr and mbs parameters. So far the
atm_trafprm structure does not provide neither scr nor mbs. We could modify
atm_traf_prm however we found simpler to reuse existing parameters for ABR. 
This makes the job without impacting other ATM layers and drivers. 
So when using VBR VC's, enter :

    - the pcr value into max_pcr, 
    - the scr value into pcr,
    - the mbs value into min_pcr. 

This VBR implementation is intended for writing atm applications that manage 
the qos structure directly since the Linux-atm tools do not provide direct 
support of VBR. You may also add the VBR qos support into qos2text.c and 
text2qos.c and recompile linux-atm. A version of linux-atm supporting VBR
is available on our web site.


10. OAM cells
============

Proatm can process automatically F4 and F5 ATM fault management, loopback,
and continuity check cells. It behaves like an endpoint and generates 
automatically the appropriate response. It also allows sending OAM cells
from applications running in the user space. It does not implement send_oam ()
but instead detects the AAL0 raw-cells that match the VCI/PTI OAM
characteristics.
The CRC10 is automatically generated and put at the end of the OAM cells before
their transmission. So there is no need to compute it into the application. 

Please be aware that OAM cells can be received and sent only on VCs that are 
open for reception and transmission.

The linux-atm package on our web site contains an atmdump tool that has been 
slightly modified to permit an easy generation of any raw cell in hexadecimal.
It can be used to generate all types of OAM cells. 

There is a compilation option into "proatm.h" that permits to enable/disable 
the support of OAM cells. 
You can also define the Loopback Location ID of the ATM interface. However, 
please note that this LLID applies to all PROATM cards into the computer.
 

11. Technical and sales support
==============================

Technical support: Send E-mail to support@prosum.net

Sales and information: (33) 1 45 90 62 70 or E-mail contact@prosum.net

