  ACPI : interface avance de configuration et de gestion de l'nergie

  Adaptation franaise du guide pratique ACPI: Advanced Configuration
  and Power Interface

  Emma Jane Hogbin

   xtrinsic [http://www.xtrinsic.com]

   <emmajane CHEZ xtrinsic POINT com>

   Auteur de la section sur DSDT: Erich Schubert

   Adaptation franaise: Guillaume Lelarge

   Relecture de la version franaise: Vanessa Conchodon

   Prparation de la publication de la v.f.: Jean-Philippe Gurard

   Version : 1.2.fr.1.2

   Copyright  2003 Emma Jane Hogbin

   Copyright  2003 Guillaume Lelarge, Vanessa Conchodon,
   Jean-Philippe Gurard

   15 mai 2005

   +----------------------------------------------------------------+
   | Historique des versions                                        |
   |----------------------------------------------------------------|
   | Version 1.2.fr.1.2        | 2005-05-15      | JPG              |
   |----------------------------------------------------------------|
   | Correction du titre sur une judicieuse suggestion de Bertrand  |
   | Duret.                                                         |
   |----------------------------------------------------------------|
   | Version 1.2.fr.1.1        | 2003-09-03      | GL, VC, JPG      |
   |----------------------------------------------------------------|
   | Quelques corrections mineures.                                 |
   |----------------------------------------------------------------|
   | Version 1.2.fr.1.0        | 2003-07-20      | GL, VC, JPG      |
   |----------------------------------------------------------------|
   | Adaptation franaise.                                          |
   |----------------------------------------------------------------|
   | Version 1.2               | 2003-07-08      | EJH              |
   |----------------------------------------------------------------|
   | Ajout du rsum (Added the abstract).                          |
   |----------------------------------------------------------------|
   | Version 1.1               | 2003-07-03      | EJH              |
   |----------------------------------------------------------------|
   | Mise  jour pour le noyau 2.4.21, dernire version stable du   |
   | noyau  ce jour (Added updates for the 2.4.21 kernel, the      |
   | latest stable kernel at the time).                             |
   |----------------------------------------------------------------|
   | Version 1.0               | 2003-07-01      | EJH              |
   |----------------------------------------------------------------|
   | Version initiale, revue par le LDP (Initial release, reviewed  |
   | by LDP).                                                       |
   |----------------------------------------------------------------|
   | Version 0.2               | 2003-06-12      | EJH              |
   +----------------------------------------------------------------+

   Rsum

   Ce document montre comment modifier le noyau Linux (via un
   correctif) afin de disposer d'une gestion de l'ACPI.

   -------------------------------------------------------------------

   Table des matires

   1.  propos de ce document

   2. Droits d'utilisation et marques dposes

   3. Copyright and License

   4. Commentaires et corrections

   5. Nouvelles versions de ce document

   6.  propos de l'ACPI

   7. Pourquoi changer ?

   8. La table de description diffrencie du systme (DSDT)

   9. Installer  partir de rien

                9.1. Choisir un noyau

   10. Sauvegardes

   11. Paquets requis

   12. Tlcharger et appliquer le correctif

                12.1. Dballer

                12.2. Correctif

   13. Configurer le nouveau noyau

   14. Compiler le nouveau noyau

   15. Installer le nouveau noyau

   16. Redmarrage et test

   17. Charger les modules

   18. Passer d'APM  l'ACPI

   19. Utiliser l'ACPI

   20. Rfrences et ressources

   21. Remerciements

   A. L'ACPI sans utiliser Debian

                1. Compiler le noyau

                2. Installer le nouveau noyau

                3. Paquets logiciels

   B. GNU Free Documentation License

                1. PREAMBLE

                2. APPLICABILITY AND DEFINITIONS

                3. VERBATIM COPYING

                4. COPYING IN QUANTITY

                5. MODIFICATIONS

                6. COMBINING DOCUMENTS

                7. COLLECTIONS OF DOCUMENTS

                8. AGGREGATION WITH INDEPENDENT WORKS

                9. TRANSLATION

                10. TERMINATION

                11. FUTURE REVISIONS OF THIS LICENSE

                12. How to use this License for your documents

1.  propos de ce document

   Lorsque j'ai commenc le passage de l'APM  l'ACPI, je n'ai pas
   ralis que je devais appliquer un correctif au noyau. Mon
   problme (un ventilateur assourdissant) a t corrig simplement
   en mettant  jour mon noyau en version 2.4.20 (noyau prpar par
   Debian avec un correctif antrieur provenant de
   acpi.sourceforge.net [http://acpi.sourceforge.net]).
   Malheureusement, aprs la premire mise  jour, je n'tais pas
   capable d'arrter (halt) mon ordinateur sans utiliser le bouton
   d'arrt. Ce n'est que bien aprs que j'ai ralis que j'avais un
   vieux correctif ACPI inefficace. Ce guide pratique a t crit
   pour rsumer le processus d'installation que j'ai suivi et, je
   l'espre, aider d'autres personnes ayant elles-aussi des
   difficults  trouver les bonnes informations sur l'ACPI. Merci de
   noter que l'article se base principalement sur la faon Debian
   [http://www.debian.org] de faire les choses. Il existe aussi une
   partie gnrique dans Annexe A, L'ACPI sans utiliser Debian pour
   ceux d'entre vous prfrant... un moyen gnrique.

2. Droits d'utilisation et marques dposes

   [1][Important] Important                                           
                  Le texte ci-dessous est la version franaise de la  
                  licence de ce document. Seule la version originale  
                  de cette licence, prsente dans la section         
                  suivante, fait foi.                                 

     Copyright  2003 Emma Jane Hogbin

     Vous tes autoris  copier, distribuer ou modifier la version
     originale de ce document selon les termes de la licence de
     documentation libre GNU (GFDL), version 1.1 ou ultrieure, telle
     que publie par la Free Software Foundation ; sans section
     inaltrable, ni texte de premire de couverture, ni texte de
     quatrime de couverture.

     Une copie en anglais de cette licence est incluse  la fin de ce
     document (cf. Annexe B, GNU Free Documentation License). Une
     traduction franaise officieuse de cette licence est disponible
     sur http://cesarx.free.fr/gfdlf.html
     [http://cesarx.free.fr/gfdlf.html].

     Copyright  2003-2005 Guillaume Lelarge, Vanessa Conchodon et
     Jean-Philippe Gurard pour la version franaise

     La version franaise de ce document a t ralise par Guillaume
     Lelarge, Vanessa Conchodon et Jean-Philippe Gurard. Elle est
     publie en accord avec les termes de la licence de documentation
     libre GNU (GFDL), version 1.1 ou ultrieure, telle que publie
     par la Free Software Foundation [http://fsffrance.org/] ; sans
     section invariante, sans texte de premire de couverture ni
     texte de quatrime de couverture.

     Une copie en anglais de cette licence est incluse  la fin de ce
     document (cf. Annexe B, GNU Free Documentation License). Une
     traduction franaise officieuse de cette licence est disponible
     sur http://cesarx.free.fr/gfdlf.html
     [http://cesarx.free.fr/gfdlf.html].

3. Copyright and License

   [2][Important] Important                                           
                  Le texte ci-dessous est la licence de ce document.  
                  Ce texte fait foi. Il est compos de la licence (en 
                  anglais) du document original, suivi de la licence  
                  (en franais) de sa traduction.                     

     Copyright (c) 2003 Emma Jane Hogbin.

     Permission is granted to copy, distribute and/or modify this
     document under the terms of the GNU Free Documentation License,
     Version 1.1 or any later version published by the Free Software
     Foundation; with no Invariant Sections, no Front-Cover Texts,
     and with no Back-Cover Texts. A copy of the license is included
     in Annexe B, GNU Free Documentation License.

     Copyright  2003 Guillaume Lelarge, Vanessa Conchodon et
     Jean-Philippe Gurard pour la version franaise

     La version franaise de ce document a t ralise par Guillaume
     Lelarge, Vanessa Conchodon et Jean-Philippe Gurard. Elle est
     publie en accord avec les termes de la licence de documentation
     libre GNU (GFDL), version 1.1 ou ultrieure, telle que publie
     par la Free Software Foundation [http://fsffrance.org/] ; sans
     section invariante, sans texte de premire de couverture ni
     texte de quatrime de couverture.

     Une copie en anglais de cette licence est incluse  la fin de ce
     document (cf. Annexe B, GNU Free Documentation License). Une
     traduction franaise officieuse de cette licence est disponible
     sur http://cesarx.free.fr/gfdlf.html
     [http://cesarx.free.fr/gfdlf.html].

4. Commentaires et corrections

   N'hsitez pas  faire parvenir tous commentaires relatifs  la
   version franaise de ce document  <commentaires CHEZ traduc POINT
   org>

5. Nouvelles versions de ce document

   Les nouvelles ditions franaises de ce document sont disponibles
   sur http://www.traduc.org/ [http://www.traduc.org/].

6.  propos de l'ACPI

   Dans le monde de la gestion d'nergie, l'ACPI est relativement
   rcent. Sa premire version date de 1996 et a t conue par
   Compaq - Hewlett-Packard, Intel, Microsoft, Phoenix et Toshiba.
   Ses dveloppeurs ont souhait remplacer le standard industriel
   prcdent en matire de gestion d'nergie. Leur site ACPI.info
   [http://www.acpi.info] contient les spcifications officielles,
   une liste des socits supportant l'ACPI et un certain nombre
   d'autres choses. Il n'est pas ncessaire de le lire bien que cela
   puisse avoir de l'intrt pour les curieux maladifs.

   ACPI permet le contrle de la gestion d'nergie par le systme
   d'exploitation. Le standard industriel prcdent, Advanced Power
   Management (APM), est contrl au niveau du BIOS. L'APM est activ
   lorsque le systme ne fait rien -- plus le systme est en attente,
   moins il utilise de puissance (c'est--dire qu'on commence par
   l'conomiseur d'cran, que l'on passe en mode veille puis en mode
   suspendu). Avec l'APM, le systme d'exploitation n'a pas
   connaissance du moment o l'ordinateur changera d'tat.

   L'ACPI peut tre gnralement configur  partir du systme
   d'exploitation. Ce n'est pas comme l'APM o la configuration
   ncessite souvent de redmarrer et de passer par l'interface de
   configuration du BIOS pour dfinir les paramtres.

   L'ACPI a diffrents composants logiciels :

     o Un sous-systme contrlant l'tat et les fonctions du matriel
       (qui faisait partie auparavant de la configuration du BIOS).

       Les tats incluent :

          o le contrle thermique ;

          o la configuration de la carte mre ;

          o l'tat lectrique (en veille, suspendu).

     o Un gestionnaire de politique, c'est--dire un logiciel
       au-dessus du systme d'exploitation permettant  l'utilisateur
       de dcider des politiques suivies par le systme.

     o L'ACPI dispose aussi de pilotes de priphriques contrlant et
       surveillant les priphriques comme la batterie du portable,
       SMBus (chemin de communication et de transmission) et EC
       (contrleur embarqu).

   Si vous souhaitez plus d'informations sur la gestion d'nergie sur
   les portables, jetez un il aux ressources disponibles (en
   anglais) sur tuxmobil.org [http://www.tuxmobil.org]. Plus
   spcifiquement : La gestion d'nergie sous Linux -- APM, ACPI, PMU
   [http://tuxmobil.org/apm_linux.html] et la section consacre au
   matriel dans le dtail
   [http://tuxmobil.org/Mobile-Guide.db/mobile-guide-p2c1-hardware-in-detail.html]
   du Guide du Linux itinrant
   [http://tuxmobil.org/Mobile-Guide.db/Mobile-Guide.html].

7. Pourquoi changer ?

   Tous les systmes ne sont pas compatibles  la fois avec APM et
   ACPI. Je suis passe  l'ACPI, car mon systme n'tait compatible
   qu'avec ce mode de gestion de l'nergie. La dcision a du coup t
   assez facile. Si vous pensez changer pour pouvoir utiliser le mode
   S3 [http://acpi.sourceforge.net/documentation/sleep.html] (systme
   suspendu en RAM -- suspend to RAM) et que vous utilisez un noyau
   2.4.x, oubliez cette ide. Cela n'est pas possible
   [http://lists.debian.org/debian-laptop/2003/debian-laptop-200304/msg00418.html].

   Vous n'tes pas sr que votre systme est compatible ? ACPI4Linux
   a une liste de machines et BIOS compatibles
   [http://acpi.sourceforge.net/wiki/index.php/InstallationReports]
   sur leur Wiki. Merci de contribuer  la liste si vous avez
   install l'ACPI ! Ils ont aussi une liste des machines qui ne sont
   pas compatibles
   [http://acpi.sourceforge.net/documentation/blacklist.html].

8. La table de description diffrencie du systme (DSDT)

   Merci  Erich [http://www.vitavonni.de/] pour la rdaction de
   cette section.

   Vous aurez peut-tre besoin de passer outre la DSDT lorsque
   certaines informations, comme l'tat de la batterie, sont
   transmises de faon incorrecte (causant habituellement des
   messages d'erreur dans syslog). Les portables DELL ont
   gnralement besoin de ce type de palliatifs. Les DSDT corriges
   sont disponibles pour de nombreux systmes sur la page DSDT
   [http://acpi.sourceforge.net/dsdt/index.php] avec un correctif
   indiquant au noyau d'ignorer la table du BIOS et d'utiliser la
   DSDT corrige.

   Vous aurez simplement besoin de copier la table corrige dans les
   sources du noyau avec un nom de fichier particulier (ou en
   modifiant le nom du fichier dans le correctif donn sur la page
   DSDT [http://acpi.sourceforge.net/dsdt/index.php]). Passer outre
   la DSDT est donc assez facile : au lieu de charger la table DSDT
   du BIOS, le noyau est compil avec et utilise sa propre table
   DSDT. C'est tout.

9. Installer  partir de rien

   ACPI est constamment en rvision. Il n'est pas encore disponible
   pour les noyaux de la srie 2.4.x mais le sera pour la srie 2.5.x
   (ou peut-tre pas avant le 2.6). Ceci signifie que tous les noyaux
   avant les 2.5.x doivent se voir appliquer un correctif. Ceux-ci
   sont disponibles sur le site acpi.sourceforge.net
   [http://acpi.sourceforge.net]. Vous aurez besoin de rcuprer le
   correctif correspondant exactement au noyau que vous utilisez.
   Comme il s'agit d'une section d' installation  partir de rien ,
   je supposerais que vous savez exactement quel noyau vous allez
   installer.

  9.1. Choisir un noyau

   Ce document a t crit pour le noyau 2.4.20. Depuis, le noyau
   stable 2.4.21 est disponible. Les applications du dernier
   correctif ACPI sur ce noyau ont eu des rsultats mitigs. Pour
   l'instant, je recommande de rester sur le noyau 2.4.20 et son
   dernier correctif : 2002.12.12. D'autres recommendent d'autres
   choses. Une recherche via Google sur les listes de diffusion
   debian-user, debian-laptop et acpi-support vous sera utile si vous
   n'tes pas sr de ce que vous devez faire pour votre systme
   spcifique.

   [3][Note] Note                                                     
             Pour tre sr du rsultat, ce document utilisera le      
             noyau 2.4.20 comme exemple ; substituez la version de    
             votre noyau de faon approprie.                         

   Il est important d'utiliser la dernire version du correctif ACPI.
   Certaines distributions ont dj appliqu des correctifs  leurs
   noyaux. C'est le cas pour Debian et certainement pour d'autres.
   Pour plus d'informations sur les correctifs qui ont t appliqus
   aux sources du noyau telles qu'elles sont livres par Debian,
   lisez /usr/src/kernel-source-version/README.Debian. Si vous
   n'utilisez pas Debian, trouvez le fichier quivalent pour votre
   distribution.

   Un utilisateur sur acpi-support m'a confirm que je ne devrais pas
   avoir besoin des correctifs supplmentaires appliqus au noyau
   pour qu'il s'excute sur mon portable. Si vous utilisez un serveur
   en production ou proposez des pages web sur Internet, vous devriez
   rellement appliquer tout correctif de scurit supplmentaire.

   [4][Avertissement] Avertissement                                   
                      Si un noyau dispose d'autres correctifs, vous   
                      pourriez avoir quelques soucis pour appliquer   
                      le correctif ACPI. Bien sr, un correctif ACPI  
                      ne devrait pas tre appliqu  un noyau         
                      disposant dj d'un correctif ACPI. A priori,   
                      tant qu'aucun autre correctif ACPI n'a t      
                      appliqu au noyau, il devrait tre possible     
                      d'en appliquer un maintenant. Suivant les       
                      correctifs appliqus, vous pourrez avoir besoin 
                      de modifier certains fichiers Makefile pour que 
                      le correctif s'installe avec succs. Ceci est   
                      bien au-del de mes comptences et n'est donc   
                      pas trait dans ce document.                    

    9.1.1. Noyau prpar par Debian

   Si vous prfrez utiliser un noyau prpar par Debian, maxx
   [http://people.debian.org/~maxx] propose un paquet des sources du
   noyau disposant dj du correctif compatible avec le noyau 2.4.20.
   Ceci vous vitera de tlcharger un noyau sans correctif sur
   www.kernel.org [http://www.kernel.org]. Il m'a envoy un courrier
   lectronique avec les dtails suivants :

     J'ai pris les sources du noyau 2.4.20-8  partir de unstable,    
     supprim les modifications pour l'ACPI (c'est--dire l'ancien    
     correctif) et appliqu acpi-20021212-2.4.20.diff.gz provenant    
     de acpi.sf.net car le noyau 2.4.20 de base a plusieurs failles   
     de scurit (ptrace, tableau hash, ...).                         
                                                                      
     Vous pouvez trouver le paquet sur                                
     http://people.debian.org/~maxx/kernel-source-2.4.20/             
     [http://people.debian.org/~maxx/kernel-source-2.4.20/]. (je      
     n'ai pas charg le .orig.tar.gz car vous pouvez l'obtenir de     
     n'importe quel miroir debian et que celui-ci est dj assez      
     gros).                                                           
                              --maxx [http://people.debian.org/~maxx]

   [5][Avertissement] Avertissement                                   
                      Je n'ai pas test ces paquets. Vous pouvez      
                      tre, ou non, chanceux. Merci de ne pas me      
                      demander quoi que ce soit l-dessus, voyez      
                      directement avec maxx.                          

10. Sauvegardes

   Si vous avez dj un noyau fonctionnel de la mme version que
   celui que vous souhaitez corriger, je vous recommande de crer un
   nouveau rpertoire pour le nouveau noyau corrig. Rappelez-vous
   que les sauvegardes ne sont jamais une mauvaise chose. Voici les
   fichiers que je sauvegarde :

     o /etc/lilo.conf

     o /usr/src/*.deb (spcifique  la Debian)

     o /etc/modules

     o /etc/modutils/aliases

     o /usr/src/linux/.config

     o Si vous n'agissez pas  la faon Debian vous devez aussi
       sauvegarder le rpertoire /lib/modules, /boot/vmlinuz,
       /usr/src/linux/arch/i386/boot/bzImage et /usr/src/System.map.
       Il est possible que l'emplacement de ces fichiers soit
       diffrent. Faites un locate <fichier> s'ils ne se trouvent pas
       l o je l'ai dit.

11. Paquets requis

   Comme j'ai commenc sur une toute nouvelle machine, je suis
   pratiquement sre que j'ai une liste complte de tous les paquets
   requis pour que le correctif s'applique correctement. Voici la
   liste complte :

     o fichiers source du noyau ;

     o correctif ACPI correspondant exactement  la version de votre
       noyau ;

     o paquets debian : make, bzip2, gcc, libc6-dev, tk8.3,
       libncurses5-dev, kernel-package

     o aprs avoir appliqu le correctif, ajoutez les paquets
       debian : acpid, acpi (Debian testing and unstable only)

12. Tlcharger et appliquer le correctif

   Tlchargez un noyau  partir de www.kernel.org
   [http://www.kernel.org]. Vous devez vous assurer que vous avez un
   noyau complet. Cherchez la  dernire version stable du noyau
   Linux  et cliquez sur F pour FULL (NdT : COMPLET). Attendez
   patiemment. Un noyau compress avec bzip2 pse  peu prs 26 Mo.
   Si vous vous sentez particulirement geek, vous pouvez aussi
   lancer wget
   http://kernel.org/pub/linux/kernel/v2.4/linux-version.tar.bz2.

   [6][Astuce] Astuce                                                 
               Vous pouvez, ou non, vouloir la dernire version       
               stable. Pour plus d'informations, lisez la             
               Section 9.1,  Choisir un noyau  de ce document. Si   
               vous dcidez d'utiliser une version du noyau non       
               publie sur la page principale, utilisez le rpertoire 
               /pub/linux/kernel                                      
               [http://www.kernel.org/pub/linux/kernel/] sur le site  
               kernel.org [http://www.kernel.org] pour trouver le     
               noyau que vous souhaitez.                              

   Pendant que vous attendez, rcuprez aussi une copie du correctif.
   Pour le noyau 2.4.20, utilisez le correctif 2.4.20
   [http://prdownloads.sourceforge.net/acpi/acpi-20021212-2.4.20.diff.gz?download].
   Il est dat du 12.12.2002. Vous aurez besoin de connatre ce
   nombre plus tard lorsque nous vrifierons que le correctif s'est
   bien appliqu. Si vous utilisez une version diffrente du noyau,
   assurez-vous d'avoir bien not la date du correctif. Vos nombres
   vont diffrer lgrement de celui que j'utiliserai plus tard.

   Une fois que vous avez ces deux fichiers (le noyau et le
   correctif), dballez-les et appliquez le correctif au noyau.

  12.1. Dballer

   Maintenant, nous allons prparer le terrain pour l'application du
   correctif au noyau. Nous avons besoin de dballer le fichier bz2
   (bzip2) et de dplacer quelques rpertoires. /usr/src/linux pointe
   probablement vers votre noyau actuel. Nous avons besoin qu'il
   pointe vers le nouveau noyau, donc nous allons faire en sorte
   qu'il le fasse.

 cd /usr/src
 mkdir kernel-source-version          # Utilisez un autre nom si vous
                                      # avez dj une version de ce noyau
                                      # installe
 cp linux.version.tar.bz2 /usr/src/kernel-source-version
 cd /usr/src/kernel-source-version
 tar xjfv linux.version.tar.bz2
 mv linux.version /usr/src/linux-version
 rm linux                             # En supposant qu'il s'agit d'un
                                      # lien vers votre ancien noyau
 ln -s /usr/src/linux-version linux

  12.2. Correctif

   Maintenant, nous allons appliquer le correctif au noyau. Je
   ralise une tape supplmentaire aux instructions
   [http://acpi.sourceforge.net/download.html] sur ACPI4Linux. Au
   lieu de dcompresser et d'appliquer le correctif sur la mme
   ligne, j'utilise deux lignes. C'est juste par prfrence
   personnelle. Lorsque vous appliquez le correctif au noyau, vous
   voulez vous assurer qu'il n'y a eu aucun message d'erreur (il n'y
   a pas de ligne annonant le succs, donc vrifiez plutt l'absence
   d'erreurs).

 cd /usr/src/linux

 # Le nom de fichier du correctif sera diffrent si vous n'utilisez pas le
 # noyau 2.4.20 :

 cp acpi-20021212-2.4.20.diff.gz /usr/src/linux/
        
 gunzip acpi-20021212-2.4.20.diff.gz

 # Enfin la partie de l'application du correctif :

 patch -p1 < acpi-20021212-2.4.20.diff

13. Configurer le nouveau noyau

   Maintenant, au lieu d'utiliser make menuconfig, j'ai une option
   gniale. Faites ceci : copiez votre fichier .config actuel dans
   /usr/src/linux. Ensuite, utilisez make oldconfig. Il va lire
   l'intgralit de votre ancien fichier de configuration et voir ce
   qui a t mis  jour de faon  ce que vous n'ayez pas  chercher
   toutes les nouvelles options. Tout ce qui concerne l'ACPI (les
   cinq premires questions pour moi, mais peut-tre plus pour vous
   si vous n'avez jamais configur un noyau ayant dj des
   correctifs) doit tre  M (pour module). Il existe trois autres
   questions auxquelles je rponds non.

   Voici comment configurer le noyau point par point :

 cd /usr/src/linux
 cp /usr/src/anciennes-sources-du-noyau/.config .config
 make oldconfig      # Dites  M  pour toutes les nouvelles options
                     # de l'ACPI - vous pouvez aussi dire oui ( Y )
                     # si vous prfrez les compiler directement dans le
                     # noyau

   Maintenant, allez dans le fichier de configuration avec make
   menuconfig. Assurez-vous que l'APM est dsactiv. Sous  General
   Setup , assurez-vous que :

     o Power Management Support est activ

     o APM (Advanced Power Management) est dsactiv (c'est l'ancien
       systme -- vous ne devriez mme pas en vouloir comme module 
       moins de savoir ce que vous faites. Et si vous le saviez, vous
       ne seriez probablement pas en train de lire ceci :))

     o tout ce qui a trait  l'ACPI devrait avoir un M (module) ou
       une toile (*) (compil directement dans le noyau)

   Sortez et sauvegardez la nouvelle configuration

14. Compiler le nouveau noyau

   Si vous avez des modules supplmentaires ne faisant pas partie du
   rpertoire principal des sources, vous aurez besoin d'ajouter
   modules_image lors de la construction des paquets Debian. Ceci est
   pratiquement invitable si vous utilisez un portable. Il y a trois
   correctifs ne faisant pas partie du noyau de base et que je dois
   installer sparment : ma carte graphique (nvidia) ; ma carte son
   (ALSA) ; et ma carte wifi (PCMCIA).

 cd /usr/src/linux
 make-kpkg clean
 make-kpkg --append-to-version=date kernel_image modules_image

   [7][Note] Nommer le noyau construit                                
             Je n'utilise plus .date pour distinguer les diffrents   
             noyaux que j'ai construit. Il tait trop frustrant       
             d'avoir des 030627a, 032627b (et ctera) alors que       
             j'essayais de comprendre comment cela marchait.          
                                                                      
             J'utilise maintenant des noms, en ordre alphabtique, en 
             commenant avec le noyau que j'ai nomm  alien . Je    
             conserve malgr tout ici l'option de la date car je      
             pense qu'il s'agit d'une bonne faon de faire les        
             choses.                                                  

   [8][Note] Aide pour la compilation du noyau                         
             Pour les instructions pour une distribution non Debian,   
             voir l'annexe Annexe A, L'ACPI sans utiliser Debian.      
                                                                       
             Pour plus d'informations sur la compilation du noyau sur  
             une Debian, lisez Crer des noyaux personnaliss avec le  
             systme de paquets du noyau de Debian                     
             [http://newbiedoc.sourceforge.net/system/kernel-pkg.html] 
             (document en anglais).                                    

15. Installer le nouveau noyau

   J'aime configurer lilo moi-mme, mais faites comme vous
   l'entendez.

 cd /usr/src
 dpkg -i kernel-image-version.date_10.00.Custom_i386.deb

 #  ce moment, je refuse toutes les mises  jour
 # lilo et le configure moi-mme manuellement.

 # Configurez lilo manuellement

 vi /etc/lilo.conf

 # Chargez le nouveau noyau dans lilo

 lilo

 # Si vous avez d'autres fichiers deb pour vos modules, vous devriez les
 # installer maintenant. Si vous n'tes pas sr, vrifiez /usr/src pour
 # des fichiers .deb supplmentaires.

   [9][Note] Aide pour la compilation du noyau                         
             Pour les instructions pour une distribution non Debian,   
             voir l'annexe Annexe A, L'ACPI sans utiliser Debian.      
                                                                       
             Pour plus d'informations sur la compilation du noyau sur  
             une Debian, lisez Crer des noyaux personnaliss avec le  
             systme de paquets du noyau de Debian                     
             [http://newbiedoc.sourceforge.net/system/kernel-pkg.html] 
             (document en anglais).                                    

16. Redmarrage et test

    ce moment, vous devez redmarrer votre machine. Lorsque le
   systme est relanc (en supposant que tout s'est pass
   correctement et que vous avez toujours un systme), vrifiez quel
   noyau est en cours d'excution avec uname -a. Cela devrait vous
   montrer celui que vous venez de construire. Vous aurez aussi
   besoin de vous assurer que le bon correctif a t install. Vous
   pouvez faire ceci avec :

 dmesg | grep ACPI.*Subsystem\ revision

   Il devrait afficher :

 ACPI : Subsystem revision 20021212

   Le numro de rvision est la date du correctif. Ce numro sera
   diffrent du mien si vous n'utilisez pas un noyau 2.4.20. Pour
   rechercher tout ce qui concerne l'ACPI et qui a t charg ou
   lanc lors du redmarrage du systme, faites ceci :

 dmesg | grep ACPI

   dmesg affiche les messages du dmarrage et grep ACPI s'assure que
   seuls les messages relatifs  l'ACPI sont affichs.

   Vous pouvez aussi vrifier la version que vous utilisez avec
   cat /proc/acpi/info. Ne croyez pas tout ce qui vous est indiqu.
   Ma sortie indique que S3 est un tat utilisable, mais nous savons
   dj que ce n'est pas le cas. Par contre, le numro de version est
   correct, ce qui est bien utile.

17. Charger les modules

   Si vous avez compil la gestion de l'ACPI en tant que module
   ( M ), vous aurez probablement besoin de charger les modules 
   la main. Vous devrez chercher un peu pour trouver les modules. Les
   miens sont dans /lib/modules/version.date/kernel/drivers/acpi/ et
   s'appellent :

 -rw-r--r--    1 root     root         4.1k Jun  3 23:57 ac.o
 -rw-r--r--    1 root     root         9.5k Jun  3 23:57 battery.o
 -rw-r--r--    1 root     root         5.2k Jun  3 23:57 button.o
 -rw-r--r--    1 root     root         3.7k Jun  3 23:57 fan.o
 -rw-r--r--    1 root     root          14k Jun  3 23:57 processor.o
 -rw-r--r--    1 root     root          11k Jun  3 23:57 thermal.o
 -rw-r--r--    1 root     root         6.2k Jun  3 23:57 toshiba_acpi.o

   La premire fois que j'ai redmarr, je les ai chargs
   manuellement en tapant

 insmod nom_du_module

   Je commence par processor, bien que les avis soient partags sur
   le fait que l'ordre ait une importance.

   [10][Note] Modules du noyau                                        
              Le nom du module est la partie du nom du fichier,       
              prcdant l'extension .o.                               
                                                                      
              processor.o est le fichier, processor est le nom du     
              module. Pour installer un module du noyau, utilisez     
              insmod processor.                                       

   Vous pouvez vrifier les modules chargs avec lsmod. Ma sortie de
   lsmod (avec la plupart des extras supprims) ressemble  ceci :

 Module                  Size  Used by    Tainted: P 
 button                  2420   0 (unused)
 battery                 5960   0 (unused)
 ac                      1832   0 (unused)
 fan                     1608   0 (unused)
 thermal                 6664   0 (unused)
 processor               8664   0 [thermal]
 NVdriver              945408  11

   Le dernier est ma carte graphique utilisant des pilotes
   propritaires. C'est pourquoi un  P  se trouve  ct de Tainted
   sur la premire ligne.

   [11][Note] Gestion d'nergie du systme d'exploitation (OSPM ou    
              Operating System Power Management                       
              La premire fois o j'ai essay ceci, les modules       
              taient tous dans des rpertoires spars et se         
              nommaient ospm_<nom>. C'est probablement d au fait que 
              j'utilisais un ancien correctif, mais c'est important   
              de le savoir. Les modules OSPM sont maintenant          
              abandonns, donc vous ne devriez plus les voir.         

   Pour ne pas avoir  charger les modules dans le noyau  chaque
   fois que vous dmarrez, vous devez soit les compiler directement
   dans le noyau (un peu tard, n'est-ce-pas ?) soit les ajouter dans
   votre fichier /etc/modules. Si vous n'avez pas dj une copie de
   ce fichier, crez-le et ajoutez un nom de module (rappelez-vous,
   pas de .o) par ligne.

18. Passer d'APM  l'ACPI

   Ne laissez pas apmd et acpid s'excuter en mme temps  moins que
   vous ne sachiez rellement ce que vous faites. Debian ne vrifiera
   pas si l'un d'entre eux est dj lanc. Vous devez le vrifier.
   APM essaiera de passer votre systme en S3. Sur les noyaux de
   srie 2.4.x (et prcdents), ceci a de fortes chances de bloquer
   votre machine. S3 n'est pas support jusqu'au 2.5.x. Mme le
   correctif n'apporte pas le support de S3. J'ai prfr faire un
   apt-get remove apmd pour rsoudre ce problme.

   Vous devez aussi connatre un autre petit problme que j'ai
   dcouvert. Le serveur XFree86 a une option pour les
   fonctionnalits DPMS (Energy Star). Le DPMS peut passer par
   diffrents tats : en attente, suspendu, arrt, en cours. Comme
   les noyaux 2.4.x ne peuvent tre suspendus vers le disque, ceci
   peut poser problme. J'ai corrig mon systme en faisant deux
   choses :

     o xset -dpms (dsactive les fonctionnalits DPMS)

     o Dans /etc/X11/XF86Config-4, j'ai mis en commentaire la ligne
       Option "DPMS" de la section "Monitor".

19. Utiliser l'ACPI

   Il existe plusieurs applications/dmons diffrents que vous
   voudrez installer sur votre systme : acpid (le dmon qui contrle
   les tats du matriel) et acpi (l'interface surveillant les
   vnements et les tats) font partie de l'installation de base. Le
   paquet Debian acpi est seulement disponible dans testing et est
   instable. Si vous utilisez la distribution Debian stable, vous ne
   serez pas capable de l'installer sans bidouiller avec apt et votre
   fichier sources.list. Vous pouvez probablement les compiler 
   partir des sources. Si vous avez acpi install, vous pouvez
   l'utiliser pour surveiller votre systme en utilisant cette
   commande : acpi -V. Sa sortie vous donnera des informations sur
   votre systme. La mienne ressemble  ceci :

      Thermal 1: ok, 47.1 degrees C
      Thermal 2: ok, 45.1 degrees C
   AC Adapter 1: off-line <-- fonctionne sur batteries
   AC Adapter 1: on-line <-- fonctionne sur secteur

   Malheureusement, la  version complte  de -V ne fonctionne pas
   pour moi. Heureusement, je peux toujours regarder dans chacun des
   fichiers acpi individuellement pour obtenir des informations sur
   mon systme. Regardez dans le rpertoire /proc/acpi afin de
   vrifier diffrents points importants. Si je veux vrifier ma
   batterie, je lis le fichier suivant comme ceci :

 cat /proc/acpi/battery/BAT0/state

   La sortie ressemble  ceci :

 present:                 yes
 capacity state:          ok
 charging state:          discharging <-- fonctionne sur batteries
 present rate:            unknown
 remaining capacity:      3920 mAh <-- surveillez ce nombre
 present voltage:         14800 mV

 present:                 yes
 capacity state:          ok
 charging state:          discharging
 present rate:            unknown
 remaining capacity:      3840 mAh <-- la charge batterie diminue
 present voltage:         14800 mV

 present:                 yes
 capacity state:          ok
 charging state:          charging <-- adaptateur secteur branch
 present rate:            unknown
 remaining capacity:      3840 mAh
 present voltage:         14800 mV

   Si je veux de l'information sur ma batterie en gnral, je
   testerais ceci :

 cat /proc/acpi/battery/BAT0/info

 present:                 yes
 design capacity:         3920 mAh
 last full capacity:      3920 mAh
 battery technology:      rechargeable
 design voltage:          14800 mV
 design capacity warning: 30 mAh
 design capacity low:     20 mAh
 capacity granularity 1:  10 mAh
 capacity granularity 2:  3470 mAh
 model number:            Bat0
 serial number:             
 battery type:            Lion
 OEM info:                Acer

   Vous tes des personnes intelligentes. Vous pouvez probablement
   vous dbrouiller  partir de maintenant :)

20. Rfrences et ressources

   Les liens suivants ont t incroyablement utiles pour l'criture
   de ce guide pratique et en rgle gnral pour faire fonctionner
   l'ACPI.

   Guides pratiques

   Guide pratique de l'installation de l'ACPI sous Linux

           http://sylvestre.ledru.info/howto/howto_acpi.php
           [http://sylvestre.ledru.info/howto/howto_acpi.php]

   Guide pratique de l'ACPI sous Linux

           http://www.columbia.edu/~ariel/acpi/acpi_howto.txt
           [http://www.columbia.edu/~ariel/acpi/acpi_howto.txt]

   Linux en voyage, auparavant : Guide pratique du portable sous
   Linux [http://www.traduc.org/docs/howto/lecture/Laptop-HOWTO.html]

           http://tuxmobil.org/howtos.html
           [http://tuxmobil.org/howtos.html] Vous aurez besoin de
           descendre un peu ou d'utiliser la version HTML :
           http://tuxmobil.org/Mobile-Guide.db/Mobile-Guide.html
           [http://tuxmobil.org/Mobile-Guide.db/Mobile-Guide.html]

   Matriel en dtail (partie du Linux en voyage)

           http://tuxmobil.org/Mobile-Guide.db/mobile-guide-p2c1-hardware-in-detail.html
           [http://tuxmobil.org/Mobile-Guide.db/mobile-guide-p2c1-hardware-in-detail.html]

   Gestion de l'nergie avec Linux - APM, ACPI, PMU

           http://tuxmobil.org/apm_linux.html
           [http://tuxmobil.org/apm_linux.html]

   Crer des noyaux personnaliss avec le systme de paquets de
   noyaux de Debian

           http://newbiedoc.sourceforge.net/system/kernel-pkg.html
           [http://newbiedoc.sourceforge.net/system/kernel-pkg.html]

   Rapports d'installation et informations spcifiques  un matriel

   Rapports d'installation

           http://acpi.sourceforge.net/wiki/index.php/InstallationReports
           [http://acpi.sourceforge.net/wiki/index.php/InstallationReports]

   Liste noire

           http://acpi.sourceforge.net/documentation/blacklist.html
           [http://acpi.sourceforge.net/documentation/blacklist.html]

   DSDT : Survol

           http://acpi.sourceforge.net/dsdt/index.php
           [http://acpi.sourceforge.net/dsdt/index.php] Inclut des
           liens vers des DSDT corrigs et vers des guides pratiques
           sur l'application d'un correctif disposant de votre propre
           DSDT.

   Paramtrages du BIOS pour l'Acer (Phoenix BIOS)

           http://help.nec-computers.com/au/pri/item_instr_bios_7521N.asp
           [http://help.nec-computers.com/au/pri/item_instr_bios_7521N.asp]

   Groupes de dveloppement de logiciels

   ACPI4Linux

           http://acpi.sf.net [http://acpi.sf.net]

   Groupe d'intrt ACPI

           http://www.acpi.info/ [http://www.acpi.info/]

   Intel

           http://developer.intel.com/technology/iapc/acpi/
           [http://developer.intel.com/technology/iapc/acpi/]

   Listes de diffusion

   Discussion sur debian-laptop : can't restore from suspend (NdT :
   Impossible de restaurer  partir du mode suspendu)

           http://lists.debian.org/debian-laptop/2003/debian-laptop-200304/msg00367.html
           [http://lists.debian.org/debian-laptop/2003/debian-laptop-200304/msg00367.html]

   Discussion sur acpi-support : newbie HOWTO and debian patching
   (NdT : guide pratique pour les nouveaux et pour amender la debian)

           http://sourceforge.net/mailarchive/forum.php?forum_id=7803&max_rows=25&style=flat&viewmonth=200304&viewday=17
           [http://sourceforge.net/mailarchive/forum.php?forum_id=7803&max_rows=25&style=flat&viewmonth=200304&viewday=17]

   Discussion sur debian-laptop : acer 634 ACPI (NdT : ACPI sur
   l'acer 634

           http://lists.debian.org/debian-laptop/2002/debian-laptop-200212/msg00242.html
           [http://lists.debian.org/debian-laptop/2002/debian-laptop-200212/msg00242.html]

   Paquets ACPI et logiciels en relation

   Noyau

           Rappelez-vous de choisir "F" pour full (NdT : pour
           complet) lorsque vous tlchargez les sources du noyau.
           http://www.kernel.org [http://www.kernel.org]

   Noyau prpar par Debian

           Paquet des sources du noyau 2.4.20-8 prpar par maxx.
           Pour plus d'informations, voir les Section 9.1.1,  Noyau
           prpar par Debian .
           http://people.debian.org/~maxx/kernel-source-2.4.20/
           [http://people.debian.org/~maxx/kernel-source-2.4.20/]

   Correctif du noyau pour l'ACPI

           Vous devrez prendre la version correspondant exactement au
           noyau que vous utilisez.
           http://sourceforge.net/project/showfiles.php?group_id=36832
           [http://sourceforge.net/project/showfiles.php?group_id=36832]

   acpid

           le dmon http://sourceforge.net/projects/acpid
           [http://sourceforge.net/projects/acpid]

   acpi

           l'interface texte http://grahame.angrygoats.net/acpi.shtml
           [http://grahame.angrygoats.net/acpi.shtml]

   Kacpi

           l'interface graphique de KDE
           http://www.elektronikschule.de/~genannt/kacpi/download.html
           [http://www.elektronikschule.de/~genannt/kacpi/download.html]

   aKpi

           une autre interface de KDE http://akpi.scmd.at/
           [http://akpi.scmd.at/]

   wmacpi

           un DockApp WindowMaker (un autre GUI)
           http://www.ne.jp/asahi/linux/timecop/
           [http://www.ne.jp/asahi/linux/timecop/]

   wmacpi+clecourt

           un DockApp WindowMaker (une autre interface graphique).
           Gre deux batteries.
           http://open.iliad.fr/~clecourt/wmacpi/index.html
           [http://open.iliad.fr/~clecourt/wmacpi/index.html]

21. Remerciements

   Mes remerciements vont aux personnes suivantes :

     o acpi-support [http://acpi.sourceforge.net/mailinglists.html]

     o debian-laptop [http://lists.debian.org/debian-laptop/]

     o debian-user [http://lists.debian.org/debian-user/]

     o techtalk [http://linuxchix.org/]

     o listes de diffusions de TLDP
       [http://www.tldp.org/mailinfo.html#maillists] (discuss et
       docbook)

     o Sebastian Henschel pour m'avoir rappel que j'avais promis de
       l'crire

     o Erich Schubert pour la rdaction de la section sur DSDT

     o Werner Heuser pour m'avoir suggr de soumettre le document au
       LDP

     o Tabatha Marshall pour l'dition et d'avoir t en rgle
       gnrale trs enthousiaste pour apprendre DocBook

A. L'ACPI sans utiliser Debian

   Il n'existe que peu de diffrence entre la manire Debian et la
   manire gnrique. En fait, il doit y avoir seulement dix lignes
   de diffrences.

1. Compiler le noyau

   La faon  habituelle  de compiler un noyau ne fait pas usage de
   make-kpkg.  la place, elle utilise les tapes suivantes :

 cd /usr/src/linux # qui devrait pointer vers les fichiers (dcompresss)
                   # du noyau 2.4.20
 make dep
 make clean
 make bzImage
 make modules      # (rappelez-vous de dballer vos modules en premier
                   # lieu)

2. Installer le nouveau noyau

    la manire Debian, vous crez un fichier deb contenant
   l'information sur l'emplacement du noyau (et crez le noyau et
   ainsi de suite). D'une faon plus gnrique, vous placez les
   choses l o elles doivent tre. Vous avez besoin d'installer vos
   modules, puis de configurer lilo pour pointer vers le nouveau
   noyau et d'excuter lilo. Si vous ne faites pas de la faon
   Debian, votre  installation  ressemblera  ceci :

 cd /usr/src/linux
 make modules_install
 cp arch/i386/boot/bzImage /boot/vmlinuz.date
 vi /etc/lilo.conf # et copiez la structure votre noyau actuel. Ne
                   # supprimez PAS la rfrence  votre noyau
                   # actuel ! Vous avez besoin de faire pointer lilo
                   # vers le fichier  vmlinuz  qui a t cr
                   # lors de votre compilation du noyau ci-dessus.
        
 lilo              # (oui, exactement comme a.)
                   # Lilo vous indiquera si des problmes importants
                   # sont survenus lors du chargement du nouveau noyau.

   [12][Avertissement] Avertissement                                  
                       N'oubliez PAS de lancer lilo avant de          
                       redmarrer. Tapez lilo. C'est aussi simple (et 
                       c'est aussi simple de l'oublier).              

3. Paquets logiciels

   Vous pouvez toujours utiliser tous les logiciels mentionns dans
   ce guide pratique mme si vous n'utilisez pas Debian.
   Malheureusement, cela demandera un peu plus d'efforts de votre
   part pour tlcharger et installer tout. Heureusement, ce n'est
   pas si difficile. Lorsque vous les dcompressez, la plupart des
   paquets comprennent un fichier README qui vous explique ce dont
   vous avez besoin pour les faire fonctionner sur votre systme.

   [13][Astuce] Tlchargement des logiciels                          
                Pour plus d'informations sur les logiciels prenant en 
                compte l'ACPI, merci d'utiliser le Paquets ACPI et    
                logiciels en relation.                                

B. GNU Free Documentation License

   Version 1.1, March 2000

     Copyright (C) 2000 Free Software Foundation, Inc. 59 Temple
     Place, Suite 330, Boston, MA 02111-1307 USA Everyone is
     permitted to copy and distribute verbatim copies of this license
     document, but changing it is not allowed.

1. PREAMBLE

   The purpose of this License is to make a manual, textbook, or
   other written document "free" in the sense of freedom: to assure
   everyone the effective freedom to copy and redistribute it, with
   or without modifying it, either commercially or noncommercially.
   Secondarily, this License preserves for the author and publisher a
   way to get credit for their work, while not being considered
   responsible for modifications made by others.

   This License is a kind of "copyleft", which means that derivative
   works of the document must themselves be free in the same sense.
   It complements the GNU General Public License, which is a copyleft
   license designed for free software.

   We have designed this License in order to use it for manuals for
   free software, because free software needs free documentation: a
   free program should come with manuals providing the same freedoms
   that the software does. But this License is not limited to
   software manuals; it can be used for any textual work, regardless
   of subject matter or whether it is published as a printed book. We
   recommend this License principally for works whose purpose is
   instruction or reference.

2. APPLICABILITY AND DEFINITIONS

   This License applies to any manual or other work that contains a
   notice placed by the copyright holder saying it can be distributed
   under the terms of this License. The "Document", below, refers to
   any such manual or work. Any member of the public is a licensee,
   and is addressed as "you".

   A "Modified Version" of the Document means any work containing the
   Document or a portion of it, either copied verbatim, or with
   modifications and/or translated into another language.

   A "Secondary Section" is a named appendix or a front-matter
   section of the Document that deals exclusively with the
   relationship of the publishers or authors of the Document to the
   Document's overall subject (or to related matters) and contains
   nothing that could fall directly within that overall subject. (For
   example, if the Document is in part a textbook of mathematics, a
   Secondary Section may not explain any mathematics.) The
   relationship could be a matter of historical connection with the
   subject or with related matters, or of legal, commercial,
   philosophical, ethical or political position regarding them.

   The "Invariant Sections" are certain Secondary Sections whose
   titles are designated, as being those of Invariant Sections, in
   the notice that says that the Document is released under this
   License.

   The "Cover Texts" are certain short passages of text that are
   listed, as Front-Cover Texts or Back-Cover Texts, in the notice
   that says that the Document is released under this License.

   A "Transparent" copy of the Document means a machine-readable
   copy, represented in a format whose specification is available to
   the general public, whose contents can be viewed and edited
   directly and straightforwardly with generic text editors or (for
   images composed of pixels) generic paint programs or (for
   drawings) some widely available drawing editor, and that is
   suitable for input to text formatters or for automatic translation
   to a variety of formats suitable for input to text formatters. A
   copy made in an otherwise Transparent file format whose markup has
   been designed to thwart or discourage subsequent modification by
   readers is not Transparent. A copy that is not "Transparent" is
   called "Opaque".

   Examples of suitable formats for Transparent copies include plain
   ASCII without markup, Texinfo input format, LaTeX input format,
   SGML or XML using a publicly available DTD, and
   standard-conforming simple HTML designed for human modification.
   Opaque formats include PostScript, PDF, proprietary formats that
   can be read and edited only by proprietary word processors, SGML
   or XML for which the DTD and/or processing tools are not generally
   available, and the machine-generated HTML produced by some word
   processors for output purposes only.

   The "Title Page" means, for a printed book, the title page itself,
   plus such following pages as are needed to hold, legibly, the
   material this License requires to appear in the title page. For
   works in formats which do not have any title page as such, "Title
   Page" means the text near the most prominent appearance of the
   work's title, preceding the beginning of the body of the text.

3. VERBATIM COPYING

   You may copy and distribute the Document in any medium, either
   commercially or noncommercially, provided that this License, the
   copyright notices, and the license notice saying this License
   applies to the Document are reproduced in all copies, and that you
   add no other conditions whatsoever to those of this License. You
   may not use technical measures to obstruct or control the reading
   or further copying of the copies you make or distribute. However,
   you may accept compensation in exchange for copies. If you
   distribute a large enough number of copies you must also follow
   the conditions in section 3.

   You may also lend copies, under the same conditions stated above,
   and you may publicly display copies.

4. COPYING IN QUANTITY

   If you publish printed copies of the Document numbering more than
   100, and the Document's license notice requires Cover Texts, you
   must enclose the copies in covers that carry, clearly and legibly,
   all these Cover Texts: Front-Cover Texts on the front cover, and
   Back-Cover Texts on the back cover. Both covers must also clearly
   and legibly identify you as the publisher of these copies. The
   front cover must present the full title with all words of the
   title equally prominent and visible. You may add other material on
   the covers in addition. Copying with changes limited to the
   covers, as long as they preserve the title of the Document and
   satisfy these conditions, can be treated as verbatim copying in
   other respects.

   If the required texts for either cover are too voluminous to fit
   legibly, you should put the first ones listed (as many as fit
   reasonably) on the actual cover, and continue the rest onto
   adjacent pages.

   If you publish or distribute Opaque copies of the Document
   numbering more than 100, you must either include a
   machine-readable Transparent copy along with each Opaque copy, or
   state in or with each Opaque copy a publicly-accessible
   computer-network location containing a complete Transparent copy
   of the Document, free of added material, which the general
   network-using public has access to download anonymously at no
   charge using public-standard network protocols. If you use the
   latter option, you must take reasonably prudent steps, when you
   begin distribution of Opaque copies in quantity, to ensure that
   this Transparent copy will remain thus accessible at the stated
   location until at least one year after the last time you
   distribute an Opaque copy (directly or through your agents or
   retailers) of that edition to the public.

   It is requested, but not required, that you contact the authors of
   the Document well before redistributing any large number of
   copies, to give them a chance to provide you with an updated
   version of the Document.

5. MODIFICATIONS

   You may copy and distribute a Modified Version of the Document
   under the conditions of sections 2 and 3 above, provided that you
   release the Modified Version under precisely this License, with
   the Modified Version filling the role of the Document, thus
   licensing distribution and modification of the Modified Version to
   whoever possesses a copy of it. In addition, you must do these
   things in the Modified Version:

    A. Use in the Title Page (and on the covers, if any) a title
       distinct from that of the Document, and from those of previous
       versions (which should, if there were any, be listed in the
       History section of the Document). You may use the same title
       as a previous version if the original publisher of that
       version gives permission.

    B. List on the Title Page, as authors, one or more persons or
       entities responsible for authorship of the modifications in
       the Modified Version, together with at least five of the
       principal authors of the Document (all of its principal
       authors, if it has less than five).

    C. State on the Title page the name of the publisher of the
       Modified Version, as the publisher.

    D. Preserve all the copyright notices of the Document.

    E. Add an appropriate copyright notice for your modifications
       adjacent to the other copyright notices.

    F. Include, immediately after the copyright notices, a license
       notice giving the public permission to use the Modified
       Version under the terms of this License, in the form shown in
       the Addendum below.

    G. Preserve in that license notice the full lists of Invariant
       Sections and required Cover Texts given in the Document's
       license notice.

    H. Include an unaltered copy of this License.

    I. Preserve the section entitled "History", and its title, and
       add to it an item stating at least the title, year, new
       authors, and publisher of the Modified Version as given on the
       Title Page. If there is no section entitled "History" in the
       Document, create one stating the title, year, authors, and
       publisher of the Document as given on its Title Page, then add
       an item describing the Modified Version as stated in the
       previous sentence.

    J. Preserve the network location, if any, given in the Document
       for public access to a Transparent copy of the Document, and
       likewise the network locations given in the Document for
       previous versions it was based on. These may be placed in the
       "History" section. You may omit a network location for a work
       that was published at least four years before the Document
       itself, or if the original publisher of the version it refers
       to gives permission.

    K. In any section entitled "Acknowledgements" or "Dedications",
       preserve the section's title, and preserve in the section all
       the substance and tone of each of the contributor
       acknowledgements and/or dedications given therein.

    L. Preserve all the Invariant Sections of the Document, unaltered
       in their text and in their titles. Section numbers or the
       equivalent are not considered part of the section titles.

    M. Delete any section entitled "Endorsements". Such a section may
       not be included in the Modified Version.

    N. Do not retitle any existing section as "Endorsements" or to
       conflict in title with any Invariant Section.

   If the Modified Version includes new front-matter sections or
   appendices that qualify as Secondary Sections and contain no
   material copied from the Document, you may at your option
   designate some or all of these sections as invariant. To do this,
   add their titles to the list of Invariant Sections in the Modified
   Version's license notice. These titles must be distinct from any
   other section titles.

   You may add a section entitled "Endorsements", provided it
   contains nothing but endorsements of your Modified Version by
   various parties--for example, statements of peer review or that
   the text has been approved by an organization as the authoritative
   definition of a standard.

   You may add a passage of up to five words as a Front-Cover Text,
   and a passage of up to 25 words as a Back-Cover Text, to the end
   of the list of Cover Texts in the Modified Version. Only one
   passage of Front-Cover Text and one of Back-Cover Text may be
   added by (or through arrangements made by) any one entity. If the
   Document already includes a cover text for the same cover,
   previously added by you or by arrangement made by the same entity
   you are acting on behalf of, you may not add another; but you may
   replace the old one, on explicit permission from the previous
   publisher that added the old one.

   The author(s) and publisher(s) of the Document do not by this
   License give permission to use their names for publicity for or to
   assert or imply endorsement of any Modified Version.

6. COMBINING DOCUMENTS

   You may combine the Document with other documents released under
   this License, under the terms defined in section 4 above for
   modified versions, provided that you include in the combination
   all of the Invariant Sections of all of the original documents,
   unmodified, and list them all as Invariant Sections of your
   combined work in its license notice.

   The combined work need only contain one copy of this License, and
   multiple identical Invariant Sections may be replaced with a
   single copy. If there are multiple Invariant Sections with the
   same name but different contents, make the title of each such
   section unique by adding at the end of it, in parentheses, the
   name of the original author or publisher of that section if known,
   or else a unique number. Make the same adjustment to the section
   titles in the list of Invariant Sections in the license notice of
   the combined work.

   In the combination, you must combine any sections entitled
   "History" in the various original documents, forming one section
   entitled "History"; likewise combine any sections entitled
   "Acknowledgements", and any sections entitled "Dedications". You
   must delete all sections entitled "Endorsements."

7. COLLECTIONS OF DOCUMENTS

   You may make a collection consisting of the Document and other
   documents released under this License, and replace the individual
   copies of this License in the various documents with a single copy
   that is included in the collection, provided that you follow the
   rules of this License for verbatim copying of each of the
   documents in all other respects.

   You may extract a single document from such a collection, and
   distribute it individually under this License, provided you insert
   a copy of this License into the extracted document, and follow
   this License in all other respects regarding verbatim copying of
   that document.

8. AGGREGATION WITH INDEPENDENT WORKS

   A compilation of the Document or its derivatives with other
   separate and independent documents or works, in or on a volume of
   a storage or distribution medium, does not as a whole count as a
   Modified Version of the Document, provided no compilation
   copyright is claimed for the compilation. Such a compilation is
   called an "aggregate", and this License does not apply to the
   other self-contained works thus compiled with the Document, on
   account of their being thus compiled, if they are not themselves
   derivative works of the Document.

   If the Cover Text requirement of section 3 is applicable to these
   copies of the Document, then if the Document is less than one
   quarter of the entire aggregate, the Document's Cover Texts may be
   placed on covers that surround only the Document within the
   aggregate. Otherwise they must appear on covers around the whole
   aggregate.

9. TRANSLATION

   Translation is considered a kind of modification, so you may
   distribute translations of the Document under the terms of section
   4. Replacing Invariant Sections with translations requires special
   permission from their copyright holders, but you may include
   translations of some or all Invariant Sections in addition to the
   original versions of these Invariant Sections. You may include a
   translation of this License provided that you also include the
   original English version of this License. In case of a
   disagreement between the translation and the original English
   version of this License, the original English version will
   prevail.

10. TERMINATION

   You may not copy, modify, sublicense, or distribute the Document
   except as expressly provided for under this License. Any other
   attempt to copy, modify, sublicense or distribute the Document is
   void, and will automatically terminate your rights under this
   License. However, parties who have received copies, or rights,
   from you under this License will not have their licenses
   terminated so long as such parties remain in full compliance.

11. FUTURE REVISIONS OF THIS LICENSE

   The Free Software Foundation may publish new, revised versions of
   the GNU Free Documentation License from time to time. Such new
   versions will be similar in spirit to the present version, but may
   differ in detail to address new problems or concerns. See
   http://www.gnu.org/copyleft/ [http://www.gnu.org/copyleft/].

   Each version of the License is given a distinguishing version
   number. If the Document specifies that a particular numbered
   version of this License "or any later version" applies to it, you
   have the option of following the terms and conditions either of
   that specified version or of any later version that has been
   published (not as a draft) by the Free Software Foundation. If the
   Document does not specify a version number of this License, you
   may choose any version ever published (not as a draft) by the Free
   Software Foundation.

12. How to use this License for your documents

   To use this License in a document you have written, include a copy
   of the License in the document and put the following copyright and
   license notices just after the title page:

     Copyright (c) YEAR YOUR NAME. Permission is granted to copy,
     distribute and/or modify this document under the terms of the
     GNU Free Documentation License, Version 1.1 or any later version
     published by the Free Software Foundation; with the Invariant
     Sections being LIST THEIR TITLES, with the Front-Cover Texts
     being LIST, and with the Back-Cover Texts being LIST. A copy of
     the license is included in the section entitled "GNU Free
     Documentation License".

   If you have no Invariant Sections, write "with no Invariant
   Sections" instead of saying which ones are invariant. If you have
   no Front-Cover Texts, write "no Front-Cover Texts" instead of
   "Front-Cover Texts being LIST"; likewise for Back-Cover Texts.

   If your document contains nontrivial examples of program code, we
   recommend releasing these examples in parallel under your choice
   of free software license, such as the GNU General Public License,
   to permit their use in free software.

