****************************************************************************
*********************************ATTENTION**********************************
****************************************************************************

Ce logiciel est en version beta et est fourni tel quel. Il fonctionne
au niveau du noyau du systme d'exploitation et peut donc engendrer la perte
d'une partie ou de la totalit de vos donnes.

Les auteurs de ce logiciel ainsi que ceux qui ont travaill dessus (y compris
moi-mme) en laissent la responsabilit totale  l'utilisateur. Autrement dit,
vous tes libre de ne pas l'utiliser, mais si vous le faites, c'est sous votre
entire responsabilit.

****************************************************************************
****************************************************************************
****************************************************************************

I. Introduction

    Ceci est la refonte du driver pour Linux des modems bass sur le chipset
Eagle 8051 d'Analog. Le modem Sagem F@st 800 et les modems ADSL de USRobotics
sont notamment bass sur ce chipset. Toutefois, seul le modem F@st 800 a t
rellement test.
    La dernire version de ce driver pourra tre tlcharge  partir
de la page suivante :

http://sl33p3r.free.fr/

    Vous trouverez un forum ddi au support des drivers Sagem
 l'adresse suivante :

http://www.eagle-usb.fr.st/

    Le code du driver a t partiellement nettoy/rcrit et a t rendu
compltement compatible avec la GPL par rcriture des parties non libres, afin
de permettre les extensions et modifications ultrieures. Un certain nombre
d'abrations ont galement t corriges dans l'organisation des sources et
dans le code lui-mme dans le cadre du nettoyage. Enfin, les bugs les plus
graves ont t corrigs afin de rendre le driver utilisable. Le code
de communication avec l'espace utilisateur a t rcrit pour blinder le module
en cas d'erreur de la part des clients.

    Les principale modifications sont les suivantes :
    - correction du memory leak en pppoa ;
    - correction de la perte de connexion en cas de trafic montant lev ;
    - correction des plantages de pppoa et contrle des tailles des paquets
reus de l'interface du driver ;
    - correction des race conditions  l'initialisation ;
    - ajout des codes de contrles ioctl ncessaires pour un usage sr ;
    - contrle de la validit des firmwares envoys au noyau ;
    - support des noyaux 2.4.x ;
    - simplification et corrections diverses du code du module ;
    - rcriture des fichiers hotplug ;
    - rcriture du programme d'installation ;
    - rcriture complte en GPL de adictrl avec support d'une option
pour obtenir de l'aide et amlioration des messages d'erreur.

    C'est surtout ce dernier point qui va provoquer des incompatibilits
avec le driver original d'ADI, aussi les informations qui suivent
vous seront utiles pour installer cette version.


II. Installation

    Avant tout, le driver demande un certain nombre de fonctionnalits
au niveau du noyau pour fonctionner. Ces fonctionnalits sont les suivantes :
    - support du chargement des modules du noyau avec les informations
