
                       Interphase (i) Corporation
                            README ME FIRST

--------------------------------------------------------------------------------
                       Read This Before You Begin
--------------------------------------------------------------------------------

DESCRIPTION
-----------

This is the README file for the Interphase 5575 Linux ATM driver.

The features and limitations of this driver are as follows:

    - A single VPI (VPI value of 0) is supported.
    - UBR, ABR and CBR service categories are supported.
    - Only AAL5 is supported. 
    - Supports setting of PCR on the VCs. 
    - Multiple adapters in a system are supported.
    - All variants of 5575 are supported.
      (See: http://www.iphase.com/products/DataSheet.cfm?ProductNumber=5575)
    - Only x86 platforms are supported.
    - SMP is not supported.


This directory contains the following files:

    readme.ia:
        This file.

    ia.tar.gz:
        This file contains the binary Linux ATM driver (IA) and the ABR
        patches. To use this driver the kernel should be built with the
        Linux version 2.2.5 or above and Linux ATM software 0.57 or above
        with the patches included.
 
    linux-atm-ia-2.2.5-57-1.RH51.i386.rpm:
    linux-atm-ia-2.2.5-57-1.RH60.i386.rpm:
        These are the Linux RPM packages. These packages contain ATM-capable
        Linux kernel and ATM tools built with Linux version 2.2.5, ATM
        tools version 0.57 and ABR patches developed by Interphase. These
        packages can be used to avoid building a new kernel with the ATM
        capabilities on RedHat 5.1, 5.2 and 6.0 distributions. The package,
        linux-atm-ia-2.2.5-57-1.RH51.i386.rpm, is for RedHat 5.1 and 5.2
        distributions. The package, linux-atm-ia-2.2.5-57-1.RH60.i386.rpm,
        is for RedHat 6.0 distribution.


BEFORE YOU START
----------------


INSTALLATION
------------

1. Installing the adapters in the system

       To install the ATM adapters in the system, follow the steps below.

       a. Login as root.

       b. Shut down the system and power off the system.

       c. Install one or more ATM adapters in the system.

       d. Connect each adapter to a port on an ATM switch. The green 'Link'
          LED on the front panel of the adapter will be on if the adapter is
          connected to the switch properly when the system is powered up.

       e. Power on and boot the system.


2. RPM package installation and system configuration

       Follow the steps below to install the RPM package and configure the
       system.
  
       a. Login as root.

       b. Go the directory that contains the RPM package.

       c. To install the RPM package, type:
  
             rpm -ivh linux-atm-ia-2.2.5-57-1.RHXX.i386.rpm

          To display which files are installed, type:
           
             rpm -ql linux-atm-ia
  
       d. To make a boot image of the new kernel, type:
  
             mkinitrd /boot/initrd-2.2.5-57.img 2.2.5-57
  
       e. Edit the file /etc/lilo.conf. Add the following boot section to
          the file. To boot the linux-atm kernel by default, make
          this the first boot section in the file.
          
             image=/boot/vmlinuz-2.2.5-57
             lable=linux-atm
             root=<boot device>
             initrd=/boot/initrd-2.2.5-57.img
             read-only
  
          Where <boot device> is a boot device where the kernel image
          resides, for example, /dev/sda1.
  
       f. Run the following command:
  
             lilo -v
  
       g. Reboot the system.
  
       NOTE: If the system fails to boot or does not contain all the drivers
             or other features that you require, you will need to rebuild 
             the kernel. The source for the kernel can be found at the
             following sites:

                 - http://icawww1.epfl.ch/linux-atm
                 - http://www.kernel.org

3. Load the adapter hardware driver (ia driver)

       a. Login as root.

       b. Change directory to /root/ia.

       c. If the system is booted with the kernel distributed with the RPM
          package, run the following command to load the ATM driver:

              insmod ia.o

          Or, if the system is booted from another kernel image, run
          the following command:

              insmod -f ia.o

          The yellow 'status' LED on the front panel of the adapter will 
          blink while the driver is loaded in the system.

       d. To verify that the 'ia' driver is loaded successfully, run the
          following command:

              cat /proc/atm/devices

          If the driver is loaded successfully, the output of the command
          will be similar to the following lines:

              Itf Type    ESI/"MAC"addr AAL(TX,err,RX,err,drop) ...
               0   ia      xxxxxxxxx  0 ( 0 0 0 0 0 )  5 ( 0 0 0 0 0 )

          You can also check the system log file /var/log/messages for 
          messages related to the ATM driver.


4. Ia Driver Configuration
       
   4.1 Rebuild kernel with ABR support

       The two ABR patches must be applied to the linux kernel. The linux
       kernel in the RPM packages provided by Interphase have had the ABR 
       patches applied to them.

       a. Apply abr_atm-0.57.patch patch

          The patch file, abr_atm-0.57.patch, should be applied from the
          root directory of atm-0.57 by typing the following:
          
              patch -p1 < <IA_DIR>/abr_atm-0.57.patch

          Where <IA_DIR> is the full pathname of the directory where the
          patch is located.

       b. Apply abr_atm_kernel-2.2.5.patch patch

          The patch file, abr_atm_kernel-2.2.5.patch, should be applied
          from the root directory of linux-2.2.5 by typing the following:

              patch -p1 < <IA_DIR>/abr_atm_kernel-2.2.5.patch

       c. Load the driver

          To load the 'ia' driver, type:

              insmod -f <IA_DIR>/ia.o

   4.2 Configuration of adapter buffers
         
       The 5575 board has 3 different packet RAM size variants: 128K, 512K 
       and 1M. The RAM size decides the number of buffers and buffer size. 
       The default size and number of buffers are set as following:
 
          Totol    Rx RAM   Tx RAM   Rx Buf   Tx Buf   Rx buf   Tx buf
         RAM size   size     size     size     size      cnt      cnt
         --------  ------   ------   ------   ------   ------   ------
           128K      64K      64K      10K      10K       6        6
           512K     256K     256K      10K      10K      25       25
             1M     512K     512K      10K      10K      51       51

       These setting should work well in most environments, but can be
       changed by typing the following command: 
 
           insmod <IA_DIR>/ia.o IA_RX_BUF=<RX_CNT> IA_RX_BUF_SZ=<RX_SIZE> \
                   IA_TX_BUF=<TX_CNT> IA_TX_BUF_SZ=<TX_SIZE>

       Where:
            RX_CNT   = number of receive buffers in the range (1-128)
            RX_SIZE  = size of receive buffers in the range (48-64K)
            TX_CNT   = number of transmit buffers in the range (1-128)
            TX_SIZE  = size of transmit buffers in the range (48-64K)

       Note:
            1. Transmit and receive buffer size must be a multiple of 4.
            2. Care should be taken so that the memory required for the
               transmit and receive buffers is less than or equal to the
               total adapter packet memory.   

   4.3 Ia Debug Tool - iadbg

      iadbg is an application program to help in debugging the 'ia' driver.
      When the iadbg runs without any option, the following menu will be
      displayed on the screen:

  		IA Driver Debugging Options
		===========================
	  IF_INIT ------------- (On: 1    Off: 2)
	  IF_EVENT ------------ (On: 3    Off: 4)
	  IF_TXPKT ------------ (On: 5    Off: 6)
	  IF_RXPKT ------------ (On: 7    Off: 8)
	  IF_CBR -------------- (On: 9    Off: 10)
	  IF_ABR -------------- (On: 11   Off: 12)
	  IF_ERR -------------- (On: 13   Off: 14)
	  ALL    -------------- (On: 15   Off: 16)
	  Done   -------------- ( 0 ) Make ioctl call
	  Exit   -------------- ( 17 )    

      The desired debugging information can be obtained by enabling the 
      corresponding option. Multiple options may be selected. After the
      selection is made (one or multiple) from the list, enter '0' to
      issue the command.

5. Configuring and starting the ATM software

       The Linux ATM software is still under development and is considered
       experimental. This ATM software is owned by the linux-atm work group
       under GPL. The web site (http://icawww1.epfl.ch/linux-atm) has a
       description of the features of this software.

       You may go to the Linux ATM newsgroup (linux-atm@lrc.di.epfl.ch)
       if you have questions or need help with the ATM software.

       You should read the USAGE file under the root directory of the
       atm-0.57 distribution before doing the configuration. To configure
       the ATM software, follow the steps below.

       This section shows the manual steps to start the various ATM
       software entities. It is not necessary to do ATM configuration
       manually every time the system is booted. These manual steps
       can be useful to isolate problems and to get a good understating
       of software configuration. 

       'Ia' driver must be loaded to start the ATM entities such as signaling,
       LAN Emulation clients, etc.

       The following configuration description is only for one ATM adapter,
       or the first ATM adapter in a system with multiple ATM adapters. For
       multiple ATM adapter configurations, the steps for each adapter are
       same, but the physical interface and local interface number vary in
       the related daemon command line options. Please refer to the ATM tool 
       man pages for the configuration.     

   5.1 Configuring and starting the UNI software

       a. Configure the ATM UNI version
 
          Both sides on the UNI - the user side and the network side -
          must be configured to the same UNI version. To add (or modify)
          the UNI version on the system, edit the file /etc/atmsigd.conf.
          Add (or modify) the following line in this file:

              sig uni<xx>

          Where the valid values of <xx> are 30, 31 or 40.

       b. Start the signaling daemon by running the following command:

              atmsigd -b

          Or, you may run the signaling daemon in the debug mode by
          running the following command:


              atmsigd -d

          The signaling daemon can be stopped by removing the process
          associated with the daemon and started again. See man page for 
          atmsigd for more features and options.

       c. Start the ILMI daemon by running the following command:  

              ilmid -b

          Or, you may run the ILMI daemon in the debug mode by running
          the following command:

              ilmid -d

          See man page for ilmid for more features and options. 

   5.2 Configuring and starting LAN Emulation
    
          Signaling and ILMI daemons must be running to start LAN Emulation.
          Also, LAN Emulation services must be running on the ATM network
          for LAN Emulation clients to come up and be able to transmit and
          receive data.

          Multiple LAN Emulation clients (LEC) can be configured on each
          physical ATM interface. The command below shows how to configure
          one LEC on an ATM interface. See the man page for 'zeppelin'
          to configure multiple LECs and other details.

              zeppelin -n <VLAN_name>

          Where <VLAN_name> is the name of ELAN that the LEC is to join.
          If the LECS is not at the 'well known address' (WKA), the LECS
          address can be specified with the '-c' option in the zeppelin
          command.

          To verify the status of the LEC, run the following command:

              cat /proc/atm/svc

          The network interface must now be configured before the data
          packets can be transmitted and received over the LANE. To configure
          the network interface, run the following command:

              ifconfig lec0 <IP> netmask <NETMASK> broadcast <BROADCAST> up

          Where:
               IP        = IP address of the interface
               NETMASK   = Netmask of the interface
               BROADCAST = Broadcast IP address for this interface

          'Ping' program can now be used to test the network connectivity
          of the configured interface. 

   5.3 Configuring and starting Classical IP
    
          Signaling and ILMI daemons must be running to start the classical
          IP (CIP) client. Also, CIP ARP server must be running on the ATM
          network for the classical IP client to come up.

          Start atmarpd daemon, type:
   
              atmarpd -b

          Multiple CIP clients can be configured on each physical ATM
          interface. The command below shows how to configure one CIP client
          on an ATM interface. See the man page for 'atmarp' to configure
          multiple CIP clients and other details.
             
              atmarp -c atm0

          Connect to the ARP server by typing the following command:

              atmarp -s <IP> <ATM> arpsrv
 
          Where:
               IP  = IP address of the ARP server
               ATM = ATM address of the ARP server

          To verify the status of the CIP client, run the following command:

              cat /proc/atm/svc

          The network interface must now be configured before the data
          packets can be transmitted and received over the CIP client. To
          configure the network interface, run the following command.

              ifconfig atm0 <IP> netmask <NETMASK> broadcast <BROADCAST> up

          Where:
               IP        = IP address of the interface
               NETMASK   = Netmask of the interface
               BROADCAST = Broadcast IP address for this interface

          'Ping' program can now be used to test the network connectivity
          of the configured interface. 


6. ATM startup script

       As discussed above, the ATM configuration can be done through the
       scripts. Once the scripts are setup, the ATM entities are started
       automatically at system bootup.

       'Ia' driver must be loaded to start the ATM entities. 

       Setting up the scripts require editing several files.

       a. Edit the file /etc/sysconfig/atm 

          Add the following lines to enable ATM, LANE and IPATM:

              ATM=yes
              LANE=yes
              IPATM=yes

       b. LEC configuration files

          In the /etc/sysconfig/network-scripts, add a configuration file
          ( ifcfg-lec<n> ) for each LEC. Where <n> is the LEC number. The
          configuration file for the first LEC is installed with the package.  
          This file should be modified for the desired LEC configuration.
          This file can be duplicated and modified for the other LECs.

       c. IPATM configuration files

          In the /etc/sysconfig/network-scripts, add a configuration file
          ( ifcfg-atm<n> ) for each CIP client. Where <n> is the client number.
          The configuration file for the first client is installed with the
          package. This file should be modified for the desired client
          configuration. This file can be duplicated and modified for the
          other clients.

        d. After the configuration above is done, the LANE and/or CIP 
           client(s) can start or stop by the script, /usr/bin/ATM.
           
               ATM start  - to start ATM service

               ATM stop   - to stop ATM service

           After the script is tested, you may choose to start the ATM
           service automatically by appending the line 
     
                      "insmod <-f> /root/ia.o ; ATM start"
 
           to /etc/rc.d/rc.local.


7. Ia Driver Test Using ttcp_atm and PVC

   For the PVC setup, the test machines can either be connected back-to-back
   or through a switch. If connected through the switch, the switch must
   be configured for the PVC(s).

   a. For UBR test:

      At the test machine intended to receive data, type:

         ttcp_atm -r -a -s 0.100 

      At the other test machine, type:

         ttcp_atm -t -a -s 0.100 -n 10000

      Run "ttcp_atm -h" to display more options of the ttcp_atm tool.

   b. For ABR test:

      It is the same as the UBR testing, but with an extra command option:

         -Pabr:max_pcr=<xxx>

         where:
             xxx = the maximum peak cell rate, from 170 - 353207.

         This option must be set on both the machines.

   c. For CBR test:
     
      It is the same as the UBR testing, but with an extra command option:

         -Pcbr:max_pcr=<xxx>

         where:
             xxx = the maximum peak cell rate, from 170 - 353207.

         This option may only be set on the trasmit machine.



OUTSTANDING ISSUES
------------------



CONTACT INFORMATION
-------------------

    Customer Service:

        United States:  Telephone:      (214) 654-5555
                        Fax:            (214) 654-5500
                        E-Mail:         intouch@iphase.com

        Europe:         Telephone:      + 33 (0) 1 41 15 44 00
                        Fax:            + 33 (0) 1 41 15 12 13


    World Wide Web:     http://www.iphase.com

    Anonymous FTP:      ftp.iphase.com
