Linux ATM driver for Solos PCI Multiport ADSL2+ Modem
=====================================================

Last modified : 16/May/2010

Guy Ellis <guy@traverse.com.au>
Nathan Williams <nathan@traverse.com.au>

Copyright (C) 2008-2010 Traverse Technologies

This package is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation; either version 2 of the License, or
(at your option) any later version.

This package is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License along
with this package; if not, write to the Free Software Foundation, Inc.,
51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.

Please see COPYING.GPL for the full license.


Introduction
------------

The Solos PCI multiport ADSL2+ modem has been designed by Traverse
Technologies.  Each ADSL port is controlled by a Conexant Solos D ADSL2+
chipset, which interfaces to the PCI bus through an FPGA.

This document describes how to install, compile and configure the Solos PCI
ADSL2+ GPL Linux drivers.  This driver is compatible with Linux kernel versions
2.6.23 and later.  Please note that sysfs parameters are disabled in versions
earlier than 2.6.25.

The Solos driver is also included in Linux kernel versions 2.6.29 and later.
Patches for the source in kernel 2.6.29 and 2.6.30 can be found in the
directory `kernel-patches'.  These patches add support for the latest Solos
cards.


Table of Contents
-----------------
1. Kernel preparation
2. ATM utilities and libraries
3. Bridging (RFC1483 / RFC2684) Utility for Bridged Ethernet
4. PPPoA
5. PPPoE
6. Untar and Compile the driver
7. Showtime
8. Firmware and FPGA Upgrades
9. References and further reading


1. Kernel preparation
---------------------

Fortunately the 2.6 kernels include ATM support so normally no kernel patching
is required.  However you may need to recompile your kernel if you don't have
ATM support enabled.  If you are not sure, check your kernel .config file for
the following...

CONFIG_ATM=y
# CONFIG_ATM_CLIP is not set
# CONFIG_ATM_LANE is not set
CONFIG_ATM_BR2684=y

If not run make menuconfig and set the following under
Networking Options...

[M] Asynchronous Transfer Mode (ATM) (EXPERIMENTAL)
[ ]   Classical IP over ATM
< >   LAN Emulation (LANE) support
<M>   RFC1483/2684 Bridged protocols

Firmware loading support is required for FPGA and ADSL firmware updates
Check for the following in your .config file...

CONFIG_FW_LOADER=y

If not run make menuconfig and set the following under
Device Drivers ---> Generic Driver Options...

[*] Userspace firmware loading support

For PPPoA (RFC2364) you must also have the following set in your .config
file...

CONFIG_PPPOATM=m

If not run make menuconfig and set the following under
Network device support...

<M> PPP (point-to-point protocol) support
[*]   PPP multilink support (EXPERIMENTAL)
[*]   PPP filtering
<M>   PPP support for async serial ports
<M>   PPP support for sync tty ports
<M>   PPP Deflate compression
<M>   PPP BSD-Compress compression
<M>   PPP over Ethernet (EXPERIMENTAL)
<M>   PPP over ATM (EXPERIMENTAL)

If the required options are not set you will need to set them and recompile
your kernel.  If you don't know how to do this please read the Kernel Rebuild
Guide at...

http://www.digitalhermit.com/linux/Kernel-Build-HOWTO.html


2. ATM utilities and libraries
------------------------------

Fedora : install the linux-atm package
Debian : install the libatm1-dev package
Source : linux-atm-2.5.0.tar.gz from http://sourceforge.net/projects/linux-atm


3. Bridging (RFC1483 / RFC2684) Utility for Bridged Ethernet
------------------------------------------------------------

If you plan to use RFC1483 you will need br2684ctl.

Fedora : supplied with the linux-atm package
Debian : install the br2684ctl package
Source : supplied with linux-atm-2.5.0.tar.gz


4. PPPoA
--------

Fedora : install the ppp package
Debian : install the ppp package
Source : ppp-2.4.4.tar.gz from ftp://ftp.samba.org/pub/ppp/

5. PPPoE
--------

Download rp-pppoe-3.10.tar.gz from http://www.roaringpenguin.com/products/pppoe


5.1 Install

  $ tar -xvzf rp-pppoe-3.10.tar.gz
  $ cd rp-pppoe-3.10
  $ ./configure --enable-plugin=$PPPDIR
  $ make
  $ make install

Note $PPPDIR is the ppp directory on your system, eg. /usr/local/lib/pppd/2.4.4

6. Untar and Compile the driver
-------------------------------

6.1 Untar the driver

  $ tar -xvzf solos-pci-x.xx.tar.gz
  $ cd solos-pci-x.xx

6.2 Compile

  $ make clean
  $ make


7. Showtime
-----------

IMPORTANT : The following examples use Vpi = 0, Vci = 38 which are the common
PVC values for the UK.  Other countries & providers are different, so check
with your provider first.

For Bridged Ethernet (RFC1483)...

  $ modprobe atm
  $ insmod solos-pci.ko
  $ br2684ctl -b -s 2040 -c 0 -a 0.0.38
  $ ifconfig nas0 203.123.69.1 up

and for the second port...

  $ br2684ctl -b -s 2040 -c 1 -a 1.0.38
  $ ifconfig nas1 203.123.69.2 up


For PPPoA (RFC2364)...

  $ modprobe atm
  $ modprobe pppoatm
  $ insmod solos-pci.ko
  $ pppd plugin pppoatm.so 0.0.38 user test password test noauth

and for the second port...

  $ pppd plugin pppoatm.so 1.0.38 user test2 password test2 noauth


For PPPoE...

  $ modprobe atm
  $ insmod solos-pci.ko
  $ br2684ctl -b -s 2040 -c 0 -a 0.0.38
  $ ifconfig nas0 up
  $ pppd plugin rp-pppoe.so nic-nas0 user test password test noauth

and for the second port...

  $ br2684ctl -b -s 2040 -c 1 -a 1.0.38
  $ ifconfig nas1 up
  $ pppd plugin rp-pppoe.so nic-nas1 user test2 password test2 noauth


8. Firmware and FPGA Upgrades
-----------------------------

The Solos PCI multiport ADSL2+ modem has two types of flash upgrades.
The modem firmware flash upgrade


8.1 Modem Firmware Flash Upgrade

Copy the firmware binary image to:

  /lib/firmware/solos-Firmware.bin

Reload the driver with the firmware upgrade module parameter set:

  $ rmmod solos-pci.ko
  $ insmod solos-pci.ko firmware_upgrade=1

The modem status LEDs will turn off during the upgrade.  When the upgrade is
complete, the LEDs will return to their normal behaviour.

Status messages are written to /var/log/messages when the upgrade begins and
ends.  "Returning FPGA to Data mode" is written when the upgrade is complete.

The firmware upgrade should take between 2-3 minutes to complete.


8.2 FPGA Configuration Flash Upgrade

Copy the FPGA binary image to:

  /lib/firmware/solos-FPGA.bin

Reload the driver with the FPGA upgrade module parameter set:

  $ rmmod solos-pci.ko
  $ insmod solos-pci.ko fpga_upgrade=1

The modem status LEDs will turn off during the upgrade.  When the upgrade is
complete, the LEDs will return to their normal behaviour.

Status messages are written to /var/log/messages when the upgrade begins and
ends.  "Returning FPGA to Data mode" is written when the upgrade is complete.

The FPGA upgrade should take between 1-2 minutes to complete.

Before the new FPGA configuration will be loaded, the PC must be shutdown and
powered back on again.  Do not shutdown the PC until the LEDs have returned to
their normal behavior.


9. References and further reading
---------------------------------

Linux ATM driver for Solos PCI modem on SourceForge...
http://sourceforge.net/projects/openadsl/

Linux-ATM homepage...
http://linux-atm.sourceforge.net/

Linux-ATM project on SourceForge...
http://sourceforge.net/projects/linux-atm/

Eric Leblond's ATM Bridging Howto...
http://home.regit.org/br2684.html

The official ATM Howto...
http://www.tldp.org/HOWTO/ATM-Linux-HOWTO/index.html

ATM Technical Overview - IBM Redbooks
http://www.redbooks.ibm.com/redbooks/pdfs/sg244625.pdf

RFC1483 (IPoATM)

RFC2364 (PPPoA)