de version (options "Enable loadable module suppor", "Set version information
on all module symbols" et "Kernel module loader") ;
    - support pour le chargement des priphriques  chaud (si l'on veut que
le driver soit charg automatiquement au dmarrage, option "Support for
hot-pluggable devices") ;
    - support du rseau (normalement, c'est assur sur tous les noyaux) ;
    - support ppp (options "PPP (point-to-point protocol) support",
"PPP support for async serial ports", et ventuellement "PPP support for sync
tty ports" si vous voulez utiliser le mode de connexion synchrone de pppd) ;
    - support USB (options "Support for USB", "Preliminary USB device
filesystem" et le support pour l'un des contrleurs UHCI ou pour le contrleur
OHCI). Pour ceux dont le contrleur USB est UHCI, il est recommand d'utiliser
le pilote alternatif JE du noyau.

    Les en-ttes du noyau doivent se trouver dans le rpertoire
/usr/src/linux, ou celui-ci doit tre un lien symbolique vers ce rpertoire.

    Les systmes de fichiers virtuels /proc et /proc/bus/usb doivent tre
monts. Pour automatiser cela, il suffit d'ajouter les lignes suivantes
dans le fichier /etc/fstab :

none            /proc                     proc            defaults   0   0
usbdevfs        /proc/bus/usb             usbdevfs        defaults   0   0

    Le dmon pppd version 2.4.1 ou plus doit galement tre install.

    L'installation du driver en soi doit se faire de la manire suivante :
    
    1. Compilation du driver
    
    make clean
    make

    2. Installation du driver
    
    make install
    
    Cette tape ncessite d'tre sous le compte root. Elle vous demandera
les paramtres de connexion  votre fournisseur d'accs pour gnrer
les fichiers de configuration /etc/ppp/options, /etc/ppp/pap-secrets et
/etc/ppp/chap-secrets.
    Une fois les drivers installs, vous pourrez vous connecter  l'aide
du script /usr/sbin/startadsl et terminer la connexion avec le script
/usr/sbin/stopadsl. Ces scripts ne peuvent tre excuts que dans le compte
root.

    3. Configuration de la connexion automatique
    
    Cette version n'installe pas les scripts d'automatisation de la connexion
en raison des diffrences entre les distributions et les gots de chacun
quant  la manire de raliser cette automatisation.
    Cependant, un script de reconnexion automatique est fourni dans
le rpertoire scripts/adsl. Ce script se nomme adsl.inittab et est crit pour
tre utilis directement  partir du fichier de configuration /etc/inittab.
Pour l'installer, il suffit de le copier dans le rpertoire /usr/sbin et
d'ajouter la ligne suivante dans le fichier /etc/inittab :

adsl:2345:respawn:/usr/sbin/adsl.inittab

Cela permettra de lancer la connexion automatique (et de grer
les reconnexions) dans les niveaux d'excution 2, 3, 4 et 5.

Note :
    L'installation ne prend pas en charge les drivers USRobotics pour
l'instant. Le driver est fourni avec les fichiers BNM du code du DSP
de ces modems et les fichiers de configuration, tels qu'ils sont fournis
par USRobotics. Leur utilisation ncessite de reconstruire le fichier binaire
contenant le code du DSP appropri au modle de modem utilis  l'aide
de l'outil buildDSP, et d'installer le fichier gnr et le fichier
d'options adquat dans le rpertoire /etc/analog.


III. Dsinstallation

    Aucun outil de dsinstallation n'est fourni dans cette version.
La dsinstallation doit donc tre effectue manuellement.
    Pour information, le driver installe les fichiers suivants :
    
    /lib/modules/version/kernel/drivers/usb/adiusbadsl.o
    /usr/sbin/adictrl
    /usr/sbin/startadsl
    /usr/sbin/stopadsl
    /usr/sbin/startmire
    /usr/sbin/showstat
    /etc/analog/adiusbadsl.conf
    /etc/analog/DSPcode.bin
    /etc/hotplug/usb/adiusbfirmware
    /etc/hotplug/usb/adiusbdsp
    /etc/ppp/options.adsl
    /etc/ppp/options.mire
    
    Il modifie galement les fichiers de configuration suivants :
    
    /etc/ppp/pap-secrets (ajout du mot de passe de la connexion)
    /etc/ppp/chap-secrets (ajout du mot de passe de la connexion)
    /etc/hotplug/usb.usermap (ajout des entres pour les priphriques pris
en charge par les fichiers hotplug du driver).


IV. Utilisation

    Lorsque le modem est branche pour la premiere fois, il s'annonce
en tant que modem "pre-firmware". Le driver detecte cet etat et se
charge de lui envoyer le code firmware. Ceci entraine une deconnection
du modem, et une reconnection en tant que modem post-firmware.

    Une fois le firmware charg dans le modem, celui-ci attend le code
du DSP ADSL, qui doit tre charg avec la commande :

adictrl -d [fichier]

o "fichier" est le fichier binaire contenant le code du DSP. Ce fichier peut
tre gnr  l'aide du programme driver/firmware/buildDSP  partir
des fichiers .BNM. Par dfaut il s'agit de /etc/analog/DSPcode.bin.
    Le module conserve le code du DSP en mmoire car le modem peut en avoir
besoin  tout instant. Cependant, il n'est pas renvoy automatiquement
lors du rebranchement du modem, aussi est-il ncessaire de relancer
adictrl explicitement dans ce cas.

    Cette commande envoie galement les options du fichier
/etc/analog/adiusbadsl.conf au module. Le fichier d'option peut tre chang
indpendamment  l'aide de l'option '-o' de adictrl. Toutefois, les options
ne peuvent pas tre recharges tant que l'interface rseau du modem est
en cours d'utilisation.

    Le modem s'initialise ds qu'il reoit le code du DSP. Une fois
l'initialisation termine, il est possible de se connecter.  tout instant,
il est possible de visualiser l'tat du modem  l'aide du fichier :

/proc/driver/adimodem

(attention, ce fichier tait plac au pralable directement dans /proc).
La commande showstat permet d'afficher le contenu de ce fichier plus
facilement.

    Il est possible de se synchroniser avec le modem grce  la commande
suivante :

atictrl -s [timeout]

qui ne se termine que lorsque le modem passe dans l'tat "operational".

    Pour se connecter, il suffit de monter l'interface rseau ethX du modem
(attention, cette interface tait nomme "ADIModem" auparavant), o X est
un numro dpendant du nombre d'interfaces Ethernet dj installes dans
votre systme. Il s'agit gnralement de 0 (pas de carte rseau) ou de 1
(une carte rsau). Cette interface rseau est cre  la demande  l'aide
de l'option -i de adictrl :

adictrl -i

Cette commande affiche galement le nom de l'interface rseau utilise.
Elle peut tre appele plusieurs fois, une seule interface est cre,
lors du premier appel. Ceci permet de s'assurer que le nom de l'interface
rseau choisi par le driver ne dcale pas les noms des ventuelles autres
cartes rseaux installes sur le systme.

NOTE: il est possible de forcer le nom de l'interface a utiliser, en
      specifiant une valeur pour la variable teh_name, lors du
      chargement du module.
      Exe: insmod adiusbadsl.i eth_name="eth9"

    Le montage de l'interface rseau se fait classiquement  l'aide
de la commande ifconfig :

/sbin/ifconfig ethX 192.168.60.30 up

Le choix de l'adresse IP utilise n'a aucune importance, du moment qu'elle
n'entre pas en conflit avec une adresse existante. Il est recommand de
n'utiliser que des adresses rserves aux rseaux privs.

    Lorsque l'interface rseau est monte, la commande

/usr/sbin/pppd pty "/usr/sbin/pppoa -I ethX" file /etc/ppp/options.adsl

lance la connexion, pourvu que les options et les paramtres
de connexion aient t correctement dfinis dans /etc/ppp/options.adsl
et /etc/ppp/pap-secrets ou /etc/ppp/chap-secrets. Vous trouverez
des exemples de ces fichiers dans le rpertoire scripts/ppp. Le programme
d'installation gnre normalement ces scripts correctement  condition que
vous lui fournissiez votre login et votre mot de passe.

    Les oprations de connexion/dconnexion peuvent tre automatises  l'aide
des scripts startadsl et stopadsl. Le script startmire permet de se connecter
 la mire ADSL de France tlcom afin de tester la connexion ADSL. Il faut
galement utiliser la commande stopadsl pour se dconnecter de la mire.

Remarques :
    L'ordre des oprations est important. Le code du driver et d'adictrl
a t modifi pour empcher les mauvaises manipulation. En particulier,
il est impossible de recharger les options ou le code du DSP dans le modem
tant que l'interface rseau est monte.
    Le dbranchement du modem provoque la disparition de l'interface rseau.
Les scripts de connexions automatique doivent donc en tenir compte.



V. Fonctionnement

    Je dcris dans cette section ce que j'ai compris du fonctionnement
du driver. Cette description n'est peut-tre pas trs prcise ni
rigoureusement exacte, mais elle permettra peut-tre aux personnes dsirant
modifier ou amliorer le driver d'en comprendre plus rapidement
l'architecture.
    Le driver est un driver de priphrique USB prenant en charge
les modems ADSL USB bass sur le chipset Eagle 8051 d'Analog. Les priphriques
sont identifis par la liste des identifiants de vendeurs et de priphrique
dclars dans le fichier AdiUsbAdsl.h. La liste des priphriques est dclare
dans le fichier AdiUsbAdsl.c pour que depmod puisse les localiser.
    Ces priphriques disposent de deux identifiants (ce qui apparemment est
classique dans le monde USB), le premier correspondant au priphrique sans
firmware charg, et le deuxime au priphrique avec firmware. Lorsque
les priphriques de chaque type sont dtects par le systme, la fonction
adi_probe est appele pour dterminer si le module les prend en charge.
    Le module gre les priphriques sans firmware simplement en leur
envoyant leur firmware. Une fois le firmware charg, le priphrique
disparat et rapparat sous son deuxime identifiant. C'est l que
les oprations intressantes sont faites.
    Le module commence par slectionner la bonne configuration USB
et initialise ses structures de donnes (tat du modem et buffers
de rception). Puis il charge le code du DSP dans le modem et
l'initialise. Lorsque cette initialisation est termine, les scripts
clients peuvent crer une interface rseau de type Ethernet par laquelle
les programmes pppoa et pppoe pourront envoyer et recevoir leurs
paquets.  noter que la disparition du priphrique implique la destruction
de l'interface rseau automatiquement. J'ignore compltement
ce qui se passe du ct des programmes clients  ce moment.
De toutes faons, dbrancher le modem en cours d'utilisaiton ne constitue
normalement pas un cadre d'utilisation normal.
    L'outil de configuration adictrl communique avec le module par
l'intermdiaire des fichiers spciaux de priphriques crs dans le systme
de fichiers usbdevfs. Pour cela, il recherche les priphriques qu'il peut
contrler dans le rpertoire /proc/bus/usb, qui contient un sous-rpertoire
par bus USB. Lorsque le priphrique cible est localis, une commande ioctl
est envoye pour passer ou rcuprer les informations du module. La liste
des commandes ioctl prises en charge par le module est dclare dans
le fichier AdiUsbAdsl.h.
    Entre autres oprations, adictrl permet de charger le firmware,
le mode de fonctionnement et le code du DSP  charger dans le modem.
Le mode de fonctionnemnet indique principalement l'encapsulation utilise
pour envoyer et recevoir les paquets, ainsi que les canaux VPI/VCI ATM
utilis par le fournisseur d'accs. Le code du DSP quant  lui est
le programme qui permet au modem de communiquer avec le module d'un ct
et avec le terminal ADSL de l'autre. La communication avec le terminal
ADSL se fait en ATM (Asynchronous Transfer Mode).
    Le code du DSP est envoy ds que possible au modem. Apparemment,
ce code est trop volumineux pour tenir dans le modem (ou pour tre
charg en une seule tape), il est donc dcoup en pages (elles-mmes
dcoupes en "blocs") qui peuvent tre demandes par le modem de manire
asynchrone. Le code de chargement doit donc tre trait en partie
dans l'interruption de traitement des vnements provenant du modem.
Cette interruption est donc installe juste avant l'envoi du code du DSP,
qui consiste en fait  envoyer la premire page du DSP. Cette interruption
est gre en cblant un URB (en gros une requte d'entre / sortie USB)
sur une des interfaces USB du modem. Cette interruption gre galement
les notifications de changement d'tat du modem. Son point d'entre
dans le module est la fonction adi_irq. L'amorage du modem
se fait dans la fonction BootTheModem (fichier Boot.c).
    Une fois le modem boot, son tat est susceptible d'voluer
le temps qu'il se synchronise / resynchronise. La gestion des tats
du modem est prise en charge dans les fichiers Sm.c et Me.c (Sate machine
et Management entity respectivement). Les chanbements d'tat sont
capts par le code de l'ISR du module (Interrupt Service Routine).
    Le code de gestion de l'tat du modem contient un timer qui a pour
but de vrifier rgulirement si le modem est vivant. Dans le cas
contraire, le modem est reboot par le driver, ce qui provoque
la relecture des pages du DSP. Le module conserve donc en permanence
les pages du DSP en mmoire (500 Ko environ).
    Un code ioctl permet de synchroniser les processus utilisteurs avec
l'tat du modem. Lorsque le modem est synchronis, ces processus peuvent
communiquer avec l'interface Ethernet du module.
    La manire de procder est toujours la mme : il faut ouvrir
l'interface en mode packet, c'est  dire de telle sorte  pouvoir lire
et crire les paquets Ethernet directement. Pour cela, il faut bien sr
tre dans le compte root. Les outils pppoa et pppoe font exactement cela :
ils communiquent avec le dmon pppd par leur flux d'entre et de sortie
d'un ct, et avec l'interface rseau de l'autre ct. La diffrence
entre ces deux outils rside dans l'encapulation utilise pour envoyer
les paquets PPP au point d'accs du fournisseur d'accs (le "peer").
    Les paquets en mission sont donc encapsuls dans une trame
Ethernet tendue d'informations complmentaires. Ces informations
sont dpendantes du type d'encapsulation utilis. Grosso modo,
l'encapsulation pppoa est plus lgre que celle utilise par pppoe.
Les paquets Ethernet sont galement traits au niveau de l'interface
rseau de manire spcifique en fonction de l'encapsulation utilise.
En gros, les paquets de type pppoe sont transmis tels quels  la couche ATM,
avec les en-ttes Ethernet. Les paquets pppoa en revanche sont "nettoys"
de leurs en-ttes Ethernet et sont donc plus petits.
    Le module utilise un buffer de rception constitu de plusieurs
URBs en lecture. Ces URBs sont cbls sur l'interface des donnes
du modem et sont traites par une fonction de rception de donnes
appele en asynchrone par les couches USB. Toutefois, ce traitement
est effectu de manire synchrone dans le contexte d'appel du driver
USB. Le traitement des donnes en entre est ralis dans le fichier
Pipes.c. Grce  ce buffer, les donnes peuvent arriver plus vite
que le module ne peut les traiter. Ds qu'une donne est arrive,
la fonction de rception rcupre les donnes dans l'URB qui lui est
fourni en paramtre et envoie ces donnes au code de dsencapsulation
ATM (fonction UniProcessInboundData).
    Lorsque les donnes sont reconstitues par le code ATM du module,
la fonction ReadSendItUp du fichier Pipes.c est appele. Cette
fonction effectue le traitement adquat pour reconstituer les paquets
Ethernet. Pour l'encapsulation pppoe, ce traitement consiste  analyser
l'en-tte Ethernet reu de la couche ATM, et pour l'encapsulation pppoa,
elle consiste  reconstruire un en-tte virtuel (puique l'encapsulation
pppoa fait l'conomie de ces en-ttes). Une fois ces traitements
effectus, le paquet Ethernet est retransmis directement aux couches
rseau suprieures de Linux via la mthode netif_rx de Linux. Le noyau
les achemine alors vers pppoa ou pppoe (ceux-ci retirant leur propre
encapsulation et transmettant ensuite les paquets PPP  pppd).
    Le code ATM du module n'a pas t analys. Il semble que ce soit un code
de dcoupage de paquets conforme au protocole AAL5. Il ralise donc (encore)
une encapsulation des donnes fournies par l'interface rseau du module pour
les placer dans des cellules ATM.  noter que l'encapsulation AAL5 se fait
en plusieurs endroits : premirement les en-ttes permettant de dfinir
l'encapsulation utilise sont traits dans le fichier Mpoa.c, puis le dcoupage
en cellules est ralis dans les fichiers Uni.c et Sar.c. On notera ici aussi
qu'outre le transfert complet des paquets Ethernet, l'encodage AAL5 ajoute
un en-tte de 10 octets pour le protocole PPPoE ( prendre sur la bande
passante), alors que l'encodage pour le protocole PPPoA / VC ne prend rien.
    En clair, l'encapsulation PPPoA revient  dire que les paquets PPP sont
transmis directement  la couche ATM, via un petit dtour par l'interface
Ethernet du module. L'encapsulation PPPoE se fait au niveau de pppoe lui-mme,
et les paquets Ethernet ainsi gnrs sont envoys (avec leur en-tte et tout
et tout)  la couche ATM. Il s'agit donc de "PPPoEoA" (PPP over Ethernet
over ATM). Cela implique un MTU (Maximum Transmit Unit) plus faible au niveau
du dmon pppd. Si je ne me suis pas tromp dans mes calculs, pppoa utilise
14 octets d'en-tte Ethernet + 2 octets d'encapsulation, soit un MTU
de 1500 - 2 = 1498 (les paquets Ethernet faisant 1514 octets au maximum).
pppoe quant  lui utilise 6 octets d'encapsulation, ce qui donne un MTU
de 1494.  ces octets d'encapsulation, il faut ajouter deux octets d'en-tte
ajouts par PPP (pour les deux protocoles), ce qui fait respectivement
un MTU de 1496 et 1492. De plus, le protocole PPPoA n'utilise pas d'octets
d'encapsulation au niveau ATM alors que le protocole PPPoE en utilise 10.
Je recommande donc l'utilisation du protocole PPPoA, car c'est celle qui
consomme le moins de bande passante (au dtriment d'une reconstitution
d'en-tte Ethernet  la rception, les deux protocoles construisant
ces en-ttes  l'mission). La diffrence thorique entre les deux protocoles
est a priori de 1.9% (un paquet de 1492 octets est transfr en 1514+10=1524
octets avec PPPoE, soit 32 octets de frais ; PPPoA ne rclame que 4 octets
de frais, la diffrence est donc de 28 octets pour 1492, qu'il faut corriger
d'un facteur 1496/1492 en raison du MTU plus faible de PPPoE). L, j'ai environ
50% de chances de me planter et de raconter n'importe quoi.


Voil voil...

Bon surf,

C. Casteyde (casteyde.christian@free.fr) (a la retraite ;)
Fred Sleeper Ros (sl33p3r@free.fr)
