ACPI: Advanced Configuration and Power Interface

Emma Jane Hogbin

xtrinsic (http://www.xtrinsic.com)

emmajane@xtrinsic.com

Erich Schubert

Diario delle Revisioni

Revisione v1.5.1 2004-07-15 Revisionato da: ejh

Incluso un collegamento alla traduzione Francese di questo documento.

Revisione v1.5 2004-05-21 Revisionato da: ejh

Aggiornamenti minori per il kernel 2.6.6 e correzioni riguardanti quali kernel hanno bisogno di patch.

Revisione v1.4 2004-05-12 Revisionato da: ejh

Prime riflessioni sul kernel 2.6.5; incluse informazioni sulle applicazioni per il controllo delle batterie che causano problemi al lockup del touchpad.

Guida all’applicazione di una patch al kernel per il supporto ACPI.

Traduzione a cura di Giuseppe Briotti <g.briotti (at) mclink.it>. Revisione a cura di Amelia De

    Vivo <devivo (at) unibas.it>/email>>.

Sommario

1. Questo documento .....................................................................................................................................................3
2. Copyright e Licenza ..................................................................................................................................................3
3. Traduzioni ..................................................................................................................................................................3
4. Sull’ACPI ...................................................................................................................................................................3
5. Perché cambiare? ......................................................................................................................................................4
6. La DSDT: Differentiated System Description Table ..............................................................................................4
7. Installazione dai sorgenti ..........................................................................................................................................5
7.1. Scelta del kernel.............................................................................................................................................5
7.1.1. Kernel Debianizzato comprensivo di patch.......................................................................................6
8. Backup .......................................................................................................................................................................6
9. Scaricare e decomprimere il nuovo kernel .............................................................................................................7
9.1. Pacchetti richiesti...........................................................................................................................................7
9.2. Decompressione.............................................................................................................................................7

10. Configurare il nuovo kernel ...................................................................................................................................8
11. Compilare il nuovo kernel ......................................................................................................................................8
12. Installare il nuovo kernel ........................................................................................................................................9
13. Riavvio e verifica .....................................................................................................................................................9
14. Caricare i moduli ..................................................................................................................................................10
15. Passare da APM a ACPI .......................................................................................................................................11
16. Utilizzare l’ACPI ...................................................................................................................................................12
17. Riferimenti e risorse .............................................................................................................................................13
18. Ringraziamenti ......................................................................................................................................................16
A. Applicare patch ai vecchi kernel ...........................................................................................................................16
A.1. Recuperare i file sorgenti.............................................................................................................................16
A.1.1. Applicare la patch...........................................................................................................................17
B. ACPI: il modo Non-Debian ...................................................................................................................................17
B.1. Compilare il kernel......................................................................................................................................17
B.2. Installare il nuovo kernel.............................................................................................................................18
B.3. Pacchetti software........................................................................................................................................18
C. GNU Free Documentation License .......................................................................................................................18
C.1. PREAMBLE................................................................................................................................................19
C.2. APPLICABILITY AND DEFINITIONS....................................................................................................19
C.3. VERBATIM COPYING..............................................................................................................................20
C.4. COPYING IN QUANTITY.........................................................................................................................20
C.5. MODIFICATIONS......................................................................................................................................20
C.6. COMBINING DOCUMENTS....................................................................................................................22
C.7. COLLECTIONS OF DOCUMENTS..........................................................................................................22
C.8. AGGREGATION WITH INDEPENDENT WORKS.................................................................................22
C.9. TRANSLATION..........................................................................................................................................23
C.10. TERMINATION........................................................................................................................................23
C.11. FUTURE REVISIONS OF THIS LICENSE............................................................................................23
C.12. How to use this License for your documents.............................................................................................23

1. Questo documento

Quando inizialmente ho cominciato il passaggio da APM a ACPI, non avevo realizzato che il kernel aveva bisogno di una patch. Il mio problema (folle ammiratore) fu risolto solo con il passaggio alla versione 2.4.20 (kernel distribuito da Debian con una prima patch di acpi.sourceforge.net (http://acpi.sourceforge.net)). Sfortunatamente, dopo il primo aggiornamento, non mi è stato possibile arrestare il computer senza utilizzare l’interruttore dell’alimentazione per spegnerlo. È stato solo dopo che ho realizzato di avere una patch ACPI vecchia ed inefficace. Questo HOWTO è stato scritto per riassumere il processo di installazione da me utilizzato, con la speranza di aiutare altri che hanno avuto difficoltà a reperire informazioni sull’ACPI. Si noti: il corpo principale del documento mostra Il Modo Debian (http://www.debian.org) di risolvere il problema. Vi sono anche informazioni generiche nella sezione Appendice B per quelli che preferiscono... il modo generico.

2. Copyright e Licenza

Copyright (c) 2003, 2004 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 Appendice C.

(NdT. di seguito è riportata la traduzione del paragrafo precedente, con l’avvertenza che ha valore legale solo il testo originale in inglese)

Copyright (c) 2003, 2004 Emma Jane Hogbin.

È concesso il permesso di copiare, distribuire e/o modificare questo documento nei termini della licenza GNU sulla libera documentazione, Versione 1.1 o qualunque versione successiva pubblicata dalla Free Software Foundation; senza le clausole sulle Sezioni immodificabili, sulla Prima di copertina e sull’Ultima di copertina. Una copia della licenza è riportata in Appendice C.

3. Traduzioni

Questo documento è anche disponibile nelle seguenti lingue:

• La versione 1.2 in inglese è tradotta in: Francese (http://www.traduc.org/docs/HOWTO/lecture/ACPI-HOWTO.html). Merci a Guillaume Lelarge et Vanessa Conchodon pour le traduction!

4. Sull’ACPI

Nel mondo della gestione dell’alimentazione ACPI è relativamente recente. Fu rilasciata la prima volta nel 1996 da Compaq/Hewlett-Packard, Intel, Microsoft, Phoenix e Toshiba. Questi sviluppatori ambivano a rimpiazzare il precedente standard industriale per la gestione dell’alimentazione. Il loro sito ACPI.info (http://www.acpi.info) contiene le specifiche ufficiali, una lista delle compagnie che supportano ACPI ed un certo numero di altre cose interessanti. Non si tratta di letture necessarie, ma possono essere di qualche interesse per i curiosi morbosi.

ACPI: Advanced Configuration and Power Interface

ACPI consente il controllo della gestione dell’alimentazione dall’interno del sistema operativo. Il precendente standard industriale per la gestione dell’alimentazione, l’Advanced Power Management (APM), è controllato a livello di BIOS. L’APM viene attivato quando il sistema rimane inattivo: più a lungo il sistema rimane inattivo, meno energia consuma (ad es. si passa dall’attivazione del salvaschermo alla modalità "sleep" fino alla "suspend"). In APM, il sistema operativo non ha conoscenza di quando il sistema cambia il proprio stato di alimentazione.

L’ACPI, tipicamente, può essere configurato dall’interno del sistema operativo. In questo è diverso dall’APM, dove la configurazione spesso richiede il riavvio del computer e l’accesso alle schermate di configurazione del BIOS per l’impostazione dei parametri.

ACPI ha diversi componenti software:

• un sottosistema che controlla gli stati e le funzioni dell’hardware che precedentemente potevano essere nella configurazione del BIOS

Questi stati includono:

• controllo termico

• configurazione della scheda madre

• stati dell’alimentazione (sleep, suspend)

• un gestore delle politiche, cioè un software che si interfaccia col sistema operativo e consente all’utente di agire sulle politiche del sistema

• l’ACPI contiene anche driver che controllano periferiche quali le batterie di un portatile, SMBus (percorso di comunicazione/trasmissione) e EC (controller integrato).

Se si desiderano maggiori informazioni sulla gestione dell’alimentazione nei portatili, si guardino le risorse disponibili su tuxmobil.org (http://www.tuxmobil.org). Specificatamente: Power Management with Linux - APM, ACPI, PMU (http://tuxmobil.org/apm_linux.html) e la sezione Hardware in Detail (http://tuxmobil.org/Mobile-Guide.db/mobile-guide-p2c1-hardware-in-detail.html) della Linux Mobile Guide (http://tuxmobil.org/Mobile-Guide.db/Mobile-Guide.html).

5. Perché cambiare?

Non tutti i sistemi supportano sia APM che ACPI. Io ho cambiato poiché il mio sistema supportava soltanto l’ACPI. Quindi una decisione piuttosto facile. Se decidete di cambiare per avere il supporto S3 (http://acpi.sourceforge.net/documentation/sleep.html) (sospensione in RAM) e non state usando un kernel 2.4.x, non preoccupatevi. Non è supportato (http://lists.debian.org/debian-laptop/2003/debian-laptop-200304/msg00418.html). Punto e basta.

Non si è sicuri che il proprio sistema sia supportato? ACPI4Linux ha una lista di macchine e BIOS (http://acpi.sourceforge.net/wiki/index.php/InstallationReports) supportati nel proprio Wiki. Siete invitati a contribuire all’aggiornamento della lista se avete installato l’ACPI! Vi è anche una lista di macchine che non sono supportate (http://acpi.sourceforge.net/documentation/blacklist.html).

Per ulteriori informazioni sulla gestione dell’alimentazione nei portatili, è (inoltre) utile il Battery Power Linux mini-HOWTO (http://www.tldp.org/HOWTO/mini/Battery-Powered/index.html).

6. La DSDT: Differentiated System Description Table

Grazie a Erich (http://www.vitavonni.de/) che ha scritto questa sezione.

Potrebbe essere necessario sovrascrivere la DSDT qualora alcune caratteristiche, come lo stato delle batterie, vengano erroneamente riportate (di solito causando messaggi di errore sul log di sistema). I portatili DELL solitamente hanno bisogno di questo tipo di intervento. DSDT corrette per diversi sistemi sono disponibile sulla pagina DSDT (http://acpi.sourceforge.net/dsdt/index.php), insieme ad una patch che indica al kernel di ignorare la tabella fornita dal BIOS, in favore della DSDT corretta contenuta nella patch stessa.

Fondamentalmente, è necessario copiare la tabella corretta nel sorgente del kernel con uno specifico nome di file (o modificare il nome del file nella patch fornita dalla pagina DSDT (http://acpi.sourceforge.net/dsdt/index.php)) Questa sostituzione è abbastanza facile: invece di caricare la tabella DSDT dal BIOS, il kernel utilizza la tabella DSDT compilata nella patch. E questo è tutto.

7. Installazione dai sorgenti

ACPI viene costantemente sottoposto a revisioni. È disponibile nelle ultime versioni dei kernel della serie 2.4.x (2.4.22 e superiori) e in tutti i kernel della serie 2.6.x. Se si volesse utilizzare un kernel precedente alla versione 2.4.22, è necessario applicare una patch ai sorgenti del kernel per aggiungere le funzionalità di ACPI. Se possibile, si dovrebbe impiegare l’ultima versione stabile del kernel. Le patch sono disponibili su acpi.sourceforge.net (http://acpi.sourceforge.net).

Red Hat Fedora Core 2 ora viene fornita con ACPI attivata di default. Questo è un bel passo avanti per il gruppo di sviluppo di ACPI. Congratulazioni a tutti.

Nota: Perfino l’ultimo kernel talvolta avrà piccole correzioni disponibili come patch. Si dovrebbe controllare il sito web di ACPI4Linux per verificare se vi sono disponibili delle patch.

È necessario recuperare la patch che corrisponde esattamente alla versione del kernel che si sta utilizzando. Poiché questa è la sezione “installazione dai sorgenti” si assume che sia noto il kernel che si ha intenzione di installare.

7.1. Scelta del kernel

Questo documento è stato scritto originariamente per il kernel versione 2.4.20 ed è stato aggiornato per includere informazioni sui kernel della serie 2.6.x. Al momento di questo aggiornamento i kernel della serie 2.6.x si sono rivelati facili per alcuni e difficili per altri. Personalmente, non sono stata in grado di spegnere correttamente il mio computer con il kernel 2.6.5).

Se possibile, vorrei raccomandare di attendere prima di aggiornare il proprio kernel alla serie 2.6.x, almeno fino a che non siano stati risolti ulteriori bachi. Vi sono moltissimi cambiamenti nei kernel della serie 2.6.x. Quando ho aggiornato il mio kernel alla versione 2.6.5, per poter aggiornare questo documento, ho incontrato problemi con la connessione wireless, la scheda grafica nvidia e con l’ACPI. Il vostro iter può essere diverso. Personalmente, ho avuto un buon successo con la versione 2.4.20 cui avevo applicato l’ultima patch, e con il kernel 2.4.22 senza alcuna patch. Una ricerca nella mailing list della propria distribuzione e in quella acpi-devel dovrebbe essere di aiuto per individuare il kernel giusto.

Nota: Questo documento utilizza il kernel 2.4.20 come esempio per tutti i kernel della serie 2.4.x. Si sostituisca opportunamente la propria versione del kernel.

Indipendentemente da quale kernel si sceglie, se è un kernel che richiede l’uso di una patch, è importante utilizzare l’ultima versione della patch ACPI. Alcune distribuzioni hanno già applicato una patch al proprio kernel. Questo è il caso della Debian e potrebbe essere analogo per altre distribuzioni. Per maggiori informazioni sulle patch che sono state applicate ai sorgenti del kernel Debian si può cercare in:

/usr/src/kernel-source-<version>/README.Debian. Se non si utilizza una distribuzione Debian,

probabilmente sarà possibile trovare un file equivalente per la propria distribuzione.

Sulla mailing list acpi-support, un utente confermava che non era necessaria alcuna delle patch addizionali che erano state applicate al kernel per far funzionale il mio portatile. Se la macchina che si intende utilizzare è un server di produzione e/o un server web per internet, si dovrebbero applicare tutte le patch addizionali relative alla sicurezza.

Avvertimento

Se un kernel ha altre patch applicate, si potrebbero avere problemi nell’installazione della patch ACPI. Naturalmente, una patch ACPI non dovrebbe essere applicata ad un kernel che ha già una patch per ACPI. Anche se non sono mai state applicate al kernel patch ACPI, è possibile applicarne una in seguito. A seconda delle patch applicate, potrebbe essere necessario modificare uno o più dei Makefile per installare la patch con successo. Questo aspetto va oltre gli scopi prefissi, quindi non è trattato in questo documento.

7.1.1. Kernel Debianizzato comprensivo di patch

Se si preferisce utilizzare un kernel Debianizzato invece di uno base, maxx (http://people.debian.org/~maxx) ha fornito i sorgenti del kernel comprensivi dell’ultima patch per il kernel 2.4.20. Potrebbe essere utilizzato questo invece di scaricare un kernel base (senza patch) da www.kernel.org (http://www.kernel.org). Mi ha inviato una email con le seguenti osservazioni:

Ho preso i sorgenti del kernel 2.4.20-8 instabile, ho rimosso le modifiche ACPI [cioè la vecchia patch] ed ho applicato acpi-20021212-2.4.20.diff.gz di acpi.sf.net poiché la versione vanilla 2.4.20 HA diverse carenze di sicurezza (ptrace, hash table, ...).

Si può trovare il pacchetto all’indirizzo http://people.debian.org/~maxx/kernel-source-2.4.20/ (Non ho fatto l’upload del .orig.tar.gz poiché è disponibile su un qualunque mirror del sito debian ed il .deb è già grande abbastanza)

—maxx (http://people.debian.org/~maxx)

Avvertimento

Non ho provato questo pacchetto. È possibile avervi più o meno successo. Si prega di non inviare all’autrice alcuna email che riguardi questo pacchetto, bensì di inviarla a maxx.

ACPI: Advanced Configuration and Power Interface

8. Backup

Se si sta già utilizzando un kernel che è della medesima versione di quello cui si ha intenzione di applicare la patch, si raccomanda di creare una nuova directory per il nuovo kernel con la patch. Si ricordi che i backup non sono mai una cattiva cosa. Questi sono i file di cui io ho fatto il back up:

• /etc/lilo.conf

• /usr/src/*.deb (specifici di Debian)

• /etc/modules
• /etc/modutils/aliases
• /usr/src/linux/.config

• Se non si sta seguendo il Modo Debian, si dovrebbe eseguire il back up anche della directory /lib/modules e dei

  file /boot/vmlinuz, /usr/src/linux/arch/i386/boot/bzImage e /usr/src/System.map. È possibile

che queste indicazioni sulla locazione dei file siano differenti. Si effettui un locate <file> se non sono dove indicato.

9. Scaricare e decomprimere il nuovo kernel

9.1. Pacchetti richiesti

La seguente è una lista dei pacchetti richiesti per applicare patch ai kernel della serie 2.4.x. Sto ancora lavorando sulle note per l’installazione di una serie 2.6.x. kernel serie 2.4.x

• file sorgenti del kernel

• patch ACPI che corrisponda esattamente alla versione del kernel

• pacchetti debian: make, bzip2, gcc, libc6-dev, tk8.3, libncurses5-dev, kernel-package

• dopo aver applicato la patch al kernel si aggiungano i pacchetti debian: acpid, acpi (quest’ultimo è disponibile nelle versioni test ed instabile, ma non in versione stabile)

9.2. Decompressione

È necessario decomprimere il file bz2 (bzip2) e riorganizzare un pò le directory. /usr/src/linux probabilmente punta al kernel attualmente in uso. È necessario fare in modo che punti al nuovo kernel, quindi faremo anche questo.

• cd /usr/src

• mkdir kernel-source-<version> (si utilizzi un nome alternativo se esiste già una versione installata di questo kernel)

• cp linux.<version>.tar.bz2/usr/src/kernel-source-<version>
• cd /usr/src/kernel-source-<version>

ACPI: Advanced Configuration and Power Interface

• tar xjfvlinux.<version>.tar.bz2
• mv linux.<version>/usr/src/linux-<version>

• rm linux (assumendo che questo sia un link al vecchio kernel)

• ln -s/usr/src/linux-<version>linux

Se il proprio kernel ha bisogno di una patch, è il momento di applicarla. Le istruzioni sono disponibili in Appendice A.

10. Configurare il nuovo kernel

Prima si applichi la patch al kernel: Se si sta utilizzando un vecchio kernel, è necessario applicare la patch prima di procedere. Istruzioni su come applicare la patch al kernel sono disponibili in Appendice A. I kernel della serie 2.6.x non hanno bisogno di patch.

Ora, invece di utilizzare make menuconfig, c’è un’ottima alternativa. Verificatela: si copi il file .config corrente nella directory /usr/src/linux. Si usi quindi “make oldconfig”. Il comando effettuerè una scansione del vecchio file di configurazione, verificando gli aggiornamenti in modo da non obbligarvi a cercare tutte le nuove opzioni. Per tutto quello che ha a che fare con ACPI ed il proprio hardware specifico (chi ha Toshiba scelga le opzioni Toshiba, chi ha Asus scelga le opzioni Asus) si risponda M per modulo. Vi sono una decina di opzioni connesse a ACPI che è necessario selezionare. Al dunque, punto per punto, il kernel dovrebbe essere configurato come segue:

• cd /usr/src/linux
• cp /usr/src/<oldkernel-source-directory>/.config.config

• make oldconfig (rispondere M a tutte le nuove opzioni per ACPI -- è anche possibile rispondere “Y” se si preferisce compilarlo direttamente nel kernel)

Ora si entri nel file di configurazione con make menuconfig. Bisogna controllare di avere disabilitato l’APM (il precedente strumento di controllo dell’alimentazione). Alla voce “General Setup”, si verifichi che:

• Power Management Support sia su ON

• APM (Advanced Power Management) sia su OFF (questo è il vecchio strumento, non occorre che sia disponibile, neanche come modulo, a meno che non si sappia esattamente cosa si sta facendo. E se lo si sa, probabilmente non è necessario leggere questo documento.)

• tutto quello che riguarda ACPI deve essere impostato su M (caricato come modulo) o * (compilato direttamente nel kernel). Si legga la lista attentamente: alcune opzioni non saranno applicabili al proprio hardware.

si esca salvando la nuova configurazione

11. Compilare il nuovo kernel

Se vi sono moduli addizionali che non sono parte dell’albero principale dei sorgenti, è necessario aggiungere i file immagine dei moduli quando si creano i pacchetti Debian. Questo è pressoché inevitabile se si sta usando un portatile ed un kernel più vecchio. Ora solo la mia scheda grafica nvidia richiede moduli addizionali.

• cd /usr/src/linux

• make-kpkg clean

• make-kpkg --append-to-version=.<date>kernel_imagemodules_image

Nominare le versioni del kernel: Io non uso più le estensioni .data per distinguere le varie versioni del kernel. È molto frustrante avere numerazioni quali 030627a, 032627b, ecc. quando si cerca di capire le cose. Attualmente utilizzo dei nomi, in ordine alfabetico, cominciando dalla versione del kernel “alien”. Ho intenzione di abbandonare l’opzione delle date, anche se penso ancora che sia un buon metodo.

Il mio attuale kernel, 2.6.6, è “Elrond”. La macchina è “Smeagol”.

Aiuto per compilare il Kernel: Per istruzioni relative a distribuzioni diverse da Debian si veda l’Appendice “Appendice B”.

Per ulteriori istruzioni su come compilare il kernel nel Modo Debian si leggaCreazione di un kernel personalizzato con il sistema kernel-package di Debian (http://newbiedoc.sourceforge.net/system/kernel-pkg.html)

12. Installare il nuovo kernel

Personalmente preferisco configurare da me lilo, ma voi fare come meglio credete.

• cd /usr/src

• dpkg -i kernel-image-<version>.<date>_10.00.Custom_i386.deb A questo punto, scarto tutti gli aggiornamenti di lilo e lo configuro a mano da me.

• configurare lilo manualmente: vi /etc/lilo.conf

• caricare il nuovo kernel in lilo: lilo

• Se avete altri file deb per altri moduli, è necessario installarli a parte adesso. In caso di dubbio, controllare /usr/src per ulteriori file .deb.

Aiuto per compilare il Kernel: Per istruzioni relative a distribuzioni diverse da Debian si veda l’Appendice “Appendice B”.

Per ulteriori istruzioni su come compilare il kernel nel Modo Debian si leggaCreazione di un kernel personalizzato con il sistema kernel-package di Debian (http://newbiedoc.sourceforge.net/system/kernel-pkg.html)

13. Riavvio e verifica

A questo punto bisognerebbe riavviare la macchina. Quando il sistema è di nuovo in piedi (assumendo naturalmente che tutto sia andato per il verso giusto e che si abbia nuovamente un sistema), si verifichi il kernel in esecuzione con uname-a. Il comando dovrebbe mostrare la versione appena compilata. Inoltre, si dovrebbe verificare di aver installato la patch giusta. Questo può essere fatto con dmesg | grep ACPI.*Subsystem\ revision . Che dovrebbe produrre: ACPI: Subsystem revision 20021212. La revisione è la data in cui la patch è stata rilasciata. Questo numero sarà differente dal mio se non si sta utilizzando il kernel 2.4.20. Per vedere tutto ciò che viene caricato/avviato relativamente ad ACPI al boot del sistema, si esegua: dmesg | grep ACPI . dmesg mostra i messaggi di avvio e grep ACPI fa in modo che vengano mostrati solo i messaggi connessi a ACPI.

Si può verificare la versione che si sta utilizzando anche con cat /proc/acpi/info. Non si deve credere a tutto quello che si legge. A me viene indicato che S3 è uno stato supportato, ma sappiamo già che non è vero. Tuttavia la versione mostrata è quella corretta, cosa questa molto utile.

14. Caricare i moduli

Si verifichi che ogni modulo ACPI sia stato caricato dopo l’avvio della macchina. Si può usare il comando lsmod. Bisogna cercare le opzioni seguenti: button, battery, fan, ac, thermal e processor (NdT. pulsante, batteria, ventola, corrente alternata, temperatura e processore). Se si è scelto “Y” invece dei moduli prima di compilare il kernel, non si riuscirà a vedere questa lista. L’output sul mio computer assomiglia a questo:

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

L’ultimo modulo è la mia scheda grafica, che utilizza driver proprietari. Questo è il motivo della presenza della “P” accanto a Tainted nella linea superiore.

Se si è compilato il supporto ACPI come “M”oduli e non si riesce a vedere la lista dei moduli ACPI, si avrà bisogno di caricarli manualmente. I moduli dovrebbero essere collocati in /lib/modules/<version>.

<date>/kernel/drivers/acpi/ e sono i seguenti:
-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

Estensioni per i moduli: Il nome del modulo è tutto ciò che precede l’estensione .o nel nome del file. processor.o è il file, e processor è il nome del modulo. Per installare un modulo kernel si usi: insmod

     processor.

I kernel della serie 2.4.x utilizzano l’estensione .o; tuttavia, i kernel della serie 2.6.x utilizzano l’estensione .ko.

La prima volta che ho riavviato, li ho caricati tutti a mano, digitando insmod <modulename>. Personalmente, ho caricato prima processor, anche se vi sono diverse indicazioni sull’importanza o meno della sequenza di caricamento.

Operating System Power Management (OSPM): La prima volta che l’ho provato, i moduli erano tutti in directory separate e si chiamavano ospm_<name>. Probabilmente era dovuto al fatto di aver utilizzato una patch vecchia, ma è bene fare attenzione. I moduli OSPM ora sono deprecati, così probabilmente non si incontranno affatto.

Per evitare di caricare i moduli ogni volta che viene fatto un riavvio, si possono fare due cose: compilarli direttamente nel kernel (un po’ tardi per pensarci adesso, eh?) oppure aggiungerli al file /etc/modules. Se non si ha giè una copia del file, basta crearne uno nuovo aggiungendovi tutti i nomi dei moduli (si rammenti di non mettere l’estensione), uno per riga. Si può anche provare ad eseguire update-modules che dovrebbe automaticamente aggiornare il file di

configurazione /etc/modules.conf.

15. Passare da APM a ACPI

Non bisogna far girare simultaneamente l’apmd e l’acpid a meno che REALMENTE non si sappia cosa si sta facendo. Debian non assicura che ne giri uno solo per volta. È vostro compito controllare che ciò non avvenga. L’APM proverà a mettere il vostro sistema nello stato S3. Sui kernel della serie 2.4.x (e precedenti) questo molto probabilmente bloccherà la macchina. S3 non è supportato che dalla versione 2.5.x. Neanche la patch fornisce supporto per l’S3 nei kernel della serie 2.4.x. Personalmente ho eseguito un apt-get remove apmd per risolvere i problemi di blocco.

Bisogna fare attenzione anche ad un’altra anomalia che ho scoperto. Il server XFree86 ha una opzione per il sistema DPMS (Energy Star). Il DPMS può essere in uno dei seguenti stati: standby, suspend (NdT "sospeso"), spento o acceso. Poiché i kernel 2.4.x non possono essere sospesi su disco, si possono avere problemi. Ho corretto il mio sistema facendo due cose:

• xset -dpms (disabilita il DPMS)

• Nel file /etc/X11/XF86Config-4 ho commentato la linea Option "DPMS" nella sezione "Monitor".

Perdita degli interrupt del touchpad e della tastiera

Karl Hegbloom mi ha inviato una e-mail in cui dice che “il polling sullo stato delle batterie via ACPI ed il file system proc causano il blocco dei tasti della tastiera, salti improvvisi attraverso lo schermo del puntatore del "touchpad", rallentamenti nel corso di onerose operazioni di I/O di rete.” Questo problema è causato, in parte, da un ritardo tra la richiesta iniziale per avere informazioni sullo stato delle batterie e la relativa risposta. In questo intervallo di tempo, gli interrupt possono essere congelati e può andare perduta la sincronizzazione con la tastiera ed il "touchpad". “La soluzione immediata consiste nel disabilitare l’applicazione di monitoraggio delle batterie, oppure ridurre la sua frequenza di polling.” Karl ha anche osservato che un aggiornamento del BIOS è in grado di risolvere il problema. Grazie Karl!

Non ho incontrato questo problema utilizzando i kernel 2.4.x, tuttavia, si è verificato quando ho aggiornato il kernel alla versione 2.6.5. Io uso wmacpi per controllare lo stato delle batterie. Impostando la frequenza di polling ad 1 (il valore più basso possibile), mi è sembrato di aver eliminato i blocchi del "touchpad". Nel mio file .xinitrc ho inserito:

/usr/bin/wmacpi -s 1

Il parametro -s 1 rappresenta la frequenza di polling (frequenza di campionamento) pari a “una volta al minuto.” L’impostazione predefinita è 20.

16. Utilizzare l’ACPI

Ci sono poche applicazioni e demoni che potreste voler installare sul vostro sistema: acpid (il demone che controlla lo stato dell’hardware) e acpi (l’interfaccia per monitorare eventi e stati) costituiscono l’installazione di base. Il pacchetto Debian acpi è disponibile nella versione di test ed non è stabile. Se il vostro sistema è stabile, non potrete installarlo senza giocare un po’ con apt ed il file list.sources. Probabilmente potreste anche compilarlo da sorgente. Una volta installato acpi, si potrà utilizzarlo per monitorare il proprio sistema come segue: acpi -V. L’output fornirè informazioni sul sistema. Il mio risulta come segue:

Thermal 1: ok, 47.1 degrees C
Thermal 2: ok, 45.1 degrees C
AC Adapter 1: off-line <-- batterie esaurite
AC Adapter 1: on-line <-- alimentazione AC

Sfortunatamente, l’opzione -V “full version” non funziona sul mio sistema. Tuttavia, fortunatamente, posso ancora controllare ciascuno dei file acpi per ricavare informazioni sul mio sistema. Si cerchino nella directory /proc/acpi le cose che possono interessare. Se voglio controllare lo stato delle batterie, leggo il file relativo con il comando: cat

/proc/acpi/battery/BAT0/state. Il risultato è il seguente:
present:                   yes
capacity state:           ok
charging state:           discharging <-- batterie in esaurimento
present rate:              unknown
remaining capacity:       3920 mAh <-- controllare questo numero
present voltage:          14800 mV
present:                   yes
capacity state:           ok
charging state:           discharging
present rate:              unknown

remaining capacity:       3840 mAh <-- la capacità sta diminuendo
present voltage:          14800 mV
present:                   yes
capacity state:           ok
charging state:           charging <-- alimentatore AC inserito
present rate:              unknown
remaining capacity:       3840 mAh
present voltage:          14800 mV

Se voglio informazioni generali sulle batterie, posso controllarle con: 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

Siete persone intelligenti. Potete fare le vostre deduzioni. :)

17. Riferimenti e risorse

Le seguenti URL sono state molto utili nella stesura di questo HOWTO ed in generale per configurare e far funzionare l’ACPI.

HOWTO

HOWTO install ACPI under Linux

http://sylvestre.ledru.info/howto/howto_acpi.php (http://sylvestre.ledru.info/howto/howto_acpi.php)

Linux ACPI-HOWTO

http://www.columbia.edu/~ariel/acpi/acpi_howto.txt (http://www.columbia.edu/~ariel/acpi/acpi_howto.txt)

Linux on the road altrimenti detto: Linux Laptop HOWTO (http://www.tldp.org/HOWTO/Laptop-HOWTO.htm)

http://tuxmobil.org/howtos.html (http://tuxmobil.org/howtos.html) È necessario navigarci un po’, od usare la versione in HTML: http://tuxmobil.org/Mobile-Guide.db/Mobile-Guide.html (http://tuxmobil.org/Mobile-Guide.db/Mobile-Guide.html)

ACPI: Advanced Configuration and Power Interface

Hardware in Detail (sezione di Linux on the road)

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)

Power Management with Linux - APM, ACPI, PMU

http://tuxmobil.org/apm_linux.html (http://tuxmobil.org/apm_linux.html) Battery Powered Linux Mini-HOWTO

http://www.tldp.org/HOWTO/mini/Battery-Powered/ (http://www.tldp.org/HOWTO/mini/Battery-Powered/) Creating custom kernels with Debian’s Kernel-Package system

http://newbiedoc.sourceforge.net/system/kernel-pkg.html (http://newbiedoc.sourceforge.net/system/kernelpkg.html)

Report e informazioni sull’installazione di hardware specifico

Installation reports

http://acpi.sourceforge.net/wiki/index.php/InstallationReports (http://acpi.sourceforge.net/wiki/index.php/InstallationReports) Blacklist

http://acpi.sourceforge.net/documentation/blacklist.html (http://acpi.sourceforge.net/documentation/blacklist.html) DSDT: overview

http://acpi.sourceforge.net/dsdt/index.php (http://acpi.sourceforge.net/dsdt/index.php) Include link a DSDT con patch e HOWTO su come applicare patch al proprio DSDT.

BIOS settings for the AcerTM (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)

Gruppi di sviluppo software

ACPI4Linux

http://acpi.sf.net (http://acpi.sf.net) ACPI Special Interest Group

http://www.acpi.info/ (http://www.acpi.info/) Intel

http://developer.intel.com/technology/iapc/acpi/ (http://developer.intel.com/technology/iapc/acpi/)

ACPI: Advanced Configuration and Power Interface

Articoli su ACPI

Fan Speed Control Techniques in PCs

http://www.analog.com/library/analogDialogue/archives/34-04/fan/

(http://www.analog.com/library/analogDialogue/archives/34-04/fan/)

Thread presi da alcune Mailing List

debian-laptop thread: can’t restore from suspend

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

(http://lists.debian.org/debian-laptop/2003/debian-laptop-200304/msg00367.html) acpi-support thread: newbie HOWTO and debian patching

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)

debian-laptop thread: acer 634 acpi & apm

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

(http://lists.debian.org/debian-laptop/2002/debian-laptop-200212/msg00242.html)

Pacchetti ACPI e software correlati

Il Kernel Si ricordi di scegliere "F" (per "full" - completo) quando si scaricano i sorgenti del kernel. http://www.kernel.org (http://www.kernel.org)

Kernel Debianizzato Pacchetto dei sorgenti del kernel 2.4.20-8 con la patch di maxx già applicata. Per ulteriori informazioni si legga la nota di maxx. http://people.debian.org/~maxx/kernel-source-2.4.20/ (http://people.debian.org/~maxx/kernelsource-2.4.20/)

Patch ACPI È necessario scegliere la versione che corrisponde esattamente al kernel che si sta utilizzando. http://sourceforge.net/project/showfiles.php?group_id=36832 (http://sourceforge.net/project/showfiles.php?group_id=36832)

acpid

il demone http://sourceforge.net/projects/acpid (http://sourceforge.net/projects/acpid) acpi

interfaccia testuale http://grahame.angrygoats.net/acpi.shtml (http://grahame.angrygoats.net/acpi.shtml) Kacpi

interfaccia grafica per KDE http://www.elektronikschule.de/~genannt/kacpi/download.html (http://www.elektronikschule.de/~genannt/kacpi/download.html)

ACPI: Advanced Configuration and Power Interface

aKpi

un’altra interfaccia per KDE http://akpi.scmd.at/ (http://akpi.scmd.at/) wmacpi

WindowMaker DockApp (un’altra GUI) http://www.ne.jp/asahi/linux/timecop/ (http://www.ne.jp/asahi/linux/timecop/)

wmacpi+clecourt WindowMaker DockApp (un’altra interfaccia grafica). Gestisce due slot per batterie. http://open.iliad.fr/~clecourt/wmacpi/index.html (http://open.iliad.fr/~clecourt/wmacpi/index.html)

18. Ringraziamenti

Molti ringraziamenti vanno a:

• acpi-support (http://acpi.sourceforge.net/mailinglists.html) (nota: la lista di discussione su ACPI4Linux è ora in acpi-devel)

• debian-laptop (http://lists.debian.org/debian-laptop/)

• debian-user (http://lists.debian.org/debian-user/)

• techtalk (http://linuxchix.org/)

• TLDP mailing lists (http://www.tldp.org/mailinfo.html#maillists) (discussioni e DocBook)

• Sebastian Henschel per avermi ricordato la promessa di redigere il documento

• Erich Schubert per aver scritto la sezione sul DSDT

• Werner Heuser per avermi suggerito di sottoporre il documento al LDP

• Tabatha Marshall per l’impaginazione ed in generale per essere stata entusiasta di imparare DocBook

A. Applicare patch ai vecchi kernel

Se si sta utilizzando un kernel della serie 2.4.x, sarà necessaria una patch prima di poter aggiungere il supporto ACPI. Nonostante ACPI sia incluso nei kernel della serie 2.6.x, si dovrebbe sempre verificare se sono state rilasciate patch per correggere eventuali bachi. Questa informazione è disponibile sul sito di ACPI4Linux.

A.1. Recuperare i file sorgenti

Scaricare un nuovo kernel da www.kernel.org (http://www.kernel.org). Assicurarsi di aver scaricato un kernel completo. Si cerchi “l’ultima versione stabile del kernel Linux” e si selezioni l’opzione F per FULL (NdT. completo). Si attenda pazientemente. Un kernel compresso con bzip occupa circa 26M. Se vi sentite particolarmente confidenti,

potete anche eseguire wget http://kernel.org/pub/linux/kernel/v2.4/linux-<version>.tar.bz2.

Suggerimento: Potreste volere o meno l’ultima versione stabile. Per maggiori informazioni si legga la sezione la Sezione 7.1 di questo documento. Se si decide di utilizzare una versione del kernel che non è pubblicata sulla pagina principale, si cerchi nella directory /pub/linux/kernel (http://www.kernel.org/pub/linux/kernel/) sul sito kernel.org (http://www.kernel.org) il kernel desiderato.

Mentre aspettate, procuratevi anche una copia della patch. Per il kernel 2.4.20 si usi la patch 2.4.20 (http://prdownloads.sourceforge.net/acpi/acpi-20021212-2.4.20.diff.gz?download). È datata 2002.12.12. Questo numero sarà necessario in seguito, quando si verificherà che la patch funzioni. Se si sta impiegando una versione del kernel differente, ci si assicuri di prendere nota della data della patch corrispondente. I vostri numeri potranno essere sensibilmente diversi da quelli che io utilizzerò di qui in avanti.

Una volta ottenuti i due file (il kernel e la patch) li si decomprima e si applichi la patch al kernel.

A.1.1. Applicare la patch

A questo punto si applicherà effettivamente la patch al kernel. Ho eseguito un passo in più rispetto alle istruzioni (http://acpi.sourceforge.net/download.html) sul sito di ACPI4Linux. Invece di eseguire gunzip e patch sulla stessa linea di comando, ne ho impiegate due. Solo una questione di gusti. Quando si applica una patch al kernel, si potrebbe voler verificare che non vi siano messaggi di errore (non c’è un messaggio “tutto bene”, occorre invece verificare l’assenza di messaggi di errore).

• cd /usr/src/linux

• cp acpi-20021212-2.4.20.diff.gz/usr/src/linux/. (Il nome del file della patch potrebbe essere differente se non si sta utilizzando il kernel 2.4.20)

• gunzip acpi-20021212-2.4.20.diff.gz

• patch -p1 < acpi-20021212-2.4.20.diff (questa è la fase della effettiva applicazione della patch)

Una volta terminata l’applicazione della patch, si continui la lettura alla sezione la Sezione 10.

B. ACPI: il modo Non-Debian

Ci sono poche e piccole differenze tra il Modo Debian e quello generica. Probabilmente solo circa 10 linee di differenza.

B.1. Compilare il kernel

Il modo “normale” di compilare il kernel non utilizza il comando make-kpkg. Segue invece i seguenti passi:

• cd /usr/src/linux che dovrebbe puntare ai file (decompressi) del kernel 2.4.20

• make dep

• make clean
• make bzImage

• make modules (ricordarsi prima di scompattare i propri moduli)

B.2. Installare il nuovo kernel

Secondo il Modo Debian, si crea un file deb che contiene le informazioni sulla posizione del kernel (e compila il kernel e tutto il resto). Secondo il modo “normal”, si devono mettere le cose al posto giusto. Si devono installare i moduli e quindi configurare lilo affinché punti al nuovo kernel, infine lanciare lilo. Se non si sta seguendo il Modo Debian, la propria “installazione” risulterà come segue

• cd /usr/src/linux
• make modules_install
• cp arch/i386/boot/bzImage/boot/vmlinuz.<date>

• vi /etc/lilo.conf e si copi la struttura del kernel già installato. NON si devono cancellare i riferimenti al kernel esistente! Lilo deve puntare al file “vmlinuz” che è stato creato durante la compilazione del kernel

• lilo (esattamente nello stesso modo.) Lilo mostrerà dei messaggi se incontrerè gravi problemi per caricare il nuovo kernel.

Avvertimento

NON bisogna dimenticare di lanciare lilo prima del riavvio. Si digiti lilo. È così facile (e così facile da dimenticare).

B.3. Pacchetti software

Si può utilizzare tutto il software menzionato in questo HOWTO anche se non si sta utilizzando Debian. Sfortunatamente ciò richiederà un piccolo sforzo da parte vostra per scaricare ed installare ogni cosa. Fortunatamente non è così difficile. La maggior parte dei pacchetti software, una volta scompattati, contengono un file README che indica di cosa si ha bisogno e cosa fare per far funzionare le cose sul proprio sistema.

Scaricare il software: Per ulteriori informazioni sul software per ACPI, si veda ACPI packages and related software .

C. 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.

C.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.

C.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, La-TeX 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.

C.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.

C.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 publiclyaccessible 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.

C.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.

C.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."

C.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.

C.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.

C.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.

C.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.

C.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/.

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.

C.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.