diff options
Diffstat (limited to 'Documentation/translations')
47 files changed, 16124 insertions, 0 deletions
diff --git a/Documentation/translations/index.rst b/Documentation/translations/index.rst new file mode 100644 index 000000000..7f77c52d3 --- /dev/null +++ b/Documentation/translations/index.rst @@ -0,0 +1,13 @@ +.. _translations: + +============ +Translations +============ + +.. toctree:: + :maxdepth: 1 + + zh_CN/index + it_IT/index + ko_KR/index + ja_JP/index diff --git a/Documentation/translations/it_IT/disclaimer-ita.rst b/Documentation/translations/it_IT/disclaimer-ita.rst new file mode 100644 index 000000000..d68e52de6 --- /dev/null +++ b/Documentation/translations/it_IT/disclaimer-ita.rst @@ -0,0 +1,13 @@ +:orphan: + +.. note:: + This document is maintained by Federico Vaga <federico.vaga@vaga.pv.it>. + If you find any difference between this document and the original file or a + problem with the translation, please contact the maintainer of this file. + Following people helped to translate or review: + Alessia Mantegazza <amantegazza@vaga.pv.it> + +.. warning:: + The purpose of this file is to be easier to read and understand for Italian + speakers and is not intended as a fork. So, if you have any comments or + updates for this file please try to update the original English file first. diff --git a/Documentation/translations/it_IT/doc-guide/index.rst b/Documentation/translations/it_IT/doc-guide/index.rst new file mode 100644 index 000000000..7a6562b54 --- /dev/null +++ b/Documentation/translations/it_IT/doc-guide/index.rst @@ -0,0 +1,24 @@ +.. include:: ../disclaimer-ita.rst + +.. note:: Per leggere la documentazione originale in inglese: + :ref:`Documentation/doc-guide/index.rst <doc_guide>` + +.. _it_doc_guide: + +========================================== +Come scrivere la documentazione del kernel +========================================== + +.. toctree:: + :maxdepth: 1 + + sphinx.rst + kernel-doc.rst + parse-headers.rst + +.. only:: subproject and html + + Indices + ======= + + * :ref:`genindex` diff --git a/Documentation/translations/it_IT/doc-guide/kernel-doc.rst b/Documentation/translations/it_IT/doc-guide/kernel-doc.rst new file mode 100644 index 000000000..2bf1c1e2f --- /dev/null +++ b/Documentation/translations/it_IT/doc-guide/kernel-doc.rst @@ -0,0 +1,554 @@ +.. include:: ../disclaimer-ita.rst + +.. note:: Per leggere la documentazione originale in inglese: + :ref:`Documentation/doc-guide/index.rst <doc_guide>` + +.. _it_kernel_doc: + +Scrivere i commenti in kernel-doc +================================= + +Nei file sorgenti del kernel Linux potrete trovare commenti di documentazione +strutturanti secondo il formato kernel-doc. Essi possono descrivere funzioni, +tipi di dati, e l'architettura del codice. + +.. note:: Il formato kernel-doc può sembrare simile a gtk-doc o Doxygen ma + in realtà è molto differente per ragioni storiche. I sorgenti del kernel + contengono decine di migliaia di commenti kernel-doc. Siete pregati + d'attenervi allo stile qui descritto. + +La struttura kernel-doc è estratta a partire dai commenti; da questi viene +generato il `dominio Sphinx per il C`_ con un'adeguata descrizione per le +funzioni ed i tipi di dato con i loro relativi collegamenti. Le descrizioni +vengono filtrare per cercare i riferimenti ed i marcatori. + +Vedere di seguito per maggiori dettagli. + +.. _`dominio Sphinx per il C`: http://www.sphinx-doc.org/en/stable/domains.html + +Tutte le funzioni esportate verso i moduli esterni utilizzando +``EXPORT_SYMBOL`` o ``EXPORT_SYMBOL_GPL`` dovrebbero avere un commento +kernel-doc. Quando l'intenzione è di utilizzarle nei moduli, anche le funzioni +e le strutture dati nei file d'intestazione dovrebbero avere dei commenti +kernel-doc. + +È considerata una buona pratica quella di fornire una documentazione formattata +secondo kernel-doc per le funzioni che sono visibili da altri file del kernel +(ovvero, che non siano dichiarate utilizzando ``static``). Raccomandiamo, +inoltre, di fornire una documentazione kernel-doc anche per procedure private +(ovvero, dichiarate "static") al fine di fornire una struttura più coerente +dei sorgenti. Quest'ultima raccomandazione ha una priorità più bassa ed è a +discrezione dal manutentore (MAINTAINER) del file sorgente. + + + +Sicuramente la documentazione formattata con kernel-doc è necessaria per +le funzioni che sono esportate verso i moduli esterni utilizzando +``EXPORT_SYMBOL`` o ``EXPORT_SYMBOL_GPL``. + +Cerchiamo anche di fornire una documentazione formattata secondo kernel-doc +per le funzioni che sono visibili da altri file del kernel (ovvero, che non +siano dichiarate utilizzando "static") + +Raccomandiamo, inoltre, di fornire una documentazione formattata con kernel-doc +anche per procedure private (ovvero, dichiarate "static") al fine di fornire +una struttura più coerente dei sorgenti. Questa raccomandazione ha una priorità +più bassa ed è a discrezione dal manutentore (MAINTAINER) del file sorgente. + +Le strutture dati visibili nei file di intestazione dovrebbero essere anch'esse +documentate utilizzando commenti formattati con kernel-doc. + +Come formattare i commenti kernel-doc +------------------------------------- + +I commenti kernel-doc iniziano con il marcatore ``/**``. Il programma +``kernel-doc`` estrarrà i commenti marchiati in questo modo. Il resto +del commento è formattato come un normale commento multilinea, ovvero +con un asterisco all'inizio d'ogni riga e che si conclude con ``*/`` +su una riga separata. + +I commenti kernel-doc di funzioni e tipi dovrebbero essere posizionati +appena sopra la funzione od il tipo che descrivono. Questo allo scopo di +aumentare la probabilità che chi cambia il codice si ricordi di aggiornare +anche la documentazione. I commenti kernel-doc di tipo più generale possono +essere posizionati ovunque nel file. + +Al fine di verificare che i commenti siano formattati correttamente, potete +eseguire il programma ``kernel-doc`` con un livello di verbosità alto e senza +che questo produca alcuna documentazione. Per esempio:: + + scripts/kernel-doc -v -none drivers/foo/bar.c + +Il formato della documentazione è verificato della procedura di generazione +del kernel quando viene richiesto di effettuare dei controlli extra con GCC:: + + make W=n + +Documentare le funzioni +------------------------ + +Generalmente il formato di un commento kernel-doc per funzioni e +macro simil-funzioni è il seguente:: + + /** + * function_name() - Brief description of function. + * @arg1: Describe the first argument. + * @arg2: Describe the second argument. + * One can provide multiple line descriptions + * for arguments. + * + * A longer description, with more discussion of the function function_name() + * that might be useful to those using or modifying it. Begins with an + * empty comment line, and may include additional embedded empty + * comment lines. + * + * The longer description may have multiple paragraphs. + * + * Context: Describes whether the function can sleep, what locks it takes, + * releases, or expects to be held. It can extend over multiple + * lines. + * Return: Describe the return value of foobar. + * + * The return value description can also have multiple paragraphs, and should + * be placed at the end of the comment block. + */ + +La descrizione introduttiva (*brief description*) che segue il nome della +funzione può continuare su righe successive e termina con la descrizione di +un argomento, una linea di commento vuota, oppure la fine del commento. + +Parametri delle funzioni +~~~~~~~~~~~~~~~~~~~~~~~~ + +Ogni argomento di una funzione dovrebbe essere descritto in ordine, subito +dopo la descrizione introduttiva. Non lasciare righe vuote né fra la +descrizione introduttiva e quella degli argomenti, né fra gli argomenti. + +Ogni ``@argument:`` può estendersi su più righe. + +.. note:: + + Se la descrizione di ``@argument:`` si estende su più righe, + la continuazione dovrebbe iniziare alla stessa colonna della riga + precedente:: + + * @argument: some long description + * that continues on next lines + + or:: + + * @argument: + * some long description + * that continues on next lines + +Se una funzione ha un numero variabile di argomento, la sua descrizione +dovrebbe essere scritta con la notazione kernel-doc:: + + * @...: description + +Contesto delle funzioni +~~~~~~~~~~~~~~~~~~~~~~~ + +Il contesto in cui le funzioni vengono chiamate viene descritto in una +sezione chiamata ``Context``. Questo dovrebbe informare sulla possibilità +che una funzione dorma (*sleep*) o che possa essere chiamata in un contesto +d'interruzione, così come i *lock* che prende, rilascia e che si aspetta che +vengano presi dal chiamante. + +Esempi:: + + * Context: Any context. + * Context: Any context. Takes and releases the RCU lock. + * Context: Any context. Expects <lock> to be held by caller. + * Context: Process context. May sleep if @gfp flags permit. + * Context: Process context. Takes and releases <mutex>. + * Context: Softirq or process context. Takes and releases <lock>, BH-safe. + * Context: Interrupt context. + +Valore di ritorno +~~~~~~~~~~~~~~~~~ + +Il valore di ritorno, se c'è, viene descritto in una sezione dedicata di nome +``Return``. + +.. note:: + + #) La descrizione multiriga non riconosce il termine d'una riga, per cui + se provate a formattare bene il vostro testo come nel seguente esempio:: + + * Return: + * 0 - OK + * -EINVAL - invalid argument + * -ENOMEM - out of memory + + le righe verranno unite e il risultato sarà:: + + Return: 0 - OK -EINVAL - invalid argument -ENOMEM - out of memory + + Quindi, se volete che le righe vengano effettivamente generate, dovete + utilizzare una lista ReST, ad esempio:: + + * Return: + * * 0 - OK to runtime suspend the device + * * -EBUSY - Device should not be runtime suspended + + #) Se il vostro testo ha delle righe che iniziano con una frase seguita dai + due punti, allora ognuna di queste frasi verrà considerata come il nome + di una nuova sezione, e probabilmente non produrrà gli effetti desiderati. + +Documentare strutture, unioni ed enumerazioni +--------------------------------------------- + +Generalmente il formato di un commento kernel-doc per struct, union ed enum è:: + + /** + * struct struct_name - Brief description. + * @member1: Description of member1. + * @member2: Description of member2. + * One can provide multiple line descriptions + * for members. + * + * Description of the structure. + */ + +Nell'esempio qui sopra, potete sostituire ``struct`` con ``union`` o ``enum`` +per descrivere unioni ed enumerati. ``member`` viene usato per indicare i +membri di strutture ed unioni, ma anche i valori di un tipo enumerato. + +La descrizione introduttiva (*brief description*) che segue il nome della +funzione può continuare su righe successive e termina con la descrizione di +un argomento, una linea di commento vuota, oppure la fine del commento. + +Membri +~~~~~~ + +I membri di strutture, unioni ed enumerati devo essere documentati come i +parametri delle funzioni; seguono la descrizione introduttiva e possono +estendersi su più righe. + +All'interno d'una struttura o d'un unione, potete utilizzare le etichette +``private:`` e ``public:``. I campi che sono nell'area ``private:`` non +verranno inclusi nella documentazione finale. + +Le etichette ``private:`` e ``public:`` devono essere messe subito dopo +il marcatore di un commento ``/*``. Opzionalmente, possono includere commenti +fra ``:`` e il marcatore di fine commento ``*/``. + +Esempio:: + + /** + * struct my_struct - short description + * @a: first member + * @b: second member + * @d: fourth member + * + * Longer description + */ + struct my_struct { + int a; + int b; + /* private: internal use only */ + int c; + /* public: the next one is public */ + int d; + }; + +Strutture ed unioni annidate +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +È possibile documentare strutture ed unioni annidate, ad esempio:: + + /** + * struct nested_foobar - a struct with nested unions and structs + * @memb1: first member of anonymous union/anonymous struct + * @memb2: second member of anonymous union/anonymous struct + * @memb3: third member of anonymous union/anonymous struct + * @memb4: fourth member of anonymous union/anonymous struct + * @bar: non-anonymous union + * @bar.st1: struct st1 inside @bar + * @bar.st2: struct st2 inside @bar + * @bar.st1.memb1: first member of struct st1 on union bar + * @bar.st1.memb2: second member of struct st1 on union bar + * @bar.st2.memb1: first member of struct st2 on union bar + * @bar.st2.memb2: second member of struct st2 on union bar + */ + struct nested_foobar { + /* Anonymous union/struct*/ + union { + struct { + int memb1; + int memb2; + } + struct { + void *memb3; + int memb4; + } + } + union { + struct { + int memb1; + int memb2; + } st1; + struct { + void *memb1; + int memb2; + } st2; + } bar; + }; + +.. note:: + + #) Quando documentate una struttura od unione annidata, ad esempio + di nome ``foo``, il suo campo ``bar`` dev'essere documentato + usando ``@foo.bar:`` + #) Quando la struttura od unione annidata è anonima, il suo campo + ``bar`` dev'essere documentato usando ``@bar:`` + +Commenti in linea per la documentazione dei membri +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +I membri d'una struttura possono essere documentati in linea all'interno +della definizione stessa. Ci sono due stili: una singola riga di commento +che inizia con ``/**`` e finisce con ``*/``; commenti multi riga come +qualsiasi altro commento kernel-doc:: + + /** + * struct foo - Brief description. + * @foo: The Foo member. + */ + struct foo { + int foo; + /** + * @bar: The Bar member. + */ + int bar; + /** + * @baz: The Baz member. + * + * Here, the member description may contain several paragraphs. + */ + int baz; + union { + /** @foobar: Single line description. */ + int foobar; + }; + /** @bar2: Description for struct @bar2 inside @foo */ + struct { + /** + * @bar2.barbar: Description for @barbar inside @foo.bar2 + */ + int barbar; + } bar2; + }; + + +Documentazione dei tipi di dato +------------------------------- +Generalmente il formato di un commento kernel-doc per typedef è +il seguente:: + + /** + * typedef type_name - Brief description. + * + * Description of the type. + */ + +Anche i tipi di dato per prototipi di funzione possono essere documentati:: + + /** + * typedef type_name - Brief description. + * @arg1: description of arg1 + * @arg2: description of arg2 + * + * Description of the type. + * + * Context: Locking context. + * Return: Meaning of the return value. + */ + typedef void (*type_name)(struct v4l2_ctrl *arg1, void *arg2); + +Marcatori e riferimenti +----------------------- + +All'interno dei commenti di tipo kernel-doc vengono riconosciuti i seguenti +*pattern* che vengono convertiti in marcatori reStructuredText ed in riferimenti +del `dominio Sphinx per il C`_. + +.. attention:: Questi sono riconosciuti **solo** all'interno di commenti + kernel-doc, e **non** all'interno di documenti reStructuredText. + +``funcname()`` + Riferimento ad una funzione. + +``@parameter`` + Nome di un parametro di una funzione (nessun riferimento, solo formattazione). + +``%CONST`` + Il nome di una costante (nessun riferimento, solo formattazione) + +````literal```` + Un blocco di testo che deve essere riportato così com'è. La rappresentazione + finale utilizzerà caratteri a ``spaziatura fissa``. + + Questo è utile se dovete utilizzare caratteri speciali che altrimenti + potrebbero assumere un significato diverso in kernel-doc o in reStructuredText + + Questo è particolarmente utile se dovete scrivere qualcosa come ``%ph`` + all'interno della descrizione di una funzione. + +``$ENVVAR`` + Il nome di una variabile d'ambiente (nessun riferimento, solo formattazione). + +``&struct name`` + Riferimento ad una struttura. + +``&enum name`` + Riferimento ad un'enumerazione. + +``&typedef name`` + Riferimento ad un tipo di dato. + +``&struct_name->member`` or ``&struct_name.member`` + Riferimento ad un membro di una struttura o di un'unione. Il riferimento sarà + la struttura o l'unione, non il memembro. + +``&name`` + Un generico riferimento ad un tipo. Usate, preferibilmente, il riferimento + completo come descritto sopra. Questo è dedicato ai commenti obsoleti. + +Riferimenti usando reStructuredText +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Per fare riferimento a funzioni e tipi di dato definiti nei commenti kernel-doc +all'interno dei documenti reStructuredText, utilizzate i riferimenti dal +`dominio Sphinx per il C`_. Per esempio:: + + See function :c:func:`foo` and struct/union/enum/typedef :c:type:`bar`. + +Nonostante il riferimento ai tipi di dato funzioni col solo nome, +ovvero senza specificare struct/union/enum/typedef, potreste preferire il +seguente:: + + See :c:type:`struct foo <foo>`. + See :c:type:`union bar <bar>`. + See :c:type:`enum baz <baz>`. + See :c:type:`typedef meh <meh>`. + +Questo produce dei collegamenti migliori, ed è in linea con il modo in cui +kernel-doc gestisce i riferimenti. + +Per maggiori informazioni, siete pregati di consultare la documentazione +del `dominio Sphinx per il C`_. + +Commenti per una documentazione generale +---------------------------------------- + +Al fine d'avere il codice ed i commenti nello stesso file, potete includere +dei blocchi di documentazione kernel-doc con un formato libero invece +che nel formato specifico per funzioni, strutture, unioni, enumerati o tipi +di dato. Per esempio, questo tipo di commento potrebbe essere usato per la +spiegazione delle operazioni di un driver o di una libreria + +Questo s'ottiene utilizzando la parola chiave ``DOC:`` a cui viene associato +un titolo. + +Generalmente il formato di un commento generico o di visione d'insieme è +il seguente:: + + /** + * DOC: Theory of Operation + * + * The whizbang foobar is a dilly of a gizmo. It can do whatever you + * want it to do, at any time. It reads your mind. Here's how it works. + * + * foo bar splat + * + * The only drawback to this gizmo is that is can sometimes damage + * hardware, software, or its subject(s). + */ + +Il titolo che segue ``DOC:`` funziona da intestazione all'interno del file +sorgente, ma anche come identificatore per l'estrazione di questi commenti di +documentazione. Quindi, il titolo dev'essere unico all'interno del file. + +Includere i commenti di tipo kernel-doc +======================================= + +I commenti di documentazione possono essere inclusi in un qualsiasi documento +di tipo reStructuredText mediante l'apposita direttiva nell'estensione +kernel-doc per Sphinx. + +Le direttive kernel-doc sono nel formato:: + + .. kernel-doc:: source + :option: + +Il campo *source* è il percorso ad un file sorgente, relativo alla cartella +principale dei sorgenti del kernel. La direttiva supporta le seguenti opzioni: + +export: *[source-pattern ...]* + Include la documentazione per tutte le funzioni presenti nel file sorgente + (*source*) che sono state esportate utilizzando ``EXPORT_SYMBOL`` o + ``EXPORT_SYMBOL_GPL`` in *source* o in qualsiasi altro *source-pattern* + specificato. + + Il campo *source-patter* è utile quando i commenti kernel-doc sono stati + scritti nei file d'intestazione, mentre ``EXPORT_SYMBOL`` e + ``EXPORT_SYMBOL_GPL`` si trovano vicino alla definizione delle funzioni. + + Esempi:: + + .. kernel-doc:: lib/bitmap.c + :export: + + .. kernel-doc:: include/net/mac80211.h + :export: net/mac80211/*.c + +internal: *[source-pattern ...]* + Include la documentazione per tutte le funzioni ed i tipi presenti nel file + sorgente (*source*) che **non** sono stati esportati utilizzando + ``EXPORT_SYMBOL`` o ``EXPORT_SYMBOL_GPL`` né in *source* né in qualsiasi + altro *source-pattern* specificato. + + Esempio:: + + .. kernel-doc:: drivers/gpu/drm/i915/intel_audio.c + :internal: + +doc: *title* + Include la documentazione del paragrafo ``DOC:`` identificato dal titolo + (*title*) all'interno del file sorgente (*source*). Gli spazi in *title* sono + permessi; non virgolettate *title*. Il campo *title* è utilizzato per + identificare un paragrafo e per questo non viene incluso nella documentazione + finale. Verificate d'avere l'intestazione appropriata nei documenti + reStructuredText. + + Esempio:: + + .. kernel-doc:: drivers/gpu/drm/i915/intel_audio.c + :doc: High Definition Audio over HDMI and Display Port + +functions: *function* *[...]* + Dal file sorgente (*source*) include la documentazione per le funzioni + elencate (*function*). + + Esempio:: + + .. kernel-doc:: lib/bitmap.c + :functions: bitmap_parselist bitmap_parselist_user + +Senza alcuna opzione, la direttiva kernel-doc include tutti i commenti di +documentazione presenti nel file sorgente (*source*). + +L'estensione kernel-doc fa parte dei sorgenti del kernel, la si può trovare +in ``Documentation/sphinx/kerneldoc.py``. Internamente, viene utilizzato +lo script ``scripts/kernel-doc`` per estrarre i commenti di documentazione +dai file sorgenti. + +Come utilizzare kernel-doc per generare pagine man +-------------------------------------------------- + +Se volete utilizzare kernel-doc solo per generare delle pagine man, potete +farlo direttamente dai sorgenti del kernel:: + + $ scripts/kernel-doc -man $(git grep -l '/\*\*' -- :^Documentation :^tools) | scripts/split-man.pl /tmp/man diff --git a/Documentation/translations/it_IT/doc-guide/parse-headers.rst b/Documentation/translations/it_IT/doc-guide/parse-headers.rst new file mode 100644 index 000000000..b38918ca6 --- /dev/null +++ b/Documentation/translations/it_IT/doc-guide/parse-headers.rst @@ -0,0 +1,196 @@ +.. include:: ../disclaimer-ita.rst + +.. note:: Per leggere la documentazione originale in inglese: + :ref:`Documentation/doc-guide/index.rst <doc_guide>` + +========================================= +Includere gli i file di intestazione uAPI +========================================= + +Qualche volta è utile includere dei file di intestazione e degli esempi di codice C +al fine di descrivere l'API per lo spazio utente e per generare dei riferimenti +fra il codice e la documentazione. Aggiungere i riferimenti ai file dell'API +dello spazio utente ha ulteriori vantaggi: Sphinx genererà dei messaggi +d'avviso se un simbolo non viene trovato nella documentazione. Questo permette +di mantenere allineate la documentazione della uAPI (API spazio utente) +con le modifiche del kernel. +Il programma :ref:`parse_headers.pl <it_parse_headers>` genera questi riferimenti. +Esso dev'essere invocato attraverso un Makefile, mentre si genera la +documentazione. Per avere un esempio su come utilizzarlo all'interno del kernel +consultate ``Documentation/media/Makefile``. + +.. _it_parse_headers: + +parse_headers.pl +^^^^^^^^^^^^^^^^ + +NOME +**** + + +parse_headers.pl - analizza i file C al fine di identificare funzioni, +strutture, enumerati e definizioni, e creare riferimenti per Sphinx + +SINTASSI +******** + + +\ **parse_headers.pl**\ [<options>] <C_FILE> <OUT_FILE> [<EXCEPTIONS_FILE>] + +Dove <options> può essere: --debug, --usage o --help. + + +OPZIONI +******* + + + +\ **--debug**\ + + Lo script viene messo in modalità verbosa, utile per il debugging. + + +\ **--usage**\ + + Mostra un messaggio d'aiuto breve e termina. + + +\ **--help**\ + + Mostra un messaggio d'aiuto dettagliato e termina. + + +DESCRIZIONE +*********** + +Converte un file d'intestazione o un file sorgente C (C_FILE) in un testo +ReStructuredText incluso mediante il blocco ..parsed-literal +con riferimenti alla documentazione che descrive l'API. Opzionalmente, +il programma accetta anche un altro file (EXCEPTIONS_FILE) che +descrive quali elementi debbano essere ignorati o il cui riferimento +deve puntare ad elemento diverso dal predefinito. + +Il file generato sarà disponibile in (OUT_FILE). + +Il programma è capace di identificare *define*, funzioni, strutture, +tipi di dato, enumerati e valori di enumerati, e di creare i riferimenti +per ognuno di loro. Inoltre, esso è capace di distinguere le #define +utilizzate per specificare i comandi ioctl di Linux. + +Il file EXCEPTIONS_FILE contiene due tipi di dichiarazioni: +\ **ignore**\ o \ **replace**\ . + +La sintassi per ignore è: + +ignore \ **tipo**\ \ **nome**\ + +La dichiarazione \ **ignore**\ significa che non verrà generato alcun +riferimento per il simbolo \ **name**\ di tipo \ **tipo**\ . + + +La sintassi per replace è: + +replace \ **tipo**\ \ **nome**\ \ **nuovo_valore**\ + +La dichiarazione \ **replace**\ significa che verrà generato un +riferimento per il simbolo \ **name**\ di tipo \ **tipo**\ , ma, invece +di utilizzare il valore predefinito, verrà utilizzato il valore +\ **nuovo_valore**\ . + +Per entrambe le dichiarazioni, il \ **tipo**\ può essere uno dei seguenti: + + +\ **ioctl**\ + + La dichiarazione ignore o replace verrà applicata su definizioni di ioctl + come la seguente: + + #define VIDIOC_DBG_S_REGISTER _IOW('V', 79, struct v4l2_dbg_register) + + + +\ **define**\ + + La dichiarazione ignore o replace verrà applicata su una qualsiasi #define + trovata in C_FILE. + + + +\ **typedef**\ + + La dichiarazione ignore o replace verrà applicata ad una dichiarazione typedef + in C_FILE. + + + +\ **struct**\ + + La dichiarazione ignore o replace verrà applicata ai nomi di strutture + in C_FILE. + + + +\ **enum**\ + + La dichiarazione ignore o replace verrà applicata ai nomi di enumerati + in C_FILE. + + + +\ **symbol**\ + + La dichiarazione ignore o replace verrà applicata ai nomi di valori di + enumerati in C_FILE. + + Per le dichiarazioni di tipo replace, il campo \ **new_value**\ utilizzerà + automaticamente i riferimenti :c:type: per \ **typedef**\ , \ **enum**\ e + \ **struct**\. Invece, utilizzerà :ref: per \ **ioctl**\ , \ **define**\ e + \ **symbol**\. Il tipo di riferimento può essere definito esplicitamente + nella dichiarazione stessa. + + +ESEMPI +****** + + +ignore define _VIDEODEV2_H + + +Ignora una definizione #define _VIDEODEV2_H nel file C_FILE. + +ignore symbol PRIVATE + + +In un enumerato come il seguente: + +enum foo { BAR1, BAR2, PRIVATE }; + +Non genererà alcun riferimento per \ **PRIVATE**\ . + +replace symbol BAR1 :c:type:\`foo\` +replace symbol BAR2 :c:type:\`foo\` + + +In un enumerato come il seguente: + +enum foo { BAR1, BAR2, PRIVATE }; + +Genererà un riferimento ai valori BAR1 e BAR2 dal simbolo foo nel dominio C. + + +BUGS +**** + +Riferire ogni malfunzionamento a Mauro Carvalho Chehab <mchehab@s-opensource.com> + + +COPYRIGHT +********* + + +Copyright (c) 2016 by Mauro Carvalho Chehab <mchehab@s-opensource.com>. + +Licenza GPLv2: GNU GPL version 2 <http://gnu.org/licenses/gpl.html>. + +Questo è software libero: siete liberi di cambiarlo e ridistribuirlo. +Non c'è alcuna garanzia, nei limiti permessi dalla legge. diff --git a/Documentation/translations/it_IT/doc-guide/sphinx.rst b/Documentation/translations/it_IT/doc-guide/sphinx.rst new file mode 100644 index 000000000..474b7e127 --- /dev/null +++ b/Documentation/translations/it_IT/doc-guide/sphinx.rst @@ -0,0 +1,457 @@ +.. include:: ../disclaimer-ita.rst + +.. note:: Per leggere la documentazione originale in inglese: + :ref:`Documentation/doc-guide/index.rst <doc_guide>` + +Introduzione +============ + +Il kernel Linux usa `Sphinx`_ per la generazione della documentazione a partire +dai file `reStructuredText`_ che si trovano nella cartella ``Documentation``. +Per generare la documentazione in HTML o PDF, usate comandi ``make htmldocs`` o +``make pdfdocs``. La documentazione così generata sarà disponibile nella +cartella ``Documentation/output``. + +.. _Sphinx: http://www.sphinx-doc.org/ +.. _reStructuredText: http://docutils.sourceforge.net/rst.html + +I file reStructuredText possono contenere delle direttive che permettono di +includere i commenti di documentazione, o di tipo kernel-doc, dai file +sorgenti. +Solitamente questi commenti sono utilizzati per descrivere le funzioni, i tipi +e l'architettura del codice. I commenti di tipo kernel-doc hanno una struttura +e formato speciale, ma a parte questo vengono processati come reStructuredText. + +Inoltre, ci sono migliaia di altri documenti in formato testo sparsi nella +cartella ``Documentation``. Alcuni di questi verranno probabilmente convertiti, +nel tempo, in formato reStructuredText, ma la maggior parte di questi rimarranno +in formato testo. + +.. _it_sphinx_install: + +Installazione Sphinx +==================== + +I marcatori ReST utilizzati nei file in Documentation/ sono pensati per essere +processati da ``Sphinx`` nella versione 1.3 o superiore. Se desiderate produrre +un documento PDF è raccomandato l'utilizzo di una versione superiore alle 1.4.6. + +Esiste uno script che verifica i requisiti Sphinx. Per ulteriori dettagli +consultate :ref:`it_sphinx-pre-install`. + +La maggior parte delle distribuzioni Linux forniscono Sphinx, ma l'insieme dei +programmi e librerie è fragile e non è raro che dopo un aggiornamento di +Sphinx, o qualche altro pacchetto Python, la documentazione non venga più +generata correttamente. + +Un modo per evitare questo genere di problemi è quello di utilizzare una +versione diversa da quella fornita dalla vostra distribuzione. Per fare questo, +vi raccomandiamo di installare Sphinx dentro ad un ambiente virtuale usando +``virtualenv-3`` o ``virtualenv`` a seconda di come Python 3 è stato +pacchettizzato dalla vostra distribuzione. + +.. note:: + + #) Le versioni di Sphinx inferiori alla 1.5 non funzionano bene + con il pacchetto Python docutils versione 0.13.1 o superiore. + Se volete usare queste versioni, allora dovere eseguire + ``pip install 'docutils==0.12'``. + + #) Viene raccomandato l'uso del tema RTD per la documentazione in HTML. + A seconda della versione di Sphinx, potrebbe essere necessaria + l'installazione tramite il comando ``pip install sphinx_rtd_theme``. + + #) Alcune pagine ReST contengono delle formule matematiche. A causa del + modo in cui Sphinx funziona, queste espressioni sono scritte + utilizzando LaTeX. Per una corretta interpretazione, è necessario aver + installato texlive con i pacchetti amdfonts e amsmath. + +Riassumendo, se volete installare la versione 1.4.9 di Sphinx dovete eseguire:: + + $ virtualenv sphinx_1.4 + $ . sphinx_1.4/bin/activate + (sphinx_1.4) $ pip install -r Documentation/sphinx/requirements.txt + +Dopo aver eseguito ``. sphinx_1.4/bin/activate``, il prompt cambierà per +indicare che state usando il nuovo ambiente. Se aprite un nuova sessione, +prima di generare la documentazione, dovrete rieseguire questo comando per +rientrare nell'ambiente virtuale. + +Generazione d'immagini +---------------------- + +Il meccanismo che genera la documentazione del kernel contiene un'estensione +capace di gestire immagini in formato Graphviz e SVG (per maggior informazioni +vedere :ref:`it_sphinx_kfigure`). + +Per far si che questo funzioni, dovete installare entrambe i pacchetti +Graphviz e ImageMagick. Il sistema di generazione della documentazione è in +grado di procedere anche se questi pacchetti non sono installati, ma il +risultato, ovviamente, non includerà le immagini. + +Generazione in PDF e LaTeX +-------------------------- + +Al momento, la generazione di questi documenti è supportata solo dalle +versioni di Sphinx superiori alla 1.4. + +Per la generazione di PDF e LaTeX, avrete bisogno anche del pacchetto +``XeLaTeX`` nella versione 3.14159265 + +Per alcune distribuzioni Linux potrebbe essere necessario installare +anche una serie di pacchetti ``texlive`` in modo da fornire il supporto +minimo per il funzionamento di ``XeLaTeX``. + +.. _it_sphinx-pre-install: + +Verificare le dipendenze Sphinx +------------------------------- + +Esiste uno script che permette di verificare automaticamente le dipendenze di +Sphinx. Se lo script riesce a riconoscere la vostra distribuzione, allora +sarà in grado di darvi dei suggerimenti su come procedere per completare +l'installazione:: + + $ ./scripts/sphinx-pre-install + Checking if the needed tools for Fedora release 26 (Twenty Six) are available + Warning: better to also install "texlive-luatex85". + You should run: + + sudo dnf install -y texlive-luatex85 + /usr/bin/virtualenv sphinx_1.4 + . sphinx_1.4/bin/activate + pip install -r Documentation/sphinx/requirements.txt + + Can't build as 1 mandatory dependency is missing at ./scripts/sphinx-pre-install line 468. + +L'impostazione predefinita prevede il controllo dei requisiti per la generazione +di documenti html e PDF, includendo anche il supporto per le immagini, le +espressioni matematiche e LaTeX; inoltre, presume che venga utilizzato un +ambiente virtuale per Python. I requisiti per generare i documenti html +sono considerati obbligatori, gli altri sono opzionali. + +Questo script ha i seguenti parametri: + +``--no-pdf`` + Disabilita i controlli per la generazione di PDF; + +``--no-virtualenv`` + Utilizza l'ambiente predefinito dal sistema operativo invece che + l'ambiente virtuale per Python; + + +Generazione della documentazione Sphinx +======================================= + +Per generare la documentazione in formato HTML o PDF si eseguono i rispettivi +comandi ``make htmldocs`` o ``make pdfdocs``. Esistono anche altri formati +in cui è possibile generare la documentazione; per maggiori informazioni +potere eseguire il comando ``make help``. +La documentazione così generata sarà disponibile nella sottocartella +``Documentation/output``. + +Ovviamente, per generare la documentazione, Sphinx (``sphinx-build``) +dev'essere installato. Se disponibile, il tema *Read the Docs* per Sphinx +verrà utilizzato per ottenere una documentazione HTML più gradevole. +Per la documentazione in formato PDF, invece, avrete bisogno di ``XeLaTeX` +e di ``convert(1)`` disponibile in ImageMagick (https://www.imagemagick.org). +Tipicamente, tutti questi pacchetti sono disponibili e pacchettizzati nelle +distribuzioni Linux. + +Per poter passare ulteriori opzioni a Sphinx potete utilizzare la variabile +make ``SPHINXOPTS``. Per esempio, se volete che Sphinx sia più verboso durante +la generazione potete usare il seguente comando ``make SPHINXOPTS=-v htmldocs``. + +Potete eliminare la documentazione generata tramite il comando +``make cleandocs``. + +Scrivere la documentazione +========================== + +Aggiungere nuova documentazione è semplice: + +1. aggiungete un file ``.rst`` nella sottocartella ``Documentation`` +2. aggiungete un riferimento ad esso nell'indice (`TOC tree`_) in + ``Documentation/index.rst``. + +.. _TOC tree: http://www.sphinx-doc.org/en/stable/markup/toctree.html + +Questo, di solito, è sufficiente per la documentazione più semplice (come +quella che state leggendo ora), ma per una documentazione più elaborata è +consigliato creare una sottocartella dedicata (o, quando possibile, utilizzarne +una già esistente). Per esempio, il sottosistema grafico è documentato nella +sottocartella ``Documentation/gpu``; questa documentazione è divisa in +diversi file ``.rst`` ed un indice ``index.rst`` (con un ``toctree`` +dedicato) a cui si fa riferimento nell'indice principale. + +Consultate la documentazione di `Sphinx`_ e `reStructuredText`_ per maggiori +informazione circa le loro potenzialità. In particolare, il +`manuale introduttivo a reStructuredText`_ di Sphinx è un buon punto da +cui cominciare. Esistono, inoltre, anche alcuni +`costruttori specifici per Sphinx`_. + +.. _`manuale introduttivo a reStructuredText`: http://www.sphinx-doc.org/en/stable/rest.html +.. _`costruttori specifici per Sphinx`: http://www.sphinx-doc.org/en/stable/markup/index.html + +Guide linea per la documentazione del kernel +-------------------------------------------- + +In questa sezione troverete alcune linee guida specifiche per la documentazione +del kernel: + +* Non esagerate con i costrutti di reStructuredText. Mantenete la + documentazione semplice. La maggior parte della documentazione dovrebbe + essere testo semplice con una strutturazione minima che permetta la + conversione in diversi formati. + +* Mantenete la strutturazione il più fedele possibile all'originale quando + convertite un documento in formato reStructuredText. + +* Aggiornate i contenuti quando convertite della documentazione, non limitatevi + solo alla formattazione. + +* Mantenete la decorazione dei livelli di intestazione come segue: + + 1. ``=`` con una linea superiore per il titolo del documento:: + + ====== + Titolo + ====== + + 2. ``=`` per i capitoli:: + + Capitoli + ======== + + 3. ``-`` per le sezioni:: + + Sezioni + ------- + + 4. ``~`` per le sottosezioni:: + + Sottosezioni + ~~~~~~~~~~~~ + + Sebbene RST non forzi alcun ordine specifico (*Piuttosto che imporre + un numero ed un ordine fisso di decorazioni, l'ordine utilizzato sarà + quello incontrato*), avere uniformità dei livelli principali rende più + semplice la lettura dei documenti. + +* Per inserire blocchi di testo con caratteri a dimensione fissa (codici di + esempio, casi d'uso, eccetera): utilizzate ``::`` quando non è necessario + evidenziare la sintassi, specialmente per piccoli frammenti; invece, + utilizzate ``.. code-block:: <language>`` per blocchi di più lunghi che + potranno beneficiare dell'avere la sintassi evidenziata. + + +Il dominio C +------------ + +Il **Dominio Sphinx C** (denominato c) è adatto alla documentazione delle API C. +Per esempio, un prototipo di una funzione: + +.. code-block:: rst + + .. c:function:: int ioctl( int fd, int request ) + +Il dominio C per kernel-doc ha delle funzionalità aggiuntive. Per esempio, +potete assegnare un nuovo nome di riferimento ad una funzione con un nome +molto comune come ``open`` o ``ioctl``: + +.. code-block:: rst + + .. c:function:: int ioctl( int fd, int request ) + :name: VIDIOC_LOG_STATUS + +Il nome della funzione (per esempio ioctl) rimane nel testo ma il nome del suo +riferimento cambia da ``ioctl`` a ``VIDIOC_LOG_STATUS``. Anche la voce +nell'indice cambia in ``VIDIOC_LOG_STATUS`` e si potrà quindi fare riferimento +a questa funzione scrivendo: + +.. code-block:: rst + + :c:func:`VIDIOC_LOG_STATUS` + + +Tabelle a liste +--------------- + +Raccomandiamo l'uso delle tabelle in formato lista (*list table*). Le tabelle +in formato lista sono liste di liste. In confronto all'ASCII-art potrebbero +non apparire di facile lettura nei file in formato testo. Il loro vantaggio è +che sono facili da creare o modificare e che la differenza di una modifica è +molto più significativa perché limitata alle modifiche del contenuto. + +La ``flat-table`` è anch'essa una lista di liste simile alle ``list-table`` +ma con delle funzionalità aggiuntive: + +* column-span: col ruolo ``cspan`` una cella può essere estesa attraverso + colonne successive + +* raw-span: col ruolo ``rspan`` una cella può essere estesa attraverso + righe successive + +* auto-span: la cella più a destra viene estesa verso destra per compensare + la mancanza di celle. Con l'opzione ``:fill-cells:`` questo comportamento + può essere cambiato da *auto-span* ad *auto-fill*, il quale inserisce + automaticamente celle (vuote) invece che estendere l'ultima. + +opzioni: + +* ``:header-rows:`` [int] conta le righe di intestazione +* ``:stub-columns:`` [int] conta le colonne di stub +* ``:widths:`` [[int] [int] ... ] larghezza delle colonne +* ``:fill-cells:`` invece di estendere automaticamente una cella su quelle + mancanti, ne crea di vuote. + +ruoli: + +* ``:cspan:`` [int] colonne successive (*morecols*) +* ``:rspan:`` [int] righe successive (*morerows*) + +L'esempio successivo mostra come usare questo marcatore. Il primo livello della +nostra lista di liste è la *riga*. In una *riga* è possibile inserire solamente +la lista di celle che compongono la *riga* stessa. Fanno eccezione i *commenti* +( ``..`` ) ed i *collegamenti* (per esempio, un riferimento a +``:ref:`last row <last row>``` / :ref:`last row <it last row>`) + +.. code-block:: rst + + .. flat-table:: table title + :widths: 2 1 1 3 + + * - head col 1 + - head col 2 + - head col 3 + - head col 4 + + * - column 1 + - field 1.1 + - field 1.2 with autospan + + * - column 2 + - field 2.1 + - :rspan:`1` :cspan:`1` field 2.2 - 3.3 + + * .. _`it last row`: + + - column 3 + +Che verrà rappresentata nel seguente modo: + + .. flat-table:: table title + :widths: 2 1 1 3 + + * - head col 1 + - head col 2 + - head col 3 + - head col 4 + + * - column 1 + - field 1.1 + - field 1.2 with autospan + + * - column 2 + - field 2.1 + - :rspan:`1` :cspan:`1` field 2.2 - 3.3 + + * .. _`it last row`: + + - column 3 + +.. _it_sphinx_kfigure: + +Figure ed immagini +================== + +Se volete aggiungere un'immagine, utilizzate le direttive ``kernel-figure`` +e ``kernel-image``. Per esempio, per inserire una figura di un'immagine in +formato SVG:: + + .. kernel-figure:: ../../../doc-guide/svg_image.svg + :alt: una semplice immagine SVG + + Una semplice immagine SVG + +.. _it_svg_image_example: + +.. kernel-figure:: ../../../doc-guide/svg_image.svg + :alt: una semplice immagine SVG + + Una semplice immagine SVG + +Le direttive del kernel per figure ed immagini supportano il formato **DOT**, +per maggiori informazioni + +* DOT: http://graphviz.org/pdf/dotguide.pdf +* Graphviz: http://www.graphviz.org/content/dot-language + +Un piccolo esempio (:ref:`it_hello_dot_file`):: + + .. kernel-figure:: ../../../doc-guide/hello.dot + :alt: ciao mondo + + Esempio DOT + +.. _it_hello_dot_file: + +.. kernel-figure:: ../../../doc-guide/hello.dot + :alt: ciao mondo + + Esempio DOT + +Tramite la direttiva ``kernel-render`` è possibile aggiungere codice specifico; +ad esempio nel formato **DOT** di Graphviz.:: + + .. kernel-render:: DOT + :alt: foobar digraph + :caption: Codice **DOT** (Graphviz) integrato + + digraph foo { + "bar" -> "baz"; + } + +La rappresentazione dipenderà dei programmi installati. Se avete Graphviz +installato, vedrete un'immagine vettoriale. In caso contrario, il codice grezzo +verrà rappresentato come *blocco testuale* (:ref:`it_hello_dot_render`). + +.. _it_hello_dot_render: + +.. kernel-render:: DOT + :alt: foobar digraph + :caption: Codice **DOT** (Graphviz) integrato + + digraph foo { + "bar" -> "baz"; + } + +La direttiva *render* ha tutte le opzioni della direttiva *figure*, con +l'aggiunta dell'opzione ``caption``. Se ``caption`` ha un valore allora +un nodo *figure* viene aggiunto. Altrimenti verrà aggiunto un nodo *image*. +L'opzione ``caption`` è necessaria in caso si vogliano aggiungere dei +riferimenti (:ref:`it_hello_svg_render`). + +Per la scrittura di codice **SVG**:: + + .. kernel-render:: SVG + :caption: Integrare codice **SVG** + :alt: so-nw-arrow + + <?xml version="1.0" encoding="UTF-8"?> + <svg xmlns="http://www.w3.org/2000/svg" version="1.1" ...> + ... + </svg> + +.. _it_hello_svg_render: + +.. kernel-render:: SVG + :caption: Integrare codice **SVG** + :alt: so-nw-arrow + + <?xml version="1.0" encoding="UTF-8"?> + <svg xmlns="http://www.w3.org/2000/svg" + version="1.1" baseProfile="full" width="70px" height="40px" viewBox="0 0 700 400"> + <line x1="180" y1="370" x2="500" y2="50" stroke="black" stroke-width="15px"/> + <polygon points="585 0 525 25 585 50" transform="rotate(135 525 25)"/> + </svg> diff --git a/Documentation/translations/it_IT/index.rst b/Documentation/translations/it_IT/index.rst new file mode 100644 index 000000000..898a7823a --- /dev/null +++ b/Documentation/translations/it_IT/index.rst @@ -0,0 +1,118 @@ +.. _it_linux_doc: + +=================== +Traduzione italiana +=================== + +L'obiettivo di questa traduzione è di rendere più facile la lettura e +la comprensione per chi preferisce leggere in lingua italiana. +Tenete presente che la documentazione di riferimento rimane comunque +quella in lingua inglese: :ref:`linux_doc` + +Questa traduzione cerca di essere il più fedele possibile all'originale ma +è ovvio che alcune frasi vadano trasformate: non aspettatevi una traduzione +letterale. Quando possibile, si eviteranno gli inglesismi ed al loro posto +verranno utilizzate le corrispettive parole italiane. + +Se notate che la traduzione non è più aggiornata potete contattare +direttamente il manutentore della traduzione italiana. + +Se notate che la documentazione contiene errori o dimenticanze, allora +verificate la documentazione di riferimento in lingua inglese. Se il problema +è presente anche nella documentazione di riferimento, contattate il suo +manutentore. Se avete problemi a scrivere in inglese, potete comunque +riportare il problema al manutentore della traduzione italiana. + +Manutentore della traduzione italiana: Federico Vaga <federico.vaga@vaga.pv.it> + +La documentazione del kernel Linux +================================== + +Questo è il livello principale della documentazione del kernel in +lingua italiana. La traduzione è incompleta, noterete degli avvisi +che vi segnaleranno la mancanza di una traduzione o di un gruppo di +traduzioni. + +Più in generale, la documentazione, come il kernel stesso, sono in +costante sviluppo; particolarmente vero in quanto stiamo lavorando +alla riorganizzazione della documentazione in modo più coerente. +I miglioramenti alla documentazione sono sempre i benvenuti; per cui, +se vuoi aiutare, iscriviti alla lista di discussione linux-doc presso +vger.kernel.org. + +Documentazione sulla licenza dei sorgenti +----------------------------------------- + +I seguenti documenti descrivono la licenza usata nei sorgenti del kernel Linux +(GPLv2), come licenziare i singoli file; inoltre troverete i riferimenti al +testo integrale della licenza. + +.. warning:: + + TODO ancora da tradurre + +Documentazione per gli utenti +----------------------------- + +I seguenti manuali sono scritti per gli *utenti* del kernel - ovvero, +coloro che cercano di farlo funzionare in modo ottimale su un dato sistema + +.. warning:: + + TODO ancora da tradurre + +Documentazione per gli sviluppatori di applicazioni +--------------------------------------------------- + +Il manuale delle API verso lo spazio utente è una collezione di documenti +che descrivono le interfacce del kernel viste dagli sviluppatori +di applicazioni. + +.. warning:: + + TODO ancora da tradurre + + +Introduzione allo sviluppo del kernel +------------------------------------- + +Questi manuali contengono informazioni su come contribuire allo sviluppo +del kernel. +Attorno al kernel Linux gira una comunità molto grande con migliaia di +sviluppatori che contribuiscono ogni anno. Come in ogni grande comunità, +sapere come le cose vengono fatte renderà il processo di integrazione delle +vostre modifiche molto più semplice + +.. toctree:: + :maxdepth: 2 + + doc-guide/index + kernel-hacking/index + +.. warning:: + + TODO ancora da tradurre + +Documentazione della API del kernel +----------------------------------- + +Questi manuali forniscono dettagli su come funzionano i sottosistemi del +kernel dal punto di vista degli sviluppatori del kernel. Molte delle +informazioni contenute in questi manuali sono prese direttamente dai +file sorgenti, informazioni aggiuntive vengono aggiunte solo se necessarie +(o almeno ci proviamo — probabilmente *non* tutto quello che è davvero +necessario). + +.. warning:: + + TODO ancora da tradurre + +Documentazione specifica per architettura +----------------------------------------- + +Questi manuali forniscono dettagli di programmazione per le diverse +implementazioni d'architettura. + +.. warning:: + + TODO ancora da tradurre diff --git a/Documentation/translations/it_IT/kernel-hacking/hacking.rst b/Documentation/translations/it_IT/kernel-hacking/hacking.rst new file mode 100644 index 000000000..7178e517a --- /dev/null +++ b/Documentation/translations/it_IT/kernel-hacking/hacking.rst @@ -0,0 +1,855 @@ +.. include:: ../disclaimer-ita.rst + +.. note:: Per leggere la documentazione originale in inglese: + :ref:`Documentation/kernel-hacking/hacking.rst <kernel_hacking_hack>` + +:Original: :ref:`Documentation/kernel-hacking/hacking.rst <kernel_hacking_hack>` +:Translator: Federico Vaga <federico.vaga@vaga.pv.it> + +.. _it_kernel_hacking_hack: + +================================================= +L'inaffidabile guida all'hacking del kernel Linux +================================================= + +:Author: Rusty Russell + +Introduzione +============ + +Benvenuto, gentile lettore, alla notevole ed inaffidabile guida all'hacking +del kernel Linux ad opera di Rusty. Questo documento descrive le procedure +più usate ed i concetti necessari per scrivere codice per il kernel: lo scopo +è di fornire ai programmatori C più esperti un manuale di base per sviluppo. +Eviterò dettagli implementativi: per questo abbiamo il codice, +ed ignorerò intere parti di alcune procedure. + +Prima di leggere questa guida, sappiate che non ho mai voluto scriverla, +essendo esageratamente sotto qualificato, ma ho sempre voluto leggere +qualcosa di simile, e quindi questa era l'unica via. Spero che possa +crescere e diventare un compendio di buone pratiche, punti di partenza +e generiche informazioni. + +Gli attori +========== + +In qualsiasi momento ognuna delle CPU di un sistema può essere: + +- non associata ad alcun processo, servendo un'interruzione hardware; + +- non associata ad alcun processo, servendo un softirq o tasklet; + +- in esecuzione nello spazio kernel, associata ad un processo + (contesto utente); + +- in esecuzione di un processo nello spazio utente; + +Esiste un ordine fra questi casi. Gli ultimi due possono avvicendarsi (preempt) +l'un l'altro, ma a parte questo esiste una gerarchia rigida: ognuno di questi +può avvicendarsi solo ad uno di quelli sottostanti. Per esempio, mentre un +softirq è in esecuzione su d'una CPU, nessun altro softirq può avvicendarsi +nell'esecuzione, ma un'interruzione hardware può. Ciò nonostante, le altre CPU +del sistema operano indipendentemente. + +Più avanti vedremo alcuni modi in cui dal contesto utente è possibile bloccare +le interruzioni, così da impedirne davvero il diritto di prelazione. + +Contesto utente +--------------- + +Ci si trova nel contesto utente quando si arriva da una chiamata di sistema +od altre eccezioni: come nello spazio utente, altre procedure più importanti, +o le interruzioni, possono far valere il proprio diritto di prelazione sul +vostro processo. Potete sospendere l'esecuzione chiamando :c:func:`schedule()`. + +.. note:: + + Si è sempre in contesto utente quando un modulo viene caricato o rimosso, + e durante le operazioni nello strato dei dispositivi a blocchi + (*block layer*). + +Nel contesto utente, il puntatore ``current`` (il quale indica il processo al +momento in esecuzione) è valido, e :c:func:`in_interrupt()` +(``include/linux/preempt.h``) è falsa. + +.. warning:: + + Attenzione che se avete la prelazione o i softirq disabilitati (vedere + di seguito), :c:func:`in_interrupt()` ritornerà un falso positivo. + +Interruzioni hardware (Hard IRQs) +--------------------------------- + +Temporizzatori, schede di rete e tastiere sono esempi di vero hardware +che possono produrre interruzioni in un qualsiasi momento. Il kernel esegue +i gestori d'interruzione che prestano un servizio all'hardware. Il kernel +garantisce che questi gestori non vengano mai interrotti: se una stessa +interruzione arriva, questa verrà accodata (o scartata). +Dato che durante la loro esecuzione le interruzioni vengono disabilitate, +i gestori d'interruzioni devono essere veloci: spesso si limitano +esclusivamente a notificare la presa in carico dell'interruzione, +programmare una 'interruzione software' per l'esecuzione e quindi terminare. + +Potete dire d'essere in una interruzione hardware perché :c:func:`in_irq()` +ritorna vero. + +.. warning:: + + Attenzione, questa ritornerà un falso positivo se le interruzioni + sono disabilitate (vedere di seguito). + +Contesto d'interruzione software: softirq e tasklet +--------------------------------------------------- + +Quando una chiamata di sistema sta per tornare allo spazio utente, +oppure un gestore d'interruzioni termina, qualsiasi 'interruzione software' +marcata come pendente (solitamente da un'interruzione hardware) viene +eseguita (``kernel/softirq.c``). + +La maggior parte del lavoro utile alla gestione di un'interruzione avviene qui. +All'inizio della transizione ai sistemi multiprocessore, c'erano solo i +cosiddetti 'bottom half' (BH), i quali non traevano alcun vantaggio da questi +sistemi. Non appena abbandonammo i computer raffazzonati con fiammiferi e +cicche, abbandonammo anche questa limitazione e migrammo alle interruzioni +software 'softirqs'. + +Il file ``include/linux/interrupt.h`` elenca i differenti tipi di 'softirq'. +Un tipo di softirq molto importante è il timer (``include/linux/timer.h``): +potete programmarlo per far si che esegua funzioni dopo un determinato +periodo di tempo. + +Dato che i softirq possono essere eseguiti simultaneamente su più di un +processore, spesso diventa estenuante l'averci a che fare. Per questa ragione, +i tasklet (``include/linux/interrupt.h``) vengo usati più di frequente: +possono essere registrati dinamicamente (il che significa che potete averne +quanti ne volete), e garantiscono che un qualsiasi tasklet verrà eseguito +solo su un processore alla volta, sebbene diversi tasklet possono essere +eseguiti simultaneamente. + +.. warning:: + + Il nome 'tasklet' è ingannevole: non hanno niente a che fare + con i 'processi' ('tasks'), e probabilmente hanno più a che vedere + con qualche pessima vodka che Alexey Kuznetsov si fece a quel tempo. + +Potete determinate se siete in un softirq (o tasklet) utilizzando la +macro :c:func:`in_softirq()` (``include/linux/preempt.h``). + +.. warning:: + + State attenti che questa macro ritornerà un falso positivo + se :ref:`botton half lock <it_local_bh_disable>` è bloccato. + +Alcune regole basilari +====================== + +Nessuna protezione della memoria + Se corrompete la memoria, che sia in contesto utente o d'interruzione, + la macchina si pianterà. Siete sicuri che quello che volete fare + non possa essere fatto nello spazio utente? + +Nessun numero in virgola mobile o MMX + Il contesto della FPU non è salvato; anche se siete in contesto utente + lo stato dell'FPU probabilmente non corrisponde a quello del processo + corrente: vi incasinerete con lo stato di qualche altro processo. Se + volete davvero usare la virgola mobile, allora dovrete salvare e recuperare + lo stato dell'FPU (ed evitare cambi di contesto). Generalmente è una + cattiva idea; usate l'aritmetica a virgola fissa. + +Un limite rigido dello stack + A seconda della configurazione del kernel lo stack è fra 3K e 6K per la + maggior parte delle architetture a 32-bit; è di 14K per la maggior + parte di quelle a 64-bit; e spesso è condiviso con le interruzioni, + per cui non si può usare. + Evitare profonde ricorsioni ad enormi array locali nello stack + (allocateli dinamicamente). + +Il kernel Linux è portabile + Quindi mantenetelo tale. Il vostro codice dovrebbe essere a 64-bit ed + indipendente dall'ordine dei byte (endianess) di un processore. Inoltre, + dovreste minimizzare il codice specifico per un processore; per esempio + il codice assembly dovrebbe essere incapsulato in modo pulito e minimizzato + per facilitarne la migrazione. Generalmente questo codice dovrebbe essere + limitato alla parte di kernel specifica per un'architettura. + +ioctl: non scrivere nuove chiamate di sistema +============================================= + +Una chiamata di sistema, generalmente, è scritta così:: + + asmlinkage long sys_mycall(int arg) + { + return 0; + } + +Primo, nella maggior parte dei casi non volete creare nuove chiamate di +sistema. +Create un dispositivo a caratteri ed implementate l'appropriata chiamata ioctl. +Questo meccanismo è molto più flessibile delle chiamate di sistema: esso non +dev'essere dichiarato in tutte le architetture nei file +``include/asm/unistd.h`` e ``arch/kernel/entry.S``; inoltre, è improbabile +che questo venga accettato da Linus. + +Se tutto quello che il vostro codice fa è leggere o scrivere alcuni parametri, +considerate l'implementazione di un'interfaccia :c:func:`sysfs()`. + +All'interno di una ioctl vi trovate nel contesto utente di un processo. Quando +avviene un errore dovete ritornare un valore negativo di errno (consultate +``include/uapi/asm-generic/errno-base.h``, +``include/uapi/asm-generic/errno.h`` e ``include/linux/errno.h``), altrimenti +ritornate 0. + +Dopo aver dormito dovreste verificare se ci sono stati dei segnali: il modo +Unix/Linux di gestire un segnale è di uscire temporaneamente dalla chiamata +di sistema con l'errore ``-ERESTARTSYS``. La chiamata di sistema ritornerà +al contesto utente, eseguirà il gestore del segnale e poi la vostra chiamata +di sistema riprenderà (a meno che l'utente non l'abbia disabilitata). Quindi, +dovreste essere pronti per continuare l'esecuzione, per esempio nel mezzo +della manipolazione di una struttura dati. + +:: + + if (signal_pending(current)) + return -ERESTARTSYS; + +Se dovete eseguire dei calcoli molto lunghi: pensate allo spazio utente. +Se **davvero** volete farlo nel kernel ricordatevi di verificare periodicamente +se dovete *lasciare* il processore (ricordatevi che, per ogni processore, c'è +un sistema multi-processo senza diritto di prelazione). +Esempio:: + + cond_resched(); /* Will sleep */ + +Una breve nota sulla progettazione delle interfacce: il motto dei sistemi +UNIX è "fornite meccanismi e non politiche" + +La ricetta per uno stallo +========================= + +Non è permesso invocare una procedura che potrebbe dormire, fanno eccezione +i seguenti casi: + +- Siete in un contesto utente. + +- Non trattenete alcun spinlock. + +- Avete abilitato le interruzioni (in realtà, Andy Kleen dice che + lo schedulatore le abiliterà per voi, ma probabilmente questo non è quello + che volete). + +Da tener presente che alcune funzioni potrebbero dormire implicitamente: +le più comuni sono quelle per l'accesso allo spazio utente (\*_user) e +quelle per l'allocazione della memoria senza l'opzione ``GFP_ATOMIC`` + +Dovreste sempre compilare il kernel con l'opzione ``CONFIG_DEBUG_ATOMIC_SLEEP`` +attiva, questa vi avviserà se infrangete una di queste regole. +Se **infrangete** le regole, allora potreste bloccare il vostro scatolotto. + +Veramente. + +Alcune delle procedure più comuni +================================= + +:c:func:`printk()` +------------------ + +Definita in ``include/linux/printk.h`` + +:c:func:`printk()` fornisce messaggi alla console, dmesg, e al demone syslog. +Essa è utile per il debugging o per la notifica di errori; può essere +utilizzata anche all'interno del contesto d'interruzione, ma usatela con +cautela: una macchina che ha la propria console inondata da messaggi diventa +inutilizzabile. La funzione utilizza un formato stringa quasi compatibile con +la printf ANSI C, e la concatenazione di una stringa C come primo argomento +per indicare la "priorità":: + + printk(KERN_INFO "i = %u\n", i); + +Consultate ``include/linux/kern_levels.h`` per gli altri valori ``KERN_``; +questi sono interpretati da syslog come livelli. Un caso speciale: +per stampare un indirizzo IP usate:: + + __be32 ipaddress; + printk(KERN_INFO "my ip: %pI4\n", &ipaddress); + + +:c:func:`printk()` utilizza un buffer interno di 1K e non s'accorge di +eventuali sforamenti. Accertatevi che vi basti. + +.. note:: + + Saprete di essere un vero hacker del kernel quando inizierete a digitare + nei vostri programmi utenti le printf come se fossero printk :) + +.. note:: + + Un'altra nota a parte: la versione originale di Unix 6 aveva un commento + sopra alla funzione printf: "Printf non dovrebbe essere usata per il + chiacchiericcio". Dovreste seguire questo consiglio. + +:c:func:`copy_to_user()` / :c:func:`copy_from_user()` / :c:func:`get_user()` / :c:func:`put_user()` +--------------------------------------------------------------------------------------------------- + +Definite in ``include/linux/uaccess.h`` / ``asm/uaccess.h`` + +**[DORMONO]** + +:c:func:`put_user()` e :c:func:`get_user()` sono usate per ricevere ed +impostare singoli valori (come int, char, o long) da e verso lo spazio utente. +Un puntatore nello spazio utente non dovrebbe mai essere dereferenziato: i dati +dovrebbero essere copiati usando suddette procedure. Entrambe ritornano +``-EFAULT`` oppure 0. + +:c:func:`copy_to_user()` e :c:func:`copy_from_user()` sono più generiche: +esse copiano una quantità arbitraria di dati da e verso lo spazio utente. + +.. warning:: + + Al contrario di:c:func:`put_user()` e :c:func:`get_user()`, queste + funzioni ritornano la quantità di dati copiati (0 è comunque un successo). + +[Sì, questa stupida interfaccia mi imbarazza. La battaglia torna in auge anno +dopo anno. --RR] + +Le funzioni potrebbero dormire implicitamente. Queste non dovrebbero mai essere +invocate fuori dal contesto utente (non ha senso), con le interruzioni +disabilitate, o con uno spinlock trattenuto. + +:c:func:`kmalloc()`/:c:func:`kfree()` +------------------------------------- + +Definite in ``include/linux/slab.h`` + +**[POTREBBERO DORMIRE: LEGGI SOTTO]** + +Queste procedure sono utilizzate per la richiesta dinamica di un puntatore ad +un pezzo di memoria allineato, esattamente come malloc e free nello spazio +utente, ma :c:func:`kmalloc()` ha un argomento aggiuntivo per indicare alcune +opzioni. Le opzioni più importanti sono: + +``GFP_KERNEL`` + Potrebbe dormire per librarare della memoria. L'opzione fornisce il modo + più affidabile per allocare memoria, ma il suo uso è strettamente limitato + allo spazio utente. + +``GFP_ATOMIC`` + Non dorme. Meno affidabile di ``GFP_KERNEL``, ma può essere usata in un + contesto d'interruzione. Dovreste avere **davvero** una buona strategia + per la gestione degli errori in caso di mancanza di memoria. + +``GFP_DMA`` + Alloca memoria per il DMA sul bus ISA nello spazio d'indirizzamento + inferiore ai 16MB. Se non sapete cos'è allora non vi serve. + Molto inaffidabile. + +Se vedete un messaggio d'avviso per una funzione dormiente che viene chiamata +da un contesto errato, allora probabilmente avete usato una funzione +d'allocazione dormiente da un contesto d'interruzione senza ``GFP_ATOMIC``. +Dovreste correggerlo. Sbrigatevi, non cincischiate. + +Se allocate almeno ``PAGE_SIZE``(``asm/page.h`` o ``asm/page_types.h``) byte, +considerate l'uso di :c:func:`__get_free_pages()` (``include/linux/gfp.h``). +Accetta un argomento che definisce l'ordine (0 per per la dimensione di una +pagine, 1 per una doppia pagina, 2 per quattro pagine, eccetra) e le stesse +opzioni d'allocazione viste precedentemente. + +Se state allocando un numero di byte notevolemnte superiore ad una pagina +potete usare :c:func:`vmalloc()`. Essa allocherà memoria virtuale all'interno +dello spazio kernel. Questo è un blocco di memoria fisica non contiguo, ma +la MMU vi darà l'impressione che lo sia (quindi, sarà contiguo solo dal punto +di vista dei processori, non dal punto di vista dei driver dei dispositivi +esterni). +Se per qualche strana ragione avete davvero bisogno di una grossa quantità di +memoria fisica contigua, avete un problema: Linux non ha un buon supporto per +questo caso d'uso perché, dopo un po' di tempo, la frammentazione della memoria +rende l'operazione difficile. Il modo migliore per allocare un simile blocco +all'inizio dell'avvio del sistema è attraverso la procedura +:c:func:`alloc_bootmem()`. + +Prima di inventare la vostra cache per gli oggetti più usati, considerate +l'uso di una cache slab disponibile in ``include/linux/slab.h``. + +:c:func:`current()` +------------------- + +Definita in ``include/asm/current.h`` + +Questa variabile globale (in realtà una macro) contiene un puntatore alla +struttura del processo corrente, quindi è valido solo dal contesto utente. +Per esempio, quando un processo esegue una chiamata di sistema, questo +punterà alla struttura dati del processo chiamate. +Nel contesto d'interruzione in suo valore **non è NULL**. + +:c:func:`mdelay()`/:c:func:`udelay()` +------------------------------------- + +Definite in ``include/asm/delay.h`` / ``include/linux/delay.h`` + +Le funzioni :c:func:`udelay()` e :c:func:`ndelay()` possono essere utilizzate +per brevi pause. Non usate grandi valori perché rischiate d'avere un +overflow - in questo contesto la funzione :c:func:`mdelay()` è utile, +oppure considerate :c:func:`msleep()`. + +:c:func:`cpu_to_be32()`/:c:func:`be32_to_cpu()`/:c:func:`cpu_to_le32()`/:c:func:`le32_to_cpu()` +----------------------------------------------------------------------------------------------- + +Definite in ``include/asm/byteorder.h`` + +La famiglia di funzioni :c:func:`cpu_to_be32()` (dove "32" può essere +sostituito da 64 o 16, e "be" con "le") forniscono un modo generico +per fare conversioni sull'ordine dei byte (endianess): esse ritornano +il valore convertito. Tutte le varianti supportano anche il processo inverso: +:c:func:`be32_to_cpu()`, eccetera. + +Queste funzioni hanno principalmente due varianti: la variante per +puntatori, come :c:func:`cpu_to_be32p(), che prende un puntatore +ad un tipo, e ritorna il valore convertito. L'altra variante per +la famiglia di conversioni "in-situ", come :c:func:`cpu_to_be32s()`, +che convertono il valore puntato da un puntatore, e ritornano void. + +:c:func:`local_irq_save()`/:c:func:`local_irq_restore()` +-------------------------------------------------------- + +Definite in ``include/linux/irqflags.h`` + +Queste funzioni abilitano e disabilitano le interruzioni hardware +sul processore locale. Entrambe sono rientranti; esse salvano lo stato +precedente nel proprio argomento ``unsigned long flags``. Se sapete +che le interruzioni sono abilite, potete semplicemente utilizzare +:c:func:`local_irq_disable()` e :c:func:`local_irq_enable()`. + +.. _it_local_bh_disable: + +:c:func:`local_bh_disable()`/:c:func:`local_bh_enable()` +-------------------------------------------------------- + +Definite in ``include/linux/bottom_half.h`` + + +Queste funzioni abilitano e disabilitano le interruzioni software +sul processore locale. Entrambe sono rientranti; se le interruzioni +software erano già state disabilitate in precedenza, rimarranno +disabilitate anche dopo aver invocato questa coppia di funzioni. +Lo scopo è di prevenire l'esecuzione di softirq e tasklet sul processore +attuale. + +:c:func:`smp_processor_id()` +---------------------------- + +Definita in ``include/linux/smp.h`` + +:c:func:`get_cpu()` nega il diritto di prelazione (quindi non potete essere +spostati su un altro processore all'improvviso) e ritorna il numero +del processore attuale, fra 0 e ``NR_CPUS``. Da notare che non è detto +che la numerazione dei processori sia continua. Quando avete terminato, +ritornate allo stato precedente con :c:func:`put_cpu()`. + +Se sapete che non dovete essere interrotti da altri processi (per esempio, +se siete in un contesto d'interruzione, o il diritto di prelazione +è disabilitato) potete utilizzare smp_processor_id(). + + +``__init``/``__exit``/``__initdata`` +------------------------------------ + +Definite in ``include/linux/init.h`` + +Dopo l'avvio, il kernel libera una sezione speciale; le funzioni marcate +con ``__init`` e le strutture dati marcate con ``__initdata`` vengono +eliminate dopo il completamento dell'avvio: in modo simile i moduli eliminano +questa memoria dopo l'inizializzazione. ``__exit`` viene utilizzato per +dichiarare che una funzione verrà utilizzata solo in fase di rimozione: +la detta funzione verrà eliminata quando il file che la contiene non è +compilato come modulo. Guardate l'header file per informazioni. Da notare che +non ha senso avere una funzione marcata come ``__init`` e al tempo stesso +esportata ai moduli utilizzando :c:func:`EXPORT_SYMBOL()` o +:c:func:`EXPORT_SYMBOL_GPL()` - non funzionerà. + + +:c:func:`__initcall()`/:c:func:`module_init()` +---------------------------------------------- + +Definite in ``include/linux/init.h`` / ``include/linux/module.h`` + +Molte parti del kernel funzionano bene come moduli (componenti del kernel +caricabili dinamicamente). L'utilizzo delle macro :c:func:`module_init()` +e :c:func:`module_exit()` semplifica la scrittura di codice che può funzionare +sia come modulo, sia come parte del kernel, senza l'ausilio di #ifdef. + +La macro :c:func:`module_init()` definisce quale funzione dev'essere +chiamata quando il modulo viene inserito (se il file è stato compilato come +tale), o in fase di avvio : se il file non è stato compilato come modulo la +macro :c:func:`module_init()` diventa equivalente a :c:func:`__initcall()`, +la quale, tramite qualche magia del linker, s'assicura che la funzione venga +chiamata durante l'avvio. + +La funzione può ritornare un numero d'errore negativo per scatenare un +fallimento del caricamento (sfortunatamente, questo non ha effetto se il +modulo è compilato come parte integrante del kernel). Questa funzione è chiamata +in contesto utente con le interruzioni abilitate, quindi potrebbe dormire. + + +:c:func:`module_exit()` +----------------------- + + +Definita in ``include/linux/module.h`` + +Questa macro definisce la funzione che dev'essere chiamata al momento della +rimozione (o mai, nel caso in cui il file sia parte integrante del kernel). +Essa verrà chiamata solo quando il contatore d'uso del modulo raggiunge lo +zero. Questa funzione può anche dormire, ma non può fallire: tutto dev'essere +ripulito prima che la funzione ritorni. + +Da notare che questa macro è opzionale: se non presente, il modulo non sarà +removibile (a meno che non usiate 'rmmod -f' ). + + +:c:func:`try_module_get()`/:c:func:`module_put()` +------------------------------------------------- + +Definite in ``include/linux/module.h`` + +Queste funzioni maneggiano il contatore d'uso del modulo per proteggerlo dalla +rimozione (in aggiunta, un modulo non può essere rimosso se un altro modulo +utilizzo uno dei sui simboli esportati: vedere di seguito). Prima di eseguire +codice del modulo, dovreste chiamare :c:func:`try_module_get()` su quel modulo: +se fallisce significa che il modulo è stato rimosso e dovete agire come se +non fosse presente. Altrimenti, potete accedere al modulo in sicurezza, e +chiamare :c:func:`module_put()` quando avete finito. + +La maggior parte delle strutture registrabili hanno un campo owner +(proprietario), come nella struttura +:c:type:`struct file_operations <file_operations>`. +Impostate questo campo al valore della macro ``THIS_MODULE``. + + +Code d'attesa ``include/linux/wait.h`` +====================================== + +**[DORMONO]** + +Una coda d'attesa è usata per aspettare che qualcuno vi attivi quando una +certa condizione s'avvera. Per evitare corse critiche, devono essere usate +con cautela. Dichiarate una :c:type:`wait_queue_head_t`, e poi i processi +che vogliono attendere il verificarsi di quella condizione dichiareranno +una :c:type:`wait_queue_entry_t` facendo riferimento a loro stessi, poi +metteranno questa in coda. + +Dichiarazione +------------- + +Potere dichiarare una ``wait_queue_head_t`` utilizzando la macro +:c:func:`DECLARE_WAIT_QUEUE_HEAD()` oppure utilizzando la procedura +:c:func:`init_waitqueue_head()` nel vostro codice d'inizializzazione. + +Accodamento +----------- + +Mettersi in una coda d'attesa è piuttosto complesso, perché dovete +mettervi in coda prima di verificare la condizione. Esiste una macro +a questo scopo: :c:func:`wait_event_interruptible()` (``include/linux/wait.h``). +Il primo argomento è la testa della coda d'attesa, e il secondo è +un'espressione che dev'essere valutata; la macro ritorna 0 quando questa +espressione è vera, altrimenti ``-ERESTARTSYS`` se è stato ricevuto un segnale. +La versione :c:func:`wait_event()` ignora i segnali. + +Svegliare una procedura in coda +------------------------------- + +Chiamate :c:func:`wake_up()` (``include/linux/wait.h``); questa attiverà tutti +i processi in coda. Ad eccezione se uno di questi è impostato come +``TASK_EXCLUSIVE``, in questo caso i rimanenti non verranno svegliati. +Nello stesso header file esistono altre varianti di questa funzione. + +Operazioni atomiche +=================== + +Certe operazioni sono garantite come atomiche su tutte le piattaforme. +Il primo gruppo di operazioni utilizza :c:type:`atomic_t` +(``include/asm/atomic.h``); questo contiene un intero con segno (minimo 32bit), +e dovete utilizzare queste funzione per modificare o leggere variabili di tipo +:c:type:`atomic_t`. :c:func:`atomic_read()` e :c:func:`atomic_set()` leggono ed +impostano il contatore, :c:func:`atomic_add()`, :c:func:`atomic_sub()`, +:c:func:`atomic_inc()`, :c:func:`atomic_dec()`, e +:c:func:`atomic_dec_and_test()` (ritorna vero se raggiunge zero dopo essere +stata decrementata). + +Sì. Ritorna vero (ovvero != 0) se la variabile atomica è zero. + +Da notare che queste funzioni sono più lente rispetto alla normale aritmetica, +e quindi non dovrebbero essere usate a sproposito. + +Il secondo gruppo di operazioni atomiche sono definite in +``include/linux/bitops.h`` ed agiscono sui bit d'una variabile di tipo +``unsigned long``. Queste operazioni prendono come argomento un puntatore +alla variabile, e un numero di bit dove 0 è quello meno significativo. +:c:func:`set_bit()`, :c:func:`clear_bit()` e :c:func:`change_bit()` +impostano, cancellano, ed invertono il bit indicato. +:c:func:`test_and_set_bit()`, :c:func:`test_and_clear_bit()` e +:c:func:`test_and_change_bit()` fanno la stessa cosa, ad eccezione che +ritornano vero se il bit era impostato; queste sono particolarmente +utili quando si vuole impostare atomicamente dei flag. + +Con queste operazioni è possibile utilizzare indici di bit che eccedono +il valore ``BITS_PER_LONG``. Il comportamento è strano sulle piattaforme +big-endian quindi è meglio evitarlo. + +Simboli +======= + +All'interno del kernel, si seguono le normali regole del linker (ovvero, +a meno che un simbolo non venga dichiarato con visibilita limitata ad un +file con la parola chiave ``static``, esso può essere utilizzato in qualsiasi +parte del kernel). Nonostante ciò, per i moduli, esiste una tabella dei +simboli esportati che limita i punti di accesso al kernel. Anche i moduli +possono esportare simboli. + +:c:func:`EXPORT_SYMBOL()` +------------------------- + +Definita in ``include/linux/export.h`` + +Questo è il classico metodo per esportare un simbolo: i moduli caricati +dinamicamente potranno utilizzare normalmente il simbolo. + +:c:func:`EXPORT_SYMBOL_GPL()` +----------------------------- + +Definita in ``include/linux/export.h`` + +Essa è simile a :c:func:`EXPORT_SYMBOL()` ad eccezione del fatto che i +simboli esportati con :c:func:`EXPORT_SYMBOL_GPL()` possono essere +utilizzati solo dai moduli che hanno dichiarato una licenza compatibile +con la GPL attraverso :c:func:`MODULE_LICENSE()`. Questo implica che la +funzione esportata è considerata interna, e non una vera e propria interfaccia. +Alcuni manutentori e sviluppatori potrebbero comunque richiedere +:c:func:`EXPORT_SYMBOL_GPL()` quando si aggiungono nuove funzionalità o +interfacce. + +Procedure e convenzioni +======================= + +Liste doppiamente concatenate ``include/linux/list.h`` +------------------------------------------------------ + +Un tempo negli header del kernel c'erano tre gruppi di funzioni per +le liste concatenate, ma questa è stata la vincente. Se non avete particolari +necessità per una semplice lista concatenata, allora questa è una buona scelta. + +In particolare, :c:func:`list_for_each_entry()` è utile. + +Convenzione dei valori di ritorno +--------------------------------- + +Per codice chiamato in contesto utente, è molto comune sfidare le convenzioni +C e ritornare 0 in caso di successo, ed un codice di errore negativo +(eg. ``-EFAULT``) nei casi fallimentari. Questo potrebbe essere controintuitivo +a prima vista, ma è abbastanza diffuso nel kernel. + +Utilizzate :c:func:`ERR_PTR()` (``include/linux/err.h``) per codificare +un numero d'errore negativo in un puntatore, e :c:func:`IS_ERR()` e +:c:func:`PTR_ERR()` per recuperarlo di nuovo: così si evita d'avere un +puntatore dedicato per il numero d'errore. Da brividi, ma in senso positivo. + +Rompere la compilazione +----------------------- + +Linus e gli altri sviluppatori a volte cambiano i nomi delle funzioni e +delle strutture nei kernel in sviluppo; questo non è solo per tenere +tutti sulle spine: questo riflette cambiamenti fondamentati (eg. la funzione +non può più essere chiamata con le funzioni attive, o fa controlli aggiuntivi, +o non fa più controlli che venivano fatti in precedenza). Solitamente a questo +s'accompagna un'adeguata e completa nota sulla lista di discussone +linux-kernel; cercate negli archivi. +Solitamente eseguire una semplice sostituzione su tutto un file rendere +le cose **peggiori**. + +Inizializzazione dei campi d'una struttura +------------------------------------------ + +Il metodo preferito per l'inizializzazione delle strutture è quello +di utilizzare gli inizializzatori designati, come definiti nello +standard ISO C99, eg:: + + static struct block_device_operations opt_fops = { + .open = opt_open, + .release = opt_release, + .ioctl = opt_ioctl, + .check_media_change = opt_media_change, + }; + +Questo rende più facile la ricerca con grep, e rende più chiaro quale campo +viene impostato. Dovreste fare così perché si mostra meglio. + +Estensioni GNU +-------------- + +Le estensioni GNU sono esplicitamente permesse nel kernel Linux. Da notare +che alcune delle più complesse non sono ben supportate, per via dello scarso +sviluppo, ma le seguenti sono da considerarsi la norma (per maggiori dettagli, +leggete la sezione "C Extensions" nella pagina info di GCC - Sì, davvero +la pagina info, la pagina man è solo un breve riassunto delle cose nella +pagina info). + +- Funzioni inline + +- Istruzioni in espressioni (ie. il costrutto ({ and }) ). + +- Dichiarate attributi di una funzione / variabile / tipo + (__attribute__) + +- typeof + +- Array con lunghezza zero + +- Macro varargs + +- Aritmentica sui puntatori void + +- Inizializzatori non costanti + +- Istruzioni assembler (non al di fuori di 'arch/' e 'include/asm/') + +- Nomi delle funzioni come stringhe (__func__). + +- __builtin_constant_p() + +Siate sospettosi quando utilizzate long long nel kernel, il codice generato +da gcc è orribile ed anche peggio: le divisioni e le moltiplicazioni non +funzionano sulle piattaforme i386 perché le rispettive funzioni di runtime +di GCC non sono incluse nell'ambiente del kernel. + +C++ +--- + +Solitamente utilizzare il C++ nel kernel è una cattiva idea perché +il kernel non fornisce il necessario ambiente di runtime e gli header file +non sono stati verificati. Rimane comunque possibile, ma non consigliato. +Se davvero volete usarlo, almeno evitate le eccezioni. + +NUMif +----- + +Viene generalmente considerato più pulito l'uso delle macro negli header file +(o all'inizio dei file .c) per astrarre funzioni piuttosto che utlizzare +l'istruzione di pre-processore \`#if' all'interno del codice sorgente. + +Mettere le vostre cose nel kernel +================================= + +Al fine d'avere le vostre cose in ordine per l'inclusione ufficiale, o +anche per avere patch pulite, c'è del lavoro amministrativo da fare: + +- Trovare di chi è lo stagno in cui state pisciando. Guardare in cima + ai file sorgenti, all'interno del file ``MAINTAINERS``, ed alla fine + di tutti nel file ``CREDITS``. Dovreste coordinarvi con queste persone + per evitare di duplicare gli sforzi, o provare qualcosa che è già stato + rigettato. + + Assicuratevi di mettere il vostro nome ed indirizzo email in cima a + tutti i file che create o che mangeggiate significativamente. Questo è + il primo posto dove le persone guarderanno quando troveranno un baco, + o quando **loro** vorranno fare una modifica. + +- Solitamente vorrete un'opzione di configurazione per la vostra modifica + al kernel. Modificate ``Kconfig`` nella cartella giusta. Il linguaggio + Config è facile con copia ed incolla, e c'è una completa documentazione + nel file ``Documentation/kbuild/kconfig-language.txt``. + + Nella descrizione della vostra opzione, assicuratevi di parlare sia agli + utenti esperti sia agli utente che non sanno nulla del vostro lavoro. + Menzionate qui le incompatibilità ed i problemi. Chiaramente la + descrizione deve terminare con “if in doubt, say N” (se siete in dubbio, + dite N) (oppure, occasionalmente, \`Y'); questo è per le persone che non + hanno idea di che cosa voi stiate parlando. + +- Modificate il file ``Makefile``: le variabili CONFIG sono esportate qui, + quindi potete solitamente aggiungere una riga come la seguete + "obj-$(CONFIG_xxx) += xxx.o". La sintassi è documentata nel file + ``Documentation/kbuild/makefiles.txt``. + +- Aggiungete voi stessi in ``CREDITS`` se avete fatto qualcosa di notevole, + solitamente qualcosa che supera il singolo file (comunque il vostro nome + dovrebbe essere all'inizio dei file sorgenti). ``MAINTAINERS`` significa + che volete essere consultati quando vengono fatte delle modifiche ad un + sottosistema, e quando ci sono dei bachi; questo implica molto di più + di un semplice impegno su una parte del codice. + +- Infine, non dimenticatevi di leggere + ``Documentation/process/submitting-patches.rst`` e possibilmente anche + ``Documentation/process/submitting-drivers.rst``. + +Trucchetti del kernel +===================== + +Dopo una rapida occhiata al codice, questi sono i preferiti. Sentitevi liberi +di aggiungerne altri. + +``arch/x86/include/asm/delay.h``:: + + #define ndelay(n) (__builtin_constant_p(n) ? \ + ((n) > 20000 ? __bad_ndelay() : __const_udelay((n) * 5ul)) : \ + __ndelay(n)) + + +``include/linux/fs.h``:: + + /* + * Kernel pointers have redundant information, so we can use a + * scheme where we can return either an error code or a dentry + * pointer with the same return value. + * + * This should be a per-architecture thing, to allow different + * error and pointer decisions. + */ + #define ERR_PTR(err) ((void *)((long)(err))) + #define PTR_ERR(ptr) ((long)(ptr)) + #define IS_ERR(ptr) ((unsigned long)(ptr) > (unsigned long)(-1000)) + +``arch/x86/include/asm/uaccess_32.h:``:: + + #define copy_to_user(to,from,n) \ + (__builtin_constant_p(n) ? \ + __constant_copy_to_user((to),(from),(n)) : \ + __generic_copy_to_user((to),(from),(n))) + + +``arch/sparc/kernel/head.S:``:: + + /* + * Sun people can't spell worth damn. "compatability" indeed. + * At least we *know* we can't spell, and use a spell-checker. + */ + + /* Uh, actually Linus it is I who cannot spell. Too much murky + * Sparc assembly will do this to ya. + */ + C_LABEL(cputypvar): + .asciz "compatibility" + + /* Tested on SS-5, SS-10. Probably someone at Sun applied a spell-checker. */ + .align 4 + C_LABEL(cputypvar_sun4m): + .asciz "compatible" + + +``arch/sparc/lib/checksum.S:``:: + + /* Sun, you just can't beat me, you just can't. Stop trying, + * give up. I'm serious, I am going to kick the living shit + * out of you, game over, lights out. + */ + + +Ringraziamenti +============== + +Ringrazio Andi Kleen per le sue idee, le risposte alle mie domande, +le correzioni dei miei errori, l'aggiunta di contenuti, eccetera. +Philipp Rumpf per l'ortografia e per aver reso più chiaro il testo, e +per alcuni eccellenti punti tutt'altro che ovvi. Werner Almesberger +per avermi fornito un ottimo riassunto di :c:func:`disable_irq()`, +e Jes Sorensen e Andrea Arcangeli per le precisazioni. Michael Elizabeth +Chastain per aver verificato ed aggiunto la sezione configurazione. +Telsa Gwynne per avermi insegnato DocBook. diff --git a/Documentation/translations/it_IT/kernel-hacking/index.rst b/Documentation/translations/it_IT/kernel-hacking/index.rst new file mode 100644 index 000000000..50228380b --- /dev/null +++ b/Documentation/translations/it_IT/kernel-hacking/index.rst @@ -0,0 +1,16 @@ +.. include:: ../disclaimer-ita.rst + +:Original: :ref:`Documentation/kernel-hacking/index.rst <kernel_hacking>` +:Translator: Federico Vaga <federico.vaga@vaga.pv.it> + +.. _it_kernel_hacking: + +============================ +Guida all'hacking del kernel +============================ + +.. toctree:: + :maxdepth: 2 + + hacking + locking diff --git a/Documentation/translations/it_IT/kernel-hacking/locking.rst b/Documentation/translations/it_IT/kernel-hacking/locking.rst new file mode 100644 index 000000000..753643622 --- /dev/null +++ b/Documentation/translations/it_IT/kernel-hacking/locking.rst @@ -0,0 +1,1493 @@ +.. include:: ../disclaimer-ita.rst + +:Original: :ref:`Documentation/kernel-hacking/locking.rst <kernel_hacking_lock>` +:Translator: Federico Vaga <federico.vaga@vaga.pv.it> + +.. _it_kernel_hacking_lock: + +========================================== +L'inaffidabile guida alla sincronizzazione +========================================== + +:Author: Rusty Russell + +Introduzione +============ + +Benvenuto, alla notevole ed inaffidabile guida ai problemi di sincronizzazione +(locking) nel kernel. Questo documento descrive il sistema di sincronizzazione +nel kernel Linux 2.6. + +Dato il largo utilizzo del multi-threading e della prelazione nel kernel +Linux, chiunque voglia dilettarsi col kernel deve conoscere i concetti +fondamentali della concorrenza e della sincronizzazione nei sistemi +multi-processore. + +Il problema con la concorrenza +============================== + +(Saltatelo se sapete già cos'è una corsa critica). + +In un normale programma, potete incrementare un contatore nel seguente modo: + +:: + + contatore++; + +Questo è quello che vi aspettereste che accada sempre: + + +.. table:: Risultati attesi + + +------------------------------------+------------------------------------+ + | Istanza 1 | Istanza 2 | + +====================================+====================================+ + | leggi contatore (5) | | + +------------------------------------+------------------------------------+ + | aggiungi 1 (6) | | + +------------------------------------+------------------------------------+ + | scrivi contatore (6) | | + +------------------------------------+------------------------------------+ + | | leggi contatore (6) | + +------------------------------------+------------------------------------+ + | | aggiungi 1 (7) | + +------------------------------------+------------------------------------+ + | | scrivi contatore (7) | + +------------------------------------+------------------------------------+ + +Questo è quello che potrebbe succedere in realtà: + +.. table:: Possibile risultato + + +------------------------------------+------------------------------------+ + | Istanza 1 | Istanza 2 | + +====================================+====================================+ + | leggi contatore (5) | | + +------------------------------------+------------------------------------+ + | | leggi contatore (5) | + +------------------------------------+------------------------------------+ + | aggiungi 1 (6) | | + +------------------------------------+------------------------------------+ + | | aggiungi 1 (6) | + +------------------------------------+------------------------------------+ + | scrivi contatore (6) | | + +------------------------------------+------------------------------------+ + | | scrivi contatore (6) | + +------------------------------------+------------------------------------+ + + +Corse critiche e sezioni critiche +--------------------------------- + +Questa sovrapposizione, ovvero quando un risultato dipende dal tempo che +intercorre fra processi diversi, è chiamata corsa critica. La porzione +di codice che contiene questo problema è chiamata sezione critica. +In particolar modo da quando Linux ha incominciato a girare su +macchine multi-processore, le sezioni critiche sono diventate uno dei +maggiori problemi di progettazione ed implementazione del kernel. + +La prelazione può sortire gli stessi effetti, anche se c'è una sola CPU: +interrompendo un processo nella sua sezione critica otterremo comunque +la stessa corsa critica. In questo caso, il thread che si avvicenda +nell'esecuzione potrebbe eseguire anch'esso la sezione critica. + +La soluzione è quella di riconoscere quando avvengono questi accessi +simultanei, ed utilizzare i *lock* per accertarsi che solo un'istanza +per volta possa entrare nella sezione critica. Il kernel offre delle buone +funzioni a questo scopo. E poi ci sono quelle meno buone, ma farò finta +che non esistano. + +Sincronizzazione nel kernel Linux +================================= + +Se posso darvi un suggerimento: non dormite mai con qualcuno più pazzo di +voi. Ma se dovessi darvi un suggerimento sulla sincronizzazione: +**mantenetela semplice**. + +Siate riluttanti nell'introduzione di nuovi *lock*. + +Abbastanza strano, quest'ultimo è l'esatto opposto del mio suggerimento +su quando **avete** dormito con qualcuno più pazzo di voi. E dovreste +pensare a prendervi un cane bello grande. + +I due principali tipi di *lock* nel kernel: spinlock e mutex +------------------------------------------------------------ + +Ci sono due tipi principali di *lock* nel kernel. Il tipo fondamentale è lo +spinlock (``include/asm/spinlock.h``), un semplice *lock* che può essere +trattenuto solo da un processo: se non si può trattenere lo spinlock, allora +rimane in attesa attiva (in inglese *spinning*) finché non ci riesce. +Gli spinlock sono molto piccoli e rapidi, possono essere utilizzati ovunque. + +Il secondo tipo è il mutex (``include/linux/mutex.h``): è come uno spinlock, +ma potreste bloccarvi trattenendolo. Se non potete trattenere un mutex +il vostro processo si auto-sospenderà; verrà riattivato quando il mutex +verrà rilasciato. Questo significa che il processore potrà occuparsi d'altro +mentre il vostro processo è in attesa. Esistono molti casi in cui non potete +permettervi di sospendere un processo (vedere +:ref:`Quali funzioni possono essere chiamate in modo sicuro dalle interruzioni? <it_sleeping-things>`) +e quindi dovrete utilizzare gli spinlock. + +Nessuno di questi *lock* è ricorsivo: vedere +:ref:`Stallo: semplice ed avanzato <it_deadlock>` + +I *lock* e i kernel per sistemi monoprocessore +---------------------------------------------- + +Per i kernel compilati senza ``CONFIG_SMP`` e senza ``CONFIG_PREEMPT`` +gli spinlock non esistono. Questa è un'ottima scelta di progettazione: +quando nessun altro processo può essere eseguito in simultanea, allora +non c'è la necessità di avere un *lock*. + +Se il kernel è compilato senza ``CONFIG_SMP`` ma con ``CONFIG_PREEMPT``, +allora gli spinlock disabilitano la prelazione; questo è sufficiente a +prevenire le corse critiche. Nella maggior parte dei casi, possiamo considerare +la prelazione equivalente ad un sistema multi-processore senza preoccuparci +di trattarla indipendentemente. + +Dovreste verificare sempre la sincronizzazione con le opzioni ``CONFIG_SMP`` e +``CONFIG_PREEMPT`` abilitate, anche quando non avete un sistema +multi-processore, questo vi permetterà di identificare alcuni problemi +di sincronizzazione. + +Come vedremo di seguito, i mutex continuano ad esistere perché sono necessari +per la sincronizzazione fra processi in contesto utente. + +Sincronizzazione in contesto utente +----------------------------------- + +Se avete una struttura dati che verrà utilizzata solo dal contesto utente, +allora, per proteggerla, potete utilizzare un semplice mutex +(``include/linux/mutex.h``). Questo è il caso più semplice: inizializzate il +mutex; invocate :c:func:`mutex_lock_interruptible()` per trattenerlo e +:c:func:`mutex_unlock()` per rilasciarlo. C'è anche :c:func:`mutex_lock()` +ma questa dovrebbe essere evitata perché non ritorna in caso di segnali. + +Per esempio: ``net/netfilter/nf_sockopt.c`` permette la registrazione +di nuove chiamate per :c:func:`setsockopt()` e :c:func:`getsockopt()` +usando la funzione :c:func:`nf_register_sockopt()`. La registrazione e +la rimozione vengono eseguite solamente quando il modulo viene caricato +o scaricato (e durante l'avvio del sistema, qui non abbiamo concorrenza), +e la lista delle funzioni registrate viene consultata solamente quando +:c:func:`setsockopt()` o :c:func:`getsockopt()` sono sconosciute al sistema. +In questo caso ``nf_sockopt_mutex`` è perfetto allo scopo, in particolar modo +visto che setsockopt e getsockopt potrebbero dormire. + +Sincronizzazione fra il contesto utente e i softirq +--------------------------------------------------- + +Se un softirq condivide dati col contesto utente, avete due problemi. +Primo, il contesto utente corrente potrebbe essere interroto da un softirq, +e secondo, la sezione critica potrebbe essere eseguita da un altro +processore. Questo è quando :c:func:`spin_lock_bh()` +(``include/linux/spinlock.h``) viene utilizzato. Questo disabilita i softirq +sul processore e trattiene il *lock*. Invece, :c:func:`spin_unlock_bh()` fa +l'opposto. (Il suffisso '_bh' è un residuo storico che fa riferimento al +"Bottom Halves", il vecchio nome delle interruzioni software. In un mondo +perfetto questa funzione si chiamerebbe 'spin_lock_softirq()'). + +Da notare che in questo caso potete utilizzare anche :c:func:`spin_lock_irq()` +o :c:func:`spin_lock_irqsave()`, queste fermano anche le interruzioni hardware: +vedere :ref:`Contesto di interruzione hardware <it_hardirq-context>`. + +Questo funziona alla perfezione anche sui sistemi monoprocessore: gli spinlock +svaniscono e questa macro diventa semplicemente :c:func:`local_bh_disable()` +(``include/linux/interrupt.h``), la quale impedisce ai softirq d'essere +eseguiti. + +Sincronizzazione fra contesto utente e i tasklet +------------------------------------------------ + +Questo caso è uguale al precedente, un tasklet viene eseguito da un softirq. + +Sincronizzazione fra contesto utente e i timer +---------------------------------------------- + +Anche questo caso è uguale al precedente, un timer viene eseguito da un +softirq. +Dal punto di vista della sincronizzazione, tasklet e timer sono identici. + +Sincronizzazione fra tasklet e timer +------------------------------------ + +Qualche volta un tasklet od un timer potrebbero condividere i dati con +un altro tasklet o timer + +Lo stesso tasklet/timer +~~~~~~~~~~~~~~~~~~~~~~~ + +Dato che un tasklet non viene mai eseguito contemporaneamente su due +processori, non dovete preoccuparvi che sia rientrante (ovvero eseguito +più volte in contemporanea), perfino su sistemi multi-processore. + +Differenti tasklet/timer +~~~~~~~~~~~~~~~~~~~~~~~~ + +Se un altro tasklet/timer vuole condividere dati col vostro tasklet o timer, +allora avrete bisogno entrambe di :c:func:`spin_lock()` e +:c:func:`spin_unlock()`. Qui :c:func:`spin_lock_bh()` è inutile, siete già +in un tasklet ed avete la garanzia che nessun altro verrà eseguito sullo +stesso processore. + +Sincronizzazione fra softirq +---------------------------- + +Spesso un softirq potrebbe condividere dati con se stesso o un tasklet/timer. + +Lo stesso softirq +~~~~~~~~~~~~~~~~~ + +Lo stesso softirq può essere eseguito su un diverso processore: allo scopo +di migliorare le prestazioni potete utilizzare dati riservati ad ogni +processore (vedere :ref:`Dati per processore <it_per-cpu>`). Se siete arrivati +fino a questo punto nell'uso dei softirq, probabilmente tenete alla scalabilità +delle prestazioni abbastanza da giustificarne la complessità aggiuntiva. + +Dovete utilizzare :c:func:`spin_lock()` e :c:func:`spin_unlock()` per +proteggere i dati condivisi. + +Diversi Softirqs +~~~~~~~~~~~~~~~~ + +Dovete utilizzare :c:func:`spin_lock()` e :c:func:`spin_unlock()` per +proteggere i dati condivisi, che siano timer, tasklet, diversi softirq o +lo stesso o altri softirq: uno qualsiasi di essi potrebbe essere in esecuzione +su un diverso processore. + +.. _`it_hardirq-context`: + +Contesto di interruzione hardware +================================= + +Solitamente le interruzioni hardware comunicano con un tasklet o un softirq. +Spesso questo si traduce nel mettere in coda qualcosa da fare che verrà +preso in carico da un softirq. + +Sincronizzazione fra interruzioni hardware e softirq/tasklet +------------------------------------------------------------ + +Se un gestore di interruzioni hardware condivide dati con un softirq, allora +avrete due preoccupazioni. Primo, il softirq può essere interrotto da +un'interruzione hardware, e secondo, la sezione critica potrebbe essere +eseguita da un'interruzione hardware su un processore diverso. Questo è il caso +dove :c:func:`spin_lock_irq()` viene utilizzato. Disabilita le interruzioni +sul processore che l'esegue, poi trattiene il lock. :c:func:`spin_unlock_irq()` +fa l'opposto. + +Il gestore d'interruzione hardware non usa :c:func:`spin_lock_irq()` perché +i softirq non possono essere eseguiti quando il gestore d'interruzione hardware +è in esecuzione: per questo si può usare :c:func:`spin_lock()`, che è un po' +più veloce. L'unica eccezione è quando un altro gestore d'interruzioni +hardware utilizza lo stesso *lock*: :c:func:`spin_lock_irq()` impedirà a questo +secondo gestore di interrompere quello in esecuzione. + +Questo funziona alla perfezione anche sui sistemi monoprocessore: gli spinlock +svaniscono e questa macro diventa semplicemente :c:func:`local_irq_disable()` +(``include/asm/smp.h``), la quale impedisce a softirq/tasklet/BH d'essere +eseguiti. + +:c:func:`spin_lock_irqsave()` (``include/linux/spinlock.h``) è una variante che +salva lo stato delle interruzioni in una variabile, questa verrà poi passata +a :c:func:`spin_unlock_irqrestore()`. Questo significa che lo stesso codice +potrà essere utilizzato in un'interruzione hardware (dove le interruzioni sono +già disabilitate) e in un softirq (dove la disabilitazione delle interruzioni +è richiesta). + +Da notare che i softirq (e quindi tasklet e timer) sono eseguiti al ritorno +da un'interruzione hardware, quindi :c:func:`spin_lock_irq()` interrompe +anche questi. Tenuto conto di questo si può dire che +:c:func:`spin_lock_irqsave()` è la funzione di sincronizzazione più generica +e potente. + +Sincronizzazione fra due gestori d'interruzioni hardware +-------------------------------------------------------- + +Condividere dati fra due gestori di interruzione hardware è molto raro, ma se +succede, dovreste usare :c:func:`spin_lock_irqsave()`: è una specificità +dell'architettura il fatto che tutte le interruzioni vengano interrotte +quando si eseguono di gestori di interruzioni. + +Bigino della sincronizzazione +============================= + +Pete Zaitcev ci offre il seguente riassunto: + +- Se siete in un contesto utente (una qualsiasi chiamata di sistema) + e volete sincronizzarvi con altri processi, usate i mutex. Potete trattenere + il mutex e dormire (``copy_from_user*(`` o ``kmalloc(x,GFP_KERNEL)``). + +- Altrimenti (== i dati possono essere manipolati da un'interruzione) usate + :c:func:`spin_lock_irqsave()` e :c:func:`spin_unlock_irqrestore()`. + +- Evitate di trattenere uno spinlock per più di 5 righe di codice incluse + le chiamate a funzione (ad eccezione di quell per l'accesso come + :c:func:`readb()`). + +Tabella dei requisiti minimi +---------------------------- + +La tabella seguente illustra i requisiti **minimi** per la sincronizzazione fra +diversi contesti. In alcuni casi, lo stesso contesto può essere eseguito solo +da un processore per volta, quindi non ci sono requisiti per la +sincronizzazione (per esempio, un thread può essere eseguito solo su un +processore alla volta, ma se deve condividere dati con un altro thread, allora +la sincronizzazione è necessaria). + +Ricordatevi il suggerimento qui sopra: potete sempre usare +:c:func:`spin_lock_irqsave()`, che è un sovrainsieme di tutte le altre funzioni +per spinlock. + +============== ============= ============= ========= ========= ========= ========= ======= ======= ============== ============== +. IRQ Handler A IRQ Handler B Softirq A Softirq B Tasklet A Tasklet B Timer A Timer B User Context A User Context B +============== ============= ============= ========= ========= ========= ========= ======= ======= ============== ============== +IRQ Handler A None +IRQ Handler B SLIS None +Softirq A SLI SLI SL +Softirq B SLI SLI SL SL +Tasklet A SLI SLI SL SL None +Tasklet B SLI SLI SL SL SL None +Timer A SLI SLI SL SL SL SL None +Timer B SLI SLI SL SL SL SL SL None +User Context A SLI SLI SLBH SLBH SLBH SLBH SLBH SLBH None +User Context B SLI SLI SLBH SLBH SLBH SLBH SLBH SLBH MLI None +============== ============= ============= ========= ========= ========= ========= ======= ======= ============== ============== + +Table: Tabella dei requisiti per la sincronizzazione + ++--------+----------------------------+ +| SLIS | spin_lock_irqsave | ++--------+----------------------------+ +| SLI | spin_lock_irq | ++--------+----------------------------+ +| SL | spin_lock | ++--------+----------------------------+ +| SLBH | spin_lock_bh | ++--------+----------------------------+ +| MLI | mutex_lock_interruptible | ++--------+----------------------------+ + +Table: Legenda per la tabella dei requisiti per la sincronizzazione + +Le funzioni *trylock* +===================== + +Ci sono funzioni che provano a trattenere un *lock* solo una volta e +ritornano immediatamente comunicato il successo od il fallimento +dell'operazione. Posso essere usate quando non serve accedere ai dati +protetti dal *lock* quando qualche altro thread lo sta già facendo +trattenendo il *lock*. Potrete acquisire il *lock* più tardi se vi +serve accedere ai dati protetti da questo *lock*. + +La funzione :c:func:`spin_trylock()` non ritenta di acquisire il *lock*, +se ci riesce al primo colpo ritorna un valore diverso da zero, altrimenti +se fallisce ritorna 0. Questa funzione può essere utilizzata in un qualunque +contesto, ma come :c:func:`spin_lock()`: dovete disabilitare i contesti che +potrebbero interrompervi e quindi trattenere lo spinlock. + +La funzione :c:func:`mutex_trylock()` invece di sospendere il vostro processo +ritorna un valore diverso da zero se è possibile trattenere il lock al primo +colpo, altrimenti se fallisce ritorna 0. Nonostante non dorma, questa funzione +non può essere usata in modo sicuro in contesti di interruzione hardware o +software. + +Esempi più comuni +================= + +Guardiamo un semplice esempio: una memoria che associa nomi a numeri. +La memoria tiene traccia di quanto spesso viene utilizzato ogni oggetto; +quando è piena, l'oggetto meno usato viene eliminato. + +Tutto in contesto utente +------------------------ + +Nel primo esempio, supponiamo che tutte le operazioni avvengano in contesto +utente (in soldoni, da una chiamata di sistema), quindi possiamo dormire. +Questo significa che possiamo usare i mutex per proteggere la nostra memoria +e tutti gli oggetti che contiene. Ecco il codice:: + + #include <linux/list.h> + #include <linux/slab.h> + #include <linux/string.h> + #include <linux/mutex.h> + #include <asm/errno.h> + + struct object + { + struct list_head list; + int id; + char name[32]; + int popularity; + }; + + /* Protects the cache, cache_num, and the objects within it */ + static DEFINE_MUTEX(cache_lock); + static LIST_HEAD(cache); + static unsigned int cache_num = 0; + #define MAX_CACHE_SIZE 10 + + /* Must be holding cache_lock */ + static struct object *__cache_find(int id) + { + struct object *i; + + list_for_each_entry(i, &cache, list) + if (i->id == id) { + i->popularity++; + return i; + } + return NULL; + } + + /* Must be holding cache_lock */ + static void __cache_delete(struct object *obj) + { + BUG_ON(!obj); + list_del(&obj->list); + kfree(obj); + cache_num--; + } + + /* Must be holding cache_lock */ + static void __cache_add(struct object *obj) + { + list_add(&obj->list, &cache); + if (++cache_num > MAX_CACHE_SIZE) { + struct object *i, *outcast = NULL; + list_for_each_entry(i, &cache, list) { + if (!outcast || i->popularity < outcast->popularity) + outcast = i; + } + __cache_delete(outcast); + } + } + + int cache_add(int id, const char *name) + { + struct object *obj; + + if ((obj = kmalloc(sizeof(*obj), GFP_KERNEL)) == NULL) + return -ENOMEM; + + strlcpy(obj->name, name, sizeof(obj->name)); + obj->id = id; + obj->popularity = 0; + + mutex_lock(&cache_lock); + __cache_add(obj); + mutex_unlock(&cache_lock); + return 0; + } + + void cache_delete(int id) + { + mutex_lock(&cache_lock); + __cache_delete(__cache_find(id)); + mutex_unlock(&cache_lock); + } + + int cache_find(int id, char *name) + { + struct object *obj; + int ret = -ENOENT; + + mutex_lock(&cache_lock); + obj = __cache_find(id); + if (obj) { + ret = 0; + strcpy(name, obj->name); + } + mutex_unlock(&cache_lock); + return ret; + } + +Da notare che ci assicuriamo sempre di trattenere cache_lock quando +aggiungiamo, rimuoviamo od ispezioniamo la memoria: sia la struttura +della memoria che il suo contenuto sono protetti dal *lock*. Questo +caso è semplice dato che copiamo i dati dall'utente e non permettiamo +mai loro di accedere direttamente agli oggetti. + +C'è una piccola ottimizzazione qui: nella funzione :c:func:`cache_add()` +impostiamo i campi dell'oggetto prima di acquisire il *lock*. Questo è +sicuro perché nessun altro potrà accedervi finché non lo inseriremo +nella memoria. + +Accesso dal contesto utente +--------------------------- + +Ora consideriamo il caso in cui :c:func:`cache_find()` può essere invocata +dal contesto d'interruzione: sia hardware che software. Un esempio potrebbe +essere un timer che elimina oggetti dalla memoria. + +Qui di seguito troverete la modifica nel formato *patch*: le righe ``-`` +sono quelle rimosse, mentre quelle ``+`` sono quelle aggiunte. + +:: + + --- cache.c.usercontext 2003-12-09 13:58:54.000000000 +1100 + +++ cache.c.interrupt 2003-12-09 14:07:49.000000000 +1100 + @@ -12,7 +12,7 @@ + int popularity; + }; + + -static DEFINE_MUTEX(cache_lock); + +static DEFINE_SPINLOCK(cache_lock); + static LIST_HEAD(cache); + static unsigned int cache_num = 0; + #define MAX_CACHE_SIZE 10 + @@ -55,6 +55,7 @@ + int cache_add(int id, const char *name) + { + struct object *obj; + + unsigned long flags; + + if ((obj = kmalloc(sizeof(*obj), GFP_KERNEL)) == NULL) + return -ENOMEM; + @@ -63,30 +64,33 @@ + obj->id = id; + obj->popularity = 0; + + - mutex_lock(&cache_lock); + + spin_lock_irqsave(&cache_lock, flags); + __cache_add(obj); + - mutex_unlock(&cache_lock); + + spin_unlock_irqrestore(&cache_lock, flags); + return 0; + } + + void cache_delete(int id) + { + - mutex_lock(&cache_lock); + + unsigned long flags; + + + + spin_lock_irqsave(&cache_lock, flags); + __cache_delete(__cache_find(id)); + - mutex_unlock(&cache_lock); + + spin_unlock_irqrestore(&cache_lock, flags); + } + + int cache_find(int id, char *name) + { + struct object *obj; + int ret = -ENOENT; + + unsigned long flags; + + - mutex_lock(&cache_lock); + + spin_lock_irqsave(&cache_lock, flags); + obj = __cache_find(id); + if (obj) { + ret = 0; + strcpy(name, obj->name); + } + - mutex_unlock(&cache_lock); + + spin_unlock_irqrestore(&cache_lock, flags); + return ret; + } + +Da notare che :c:func:`spin_lock_irqsave()` disabiliterà le interruzioni +se erano attive, altrimenti non farà niente (quando siamo già in un contesto +d'interruzione); dunque queste funzioni possono essere chiamante in +sicurezza da qualsiasi contesto. + +Sfortunatamente, :c:func:`cache_add()` invoca :c:func:`kmalloc()` con +l'opzione ``GFP_KERNEL`` che è permessa solo in contesto utente. Ho supposto +che :c:func:`cache_add()` venga chiamata dal contesto utente, altrimenti +questa opzione deve diventare un parametro di :c:func:`cache_add()`. + +Exposing Objects Outside This File +---------------------------------- + +Se i vostri oggetti contengono più informazioni, potrebbe non essere +sufficiente copiare i dati avanti e indietro: per esempio, altre parti del +codice potrebbero avere un puntatore a questi oggetti piuttosto che cercarli +ogni volta. Questo introduce due problemi. + +Il primo problema è che utilizziamo ``cache_lock`` per proteggere gli oggetti: +dobbiamo renderlo dinamico così che il resto del codice possa usarlo. Questo +rende la sincronizzazione più complicata dato che non avviene più in un unico +posto. + +Il secondo problema è il problema del ciclo di vita: se un'altra struttura +mantiene un puntatore ad un oggetto, presumibilmente si aspetta che questo +puntatore rimanga valido. Sfortunatamente, questo è garantito solo mentre +si trattiene il *lock*, altrimenti qualcuno potrebbe chiamare +:c:func:`cache_delete()` o peggio, aggiungere un oggetto che riutilizza lo +stesso indirizzo. + +Dato che c'è un solo *lock*, non potete trattenerlo a vita: altrimenti +nessun altro potrà eseguire il proprio lavoro. + +La soluzione a questo problema è l'uso di un contatore di riferimenti: +chiunque punti ad un oggetto deve incrementare il contatore, e decrementarlo +quando il puntatore non viene più usato. Quando il contatore raggiunge lo zero +significa che non è più usato e l'oggetto può essere rimosso. + +Ecco il codice:: + + --- cache.c.interrupt 2003-12-09 14:25:43.000000000 +1100 + +++ cache.c.refcnt 2003-12-09 14:33:05.000000000 +1100 + @@ -7,6 +7,7 @@ + struct object + { + struct list_head list; + + unsigned int refcnt; + int id; + char name[32]; + int popularity; + @@ -17,6 +18,35 @@ + static unsigned int cache_num = 0; + #define MAX_CACHE_SIZE 10 + + +static void __object_put(struct object *obj) + +{ + + if (--obj->refcnt == 0) + + kfree(obj); + +} + + + +static void __object_get(struct object *obj) + +{ + + obj->refcnt++; + +} + + + +void object_put(struct object *obj) + +{ + + unsigned long flags; + + + + spin_lock_irqsave(&cache_lock, flags); + + __object_put(obj); + + spin_unlock_irqrestore(&cache_lock, flags); + +} + + + +void object_get(struct object *obj) + +{ + + unsigned long flags; + + + + spin_lock_irqsave(&cache_lock, flags); + + __object_get(obj); + + spin_unlock_irqrestore(&cache_lock, flags); + +} + + + /* Must be holding cache_lock */ + static struct object *__cache_find(int id) + { + @@ -35,6 +65,7 @@ + { + BUG_ON(!obj); + list_del(&obj->list); + + __object_put(obj); + cache_num--; + } + + @@ -63,6 +94,7 @@ + strlcpy(obj->name, name, sizeof(obj->name)); + obj->id = id; + obj->popularity = 0; + + obj->refcnt = 1; /* The cache holds a reference */ + + spin_lock_irqsave(&cache_lock, flags); + __cache_add(obj); + @@ -79,18 +111,15 @@ + spin_unlock_irqrestore(&cache_lock, flags); + } + + -int cache_find(int id, char *name) + +struct object *cache_find(int id) + { + struct object *obj; + - int ret = -ENOENT; + unsigned long flags; + + spin_lock_irqsave(&cache_lock, flags); + obj = __cache_find(id); + - if (obj) { + - ret = 0; + - strcpy(name, obj->name); + - } + + if (obj) + + __object_get(obj); + spin_unlock_irqrestore(&cache_lock, flags); + - return ret; + + return obj; + } + +Abbiamo incapsulato il contatore di riferimenti nelle tipiche funzioni +di 'get' e 'put'. Ora possiamo ritornare l'oggetto da :c:func:`cache_find()` +col vantaggio che l'utente può dormire trattenendo l'oggetto (per esempio, +:c:func:`copy_to_user()` per copiare il nome verso lo spazio utente). + +Un altro punto da notare è che ho detto che il contatore dovrebbe incrementarsi +per ogni puntatore ad un oggetto: quindi il contatore di riferimenti è 1 +quando l'oggetto viene inserito nella memoria. In altre versione il framework +non trattiene un riferimento per se, ma diventa più complicato. + +Usare operazioni atomiche per il contatore di riferimenti +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +In sostanza, :c:type:`atomic_t` viene usato come contatore di riferimenti. +Ci sono un certo numbero di operazioni atomiche definite +in ``include/asm/atomic.h``: queste sono garantite come atomiche su qualsiasi +processore del sistema, quindi non sono necessari i *lock*. In questo caso è +più semplice rispetto all'uso degli spinlock, benché l'uso degli spinlock +sia più elegante per casi non banali. Le funzioni :c:func:`atomic_inc()` e +:c:func:`atomic_dec_and_test()` vengono usate al posto dei tipici operatori di +incremento e decremento, e i *lock* non sono più necessari per proteggere il +contatore stesso. + +:: + + --- cache.c.refcnt 2003-12-09 15:00:35.000000000 +1100 + +++ cache.c.refcnt-atomic 2003-12-11 15:49:42.000000000 +1100 + @@ -7,7 +7,7 @@ + struct object + { + struct list_head list; + - unsigned int refcnt; + + atomic_t refcnt; + int id; + char name[32]; + int popularity; + @@ -18,33 +18,15 @@ + static unsigned int cache_num = 0; + #define MAX_CACHE_SIZE 10 + + -static void __object_put(struct object *obj) + -{ + - if (--obj->refcnt == 0) + - kfree(obj); + -} + - + -static void __object_get(struct object *obj) + -{ + - obj->refcnt++; + -} + - + void object_put(struct object *obj) + { + - unsigned long flags; + - + - spin_lock_irqsave(&cache_lock, flags); + - __object_put(obj); + - spin_unlock_irqrestore(&cache_lock, flags); + + if (atomic_dec_and_test(&obj->refcnt)) + + kfree(obj); + } + + void object_get(struct object *obj) + { + - unsigned long flags; + - + - spin_lock_irqsave(&cache_lock, flags); + - __object_get(obj); + - spin_unlock_irqrestore(&cache_lock, flags); + + atomic_inc(&obj->refcnt); + } + + /* Must be holding cache_lock */ + @@ -65,7 +47,7 @@ + { + BUG_ON(!obj); + list_del(&obj->list); + - __object_put(obj); + + object_put(obj); + cache_num--; + } + + @@ -94,7 +76,7 @@ + strlcpy(obj->name, name, sizeof(obj->name)); + obj->id = id; + obj->popularity = 0; + - obj->refcnt = 1; /* The cache holds a reference */ + + atomic_set(&obj->refcnt, 1); /* The cache holds a reference */ + + spin_lock_irqsave(&cache_lock, flags); + __cache_add(obj); + @@ -119,7 +101,7 @@ + spin_lock_irqsave(&cache_lock, flags); + obj = __cache_find(id); + if (obj) + - __object_get(obj); + + object_get(obj); + spin_unlock_irqrestore(&cache_lock, flags); + return obj; + } + +Proteggere l'oggetto stesso +--------------------------- + +In questo esempio, assumiamo che gli oggetti (ad eccezione del contatore +di riferimenti) non cambino mai dopo la loro creazione. Se vogliamo permettere +al nome di cambiare abbiamo tre possibilità: + +- Si può togliere static da ``cache_lock`` e dire agli utenti che devono + trattenere il *lock* prima di modificare il nome di un oggetto. + +- Si può fornire una funzione :c:func:`cache_obj_rename()` che prende il + *lock* e cambia il nome per conto del chiamante; si dirà poi agli utenti + di usare questa funzione. + +- Si può decidere che ``cache_lock`` protegge solo la memoria stessa, ed + un altro *lock* è necessario per la protezione del nome. + +Teoricamente, possiamo avere un *lock* per ogni campo e per ogni oggetto. +In pratica, le varianti più comuni sono: + +- un *lock* che protegge l'infrastruttura (la lista ``cache`` di questo + esempio) e gli oggetti. Questo è quello che abbiamo fatto finora. + +- un *lock* che protegge l'infrastruttura (inclusi i puntatori alla lista + negli oggetti), e un *lock* nell'oggetto per proteggere il resto + dell'oggetto stesso. + +- *lock* multipli per proteggere l'infrastruttura (per esempio un *lock* + per ogni lista), possibilmente con un *lock* per oggetto. + +Qui di seguito un'implementazione con "un lock per oggetto": + +:: + + --- cache.c.refcnt-atomic 2003-12-11 15:50:54.000000000 +1100 + +++ cache.c.perobjectlock 2003-12-11 17:15:03.000000000 +1100 + @@ -6,11 +6,17 @@ + + struct object + { + + /* These two protected by cache_lock. */ + struct list_head list; + + int popularity; + + + atomic_t refcnt; + + + + /* Doesn't change once created. */ + int id; + + + + spinlock_t lock; /* Protects the name */ + char name[32]; + - int popularity; + }; + + static DEFINE_SPINLOCK(cache_lock); + @@ -77,6 +84,7 @@ + obj->id = id; + obj->popularity = 0; + atomic_set(&obj->refcnt, 1); /* The cache holds a reference */ + + spin_lock_init(&obj->lock); + + spin_lock_irqsave(&cache_lock, flags); + __cache_add(obj); + +Da notare che ho deciso che il contatore di popolarità dovesse essere +protetto da ``cache_lock`` piuttosto che dal *lock* dell'oggetto; questo +perché è logicamente parte dell'infrastruttura (come +:c:type:`struct list_head <list_head>` nell'oggetto). In questo modo, +in :c:func:`__cache_add()`, non ho bisogno di trattenere il *lock* di ogni +oggetto mentre si cerca il meno popolare. + +Ho anche deciso che il campo id è immutabile, quindi non ho bisogno di +trattenere il lock dell'oggetto quando si usa :c:func:`__cache_find()` +per leggere questo campo; il *lock* dell'oggetto è usato solo dal chiamante +che vuole leggere o scrivere il campo name. + +Inoltre, da notare che ho aggiunto un commento che descrive i dati che sono +protetti dal *lock*. Questo è estremamente importante in quanto descrive il +comportamento del codice, che altrimenti sarebbe di difficile comprensione +leggendo solamente il codice. E come dice Alan Cox: “Lock data, not code”. + +Problemi comuni +=============== + +.. _`it_deadlock`: + +Stallo: semplice ed avanzato +---------------------------- + +Esiste un tipo di baco dove un pezzo di codice tenta di trattenere uno +spinlock due volte: questo rimarrà in attesa attiva per sempre aspettando che +il *lock* venga rilasciato (in Linux spinlocks, rwlocks e mutex non sono +ricorsivi). +Questo è facile da diagnosticare: non è uno di quei problemi che ti tengono +sveglio 5 notti a parlare da solo. + +Un caso un pochino più complesso; immaginate d'avere una spazio condiviso +fra un softirq ed il contesto utente. Se usate :c:func:`spin_lock()` per +proteggerlo, il contesto utente potrebbe essere interrotto da un softirq +mentre trattiene il lock, da qui il softirq rimarrà in attesa attiva provando +ad acquisire il *lock* già trattenuto nel contesto utente. + +Questi casi sono chiamati stalli (*deadlock*), e come mostrato qui sopra, +può succedere anche con un solo processore (Ma non sui sistemi +monoprocessore perché gli spinlock spariscano quando il kernel è compilato +con ``CONFIG_SMP``\ =n. Nonostante ciò, nel secondo caso avrete comunque +una corruzione dei dati). + +Questi casi sono facili da diagnosticare; sui sistemi multi-processore +il supervisione (*watchdog*) o l'opzione di compilazione ``DEBUG_SPINLOCK`` +(``include/linux/spinlock.h``) permettono di scovare immediatamente quando +succedono. + +Esiste un caso più complesso che è conosciuto come l'abbraccio della morte; +questo coinvolge due o più *lock*. Diciamo che avete un vettore di hash in cui +ogni elemento è uno spinlock a cui è associata una lista di elementi con lo +stesso hash. In un gestore di interruzioni software, dovete modificare un +oggetto e spostarlo su un altro hash; quindi dovrete trattenete lo spinlock +del vecchio hash e di quello nuovo, quindi rimuovere l'oggetto dal vecchio ed +inserirlo nel nuovo. + +Qui abbiamo due problemi. Primo, se il vostro codice prova a spostare un +oggetto all'interno della stessa lista, otterrete uno stallo visto che +tenterà di trattenere lo stesso *lock* due volte. Secondo, se la stessa +interruzione software su un altro processore sta tentando di spostare +un altro oggetto nella direzione opposta, potrebbe accadere quanto segue: + ++---------------------------------+---------------------------------+ +| CPU 1 | CPU 2 | ++=================================+=================================+ +| Trattiene *lock* A -> OK | Trattiene *lock* B -> OK | ++---------------------------------+---------------------------------+ +| Trattiene *lock* B -> attesa | Trattiene *lock* A -> attesa | ++---------------------------------+---------------------------------+ + +Table: Conseguenze + +Entrambe i processori rimarranno in attesa attiva sul *lock* per sempre, +aspettando che l'altro lo rilasci. Sembra e puzza come un blocco totale. + +Prevenire gli stalli +-------------------- + +I libri di testo vi diranno che se trattenete i *lock* sempre nello stesso +ordine non avrete mai un simile stallo. La pratica vi dirà che questo +approccio non funziona all'ingrandirsi del sistema: quando creo un nuovo +*lock* non ne capisco abbastanza del kernel per dire in quale dei 5000 *lock* +si incastrerà. + +I *lock* migliori sono quelli incapsulati: non vengono esposti nei file di +intestazione, e non vengono mai trattenuti fuori dallo stesso file. Potete +rileggere questo codice e vedere che non ci sarà mai uno stallo perché +non tenterà mai di trattenere un altro *lock* quando lo ha già. +Le persone che usano il vostro codice non devono nemmeno sapere che voi +state usando dei *lock*. + +Un classico problema deriva dall'uso di *callback* e di *hook*: se li +chiamate mentre trattenete un *lock*, rischiate uno stallo o un abbraccio +della morte (chi lo sa cosa farà una *callback*?). + +Ossessiva prevenzione degli stalli +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Gli stalli sono un problema, ma non così terribile come la corruzione dei dati. +Un pezzo di codice trattiene un *lock* di lettura, cerca in una lista, +fallisce nel trovare quello che vuole, quindi rilascia il *lock* di lettura, +trattiene un *lock* di scrittura ed inserisce un oggetto; questo genere di +codice presenta una corsa critica. + +Se non riuscite a capire il perché, per favore state alla larga dal mio +codice. + +corsa fra temporizzatori: un passatempo del kernel +-------------------------------------------------- + +I temporizzatori potrebbero avere dei problemi con le corse critiche. +Considerate una collezione di oggetti (liste, hash, eccetera) dove ogni oggetto +ha un temporizzatore che sta per distruggerlo. + +Se volete eliminare l'intera collezione (diciamo quando rimuovete un modulo), +potreste fare come segue:: + + /* THIS CODE BAD BAD BAD BAD: IF IT WAS ANY WORSE IT WOULD USE + HUNGARIAN NOTATION */ + spin_lock_bh(&list_lock); + + while (list) { + struct foo *next = list->next; + del_timer(&list->timer); + kfree(list); + list = next; + } + + spin_unlock_bh(&list_lock); + +Primo o poi, questo esploderà su un sistema multiprocessore perché un +temporizzatore potrebbe essere già partiro prima di :c:func:`spin_lock_bh()`, +e prenderà il *lock* solo dopo :c:func:`spin_unlock_bh()`, e cercherà +di eliminare il suo oggetto (che però è già stato eliminato). + +Questo può essere evitato controllando il valore di ritorno di +:c:func:`del_timer()`: se ritorna 1, il temporizzatore è stato già +rimosso. Se 0, significa (in questo caso) che il temporizzatore è in +esecuzione, quindi possiamo fare come segue:: + + retry: + spin_lock_bh(&list_lock); + + while (list) { + struct foo *next = list->next; + if (!del_timer(&list->timer)) { + /* Give timer a chance to delete this */ + spin_unlock_bh(&list_lock); + goto retry; + } + kfree(list); + list = next; + } + + spin_unlock_bh(&list_lock); + +Un altro problema è l'eliminazione dei temporizzatori che si riavviano +da soli (chiamando :c:func:`add_timer()` alla fine della loro esecuzione). +Dato che questo è un problema abbastanza comune con una propensione +alle corse critiche, dovreste usare :c:func:`del_timer_sync()` +(``include/linux/timer.h``) per gestire questo caso. Questa ritorna il +numero di volte che il temporizzatore è stato interrotto prima che +fosse in grado di fermarlo senza che si riavviasse. + +Velocità della sincronizzazione +=============================== + +Ci sono tre cose importanti da tenere in considerazione quando si valuta +la velocità d'esecuzione di un pezzo di codice che necessita di +sincronizzazione. La prima è la concorrenza: quante cose rimangono in attesa +mentre qualcuno trattiene un *lock*. La seconda è il tempo necessario per +acquisire (senza contese) e rilasciare un *lock*. La terza è di usare meno +*lock* o di più furbi. Immagino che i *lock* vengano usati regolarmente, +altrimenti, non sareste interessati all'efficienza. + +La concorrenza dipende da quanto a lungo un *lock* è trattenuto: dovreste +trattenere un *lock* solo il tempo minimo necessario ma non un istante in più. +Nella memoria dell'esempio precedente, creiamo gli oggetti senza trattenere +il *lock*, poi acquisiamo il *lock* quando siamo pronti per inserirlo nella +lista. + +Il tempo di acquisizione di un *lock* dipende da quanto danno fa +l'operazione sulla *pipeline* (ovvero stalli della *pipeline*) e quant'è +probabile che il processore corrente sia stato anche l'ultimo ad acquisire +il *lock* (in pratica, il *lock* è nella memoria cache del processore +corrente?): su sistemi multi-processore questa probabilità precipita +rapidamente. Consideriamo un processore Intel Pentium III a 700Mhz: questo +esegue un'istruzione in 0.7ns, un incremento atomico richiede 58ns, acquisire +un *lock* che è nella memoria cache del processore richiede 160ns, e un +trasferimento dalla memoria cache di un altro processore richiede altri +170/360ns (Leggetevi l'articolo di Paul McKenney's `Linux Journal RCU +article <http://www.linuxjournal.com/article.php?sid=6993>`__). + +Questi due obiettivi sono in conflitto: trattenere un *lock* per il minor +tempo possibile potrebbe richiedere la divisione in più *lock* per diverse +parti (come nel nostro ultimo esempio con un *lock* per ogni oggetto), +ma questo aumenta il numero di acquisizioni di *lock*, ed il risultato +spesso è che tutto è più lento che con un singolo *lock*. Questo è un altro +argomento in favore della semplicità quando si parla di sincronizzazione. + +Il terzo punto è discusso di seguito: ci sono alcune tecniche per ridurre +il numero di sincronizzazioni che devono essere fatte. + +Read/Write Lock Variants +------------------------ + +Sia gli spinlock che i mutex hanno una variante per la lettura/scrittura +(read/write): ``rwlock_t`` e :c:type:`struct rw_semaphore <rw_semaphore>`. +Queste dividono gli utenti in due categorie: i lettori e gli scrittori. +Se state solo leggendo i dati, potete acquisire il *lock* di lettura, ma +per scrivere avrete bisogno del *lock* di scrittura. Molti possono trattenere +il *lock* di lettura, ma solo uno scrittore alla volta può trattenere +quello di scrittura. + +Se il vostro codice si divide chiaramente in codice per lettori e codice +per scrittori (come nel nostro esempio), e il *lock* dei lettori viene +trattenuto per molto tempo, allora l'uso di questo tipo di *lock* può aiutare. +Questi sono leggermente più lenti rispetto alla loro versione normale, quindi +nella pratica l'uso di ``rwlock_t`` non ne vale la pena. + +Evitare i *lock*: Read Copy Update +-------------------------------------------- + +Esiste un metodo di sincronizzazione per letture e scritture detto +Read Copy Update. Con l'uso della tecnica RCU, i lettori possono scordarsi +completamente di trattenere i *lock*; dato che nel nostro esempio ci +aspettiamo d'avere più lettore che scrittori (altrimenti questa memoria +sarebbe uno spreco) possiamo dire che questo meccanismo permette +un'ottimizzazione. + +Come facciamo a sbarazzarci dei *lock* di lettura? Sbarazzarsi dei *lock* di +lettura significa che uno scrittore potrebbe cambiare la lista sotto al naso +dei lettori. Questo è abbastanza semplice: possiamo leggere una lista +concatenata se lo scrittore aggiunge elementi alla fine e con certe +precauzioni. Per esempio, aggiungendo ``new`` ad una lista concatenata +chiamata ``list``:: + + new->next = list->next; + wmb(); + list->next = new; + +La funzione :c:func:`wmb()` è una barriera di sincronizzazione delle +scritture. Questa garantisce che la prima operazione (impostare l'elemento +``next`` del nuovo elemento) venga completata e vista da tutti i processori +prima che venga eseguita la seconda operazione (che sarebbe quella di mettere +il nuovo elemento nella lista). Questo è importante perché i moderni +compilatori ed i moderni processori possono, entrambe, riordinare le istruzioni +se non vengono istruiti altrimenti: vogliamo che i lettori non vedano +completamente il nuovo elemento; oppure che lo vedano correttamente e quindi +il puntatore ``next`` deve puntare al resto della lista. + +Fortunatamente, c'è una funzione che fa questa operazione sulle liste +:c:type:`struct list_head <list_head>`: :c:func:`list_add_rcu()` +(``include/linux/list.h``). + +Rimuovere un elemento dalla lista è anche più facile: sostituiamo il puntatore +al vecchio elemento con quello del suo successore, e i lettori vedranno +l'elemento o lo salteranno. + +:: + + list->next = old->next; + +La funzione :c:func:`list_del_rcu()` (``include/linux/list.h``) fa esattamente +questo (la versione normale corrompe il vecchio oggetto, e non vogliamo che +accada). + +Anche i lettori devono stare attenti: alcuni processori potrebbero leggere +attraverso il puntatore ``next`` il contenuto dell'elemento successivo +troppo presto, ma non accorgersi che il contenuto caricato è sbagliato quando +il puntatore ``next`` viene modificato alla loro spalle. Ancora una volta +c'è una funzione che viene in vostro aiuto :c:func:`list_for_each_entry_rcu()` +(``include/linux/list.h``). Ovviamente, gli scrittori possono usare +:c:func:`list_for_each_entry()` dato che non ci possono essere due scrittori +in contemporanea. + +Il nostro ultimo dilemma è il seguente: quando possiamo realmente distruggere +l'elemento rimosso? Ricordate, un lettore potrebbe aver avuto accesso a questo +elemento proprio ora: se eliminiamo questo elemento ed il puntatore ``next`` +cambia, il lettore salterà direttamente nella spazzatura e scoppierà. Dobbiamo +aspettare finché tutti i lettori che stanno attraversando la lista abbiano +finito. Utilizziamo :c:func:`call_rcu()` per registrare una funzione di +richiamo che distrugga l'oggetto quando tutti i lettori correnti hanno +terminato. In alternative, potrebbe essere usata la funzione +:c:func:`synchronize_rcu()` che blocca l'esecuzione finché tutti i lettori +non terminano di ispezionare la lista. + +Ma come fa l'RCU a sapere quando i lettori sono finiti? Il meccanismo è +il seguente: innanzi tutto i lettori accedono alla lista solo fra la coppia +:c:func:`rcu_read_lock()`/:c:func:`rcu_read_unlock()` che disabilita la +prelazione così che i lettori non vengano sospesi mentre stanno leggendo +la lista. + +Poi, l'RCU aspetta finché tutti i processori non abbiano dormito almeno +una volta; a questo punto, dato che i lettori non possono dormire, possiamo +dedurre che un qualsiasi lettore che abbia consultato la lista durante la +rimozione abbia già terminato, quindi la *callback* viene eseguita. Il vero +codice RCU è un po' più ottimizzato di così, ma questa è l'idea di fondo. + +:: + + --- cache.c.perobjectlock 2003-12-11 17:15:03.000000000 +1100 + +++ cache.c.rcupdate 2003-12-11 17:55:14.000000000 +1100 + @@ -1,15 +1,18 @@ + #include <linux/list.h> + #include <linux/slab.h> + #include <linux/string.h> + +#include <linux/rcupdate.h> + #include <linux/mutex.h> + #include <asm/errno.h> + + struct object + { + - /* These two protected by cache_lock. */ + + /* This is protected by RCU */ + struct list_head list; + int popularity; + + + struct rcu_head rcu; + + + atomic_t refcnt; + + /* Doesn't change once created. */ + @@ -40,7 +43,7 @@ + { + struct object *i; + + - list_for_each_entry(i, &cache, list) { + + list_for_each_entry_rcu(i, &cache, list) { + if (i->id == id) { + i->popularity++; + return i; + @@ -49,19 +52,25 @@ + return NULL; + } + + +/* Final discard done once we know no readers are looking. */ + +static void cache_delete_rcu(void *arg) + +{ + + object_put(arg); + +} + + + /* Must be holding cache_lock */ + static void __cache_delete(struct object *obj) + { + BUG_ON(!obj); + - list_del(&obj->list); + - object_put(obj); + + list_del_rcu(&obj->list); + cache_num--; + + call_rcu(&obj->rcu, cache_delete_rcu); + } + + /* Must be holding cache_lock */ + static void __cache_add(struct object *obj) + { + - list_add(&obj->list, &cache); + + list_add_rcu(&obj->list, &cache); + if (++cache_num > MAX_CACHE_SIZE) { + struct object *i, *outcast = NULL; + list_for_each_entry(i, &cache, list) { + @@ -104,12 +114,11 @@ + struct object *cache_find(int id) + { + struct object *obj; + - unsigned long flags; + + - spin_lock_irqsave(&cache_lock, flags); + + rcu_read_lock(); + obj = __cache_find(id); + if (obj) + object_get(obj); + - spin_unlock_irqrestore(&cache_lock, flags); + + rcu_read_unlock(); + return obj; + } + +Da notare che i lettori modificano il campo popularity nella funzione +:c:func:`__cache_find()`, e ora non trattiene alcun *lock*. Una soluzione +potrebbe essere quella di rendere la variabile ``atomic_t``, ma per l'uso +che ne abbiamo fatto qui, non ci interessano queste corse critiche perché un +risultato approssimativo è comunque accettabile, quindi non l'ho cambiato. + +Il risultato è che la funzione :c:func:`cache_find()` non ha bisogno di alcuna +sincronizzazione con le altre funzioni, quindi è veloce su un sistema +multi-processore tanto quanto lo sarebbe su un sistema mono-processore. + +Esiste un'ulteriore ottimizzazione possibile: vi ricordate il codice originale +della nostra memoria dove non c'erano contatori di riferimenti e il chiamante +semplicemente tratteneva il *lock* prima di accedere ad un oggetto? Questo è +ancora possibile: se trattenete un *lock* nessuno potrà cancellare l'oggetto, +quindi non avete bisogno di incrementare e decrementare il contatore di +riferimenti. + +Ora, dato che il '*lock* di lettura' di un RCU non fa altro che disabilitare +la prelazione, un chiamante che ha sempre la prelazione disabilitata fra le +chiamate :c:func:`cache_find()` e :c:func:`object_put()` non necessita +di incrementare e decrementare il contatore di riferimenti. Potremmo +esporre la funzione :c:func:`__cache_find()` dichiarandola non-static, +e quel chiamante potrebbe usare direttamente questa funzione. + +Il beneficio qui sta nel fatto che il contatore di riferimenti no +viene scritto: l'oggetto non viene alterato in alcun modo e quindi diventa +molto più veloce su sistemi molti-processore grazie alla loro memoria cache. + +.. _`it_per-cpu`: + +Dati per processore +------------------- + +Un'altra tecnica comunemente usata per evitare la sincronizzazione è quella +di duplicare le informazioni per ogni processore. Per esempio, se volete +avere un contatore di qualcosa, potreste utilizzare uno spinlock ed un +singolo contatore. Facile e pulito. + +Se questo dovesse essere troppo lento (solitamente non lo è, ma se avete +dimostrato che lo è devvero), potreste usare un contatore per ogni processore +e quindi non sarebbe più necessaria la mutua esclusione. Vedere +:c:func:`DEFINE_PER_CPU()`, :c:func:`get_cpu_var()` e :c:func:`put_cpu_var()` +(``include/linux/percpu.h``). + +Il tipo di dato ``local_t``, la funzione :c:func:`cpu_local_inc()` e tutte +le altre funzioni associate, sono di particolare utilità per semplici contatori +per-processore; su alcune architetture sono anche più efficienti +(``include/asm/local.h``). + +Da notare che non esiste un modo facile ed affidabile per ottenere il valore +di un simile contatore senza introdurre altri *lock*. In alcuni casi questo +non è un problema. + +Dati che sono usati prevalentemente dai gestori d'interruzioni +-------------------------------------------------------------- + +Se i dati vengono utilizzati sempre dallo stesso gestore d'interruzioni, +allora i *lock* non vi servono per niente: il kernel già vi garantisce che +il gestore d'interruzione non verrà eseguito in contemporanea su diversi +processori. + +Manfred Spraul fa notare che potreste comunque comportarvi così anche +se i dati vengono occasionalmente utilizzati da un contesto utente o +da un'interruzione software. Il gestore d'interruzione non utilizza alcun +*lock*, e tutti gli altri accessi verranno fatti così:: + + spin_lock(&lock); + disable_irq(irq); + ... + enable_irq(irq); + spin_unlock(&lock); + +La funzione :c:func:`disable_irq()` impedisce al gestore d'interruzioni +d'essere eseguito (e aspetta che finisca nel caso fosse in esecuzione su +un altro processore). Lo spinlock, invece, previene accessi simultanei. +Naturalmente, questo è più lento della semplice chiamata +:c:func:`spin_lock_irq()`, quindi ha senso solo se questo genere di accesso +è estremamente raro. + +.. _`it_sleeping-things`: + +Quali funzioni possono essere chiamate in modo sicuro dalle interruzioni? +========================================================================= + +Molte funzioni del kernel dormono (in sostanza, chiamano ``schedule()``) +direttamente od indirettamente: non potete chiamarle se trattenere uno +spinlock o avete la prelazione disabilitata, mai. Questo significa che +dovete necessariamente essere nel contesto utente: chiamarle da un +contesto d'interruzione è illegale. + +Alcune funzioni che dormono +--------------------------- + +Le più comuni sono elencate qui di seguito, ma solitamente dovete leggere +il codice per scoprire se altre chiamate sono sicure. Se chiunque altro +le chiami dorme, allora dovreste poter dormire anche voi. In particolar +modo, le funzioni di registrazione e deregistrazione solitamente si +aspettano d'essere chiamante da un contesto utente e quindi che possono +dormire. + +- Accessi allo spazio utente: + + - :c:func:`copy_from_user()` + + - :c:func:`copy_to_user()` + + - :c:func:`get_user()` + + - :c:func:`put_user()` + +- :c:func:`kmalloc(GFP_KERNEL) <kmalloc>` + +- :c:func:`mutex_lock_interruptible()` and + :c:func:`mutex_lock()` + + C'è anche :c:func:`mutex_trylock()` che però non dorme. + Comunque, non deve essere usata in un contesto d'interruzione dato + che la sua implementazione non è sicura in quel contesto. + Anche :c:func:`mutex_unlock()` non dorme mai. Non può comunque essere + usata in un contesto d'interruzione perché un mutex deve essere rilasciato + dallo stesso processo che l'ha acquisito. + +Alcune funzioni che non dormono +------------------------------- + +Alcune funzioni possono essere chiamate tranquillamente da qualsiasi +contesto, o trattenendo un qualsiasi *lock*. + +- :c:func:`printk()` + +- :c:func:`kfree()` + +- :c:func:`add_timer()` e :c:func:`del_timer()` + +Riferimento per l'API dei Mutex +=============================== + +.. kernel-doc:: include/linux/mutex.h + :internal: + +.. kernel-doc:: kernel/locking/mutex.c + :export: + +Riferimento per l'API dei Futex +=============================== + +.. kernel-doc:: kernel/futex.c + :internal: + +Approfondimenti +=============== + +- ``Documentation/locking/spinlocks.txt``: la guida di Linus Torvalds agli + spinlock del kernel. + +- Unix Systems for Modern Architectures: Symmetric Multiprocessing and + Caching for Kernel Programmers. + + L'introduzione alla sincronizzazione a livello di kernel di Curt Schimmel + è davvero ottima (non è scritta per Linux, ma approssimativamente si adatta + a tutte le situazioni). Il libro è costoso, ma vale ogni singolo spicciolo + per capire la sincronizzazione nei sistemi multi-processore. + [ISBN: 0201633388] + +Ringraziamenti +============== + +Grazie a Telsa Gwynne per aver formattato questa guida in DocBook, averla +pulita e aggiunto un po' di stile. + +Grazie a Martin Pool, Philipp Rumpf, Stephen Rothwell, Paul Mackerras, +Ruedi Aschwanden, Alan Cox, Manfred Spraul, Tim Waugh, Pete Zaitcev, +James Morris, Robert Love, Paul McKenney, John Ashby per aver revisionato, +corretto, maledetto e commentato. + +Grazie alla congrega per non aver avuto alcuna influenza su questo documento. + +Glossario +========= + +prelazione + Prima del kernel 2.5, o quando ``CONFIG_PREEMPT`` non è impostato, i processi + in contesto utente non si avvicendano nell'esecuzione (in pratica, il + processo userà il processore fino al proprio termine, a meno che non ci siano + delle interruzioni). Con l'aggiunta di ``CONFIG_PREEMPT`` nella versione + 2.5.4 questo è cambiato: quando si è in contesto utente, processi con una + priorità maggiore possono subentrare nell'esecuzione: gli spinlock furono + cambiati per disabilitare la prelazioni, anche su sistemi monoprocessore. + +bh + Bottom Half: per ragioni storiche, le funzioni che contengono '_bh' nel + loro nome ora si riferiscono a qualsiasi interruzione software; per esempio, + :c:func:`spin_lock_bh()` blocca qualsiasi interuzione software sul processore + corrente. I *Bottom Halves* sono deprecati, e probabilmente verranno + sostituiti dai tasklet. In un dato momento potrà esserci solo un + *bottom half* in esecuzione. + +contesto d'interruzione + Non è il contesto utente: qui si processano le interruzioni hardware e + software. La macro :c:func:`in_interrupt()` ritorna vero. + +contesto utente + Il kernel che esegue qualcosa per conto di un particolare processo (per + esempio una chiamata di sistema) o di un thread del kernel. Potete + identificare il processo con la macro ``current``. Da non confondere + con lo spazio utente. Può essere interrotto sia da interruzioni software + che hardware. + +interruzione hardware + Richiesta di interruzione hardware. :c:func:`in_irq()` ritorna vero in un + gestore d'interruzioni hardware. + +interruzione software / softirq + Gestore di interruzioni software: :c:func:`in_irq()` ritorna falso; + :c:func:`in_softirq()` ritorna vero. I tasklet e le softirq sono entrambi + considerati 'interruzioni software'. + + In soldoni, un softirq è uno delle 32 interruzioni software che possono + essere eseguite su più processori in contemporanea. A volte si usa per + riferirsi anche ai tasklet (in pratica tutte le interruzioni software). + +monoprocessore / UP + (Uni-Processor) un solo processore, ovvero non è SMP. (``CONFIG_SMP=n``). + +multi-processore / SMP + (Symmetric Multi-Processor) kernel compilati per sistemi multi-processore + (``CONFIG_SMP=y``). + +spazio utente + Un processo che esegue il proprio codice fuori dal kernel. + +tasklet + Un'interruzione software registrabile dinamicamente che ha la garanzia + d'essere eseguita solo su un processore alla volta. + +timer + Un'interruzione software registrabile dinamicamente che viene eseguita + (circa) in un determinato momento. Quando è in esecuzione è come un tasklet + (infatti, sono chiamati da ``TIMER_SOFTIRQ``). diff --git a/Documentation/translations/ja_JP/SubmitChecklist b/Documentation/translations/ja_JP/SubmitChecklist new file mode 100644 index 000000000..60c7c35ac --- /dev/null +++ b/Documentation/translations/ja_JP/SubmitChecklist @@ -0,0 +1,111 @@ +NOTE: +This is a version of Documentation/process/submit-checklist.rst into Japanese. +This document is maintained by Takenori Nagano <t-nagano@ah.jp.nec.com> +and the JF Project team <http://www.linux.or.jp/JF/>. +If you find any difference between this document and the original file +or a problem with the translation, +please contact the maintainer of this file or JF project. + +Please also note that the purpose of this file is to be easier to read +for non English (read: Japanese) speakers and is not intended as a +fork. So if you have any comments or updates of this file, please try +to update the original English file first. + +Last Updated: 2008/07/14 +================================== +これは、 +linux-2.6.26/Documentation/process/submit-checklist.rst の和訳です。 + +翻訳団体： JF プロジェクト < http://www.linux.or.jp/JF/ > +翻訳日： 2008/07/14 +翻訳者： Takenori Nagano <t-nagano at ah dot jp dot nec dot com> +校正者： Masanori Kobayashi さん <zap03216 at nifty dot ne dot jp> +================================== + + +Linux カーネルパッチ投稿者向けチェックリスト +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +本書では、パッチをより素早く取り込んでもらいたい開発者が実践すべき基本的な事柄 +をいくつか紹介します。ここにある全ての事柄は、Documentation/process/submitting-patches.rst +などのLinuxカーネルパッチ投稿に際しての心得を補足するものです。 + + 1: 妥当なCONFIGオプションや変更されたCONFIGオプション、つまり =y, =m, =n + 全てで正しくビルドできることを確認してください。その際、gcc及びリンカが + warningやerrorを出していないことも確認してください。 + + 2: allnoconfig, allmodconfig オプションを用いて正しくビルドできることを + 確認してください。 + + 3: 手許のクロスコンパイルツールやOSDLのPLMのようなものを用いて、複数の + アーキテクチャにおいても正しくビルドできることを確認してください。 + + 4: 64bit長の'unsigned long'を使用しているppc64は、クロスコンパイルでの + チェックに適当なアーキテクチャです。 + + 5: カーネルコーディングスタイルに準拠しているかどうか確認してください(!) + + 6: CONFIGオプションの追加・変更をした場合には、CONFIGメニューが壊れていない + ことを確認してください。 + + 7: 新しくKconfigのオプションを追加する際には、必ずそのhelpも記述してください。 + + 8: 適切なKconfigの依存関係を考えながら慎重にチェックしてください。 + ただし、この作業はマシンを使ったテストできちんと行うのがとても困難です。 + うまくやるには、自分の頭で考えることです。 + + 9: sparseを利用してちゃんとしたコードチェックをしてください。 + +10: 'make checkstack' と 'make namespacecheck' を利用し、問題が発見されたら + 修正してください。'make checkstack' は明示的に問題を示しませんが、どれか + １つの関数が512バイトより大きいスタックを使っていれば、修正すべき候補と + なります。 + +11: グローバルなkernel API を説明する kernel-doc をソースの中に含めてください。 + ( staticな関数においては必須ではありませんが、含めてもらっても結構です ) + そして、'make htmldocs' もしくは 'make mandocs' を利用して追記した + ドキュメントのチェックを行い、問題が見つかった場合には修正を行ってください。 + +12: CONFIG_PREEMPT, CONFIG_DEBUG_PREEMPT, CONFIG_DEBUG_SLAB, + CONFIG_DEBUG_PAGEALLOC, CONFIG_DEBUG_MUTEXES, CONFIG_DEBUG_SPINLOCK, + CONFIG_DEBUG_ATOMIC_SLEEP これら全てを同時に有効にして動作確認を + 行ってください。 + +13: CONFIG_SMP, CONFIG_PREEMPT を有効にした場合と無効にした場合の両方で + ビルドした上、動作確認を行ってください。 + +14: もしパッチがディスクのI/O性能などに影響を与えるようであれば、 + 'CONFIG_LBDAF'オプションを有効にした場合と無効にした場合の両方で + テストを実施してみてください。 + +15: lockdepの機能を全て有効にした上で、全てのコードパスを評価してください。 + +16: /proc に新しいエントリを追加した場合には、Documentation/ 配下に + 必ずドキュメントを追加してください。 + +17: 新しいブートパラメータを追加した場合には、 + 必ずDocumentation/admin-guide/kernel-parameters.rst に説明を追加してください。 + +18: 新しくmoduleにパラメータを追加した場合には、MODULE_PARM_DESC()を + 利用して必ずその説明を記述してください。 + +19: 新しいuserspaceインタフェースを作成した場合には、Documentation/ABI/ に + Documentation/ABI/README を参考にして必ずドキュメントを追加してください。 + +20: 'make headers_check'を実行して全く問題がないことを確認してください。 + +21: 少なくともslabアロケーションとpageアロケーションに失敗した場合の + 挙動について、fault-injectionを利用して確認してください。 + Documentation/fault-injection/ を参照してください。 + + 追加したコードがかなりの量であったならば、サブシステム特有の + fault-injectionを追加したほうが良いかもしれません。 + +22: 新たに追加したコードは、`gcc -W'でコンパイルしてください。 + このオプションは大量の不要なメッセージを出力しますが、 + "warning: comparison between signed and unsigned" のようなメッセージは、 + バグを見つけるのに役に立ちます。 + +23: 投稿したパッチが -mm パッチセットにマージされた後、全ての既存のパッチや + VM, VFS およびその他のサブシステムに関する様々な変更と、現時点でも共存 + できることを確認するテストを行ってください。 diff --git a/Documentation/translations/ja_JP/SubmittingPatches b/Documentation/translations/ja_JP/SubmittingPatches new file mode 100644 index 000000000..021396564 --- /dev/null +++ b/Documentation/translations/ja_JP/SubmittingPatches @@ -0,0 +1,719 @@ +NOTE: +This is a version of Documentation/process/submitting-patches.rst into Japanese. +This document is maintained by Keiichi KII <k-keiichi@bx.jp.nec.com> +and the JF Project team <http://www.linux.or.jp/JF/>. +If you find any difference between this document and the original file +or a problem with the translation, +please contact the maintainer of this file or JF project. + +Please also note that the purpose of this file is to be easier to read +for non English (read: Japanese) speakers and is not intended as a +fork. So if you have any comments or updates of this file, please try +to update the original English file first. + +Last Updated: 2011/06/09 + +================================== +これは、 +linux-2.6.39/Documentation/process/submitting-patches.rst の和訳 +です。 +翻訳団体： JF プロジェクト < http://www.linux.or.jp/JF/ > +翻訳日： 2011/06/09 +翻訳者： Keiichi Kii <k-keiichi at bx dot jp dot nec dot com> +校正者： Masanari Kobayashi さん <zap03216 at nifty dot ne dot jp> + Matsukura さん <nbh--mats at nifty dot com> + Takeshi Hamasaki さん <hmatrjp at users dot sourceforge dot jp> +================================== + + Linux カーネルに変更を加えるための Howto + 又は + かの Linus Torvalds の取り扱い説明書 + +Linux カーネルに変更を加えたいと思っている個人又は会社にとって、パッ +チの投稿に関連した仕組みに慣れていなければ、その過程は時々みなさんを +おじけづかせることもあります。この文章はあなたの変更を大いに受け入れ +てもらえやすくする提案を集めたものです。 + +コードを投稿する前に、Documentation/process/submit-checklist.rst の項目リストに目 +を通してチェックしてください。もしあなたがドライバーを投稿しようとし +ているなら、Documentation/process/submitting-drivers.rst にも目を通してください。 + +-------------------------------------------- +セクション1 パッチの作り方と送り方 +-------------------------------------------- + +1) 「 diff -up 」 +------------ + +パッチの作成には「 diff -up 」又は「 diff -uprN 」を使ってください。 + +Linux カーネルに対する全ての変更は diff(1) コマンドによるパッチの形式で +生成してください。パッチを作成するときには、diff(1) コマンドに「 -u 」引 +数を指定して、unified 形式のパッチを作成することを確認してください。また、 +変更がどの C 関数で行われたのかを表示する「 -p 」引数を使ってください。 +この引数は生成した差分をずっと読みやすくしてくれます。パッチは Linux +カーネルソースの中のサブディレクトリではなく Linux カーネルソースのルート +ディレクトリを基準にしないといけません。 + +1個のファイルについてのパッチを作成するためには、ほとんどの場合、 +以下の作業を行えば十分です。 + + SRCTREE= linux-2.6 + MYFILE= drivers/net/mydriver.c + + cd $SRCTREE + cp $MYFILE $MYFILE.orig + vi $MYFILE # make your change + cd .. + diff -up $SRCTREE/$MYFILE{.orig,} > /tmp/patch + +複数のファイルについてのパッチを作成するためには、素の( vanilla )、す +なわち変更を加えてない Linux カーネルを展開し、自分の Linux カーネル +ソースとの差分を生成しないといけません。例えば、 + + MYSRC= /devel/linux-2.6 + + tar xvfz linux-2.6.12.tar.gz + mv linux-2.6.12 linux-2.6.12-vanilla + diff -uprN -X linux-2.6.12-vanilla/Documentation/dontdiff \ + linux-2.6.12-vanilla $MYSRC > /tmp/patch + +dontdiff ファイルには Linux カーネルのビルドプロセスの過程で生成された +ファイルの一覧がのっています。そして、それらはパッチを生成する diff(1) +コマンドで無視されるべきです。dontdiff ファイルは 2.6.12 以後のバージョ +ンの Linux カーネルソースツリーに含まれています。それより前のバージョン +の Linux カーネルソースツリーに対する dontdiff ファイルは、 +<http://www.xenotime.net/linux/doc/dontdiff>から取得することができます。 + +投稿するパッチの中に関係のない余分なファイルが含まれていないことを確 +認してください。diff(1) コマンドで生成したパッチがあなたの意図したとお +りのものであることを確認してください。 + +もしあなたのパッチが多くの差分を生み出すのであれば、あなたはパッチ +を意味のあるひとまとまりごとに分けたいと思うかもしれません。 +これは他のカーネル開発者にとってレビューしやすくなるので、あなたの +パッチを受け入れてもらうためにはとても重要なことです。これを補助でき +る多くのスクリプトがあります。 + +Quilt: +http://savannah.nongnu.org/projects/quilt + +2) パッチに対する説明 + +パッチの中の変更点に対する技術的な詳細について説明してください。 + +説明はできる限り具体的に。もっとも悪い説明は「ドライバー X を更新」、 +「ドライバー X に対するバグフィックス」あるいは「このパッチはサブシス +テム X に対する更新を含んでいます。どうか取り入れてください。」などです。 + +パッチの説明を Linux カーネルのソースコードマネジメントシステム「 git 」の +コミットログとして簡単に引用できる形で書けば、メンテナから感謝されるでしょう。 +以下の #15 を見てください。 + +説明が長くなりだしたのであれば、おそらくそれはパッチを分ける必要がある +という兆候です。次の #3 を見てください。 + +パッチ(シリーズ)を(再)投稿する時、十分なパッチの説明とそのパッチが必要な理由を +パッチに含めてください。ただ「これはパッチ(シリーズ)のバージョン N」とだけ +書かないでください。そして、パッチをマージする人にパッチの説明を探させそれを +パッチに追記させるため、過去のバージョンのパッチやそのパッチの URL を参照する +手間をかけさせないでください。 +つまり、パッチシリーズとその説明は一緒にあるべきです。これはパッチをマージする +人、レビューする人、どちらのためにもなります。レビューする人の中には、おそらく +過去のバージョンのパッチを受け取ってもいない人がいます。 + +登録済みのバグエントリを修正するパッチであれば、そのバグエントリを示すバグ ID +や URL を明記してください。 + +3) パッチの分割 + +意味のあるひとまとまりごとに変更を個々のパッチファイルに分けてください。 + +例えば、もし1つのドライバーに対するバグフィックスとパフォーマンス強 +化の両方の変更を含んでいるのであれば、その変更を2つ以上のパッチに分 +けてください。もし変更箇所に API の更新と、その新しい API を使う新たな +ドライバーが含まれているなら、2つのパッチに分けてください。 + +一方で、もしあなたが多数のファイルに対して意味的に同じ1つの変更を加え +るのであれば、その変更を1つのパッチにまとめてください。言いかえると、 +意味的に同じ1つの変更は1つのパッチの中に含まれます。 + +あるパッチが変更を完結させるために他のパッチに依存していたとしても、 +それは問題ありません。パッチの説明の中で「このパッチはパッチ X に依存 +している」と簡単に注意書きをつけてください。 + +もしパッチをより小さなパッチの集合に凝縮することができないなら、まずは +15かそこらのパッチを送り、そのレビューと統合を待って下さい。 + +4) パッチのスタイルチェック + +あなたのパッチが基本的な( Linux カーネルの)コーディングスタイルに違反し +ていないかをチェックして下さい。その詳細を Documentation/process/coding-style.rst で +見つけることができます。コーディングスタイルの違反はレビューする人の +時間を無駄にするだけなので、恐らくあなたのパッチは読まれることすらなく +拒否されるでしょう。 + +あなたはパッチを投稿する前に最低限パッチスタイルチェッカー +( scripts/checkpatch.pl )を利用してパッチをチェックすべきです。 +もしパッチに違反がのこっているならば、それらの全てについてあなたは正当な +理由を示せるようにしておく必要があります。 + +5) 電子メールの宛先の選び方 + +MAINTAINERS ファイルとソースコードに目を通してください。そして、その変 +更がメンテナのいる特定のサブシステムに加えられるものであることが分か +れば、その人に電子メールを送ってください。 + +もし、メンテナが載っていなかったり、メンテナからの応答がないなら、 +LKML ( linux-kernel@vger.kernel.org )へパッチを送ってください。ほとんど +のカーネル開発者はこのメーリングリストに目を通しており、変更に対して +コメントを得ることができます。 + +15個より多くのパッチを同時に vger.kernel.org のメーリングリストへ送らな +いでください!!! + +Linus Torvalds は Linux カーネルに入る全ての変更に対する最終的な意思決定者 +です。電子メールアドレスは torvalds@linux-foundation.org になります。彼は +多くの電子メールを受け取っているため、できる限り彼に電子メールを送るのは +避けるべきです。 + +バグフィックスであったり、自明な変更であったり、話し合いをほとんど +必要としないパッチは Linus へ電子メールを送るか CC しなければなりません。 +話し合いを必要としたり、明確なアドバンテージがないパッチは、通常まず +は LKML へ送られるべきです。パッチが議論された後にだけ、そのパッチを +Linus へ送るべきです。 + +6) CC (カーボンコピー)先の選び方 + +特に理由がないなら、LKML にも CC してください。 + +Linus 以外のカーネル開発者は変更に気づく必要があり、その結果、彼らはそ +の変更に対してコメントをくれたり、コードに対してレビューや提案をくれ +るかもしれません。LKML とは Linux カーネル開発者にとって一番中心的なメー +リングリストです。USB やフレームバッファデバイスや VFS や SCSI サブシステ +ムなどの特定のサブシステムに関するメーリングリストもあります。あなた +の変更に、はっきりと関連のあるメーリングリストについて知りたければ +MAINTAINERS ファイルを参照してください。 + +VGER.KERNEL.ORG でホスティングされているメーリングリストの一覧が下記の +サイトに載っています。 +<http://vger.kernel.org/vger-lists.html> + +もし、変更がユーザランドのカーネルインタフェースに影響を与え +るのであれば、MAN-PAGES のメンテナ( MAINTAINERS ファイルに一覧 +があります)に man ページのパッチを送ってください。少なくとも +情報がマニュアルページの中に入ってくるように、変更が起きたという +通知を送ってください。 + +たとえ、メンテナが #5 で反応がなかったとしても、メンテナのコードに変更を +加えたときには、いつもメンテナに CC するのを忘れないようにしてください。 + +小さなパッチであれば、Trivial Patch Monkey(ちょっとしたパッチを集めている) +<trivial@kernel.org>に CC してもいいです。その現管理者については MAINTAINERS +ファイルを見てください。ちょっとしたパッチとは以下のルールのどれか1つを満たして +いなければなりません。 + ・ドキュメントのスペルミスの修正 + ・grep(1) コマンドによる検索を困難にしているスペルの修正 + ・コンパイル時の警告の修正(無駄な警告が散乱することは好ましくないた + めです) + ・コンパイル問題の修正(それらの修正が本当に正しい場合に限る) + ・実行時の問題の修正(それらの修正が本当に問題を修正している場合に限る) + ・廃止予定の関数やマクロを使用しているコードの除去(例 check_region ) + ・問い合わせ先やドキュメントの修正 + ・移植性のないコードから移植性のあるコードへの置き換え(小さい範囲で + あればアーキテクチャ特有のことでも他の人がコピーできます) + ・作者やメンテナによる修正(すなわち patch monkey の再転送モード) + +7) MIME やリンクや圧縮ファイルや添付ファイルではなくプレインテキストのみ + +Linus や他のカーネル開発者はあなたが投稿した変更を読んで、コメントでき +る必要があります。カーネル開発者にとって、あなたが書いたコードの特定の +部分にコメントをするために、標準的な電子メールクライアントで変更が引用 +できることは重要です。 + +上記の理由で、すべてのパッチは文中に含める形式の電子メールで投稿さ +れるべきです。警告：あなたがパッチをコピー&ペーストする際には、パッ +チを改悪するエディターの折り返し機能に注意してください。 + +パッチを圧縮の有無に関わらず MIME 形式で添付しないでください。多くのポ +ピュラーな電子メールクライアントは MIME 形式の添付ファイルをプレーンテ +キストとして送信するとは限らないでしょう。そうなると、電子メールクラ +イアントがコードに対するコメントを付けることをできなくします。また、 +MIME 形式の添付ファイルは Linus に手間を取らせることになり、その変更を +受け入れてもらう可能性が低くなってしまいます。 + +例外：お使いの電子メールクライアントがパッチをめちゃくちゃにするので +あれば、誰かが MIME 形式のパッチを再送するよう求めるかもしれません。 + +余計な変更を加えずにあなたのパッチを送信するための電子メールクライアントの設定 +のヒントについては Documentation/process/email-clients.rst を参照してください。 + +8) 電子メールのサイズ + +パッチを Linus へ送るときは常に #7 の手順に従ってください。 + +大きなパッチはメーリングリストやメンテナにとって不親切です。パッチが +未圧縮で 300KB を超えるようであるなら、インターネット上のアクセス可能な +サーバに保存し、保存場所を示す URL を伝えるほうが適切です。 + +9) カーネルバージョンの明記 + +パッチが対象とするカーネルのバージョンをパッチの概要か電子メールの +サブジェクトに付けることが重要です。 + +パッチが最新バージョンのカーネルに正しく適用できなければ、Linus は +そのパッチを採用しないでしょう。 + +10) がっかりせず再投稿 + +パッチを投稿した後は、辛抱強く待っていてください。Linus があなたのパッ +チを気に入って採用すれば、Linus がリリースする次のバージョンのカーネル +の中で姿を見せるでしょう。 + +しかし、パッチが次のバージョンのカーネルに入っていないなら、いくつもの +理由があるのでしょう。その原因を絞り込み、間違っているものを正し、更新 +したパッチを投稿するのはあなたの仕事です。 + +Linus があなたのパッチに対して何のコメントもなく不採用にすることは極め +て普通のことです。それは自然な姿です。もし、Linus があなたのパッチを受 +け取っていないのであれば、以下の理由が考えられます。 +* パッチが最新バージョンの Linux カーネルにきちんと適用できなかった +* パッチが LKML で十分に議論されていなかった +* スタイルの問題(セクション2を参照) +* 電子メールフォーマットの問題(このセクションを参照) +* パッチに対する技術的な問題 +* Linus はたくさんの電子メールを受け取っているので、どさくさに紛れて見 + 失った +* 不愉快にさせている + +判断できない場合は、LKML にコメントを頼んでください。 + +11) サブジェクトに「 PATCH 」 + +Linus や LKML への大量の電子メールのために、サブジェクトのプレフィックスに +「 [PATCH] 」を付けることが慣習となっています。これによって Linus や他の +カーネル開発者がパッチであるのか、又は、他の議論に関する電子メールであるの +かをより簡単に識別できます。 + +12) パッチへの署名 + +誰が何をしたのかを追いかけやすくするために (特に、パッチが何人かの +メンテナを経て最終的に Linux カーネルに取り込まれる場合のために)、電子 +メールでやり取りされるパッチに対して「 sign-off 」という手続きを導入し +ました。 + +「 sign-off 」とは、パッチがあなたの書いたものであるか、あるいは、 +あなたがそのパッチをオープンソースとして提供する権利を保持している、 +という証明をパッチの説明の末尾に一行記載するというものです。 +ルールはとても単純です。以下の項目を確認して下さい。 + + 原作者の証明書( DCO ) 1.1 + + このプロジェクトに寄与するものとして、以下のことを証明する。 + + (a) 本寄与は私が全体又は一部作成したものであり、私がそのファイ + ル中に明示されたオープンソースライセンスの下で公開する権利 + を持っている。もしくは、 + + (b) 本寄与は、私が知る限り、適切なオープンソースライセンスでカバ + ーされている既存の作品を元にしている。同時に、私はそのライセ + ンスの下で、私が全体又は一部作成した修正物を、ファイル中で示 + される同一のオープンソースライセンスで(異なるライセンスの下で + 投稿することが許可されている場合を除いて)投稿する権利を持って + いる。もしくは、 + + (c) 本寄与は(a)、(b)、(c)を証明する第3者から私へ直接提供された + ものであり、私はそれに変更を加えていない。 + + (d) 私はこのプロジェクトと本寄与が公のものであることに理解及び同意す + る。同時に、関与した記録(投稿の際の全ての個人情報と sign-off を + 含む)が無期限に保全されることと、当該プロジェクト又は関連する + オープンソースライセンスに沿った形で再配布されることに理解及び + 同意する。 + +もしこれに同意できるなら、以下のような1行を追加してください。 + + Signed-off-by: Random J Developer <random@developer.example.org> + +実名を使ってください。(残念ですが、偽名や匿名による寄与はできません。) + +人によっては sign-off の近くに追加のタグを付加しています。それらは今のところ +無視されますが、あなたはそのタグを社内の手続きに利用したり、sign-off に特別 +な情報を示したりすることができます。 + +あなたがサブシステムまたはブランチのメンテナであれば、受け取ったパッチを自身の +ツリーにマージするために、わずかに変更が必要となる場合があります。なぜなら +あなたのツリーの中のコードと投稿者のツリーの中のコードは同一ではないためです。 +もし、あなたが厳密に上記ルール(c)にこだわるのであれば、投稿者に再度差分を +とるよう依頼すべきです。しかし、これは時間とエネルギーを非生産的に浪費する +ことになります。ルール(b)はあなたにコードを修正する権利を与えてくれます。 +しかし、投稿者のコードを修正し、その修正によるバグを投稿者に押し付けてしまう +ことはとても失礼なことです。この問題を解決するために、末尾の投稿者の +Signed-off-by とあなたがその末尾に追加する Signed-off-by の間に、修正を +加えたことを示す1行を追加することが推奨されています。 +(その1行の書き方に)決まりはありませんが、大括弧の中に電子メールアドレスや氏名 +と修正内容を記載するやり方は目につきやすく、最終段階での変更の責任があなたに +あることを明確にするのに十分な方法のようです。例えば、 + + Signed-off-by: Random J Developer <random@developer.example.org> + [lucky@maintainer.example.org: struct foo moved from foo.c to foo.h] + Signed-off-by: Lucky K Maintainer <lucky@maintainer.example.org> + +あなたが安定版のブランチを管理しており、作成者のクレジット、変更の追跡、 +修正のマージ、と同時に苦情からの投稿者の保護を行いたい場合、この慣習は特に +有用となります。いかなる事情があってもチェンジログに出てくる作成者の +アイデンティティ情報(From ヘッダ)は変更できないことに注意してください。 + +バックポートする人のための特別な注意事項。追跡を容易に行うために、コミット +メッセージのトップ(サブジェクト行のすぐ後)にパッチの起源を示す情報を記述する +ことは一般的で有用な慣習です。例えば、これは 2.6-stable ツリーでの一例です。 + + Date: Tue May 13 19:10:30 2008 +0000 + + SCSI: libiscsi regression in 2.6.25: fix nop timer handling + + commit 4cf1043593db6a337f10e006c23c69e5fc93e722 upstream + +そして、これは 2.4 ツリーでの一例です。 + + Date: Tue May 13 22:12:27 2008 +0200 + + wireless, airo: waitbusy() won't delay + + [backport of 2.6 commit b7acbdfbd1f277c1eb23f344f899cfa4cd0bf36a] + +どんな形式であれ、この情報はあなたのツリーを追跡する人やあなたのツリーのバグを +解決しようとしている人にとって価値のある支援となります。 + +13) いつ Acked-by: と Cc: を使うのか + +「 Signed-off-by: 」タグはその署名者がパッチの開発に関わっていたことやパッチ +の伝播パスにいたことを示しています。 + +ある人が直接パッチの準備や作成に関わっていないけれど、その人のパッチに対す +る承認を記録し、示したいとします。その場合、その人を示すのに Acked-by: が使 +えます。Acked-by: はパッチのチェンジログにも追加されます。 + +パッチの影響を受けるコードのメンテナがパッチに関わっていなかったり、パッチ +の伝播パスにいなかった時にも、メンテナは Acked-by: をしばしば利用します。 + +Acked-by: は Signed-off-by: のように公式なタグではありません。それはメンテナが +少なくともパッチをレビューし、同意を示しているという記録です。そのような +ことからパッチをマージする人がメンテナの「うん、良いと思うよ」という発言を +Acked-by: へ置き換えることがあります。 + +Acked-by: が必ずしもパッチ全体の承認を示しているわけではありません。例えば、 +あるパッチが複数のサブシステムへ影響を与えており、その中の1つのサブシステム +のメンテナからの Acked-by: を持っているとします。その場合、Acked-by: は通常 +そのメンテナのコードに影響を与える一部分だけに対する承認を示しています。 +この点は、ご自分で判断してください。(その Acked-by: が)疑わしい場合は、 +メーリングリストアーカイブの中の大元の議論を参照すべきです。 + +パッチにコメントする機会を持っていたが、その時にコメントしなかった人がいれば、 +その人を指す「Cc:」タグを任意で追加してもかまいません。これは指定された人からの +明確なアクションなしに付与できる唯一のタグです。 +このタグはパッチに関心があると思われる人達がそのパッチの議論に含まれていたこと +を明文化します。 + +14) Reported-by と Tested-by: と Reviewed-by: の利用 + +他の誰かによって報告された問題を修正するパッチであれば、問題報告者という寄与を +クレジットするために、Reported-by: タグを追加することを検討してください。 +こまめにバグ報告者をクレジットしていくことで、うまくいけばその人たちが将来再び +コミュニティの力となってくれるでしょう。 +ただし、報告者の許可無くこのタグを追加しないように注意してください。特に、 +問題が公の場で報告されていなかったのであれば。 + +Tested-by: タグはタグで指定された人によって(ある環境下で)パッチのテストに成功 +していることを示します。このタグはメンテナにテストが実施済みであることを +知らせ、将来の関連パッチのテスト協力者を見つける方法を提供し、テスト実施者に +対するクレジットを保証します。 + +Reviewed-by: タグは、それとは異なり、下記のレビューア宣言の下にレビューされ、 +受け入れ可能とみなされたパッチであることを示します。 + + レビューアによる監督宣言 + + 私は Reviewed-by: タグを提示することによって、以下のことを明言する。 + + (a) 私はメインラインカーネルへの統合に向け、その妥当性及び「即応性 + (訳注)」を検証し、技術的側面からパッチをレビュー済みである。 + + 訳注: + 「即応性」の原文は "readiness"。 + パッチが十分な品質を持っており、メインラインカーネルへの統合を即座に + 行うことができる状態であるかどうかを "readiness" という単語で表現 + している。 + + (b) パッチに関するあらゆる問題、懸念、あるいは、疑問は投稿者へ伝達済み + である。私はそれらのコメントに対する投稿者の返答に満足している。 + + (c) 投稿に伴い改良されるコードがある一方で、現時点で、私は(1)それが + カーネルにとって価値のある変更であること、そして、(2)統合に際して + 議論になり得るような問題はないものと確信している。 + + (d) 私はパッチをレビューし適切であると確信している一方で、あらゆる + 状況においてその宣言した目的や機能が正しく実現することに関して、 + いかなる保証もしない(特にどこかで明示しない限り)。 + +Reviewd-by タグはそのパッチがカーネルに対して適切な修正であって、深刻な技術的 +問題を残していないという意見の宣言です。興味のあるレビューアは誰でも(レビュー +作業を終えたら)パッチに対して Reviewed-by タグを提示できます。このタグは +レビューアの寄与をクレジットする働き、レビューの進捗の度合いをメンテナに +知らせる働きを持ちます。そのパッチの領域に詳しく、そして、しっかりとした +レビューを実施したレビューアによって提供される時、Reviewed-by: タグがあなたの +パッチをカーネルにマージする可能性を高めるでしょう。 + +15) 標準的なパッチのフォーマット + +標準的なパッチのサブジェクトは以下のとおりです。 + + Subject: [PATCH 001/123] subsystem: summary phrase + +標準的なパッチの、電子メールのボディは以下の項目を含んでいます。 + + - パッチの作成者を明記する「 from 」行 + + - 空行 + + - 説明本体。これはこのパッチを説明するために無期限のチェンジログ + (変更履歴)にコピーされます。 + + - 上述した「 Signed-off-by: 」行。これも説明本体と同じくチェン + ジログ内にコピーされます。 + + - マーカー行は単純に「 --- 」です。 + + - 余計なコメントは、チェンジログには不適切です。 + + - 実際のパッチ(差分出力) + +サブジェクト行のフォーマットは、アルファベット順で電子メールをとても +ソートしやすいものになっています。(ほとんどの電子メールクライアント +はソートをサポートしています)パッチのサブジェクトの連番は0詰めであ +るため、数字でのソートとアルファベットでのソートは同じ結果になります。 + +電子メールのサブジェクト内のサブシステム表記は、パッチが適用される +分野またはサブシステムを識別できるようにすべきです。 + +電子メールのサブジェクトの「summary phrase」はそのパッチの概要を正確 +に表現しなければなりません。「summary phrase」をファイル名にしてはい +けません。パッチシリーズ中でそれぞれのパッチは同じ「summary phrase」を +使ってはいけません(「パッチシリーズ」とは順序付けられた関連のある複数の +パッチ群です)。 + +あなたの電子メールの「summary phrase」がそのパッチにとって世界で唯一の識別子に +なるように心がけてください。「summary phrase」は git のチェンジログの中へ +ずっと伝播していきます。「summary phrase」は、開発者が後でパッチを参照する +ために議論の中で利用するかもしれません。 +人々はそのパッチに関連した議論を読むために「summary phrase」を使って google で +検索したがるでしょう。それはまた2、3ヶ月あとで、人々が「gitk」や +「git log --oneline」のようなツールを使用して何千ものパッチに目を通す時、 +唯一目にとまる情報となるでしょう。 + +これらの理由のため、「summary phrase」はなぜパッチが必要であるか、パッチが何を +変更するかの2つの情報をせいぜい70〜75文字で表現していなければなりません。 +「summary phrase」は簡潔であり説明的である表現を目指しつつ、うまく +まとめられている概要となるべきです。 + +「summary phrase」は「Subject: [PATCH tag] <summary phrase>」のように、 +大括弧で閉じられたタグを接頭辞として付加してもかまいません。このタグは +「summary phrase」の一部とは考えませんが、パッチをどのように取り扱うべきかを +表現します。 +一般的には「v1, v2, v3」のようなバージョン情報を表すタグ(過去のパッチに対する +コメントを反映するために複数のバージョンのパッチが投稿されているのであれば)、 +「RFC」のようなコメントを要求するタグが挙げられます。パッチシリーズとして4つの +パッチがあれば、個々のパッチに「1/4, 2/4, 3/4, 4/4」のように番号を付けても +かまいません。これは開発者がパッチを適用する順番を確実に把握するためです。 +そして、開発者がパッチシリーズの中のすべてのパッチをもらさずレビュー或いは +適用するのを保証するためです。 + +サブジェクトの例を二つ + + Subject: [patch 2/5] ext2: improve scalability of bitmap searching + Subject: [PATCHv2 001/207] x86: fix eflags tracking + +「 from 」行は電子メールのボディの一番最初の行でなければなりません。 +その形式は以下のとおりです。 + + From: Original Author <author@example.com> + +「 from 」行はチェンジログの中で、そのパッチの作成者としてクレジットされ +ている人を特定するものです。「 from 」行がかけていると、電子メールのヘッ +ダーの「 From: 」が、チェンジログの中でパッチの作成者を決定するために使わ +れるでしょう。 + +説明本体は無期限のソースのチェンジログにコミットされます。なので、説明 +本体はそのパッチに至った議論の詳細を忘れているある程度の技量を持っている人 +がその詳細を思い出すことができるものでなければなりません。パッチが対処する +障害の症状(カーネルログメッセージや oops メッセージ等)を記載することは問題に +対処可能なパッチを求めてコミットログを検索する人々にとって特に有用です。 +パッチがコンパイル問題を解決するのであれば、そのパッチを探している人が見つける +ことができる情報だけで十分であり、コンパイル時の全てのエラーを含める必要は +ありません。「summary phrase」と同様に、簡潔であり説明的であることが重要です。 + +「 --- 」マーカー行はパッチ処理ツールに対して、チェンジログメッセージの終端 +部分を認識させるという重要な役目を果たします。 + +「 --- 」マーカー行の後の追加コメントの良い使用方法の1つに diffstat コマンド +があります。diffstat コマンドとは何のファイルが変更され、1ファイル当たり何行 +追加され何行消されたかを示すものです。diffstat コマンドは特に大きなパッチに +おいて役立ちます。その時点でだけ又はメンテナにとってのみ関係のあるコメント +は無期限に保存されるチェンジログにとって適切ではありません。そのため、この +ようなコメントもマーカー行の後に書かれるべきです。 +このようなコメントの良い例として、v1 と v2 のバージョン間で何が変更されたかを +表す「パッチの変更履歴」が挙げられます。 + +「 --- 」マーカー行の後に diffstat コマンドの結果を含めるのであれば、ファイル +名はカーネルソースツリーのトップディレクトリからの表記で列記されるため、横方向 +のスペースをとり過ぎないように、diffstat コマンドにオプション「 -p 1 -w 70 」 +を指定してください(インデントを含めてちょうど80列に合うでしょう)。 + +適切なパッチのフォーマットの詳細についてはセクション3の参考文献を参照して +ください。 + +16) 「git pull」要求の送り方(Linus の電子メールから) + +間違ったブランチから引っ張るのを防ぐために、git リポジトリのアドレスと +ブランチ名を同じ行に1行で記載してください。そうすることで、3回の連続クリック +で全て選択できます。 + +正しい形式は下記の通りです。 + + "Please pull from + + git://jdelvare.pck.nerim.net/jdelvare-2.6 i2c-for-linus + + to get these changes:" + +その結果、アドレスを自分自身でタイピングして間違えることはなくなります(実際に、 +何度か間違ったブランチから引っ張ってきてしまい、その時に diffstat の結果を +検証して間違っていることに気づいたことがあります。どこから何を引っ張るべきかを +「探したり」、正しいブランチ名かどうかを重ねてチェックしたりする必要が +なくなればより快適になるでしょう)。 + +diffstat の結果を生成するために「 git diff -M --stat --summary 」を使って +ください。-M オプションはファイル名の変更を検知でき、--summary オプションは +新規ファイル、削除されたファイル、名前が変更されたファイルの概要を生成します。 + +-M オプション(ファイル名の変更検知)を指定すると、diffstat の結果はかなり +異なってきます。git は大規模な変更(追加と削除のペア)をファイル名の変更と +判断するためです。 + +------------------------------------ +セクション2 - ヒントとTIPSと小技 +------------------------------------ + +このセクションは Linux カーネルに変更を適用することに関係のある一般的な +「お約束」の多くを載せています。物事には例外というものがあります。しか +し例外を適用するには、本当に妥当な理由が不可欠です。あなたは恐らくこの +セクションを Linus のコンピュータ・サイエンス101と呼ぶでしょう。 + +1) Documentation/process/coding-style.rstを参照 + +言うまでもなく、あなたのコードがこのコーディングスタイルからあまりに +も逸脱していると、レビューやコメントなしに受け取ってもらえないかもし +れません。 + +特筆すべき例外は、コードをあるファイルから別のファイルに移動 +するときです。この場合、コードを移動するパッチでは、移動されるコード +に関して移動以外の変更を一切加えるべきではありません。これにより、 +コードの移動とあなたが行ったコードの修正を明確に区別できるようにな +ります。これは実際に何が変更されたかをレビューする際の大きな助けに +なるとともに、ツールにコードの履歴を追跡させることも容易になります。 + +投稿するより前にパッチのスタイルチェッカー( scripts/checkpatch.pl )で +あなたのパッチをチェックしてください。このスタイルチェッカーは最終結 +論としてではなく、指標としてみるべきです。もし、あなたのコードが違反 +はしているが修正するより良く見えるのであれば、おそらくそのままにする +のがベストです。 + +スタイルチェッカーによる3段階のレポート: + - エラー: 間違っている可能性が高い + - 警告：注意してレビューする必要がある + - チェック：考慮する必要がある + +あなたはパッチに残っている全ての違反について、それがなぜ必要なのか正当な +理由を示せるようにしておく必要があります。 + +2) #ifdefは見苦しい + +ifdef が散乱したコードは、読むのもメンテナンスするのも面倒です。コードの中 +で ifdef を使わないでください。代わりに、ヘッダファイルの中に ifdef を入れて、 +条件付きで、コードの中で使われる関数を「 static inline 」関数かマクロで定義し +てください。後はコンパイラが、何もしない箇所を最適化して取り去ってくれるで +しょう。 + +まずいコードの簡単な例 + + dev = alloc_etherdev (sizeof(struct funky_private)); + if (!dev) + return -ENODEV; + #ifdef CONFIG_NET_FUNKINESS + init_funky_net(dev); + #endif + +クリーンアップしたコードの例 + +(in header) + #ifndef CONFIG_NET_FUNKINESS + static inline void init_funky_net (struct net_device *d) {} + #endif + +(in the code itself) + dev = alloc_etherdev (sizeof(struct funky_private)); + if (!dev) + return -ENODEV; + init_funky_net(dev); + +3) マクロより「 static inline 」を推奨 + +「 static inline 」関数はマクロよりもずっと推奨されています。それらは、 +型安全性があり、長さにも制限が無く、フォーマットの制限もありません。 +gcc においては、マクロと同じくらい軽いです。 + +マクロは「 static inline 」が明らかに不適切であると分かる場所(高速化パスの +いくつかの特定のケース)や「 static inline 」関数を使うことができないような +場所(マクロの引数の文字列連結のような)にだけ使われるべきです。 + +「 static inline 」は「 static __inline__ 」や「 extern inline 」や +「 extern __inline__ 」よりも適切です。 + +4) 設計に凝りすぎるな + +それが有用になるかどうか分からないような不明瞭な将来を見越した設計 +をしないでください。「できる限り簡単に、そして、それ以上簡単になら +ないような設計をしてください。」 + +---------------------- +セクション3 参考文献 +---------------------- + +Andrew Morton, "The perfect patch" (tpp). + <http://www.ozlabs.org/~akpm/stuff/tpp.txt> + +Jeff Garzik, "Linux kernel patch submission format". + <http://linux.yyz.us/patch-format.html> + +Greg Kroah-Hartman, "How to piss off a kernel subsystem maintainer". + <http://www.kroah.com/log/2005/03/31/> + <http://www.kroah.com/log/2005/07/08/> + <http://www.kroah.com/log/2005/10/19/> + <http://www.kroah.com/log/2006/01/11/> + +NO!!!! No more huge patch bombs to linux-kernel@vger.kernel.org people! + <https://lkml.org/lkml/2005/7/11/336> + +Kernel Documentation/process/coding-style.rst: + <http://users.sosdg.org/~qiyong/lxr/source/Documentation/process/coding-style.rst> + +Linus Torvalds's mail on the canonical patch format: + <http://lkml.org/lkml/2005/4/7/183> + +Andi Kleen, "On submitting kernel patches" + Some strategies to get difficult or controversial changes in. + http://halobates.de/on-submitting-patches.pdf + +-- + + diff --git a/Documentation/translations/ja_JP/howto.rst b/Documentation/translations/ja_JP/howto.rst new file mode 100644 index 000000000..f3116381c --- /dev/null +++ b/Documentation/translations/ja_JP/howto.rst @@ -0,0 +1,654 @@ +NOTE: +This is a version of Documentation/process/howto.rst translated into Japanese. +This document is maintained by Tsugikazu Shibata <tshibata@ab.jp.nec.com> +If you find any difference between this document and the original file or +a problem with the translation, please contact the maintainer of this file. + +Please also note that the purpose of this file is to be easier to +read for non English (read: Japanese) speakers and is not intended as +a fork. So if you have any comments or updates for this file, please +try to update the original English file first. + +---------------------------------- + +この文書は、 +Documentation/process/howto.rst +の和訳です。 + +翻訳者： Tsugikazu Shibata <tshibata@ab.jp.nec.com> + +---------------------------------- + +Linux カーネル開発のやり方 +========================== + +これは上のトピック( Linux カーネル開発のやり方)の重要な事柄を網羅した +ドキュメントです。ここには Linux カーネル開発者になるための方法とLinux +カーネル開発コミュニティと共に活動するやり方を学ぶ方法が含まれています。 +カーネルプログラミングに関する技術的な項目に関することは何も含めないよ +うにしていますが、カーネル開発者となるための正しい方向に向かう手助けに +なります。 + +もし、このドキュメントのどこかが古くなっていた場合には、このドキュメント +の最後にリストしたメンテナにパッチを送ってください。 + +はじめに +--------- + +あなたは Linux カーネルの開発者になる方法を学びたいのでしょうか？ そ +れとも上司から「このデバイスの Linux ドライバを書くように」と言われた +のかもしれません。この文書の目的は、あなたが踏むべき手順と、コミュニティ +と一緒にうまく働くヒントを書き下すことで、あなたが知るべき全てのことを +教えることです。また、このコミュニティがなぜ今うまくまわっているのかと +いう理由も説明しようと試みています。 + +カーネルは少量のアーキテクチャ依存部分がアセンブリ言語で書かれている以 +外の大部分は C 言語で書かれています。C言語をよく理解していることはカー +ネル開発に必要です。低レベルのアーキテクチャ開発をするのでなければ、 +(どんなアーキテクチャでも)アセンブリ(訳注: 言語)は必要ありません。以下 +の本は、C 言語の十分な知識や何年もの経験に取って代わるものではありませ +んが、少なくともリファレンスとしては良い本です。 + + - "The C Programming Language" by Kernighan and Ritchie [Prentice Hall] + - 『プログラミング言語Ｃ第2版』(B.W. カーニハン/D.M. リッチー著 石田晴久訳) [共立出版] + - "Practical C Programming" by Steve Oualline [O'Reilly] + - 『C実践プログラミング第3版』(Steve Oualline著 望月康司監訳 谷口功訳) [オライリージャパン] + - "C: A Reference Manual" by Harbison and Steele [Prentice Hall] + - 『新・詳説 C 言語 H&S リファレンス』 (サミュエル P ハービソン/ガイ L スティール共著 斉藤 信男監訳)[ソフトバンク] + +カーネルは GNU C と GNU ツールチェインを使って書かれています。カーネル +は ISO C89 仕様に準拠して書く一方で、標準には無い言語拡張を多く使って +います。カーネルは標準 C ライブラリに依存しない、C 言語非依存環境です。 +そのため、C の標準の中で使えないものもあります。特に任意の long long +の除算や浮動小数点は使えません。カーネルがツールチェインや C 言語拡張 +に置いている前提がどうなっているのかわかりにくいことが時々あり、また、 +残念なことに決定的なリファレンスは存在しません。情報を得るには、gcc の +info ページ( info gcc )を見てください。 + +あなたは既存の開発コミュニティと一緒に作業する方法を学ぼうとしているこ +とに思い出してください。そのコミュニティは、コーディング、スタイル、開 +発手順について高度な標準を持つ、多様な人の集まりです。地理的に分散した +大規模なチームに対してもっともうまくいくとわかったことをベースにしなが +ら、これらの標準は長い時間をかけて築かれてきました。これらはきちんと文 +書化されていますから、事前にこれらの標準について事前にできるだけたくさ +ん学んでください。また皆があなたやあなたの会社のやり方に合わせてくれる +と思わないでください。 + +法的問題 +-------- + +Linux カーネルのソースコードは GPL ライセンスの下でリリースされていま +す。ライセンスの詳細については、ソースツリーのメインディレクトリに存在 +する、COPYING のファイルを見てください。もしライセンスについてさらに質 +問があれば、Linux Kernel メーリングリストに質問するのではなく、どうぞ +法律家に相談してください。メーリングリストの人達は法律家ではなく、法的 +問題については彼らの声明はあてにするべきではありません。 + +GPL に関する共通の質問や回答については、以下を参照してください- + + https://www.gnu.org/licenses/gpl-faq.html + +ドキュメント +------------ + +Linux カーネルソースツリーは幅広い範囲のドキュメントを含んでおり、それ +らはカーネルコミュニティと会話する方法を学ぶのに非常に貴重なものです。 +新しい機能がカーネルに追加される場合、その機能の使い方について説明した +新しいドキュメントファイルも追加することを勧めます。 +カーネルの変更が、カーネルがユーザ空間に公開しているインターフェイスの +変更を引き起こす場合、その変更を説明するマニュアルページのパッチや情報 +をマニュアルページのメンテナ mtk.manpages@gmail.com に送り、CC を +linux-api@vger.kernel.org に送ることを勧めます。 + +以下はカーネルソースツリーに含まれている読んでおくべきファイルの一覧で +す- + + README + このファイルは Linuxカーネルの簡単な背景とカーネルを設定(訳注 + configure )し、生成(訳注 build )するために必要なことは何かが書かれ + ています。 カーネルに関して初めての人はここからスタートすると良い + でしょう。 + + :ref:`Documentation/process/changes.rst <changes>` + このファイルはカーネルをうまく生成(訳注 build )し、走らせるのに最 + 小限のレベルで必要な数々のソフトウェアパッケージの一覧を示してい + ます。 + + :ref:`Documentation/process/coding-style.rst <codingstyle>` + これは Linux カーネルのコーディングスタイルと背景にある理由を記述 + しています。全ての新しいコードはこのドキュメントにあるガイドライン + に従っていることを期待されています。大部分のメンテナはこれらのルー + ルに従っているものだけを受け付け、多くの人は正しいスタイルのコード + だけをレビューします。 + + :ref:`Documentation/process/submitting-patches.rst <codingstyle>` と :ref:`Documentation/process/submitting-drivers.rst <submittingdrivers>` + これらのファイルには、どうやってうまくパッチを作って投稿するかにつ + いて非常に詳しく書かれており、以下を含みます (これだけに限らない + けれども) + + - Email に含むこと + - Email の形式 + - だれに送るか + + これらのルールに従えばうまくいくことを保証することではありません + が (すべてのパッチは内容とスタイルについて精査を受けるので)、 + ルールに従わなければ間違いなくうまくいかないでしょう。 + + この他にパッチを作る方法についてのよくできた記述は- + + "The Perfect Patch" + http://www.ozlabs.org/~akpm/stuff/tpp.txt + "Linux kernel patch submission format" + http://linux.yyz.us/patch-format.html + + :ref:`Documentation/process/stable-api-nonsense.rst <stable_api_nonsense>` + このファイルはカーネルの中に不変の API を持たないことにした意識的 + な決断の背景にある理由について書かれています。以下のようなことを含 + んでいます- + + - サブシステムとの間に層を作ること(コンパチビリティのため?) + - オペレーティングシステム間のドライバの移植性 + - カーネルソースツリーの素早い変更を遅らせる(もしくは素早い変更を妨げる) + + このドキュメントは Linux 開発の思想を理解するのに非常に重要です。 + そして、他のOSでの開発者が Linux に移る時にとても重要です。 + + :ref:`Documentation/admin-guide/security-bugs.rst <securitybugs>` + もし Linux カーネルでセキュリティ問題を発見したように思ったら、こ + のドキュメントのステップに従ってカーネル開発者に連絡し、問題解決を + 支援してください。 + + :ref:`Documentation/process/management-style.rst <managementstyle>` + このドキュメントは Linux カーネルのメンテナ達がどう行動するか、 + 彼らの手法の背景にある共有されている精神について記述しています。こ + れはカーネル開発の初心者なら（もしくは、単に興味があるだけの人でも） + 重要です。なぜならこのドキュメントは、カーネルメンテナ達の独特な + 行動についての多くの誤解や混乱を解消するからです。 + + :ref:`Documentation/process/stable-kernel-rules.rst <stable_kernel_rules>` + このファイルはどのように stable カーネルのリリースが行われるかのルー + ルが記述されています。そしてこれらのリリースの中のどこかで変更を取 + り入れてもらいたい場合に何をすれば良いかが示されています。 + + :Ref:`Documentation/process/kernel-docs.rst <kernel_docs>` + カーネル開発に付随する外部ドキュメントのリストです。もしあなたが探 + しているものがカーネル内のドキュメントでみつからなかった場合、この + リストをあたってみてください。 + + :ref:`Documentation/process/applying-patches.rst <applying_patches>` + パッチとはなにか、パッチをどうやって様々なカーネルの開発ブランチに + 適用するのかについて正確に記述した良い入門書です。 + +カーネルはソースコードそのものや、このファイルのようなリストラクチャー +ドテキストマークアップ(ReST)から自動的に生成可能な多数のドキュメントを +もっています。これにはカーネル内APIの完全な記述や、正しくロックをかけ +るための規則などが含まれます。 + +これら全てのドキュメントを PDF や HTML で生成するには以下を実行します - :: + + make pdfdocs + make htmldocs + +それぞれメインカーネルのソースディレクトリから実行します。 + +ReSTマークアップを使ったドキュメントは Documentation/outputに生成され +ます。Latex とePub 形式で生成するには - :: + + make latexdocs + make epubdocs + +カーネル開発者になるには +------------------------ + +もしあなたが、Linux カーネル開発について何も知らないのならば、 +KernelNewbies プロジェクトを見るべきです + + https://kernelnewbies.org + +このサイトには役に立つメーリングリストがあり、基本的なカーネル開発に関 +するほとんどどんな種類の質問もできます (既に回答されているようなことを +聞く前にまずはアーカイブを調べてください)。またここには、リアルタイム +で質問を聞くことができる IRC チャネルや、Linuxカーネルの開発に関して学 +ぶのに便利なたくさんの役に立つドキュメントがあります。 + +Web サイトには、コードの構成、サブシステム、現在存在するプロジェクト +(ツリーにあるもの無いものの両方)の基本的な管理情報があります。ここには、 +また、カーネルのコンパイルのやり方やパッチの当て方などの間接的な基本情 +報も記述されています。 + +あなたがどこからスタートして良いかわからないが、Linux カーネル開発コミュ +ニティに参加して何かすることをさがしているのであれば、Linux kernel +Janitor's プロジェクトにいけば良いでしょう - + + https://kernelnewbies.org/KernelJanitors + +ここはそのようなスタートをするのにうってつけの場所です。ここには、 +Linux カーネルソースツリーの中に含まれる、きれいにし、修正しなければな +らない、単純な問題のリストが記述されています。このプロジェクトに関わる +開発者と一緒に作業することで、あなたのパッチを Linuxカーネルツリーに入 +れるための基礎を学ぶことができ、そしてもしあなたがまだアイディアを持っ +ていない場合には、次にやる仕事の方向性が見えてくるかもしれません。 + +もしあなたが、すでにひとまとまりコードを書いていて、カーネルツリーに入 +れたいと思っていたり、それに関する適切な支援を求めたい場合、カーネルメ +ンターズプロジェクトはそのような皆さんを助けるためにできました。ここに +はメーリングリストがあり、以下から参照できます - + + https://selenic.com/mailman/listinfo/kernel-mentors + +実際に Linux カーネルのコードについて修正を加える前に、どうやってその +コードが動作するのかを理解することが必要です。そのためには、特別なツー +ルの助けを借りてでも、それを直接よく読むことが最良の方法です(ほとんど +のトリッキーな部分は十分にコメントしてありますから)。そういうツールで +特におすすめなのは、Linux クロスリファレンスプロジェクトです。これは、 +自己参照方式で、索引がついた web 形式で、ソースコードを参照することが +できます。この最新の素晴しいカーネルコードのリポジトリは以下で見つかり +ます - + + http://lxr.free-electrons.com/ + +開発プロセス +------------ + +Linux カーネルの開発プロセスは現在幾つかの異なるメインカーネル「ブラン +チ」と多数のサブシステム毎のカーネルブランチから構成されます。これらの +ブランチとは - + + - メインの 4.x カーネルツリー + - 4.x.y -stable カーネルツリー + - 4.x -git カーネルパッチ + - サブシステム毎のカーネルツリーとパッチ + - 統合テストのための 4.x -next カーネルツリー + +4.x カーネルツリー +~~~~~~~~~~~~~~~~~~ + +4.x カーネルは Linus Torvalds によってメンテナンスされ、 +https://kernel.org の pub/linux/kernel/v4.x/ ディレクトリに存在します。 +この開発プロセスは以下のとおり - + + - 新しいカーネルがリリースされた直後に、2週間の特別期間が設けられ、 + この期間中に、メンテナ達は Linus に大きな差分を送ることができます。 + このような差分は通常 -next カーネルに数週間含まれてきたパッチです。 + 大きな変更は git(カーネルのソース管理ツール、詳細は + http://git-scm.com/ 参照) を使って送るのが好ましいやり方ですが、パッ + チファイルの形式のまま送るのでも十分です。 + - 2週間後、-rc1 カーネルがリリースされ、この後にはカーネル全体の安定 + 性に影響をあたえるような新機能は含まない類のパッチしか取り込むこと + はできません。新しいドライバ(もしくはファイルシステム)のパッチは + -rc1 の後で受け付けられることもあることを覚えておいてください。な + ぜなら、変更が独立していて、追加されたコードの外の領域に影響を与え + ない限り、退行のリスクは無いからです。-rc1 がリリースされた後、 + Linus へパッチを送付するのに git を使うこともできますが、パッチは + レビューのために、パブリックなメーリングリストへも同時に送る必要が + あります。 + - 新しい -rc は Linus が、最新の git ツリーがテスト目的であれば十分 + に安定した状態にあると判断したときにリリースされます。目標は毎週新 + しい -rc カーネルをリリースすることです。 + - このプロセスはカーネルが 「準備ができた」と考えられるまで継続しま + す。このプロセスはだいたい 6週間継続します。 + +Andrew Morton が Linux-kernel メーリングリストにカーネルリリースについ +て書いたことをここで言っておくことは価値があります - + + *「カーネルがいつリリースされるかは誰も知りません。なぜなら、 + これは現実に認識されたバグの状況によりリリースされるのであり、 + 前もって決められた計画によってリリースされるものではないから + です。」* + +4.x.y -stable カーネルツリー +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +バージョン番号が3つの数字に分かれているカーネルは -stable カーネルです。 +これには、4.x カーネルで見つかったセキュリティ問題や重大な後戻りに対す +る比較的小さい重要な修正が含まれます。 + +これは、開発/実験的バージョンのテストに協力することに興味が無く、最新 +の安定したカーネルを使いたいユーザに推奨するブランチです。 + +もし、4.x.y カーネルが存在しない場合には、番号が一番大きい 4.x が最新 +の安定版カーネルです。 + +4.x.y は "stable" チーム <stable@vger.kernel.org> でメンテされており、 +必要に応じてリリースされます。通常のリリース期間は 2週間毎ですが、差 +し迫った問題がなければもう少し長くなることもあります。セキュリティ関 +連の問題の場合はこれに対してだいたいの場合、すぐにリリースがされます。 + +カーネルツリーに入っている、 +Documentation/process/stable-kernel-rules.rst ファイルにはどのような種 +類の変更が -stable ツリーに受け入れ可能か、またリリースプロセスがどう +動くかが記述されています。 + +4.x -git パッチ +~~~~~~~~~~~~~~~ + +git リポジトリで管理されているLinus のカーネルツリーの毎日のスナップ +ショットがあります。(だから -git という名前がついています)。これらのパッ +チはおおむね毎日リリースされており、Linus のツリーの現状を表します。こ +れは -rc カーネルと比べて、パッチが大丈夫かどうかも確認しないで自動的 +に生成されるので、より実験的です。 + +サブシステム毎のカーネルツリーとパッチ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +それぞれのカーネルサブシステムのメンテナ達は --- そして多くのカーネル +サブシステムの開発者達も --- 各自の最新の開発状況をソースリポジトリに +公開しています。そのため、自分とは異なる領域のカーネルで何が起きている +かを他の人が見られるようになっています。開発が早く進んでいる領域では、 +開発者は自身の投稿がどのサブシステムカーネルツリーを元にしているか質問 +されるので、その投稿とすでに進行中の他の作業との衝突が避けられます。 + +大部分のこれらのリポジトリは git ツリーです。しかしその他の SCM や +quilt シリーズとして公開されているパッチキューも使われています。これら +のサブシステムリポジトリのアドレスは MAINTAINERS ファイルにリストされ +ています。これらの多くは https://git.kernel.org/ で参照することができま +す。 + +提案されたパッチがこのようなサブシステムツリーにコミットされる前に、メー +リングリストで事前にレビューにかけられます（以下の対応するセクションを +参照）。いくつかのカーネルサブシステムでは、このレビューは patchworkと +いうツールによって追跡されます。Patchwork は web インターフェイスによっ +てパッチ投稿の表示、パッチへのコメント付けや改訂などができ、そしてメン +テナはパッチに対して、レビュー中、受付済み、拒否というようなマークをつ +けることができます。大部分のこれらの patchwork のサイトは +https://patchwork.kernel.org/ でリストされています。 + +統合テストのための 4.x -next カーネルツリー +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +サブシステムツリーの更新内容がメインラインの 4.x ツリーにマージされる +前に、それらは統合テストされる必要があります。この目的のため、実質的に +全サブシステムツリーからほぼ毎日プルされてできる特別なテスト用のリポジ +トリが存在します- + + https://git.kernel.org/?p=linux/kernel/git/next/linux-next.git + +このやり方によって、-next カーネルは次のマージ機会でどんなものがメイン +ラインカーネルにマージされるか、おおまかなの展望を提供します。-next カー +ネルの実行テストを行う冒険好きなテスターは大いに歓迎されます。 + +バグレポート +------------- + +https://bugzilla.kernel.org は Linux カーネル開発者がカーネルのバグを追跡する +場所です。ユーザは見つけたバグの全てをこのツールで報告すべきです。どう +kernel bugzilla を使うかの詳細は、以下を参照してください - + + https://bugzilla.kernel.org/page.cgi?id=faq.html + +メインカーネルソースディレクトリにあるファイル +admin-guide/reporting-bugs.rstはカーネルバグらしいものについてどうレポー +トするかの良いテンプレートであり、問題の追跡を助けるためにカーネル開発 +者にとってどんな情報が必要なのかの詳細が書かれています。 + +バグレポートの管理 +------------------- + +あなたのハッキングのスキルを訓練する最高の方法のひとつに、他人がレポー +トしたバグを修正することがあります。あなたがカーネルをより安定化させる +こに寄与するということだけでなく、あなたは 現実の問題を修正することを +学び、自分のスキルも強化でき、また他の開発者があなたの存在に気がつきま +す。バグを修正することは、多くの開発者の中から自分が功績をあげる最善の +道です、なぜなら多くの人は他人のバグの修正に時間を浪費することを好まな +いからです。 + +すでにレポートされたバグのために仕事をするためには、 +https://bugzilla.kernel.org に行ってください。もし今後のバグレポートに +ついてアドバイスを受けたいのであれば、bugme-new メーリングリスト(新し +いバグレポートだけがここにメールされる) または bugme-janitor メーリン +グリスト(bugzilla の変更毎にここにメールされる)を購読できます。 + + https://lists.linux-foundation.org/mailman/listinfo/bugme-new + + https://lists.linux-foundation.org/mailman/listinfo/bugme-janitors + +メーリングリスト +---------------- + +上のいくつかのドキュメントで述べていますが、コアカーネル開発者の大部分 +は Linux kernel メーリングリストに参加しています。このリストの登録/脱 +退の方法については以下を参照してください- + + http://vger.kernel.org/vger-lists.html#linux-kernel + +このメーリングリストのアーカイブは web 上の多数の場所に存在します。こ +れらのアーカイブを探すにはサーチエンジンを使いましょう。例えば- + + http://dir.gmane.org/gmane.linux.kernel + +リストに投稿する前にすでにその話題がアーカイブに存在するかどうかを検索 +することを是非やってください。多数の事がすでに詳細に渡って議論されてお +り、アーカイブにのみ記録されています。 + +大部分のカーネルサブシステムも自分の個別の開発を実施するメーリングリス +トを持っています。個々のグループがどんなリストを持っているかは、 +MAINTAINERS ファイルにリストがありますので参照してください。 + +多くのリストは kernel.org でホストされています。これらの情報は以下にあ +ります - + + http://vger.kernel.org/vger-lists.html + +メーリングリストを使う場合、良い行動習慣に従うようにしましょう。少し安っ +ぽいが、以下の URL は上のリスト(や他のリスト)で会話する場合のシンプル +なガイドラインを示しています - + + http://www.albion.com/netiquette/ + +もし複数の人があなたのメールに返事をした場合、CC: で受ける人のリストは +だいぶ多くなるでしょう。正当な理由がない限り、CC: リストから誰かを削除 +をしないように、また、メーリングリストのアドレスだけにリプライすること +のないようにしましょう。1つは送信者から、もう1つはリストからのように、 +メールを2回受けることになってもそれに慣れ、しゃれたメールヘッダーを追 +加してこの状態を変えようとしないように。人々はそのようなことは好みませ +ん。 + +今までのメールでのやりとりとその間のあなたの発言はそのまま残し、 +"John Kernelhacker wrote ...:" の行をあなたのリプライの先頭行にして、 +メールの先頭でなく、各引用行の間にあなたの言いたいことを追加するべきで +す。 + +もしパッチをメールに付ける場合は、 +Documentation/process/submitting-patches.rst に提示されているように、そ +れは プレーンな可読テキストにすることを忘れないようにしましょう。カー +ネル開発者は 添付や圧縮したパッチを扱いたがりません。彼らはあなたのパッ +チの行毎にコメントを入れたいので、そうするしかありません。あなたのメー +ルプログラムが空白やタブを圧縮しないように確認しましょう。最初の良いテ +ストとしては、自分にメールを送ってみて、そのパッチを自分で当ててみるこ +とです。もしそれがうまく行かないなら、あなたのメールプログラムを直して +もらうか、正しく動くように変えるべきです。 + +何をおいても、他の購読者に対する敬意を表すことを忘れないでください。 + +コミュニティと共に働くこと +-------------------------- + +カーネルコミュニティのゴールは可能なかぎり最高のカーネルを提供すること +です。あなたがパッチを受け入れてもらうために投稿した場合、それは、技術 +的メリットだけがレビューされます。その際、あなたは何を予想すべきでしょ +うか? + + - 批判 + - コメント + - 変更の要求 + - パッチの正当性の証明要求 + - 沈黙 + +思い出してください、これはあなたのパッチをカーネルに入れる話です。あな +たは、あなたのパッチに対する批判とコメントを受け入れるべきで、それらを +技術的レベルで評価して、パッチを再作成するか、なぜそれらの変更をすべき +でないかを明確で簡潔な理由の説明を提供してください。もし、あなたのパッ +チに何も反応がない場合、たまにはメールの山に埋もれて見逃され、あなたの +投稿が忘れられてしまうこともあるので、数日待って再度投稿してください。 + +あなたがやるべきでないことは? + + - 質問なしにあなたのパッチが受け入れられると想像すること + - 守りに入ること + - コメントを無視すること + - 要求された変更を何もしないでパッチを出し直すこと + +可能な限り最高の技術的解決を求めているコミュニティでは、パッチがどのく +らい有益なのかについては常に異なる意見があります。あなたは協調的である +べきですし、また、あなたのアイディアをカーネルに対してうまく合わせるよ +うにすることが望まれています。もしくは、最低限あなたのアイディアがそれ +だけの価値があるとすすんで証明するようにしなければなりません。 +正しい解決に向かって進もうという意志がある限り、間違うことがあっても許 +容されることを忘れないでください。 + +あなたの最初のパッチに単に 1ダースもの修正を求めるリストの返答になるこ +とも普通のことです。これはあなたのパッチが受け入れられないということで +は **ありません**、そしてあなた自身に反対することを意味するのでも **あ +りません**。単に自分のパッチに対して指摘された問題を全て修正して再送す +れば良いのです。 + + +カーネルコミュニティと企業組織のちがい +----------------------------------------------------------------- + +カーネルコミュニティは大部分の伝統的な会社の開発環境とは異ったやり方で +動いています。以下は問題を避けるためにできると良いことのリストです。 + + あなたの提案する変更について言うときのうまい言い方 - + + - "これは複数の問題を解決します" + - "これは2000行のコードを削除します" + - "以下のパッチは、私が言おうとしていることを説明するものです" + - "私はこれを5つの異なるアーキテクチャでテストしたのですが..." + - "以下は一連の小さなパッチ群ですが..." + - "これは典型的なマシンでの性能を向上させます..." + + やめた方が良い悪い言い方 - + + - "このやり方で AIX/ptx/Solaris ではできたので、できるはずだ..." + - "私はこれを20年もの間やってきた、だから..." + - "これは私の会社が金儲けをするために必要だ" + - "これは我々のエンタープライズ向け商品ラインのためである" + - "これは私が自分のアイディアを記述した、1000ページの設計資料である" + - "私はこれについて、6ケ月作業している..." + - "以下は ... に関する5000行のパッチです" + - "私は現在のぐちゃぐちゃを全部書き直した、それが以下です..." + - "私は〆切がある、そのためこのパッチは今すぐ適用される必要がある" + +カーネルコミュニティが大部分の伝統的なソフトウェアエンジニアリングの労 +働環境と異なるもう一つの点は、やりとりに顔を合わせないということです。 +email と irc を第一のコミュニケーションの形とする一つの利点は、性別や +民族の差別がないことです。Linux カーネルの職場環境は女性や少数民族を受 +容します。なぜなら、email アドレスによってのみあなたが認識されるからで +す。 +国際的な側面からも活動領域を均等にするようにします。なぜならば、あなた +は人の名前で性別を想像できないからです。ある男性が アンドレアという名 +前で、女性の名前は パット かもしれません (訳注 Andrea は米国では女性、 +それ以外(欧州など)では男性名として使われることが多い。同様に、Pat は +Patricia (主に女性名)や Patrick (主に男性名)の略称)。 +Linux カーネルの活動をして、意見を表明したことがある大部分の女性は、前 +向きな経験をもっています。 + +言葉の壁は英語が得意でない一部の人には問題になります。メーリングリスト +の中で、きちんとアイディアを交換するには、相当うまく英語を操れる必要が +あることもあります。そのため、自分のメールを送る前に英語で意味が通じて +いるかをチェックすることをお薦めします。 + +変更を分割する +-------------- + +Linux カーネルコミュニティは、一度に大量のコードの塊を喜んで受容するこ +とはありません。変更は正確に説明される必要があり、議論され、小さい、個 +別の部分に分割する必要があります。これはこれまで多くの会社がやり慣れて +きたことと全く正反対のことです。あなたのプロポーザルは、開発プロセスのと +ても早い段階から紹介されるべきです。そうすれば あなたは自分のやってい +ることにフィードバックを得られます。これは、コミュニティからみれば、あ +なたが彼らと一緒にやっているように感じられ、単にあなたの提案する機能の +ゴミ捨て場として使っているのではない、と感じられるでしょう。 +しかし、一度に 50 もの email をメーリングリストに送りつけるようなことは +やってはいけません、あなたのパッチ群はいつもどんな時でもそれよりは小さ +くなければなりません。 + +パッチを分割する理由は以下 - + +1) 小さいパッチはあなたのパッチが適用される見込みを大きくします、カー + ネルの人達はパッチが正しいかどうかを確認する時間や労力をかけないか + らです。5行のパッチはメンテナがたった1秒見るだけで適用できます。 + しかし、500行のパッチは、正しいことをレビューするのに数時間かかるか + もしれません(時間はパッチのサイズなどにより指数関数に比例してかかり + ます) + + 小さいパッチは何かあったときにデバッグもとても簡単になります。パッ + チを1個1個取り除くのは、とても大きなパッチを当てた後に(かつ、何かお + かしくなった後で)解剖するのに比べればとても簡単です。 + +2) 小さいパッチを送るだけでなく、送るまえに、書き直して、シンプルにす + る(もしくは、単に順番を変えるだけでも)ことも、とても重要です。 + +以下はカーネル開発者の Al Viro のたとえ話です - + + *"生徒の数学の宿題を採点する先生のことを考えてみてください、 + 先生は生徒が解に到達するまでの試行錯誤を見たいとは思わないでし + ょう。先生は簡潔な最高の解を見たいのです。良い生徒はこれを知っ + ており、そして最終解の前の中間作業を提出することは決してないの + です* + + *カーネル開発でもこれは同じです。メンテナ達とレビューア達は、 + 問題を解決する解の背後になる思考プロセスを見たいとは思いません。 + 彼らは単純であざやかな解決方法を見たいのです。"* + +あざやかな解を説明するのと、コミュニティと共に仕事をし、未解決の仕事を +議論することのバランスをキープするのは難しいかもしれません。ですから、 +開発プロセスの早期段階で改善のためのフィードバックをもらうようにするの +も良いですが、変更点を小さい部分に分割して全体ではまだ完成していない仕 +事を(部分的に)取り込んでもらえるようにすることも良いことです。 + +また、でき上がっていないものや、"将来直す" ようなパッチを、本流に含め +てもらうように送っても、それは受け付けられないことを理解してください。 + +あなたの変更を正当化する +------------------------ + +あなたのパッチを分割するのと同時に、なぜその変更を追加しなければならな +いかを Linux コミュニティに知らせることはとても重要です。新機能は必要 +性と有用性で正当化されなければなりません。 + +あなたの変更を説明する +---------------------- + +あなたのパッチを送付する場合には、メールの中のテキストで何を言うかにつ +いて、特別に注意を払ってください。この情報はパッチの ChangeLog に使わ +れ、いつも皆がみられるように保管されます。これは次のような項目を含め、 +パッチを完全に記述するべきです - + + - なぜ変更が必要か + - パッチ全体の設計アプローチ + - 実装の詳細 + - テスト結果 + +これについて全てがどのようにあるべきかについての詳細は、以下のドキュメ +ントの ChangeLog セクションを見てください - + + "The Perfect Patch" + http://www.ozlabs.org/~akpm/stuff/tpp.txt + +これらはどれも、実行することが時にはとても困難です。これらの例を完璧に +実施するには数年かかるかもしれません。これは継続的な改善のプロセスであ +り、多くの忍耐と決意を必要とするものです。でも諦めないで、実現は可能で +す。多数の人がすでにできていますし、彼らも最初はあなたと同じところから +スタートしたのですから。 + + + + +---------- + +Paolo Ciarrocchi に感謝、彼は彼の書いた "Development Process" +(https://lwn.net/Articles/94386/) セクションをこのテキストの原型にする +ことを許可してくれました。Rundy Dunlap と Gerrit Huizenga はメーリング +リストでやるべきこととやってはいけないことのリストを提供してくれました。 +以下の人々のレビュー、コメント、貢献に感謝。 +Pat Mochel, Hanna Linder, Randy Dunlap, Kay Sievers, +Vojtech Pavlik, Jan Kara, Josh Boyer, Kees Cook, Andrew Morton, Andi +Kleen, Vadim Lobanov, Jesper Juhl, Adrian Bunk, Keri Harris, Frans Pop, +David A. Wheeler, Junio Hamano, Michael Kerrisk, と Alex Shepard +彼らの支援なしでは、このドキュメントはできなかったでしょう。 + + + +Maintainer: Greg Kroah-Hartman <greg@kroah.com> diff --git a/Documentation/translations/ja_JP/index.rst b/Documentation/translations/ja_JP/index.rst new file mode 100644 index 000000000..2f91b895e --- /dev/null +++ b/Documentation/translations/ja_JP/index.rst @@ -0,0 +1,12 @@ +.. raw:: latex + + \renewcommand\thesection* + \renewcommand\thesubsection* + +Japanese translations +===================== + +.. toctree:: + :maxdepth: 1 + + howto diff --git a/Documentation/translations/ja_JP/stable_api_nonsense.txt b/Documentation/translations/ja_JP/stable_api_nonsense.txt new file mode 100644 index 000000000..a3b40a4bd --- /dev/null +++ b/Documentation/translations/ja_JP/stable_api_nonsense.txt @@ -0,0 +1,263 @@ +NOTE: +This is a version of Documentation/process/stable-api-nonsense.rst into Japanese. +This document is maintained by IKEDA, Munehiro <m-ikeda@ds.jp.nec.com> +and the JF Project team <http://www.linux.or.jp/JF/>. +If you find any difference between this document and the original file +or a problem with the translation, +please contact the maintainer of this file or JF project. + +Please also note that the purpose of this file is to be easier to read +for non English (read: Japanese) speakers and is not intended as a +fork. So if you have any comments or updates of this file, please try +to update the original English file first. + +Last Updated: 2007/07/18 +================================== +これは、 +linux-2.6.22-rc4/Documentation/process/stable-api-nonsense.rst の和訳 +です。 +翻訳団体： JF プロジェクト < http://www.linux.or.jp/JF/ > +翻訳日 ： 2007/06/11 +原著作者: Greg Kroah-Hartman < greg at kroah dot com > +翻訳者 ： 池田 宗広 < m-ikeda at ds dot jp dot nec dot com > +校正者 ： Masanori Kobayashi さん < zap03216 at nifty dot ne dot jp > + Seiji Kaneko さん < skaneko at a2 dot mbn dot or dot jp > +================================== + + + +Linux カーネルのドライバインターフェース +（あなたの質問すべてに対する回答とその他諸々） + +Greg Kroah-Hartman <greg at kroah dot com> + + +この文書は、なぜ Linux ではバイナリカーネルインターフェースが定義 +されていないのか、またはなぜ不変のカーネルインターフェースを持たな +いのか、ということを説明するために書かれた。ここでの話題は「カーネ +ル内部の」インターフェースについてであり、ユーザー空間とのインター +フェースではないことを理解してほしい。カーネルとユーザー空間とのイ +ンターフェースとはアプリケーションプログラムが使用するものであり、 +つまりシステムコールのインターフェースがこれに当たる。これは今まで +長きに渡り、かつ今後も「まさしく」不変である。私は確か 0.9 か何か +より前のカーネルを使ってビルドした古いプログラムを持っているが、そ +れは最新の 2.6 カーネルでもきちんと動作する。ユーザー空間とのイン +ターフェースは、ユーザーとアプリケーションプログラマが不変性を信頼 +してよいものの一つである。 + + +要旨 +---- + +あなたは不変のカーネルインターフェースが必要だと考えているかもしれ +ないが、実際のところはそうではない。あなたは必要としているものが分 +かっていない。あなたが必要としているものは安定して動作するドライバ +であり、それはドライバがメインのカーネルツリーに含まれる場合のみ得 +ることができる。ドライバがメインのカーネルツリーに含まれていると、 +他にも多くの良いことがある。それは、Linux をより強固で、安定な、成 +熟したオペレーティングシステムにすることができるということだ。これ +こそ、そもそもあなたが Linux を使う理由のはずだ。 + + +はじめに +-------- + +カーネル内部のインターフェース変更を心配しなければならないドライバ +を書きたいなどというのは、変わり者だけだ。この世界のほとんどの人は、 +そのようなドライバがどんなインターフェースを使っているかなど知らな +いし、そんなドライバのことなど全く気にもかけていない。 + + +まず初めに、クローズソースとか、ソースコードの隠蔽とか、バイナリの +みが配布される使い物にならない代物[訳注(1)]とか、実体はバイナリ +コードでそれを読み込むためのラッパー部分のみソースコードが公開され +ているとか、その他用語は何であれ GPL の下にソースコードがリリース +されていないカーネルドライバに関する法的な問題について、私は「いか +なる議論も」行うつもりがない。法的な疑問があるのならば、プログラマ +である私ではなく、弁護士に相談して欲しい。ここでは単に、技術的な問 +題について述べることにする。（法的な問題を軽視しているわけではない。 +それらは実際に存在するし、あなたはそれをいつも気にかけておく必要が +ある） + +訳注(1) +「使い物にならない代物」の原文は "blob" + + +さてここでは、バイナリカーネルインターフェースについてと、ソースレ +ベルでのインターフェースの不変性について、という二つの話題を取り上 +げる。この二つは互いに依存する関係にあるが、まずはバイナリインター +フェースについて議論を行いやっつけてしまおう。 + + +バイナリカーネルインターフェース +-------------------------------- + +もしソースレベルでのインターフェースが不変ならば、バイナリインター +フェースも当然のように不変である、というのは正しいだろうか？正しく +ない。Linux カーネルに関する以下の事実を考えてみてほしい。 + - あなたが使用するＣコンパイラのバージョンによって、カーネル内部 + の構造体の配置構造は異なったものになる。また、関数は異なった方 + 法でカーネルに含まれることになるかもしれない（例えばインライン + 関数として扱われたり、扱われなかったりする）。個々の関数がどの + ようにコンパイルされるかはそれほど重要ではないが、構造体のパデ + ィングが異なるというのは非常に重要である。 + - あなたがカーネルのビルドオプションをどのように設定するかによっ + て、カーネルには広い範囲で異なった事態が起こり得る。 + - データ構造は異なるデータフィールドを持つかもしれない + - いくつかの関数は全く実装されていない状態になり得る + （例：SMP向けではないビルドでは、いくつかのロックは中身が + カラにコンパイルされる） + - カーネル内のメモリは、異なった方法で配置され得る。これはビ + ルドオプションに依存している。 + - Linux は様々な異なるプロセッサアーキテクチャ上で動作する。 + あるアーキテクチャ用のバイナリドライバを、他のアーキテクチャで + 正常に動作させる方法はない。 + + +ある特定のカーネル設定を使用し、カーネルをビルドしたのと正確に同じ +Ｃコンパイラを使用して単にカーネルモジュールをコンパイルするだけで +も、あなたはこれらいくつもの問題に直面することになる。ある特定の +Linux ディストリビューションの、ある特定のリリースバージョン用にモ +ジュールを提供しようと思っただけでも、これらの問題を引き起こすには +十分である。にも関わらず Linux ディストリビューションの数と、サ +ポートするディストリビューションのリリース数を掛け算し、それら一つ +一つについてビルドを行ったとしたら、今度はリリースごとのビルドオプ +ションの違いという悪夢にすぐさま悩まされることになる。また、ディス +トリビューションの各リリースバージョンには、異なるハードウェア（プ +ロセッサタイプや種々のオプション）に対応するため、何種類かのカーネ +ルが含まれているということも理解して欲しい。従って、ある一つのリ +リースバージョンだけのためにモジュールを作成する場合でも、あなたは +何バージョンものモジュールを用意しなければならない。 + + +信じて欲しい。このような方法でサポートを続けようとするなら、あなた +はいずれ正気を失うだろう。遠い昔、私はそれがいかに困難なことか、身 +をもって学んだのだ・・・ + + +不変のカーネルソースレベルインターフェース +------------------------------------------ + +メインカーネルツリーに含まれていない Linux カーネルドライバを継続 +してサポートしていこうとしている人たちとの議論においては、これは極 +めて「引火性の高い」話題である。[訳注(2)] + +訳注(2) +「引火性の高い」の原文は "volatile"。 +volatile には「揮発性の」「爆発しやすい」という意味の他、「変わり +やすい」「移り気な」という意味がある。 +「（この話題は）爆発的に激しい論争を巻き起こしかねない」ということ +を、「（カーネルのソースレベルインターフェースは）移ろい行くもので +ある」ということを連想させる "volatile" という単語で表現している。 + + +Linux カーネルの開発は継続的に速いペースで行われ、決して歩みを緩め +ることがない。その中でカーネル開発者達は、現状のインターフェースに +あるバグを見つけ、より良い方法を考え出す。彼らはやがて、現状のイン +ターフェースがより正しく動作するように修正を行う。その過程で関数の +名前は変更されるかもしれず、構造体は大きく、または小さくなるかもし +れず、関数の引数は検討しなおされるかもしれない。そのような場合、引 +き続き全てが正常に動作するよう、カーネル内でこれらのインターフェー +スを使用している個所も全て同時に修正される。 + + +具体的な例として、カーネル内の USB インターフェースを挙げる。USB +サブシステムはこれまでに少なくとも３回の書き直しが行われ、その結果 +インターフェースが変更された。これらの書き直しはいくつかの異なった +問題を修正するために行われた。 + - 同期的データストリームが非同期に変更された。これにより多数のド + ライバを単純化でき、全てのドライバのスループットが向上した。今 + やほとんど全ての USB デバイスは、考えられる最高の速度で動作し + ている。 + - USB ドライバが USB サブシステムのコアから行う、データパケット + 用のメモリ確保方法が変更された。これに伴い、いくつもの文書化さ + れたデッドロック条件を回避するため、全ての USB ドライバはより + 多くの情報を USB コアに提供しなければならないようになっている。 + + +このできごとは、数多く存在するクローズソースのオペレーティングシス +テムとは全く対照的だ。それらは長期に渡り古い USB インターフェース +をメンテナンスしなければならない。古いインターフェースが残ることで、 +新たな開発者が偶然古いインターフェースを使い、正しくない方法で開発 +を行ってしまう可能性が生じる。これによりシステムの安定性は危険にさ +らされることになる。 + + +上に挙げたどちらの例においても、開発者達はその変更が重要かつ必要で +あることに合意し、比較的楽にそれを実行した。もし Linux がソースレ +ベルでインターフェースの不変性を保証しなければならないとしたら、新 +しいインターフェースを作ると同時に、古い、問題のある方を今後ともメ +ンテナンスするという余計な仕事を USB の開発者にさせなければならな +い。Linux の USB 開発者は、自分の時間を使って仕事をしている。よっ +て、価値のない余計な仕事を報酬もなしに実行しろと言うことはできない。 + + +セキュリティ問題も、Linux にとっては非常に重要である。ひとたびセキ +ュリティに関する問題が発見されれば、それは極めて短期間のうちに修正 +される。セキュリティ問題の発生を防ぐための修正は、カーネルの内部イ +ンターフェースの変更を何度も引き起こしてきた。その際同時に、変更さ +れたインターフェースを使用する全てのドライバもまた変更された。これ +により問題が解消し、将来偶然に問題が再発してしまわないことが保証さ +れる。もし内部インターフェースの変更が許されないとしたら、このよう +にセキュリティ問題を修正し、将来再発しないことを保証することなど不 +可能なのだ。 + + +カーネルのインターフェースは時が経つにつれクリーンナップを受ける。 +誰も使っていないインターフェースは削除される。これにより、可能な限 +りカーネルが小さく保たれ、現役の全てのインターフェースが可能な限り +テストされることを保証しているのだ。（使われていないインターフェー +スの妥当性をテストすることは不可能と言っていいだろう） + + + +これから何をすべきか +----------------------- + +では、もしメインのカーネルツリーに含まれない Linux カーネルドライ +バがあったとして、あなたは、つまり開発者は何をするべきだろうか？全 +てのディストリビューションの全てのカーネルバージョン向けにバイナリ +のドライバを供給することは悪夢であり、カーネルインターフェースの変 +更を追いかけ続けることもまた過酷な仕事だ。 + + +答えは簡単。そのドライバをメインのカーネルツリーに入れてしまえばよ +い。（ここで言及しているのは、GPL に従って公開されるドライバのこと +だということに注意してほしい。あなたのコードがそれに該当しないなら +ば、さよなら。幸運を祈ります。ご自分で何とかしてください。Andrew +と Linus からのコメント＜Andrew と Linus のコメントへのリンクをこ +こに置く＞をどうぞ）ドライバがメインツリーに入れば、カーネルのイン +ターフェースが変更された場合、変更を行った開発者によってドライバも +修正されることになるだろう。あなたはほとんど労力を払うことなしに、 +常にビルド可能できちんと動作するドライバを手に入れることができる。 + + +ドライバをメインのカーネルツリーに入れると、非常に好ましい以下の効 +果がある。 + - ドライバの品質が向上する一方で、（元の開発者にとっての）メンテ + ナンスコストは下がる。 + - あなたのドライバに他の開発者が機能を追加してくれる。 + - 誰かがあなたのドライバにあるバグを見つけ、修正してくれる。 + - 誰かがあなたのドライバにある改善点を見つけてくれる。 + - 外部インターフェースが変更されドライバの更新が必要になった場合、 + 誰かがあなたの代わりに更新してくれる。 + - ドライバを入れてくれとディストロに頼まなくても、そのドライバは + 全ての Linux ディストリビューションに自動的に含まれてリリース + される。 + + +Linux では、他のどのオペレーティングシステムよりも数多くのデバイス +が「そのまま」使用できるようになった。また Linux は、どのオペレー +ティングシステムよりも数多くのプロセッサアーキテクチャ上でそれらの +デバイスを使用することができるようにもなった。このように、Linux の +開発モデルは実証されており、今後も間違いなく正しい方向へと進んでい +くだろう。:) + + + +------ + +この文書の初期の草稿に対し、Randy Dunlap, Andrew Morton, David +Brownell, Hanna Linder, Robert Love, Nishanth Aravamudan から査読 +と助言を頂きました。感謝申し上げます。 + diff --git a/Documentation/translations/ja_JP/stable_kernel_rules.txt b/Documentation/translations/ja_JP/stable_kernel_rules.txt new file mode 100644 index 000000000..f9249aecb --- /dev/null +++ b/Documentation/translations/ja_JP/stable_kernel_rules.txt @@ -0,0 +1,84 @@ +NOTE: +This is Japanese translated version of "Documentation/process/stable-kernel-rules.rst". +This one is maintained by Tsugikazu Shibata <tshibata@ab.jp.nec.com> +and JF Project team <www.linux.or.jp/JF>. +If you find difference with original file or problem in translation, +please contact maintainer of this file or JF project. + +Please also note that purpose of this file is easier to read for non +English natives and do no intended to fork. So, if you have any +comment or update of this file, please try to update Original(English) +file at first. + +================================== +これは、 +linux-2.6.29/Documentation/process/stable-kernel-rules.rst +の和訳です。 + +翻訳団体： JF プロジェクト < http://www.linux.or.jp/JF/ > +翻訳日： 2009/1/14 +翻訳者： Tsugikazu Shibata <tshibata at ab dot jp dot nec dot com> +校正者： 武井伸光さん、<takei at webmasters dot gr dot jp> + かねこさん (Seiji Kaneko) <skaneko at a2 dot mbn dot or dot jp> + 小林 雅典さん (Masanori Kobayasi) <zap03216 at nifty dot ne dot jp> + 野口さん (Kenji Noguchi) <tokyo246 at gmail dot com> + 神宮信太郎さん <jin at libjingu dot jp> +================================== + +ずっと知りたかった Linux 2.6 -stable リリースの全て + +"-stable" ツリーにどのような種類のパッチが受け入れられるか、どのような +ものが受け入れられないか、についての規則- + + - 明らかに正しく、テストされているものでなければならない。 + - 文脈(変更行の前後)を含めて 100 行より大きくてはいけない。 + - ただ一個のことだけを修正しているべき。 + - 皆を悩ませている本物のバグを修正しなければならない。("これはバグで + あるかもしれないが..." のようなものではない) + - ビルドエラー(CONFIG_BROKENになっているものを除く), oops, ハング、デー + タ破壊、現実のセキュリティ問題、その他 "ああ、これはダメだね"という + ようなものを修正しなければならない。短く言えば、重大な問題。 + - 新しい device ID とクオークも受け入れられる。 + - どのように競合状態が発生するかの説明も一緒に書かれていない限り、 + "理論的には競合状態になる"ようなものは不可。 + - いかなる些細な修正も含めることはできない。(スペルの修正、空白のクリー + ンアップなど) + - Documentation/process/submitting-patches.rst の規則に従ったものでなければならない。 + - パッチ自体か同等の修正が Linus のツリーに既に存在しなければならない。 + Linus のツリーでのコミットID を -stable へのパッチ投稿の際に引用す + ること。 + +-stable ツリーにパッチを送付する手続き- + + - 上記の規則に従っているかを確認した後に、stable@vger.kernel.org にパッチ + を送る。 + - 送信者はパッチがキューに受け付けられた際には ACK を、却下された場合 + には NAK を受け取る。この反応は開発者たちのスケジュールによって、数 + 日かかる場合がある。 + - もし受け取られたら、パッチは他の開発者たちと関連するサブシステムの + メンテナーによるレビューのために -stable キューに追加される。 + - パッチに stable@vger.kernel.org のアドレスが付加されているときには、それ + が Linus のツリーに入る時に自動的に stable チームに email される。 + - セキュリティパッチはこのエイリアス (stable@vger.kernel.org) に送られるべ + きではなく、代わりに security@kernel.org のアドレスに送られる。 + +レビューサイクル- + + - -stable メンテナがレビューサイクルを決めるとき、パッチはレビュー委 + 員会とパッチが影響する領域のメンテナ(提供者がその領域のメンテナで無 + い限り)に送られ、linux-kernel メーリングリストにCCされる。 + - レビュー委員会は 48時間の間に ACK か NAK を出す。 + - もしパッチが委員会のメンバから却下されるか、メンテナ達やメンバが気付 + かなかった問題が持ちあがり、linux-kernel メンバがパッチに異議を唱え + た場合には、パッチはキューから削除される。 + - レビューサイクルの最後に、ACK を受けたパッチは最新の -stable リリー + スに追加され、その後に新しい -stable リリースが行われる。 + - セキュリティパッチは、通常のレビューサイクルを通らず、セキュリティ + カーネルチームから直接 -stable ツリーに受け付けられる。 + この手続きの詳細については kernel security チームに問い合わせること。 + +レビュー委員会- + + - この委員会は、このタスクについて活動する多くのボランティアと、少数の + 非ボランティアのカーネル開発者達で構成されている。 + diff --git a/Documentation/translations/ko_KR/howto.rst b/Documentation/translations/ko_KR/howto.rst new file mode 100644 index 000000000..a8197e072 --- /dev/null +++ b/Documentation/translations/ko_KR/howto.rst @@ -0,0 +1,632 @@ +NOTE: +This is a version of Documentation/process/howto.rst translated into korean +This document is maintained by Minchan Kim <minchan@kernel.org> +If you find any difference between this document and the original file or +a problem with the translation, please contact the maintainer of this file. + +Please also note that the purpose of this file is to be easier to +read for non English (read: korean) speakers and is not intended as +a fork. So if you have any comments or updates for this file please +try to update the original English file first. + +---------------------------------- + +이 문서는 +Documentation/process/howto.rst +의 한글 번역입니다. + +역자： 김민찬 <minchan@kernel.org> +감수： 이제이미 <jamee.lee@samsung.com> + +---------------------------------- + + +어떻게 리눅스 커널 개발을 하는가 +================================ + +이 문서는 커널 개발에 있어 가장 중요한 문서이다. 이 문서는 +리눅스 커널 개발자가 되는 법과 리눅스 커널 개발 커뮤니티와 일하는 +법을 담고있다. 커널 프로그래밍의 기술적인 측면과 관련된 내용들은 +포함하지 않으려고 하였지만 올바른 길로 여러분을 안내하는 데는 도움이 +될 것이다. + +이 문서에서 오래된 것을 발견하면 문서의 아래쪽에 나열된 메인테이너에게 +패치를 보내달라. + + +소개 +---- + +자, 여러분은 리눅스 커널 개발자가 되는 법을 배우고 싶은가? 아니면 +상사로부터"이 장치를 위한 리눅스 드라이버를 작성하시오"라는 말을 +들었는가? 이 문서의 목적은 여러분이 겪게 될 과정과 커뮤니티와 협력하는 +법을 조언하여 여러분의 목적을 달성하기 위해 필요한 것 모두를 알려주기 +위함이다. + +커널은 대부분은 C로 작성되어 있고 몇몇 아키텍쳐의 의존적인 부분은 +어셈블리로 작성되어 있다. 커널 개발을 위해 C를 잘 이해하고 있어야 한다. +여러분이 특정 아키텍쳐의 low-level 개발을 할 것이 아니라면 +어셈블리(특정 아키텍쳐)는 잘 알아야 할 필요는 없다. +다음의 참고서적들은 기본에 충실한 C 교육이나 수년간의 경험에 견주지는 +못하지만 적어도 참고 용도로는 좋을 것이다 + + - "The C Programming Language" by Kernighan and Ritchie [Prentice Hall] + - "Practical C Programming" by Steve Oualline [O'Reilly] + - "C: A Reference Manual" by Harbison and Steele [Prentice Hall] + +커널은 GNU C와 GNU 툴체인을 사용하여 작성되었다. 이 툴들은 ISO C89 표준을 +따르는 반면 표준에 있지 않은 많은 확장기능도 가지고 있다. 커널은 표준 C +라이브러리와는 관계없이 freestanding C 환경이어서 C 표준의 일부는 +지원되지 않는다. 임의의 long long 나누기나 floating point는 지원되지 않는다. +때론 이런 이유로 커널이 그런 확장 기능을 가진 툴체인을 가지고 만들어졌다는 +것이 이해하기 어려울 수도 있고 게다가 불행하게도 그런 것을 정확하게 설명하는 +어떤 참고문서도 있지 않다. 정보를 얻기 위해서는 gcc info (`info gcc`)페이지를 +살펴보라. + +여러분은 기존의 개발 커뮤니티와 협력하는 법을 배우려고 하고 있다는 것을 +기억하라. 코딩, 스타일, 함수에 관한 훌륭한 표준을 가진 사람들이 모인 +다양한 그룹이 있다. 이 표준들은 오랜동안 크고 지역적으로 분산된 팀들에 +의해 가장 좋은 방법으로 일하기 위하여 찾은 것을 기초로 만들어져 왔다. +그 표준들은 문서화가 잘 되어있기 때문에 가능한한 미리 많은 표준들에 +관하여 배우려고 시도하라. 다른 사람들은 여러분이나 여러분의 회사가 +일하는 방식에 적응하는 것을 원하지는 않는다. + + +법적 문제 +--------- + +리눅스 커널 소스 코드는 GPL로 배포(release)되었다. 소스트리의 메인 +디렉토리에 있는 라이센스에 관하여 상세하게 쓰여 있는 COPYING이라는 +파일을 봐라. 여러분이 라이센스에 관한 더 깊은 문제를 가지고 있다면 +리눅스 커널 메일링 리스트에 묻지말고 변호사와 연락하라. 메일링 +리스트들에 있는 사람들은 변호사가 아니기 때문에 법적 문제에 관하여 +그들의 말에 의지해서는 안된다. + +GPL에 관한 잦은 질문들과 답변들은 다음을 참조하라. + + https://www.gnu.org/licenses/gpl-faq.html + + +문서 +---- + +리눅스 커널 소스 트리는 커널 커뮤니티와 협력하는 법을 배우기위해 훌륭한 +다양한 문서들을 가지고 있다. 새로운 기능들이 커널에 들어가게 될 때, +그 기능을 어떻게 사용하는지에 관한 설명을 위하여 새로운 문서 파일을 +추가하는 것을 권장한다. 커널이 유저스페이스로 노출하는 인터페이스를 +변경하게 되면 변경을 설명하는 메뉴얼 페이지들에 대한 패치나 정보를 +mtk.manpages@gmail.com의 메인테이너에게 보낼 것을 권장한다. + +다음은 커널 소스 트리에 있는 읽어야 할 파일들의 리스트이다. + + README + 이 파일은 리눅스 커널에 관하여 간단한 배경 설명과 커널을 설정하고 + 빌드하기 위해 필요한 것을 설명한다. 커널에 입문하는 사람들은 여기서 + 시작해야 한다. + + :ref:`Documentation/process/changes.rst <changes>` + 이 파일은 커널을 성공적으로 빌드하고 실행시키기 위해 필요한 다양한 + 소프트웨어 패키지들의 최소 버젼을 나열한다. + + :ref:`Documentation/process/coding-style.rst <codingstyle>` + 이 문서는 리눅스 커널 코딩 스타일과 그렇게 한 몇몇 이유를 설명한다. + 모든 새로운 코드는 이 문서에 가이드라인들을 따라야 한다. 대부분의 + 메인테이너들은 이 규칙을 따르는 패치들만을 받아들일 것이고 많은 사람들이 + 그 패치가 올바른 스타일일 경우만 코드를 검토할 것이다. + + :ref:`Documentation/process/submitting-patches.rst <submittingpatches>` 와 :ref:`Documentation/process/submitting-drivers.rst <submittingdrivers>` + 이 파일들은 성공적으로 패치를 만들고 보내는 법을 다음의 내용들로 + 굉장히 상세히 설명하고 있다(그러나 다음으로 한정되진 않는다). + + - Email 내용들 + - Email 양식 + - 그것을 누구에게 보낼지 + + 이러한 규칙들을 따르는 것이 성공(역자주: 패치가 받아들여 지는 것)을 + 보장하진 않는다(왜냐하면 모든 패치들은 내용과 스타일에 관하여 + 면밀히 검토되기 때문이다). 그러나 규칙을 따르지 않는다면 거의 + 성공하지도 못할 것이다. + + 올바른 패치들을 만드는 법에 관한 훌륭한 다른 문서들이 있다. + + "The Perfect Patch" + https://www.ozlabs.org/~akpm/stuff/tpp.txt + + "Linux kernel patch submission format" + http://linux.yyz.us/patch-format.html + + :ref:`Documentation/process/stable-api-nonsense.rst <stable_api_nonsense>` + 이 문서는 의도적으로 커널이 불변하는 API를 갖지 않도록 결정한 + 이유를 설명하며 다음과 같은 것들을 포함한다. + + - 서브시스템 shim-layer(호환성을 위해?) + - 운영체제들간의 드라이버 이식성 + - 커널 소스 트리내에 빠른 변화를 늦추는 것(또는 빠른 변화를 막는 것) + + 이 문서는 리눅스 개발 철학을 이해하는데 필수적이며 다른 운영체제에서 + 리눅스로 전향하는 사람들에게는 매우 중요하다. + + + :ref:`Documentation/admin-guide/security-bugs.rst <securitybugs>` + 여러분들이 리눅스 커널의 보안 문제를 발견했다고 생각한다면 이 문서에 + 나온 단계에 따라서 커널 개발자들에게 알리고 그 문제를 해결할 수 있도록 + 도와 달라. + + :ref:`Documentation/process/management-style.rst <managementstyle>` + 이 문서는 리눅스 커널 메인테이너들이 그들의 방법론에 녹아 있는 + 정신을 어떻게 공유하고 운영하는지를 설명한다. 이것은 커널 개발에 입문하는 + 모든 사람들(또는 커널 개발에 작은 호기심이라도 있는 사람들)이 + 읽어야 할 중요한 문서이다. 왜냐하면 이 문서는 커널 메인테이너들의 + 독특한 행동에 관하여 흔히 있는 오해들과 혼란들을 해소하고 있기 + 때문이다. + + :ref:`Documentation/process/stable-kernel-rules.rst <stable_kernel_rules>` + 이 문서는 안정적인 커널 배포가 이루어지는 규칙을 설명하고 있으며 + 여러분들이 이러한 배포들 중 하나에 변경을 하길 원한다면 + 무엇을 해야 하는지를 설명한다. + + :ref:`Documentation/process/kernel-docs.rst <kernel_docs>` + 커널 개발에 관계된 외부 문서의 리스트이다. 커널 내의 포함된 문서들 + 중에 여러분이 찾고 싶은 문서를 발견하지 못할 경우 이 리스트를 + 살펴보라. + + :ref:`Documentation/process/applying-patches.rst <applying_patches>` + 패치가 무엇이며 그것을 커널의 다른 개발 브랜치들에 어떻게 + 적용하는지에 관하여 자세히 설명하고 있는 좋은 입문서이다. + +커널은 소스 코드 그 자체에서 또는 이것과 같은 ReStructuredText 마크업 (ReST) 을 +통해 자동적으로 만들어질 수 있는 많은 문서들을 가지고 있다. 이것은 커널 내의 +API에 대한 모든 설명, 그리고 락킹을 올바르게 처리하는 법에 관한 규칙을 포함하고 +있다. + +모든 그런 문서들은 커널 소스 디렉토리에서 다음 커맨드를 실행하는 것을 통해 PDF +나 HTML 의 형태로 만들어질 수 있다:: + + make pdfdocs + make htmldocs + +ReST 마크업을 사용하는 문서들은 Documentation/output 에 생성된다. 해당 +문서들은 다음의 커맨드를 사용하면 LaTeX 이나 ePub 로도 만들어질 수 있다:: + + make latexdocs + make epubdocs + +커널 개발자가 되는 것 +--------------------- + +여러분이 리눅스 커널 개발에 관하여 아무것도 모른다면 Linux KernelNewbies +프로젝트를 봐야 한다. + + https://kernelnewbies.org + +그곳은 거의 모든 종류의 기본적인 커널 개발 질문들(질문하기 전에 먼저 +아카이브를 찾아봐라. 과거에 이미 답변되었을 수도 있다)을 할 수 있는 도움이 +될만한 메일링 리스트가 있다. 또한 실시간으로 질문 할 수 있는 IRC 채널도 +가지고 있으며 리눅스 커널 개발을 배우는 데 유용한 문서들을 보유하고 있다. + +웹사이트는 코드구성, 서브시스템들, 그리고 현재 프로젝트들 +(트리 내, 외부에 존재하는)에 관한 기본적인 정보들을 가지고 있다. 또한 +그곳은 커널 컴파일이나 패치를 하는 법과 같은 기본적인 것들을 설명한다. + +여러분이 어디서 시작해야 할진 모르지만 커널 개발 커뮤니티에 참여할 수 +있는 일들을 찾길 원한다면 리눅스 커널 Janitor 프로젝트를 살펴봐라. + + https://kernelnewbies.org/KernelJanitors + +그곳은 시작하기에 훌륭한 장소이다. 그곳은 리눅스 커널 소스 트리내에 +간단히 정리되고 수정될 수 있는 문제들에 관하여 설명한다. 여러분은 이 +프로젝트를 대표하는 개발자들과 일하면서 자신의 패치를 리눅스 커널 트리에 +반영하기 위한 기본적인 것들을 배우게 될것이며 여러분이 아직 아이디어를 +가지고 있지 않다면 다음에 무엇을 해야할지에 관한 방향을 배울 수 있을 +것이다. + +여러분들이 이미 커널 트리에 반영하길 원하는 코드 묶음을 가지고 있지만 +올바른 포맷으로 포장하는데 도움이 필요하다면 그러한 문제를 돕기 위해 +만들어진 kernel-mentors 프로젝트가 있다. 그곳은 메일링 리스트이며 +다음에서 참조할 수 있다. + + https://selenic.com/mailman/listinfo/kernel-mentors + +리눅스 커널 코드에 실제 변경을 하기 전에 반드시 그 코드가 어떻게 +동작하는지 이해하고 있어야 한다. 코드를 분석하기 위하여 특정한 툴의 +도움을 빌려서라도 코드를 직접 읽는 것보다 좋은 것은 없다(대부분의 +자잘한 부분들은 잘 코멘트되어 있다). 그런 툴들 중에 특히 추천할만한 +것은 Linux Cross-Reference project이며 그것은 자기 참조 방식이며 +소스코드를 인덱스된 웹 페이지들의 형태로 보여준다. 최신의 멋진 커널 +코드 저장소는 다음을 통하여 참조할 수 있다. + + http://lxr.free-electrons.com/ + + +개발 프로세스 +------------- + +리눅스 커널 개발 프로세스는 현재 몇몇 다른 메인 커널 "브랜치들"과 +서브시스템에 특화된 커널 브랜치들로 구성된다. 몇몇 다른 메인 +브랜치들은 다음과 같다. + + - main 4.x 커널 트리 + - 4.x.y - 안정된 커널 트리 + - 4.x -git 커널 패치들 + - 서브시스템을 위한 커널 트리들과 패치들 + - 4.x - 통합 테스트를 위한 next 커널 트리 + +4.x 커널 트리 +~~~~~~~~~~~~~ + +4.x 커널들은 Linus Torvalds가 관리하며 https://kernel.org 의 +pub/linux/kernel/v4.x/ 디렉토리에서 참조될 수 있다.개발 프로세스는 다음과 같다. + + - 새로운 커널이 배포되자마자 2주의 시간이 주어진다. 이 기간동은 + 메인테이너들은 큰 diff들을 Linus에게 제출할 수 있다. 대개 이 패치들은 + 몇 주 동안 -next 커널내에 이미 있었던 것들이다. 큰 변경들을 제출하는 데 + 선호되는 방법은 git(커널의 소스 관리 툴, 더 많은 정보들은 + https://git-scm.com/ 에서 참조할 수 있다)를 사용하는 것이지만 순수한 + 패치파일의 형식으로 보내는 것도 무관하다. + - 2주 후에 -rc1 커널이 릴리즈되며 여기서부터의 주안점은 새로운 커널을 + 가능한한 안정되게 하는 것이다. 이 시점에서의 대부분의 패치들은 + 회귀(역자주: 이전에는 존재하지 않았지만 새로운 기능추가나 변경으로 인해 + 생겨난 버그)를 고쳐야 한다. 이전부터 존재한 버그는 회귀가 아니므로, 그런 + 버그에 대한 수정사항은 중요한 경우에만 보내져야 한다. 완전히 새로운 + 드라이버(혹은 파일시스템)는 -rc1 이후에만 받아들여진다는 것을 기억해라. + 왜냐하면 변경이 자체내에서만 발생하고 추가된 코드가 드라이버 외부의 다른 + 부분에는 영향을 주지 않으므로 그런 변경은 회귀를 일으킬 만한 위험을 가지고 + 있지 않기 때문이다. -rc1이 배포된 이후에 git를 사용하여 패치들을 Linus에게 + 보낼수 있지만 패치들은 공식적인 메일링 리스트로 보내서 검토를 받을 필요가 + 있다. + - 새로운 -rc는 Linus가 현재 git tree가 테스트 하기에 충분히 안정된 상태에 + 있다고 판단될 때마다 배포된다. 목표는 새로운 -rc 커널을 매주 배포하는 + 것이다. + - 이러한 프로세스는 커널이 "준비(ready)"되었다고 여겨질때까지 계속된다. + 프로세스는 대체로 6주간 지속된다. + +커널 배포에 있어서 언급할만한 가치가 있는 리눅스 커널 메일링 리스트의 +Andrew Morton의 글이 있다. + + *"커널이 언제 배포될지는 아무도 모른다. 왜냐하면 배포는 알려진 + 버그의 상황에 따라 배포되는 것이지 미리정해 놓은 시간에 따라 + 배포되는 것은 아니기 때문이다."* + +4.x.y - 안정 커널 트리 +~~~~~~~~~~~~~~~~~~~~~~ + +3 자리 숫자로 이루어진 버젼의 커널들은 -stable 커널들이다. 그것들은 4.x +커널에서 발견된 큰 회귀들이나 보안 문제들 중 비교적 작고 중요한 수정들을 +포함한다. + +이것은 가장 최근의 안정적인 커널을 원하는 사용자에게 추천되는 브랜치이며, +개발/실험적 버젼을 테스트하는 것을 돕고자 하는 사용자들과는 별로 관련이 없다. + +어떤 4.x.y 커널도 사용할 수 없다면 그때는 가장 높은 숫자의 4.x +커널이 현재의 안정 커널이다. + +4.x.y는 "stable" 팀<stable@vger.kernel.org>에 의해 관리되며 거의 매번 격주로 +배포된다. + +커널 트리 문서들 내에 Documentation/process/stable-kernel-rules.rst 파일은 어떤 +종류의 변경들이 -stable 트리로 들어왔는지와 배포 프로세스가 어떻게 +진행되는지를 설명한다. + +4.x -git 패치들 +~~~~~~~~~~~~~~~ + +git 저장소(그러므로 -git이라는 이름이 붙음)에는 날마다 관리되는 Linus의 +커널 트리의 snapshot 들이 있다. 이 패치들은 일반적으로 날마다 배포되며 +Linus의 트리의 현재 상태를 나타낸다. 이 패치들은 정상적인지 조금도 +살펴보지 않고 자동적으로 생성된 것이므로 -rc 커널들 보다도 더 실험적이다. + +서브시스템 커널 트리들과 패치들 +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +다양한 커널 서브시스템의 메인테이너들 --- 그리고 많은 커널 서브시스템 개발자들 +--- 은 그들의 현재 개발 상태를 소스 저장소로 노출한다. 이를 통해 다른 사람들도 +커널의 다른 영역에 어떤 변화가 이루어지고 있는지 알 수 있다. 급속히 개발이 +진행되는 영역이 있고 그렇지 않은 영역이 있으므로, 개발자는 다른 개발자가 제출한 +수정 사항과 자신의 수정사항의 충돌이나 동일한 일을 동시에 두사람이 따로 +진행하는 사태를 방지하기 위해 급속히 개발이 진행되고 있는 영역에 작업의 +베이스를 맞춰줄 것이 요구된다. + +대부분의 이러한 저장소는 git 트리지만, git이 아닌 SCM으로 관리되거나, quilt +시리즈로 제공되는 패치들도 존재한다. 이러한 서브시스템 저장소들은 MAINTAINERS +파일에 나열되어 있다. 대부분은 https://git.kernel.org 에서 볼 수 있다. + +제안된 패치는 서브시스템 트리에 커밋되기 전에 메일링 리스트를 통해 +리뷰된다(아래의 관련 섹션을 참고하기 바란다). 일부 커널 서브시스템의 경우, 이 +리뷰 프로세스는 patchwork라는 도구를 통해 추적된다. patchwork은 등록된 패치와 +패치에 대한 코멘트, 패치의 버전을 볼 수 있는 웹 인터페이스를 제공하고, +메인테이너는 패치를 리뷰 중, 리뷰 통과, 또는 반려됨으로 표시할 수 있다. +대부분의 이러한 patchwork 사이트는 https://patchwork.kernel.org/ 또는 +http://patchwork.ozlabs.org/ 에 나열되어 있다. + +4.x - 통합 테스트를 위한 next 커널 트리 +--------------------------------------- +서브시스템 트리들의 변경사항들은 mainline 4.x 트리로 들어오기 전에 통합 +테스트를 거쳐야 한다. 이런 목적으로, 모든 서브시스템 트리의 변경사항을 거의 +매일 받아가는 특수한 테스트 저장소가 존재한다: + + https://git.kernel.org/?p=linux/kernel/git/sfr/linux-next.git + +이런 식으로, -next 커널을 통해 다음 머지 기간에 메인라인 커널에 어떤 변경이 +가해질 것인지 간략히 알 수 있다. 모험심 강한 테스터라면 -next 커널에서 테스트를 +수행하는 것도 좋을 것이다. + + +버그 보고 +--------- + +https://bugzilla.kernel.org 는 리눅스 커널 개발자들이 커널의 버그를 추적하는 +곳이다. 사용자들은 발견한 모든 버그들을 보고하기 위하여 이 툴을 사용할 것을 +권장한다. kernel bugzilla를 사용하는 자세한 방법은 다음을 참조하라. + + https://bugzilla.kernel.org/page.cgi?id=faq.html + +메인 커널 소스 디렉토리에 있는 admin-guide/reporting-bugs.rst 파일은 커널 버그라고 생각되는 +것을 보고하는 방법에 관한 좋은 템플릿이며 문제를 추적하기 위해서 커널 +개발자들이 필요로 하는 정보가 무엇들인지를 상세히 설명하고 있다. + + +버그 리포트들의 관리 +-------------------- + +여러분의 해킹 기술을 연습하는 가장 좋은 방법 중의 하는 다른 사람들이 +보고한 버그들을 수정하는 것이다. 여러분은 커널을 더욱 안정화시키는데 +도움을 줄 뿐만이 아니라 실제있는 문제들을 수정하는 법을 배우게 되고 +그와 함께 여러분들의 기술은 향상될 것이며 다른 개발자들이 여러분의 +존재에 대해 알게 될 것이다. 버그를 수정하는 것은 개발자들 사이에서 +점수를 얻을 수 있는 가장 좋은 방법중의 하나이다. 왜냐하면 많은 사람들은 +다른 사람들의 버그들을 수정하기 위하여 시간을 낭비하지 않기 때문이다. + +이미 보고된 버그 리포트들을 가지고 작업하기 위해서 https://bugzilla.kernel.org +를 참조하라. 여러분이 앞으로 생겨날 버그 리포트들의 조언자가 되길 원한다면 +bugme-new 메일링 리스트나(새로운 버그 리포트들만이 이곳에서 메일로 전해진다) +bugme-janitor 메일링 리스트(bugzilla에 모든 변화들이 여기서 메일로 전해진다) +에 등록하면 된다. + + https://lists.linux-foundation.org/mailman/listinfo/bugme-new + + https://lists.linux-foundation.org/mailman/listinfo/bugme-janitors + + + +메일링 리스트들 +--------------- + +위의 몇몇 문서들이 설명하였지만 핵심 커널 개발자들의 대다수는 +리눅스 커널 메일링 리스트에 참여하고 있다. 리스트에 등록하고 해지하는 +방법에 관한 자세한 사항은 다음에서 참조할 수 있다. + + http://vger.kernel.org/vger-lists.html#linux-kernel + +웹상의 많은 다른 곳에도 메일링 리스트의 아카이브들이 있다. +이러한 아카이브들을 찾으려면 검색 엔진을 사용하라. 예를 들어: + + http://dir.gmane.org/gmane.linux.kernel + +여러분이 새로운 문제에 관해 리스트에 올리기 전에 말하고 싶은 주제에 관한 +것을 아카이브에서 먼저 찾아보기를 강력히 권장한다. 이미 상세하게 토론된 많은 +것들이 메일링 리스트의 아카이브에 기록되어 있다. + +각각의 커널 서브시스템들의 대부분은 자신들의 개발에 관한 노력들로 이루어진 +분리된 메일링 리스트를 따로 가지고 있다. 다른 그룹들이 무슨 리스트를 가지고 +있는지는 MAINTAINERS 파일을 참조하라. + +많은 리스트들은 kernel.org에서 호스트되고 있다. 그 정보들은 다음에서 참조될 수 있다. + + http://vger.kernel.org/vger-lists.html + +리스트들을 사용할 때는 올바른 예절을 따를 것을 유념해라. +대단하진 않지만 다음 URL은 리스트(혹은 모든 리스트)와 대화하는 몇몇 간단한 +가이드라인을 가지고 있다. + + http://www.albion.com/netiquette/ + +여러 사람들이 여러분의 메일에 응답한다면 CC: 즉 수신 리스트는 꽤 커지게 +될 것이다. 아무 이유없이 CC에서 어떤 사람도 제거하거나 리스트 주소로만 +회신하지 마라. 메일을 보낸 사람으로서 하나를 받고 리스트로부터 또 +하나를 받아 두번 받는 것에 익숙하여 있으니 mail-header를 조작하려고 하지 +말아라. 사람들은 그런 것을 좋아하지 않을 것이다. + +여러분의 회신의 문맥을 원래대로 유지해야 한다. 여러분들의 회신의 윗부분에 +"John 커널해커는 작성했다...."를 유지하며 여러분들의 의견을 그 메일의 윗부분에 +작성하지 말고 각 인용한 단락들 사이에 넣어라. + +여러분들이 패치들을 메일에 넣는다면 그것들은 Documentation/process/submitting-patches.rst에 +나와있는데로 명백히(plain) 읽을 수 있는 텍스트여야 한다. 커널 개발자들은 +첨부파일이나 압축된 패치들을 원하지 않는다. 그들은 여러분들의 패치의 +각 라인 단위로 코멘트를 하길 원하며 압축하거나 첨부하지 않고 보내는 것이 +그렇게 할 수 있는 유일한 방법이다. 여러분들이 사용하는 메일 프로그램이 +스페이스나 탭 문자들을 조작하지 않는지 확인하라. 가장 좋은 첫 테스트는 +메일을 자신에게 보내보고 스스로 그 패치를 적용해보라. 그것이 동작하지 +않는다면 여러분의 메일 프로그램을 고치던가 제대로 동작하는 프로그램으로 +바꾸어라. + +무엇보다도 메일링 리스트의 다른 구독자들에게 보여주려 한다는 것을 기억하라. + + +커뮤니티와 협력하는 법 +---------------------- + +커널 커뮤니티의 목적은 가능한한 가장 좋은 커널을 제공하는 것이다. 여러분이 +받아들여질 패치를 제출하게 되면 그 패치의 기술적인 이점으로 검토될 것이다. +그럼 여러분들은 무엇을 기대하고 있어야 하는가? + + - 비판 + - 의견 + - 변경을 위한 요구 + - 당위성을 위한 요구 + - 침묵 + +기억하라. 이것들은 여러분의 패치가 커널로 들어가기 위한 과정이다. 여러분의 +패치들은 비판과 다른 의견을 받을 수 있고 그것들을 기술적인 레벨로 평가하고 +재작업하거나 또는 왜 수정하면 안되는지에 관하여 명료하고 간결한 이유를 +말할 수 있어야 한다. 여러분이 제출한 것에 어떤 응답도 있지 않다면 몇 일을 +기다려보고 다시 시도해라. 때론 너무 많은 메일들 속에 묻혀버리기도 한다. + +여러분은 무엇을 해서는 안되는가? + + - 여러분의 패치가 아무 질문 없이 받아들여지기를 기대하는 것 + - 방어적이 되는 것 + - 의견을 무시하는 것 + - 요청된 변경을 하지 않고 패치를 다시 제출하는 것 + +가능한한 가장 좋은 기술적인 해답을 찾고 있는 커뮤니티에서는 항상 +어떤 패치가 얼마나 좋은지에 관하여 다른 의견들이 있을 수 있다. 여러분은 +협조적이어야 하고 기꺼이 여러분의 생각을 커널 내에 맞추어야 한다. 아니면 +적어도 여러분의 것이 가치있다는 것을 증명하여야 한다. 잘못된 것도 여러분이 +올바른 방향의 해결책으로 이끌어갈 의지가 있다면 받아들여질 것이라는 점을 +기억하라. + +여러분의 첫 패치에 여러분이 수정해야하는 십여개 정도의 회신이 오는 +경우도 흔하다. 이것은 여러분의 패치가 받아들여지지 않을 것이라는 것을 +의미하는 것이 아니고 개인적으로 여러분에게 감정이 있어서 그러는 것도 +아니다. 간단히 여러분의 패치에 제기된 문제들을 수정하고 그것을 다시 +보내라. + + +커널 커뮤니티와 기업 조직간의 차이점 +------------------------------------ +커널 커뮤니티는 가장 전통적인 회사의 개발 환경과는 다르다. 여기에 여러분들의 +문제를 피하기 위한 목록이 있다. + + 여러분들이 제안한 변경들에 관하여 말할 때 좋은 것들 : + + - "이것은 여러 문제들을 해결합니다." + - "이것은 2000 라인의 코드를 줄입니다." + - "이것은 내가 말하려는 것에 관해 설명하는 패치입니다." + - "나는 5개의 다른 아키텍쳐에서 그것을 테스트 했으므로..." + - "여기에 일련의 작은 패치들이 있으므로..." + - "이것은 일반적인 머신에서 성능을 향상함으로..." + + 여러분들이 말할 때 피해야 할 좋지 않은 것들 : + + - "우리는 그것을 AIX/ptx/Solaris에서 이러한 방법으로 했다. 그러므로 그것은 좋은 것임에 틀림없다..." + - "나는 20년동안 이것을 해왔다. 그러므로..." + - "이것은 돈을 벌기위해 나의 회사가 필요로 하는 것이다." + - "이것은 우리의 엔터프라이즈 상품 라인을 위한 것이다." + - "여기에 나의 생각을 말하고 있는 1000 페이지 설계 문서가 있다." + - "나는 6달동안 이것을 했으니..." + - "여기에 5000 라인 짜리 패치가 있으니..." + - "나는 현재 뒤죽박죽인 것을 재작성했다. 그리고 여기에..." + - "나는 마감시한을 가지고 있으므로 이 패치는 지금 적용될 필요가 있다." + +커널 커뮤니티가 전통적인 소프트웨어 엔지니어링 개발 환경들과 +또 다른 점은 얼굴을 보지 않고 일한다는 점이다. 이메일과 irc를 대화의 +주요수단으로 사용하는 것의 한가지 장점은 성별이나 인종의 차별이 +없다는 것이다. 리눅스 커널의 작업 환경에서는 단지 이메일 주소만 +알수 있기 때문에 여성과 소수 민족들도 모두 받아들여진다. 국제적으로 +일하게 되는 측면은 사람의 이름에 근거하여 성별을 추측할 수 없게 +하기때문에 차별을 없애는 데 도움을 준다. Andrea라는 이름을 가진 남자와 +Pat이라는 이름을 가진 여자가 있을 수도 있는 것이다. 리눅스 커널에서 +작업하며 생각을 표현해왔던 대부분의 여성들은 긍정적인 경험을 가지고 +있다. + +언어 장벽은 영어에 익숙하지 않은 몇몇 사람들에게 문제가 될 수도 있다. +언어의 훌륭한 구사는 메일링 리스트에서 올바르게 자신의 생각을 +표현하기 위하여 필요하다. 그래서 여러분은 이메일을 보내기 전에 +영어를 올바르게 사용하고 있는지를 체크하는 것이 바람직하다. + + +여러분의 변경을 나누어라 +------------------------ + +리눅스 커널 커뮤니티는 한꺼번에 굉장히 큰 코드의 묶음(chunk)을 쉽게 +받아들이지 않는다. 변경은 적절하게 소개되고, 검토되고, 각각의 +부분으로 작게 나누어져야 한다. 이것은 회사에서 하는 것과는 정확히 +반대되는 것이다. 여러분들의 제안은 개발 초기에 일찍이 소개되야 한다. +그래서 여러분들은 자신이 하고 있는 것에 관하여 피드백을 받을 수 있게 +된다. 커뮤니티가 여러분들이 커뮤니티와 함께 일하고 있다는 것을 +느끼도록 만들고 커뮤니티가 여러분의 기능을 위한 쓰레기 장으로써 +사용되지 않고 있다는 것을 느끼게 하자. 그러나 메일링 리스트에 한번에 +50개의 이메일을 보내지는 말아라. 여러분들의 일련의 패치들은 항상 +더 작아야 한다. + +패치를 나누는 이유는 다음과 같다. + +1) 작은 패치들은 여러분의 패치들이 적용될 수 있는 확률을 높여준다. + 왜냐하면 다른 사람들은 정확성을 검증하기 위하여 많은 시간과 노력을 + 들이기를 원하지 않는다. 5줄의 패치는 메인테이너가 거의 몇 초간 힐끗 + 보면 적용될 수 있다. 그러나 500 줄의 패치는 정확성을 검토하기 위하여 + 몇시간이 걸릴 수도 있다(걸리는 시간은 패치의 크기 혹은 다른 것에 + 비례하여 기하급수적으로 늘어난다). + + 패치를 작게 만드는 것은 무엇인가 잘못되었을 때 디버그하는 것을 + 쉽게 만든다. 즉, 그렇게 만드는 것은 매우 큰 패치를 적용한 후에 + 조사하는 것 보다 작은 패치를 적용한 후에 (그리고 몇몇의 것이 + 깨졌을 때) 하나씩 패치들을 제거해가며 디버그 하기 쉽도록 만들어 준다. + +2) 작은 패치들을 보내는 것뿐만 아니라 패치들을 제출하기전에 재작성하고 + 간단하게(혹은 간단한게 재배치하여) 하는 것도 중요하다. + +여기에 커널 개발자 Al Viro의 이야기가 있다. + + *"학생의 수학 숙제를 채점하는 선생님을 생각해보라. 선생님은 학생들이 + 답을 얻을때까지 겪은 시행착오를 보길 원하지 않는다. 선생님들은 + 간결하고 가장 뛰어난 답을 보길 원한다. 훌륭한 학생은 이것을 알고 + 마지막으로 답을 얻기 전 중간 과정들을 제출하진 않는다.* + + *커널 개발도 마찬가지이다. 메인테이너들과 검토하는 사람들은 문제를 + 풀어나가는 과정속에 숨겨진 과정을 보길 원하진 않는다. 그들은 + 간결하고 멋진 답을 보길 원한다."* + +커뮤니티와 협력하며 뛰어난 답을 찾는 것과 여러분들의 끝마치지 못한 작업들 +사이에 균형을 유지해야 하는 것은 어려울지도 모른다. 그러므로 프로세스의 +초반에 여러분의 작업을 향상시키기위한 피드백을 얻는 것 뿐만 아니라 +여러분들의 변경들을 작은 묶음으로 유지해서 심지어는 여러분의 작업의 +모든 부분이 지금은 포함될 준비가 되어있지 않지만 작은 부분은 벌써 +받아들여질 수 있도록 유지하는 것이 바람직하다. + +또한 완성되지 않았고 "나중에 수정될 것이다." 와 같은 것들을 포함하는 +패치들은 받아들여지지 않을 것이라는 점을 유념하라. + + +변경을 정당화해라 +----------------- + +여러분들의 나누어진 패치들을 리눅스 커뮤니티가 왜 반영해야 하는지를 +알도록 하는 것은 매우 중요하다. 새로운 기능들이 필요하고 유용하다는 +것은 반드시 그에 합당한 이유가 있어야 한다. + + +변경을 문서화해라 +----------------- + +여러분이 패치를 보내려 할때는 여러분이 무엇을 말하려고 하는지를 충분히 +생각하여 이메일을 작성해야 한다. 이 정보는 패치를 위한 ChangeLog가 될 +것이다. 그리고 항상 그 내용을 보길 원하는 모든 사람들을 위해 보존될 +것이다. 패치는 완벽하게 다음과 같은 내용들을 포함하여 설명해야 한다. + + - 변경이 왜 필요한지 + - 패치에 관한 전체 설계 접근(approach) + - 구현 상세들 + - 테스트 결과들 + +이것이 무엇인지 더 자세한 것을 알고 싶다면 다음 문서의 ChageLog 항을 봐라. + + "The Perfect Patch" + + http://www.ozlabs.org/~akpm/stuff/tpp.txt + + +이 모든 것을 하는 것은 매우 어려운 일이다. 완벽히 소화하는 데는 적어도 몇년이 +걸릴 수도 있다. 많은 인내와 결심이 필요한 계속되는 개선의 과정이다. 그러나 +가능한한 포기하지 말라. 많은 사람들은 이전부터 해왔던 것이고 그 사람들도 +정확하게 여러분들이 지금 서 있는 그 곳부터 시작했었다. + + + + +---------- + +"개발 프로세스"(https://lwn.net/Articles/94386/) 섹션을 +작성하는데 있어 참고할 문서를 사용하도록 허락해준 Paolo Ciarrocchi에게 +감사한다. 여러분들이 말해야 할 것과 말해서는 안되는 것의 목록 중 일부를 제공해준 +Randy Dunlap과 Gerrit Huizenga에게 감사한다. 또한 검토와 의견 그리고 +공헌을 아끼지 않은 Pat Mochel, Hanna Linder, Randy Dunlap, Kay Sievers, +Vojtech Pavlik, Jan Kara, Josh Boyer, Kees Cook, Andrew Morton, Andi Kleen, +Vadim Lobanov, Jesper Juhl, Adrian Bunk, Keri Harris, Frans Pop, +David A. Wheeler, Junio Hamano, Michael Kerrisk, and Alex Shepard에게도 감사를 전한다. +그들의 도움이 없었다면 이 문서는 존재하지 않았을 것이다. + + + +메인테이너: Greg Kroah-Hartman <greg@kroah.com> diff --git a/Documentation/translations/ko_KR/index.rst b/Documentation/translations/ko_KR/index.rst new file mode 100644 index 000000000..0b695345a --- /dev/null +++ b/Documentation/translations/ko_KR/index.rst @@ -0,0 +1,12 @@ +.. raw:: latex + + \renewcommand\thesection* + \renewcommand\thesubsection* + +Korean translations +=================== + +.. toctree:: + :maxdepth: 1 + + howto diff --git a/Documentation/translations/ko_KR/memory-barriers.txt b/Documentation/translations/ko_KR/memory-barriers.txt new file mode 100644 index 000000000..7f01fb1c1 --- /dev/null +++ b/Documentation/translations/ko_KR/memory-barriers.txt @@ -0,0 +1,3106 @@ +NOTE: +This is a version of Documentation/memory-barriers.txt translated into Korean. +This document is maintained by SeongJae Park <sj38.park@gmail.com>. +If you find any difference between this document and the original file or +a problem with the translation, please contact the maintainer of this file. + +Please also note that the purpose of this file is to be easier to +read for non English (read: Korean) speakers and is not intended as +a fork. So if you have any comments or updates for this file please +update the original English file first. The English version is +definitive, and readers should look there if they have any doubt. + +=================================== +이 문서는 +Documentation/memory-barriers.txt +의 한글 번역입니다. + +역자： 박성재 <sj38.park@gmail.com> +=================================== + + + ========================= + 리눅스 커널 메모리 배리어 + ========================= + +저자: David Howells <dhowells@redhat.com> + Paul E. McKenney <paulmck@linux.vnet.ibm.com> + Will Deacon <will.deacon@arm.com> + Peter Zijlstra <peterz@infradead.org> + +======== +면책조항 +======== + +이 문서는 명세서가 아닙니다; 이 문서는 완벽하지 않은데, 간결성을 위해 의도된 +부분도 있고, 의도하진 않았지만 사람에 의해 쓰였다보니 불완전한 부분도 있습니다. +이 문서는 리눅스에서 제공하는 다양한 메모리 배리어들을 사용하기 위한 +안내서입니다만, 뭔가 이상하다 싶으면 (그런게 많을 겁니다) 질문을 부탁드립니다. +일부 이상한 점들은 공식적인 메모리 일관성 모델과 tools/memory-model/ 에 있는 +관련 문서를 참고해서 해결될 수 있을 겁니다. 그러나, 이 메모리 모델조차도 그 +관리자들의 의견의 집합으로 봐야지, 절대 옳은 예언자로 신봉해선 안될 겁니다. + +다시 말하지만, 이 문서는 리눅스가 하드웨어에 기대하는 사항에 대한 명세서가 +아닙니다. + +이 문서의 목적은 두가지입니다: + + (1) 어떤 특정 배리어에 대해 기대할 수 있는 최소한의 기능을 명세하기 위해서, + 그리고 + + (2) 사용 가능한 배리어들에 대해 어떻게 사용해야 하는지에 대한 안내를 제공하기 + 위해서. + +어떤 아키텍쳐는 특정한 배리어들에 대해서는 여기서 이야기하는 최소한의 +요구사항들보다 많은 기능을 제공할 수도 있습니다만, 여기서 이야기하는 +요구사항들을 충족하지 않는 아키텍쳐가 있다면 그 아키텍쳐가 잘못된 것이란 점을 +알아두시기 바랍니다. + +또한, 특정 아키텍쳐에서 일부 배리어는 해당 아키텍쳐의 특수한 동작 방식으로 인해 +해당 배리어의 명시적 사용이 불필요해서 no-op 이 될수도 있음을 알아두시기 +바랍니다. + +역자: 본 번역 역시 완벽하지 않은데, 이 역시 부분적으로는 의도된 것이기도 +합니다. 여타 기술 문서들이 그렇듯 완벽한 이해를 위해서는 번역문과 원문을 함께 +읽으시되 번역문을 하나의 가이드로 활용하시길 추천드리며, 발견되는 오역 등에 +대해서는 언제든 의견을 부탁드립니다. 과한 번역으로 인한 오해를 최소화하기 위해 +애매한 부분이 있을 경우에는 어색함이 있더라도 원래의 용어를 차용합니다. + + +===== +목차: +===== + + (*) 추상 메모리 액세스 모델. + + - 디바이스 오퍼레이션. + - 보장사항. + + (*) 메모리 배리어란 무엇인가? + + - 메모리 배리어의 종류. + - 메모리 배리어에 대해 가정해선 안될 것. + - 데이터 의존성 배리어 (역사적). + - 컨트롤 의존성. + - SMP 배리어 짝맞추기. + - 메모리 배리어 시퀀스의 예. + - 읽기 메모리 배리어 vs 로드 예측. + - Multicopy 원자성. + + (*) 명시적 커널 배리어. + + - 컴파일러 배리어. + - CPU 메모리 배리어. + - MMIO 쓰기 배리어. + + (*) 암묵적 커널 메모리 배리어. + + - 락 Acquisition 함수. + - 인터럽트 비활성화 함수. + - 슬립과 웨이크업 함수. + - 그외의 함수들. + + (*) CPU 간 ACQUIRING 배리어의 효과. + + - Acquire vs 메모리 액세스. + - Acquire vs I/O 액세스. + + (*) 메모리 배리어가 필요한 곳 + + - 프로세서간 상호 작용. + - 어토믹 오퍼레이션. + - 디바이스 액세스. + - 인터럽트. + + (*) 커널 I/O 배리어의 효과. + + (*) 가정되는 가장 완화된 실행 순서 모델. + + (*) CPU 캐시의 영향. + + - 캐시 일관성. + - 캐시 일관성 vs DMA. + - 캐시 일관성 vs MMIO. + + (*) CPU 들이 저지르는 일들. + + - 그리고, Alpha 가 있다. + - 가상 머신 게스트. + + (*) 사용 예. + + - 순환식 버퍼. + + (*) 참고 문헌. + + +======================= +추상 메모리 액세스 모델 +======================= + +다음과 같이 추상화된 시스템 모델을 생각해 봅시다: + + : : + : : + : : + +-------+ : +--------+ : +-------+ + | | : | | : | | + | | : | | : | | + | CPU 1 |<----->| Memory |<----->| CPU 2 | + | | : | | : | | + | | : | | : | | + +-------+ : +--------+ : +-------+ + ^ : ^ : ^ + | : | : | + | : | : | + | : v : | + | : +--------+ : | + | : | | : | + | : | | : | + +---------->| Device |<----------+ + : | | : + : | | : + : +--------+ : + : : + +프로그램은 여러 메모리 액세스 오퍼레이션을 발생시키고, 각각의 CPU 는 그런 +프로그램들을 실행합니다. 추상화된 CPU 모델에서 메모리 오퍼레이션들의 순서는 +매우 완화되어 있고, CPU 는 프로그램이 인과관계를 어기지 않는 상태로 관리된다고 +보일 수만 있다면 메모리 오퍼레이션을 자신이 원하는 어떤 순서대로든 재배치해 +동작시킬 수 있습니다. 비슷하게, 컴파일러 또한 프로그램의 정상적 동작을 해치지 +않는 한도 내에서는 어떤 순서로든 자신이 원하는 대로 인스트럭션을 재배치 할 수 +있습니다. + +따라서 위의 다이어그램에서 한 CPU가 동작시키는 메모리 오퍼레이션이 만들어내는 +변화는 해당 오퍼레이션이 CPU 와 시스템의 다른 부분들 사이의 인터페이스(점선)를 +지나가면서 시스템의 나머지 부분들에 인지됩니다. + + +예를 들어, 다음의 일련의 이벤트들을 생각해 봅시다: + + CPU 1 CPU 2 + =============== =============== + { A == 1; B == 2 } + A = 3; x = B; + B = 4; y = A; + +다이어그램의 가운데에 위치한 메모리 시스템에 보여지게 되는 액세스들은 다음의 총 +24개의 조합으로 재구성될 수 있습니다: + + STORE A=3, STORE B=4, y=LOAD A->3, x=LOAD B->4 + STORE A=3, STORE B=4, x=LOAD B->4, y=LOAD A->3 + STORE A=3, y=LOAD A->3, STORE B=4, x=LOAD B->4 + STORE A=3, y=LOAD A->3, x=LOAD B->2, STORE B=4 + STORE A=3, x=LOAD B->2, STORE B=4, y=LOAD A->3 + STORE A=3, x=LOAD B->2, y=LOAD A->3, STORE B=4 + STORE B=4, STORE A=3, y=LOAD A->3, x=LOAD B->4 + STORE B=4, ... + ... + +따라서 다음의 네가지 조합의 값들이 나올 수 있습니다: + + x == 2, y == 1 + x == 2, y == 3 + x == 4, y == 1 + x == 4, y == 3 + + +한발 더 나아가서, 한 CPU 가 메모리 시스템에 반영한 스토어 오퍼레이션들의 결과는 +다른 CPU 에서의 로드 오퍼레이션을 통해 인지되는데, 이 때 스토어가 반영된 순서와 +다른 순서로 인지될 수도 있습니다. + + +예로, 아래의 일련의 이벤트들을 생각해 봅시다: + + CPU 1 CPU 2 + =============== =============== + { A == 1, B == 2, C == 3, P == &A, Q == &C } + B = 4; Q = P; + P = &B D = *Q; + +D 로 읽혀지는 값은 CPU 2 에서 P 로부터 읽혀진 주소값에 의존적이기 때문에 여기엔 +분명한 데이터 의존성이 있습니다. 하지만 이 이벤트들의 실행 결과로는 아래의 +결과들이 모두 나타날 수 있습니다: + + (Q == &A) and (D == 1) + (Q == &B) and (D == 2) + (Q == &B) and (D == 4) + +CPU 2 는 *Q 의 로드를 요청하기 전에 P 를 Q 에 넣기 때문에 D 에 C 를 집어넣는 +일은 없음을 알아두세요. + + +디바이스 오퍼레이션 +------------------- + +일부 디바이스는 자신의 컨트롤 인터페이스를 메모리의 특정 영역으로 매핑해서 +제공하는데(Memory mapped I/O), 해당 컨트롤 레지스터에 접근하는 순서는 매우 +중요합니다. 예를 들어, 어드레스 포트 레지스터 (A) 와 데이터 포트 레지스터 (D) +를 통해 접근되는 내부 레지스터 집합을 갖는 이더넷 카드를 생각해 봅시다. 내부의 +5번 레지스터를 읽기 위해 다음의 코드가 사용될 수 있습니다: + + *A = 5; + x = *D; + +하지만, 이건 다음의 두 조합 중 하나로 만들어질 수 있습니다: + + STORE *A = 5, x = LOAD *D + x = LOAD *D, STORE *A = 5 + +두번째 조합은 데이터를 읽어온 _후에_ 주소를 설정하므로, 오동작을 일으킬 겁니다. + + +보장사항 +-------- + +CPU 에게 기대할 수 있는 최소한의 보장사항 몇가지가 있습니다: + + (*) 어떤 CPU 든, 의존성이 존재하는 메모리 액세스들은 해당 CPU 자신에게 + 있어서는 순서대로 메모리 시스템에 수행 요청됩니다. 즉, 다음에 대해서: + + Q = READ_ONCE(P); D = READ_ONCE(*Q); + + CPU 는 다음과 같은 메모리 오퍼레이션 시퀀스를 수행 요청합니다: + + Q = LOAD P, D = LOAD *Q + + 그리고 그 시퀀스 내에서의 순서는 항상 지켜집니다. 하지만, DEC Alpha 에서 + READ_ONCE() 는 메모리 배리어 명령도 내게 되어 있어서, DEC Alpha CPU 는 + 다음과 같은 메모리 오퍼레이션들을 내놓게 됩니다: + + Q = LOAD P, MEMORY_BARRIER, D = LOAD *Q, MEMORY_BARRIER + + DEC Alpha 에서 수행되든 아니든, READ_ONCE() 는 컴파일러로부터의 악영향 + 또한 제거합니다. + + (*) 특정 CPU 내에서 겹치는 영역의 메모리에 행해지는 로드와 스토어 들은 해당 + CPU 안에서는 순서가 바뀌지 않은 것으로 보여집니다. 즉, 다음에 대해서: + + a = READ_ONCE(*X); WRITE_ONCE(*X, b); + + CPU 는 다음의 메모리 오퍼레이션 시퀀스만을 메모리에 요청할 겁니다: + + a = LOAD *X, STORE *X = b + + 그리고 다음에 대해서는: + + WRITE_ONCE(*X, c); d = READ_ONCE(*X); + + CPU 는 다음의 수행 요청만을 만들어 냅니다: + + STORE *X = c, d = LOAD *X + + (로드 오퍼레이션과 스토어 오퍼레이션이 겹치는 메모리 영역에 대해 + 수행된다면 해당 오퍼레이션들은 겹친다고 표현됩니다). + +그리고 _반드시_ 또는 _절대로_ 가정하거나 가정하지 말아야 하는 것들이 있습니다: + + (*) 컴파일러가 READ_ONCE() 나 WRITE_ONCE() 로 보호되지 않은 메모리 액세스를 + 당신이 원하는 대로 할 것이라는 가정은 _절대로_ 해선 안됩니다. 그것들이 + 없다면, 컴파일러는 컴파일러 배리어 섹션에서 다루게 될, 모든 "창의적인" + 변경들을 만들어낼 권한을 갖게 됩니다. + + (*) 개별적인 로드와 스토어들이 주어진 순서대로 요청될 것이라는 가정은 _절대로_ + 하지 말아야 합니다. 이 말은 곧: + + X = *A; Y = *B; *D = Z; + + 는 다음의 것들 중 어느 것으로든 만들어질 수 있다는 의미입니다: + + X = LOAD *A, Y = LOAD *B, STORE *D = Z + X = LOAD *A, STORE *D = Z, Y = LOAD *B + Y = LOAD *B, X = LOAD *A, STORE *D = Z + Y = LOAD *B, STORE *D = Z, X = LOAD *A + STORE *D = Z, X = LOAD *A, Y = LOAD *B + STORE *D = Z, Y = LOAD *B, X = LOAD *A + + (*) 겹치는 메모리 액세스들은 합쳐지거나 버려질 수 있음을 _반드시_ 가정해야 + 합니다. 다음의 코드는: + + X = *A; Y = *(A + 4); + + 다음의 것들 중 뭐든 될 수 있습니다: + + X = LOAD *A; Y = LOAD *(A + 4); + Y = LOAD *(A + 4); X = LOAD *A; + {X, Y} = LOAD {*A, *(A + 4) }; + + 그리고: + + *A = X; *(A + 4) = Y; + + 는 다음 중 뭐든 될 수 있습니다: + + STORE *A = X; STORE *(A + 4) = Y; + STORE *(A + 4) = Y; STORE *A = X; + STORE {*A, *(A + 4) } = {X, Y}; + +그리고 보장사항에 반대되는 것들(anti-guarantees)이 있습니다: + + (*) 이 보장사항들은 bitfield 에는 적용되지 않는데, 컴파일러들은 bitfield 를 + 수정하는 코드를 생성할 때 원자성 없는(non-atomic) 읽고-수정하고-쓰는 + 인스트럭션들의 조합을 만드는 경우가 많기 때문입니다. 병렬 알고리즘의 + 동기화에 bitfield 를 사용하려 하지 마십시오. + + (*) bitfield 들이 여러 락으로 보호되는 경우라 하더라도, 하나의 bitfield 의 + 모든 필드들은 하나의 락으로 보호되어야 합니다. 만약 한 bitfield 의 두 + 필드가 서로 다른 락으로 보호된다면, 컴파일러의 원자성 없는 + 읽고-수정하고-쓰는 인스트럭션 조합은 한 필드에의 업데이트가 근처의 + 필드에도 영향을 끼치게 할 수 있습니다. + + (*) 이 보장사항들은 적절하게 정렬되고 크기가 잡힌 스칼라 변수들에 대해서만 + 적용됩니다. "적절하게 크기가 잡힌" 이라함은 현재로써는 "char", "short", + "int" 그리고 "long" 과 같은 크기의 변수들을 의미합니다. "적절하게 정렬된" + 은 자연스런 정렬을 의미하는데, 따라서 "char" 에 대해서는 아무 제약이 없고, + "short" 에 대해서는 2바이트 정렬을, "int" 에는 4바이트 정렬을, 그리고 + "long" 에 대해서는 32-bit 시스템인지 64-bit 시스템인지에 따라 4바이트 또는 + 8바이트 정렬을 의미합니다. 이 보장사항들은 C11 표준에서 소개되었으므로, + C11 전의 오래된 컴파일러(예를 들어, gcc 4.6) 를 사용할 때엔 주의하시기 + 바랍니다. 표준에 이 보장사항들은 "memory location" 을 정의하는 3.14 + 섹션에 다음과 같이 설명되어 있습니다: + (역자: 인용문이므로 번역하지 않습니다) + + memory location + either an object of scalar type, or a maximal sequence + of adjacent bit-fields all having nonzero width + + NOTE 1: Two threads of execution can update and access + separate memory locations without interfering with + each other. + + NOTE 2: A bit-field and an adjacent non-bit-field member + are in separate memory locations. The same applies + to two bit-fields, if one is declared inside a nested + structure declaration and the other is not, or if the two + are separated by a zero-length bit-field declaration, + or if they are separated by a non-bit-field member + declaration. It is not safe to concurrently update two + bit-fields in the same structure if all members declared + between them are also bit-fields, no matter what the + sizes of those intervening bit-fields happen to be. + + +========================= +메모리 배리어란 무엇인가? +========================= + +앞에서 봤듯이, 상호간 의존성이 없는 메모리 오퍼레이션들은 실제로는 무작위적 +순서로 수행될 수 있으며, 이는 CPU 와 CPU 간의 상호작용이나 I/O 에 문제가 될 수 +있습니다. 따라서 컴파일러와 CPU 가 순서를 바꾸는데 제약을 걸 수 있도록 개입할 +수 있는 어떤 방법이 필요합니다. + +메모리 배리어는 그런 개입 수단입니다. 메모리 배리어는 배리어를 사이에 둔 앞과 +뒤 양측의 메모리 오퍼레이션들 간에 부분적 순서가 존재하도록 하는 효과를 줍니다. + +시스템의 CPU 들과 여러 디바이스들은 성능을 올리기 위해 명령어 재배치, 실행 +유예, 메모리 오퍼레이션들의 조합, 예측적 로드(speculative load), 브랜치 +예측(speculative branch prediction), 다양한 종류의 캐싱(caching) 등의 다양한 +트릭을 사용할 수 있기 때문에 이런 강제력은 중요합니다. 메모리 배리어들은 이런 +트릭들을 무효로 하거나 억제하는 목적으로 사용되어져서 코드가 여러 CPU 와 +디바이스들 간의 상호작용을 정상적으로 제어할 수 있게 해줍니다. + + +메모리 배리어의 종류 +-------------------- + +메모리 배리어는 네개의 기본 타입으로 분류됩니다: + + (1) 쓰기 (또는 스토어) 메모리 배리어. + + 쓰기 메모리 배리어는 시스템의 다른 컴포넌트들에 해당 배리어보다 앞서 + 명시된 모든 STORE 오퍼레이션들이 해당 배리어 뒤에 명시된 모든 STORE + 오퍼레이션들보다 먼저 수행된 것으로 보일 것을 보장합니다. + + 쓰기 배리어는 스토어 오퍼레이션들에 대한 부분적 순서 세우기입니다; 로드 + 오퍼레이션들에 대해서는 어떤 영향도 끼치지 않습니다. + + CPU 는 시간의 흐름에 따라 메모리 시스템에 일련의 스토어 오퍼레이션들을 + 하나씩 요청해 집어넣습니다. 쓰기 배리어 앞의 모든 스토어 오퍼레이션들은 + 쓰기 배리어 뒤의 모든 스토어 오퍼레이션들보다 _앞서_ 수행될 겁니다. + + [!] 쓰기 배리어들은 읽기 또는 데이터 의존성 배리어와 함께 짝을 맞춰 + 사용되어야만 함을 알아두세요; "SMP 배리어 짝맞추기" 서브섹션을 참고하세요. + + + (2) 데이터 의존성 배리어. + + 데이터 의존성 배리어는 읽기 배리어의 보다 완화된 형태입니다. 두개의 로드 + 오퍼레이션이 있고 두번째 것이 첫번째 것의 결과에 의존하고 있을 때(예: + 두번째 로드가 참조할 주소를 첫번째 로드가 읽는 경우), 두번째 로드가 읽어올 + 데이터는 첫번째 로드에 의해 그 주소가 얻어진 뒤에 업데이트 됨을 보장하기 + 위해서 데이터 의존성 배리어가 필요할 수 있습니다. + + 데이터 의존성 배리어는 상호 의존적인 로드 오퍼레이션들 사이의 부분적 순서 + 세우기입니다; 스토어 오퍼레이션들이나 독립적인 로드들, 또는 중복되는 + 로드들에 대해서는 어떤 영향도 끼치지 않습니다. + + (1) 에서 언급했듯이, 시스템의 CPU 들은 메모리 시스템에 일련의 스토어 + 오퍼레이션들을 던져 넣고 있으며, 거기에 관심이 있는 다른 CPU 는 그 + 오퍼레이션들을 메모리 시스템이 실행한 결과를 인지할 수 있습니다. 이처럼 + 다른 CPU 의 스토어 오퍼레이션의 결과에 관심을 두고 있는 CPU 가 수행 요청한 + 데이터 의존성 배리어는, 배리어 앞의 어떤 로드 오퍼레이션이 다른 CPU 에서 + 던져 넣은 스토어 오퍼레이션과 같은 영역을 향했다면, 그런 스토어 + 오퍼레이션들이 만들어내는 결과가 데이터 의존성 배리어 뒤의 로드 + 오퍼레이션들에게는 보일 것을 보장합니다. + + 이 순서 세우기 제약에 대한 그림을 보기 위해선 "메모리 배리어 시퀀스의 예" + 서브섹션을 참고하시기 바랍니다. + + [!] 첫번째 로드는 반드시 _데이터_ 의존성을 가져야지 컨트롤 의존성을 가져야 + 하는게 아님을 알아두십시오. 만약 두번째 로드를 위한 주소가 첫번째 로드에 + 의존적이지만 그 의존성은 조건적이지 그 주소 자체를 가져오는게 아니라면, + 그것은 _컨트롤_ 의존성이고, 이 경우에는 읽기 배리어나 그보다 강력한 + 무언가가 필요합니다. 더 자세한 내용을 위해서는 "컨트롤 의존성" 서브섹션을 + 참고하시기 바랍니다. + + [!] 데이터 의존성 배리어는 보통 쓰기 배리어들과 함께 짝을 맞춰 사용되어야 + 합니다; "SMP 배리어 짝맞추기" 서브섹션을 참고하세요. + + + (3) 읽기 (또는 로드) 메모리 배리어. + + 읽기 배리어는 데이터 의존성 배리어 기능의 보장사항에 더해서 배리어보다 + 앞서 명시된 모든 LOAD 오퍼레이션들이 배리어 뒤에 명시되는 모든 LOAD + 오퍼레이션들보다 먼저 행해진 것으로 시스템의 다른 컴포넌트들에 보여질 것을 + 보장합니다. + + 읽기 배리어는 로드 오퍼레이션에 행해지는 부분적 순서 세우기입니다; 스토어 + 오퍼레이션에 대해서는 어떤 영향도 끼치지 않습니다. + + 읽기 메모리 배리어는 데이터 의존성 배리어를 내장하므로 데이터 의존성 + 배리어를 대신할 수 있습니다. + + [!] 읽기 배리어는 일반적으로 쓰기 배리어들과 함께 짝을 맞춰 사용되어야 + 합니다; "SMP 배리어 짝맞추기" 서브섹션을 참고하세요. + + + (4) 범용 메모리 배리어. + + 범용(general) 메모리 배리어는 배리어보다 앞서 명시된 모든 LOAD 와 STORE + 오퍼레이션들이 배리어 뒤에 명시된 모든 LOAD 와 STORE 오퍼레이션들보다 + 먼저 수행된 것으로 시스템의 나머지 컴포넌트들에 보이게 됨을 보장합니다. + + 범용 메모리 배리어는 로드와 스토어 모두에 대한 부분적 순서 세우기입니다. + + 범용 메모리 배리어는 읽기 메모리 배리어, 쓰기 메모리 배리어 모두를 + 내장하므로, 두 배리어를 모두 대신할 수 있습니다. + + +그리고 두개의 명시적이지 않은 타입이 있습니다: + + (5) ACQUIRE 오퍼레이션. + + 이 타입의 오퍼레이션은 단방향의 투과성 배리어처럼 동작합니다. ACQUIRE + 오퍼레이션 뒤의 모든 메모리 오퍼레이션들이 ACQUIRE 오퍼레이션 후에 + 일어난 것으로 시스템의 나머지 컴포넌트들에 보이게 될 것이 보장됩니다. + LOCK 오퍼레이션과 smp_load_acquire(), smp_cond_acquire() 오퍼레이션도 + ACQUIRE 오퍼레이션에 포함됩니다. smp_cond_acquire() 오퍼레이션은 컨트롤 + 의존성과 smp_rmb() 를 사용해서 ACQUIRE 의 의미적 요구사항(semantic)을 + 충족시킵니다. + + ACQUIRE 오퍼레이션 앞의 메모리 오퍼레이션들은 ACQUIRE 오퍼레이션 완료 후에 + 수행된 것처럼 보일 수 있습니다. + + ACQUIRE 오퍼레이션은 거의 항상 RELEASE 오퍼레이션과 짝을 지어 사용되어야 + 합니다. + + + (6) RELEASE 오퍼레이션. + + 이 타입의 오퍼레이션들도 단방향 투과성 배리어처럼 동작합니다. RELEASE + 오퍼레이션 앞의 모든 메모리 오퍼레이션들은 RELEASE 오퍼레이션 전에 완료된 + 것으로 시스템의 다른 컴포넌트들에 보여질 것이 보장됩니다. UNLOCK 류의 + 오퍼레이션들과 smp_store_release() 오퍼레이션도 RELEASE 오퍼레이션의 + 일종입니다. + + RELEASE 오퍼레이션 뒤의 메모리 오퍼레이션들은 RELEASE 오퍼레이션이 + 완료되기 전에 행해진 것처럼 보일 수 있습니다. + + ACQUIRE 와 RELEASE 오퍼레이션의 사용은 일반적으로 다른 메모리 배리어의 + 필요성을 없앱니다 (하지만 "MMIO 쓰기 배리어" 서브섹션에서 설명되는 예외를 + 알아두세요). 또한, RELEASE+ACQUIRE 조합은 범용 메모리 배리어처럼 동작할 + 것을 보장하지 -않습니다-. 하지만, 어떤 변수에 대한 RELEASE 오퍼레이션을 + 앞서는 메모리 액세스들의 수행 결과는 이 RELEASE 오퍼레이션을 뒤이어 같은 + 변수에 대해 수행된 ACQUIRE 오퍼레이션을 뒤따르는 메모리 액세스에는 보여질 + 것이 보장됩니다. 다르게 말하자면, 주어진 변수의 크리티컬 섹션에서는, 해당 + 변수에 대한 앞의 크리티컬 섹션에서의 모든 액세스들이 완료되었을 것을 + 보장합니다. + + 즉, ACQUIRE 는 최소한의 "취득" 동작처럼, 그리고 RELEASE 는 최소한의 "공개" + 처럼 동작한다는 의미입니다. + +atomic_t.txt 에 설명된 어토믹 오퍼레이션들 중 일부는 완전히 순서잡힌 것들과 +(배리어를 사용하지 않는) 완화된 순서의 것들 외에 ACQUIRE 와 RELEASE 부류의 +것들도 존재합니다. 로드와 스토어를 모두 수행하는 조합된 어토믹 오퍼레이션에서, +ACQUIRE 는 해당 오퍼레이션의 로드 부분에만 적용되고 RELEASE 는 해당 +오퍼레이션의 스토어 부분에만 적용됩니다. + +메모리 배리어들은 두 CPU 간, 또는 CPU 와 디바이스 간에 상호작용의 가능성이 있을 +때에만 필요합니다. 만약 어떤 코드에 그런 상호작용이 없을 것이 보장된다면, 해당 +코드에서는 메모리 배리어를 사용할 필요가 없습니다. + + +이것들은 _최소한의_ 보장사항들임을 알아두세요. 다른 아키텍쳐에서는 더 강력한 +보장사항을 제공할 수도 있습니다만, 그런 보장사항은 아키텍쳐 종속적 코드 이외의 +부분에서는 신뢰되지 _않을_ 겁니다. + + +메모리 배리어에 대해 가정해선 안될 것 +------------------------------------- + +리눅스 커널 메모리 배리어들이 보장하지 않는 것들이 있습니다: + + (*) 메모리 배리어 앞에서 명시된 어떤 메모리 액세스도 메모리 배리어 명령의 수행 + 완료 시점까지 _완료_ 될 것이란 보장은 없습니다; 배리어가 하는 일은 CPU 의 + 액세스 큐에 특정 타입의 액세스들은 넘을 수 없는 선을 긋는 것으로 생각될 수 + 있습니다. + + (*) 한 CPU 에서 메모리 배리어를 수행하는게 시스템의 다른 CPU 나 하드웨어에 + 어떤 직접적인 영향을 끼친다는 보장은 존재하지 않습니다. 배리어 수행이 + 만드는 간접적 영향은 두번째 CPU 가 첫번째 CPU 의 액세스들의 결과를 + 바라보는 순서가 됩니다만, 다음 항목을 보세요: + + (*) 첫번째 CPU 가 두번째 CPU 의 메모리 액세스들의 결과를 바라볼 때, _설령_ + 두번째 CPU 가 메모리 배리어를 사용한다 해도, 첫번째 CPU _또한_ 그에 맞는 + 메모리 배리어를 사용하지 않는다면 ("SMP 배리어 짝맞추기" 서브섹션을 + 참고하세요) 그 결과가 올바른 순서로 보여진다는 보장은 없습니다. + + (*) CPU 바깥의 하드웨어[*] 가 메모리 액세스들의 순서를 바꾸지 않는다는 보장은 + 존재하지 않습니다. CPU 캐시 일관성 메커니즘은 메모리 배리어의 간접적 + 영향을 CPU 사이에 전파하긴 하지만, 순서대로 전파하지는 않을 수 있습니다. + + [*] 버스 마스터링 DMA 와 일관성에 대해서는 다음을 참고하시기 바랍니다: + + Documentation/PCI/pci.txt + Documentation/DMA-API-HOWTO.txt + Documentation/DMA-API.txt + + +데이터 의존성 배리어 (역사적) +----------------------------- + +리눅스 커널 v4.15 기준으로, smp_read_barrier_depends() 가 READ_ONCE() 에 +추가되었는데, 이는 이 섹션에 주의를 기울여야 하는 사람들은 DEC Alpha 아키텍쳐 +전용 코드를 만드는 사람들과 READ_ONCE() 자체를 만드는 사람들 뿐임을 의미합니다. +그런 분들을 위해, 그리고 역사에 관심 있는 분들을 위해, 여기 데이터 의존성 +배리어에 대한 이야기를 적습니다. + +데이터 의존성 배리어의 사용에 있어 지켜야 하는 사항들은 약간 미묘하고, 데이터 +의존성 배리어가 사용되어야 하는 상황도 항상 명백하지는 않습니다. 설명을 위해 +다음의 이벤트 시퀀스를 생각해 봅시다: + + CPU 1 CPU 2 + =============== =============== + { A == 1, B == 2, C == 3, P == &A, Q == &C } + B = 4; + <쓰기 배리어> + WRITE_ONCE(P, &B) + Q = READ_ONCE(P); + D = *Q; + +여기엔 분명한 데이터 의존성이 존재하므로, 이 시퀀스가 끝났을 때 Q 는 &A 또는 &B +일 것이고, 따라서: + + (Q == &A) 는 (D == 1) 를, + (Q == &B) 는 (D == 4) 를 의미합니다. + +하지만! CPU 2 는 B 의 업데이트를 인식하기 전에 P 의 업데이트를 인식할 수 있고, +따라서 다음의 결과가 가능합니다: + + (Q == &B) and (D == 2) ???? + +이런 결과는 일관성이나 인과 관계 유지가 실패한 것처럼 보일 수도 있겠지만, +그렇지 않습니다, 그리고 이 현상은 (DEC Alpha 와 같은) 여러 CPU 에서 실제로 +발견될 수 있습니다. + +이 문제 상황을 제대로 해결하기 위해, 데이터 의존성 배리어나 그보다 강화된 +무언가가 주소를 읽어올 때와 데이터를 읽어올 때 사이에 추가되어야만 합니다: + + CPU 1 CPU 2 + =============== =============== + { A == 1, B == 2, C == 3, P == &A, Q == &C } + B = 4; + <쓰기 배리어> + WRITE_ONCE(P, &B); + Q = READ_ONCE(P); + <데이터 의존성 배리어> + D = *Q; + +이 변경은 앞의 처음 두가지 결과 중 하나만이 발생할 수 있고, 세번째의 결과는 +발생할 수 없도록 합니다. + + +[!] 이 상당히 반직관적인 상황은 분리된 캐시를 가지는 기계들에서 가장 잘 +발생하는데, 예를 들면 한 캐시 뱅크는 짝수 번호의 캐시 라인들을 처리하고, 다른 +뱅크는 홀수 번호의 캐시 라인들을 처리하는 경우임을 알아두시기 바랍니다. 포인터 +P 는 짝수 번호 캐시 라인에 저장되어 있고, 변수 B 는 홀수 번호 캐시 라인에 +저장되어 있을 수 있습니다. 여기서 값을 읽어오는 CPU 의 캐시의 홀수 번호 처리 +뱅크는 열심히 일감을 처리중인 반면 홀수 번호 처리 뱅크는 할 일 없이 한가한 +중이라면 포인터 P (&B) 의 새로운 값과 변수 B 의 기존 값 (2) 를 볼 수 있습니다. + + +의존적 쓰기들의 순서를 맞추는데에는 데이터 의존성 배리어가 필요치 않은데, 이는 +리눅스 커널이 지원하는 CPU 들은 (1) 쓰기가 정말로 일어날지, (2) 쓰기가 어디에 +이루어질지, 그리고 (3) 쓰여질 값을 확실히 알기 전까지는 쓰기를 수행하지 않기 +때문입니다. 하지만 "컨트롤 의존성" 섹션과 +Documentation/RCU/rcu_dereference.txt 파일을 주의 깊게 읽어 주시기 바랍니다: +컴파일러는 매우 창의적인 많은 방법으로 종속성을 깰 수 있습니다. + + CPU 1 CPU 2 + =============== =============== + { A == 1, B == 2, C = 3, P == &A, Q == &C } + B = 4; + <쓰기 배리어> + WRITE_ONCE(P, &B); + Q = READ_ONCE(P); + WRITE_ONCE(*Q, 5); + +따라서, Q 로의 읽기와 *Q 로의 쓰기 사이에는 데이터 종속성 배리어가 필요치 +않습니다. 달리 말하면, 데이터 종속성 배리어가 없더라도 다음 결과는 생기지 +않습니다: + + (Q == &B) && (B == 4) + +이런 패턴은 드물게 사용되어야 함을 알아 두시기 바랍니다. 무엇보다도, 의존성 +순서 규칙의 의도는 쓰기 작업을 -예방- 해서 그로 인해 발생하는 비싼 캐시 미스도 +없애려는 것입니다. 이 패턴은 드물게 발생하는 에러 조건 같은것들을 기록하는데 +사용될 수 있으며, CPU의 자연적인 순서 보장이 그런 기록들을 사라지지 않게 +해줍니다. + + +데이터 의존성에 의해 제공되는 이 순서규칙은 이를 포함하고 있는 CPU 에 +지역적임을 알아두시기 바랍니다. 더 많은 정보를 위해선 "Multicopy 원자성" +섹션을 참고하세요. + + +데이터 의존성 배리어는 매우 중요한데, 예를 들어 RCU 시스템에서 그렇습니다. +include/linux/rcupdate.h 의 rcu_assign_pointer() 와 rcu_dereference() 를 +참고하세요. 여기서 데이터 의존성 배리어는 RCU 로 관리되는 포인터의 타겟을 현재 +타겟에서 수정된 새로운 타겟으로 바꾸는 작업에서 새로 수정된 타겟이 초기화가 +완료되지 않은 채로 보여지는 일이 일어나지 않게 해줍니다. + +더 많은 예를 위해선 "캐시 일관성" 서브섹션을 참고하세요. + + +컨트롤 의존성 +------------- + +현재의 컴파일러들은 컨트롤 의존성을 이해하고 있지 않기 때문에 컨트롤 의존성은 +약간 다루기 어려울 수 있습니다. 이 섹션의 목적은 여러분이 컴파일러의 무시로 +인해 여러분의 코드가 망가지는 걸 막을 수 있도록 돕는겁니다. + +로드-로드 컨트롤 의존성은 데이터 의존성 배리어만으로는 정확히 동작할 수가 +없어서 읽기 메모리 배리어를 필요로 합니다. 아래의 코드를 봅시다: + + q = READ_ONCE(a); + if (q) { + <데이터 의존성 배리어> /* BUG: No data dependency!!! */ + p = READ_ONCE(b); + } + +이 코드는 원하는 대로의 효과를 내지 못할 수 있는데, 이 코드에는 데이터 의존성이 +아니라 컨트롤 의존성이 존재하기 때문으로, 이런 상황에서 CPU 는 실행 속도를 더 +빠르게 하기 위해 분기 조건의 결과를 예측하고 코드를 재배치 할 수 있어서 다른 +CPU 는 b 로부터의 로드 오퍼레이션이 a 로부터의 로드 오퍼레이션보다 먼저 발생한 +걸로 인식할 수 있습니다. 여기에 정말로 필요했던 건 다음과 같습니다: + + q = READ_ONCE(a); + if (q) { + <읽기 배리어> + p = READ_ONCE(b); + } + +하지만, 스토어 오퍼레이션은 예측적으로 수행되지 않습니다. 즉, 다음 예에서와 +같이 로드-스토어 컨트롤 의존성이 존재하는 경우에는 순서가 -지켜진다-는 +의미입니다. + + q = READ_ONCE(a); + if (q) { + WRITE_ONCE(b, 1); + } + +컨트롤 의존성은 보통 다른 타입의 배리어들과 짝을 맞춰 사용됩니다. 그렇다곤 +하나, READ_ONCE() 도 WRITE_ONCE() 도 선택사항이 아니라 필수사항임을 부디 +명심하세요! READ_ONCE() 가 없다면, 컴파일러는 'a' 로부터의 로드를 'a' 로부터의 +또다른 로드와 조합할 수 있습니다. WRITE_ONCE() 가 없다면, 컴파일러는 'b' 로의 +스토어를 'b' 로의 또라느 스토어들과 조합할 수 있습니다. 두 경우 모두 순서에 +있어 상당히 비직관적인 결과를 초래할 수 있습니다. + +이걸로 끝이 아닌게, 컴파일러가 변수 'a' 의 값이 항상 0이 아니라고 증명할 수 +있다면, 앞의 예에서 "if" 문을 없애서 다음과 같이 최적화 할 수도 있습니다: + + q = a; + b = 1; /* BUG: Compiler and CPU can both reorder!!! */ + +그러니 READ_ONCE() 를 반드시 사용하세요. + +다음과 같이 "if" 문의 양갈래 브랜치에 모두 존재하는 동일한 스토어에 대해 순서를 +강제하고 싶은 경우가 있을 수 있습니다: + + q = READ_ONCE(a); + if (q) { + barrier(); + WRITE_ONCE(b, 1); + do_something(); + } else { + barrier(); + WRITE_ONCE(b, 1); + do_something_else(); + } + +안타깝게도, 현재의 컴파일러들은 높은 최적화 레벨에서는 이걸 다음과 같이 +바꿔버립니다: + + q = READ_ONCE(a); + barrier(); + WRITE_ONCE(b, 1); /* BUG: No ordering vs. load from a!!! */ + if (q) { + /* WRITE_ONCE(b, 1); -- moved up, BUG!!! */ + do_something(); + } else { + /* WRITE_ONCE(b, 1); -- moved up, BUG!!! */ + do_something_else(); + } + +이제 'a' 에서의 로드와 'b' 로의 스토어 사이에는 조건적 관계가 없기 때문에 CPU +는 이들의 순서를 바꿀 수 있게 됩니다: 이런 경우에 조건적 관계는 반드시 +필요한데, 모든 컴파일러 최적화가 이루어지고 난 후의 어셈블리 코드에서도 +마찬가지입니다. 따라서, 이 예에서 순서를 지키기 위해서는 smp_store_release() +와 같은 명시적 메모리 배리어가 필요합니다: + + q = READ_ONCE(a); + if (q) { + smp_store_release(&b, 1); + do_something(); + } else { + smp_store_release(&b, 1); + do_something_else(); + } + +반면에 명시적 메모리 배리어가 없다면, 이런 경우의 순서는 스토어 오퍼레이션들이 +서로 다를 때에만 보장되는데, 예를 들면 다음과 같은 경우입니다: + + q = READ_ONCE(a); + if (q) { + WRITE_ONCE(b, 1); + do_something(); + } else { + WRITE_ONCE(b, 2); + do_something_else(); + } + +처음의 READ_ONCE() 는 컴파일러가 'a' 의 값을 증명해내는 것을 막기 위해 여전히 +필요합니다. + +또한, 로컬 변수 'q' 를 가지고 하는 일에 대해 주의해야 하는데, 그러지 않으면 +컴파일러는 그 값을 추측하고 또다시 필요한 조건관계를 없애버릴 수 있습니다. +예를 들면: + + q = READ_ONCE(a); + if (q % MAX) { + WRITE_ONCE(b, 1); + do_something(); + } else { + WRITE_ONCE(b, 2); + do_something_else(); + } + +만약 MAX 가 1 로 정의된 상수라면, 컴파일러는 (q % MAX) 는 0이란 것을 알아채고, +위의 코드를 아래와 같이 바꿔버릴 수 있습니다: + + q = READ_ONCE(a); + WRITE_ONCE(b, 2); + do_something_else(); + +이렇게 되면, CPU 는 변수 'a' 로부터의 로드와 변수 'b' 로의 스토어 사이의 순서를 +지켜줄 필요가 없어집니다. barrier() 를 추가해 해결해 보고 싶겠지만, 그건 +도움이 안됩니다. 조건 관계는 사라졌고, barrier() 는 이를 되돌리지 못합니다. +따라서, 이 순서를 지켜야 한다면, MAX 가 1 보다 크다는 것을, 다음과 같은 방법을 +사용해 분명히 해야 합니다: + + q = READ_ONCE(a); + BUILD_BUG_ON(MAX <= 1); /* Order load from a with store to b. */ + if (q % MAX) { + WRITE_ONCE(b, 1); + do_something(); + } else { + WRITE_ONCE(b, 2); + do_something_else(); + } + +'b' 로의 스토어들은 여전히 서로 다름을 알아두세요. 만약 그것들이 동일하면, +앞에서 이야기했듯, 컴파일러가 그 스토어 오퍼레이션들을 'if' 문 바깥으로 +끄집어낼 수 있습니다. + +또한 이진 조건문 평가에 너무 의존하지 않도록 조심해야 합니다. 다음의 예를 +봅시다: + + q = READ_ONCE(a); + if (q || 1 > 0) + WRITE_ONCE(b, 1); + +첫번째 조건만으로는 브랜치 조건 전체를 거짓으로 만들 수 없고 두번째 조건은 항상 +참이기 때문에, 컴파일러는 이 예를 다음과 같이 바꿔서 컨트롤 의존성을 없애버릴 +수 있습니다: + + q = READ_ONCE(a); + WRITE_ONCE(b, 1); + +이 예는 컴파일러가 코드를 추측으로 수정할 수 없도록 분명히 해야 한다는 점을 +강조합니다. 조금 더 일반적으로 말해서, READ_ONCE() 는 컴파일러에게 주어진 로드 +오퍼레이션을 위한 코드를 정말로 만들도록 하지만, 컴파일러가 그렇게 만들어진 +코드의 수행 결과를 사용하도록 강제하지는 않습니다. + +또한, 컨트롤 의존성은 if 문의 then 절과 else 절에 대해서만 적용됩니다. 상세히 +말해서, 컨트롤 의존성은 if 문을 뒤따르는 코드에는 적용되지 않습니다: + + q = READ_ONCE(a); + if (q) { + WRITE_ONCE(b, 1); + } else { + WRITE_ONCE(b, 2); + } + WRITE_ONCE(c, 1); /* BUG: No ordering against the read from 'a'. */ + +컴파일러는 volatile 타입에 대한 액세스를 재배치 할 수 없고 이 조건 하의 'b' +로의 쓰기를 재배치 할 수 없기 때문에 여기에 순서 규칙이 존재한다고 주장하고 +싶을 겁니다. 불행히도 이 경우에, 컴파일러는 다음의 가상의 pseudo-assembly 언어 +코드처럼 'b' 로의 두개의 쓰기 오퍼레이션을 conditional-move 인스트럭션으로 +번역할 수 있습니다: + + ld r1,a + cmp r1,$0 + cmov,ne r4,$1 + cmov,eq r4,$2 + st r4,b + st $1,c + +완화된 순서 규칙의 CPU 는 'a' 로부터의 로드와 'c' 로의 스토어 사이에 어떤 +종류의 의존성도 갖지 않을 겁니다. 이 컨트롤 의존성은 두개의 cmov 인스트럭션과 +거기에 의존하는 스토어 에게만 적용될 겁니다. 짧게 말하자면, 컨트롤 의존성은 +주어진 if 문의 then 절과 else 절에게만 (그리고 이 두 절 내에서 호출되는 +함수들에게까지) 적용되지, 이 if 문을 뒤따르는 코드에는 적용되지 않습니다. + + +컨트롤 의존성에 의해 제공되는 이 순서규칙은 이를 포함하고 있는 CPU 에 +지역적입니다. 더 많은 정보를 위해선 "Multicopy 원자성" 섹션을 참고하세요. + + +요약하자면: + + (*) 컨트롤 의존성은 앞의 로드들을 뒤의 스토어들에 대해 순서를 맞춰줍니다. + 하지만, 그 외의 어떤 순서도 보장하지 -않습니다-: 앞의 로드와 뒤의 로드들 + 사이에도, 앞의 스토어와 뒤의 스토어들 사이에도요. 이런 다른 형태의 + 순서가 필요하다면 smp_rmb() 나 smp_wmb()를, 또는, 앞의 스토어들과 뒤의 + 로드들 사이의 순서를 위해서는 smp_mb() 를 사용하세요. + + (*) "if" 문의 양갈래 브랜치가 같은 변수에의 동일한 스토어로 시작한다면, 그 + 스토어들은 각 스토어 앞에 smp_mb() 를 넣거나 smp_store_release() 를 + 사용해서 스토어를 하는 식으로 순서를 맞춰줘야 합니다. 이 문제를 해결하기 + 위해 "if" 문의 양갈래 브랜치의 시작 지점에 barrier() 를 넣는 것만으로는 + 충분한 해결이 되지 않는데, 이는 앞의 예에서 본것과 같이, 컴파일러의 + 최적화는 barrier() 가 의미하는 바를 지키면서도 컨트롤 의존성을 손상시킬 + 수 있기 때문이라는 점을 부디 알아두시기 바랍니다. + + (*) 컨트롤 의존성은 앞의 로드와 뒤의 스토어 사이에 최소 하나의, 실행 + 시점에서의 조건관계를 필요로 하며, 이 조건관계는 앞의 로드와 관계되어야 + 합니다. 만약 컴파일러가 조건 관계를 최적화로 없앨수 있다면, 순서도 + 최적화로 없애버렸을 겁니다. READ_ONCE() 와 WRITE_ONCE() 의 주의 깊은 + 사용은 주어진 조건 관계를 유지하는데 도움이 될 수 있습니다. + + (*) 컨트롤 의존성을 위해선 컴파일러가 조건관계를 없애버리는 것을 막아야 + 합니다. 주의 깊은 READ_ONCE() 나 atomic{,64}_read() 의 사용이 컨트롤 + 의존성이 사라지지 않게 하는데 도움을 줄 수 있습니다. 더 많은 정보를 + 위해선 "컴파일러 배리어" 섹션을 참고하시기 바랍니다. + + (*) 컨트롤 의존성은 컨트롤 의존성을 갖는 if 문의 then 절과 else 절과 이 두 절 + 내에서 호출되는 함수들에만 적용됩니다. 컨트롤 의존성은 컨트롤 의존성을 + 갖는 if 문을 뒤따르는 코드에는 적용되지 -않습니다-. + + (*) 컨트롤 의존성은 보통 다른 타입의 배리어들과 짝을 맞춰 사용됩니다. + + (*) 컨트롤 의존성은 multicopy 원자성을 제공하지 -않습니다-. 모든 CPU 들이 + 특정 스토어를 동시에 보길 원한다면, smp_mb() 를 사용하세요. + + (*) 컴파일러는 컨트롤 의존성을 이해하고 있지 않습니다. 따라서 컴파일러가 + 여러분의 코드를 망가뜨리지 않도록 하는건 여러분이 해야 하는 일입니다. + + +SMP 배리어 짝맞추기 +-------------------- + +CPU 간 상호작용을 다룰 때에 일부 타입의 메모리 배리어는 항상 짝을 맞춰 +사용되어야 합니다. 적절하게 짝을 맞추지 않은 코드는 사실상 에러에 가깝습니다. + +범용 배리어들은 범용 배리어끼리도 짝을 맞추지만 multicopy 원자성이 없는 +대부분의 다른 타입의 배리어들과도 짝을 맞춥니다. ACQUIRE 배리어는 RELEASE +배리어와 짝을 맞춥니다만, 둘 다 범용 배리어를 포함해 다른 배리어들과도 짝을 +맞출 수 있습니다. 쓰기 배리어는 데이터 의존성 배리어나 컨트롤 의존성, ACQUIRE +배리어, RELEASE 배리어, 읽기 배리어, 또는 범용 배리어와 짝을 맞춥니다. +비슷하게 읽기 배리어나 컨트롤 의존성, 또는 데이터 의존성 배리어는 쓰기 배리어나 +ACQUIRE 배리어, RELEASE 배리어, 또는 범용 배리어와 짝을 맞추는데, 다음과 +같습니다: + + CPU 1 CPU 2 + =============== =============== + WRITE_ONCE(a, 1); + <쓰기 배리어> + WRITE_ONCE(b, 2); x = READ_ONCE(b); + <읽기 배리어> + y = READ_ONCE(a); + +또는: + + CPU 1 CPU 2 + =============== =============================== + a = 1; + <쓰기 배리어> + WRITE_ONCE(b, &a); x = READ_ONCE(b); + <데이터 의존성 배리어> + y = *x; + +또는: + + CPU 1 CPU 2 + =============== =============================== + r1 = READ_ONCE(y); + <범용 배리어> + WRITE_ONCE(x, 1); if (r2 = READ_ONCE(x)) { + <묵시적 컨트롤 의존성> + WRITE_ONCE(y, 1); + } + + assert(r1 == 0 || r2 == 0); + +기본적으로, 여기서의 읽기 배리어는 "더 완화된" 타입일 순 있어도 항상 존재해야 +합니다. + +[!] 쓰기 배리어 앞의 스토어 오퍼레이션은 일반적으로 읽기 배리어나 데이터 +의존성 배리어 뒤의 로드 오퍼레이션과 매치될 것이고, 반대도 마찬가지입니다: + + CPU 1 CPU 2 + =================== =================== + WRITE_ONCE(a, 1); }---- --->{ v = READ_ONCE(c); + WRITE_ONCE(b, 2); } \ / { w = READ_ONCE(d); + <쓰기 배리어> \ <읽기 배리어> + WRITE_ONCE(c, 3); } / \ { x = READ_ONCE(a); + WRITE_ONCE(d, 4); }---- --->{ y = READ_ONCE(b); + + +메모리 배리어 시퀀스의 예 +------------------------- + +첫째, 쓰기 배리어는 스토어 오퍼레이션들의 부분적 순서 세우기로 동작합니다. +아래의 이벤트 시퀀스를 보세요: + + CPU 1 + ======================= + STORE A = 1 + STORE B = 2 + STORE C = 3 + <쓰기 배리어> + STORE D = 4 + STORE E = 5 + +이 이벤트 시퀀스는 메모리 일관성 시스템에 원소끼리의 순서가 존재하지 않는 집합 +{ STORE A, STORE B, STORE C } 가 역시 원소끼리의 순서가 존재하지 않는 집합 +{ STORE D, STORE E } 보다 먼저 일어난 것으로 시스템의 나머지 요소들에 보이도록 +전달됩니다: + + +-------+ : : + | | +------+ + | |------>| C=3 | } /\ + | | : +------+ }----- \ -----> 시스템의 나머지 요소에 + | | : | A=1 | } \/ 보여질 수 있는 이벤트들 + | | : +------+ } + | CPU 1 | : | B=2 | } + | | +------+ } + | | wwwwwwwwwwwwwwww } <--- 여기서 쓰기 배리어는 배리어 앞의 + | | +------+ } 모든 스토어가 배리어 뒤의 스토어 + | | : | E=5 | } 전에 메모리 시스템에 전달되도록 + | | : +------+ } 합니다 + | |------>| D=4 | } + | | +------+ + +-------+ : : + | + | CPU 1 에 의해 메모리 시스템에 전달되는 + | 일련의 스토어 오퍼레이션들 + V + + +둘째, 데이터 의존성 배리어는 데이터 의존적 로드 오퍼레이션들의 부분적 순서 +세우기로 동작합니다. 다음 일련의 이벤트들을 보세요: + + CPU 1 CPU 2 + ======================= ======================= + { B = 7; X = 9; Y = 8; C = &Y } + STORE A = 1 + STORE B = 2 + <쓰기 배리어> + STORE C = &B LOAD X + STORE D = 4 LOAD C (gets &B) + LOAD *C (reads B) + +여기에 별다른 개입이 없다면, CPU 1 의 쓰기 배리어에도 불구하고 CPU 2 는 CPU 1 +의 이벤트들을 완전히 무작위적 순서로 인지하게 됩니다: + + +-------+ : : : : + | | +------+ +-------+ | CPU 2 에 인지되는 + | |------>| B=2 |----- --->| Y->8 | | 업데이트 이벤트 + | | : +------+ \ +-------+ | 시퀀스 + | CPU 1 | : | A=1 | \ --->| C->&Y | V + | | +------+ | +-------+ + | | wwwwwwwwwwwwwwww | : : + | | +------+ | : : + | | : | C=&B |--- | : : +-------+ + | | : +------+ \ | +-------+ | | + | |------>| D=4 | ----------->| C->&B |------>| | + | | +------+ | +-------+ | | + +-------+ : : | : : | | + | : : | | + | : : | CPU 2 | + | +-------+ | | + 분명히 잘못된 ---> | | B->7 |------>| | + B 의 값 인지 (!) | +-------+ | | + | : : | | + | +-------+ | | + X 의 로드가 B 의 ---> \ | X->9 |------>| | + 일관성 유지를 \ +-------+ | | + 지연시킴 ----->| B->2 | +-------+ + +-------+ + : : + + +앞의 예에서, CPU 2 는 (B 의 값이 될) *C 의 값 읽기가 C 의 LOAD 뒤에 이어짐에도 +B 가 7 이라는 결과를 얻습니다. + +하지만, 만약 데이터 의존성 배리어가 C 의 로드와 *C (즉, B) 의 로드 사이에 +있었다면: + + CPU 1 CPU 2 + ======================= ======================= + { B = 7; X = 9; Y = 8; C = &Y } + STORE A = 1 + STORE B = 2 + <쓰기 배리어> + STORE C = &B LOAD X + STORE D = 4 LOAD C (gets &B) + <데이터 의존성 배리어> + LOAD *C (reads B) + +다음과 같이 됩니다: + + +-------+ : : : : + | | +------+ +-------+ + | |------>| B=2 |----- --->| Y->8 | + | | : +------+ \ +-------+ + | CPU 1 | : | A=1 | \ --->| C->&Y | + | | +------+ | +-------+ + | | wwwwwwwwwwwwwwww | : : + | | +------+ | : : + | | : | C=&B |--- | : : +-------+ + | | : +------+ \ | +-------+ | | + | |------>| D=4 | ----------->| C->&B |------>| | + | | +------+ | +-------+ | | + +-------+ : : | : : | | + | : : | | + | : : | CPU 2 | + | +-------+ | | + | | X->9 |------>| | + | +-------+ | | + C 로의 스토어 앞의 ---> \ ddddddddddddddddd | | + 모든 이벤트 결과가 \ +-------+ | | + 뒤의 로드에게 ----->| B->2 |------>| | + 보이게 강제한다 +-------+ | | + : : +-------+ + + +셋째, 읽기 배리어는 로드 오퍼레이션들에의 부분적 순서 세우기로 동작합니다. +아래의 일련의 이벤트를 봅시다: + + CPU 1 CPU 2 + ======================= ======================= + { A = 0, B = 9 } + STORE A=1 + <쓰기 배리어> + STORE B=2 + LOAD B + LOAD A + +CPU 1 은 쓰기 배리어를 쳤지만, 별다른 개입이 없다면 CPU 2 는 CPU 1 에서 행해진 +이벤트의 결과를 무작위적 순서로 인지하게 됩니다. + + +-------+ : : : : + | | +------+ +-------+ + | |------>| A=1 |------ --->| A->0 | + | | +------+ \ +-------+ + | CPU 1 | wwwwwwwwwwwwwwww \ --->| B->9 | + | | +------+ | +-------+ + | |------>| B=2 |--- | : : + | | +------+ \ | : : +-------+ + +-------+ : : \ | +-------+ | | + ---------->| B->2 |------>| | + | +-------+ | CPU 2 | + | | A->0 |------>| | + | +-------+ | | + | : : +-------+ + \ : : + \ +-------+ + ---->| A->1 | + +-------+ + : : + + +하지만, 만약 읽기 배리어가 B 의 로드와 A 의 로드 사이에 존재한다면: + + CPU 1 CPU 2 + ======================= ======================= + { A = 0, B = 9 } + STORE A=1 + <쓰기 배리어> + STORE B=2 + LOAD B + <읽기 배리어> + LOAD A + +CPU 1 에 의해 만들어진 부분적 순서가 CPU 2 에도 그대로 인지됩니다: + + +-------+ : : : : + | | +------+ +-------+ + | |------>| A=1 |------ --->| A->0 | + | | +------+ \ +-------+ + | CPU 1 | wwwwwwwwwwwwwwww \ --->| B->9 | + | | +------+ | +-------+ + | |------>| B=2 |--- | : : + | | +------+ \ | : : +-------+ + +-------+ : : \ | +-------+ | | + ---------->| B->2 |------>| | + | +-------+ | CPU 2 | + | : : | | + | : : | | + 여기서 읽기 배리어는 ----> \ rrrrrrrrrrrrrrrrr | | + B 로의 스토어 전의 \ +-------+ | | + 모든 결과를 CPU 2 에 ---->| A->1 |------>| | + 보이도록 한다 +-------+ | | + : : +-------+ + + +더 완벽한 설명을 위해, A 의 로드가 읽기 배리어 앞과 뒤에 있으면 어떻게 될지 +생각해 봅시다: + + CPU 1 CPU 2 + ======================= ======================= + { A = 0, B = 9 } + STORE A=1 + <쓰기 배리어> + STORE B=2 + LOAD B + LOAD A [first load of A] + <읽기 배리어> + LOAD A [second load of A] + +A 의 로드 두개가 모두 B 의 로드 뒤에 있지만, 서로 다른 값을 얻어올 수 +있습니다: + + +-------+ : : : : + | | +------+ +-------+ + | |------>| A=1 |------ --->| A->0 | + | | +------+ \ +-------+ + | CPU 1 | wwwwwwwwwwwwwwww \ --->| B->9 | + | | +------+ | +-------+ + | |------>| B=2 |--- | : : + | | +------+ \ | : : +-------+ + +-------+ : : \ | +-------+ | | + ---------->| B->2 |------>| | + | +-------+ | CPU 2 | + | : : | | + | : : | | + | +-------+ | | + | | A->0 |------>| 1st | + | +-------+ | | + 여기서 읽기 배리어는 ----> \ rrrrrrrrrrrrrrrrr | | + B 로의 스토어 전의 \ +-------+ | | + 모든 결과를 CPU 2 에 ---->| A->1 |------>| 2nd | + 보이도록 한다 +-------+ | | + : : +-------+ + + +하지만 CPU 1 에서의 A 업데이트는 읽기 배리어가 완료되기 전에도 보일 수도 +있긴 합니다: + + +-------+ : : : : + | | +------+ +-------+ + | |------>| A=1 |------ --->| A->0 | + | | +------+ \ +-------+ + | CPU 1 | wwwwwwwwwwwwwwww \ --->| B->9 | + | | +------+ | +-------+ + | |------>| B=2 |--- | : : + | | +------+ \ | : : +-------+ + +-------+ : : \ | +-------+ | | + ---------->| B->2 |------>| | + | +-------+ | CPU 2 | + | : : | | + \ : : | | + \ +-------+ | | + ---->| A->1 |------>| 1st | + +-------+ | | + rrrrrrrrrrrrrrrrr | | + +-------+ | | + | A->1 |------>| 2nd | + +-------+ | | + : : +-------+ + + +여기서 보장되는 건, 만약 B 의 로드가 B == 2 라는 결과를 봤다면, A 에의 두번째 +로드는 항상 A == 1 을 보게 될 것이라는 겁니다. A 에의 첫번째 로드에는 그런 +보장이 없습니다; A == 0 이거나 A == 1 이거나 둘 중 하나의 결과를 보게 될겁니다. + + +읽기 메모리 배리어 VS 로드 예측 +------------------------------- + +많은 CPU들이 로드를 예측적으로 (speculatively) 합니다: 어떤 데이터를 메모리에서 +로드해야 하게 될지 예측을 했다면, 해당 데이터를 로드하는 인스트럭션을 실제로는 +아직 만나지 않았더라도 다른 로드 작업이 없어 버스 (bus) 가 아무 일도 하고 있지 +않다면, 그 데이터를 로드합니다. 이후에 실제 로드 인스트럭션이 실행되면 CPU 가 +이미 그 값을 가지고 있기 때문에 그 로드 인스트럭션은 즉시 완료됩니다. + +해당 CPU 는 실제로는 그 값이 필요치 않았다는 사실이 나중에 드러날 수도 있는데 - +해당 로드 인스트럭션이 브랜치로 우회되거나 했을 수 있겠죠 - , 그렇게 되면 앞서 +읽어둔 값을 버리거나 나중의 사용을 위해 캐시에 넣어둘 수 있습니다. + +다음을 생각해 봅시다: + + CPU 1 CPU 2 + ======================= ======================= + LOAD B + DIVIDE } 나누기 명령은 일반적으로 + DIVIDE } 긴 시간을 필요로 합니다 + LOAD A + +는 이렇게 될 수 있습니다: + + : : +-------+ + +-------+ | | + --->| B->2 |------>| | + +-------+ | CPU 2 | + : :DIVIDE | | + +-------+ | | + 나누기 하느라 바쁜 ---> --->| A->0 |~~~~ | | + CPU 는 A 의 LOAD 를 +-------+ ~ | | + 예측해서 수행한다 : : ~ | | + : :DIVIDE | | + : : ~ | | + 나누기가 끝나면 ---> ---> : : ~-->| | + CPU 는 해당 LOAD 를 : : | | + 즉각 완료한다 : : +-------+ + + +읽기 배리어나 데이터 의존성 배리어를 두번째 로드 직전에 놓는다면: + + CPU 1 CPU 2 + ======================= ======================= + LOAD B + DIVIDE + DIVIDE + <읽기 배리어> + LOAD A + +예측으로 얻어진 값은 사용된 배리어의 타입에 따라서 해당 값이 옳은지 검토되게 +됩니다. 만약 해당 메모리 영역에 변화가 없었다면, 예측으로 얻어두었던 값이 +사용됩니다: + + : : +-------+ + +-------+ | | + --->| B->2 |------>| | + +-------+ | CPU 2 | + : :DIVIDE | | + +-------+ | | + 나누기 하느라 바쁜 ---> --->| A->0 |~~~~ | | + CPU 는 A 의 LOAD 를 +-------+ ~ | | + 예측한다 : : ~ | | + : :DIVIDE | | + : : ~ | | + : : ~ | | + rrrrrrrrrrrrrrrr~ | | + : : ~ | | + : : ~-->| | + : : | | + : : +-------+ + + +하지만 다른 CPU 에서 업데이트나 무효화가 있었다면, 그 예측은 무효화되고 그 값은 +다시 읽혀집니다: + + : : +-------+ + +-------+ | | + --->| B->2 |------>| | + +-------+ | CPU 2 | + : :DIVIDE | | + +-------+ | | + 나누기 하느라 바쁜 ---> --->| A->0 |~~~~ | | + CPU 는 A 의 LOAD 를 +-------+ ~ | | + 예측한다 : : ~ | | + : :DIVIDE | | + : : ~ | | + : : ~ | | + rrrrrrrrrrrrrrrrr | | + +-------+ | | + 예측성 동작은 무효화 되고 ---> --->| A->1 |------>| | + 업데이트된 값이 다시 읽혀진다 +-------+ | | + : : +-------+ + + +MULTICOPY 원자성 +---------------- + +Multicopy 원자성은 실제의 컴퓨터 시스템에서 항상 제공되지는 않는, 순서 맞추기에 +대한 상당히 직관적인 개념으로, 특정 스토어가 모든 CPU 들에게 동시에 보여지게 +됨을, 달리 말하자면 모든 CPU 들이 모든 스토어들이 보여지는 순서를 동의하게 되는 +것입니다. 하지만, 완전한 multicopy 원자성의 사용은 가치있는 하드웨어 +최적화들을 무능하게 만들어버릴 수 있어서, 보다 완화된 형태의 ``다른 multicopy +원자성'' 라는 이름의, 특정 스토어가 모든 -다른- CPU 들에게는 동시에 보여지게 +하는 보장을 대신 제공합니다. 이 문서의 뒷부분들은 이 완화된 형태에 대해 논하게 +됩니다만, 단순히 ``multicopy 원자성'' 이라고 부르겠습니다. + +다음의 예가 multicopy 원자성을 보입니다: + + CPU 1 CPU 2 CPU 3 + ======================= ======================= ======================= + { X = 0, Y = 0 } + STORE X=1 r1=LOAD X (reads 1) LOAD Y (reads 1) + <범용 배리어> <읽기 배리어> + STORE Y=r1 LOAD X + +CPU 2 의 Y 로의 스토어에 사용되는 X 로드의 결과가 1 이었고 CPU 3 의 Y 로드가 +1을 리턴했다고 해봅시다. 이는 CPU 1 의 X 로의 스토어가 CPU 2 의 X 로부터의 +로드를 앞서고 CPU 2 의 Y 로의 스토어가 CPU 3 의 Y 로부터의 로드를 앞섬을 +의미합니다. 또한, 여기서의 메모리 배리어들은 CPU 2 가 자신의 로드를 자신의 +스토어 전에 수행하고, CPU 3 가 Y 로부터의 로드를 X 로부터의 로드 전에 수행함을 +보장합니다. 그럼 "CPU 3 의 X 로부터의 로드는 0 을 리턴할 수 있을까요?" + +CPU 3 의 X 로드가 CPU 2 의 로드보다 뒤에 이루어졌으므로, CPU 3 의 X 로부터의 +로드는 1 을 리턴한다고 예상하는게 당연합니다. 이런 예상은 multicopy +원자성으로부터 나옵니다: CPU B 에서 수행된 로드가 CPU A 의 같은 변수로부터의 +로드를 뒤따른다면 (그리고 CPU A 가 자신이 읽은 값으로 먼저 해당 변수에 스토어 +하지 않았다면) multicopy 원자성을 제공하는 시스템에서는, CPU B 의 로드가 CPU A +의 로드와 같은 값 또는 그 나중 값을 리턴해야만 합니다. 하지만, 리눅스 커널은 +시스템들이 multicopy 원자성을 제공할 것을 요구하지 않습니다. + +앞의 범용 메모리 배리어의 사용은 모든 multicopy 원자성의 부족을 보상해줍니다. +앞의 예에서, CPU 2 의 X 로부터의 로드가 1 을 리턴했고 CPU 3 의 Y 로부터의 +로드가 1 을 리턴했다면, CPU 3 의 X 로부터의 로드는 1을 리턴해야만 합니다. + +하지만, 의존성, 읽기 배리어, 쓰기 배리어는 항상 non-multicopy 원자성을 보상해 +주지는 않습니다. 예를 들어, CPU 2 의 범용 배리어가 앞의 예에서 사라져서 +아래처럼 데이터 의존성만 남게 되었다고 해봅시다: + + CPU 1 CPU 2 CPU 3 + ======================= ======================= ======================= + { X = 0, Y = 0 } + STORE X=1 r1=LOAD X (reads 1) LOAD Y (reads 1) + <데이터 의존성> <읽기 배리어> + STORE Y=r1 LOAD X (reads 0) + +이 변화는 non-multicopy 원자성이 만연하게 합니다: 이 예에서, CPU 2 의 X +로부터의 로드가 1을 리턴하고, CPU 3 의 Y 로부터의 로드가 1 을 리턴하는데, CPU 3 +의 X 로부터의 로드가 0 을 리턴하는게 완전히 합법적입니다. + +핵심은, CPU 2 의 데이터 의존성이 자신의 로드와 스토어를 순서짓지만, CPU 1 의 +스토어에 대한 순서는 보장하지 않는다는 것입니다. 따라서, 이 예제가 CPU 1 과 +CPU 2 가 스토어 버퍼나 한 수준의 캐시를 공유하는, multicopy 원자성을 제공하지 +않는 시스템에서 수행된다면 CPU 2 는 CPU 1 의 쓰기에 이른 접근을 할 수도 +있습니다. 따라서, 모든 CPU 들이 여러 접근들의 조합된 순서에 대해서 동의하게 +하기 위해서는 범용 배리어가 필요합니다. + +범용 배리어는 non-multicopy 원자성만 보상할 수 있는게 아니라, -모든- CPU 들이 +-모든- 오퍼레이션들의 순서를 동일하게 인식하게 하는 추가적인 순서 보장을 +만들어냅니다. 반대로, release-acquire 짝의 연결은 이런 추가적인 순서는 +제공하지 않는데, 해당 연결에 들어있는 CPU 들만이 메모리 접근의 조합된 순서에 +대해 동의할 것으로 보장됨을 의미합니다. 예를 들어, 존경스런 Herman Hollerith +의 코드를 C 코드로 변환하면: + + int u, v, x, y, z; + + void cpu0(void) + { + r0 = smp_load_acquire(&x); + WRITE_ONCE(u, 1); + smp_store_release(&y, 1); + } + + void cpu1(void) + { + r1 = smp_load_acquire(&y); + r4 = READ_ONCE(v); + r5 = READ_ONCE(u); + smp_store_release(&z, 1); + } + + void cpu2(void) + { + r2 = smp_load_acquire(&z); + smp_store_release(&x, 1); + } + + void cpu3(void) + { + WRITE_ONCE(v, 1); + smp_mb(); + r3 = READ_ONCE(u); + } + +cpu0(), cpu1(), 그리고 cpu2() 는 smp_store_release()/smp_load_acquire() 쌍의 +연결에 참여되어 있으므로, 다음과 같은 결과는 나오지 않을 겁니다: + + r0 == 1 && r1 == 1 && r2 == 1 + +더 나아가서, cpu0() 와 cpu1() 사이의 release-acquire 관계로 인해, cpu1() 은 +cpu0() 의 쓰기를 봐야만 하므로, 다음과 같은 결과도 없을 겁니다: + + r1 == 1 && r5 == 0 + +하지만, release-acquire 에 의해 제공되는 순서는 해당 연결에 동참한 CPU 들에만 +적용되므로 cpu3() 에, 적어도 스토어들 외에는 적용되지 않습니다. 따라서, 다음과 +같은 결과가 가능합니다: + + r0 == 0 && r1 == 1 && r2 == 1 && r3 == 0 && r4 == 0 + +비슷하게, 다음과 같은 결과도 가능합니다: + + r0 == 0 && r1 == 1 && r2 == 1 && r3 == 0 && r4 == 0 && r5 == 1 + +cpu0(), cpu1(), 그리고 cpu2() 는 그들의 읽기와 쓰기를 순서대로 보게 되지만, +release-acquire 체인에 관여되지 않은 CPU 들은 그 순서에 이견을 가질 수 +있습니다. 이런 이견은 smp_load_acquire() 와 smp_store_release() 의 구현에 +사용되는 완화된 메모리 배리어 인스트럭션들은 항상 배리어 앞의 스토어들을 뒤의 +로드들에 앞세울 필요는 없다는 사실에서 기인합니다. 이 말은 cpu3() 는 cpu0() 의 +u 로의 스토어를 cpu1() 의 v 로부터의 로드 뒤에 일어난 것으로 볼 수 있다는 +뜻입니다, cpu0() 와 cpu1() 은 이 두 오퍼레이션이 의도된 순서대로 일어났음에 +모두 동의하는데도 말입니다. + +하지만, smp_load_acquire() 는 마술이 아님을 명심하시기 바랍니다. 구체적으로, +이 함수는 단순히 순서 규칙을 지키며 인자로부터의 읽기를 수행합니다. 이것은 +어떤 특정한 값이 읽힐 것인지는 보장하지 -않습니다-. 따라서, 다음과 같은 결과도 +가능합니다: + + r0 == 0 && r1 == 0 && r2 == 0 && r5 == 0 + +이런 결과는 어떤 것도 재배치 되지 않는, 순차적 일관성을 가진 가상의 +시스템에서도 일어날 수 있음을 기억해 두시기 바랍니다. + +다시 말하지만, 당신의 코드가 모든 오퍼레이션들의 완전한 순서를 필요로 한다면, +범용 배리어를 사용하십시오. + + +================== +명시적 커널 배리어 +================== + +리눅스 커널은 서로 다른 단계에서 동작하는 다양한 배리어들을 가지고 있습니다: + + (*) 컴파일러 배리어. + + (*) CPU 메모리 배리어. + + (*) MMIO 쓰기 배리어. + + +컴파일러 배리어 +--------------- + +리눅스 커널은 컴파일러가 메모리 액세스를 재배치 하는 것을 막아주는 명시적인 +컴파일러 배리어를 가지고 있습니다: + + barrier(); + +이건 범용 배리어입니다 -- barrier() 의 읽기-읽기 나 쓰기-쓰기 변종은 없습니다. +하지만, READ_ONCE() 와 WRITE_ONCE() 는 특정 액세스들에 대해서만 동작하는 +barrier() 의 완화된 형태로 볼 수 있습니다. + +barrier() 함수는 다음과 같은 효과를 갖습니다: + + (*) 컴파일러가 barrier() 뒤의 액세스들이 barrier() 앞의 액세스보다 앞으로 + 재배치되지 못하게 합니다. 예를 들어, 인터럽트 핸들러 코드와 인터럽트 당한 + 코드 사이의 통신을 신중히 하기 위해 사용될 수 있습니다. + + (*) 루프에서, 컴파일러가 루프 조건에 사용된 변수를 매 이터레이션마다 + 메모리에서 로드하지 않아도 되도록 최적화 하는걸 방지합니다. + +READ_ONCE() 와 WRITE_ONCE() 함수는 싱글 쓰레드 코드에서는 문제 없지만 동시성이 +있는 코드에서는 문제가 될 수 있는 모든 최적화를 막습니다. 이런 류의 최적화에 +대한 예를 몇가지 들어보면 다음과 같습니다: + + (*) 컴파일러는 같은 변수에 대한 로드와 스토어를 재배치 할 수 있고, 어떤 + 경우에는 CPU가 같은 변수로부터의 로드들을 재배치할 수도 있습니다. 이는 + 다음의 코드가: + + a[0] = x; + a[1] = x; + + x 의 예전 값이 a[1] 에, 새 값이 a[0] 에 있게 할 수 있다는 뜻입니다. + 컴파일러와 CPU가 이런 일을 못하게 하려면 다음과 같이 해야 합니다: + + a[0] = READ_ONCE(x); + a[1] = READ_ONCE(x); + + 즉, READ_ONCE() 와 WRITE_ONCE() 는 여러 CPU 에서 하나의 변수에 가해지는 + 액세스들에 캐시 일관성을 제공합니다. + + (*) 컴파일러는 같은 변수에 대한 연속적인 로드들을 병합할 수 있습니다. 그런 + 병합 작업으로 컴파일러는 다음의 코드를: + + while (tmp = a) + do_something_with(tmp); + + 다음과 같이, 싱글 쓰레드 코드에서는 말이 되지만 개발자의 의도와 전혀 맞지 + 않는 방향으로 "최적화" 할 수 있습니다: + + if (tmp = a) + for (;;) + do_something_with(tmp); + + 컴파일러가 이런 짓을 하지 못하게 하려면 READ_ONCE() 를 사용하세요: + + while (tmp = READ_ONCE(a)) + do_something_with(tmp); + + (*) 예컨대 레지스터 사용량이 많아 컴파일러가 모든 데이터를 레지스터에 담을 수 + 없는 경우, 컴파일러는 변수를 다시 로드할 수 있습니다. 따라서 컴파일러는 + 앞의 예에서 변수 'tmp' 사용을 최적화로 없애버릴 수 있습니다: + + while (tmp = a) + do_something_with(tmp); + + 이 코드는 다음과 같이 싱글 쓰레드에서는 완벽하지만 동시성이 존재하는 + 경우엔 치명적인 코드로 바뀔 수 있습니다: + + while (a) + do_something_with(a); + + 예를 들어, 최적화된 이 코드는 변수 a 가 다른 CPU 에 의해 "while" 문과 + do_something_with() 호출 사이에 바뀌어 do_something_with() 에 0을 넘길 + 수도 있습니다. + + 이번에도, 컴파일러가 그런 짓을 하는걸 막기 위해 READ_ONCE() 를 사용하세요: + + while (tmp = READ_ONCE(a)) + do_something_with(tmp); + + 레지스터가 부족한 상황을 겪는 경우, 컴파일러는 tmp 를 스택에 저장해둘 수도 + 있습니다. 컴파일러가 변수를 다시 읽어들이는건 이렇게 저장해두고 후에 다시 + 읽어들이는데 드는 오버헤드 때문입니다. 그렇게 하는게 싱글 쓰레드 + 코드에서는 안전하므로, 안전하지 않은 경우에는 컴파일러에게 직접 알려줘야 + 합니다. + + (*) 컴파일러는 그 값이 무엇일지 알고 있다면 로드를 아예 안할 수도 있습니다. + 예를 들어, 다음의 코드는 변수 'a' 의 값이 항상 0임을 증명할 수 있다면: + + while (tmp = a) + do_something_with(tmp); + + 이렇게 최적화 되어버릴 수 있습니다: + + do { } while (0); + + 이 변환은 싱글 쓰레드 코드에서는 도움이 되는데 로드와 브랜치를 제거했기 + 때문입니다. 문제는 컴파일러가 'a' 의 값을 업데이트 하는건 현재의 CPU 하나 + 뿐이라는 가정 위에서 증명을 했다는데 있습니다. 만약 변수 'a' 가 공유되어 + 있다면, 컴파일러의 증명은 틀린 것이 될겁니다. 컴파일러는 그 자신이 + 생각하는 것만큼 많은 것을 알고 있지 못함을 컴파일러에게 알리기 위해 + READ_ONCE() 를 사용하세요: + + while (tmp = READ_ONCE(a)) + do_something_with(tmp); + + 하지만 컴파일러는 READ_ONCE() 뒤에 나오는 값에 대해서도 눈길을 두고 있음을 + 기억하세요. 예를 들어, 다음의 코드에서 MAX 는 전처리기 매크로로, 1의 값을 + 갖는다고 해봅시다: + + while ((tmp = READ_ONCE(a)) % MAX) + do_something_with(tmp); + + 이렇게 되면 컴파일러는 MAX 를 가지고 수행되는 "%" 오퍼레이터의 결과가 항상 + 0이라는 것을 알게 되고, 컴파일러가 코드를 실질적으로는 존재하지 않는 + 것처럼 최적화 하는 것이 허용되어 버립니다. ('a' 변수의 로드는 여전히 + 행해질 겁니다.) + + (*) 비슷하게, 컴파일러는 변수가 저장하려 하는 값을 이미 가지고 있다는 것을 + 알면 스토어 자체를 제거할 수 있습니다. 이번에도, 컴파일러는 현재의 CPU + 만이 그 변수에 값을 쓰는 오로지 하나의 존재라고 생각하여 공유된 변수에 + 대해서는 잘못된 일을 하게 됩니다. 예를 들어, 다음과 같은 경우가 있을 수 + 있습니다: + + a = 0; + ... 변수 a 에 스토어를 하지 않는 코드 ... + a = 0; + + 컴파일러는 변수 'a' 의 값은 이미 0이라는 것을 알고, 따라서 두번째 스토어를 + 삭제할 겁니다. 만약 다른 CPU 가 그 사이 변수 'a' 에 다른 값을 썼다면 + 황당한 결과가 나올 겁니다. + + 컴파일러가 그런 잘못된 추측을 하지 않도록 WRITE_ONCE() 를 사용하세요: + + WRITE_ONCE(a, 0); + ... 변수 a 에 스토어를 하지 않는 코드 ... + WRITE_ONCE(a, 0); + + (*) 컴파일러는 하지 말라고 하지 않으면 메모리 액세스들을 재배치 할 수 + 있습니다. 예를 들어, 다음의 프로세스 레벨 코드와 인터럽트 핸들러 사이의 + 상호작용을 생각해 봅시다: + + void process_level(void) + { + msg = get_message(); + flag = true; + } + + void interrupt_handler(void) + { + if (flag) + process_message(msg); + } + + 이 코드에는 컴파일러가 process_level() 을 다음과 같이 변환하는 것을 막을 + 수단이 없고, 이런 변환은 싱글쓰레드에서라면 실제로 훌륭한 선택일 수 + 있습니다: + + void process_level(void) + { + flag = true; + msg = get_message(); + } + + 이 두개의 문장 사이에 인터럽트가 발생한다면, interrupt_handler() 는 의미를 + 알 수 없는 메세지를 받을 수도 있습니다. 이걸 막기 위해 다음과 같이 + WRITE_ONCE() 를 사용하세요: + + void process_level(void) + { + WRITE_ONCE(msg, get_message()); + WRITE_ONCE(flag, true); + } + + void interrupt_handler(void) + { + if (READ_ONCE(flag)) + process_message(READ_ONCE(msg)); + } + + interrupt_handler() 안에서도 중첩된 인터럽트나 NMI 와 같이 인터럽트 핸들러 + 역시 'flag' 와 'msg' 에 접근하는 또다른 무언가에 인터럽트 될 수 있다면 + READ_ONCE() 와 WRITE_ONCE() 를 사용해야 함을 기억해 두세요. 만약 그런 + 가능성이 없다면, interrupt_handler() 안에서는 문서화 목적이 아니라면 + READ_ONCE() 와 WRITE_ONCE() 는 필요치 않습니다. (근래의 리눅스 커널에서 + 중첩된 인터럽트는 보통 잘 일어나지 않음도 기억해 두세요, 실제로, 어떤 + 인터럽트 핸들러가 인터럽트가 활성화된 채로 리턴하면 WARN_ONCE() 가 + 실행됩니다.) + + 컴파일러는 READ_ONCE() 와 WRITE_ONCE() 뒤의 READ_ONCE() 나 WRITE_ONCE(), + barrier(), 또는 비슷한 것들을 담고 있지 않은 코드를 움직일 수 있을 것으로 + 가정되어야 합니다. + + 이 효과는 barrier() 를 통해서도 만들 수 있지만, READ_ONCE() 와 + WRITE_ONCE() 가 좀 더 안목 높은 선택입니다: READ_ONCE() 와 WRITE_ONCE()는 + 컴파일러에 주어진 메모리 영역에 대해서만 최적화 가능성을 포기하도록 + 하지만, barrier() 는 컴파일러가 지금까지 기계의 레지스터에 캐시해 놓은 + 모든 메모리 영역의 값을 버려야 하게 하기 때문입니다. 물론, 컴파일러는 + READ_ONCE() 와 WRITE_ONCE() 가 일어난 순서도 지켜줍니다, CPU 는 당연히 + 그 순서를 지킬 의무가 없지만요. + + (*) 컴파일러는 다음의 예에서와 같이 변수에의 스토어를 날조해낼 수도 있습니다: + + if (a) + b = a; + else + b = 42; + + 컴파일러는 아래와 같은 최적화로 브랜치를 줄일 겁니다: + + b = 42; + if (a) + b = a; + + 싱글 쓰레드 코드에서 이 최적화는 안전할 뿐 아니라 브랜치 갯수를 + 줄여줍니다. 하지만 안타깝게도, 동시성이 있는 코드에서는 이 최적화는 다른 + CPU 가 'b' 를 로드할 때, -- 'a' 가 0이 아닌데도 -- 가짜인 값, 42를 보게 + 되는 경우를 가능하게 합니다. 이걸 방지하기 위해 WRITE_ONCE() 를 + 사용하세요: + + if (a) + WRITE_ONCE(b, a); + else + WRITE_ONCE(b, 42); + + 컴파일러는 로드를 만들어낼 수도 있습니다. 일반적으로는 문제를 일으키지 + 않지만, 캐시 라인 바운싱을 일으켜 성능과 확장성을 떨어뜨릴 수 있습니다. + 날조된 로드를 막기 위해선 READ_ONCE() 를 사용하세요. + + (*) 정렬된 메모리 주소에 위치한, 한번의 메모리 참조 인스트럭션으로 액세스 + 가능한 크기의 데이터는 하나의 큰 액세스가 여러개의 작은 액세스들로 + 대체되는 "로드 티어링(load tearing)" 과 "스토어 티어링(store tearing)" 을 + 방지합니다. 예를 들어, 주어진 아키텍쳐가 7-bit imeediate field 를 갖는 + 16-bit 스토어 인스트럭션을 제공한다면, 컴파일러는 다음의 32-bit 스토어를 + 구현하는데에 두개의 16-bit store-immediate 명령을 사용하려 할겁니다: + + p = 0x00010002; + + 스토어 할 상수를 만들고 그 값을 스토어 하기 위해 두개가 넘는 인스트럭션을 + 사용하게 되는, 이런 종류의 최적화를 GCC 는 실제로 함을 부디 알아 두십시오. + 이 최적화는 싱글 쓰레드 코드에서는 성공적인 최적화 입니다. 실제로, 근래에 + 발생한 (그리고 고쳐진) 버그는 GCC 가 volatile 스토어에 비정상적으로 이 + 최적화를 사용하게 했습니다. 그런 버그가 없다면, 다음의 예에서 + WRITE_ONCE() 의 사용은 스토어 티어링을 방지합니다: + + WRITE_ONCE(p, 0x00010002); + + Packed 구조체의 사용 역시 다음의 예처럼 로드 / 스토어 티어링을 유발할 수 + 있습니다: + + struct __attribute__((__packed__)) foo { + short a; + int b; + short c; + }; + struct foo foo1, foo2; + ... + + foo2.a = foo1.a; + foo2.b = foo1.b; + foo2.c = foo1.c; + + READ_ONCE() 나 WRITE_ONCE() 도 없고 volatile 마킹도 없기 때문에, + 컴파일러는 이 세개의 대입문을 두개의 32-bit 로드와 두개의 32-bit 스토어로 + 변환할 수 있습니다. 이는 'foo1.b' 의 값의 로드 티어링과 'foo2.b' 의 + 스토어 티어링을 초래할 겁니다. 이 예에서도 READ_ONCE() 와 WRITE_ONCE() + 가 티어링을 막을 수 있습니다: + + foo2.a = foo1.a; + WRITE_ONCE(foo2.b, READ_ONCE(foo1.b)); + foo2.c = foo1.c; + +그렇지만, volatile 로 마크된 변수에 대해서는 READ_ONCE() 와 WRITE_ONCE() 가 +필요치 않습니다. 예를 들어, 'jiffies' 는 volatile 로 마크되어 있기 때문에, +READ_ONCE(jiffies) 라고 할 필요가 없습니다. READ_ONCE() 와 WRITE_ONCE() 가 +실은 volatile 캐스팅으로 구현되어 있어서 인자가 이미 volatile 로 마크되어 +있다면 또다른 효과를 내지는 않기 때문입니다. + +이 컴파일러 배리어들은 CPU 에는 직접적 효과를 전혀 만들지 않기 때문에, 결국은 +재배치가 일어날 수도 있음을 부디 기억해 두십시오. + + +CPU 메모리 배리어 +----------------- + +리눅스 커널은 다음의 여덟개 기본 CPU 메모리 배리어를 가지고 있습니다: + + TYPE MANDATORY SMP CONDITIONAL + =============== ======================= =========================== + 범용 mb() smp_mb() + 쓰기 wmb() smp_wmb() + 읽기 rmb() smp_rmb() + 데이터 의존성 READ_ONCE() + + +데이터 의존성 배리어를 제외한 모든 메모리 배리어는 컴파일러 배리어를 +포함합니다. 데이터 의존성은 컴파일러에의 추가적인 순서 보장을 포함하지 +않습니다. + +방백: 데이터 의존성이 있는 경우, 컴파일러는 해당 로드를 올바른 순서로 일으킬 +것으로 (예: `a[b]` 는 a[b] 를 로드 하기 전에 b 의 값을 먼저 로드한다) +기대되지만, C 언어 사양에는 컴파일러가 b 의 값을 추측 (예: 1 과 같음) 해서 +b 로드 전에 a 로드를 하는 코드 (예: tmp = a[1]; if (b != 1) tmp = a[b]; ) 를 +만들지 않아야 한다는 내용 같은 건 없습니다. 또한 컴파일러는 a[b] 를 로드한 +후에 b 를 또다시 로드할 수도 있어서, a[b] 보다 최신 버전의 b 값을 가질 수도 +있습니다. 이런 문제들의 해결책에 대한 의견 일치는 아직 없습니다만, 일단 +READ_ONCE() 매크로부터 보기 시작하는게 좋은 시작이 될겁니다. + +SMP 메모리 배리어들은 유니프로세서로 컴파일된 시스템에서는 컴파일러 배리어로 +바뀌는데, 하나의 CPU 는 스스로 일관성을 유지하고, 겹치는 액세스들 역시 올바른 +순서로 행해질 것으로 생각되기 때문입니다. 하지만, 아래의 "Virtual Machine +Guests" 서브섹션을 참고하십시오. + +[!] SMP 시스템에서 공유메모리로의 접근들을 순서 세워야 할 때, SMP 메모리 +배리어는 _반드시_ 사용되어야 함을 기억하세요, 그대신 락을 사용하는 것으로도 +충분하긴 하지만 말이죠. + +Mandatory 배리어들은 SMP 시스템에서도 UP 시스템에서도 SMP 효과만 통제하기에는 +불필요한 오버헤드를 갖기 때문에 SMP 효과만 통제하면 되는 곳에는 사용되지 않아야 +합니다. 하지만, 느슨한 순서 규칙의 메모리 I/O 윈도우를 통한 MMIO 의 효과를 +통제할 때에는 mandatory 배리어들이 사용될 수 있습니다. 이 배리어들은 +컴파일러와 CPU 모두 재배치를 못하도록 함으로써 메모리 오퍼레이션들이 디바이스에 +보여지는 순서에도 영향을 주기 때문에, SMP 가 아닌 시스템이라 할지라도 필요할 수 +있습니다. + + +일부 고급 배리어 함수들도 있습니다: + + (*) smp_store_mb(var, value) + + 이 함수는 특정 변수에 특정 값을 대입하고 범용 메모리 배리어를 칩니다. + UP 컴파일에서는 컴파일러 배리어보다 더한 것을 친다고는 보장되지 않습니다. + + + (*) smp_mb__before_atomic(); + (*) smp_mb__after_atomic(); + + 이것들은 값을 리턴하지 않는 (더하기, 빼기, 증가, 감소와 같은) 어토믹 + 함수들을 위한, 특히 그것들이 레퍼런스 카운팅에 사용될 때를 위한 + 함수들입니다. 이 함수들은 메모리 배리어를 내포하고 있지는 않습니다. + + 이것들은 값을 리턴하지 않으며 어토믹한 (set_bit 과 clear_bit 같은) 비트 + 연산에도 사용될 수 있습니다. + + 한 예로, 객체 하나를 무효한 것으로 표시하고 그 객체의 레퍼런스 카운트를 + 감소시키는 다음 코드를 보세요: + + obj->dead = 1; + smp_mb__before_atomic(); + atomic_dec(&obj->ref_count); + + 이 코드는 객체의 업데이트된 death 마크가 레퍼런스 카운터 감소 동작 + *전에* 보일 것을 보장합니다. + + 더 많은 정보를 위해선 Documentation/atomic_{t,bitops}.txt 문서를 + 참고하세요. + + + (*) dma_wmb(); + (*) dma_rmb(); + + 이것들은 CPU 와 DMA 가능한 디바이스에서 모두 액세스 가능한 공유 메모리의 + 읽기, 쓰기 작업들의 순서를 보장하기 위해 consistent memory 에서 사용하기 + 위한 것들입니다. + + 예를 들어, 디바이스와 메모리를 공유하며, 디스크립터 상태 값을 사용해 + 디스크립터가 디바이스에 속해 있는지 아니면 CPU 에 속해 있는지 표시하고, + 공지용 초인종(doorbell) 을 사용해 업데이트된 디스크립터가 디바이스에 사용 + 가능해졌음을 공지하는 디바이스 드라이버를 생각해 봅시다: + + if (desc->status != DEVICE_OWN) { + /* 디스크립터를 소유하기 전에는 데이터를 읽지 않음 */ + dma_rmb(); + + /* 데이터를 읽고 씀 */ + read_data = desc->data; + desc->data = write_data; + + /* 상태 업데이트 전 수정사항을 반영 */ + dma_wmb(); + + /* 소유권을 수정 */ + desc->status = DEVICE_OWN; + + /* 업데이트된 디스크립터의 디바이스에 공지 */ + writel(DESC_NOTIFY, doorbell); + } + + dma_rmb() 는 디스크립터로부터 데이터를 읽어오기 전에 디바이스가 소유권을 + 내려놓았을 것을 보장하고, dma_wmb() 는 디바이스가 자신이 소유권을 다시 + 가졌음을 보기 전에 디스크립터에 데이터가 쓰였을 것을 보장합니다. 참고로, + writel() 을 사용하면 캐시 일관성이 있는 메모리 (cache coherent memory) + 쓰기가 MMIO 영역에의 쓰기 전에 완료되었을 것을 보장하므로 writel() 앞에 + wmb() 를 실행할 필요가 없음을 알아두시기 바랍니다. writel() 보다 비용이 + 저렴한 writel_relaxed() 는 이런 보장을 제공하지 않으므로 여기선 사용되지 + 않아야 합니다. + + writel_relaxed() 와 같은 완화된 I/O 접근자들에 대한 자세한 내용을 위해서는 + "커널 I/O 배리어의 효과" 섹션을, consistent memory 에 대한 자세한 내용을 + 위해선 Documentation/DMA-API.txt 문서를 참고하세요. + + +MMIO 쓰기 배리어 +---------------- + +리눅스 커널은 또한 memory-mapped I/O 쓰기를 위한 특별한 배리어도 가지고 +있습니다: + + mmiowb(); + +이것은 mandatory 쓰기 배리어의 변종으로, 완화된 순서 규칙의 I/O 영역에으로의 +쓰기가 부분적으로 순서를 맞추도록 해줍니다. 이 함수는 CPU->하드웨어 사이를 +넘어서 실제 하드웨어에까지 일부 수준의 영향을 끼칩니다. + +더 많은 정보를 위해선 "Acquire vs I/O 액세스" 서브섹션을 참고하세요. + + +========================= +암묵적 커널 메모리 배리어 +========================= + +리눅스 커널의 일부 함수들은 메모리 배리어를 내장하고 있는데, 락(lock)과 +스케쥴링 관련 함수들이 대부분입니다. + +여기선 _최소한의_ 보장을 설명합니다; 특정 아키텍쳐에서는 이 설명보다 더 많은 +보장을 제공할 수도 있습니다만 해당 아키텍쳐에 종속적인 코드 외의 부분에서는 +그런 보장을 기대해선 안될겁니다. + + +락 ACQUISITION 함수 +------------------- + +리눅스 커널은 다양한 락 구성체를 가지고 있습니다: + + (*) 스핀 락 + (*) R/W 스핀 락 + (*) 뮤텍스 + (*) 세마포어 + (*) R/W 세마포어 + +각 구성체마다 모든 경우에 "ACQUIRE" 오퍼레이션과 "RELEASE" 오퍼레이션의 변종이 +존재합니다. 이 오퍼레이션들은 모두 적절한 배리어를 내포하고 있습니다: + + (1) ACQUIRE 오퍼레이션의 영향: + + ACQUIRE 뒤에서 요청된 메모리 오퍼레이션은 ACQUIRE 오퍼레이션이 완료된 + 뒤에 완료됩니다. + + ACQUIRE 앞에서 요청된 메모리 오퍼레이션은 ACQUIRE 오퍼레이션이 완료된 후에 + 완료될 수 있습니다. + + (2) RELEASE 오퍼레이션의 영향: + + RELEASE 앞에서 요청된 메모리 오퍼레이션은 RELEASE 오퍼레이션이 완료되기 + 전에 완료됩니다. + + RELEASE 뒤에서 요청된 메모리 오퍼레이션은 RELEASE 오퍼레이션 완료 전에 + 완료될 수 있습니다. + + (3) ACQUIRE vs ACQUIRE 영향: + + 어떤 ACQUIRE 오퍼레이션보다 앞에서 요청된 모든 ACQUIRE 오퍼레이션은 그 + ACQUIRE 오퍼레이션 전에 완료됩니다. + + (4) ACQUIRE vs RELEASE implication: + + 어떤 RELEASE 오퍼레이션보다 앞서 요청된 ACQUIRE 오퍼레이션은 그 RELEASE + 오퍼레이션보다 먼저 완료됩니다. + + (5) 실패한 조건적 ACQUIRE 영향: + + ACQUIRE 오퍼레이션의 일부 락(lock) 변종은 락이 곧바로 획득하기에는 + 불가능한 상태이거나 락이 획득 가능해지도록 기다리는 도중 시그널을 받거나 + 해서 실패할 수 있습니다. 실패한 락은 어떤 배리어도 내포하지 않습니다. + +[!] 참고: 락 ACQUIRE 와 RELEASE 가 단방향 배리어여서 나타나는 현상 중 하나는 +크리티컬 섹션 바깥의 인스트럭션의 영향이 크리티컬 섹션 내부로도 들어올 수 +있다는 것입니다. + +RELEASE 후에 요청되는 ACQUIRE 는 전체 메모리 배리어라 여겨지면 안되는데, +ACQUIRE 앞의 액세스가 ACQUIRE 후에 수행될 수 있고, RELEASE 후의 액세스가 +RELEASE 전에 수행될 수도 있으며, 그 두개의 액세스가 서로를 지나칠 수도 있기 +때문입니다: + + *A = a; + ACQUIRE M + RELEASE M + *B = b; + +는 다음과 같이 될 수도 있습니다: + + ACQUIRE M, STORE *B, STORE *A, RELEASE M + +ACQUIRE 와 RELEASE 가 락 획득과 해제라면, 그리고 락의 ACQUIRE 와 RELEASE 가 +같은 락 변수에 대한 것이라면, 해당 락을 쥐고 있지 않은 다른 CPU 의 시야에는 +이와 같은 재배치가 일어나는 것으로 보일 수 있습니다. 요약하자면, ACQUIRE 에 +이어 RELEASE 오퍼레이션을 순차적으로 실행하는 행위가 전체 메모리 배리어로 +생각되어선 -안됩니다-. + +비슷하게, 앞의 반대 케이스인 RELEASE 와 ACQUIRE 두개 오퍼레이션의 순차적 실행 +역시 전체 메모리 배리어를 내포하지 않습니다. 따라서, RELEASE, ACQUIRE 로 +규정되는 크리티컬 섹션의 CPU 수행은 RELEASE 와 ACQUIRE 를 가로지를 수 있으므로, +다음과 같은 코드는: + + *A = a; + RELEASE M + ACQUIRE N + *B = b; + +다음과 같이 수행될 수 있습니다: + + ACQUIRE N, STORE *B, STORE *A, RELEASE M + +이런 재배치는 데드락을 일으킬 수도 있을 것처럼 보일 수 있습니다. 하지만, 그런 +데드락의 조짐이 있다면 RELEASE 는 단순히 완료될 것이므로 데드락은 존재할 수 +없습니다. + + 이게 어떻게 올바른 동작을 할 수 있을까요? + + 우리가 이야기 하고 있는건 재배치를 하는 CPU 에 대한 이야기이지, + 컴파일러에 대한 것이 아니란 점이 핵심입니다. 컴파일러 (또는, 개발자) + 가 오퍼레이션들을 이렇게 재배치하면, 데드락이 일어날 수 -있습-니다. + + 하지만 CPU 가 오퍼레이션들을 재배치 했다는걸 생각해 보세요. 이 예에서, + 어셈블리 코드 상으로는 언락이 락을 앞서게 되어 있습니다. CPU 가 이를 + 재배치해서 뒤의 락 오퍼레이션을 먼저 실행하게 됩니다. 만약 데드락이 + 존재한다면, 이 락 오퍼레이션은 그저 스핀을 하며 계속해서 락을 + 시도합니다 (또는, 한참 후에겠지만, 잠듭니다). CPU 는 언젠가는 + (어셈블리 코드에서는 락을 앞서는) 언락 오퍼레이션을 실행하는데, 이 언락 + 오퍼레이션이 잠재적 데드락을 해결하고, 락 오퍼레이션도 뒤이어 성공하게 + 됩니다. + + 하지만 만약 락이 잠을 자는 타입이었다면요? 그런 경우에 코드는 + 스케쥴러로 들어가려 할 거고, 여기서 결국은 메모리 배리어를 만나게 + 되는데, 이 메모리 배리어는 앞의 언락 오퍼레이션이 완료되도록 만들고, + 데드락은 이번에도 해결됩니다. 잠을 자는 행위와 언락 사이의 경주 상황 + (race) 도 있을 수 있겠습니다만, 락 관련 기능들은 그런 경주 상황을 모든 + 경우에 제대로 해결할 수 있어야 합니다. + +락과 세마포어는 UP 컴파일된 시스템에서의 순서에 대해 보장을 하지 않기 때문에, +그런 상황에서 인터럽트 비활성화 오퍼레이션과 함께가 아니라면 어떤 일에도 - 특히 +I/O 액세스와 관련해서는 - 제대로 사용될 수 없을 겁니다. + +"CPU 간 ACQUIRING 배리어 효과" 섹션도 참고하시기 바랍니다. + + +예를 들어, 다음과 같은 코드를 생각해 봅시다: + + *A = a; + *B = b; + ACQUIRE + *C = c; + *D = d; + RELEASE + *E = e; + *F = f; + +여기선 다음의 이벤트 시퀀스가 생길 수 있습니다: + + ACQUIRE, {*F,*A}, *E, {*C,*D}, *B, RELEASE + + [+] {*F,*A} 는 조합된 액세스를 의미합니다. + +하지만 다음과 같은 건 불가능하죠: + + {*F,*A}, *B, ACQUIRE, *C, *D, RELEASE, *E + *A, *B, *C, ACQUIRE, *D, RELEASE, *E, *F + *A, *B, ACQUIRE, *C, RELEASE, *D, *E, *F + *B, ACQUIRE, *C, *D, RELEASE, {*F,*A}, *E + + + +인터럽트 비활성화 함수 +---------------------- + +인터럽트를 비활성화 하는 함수 (ACQUIRE 와 동일) 와 인터럽트를 활성화 하는 함수 +(RELEASE 와 동일) 는 컴파일러 배리어처럼만 동작합니다. 따라서, 별도의 메모리 +배리어나 I/O 배리어가 필요한 상황이라면 그 배리어들은 인터럽트 비활성화 함수 +외의 방법으로 제공되어야만 합니다. + + +슬립과 웨이크업 함수 +-------------------- + +글로벌 데이터에 표시된 이벤트에 의해 프로세스를 잠에 빠트리는 것과 깨우는 것은 +해당 이벤트를 기다리는 태스크의 태스크 상태와 그 이벤트를 알리기 위해 사용되는 +글로벌 데이터, 두 데이터간의 상호작용으로 볼 수 있습니다. 이것이 옳은 순서대로 +일어남을 분명히 하기 위해, 프로세스를 잠에 들게 하는 기능과 깨우는 기능은 +몇가지 배리어를 내포합니다. + +먼저, 잠을 재우는 쪽은 일반적으로 다음과 같은 이벤트 시퀀스를 따릅니다: + + for (;;) { + set_current_state(TASK_UNINTERRUPTIBLE); + if (event_indicated) + break; + schedule(); + } + +set_current_state() 에 의해, 태스크 상태가 바뀐 후 범용 메모리 배리어가 +자동으로 삽입됩니다: + + CPU 1 + =============================== + set_current_state(); + smp_store_mb(); + STORE current->state + <범용 배리어> + LOAD event_indicated + +set_current_state() 는 다음의 것들로 감싸질 수도 있습니다: + + prepare_to_wait(); + prepare_to_wait_exclusive(); + +이것들 역시 상태를 설정한 후 범용 메모리 배리어를 삽입합니다. +앞의 전체 시퀀스는 다음과 같은 함수들로 한번에 수행 가능한데, 이것들은 모두 +올바른 장소에 메모리 배리어를 삽입합니다: + + wait_event(); + wait_event_interruptible(); + wait_event_interruptible_exclusive(); + wait_event_interruptible_timeout(); + wait_event_killable(); + wait_event_timeout(); + wait_on_bit(); + wait_on_bit_lock(); + + +두번째로, 깨우기를 수행하는 코드는 일반적으로 다음과 같을 겁니다: + + event_indicated = 1; + wake_up(&event_wait_queue); + +또는: + + event_indicated = 1; + wake_up_process(event_daemon); + +wake_up() 류에 의해 쓰기 메모리 배리어가 내포됩니다. 만약 그것들이 뭔가를 +깨운다면요. 이 배리어는 태스크 상태가 지워지기 전에 수행되므로, 이벤트를 +알리기 위한 STORE 와 태스크 상태를 TASK_RUNNING 으로 설정하는 STORE 사이에 +위치하게 됩니다. + + CPU 1 CPU 2 + =============================== =============================== + set_current_state(); STORE event_indicated + smp_store_mb(); wake_up(); + STORE current->state <쓰기 배리어> + <범용 배리어> STORE current->state + LOAD event_indicated + +한번더 말합니다만, 이 쓰기 메모리 배리어는 이 코드가 정말로 뭔가를 깨울 때에만 +실행됩니다. 이걸 설명하기 위해, X 와 Y 는 모두 0 으로 초기화 되어 있다는 가정 +하에 아래의 이벤트 시퀀스를 생각해 봅시다: + + CPU 1 CPU 2 + =============================== =============================== + X = 1; STORE event_indicated + smp_mb(); wake_up(); + Y = 1; wait_event(wq, Y == 1); + wake_up(); load from Y sees 1, no memory barrier + load from X might see 0 + +위 예제에서의 경우와 달리 깨우기가 정말로 행해졌다면, CPU 2 의 X 로드는 1 을 +본다고 보장될 수 있을 겁니다. + +사용 가능한 깨우기류 함수들로 다음과 같은 것들이 있습니다: + + complete(); + wake_up(); + wake_up_all(); + wake_up_bit(); + wake_up_interruptible(); + wake_up_interruptible_all(); + wake_up_interruptible_nr(); + wake_up_interruptible_poll(); + wake_up_interruptible_sync(); + wake_up_interruptible_sync_poll(); + wake_up_locked(); + wake_up_locked_poll(); + wake_up_nr(); + wake_up_poll(); + wake_up_process(); + + +[!] 잠재우는 코드와 깨우는 코드에 내포되는 메모리 배리어들은 깨우기 전에 +이루어진 스토어를 잠재우는 코드가 set_current_state() 를 호출한 후에 행하는 +로드에 대해 순서를 맞추지 _않는다는_ 점을 기억하세요. 예를 들어, 잠재우는 +코드가 다음과 같고: + + set_current_state(TASK_INTERRUPTIBLE); + if (event_indicated) + break; + __set_current_state(TASK_RUNNING); + do_something(my_data); + +깨우는 코드는 다음과 같다면: + + my_data = value; + event_indicated = 1; + wake_up(&event_wait_queue); + +event_indecated 에의 변경이 잠재우는 코드에게 my_data 에의 변경 후에 이루어진 +것으로 인지될 것이라는 보장이 없습니다. 이런 경우에는 양쪽 코드 모두 각각의 +데이터 액세스 사이에 메모리 배리어를 직접 쳐야 합니다. 따라서 앞의 재우는 +코드는 다음과 같이: + + set_current_state(TASK_INTERRUPTIBLE); + if (event_indicated) { + smp_rmb(); + do_something(my_data); + } + +그리고 깨우는 코드는 다음과 같이 되어야 합니다: + + my_data = value; + smp_wmb(); + event_indicated = 1; + wake_up(&event_wait_queue); + + +그외의 함수들 +------------- + +그외의 배리어를 내포하는 함수들은 다음과 같습니다: + + (*) schedule() 과 그 유사한 것들이 완전한 메모리 배리어를 내포합니다. + + +============================== +CPU 간 ACQUIRING 배리어의 효과 +============================== + +SMP 시스템에서의 락 기능들은 더욱 강력한 형태의 배리어를 제공합니다: 이 +배리어는 동일한 락을 사용하는 다른 CPU 들의 메모리 액세스 순서에도 영향을 +끼칩니다. + + +ACQUIRE VS 메모리 액세스 +------------------------ + +다음의 예를 생각해 봅시다: 시스템은 두개의 스핀락 (M) 과 (Q), 그리고 세개의 CPU +를 가지고 있습니다; 여기에 다음의 이벤트 시퀀스가 발생합니다: + + CPU 1 CPU 2 + =============================== =============================== + WRITE_ONCE(*A, a); WRITE_ONCE(*E, e); + ACQUIRE M ACQUIRE Q + WRITE_ONCE(*B, b); WRITE_ONCE(*F, f); + WRITE_ONCE(*C, c); WRITE_ONCE(*G, g); + RELEASE M RELEASE Q + WRITE_ONCE(*D, d); WRITE_ONCE(*H, h); + +*A 로의 액세스부터 *H 로의 액세스까지가 어떤 순서로 CPU 3 에게 보여질지에 +대해서는 각 CPU 에서의 락 사용에 의해 내포되어 있는 제약을 제외하고는 어떤 +보장도 존재하지 않습니다. 예를 들어, CPU 3 에게 다음과 같은 순서로 보여지는 +것이 가능합니다: + + *E, ACQUIRE M, ACQUIRE Q, *G, *C, *F, *A, *B, RELEASE Q, *D, *H, RELEASE M + +하지만 다음과 같이 보이지는 않을 겁니다: + + *B, *C or *D preceding ACQUIRE M + *A, *B or *C following RELEASE M + *F, *G or *H preceding ACQUIRE Q + *E, *F or *G following RELEASE Q + + + +ACQUIRE VS I/O 액세스 +---------------------- + +특정한 (특히 NUMA 가 관련된) 환경 하에서 두개의 CPU 에서 동일한 스핀락으로 +보호되는 두개의 크리티컬 섹션 안의 I/O 액세스는 PCI 브릿지에 겹쳐진 I/O +액세스로 보일 수 있는데, PCI 브릿지는 캐시 일관성 프로토콜과 합을 맞춰야 할 +의무가 없으므로, 필요한 읽기 메모리 배리어가 요청되지 않기 때문입니다. + +예를 들어서: + + CPU 1 CPU 2 + =============================== =============================== + spin_lock(Q) + writel(0, ADDR) + writel(1, DATA); + spin_unlock(Q); + spin_lock(Q); + writel(4, ADDR); + writel(5, DATA); + spin_unlock(Q); + +는 PCI 브릿지에 다음과 같이 보일 수 있습니다: + + STORE *ADDR = 0, STORE *ADDR = 4, STORE *DATA = 1, STORE *DATA = 5 + +이렇게 되면 하드웨어의 오동작을 일으킬 수 있습니다. + + +이런 경우엔 잡아둔 스핀락을 내려놓기 전에 mmiowb() 를 수행해야 하는데, 예를 +들면 다음과 같습니다: + + CPU 1 CPU 2 + =============================== =============================== + spin_lock(Q) + writel(0, ADDR) + writel(1, DATA); + mmiowb(); + spin_unlock(Q); + spin_lock(Q); + writel(4, ADDR); + writel(5, DATA); + mmiowb(); + spin_unlock(Q); + +이 코드는 CPU 1 에서 요청된 두개의 스토어가 PCI 브릿지에 CPU 2 에서 요청된 +스토어들보다 먼저 보여짐을 보장합니다. + + +또한, 같은 디바이스에서 스토어를 이어 로드가 수행되면 이 로드는 로드가 수행되기 +전에 스토어가 완료되기를 강제하므로 mmiowb() 의 필요가 없어집니다: + + CPU 1 CPU 2 + =============================== =============================== + spin_lock(Q) + writel(0, ADDR) + a = readl(DATA); + spin_unlock(Q); + spin_lock(Q); + writel(4, ADDR); + b = readl(DATA); + spin_unlock(Q); + + +더 많은 정보를 위해선 Documentation/driver-api/device-io.rst 를 참고하세요. + + +========================= +메모리 배리어가 필요한 곳 +========================= + +설령 SMP 커널을 사용하더라도 싱글 쓰레드로 동작하는 코드는 올바르게 동작하는 +것으로 보여질 것이기 때문에, 평범한 시스템 운영중에 메모리 오퍼레이션 재배치는 +일반적으로 문제가 되지 않습니다. 하지만, 재배치가 문제가 _될 수 있는_ 네가지 +환경이 있습니다: + + (*) 프로세서간 상호 작용. + + (*) 어토믹 오퍼레이션. + + (*) 디바이스 액세스. + + (*) 인터럽트. + + +프로세서간 상호 작용 +-------------------- + +두개 이상의 프로세서를 가진 시스템이 있다면, 시스템의 두개 이상의 CPU 는 동시에 +같은 데이터에 대한 작업을 할 수 있습니다. 이는 동기화 문제를 일으킬 수 있고, +이 문제를 해결하는 일반적 방법은 락을 사용하는 것입니다. 하지만, 락은 상당히 +비용이 비싸서 가능하면 락을 사용하지 않고 일을 처리하는 것이 낫습니다. 이런 +경우, 두 CPU 모두에 영향을 끼치는 오퍼레이션들은 오동작을 막기 위해 신중하게 +순서가 맞춰져야 합니다. + +예를 들어, R/W 세마포어의 느린 수행경로 (slow path) 를 생각해 봅시다. +세마포어를 위해 대기를 하는 하나의 프로세스가 자신의 스택 중 일부를 이 +세마포어의 대기 프로세스 리스트에 링크한 채로 있습니다: + + struct rw_semaphore { + ... + spinlock_t lock; + struct list_head waiters; + }; + + struct rwsem_waiter { + struct list_head list; + struct task_struct *task; + }; + +특정 대기 상태 프로세스를 깨우기 위해, up_read() 나 up_write() 함수는 다음과 +같은 일을 합니다: + + (1) 다음 대기 상태 프로세스 레코드는 어디있는지 알기 위해 이 대기 상태 + 프로세스 레코드의 next 포인터를 읽습니다; + + (2) 이 대기 상태 프로세스의 task 구조체로의 포인터를 읽습니다; + + (3) 이 대기 상태 프로세스가 세마포어를 획득했음을 알리기 위해 task + 포인터를 초기화 합니다; + + (4) 해당 태스크에 대해 wake_up_process() 를 호출합니다; 그리고 + + (5) 해당 대기 상태 프로세스의 task 구조체를 잡고 있던 레퍼런스를 해제합니다. + +달리 말하자면, 다음 이벤트 시퀀스를 수행해야 합니다: + + LOAD waiter->list.next; + LOAD waiter->task; + STORE waiter->task; + CALL wakeup + RELEASE task + +그리고 이 이벤트들이 다른 순서로 수행된다면, 오동작이 일어날 수 있습니다. + +한번 세마포어의 대기줄에 들어갔고 세마포어 락을 놓았다면, 해당 대기 프로세스는 +락을 다시는 잡지 않습니다; 대신 자신의 task 포인터가 초기화 되길 기다립니다. +그 레코드는 대기 프로세스의 스택에 있기 때문에, 리스트의 next 포인터가 읽혀지기 +_전에_ task 포인터가 지워진다면, 다른 CPU 는 해당 대기 프로세스를 시작해 버리고 +up*() 함수가 next 포인터를 읽기 전에 대기 프로세스의 스택을 마구 건드릴 수 +있습니다. + +그렇게 되면 위의 이벤트 시퀀스에 어떤 일이 일어나는지 생각해 보죠: + + CPU 1 CPU 2 + =============================== =============================== + down_xxx() + Queue waiter + Sleep + up_yyy() + LOAD waiter->task; + STORE waiter->task; + Woken up by other event + <preempt> + Resume processing + down_xxx() returns + call foo() + foo() clobbers *waiter + </preempt> + LOAD waiter->list.next; + --- OOPS --- + +이 문제는 세마포어 락의 사용으로 해결될 수도 있겠지만, 그렇게 되면 깨어난 후에 +down_xxx() 함수가 불필요하게 스핀락을 또다시 얻어야만 합니다. + +이 문제를 해결하는 방법은 범용 SMP 메모리 배리어를 추가하는 겁니다: + + LOAD waiter->list.next; + LOAD waiter->task; + smp_mb(); + STORE waiter->task; + CALL wakeup + RELEASE task + +이 경우에, 배리어는 시스템의 나머지 CPU 들에게 모든 배리어 앞의 메모리 액세스가 +배리어 뒤의 메모리 액세스보다 앞서 일어난 것으로 보이게 만듭니다. 배리어 앞의 +메모리 액세스들이 배리어 명령 자체가 완료되는 시점까지 완료된다고는 보장하지 +_않습니다_. + +(이게 문제가 되지 않을) 단일 프로세서 시스템에서 smp_mb() 는 실제로는 그저 +컴파일러가 CPU 안에서의 순서를 바꾸거나 하지 않고 주어진 순서대로 명령을 +내리도록 하는 컴파일러 배리어일 뿐입니다. 오직 하나의 CPU 만 있으니, CPU 의 +의존성 순서 로직이 그 외의 모든것을 알아서 처리할 겁니다. + + +어토믹 오퍼레이션 +----------------- + +어토믹 오퍼레이션은 기술적으로 프로세서간 상호작용으로 분류되며 그 중 일부는 +전체 메모리 배리어를 내포하고 또 일부는 내포하지 않지만, 커널에서 상당히 +의존적으로 사용하는 기능 중 하나입니다. + +더 많은 내용을 위해선 Documentation/atomic_t.txt 를 참고하세요. + + +디바이스 액세스 +--------------- + +많은 디바이스가 메모리 매핑 기법으로 제어될 수 있는데, 그렇게 제어되는 +디바이스는 CPU 에는 단지 특정 메모리 영역의 집합처럼 보이게 됩니다. 드라이버는 +그런 디바이스를 제어하기 위해 정확히 올바른 순서로 올바른 메모리 액세스를 +만들어야 합니다. + +하지만, 액세스들을 재배치 하거나 조합하거나 병합하는게 더 효율적이라 판단하는 +영리한 CPU 나 컴파일러들을 사용하면 드라이버 코드의 조심스럽게 순서 맞춰진 +액세스들이 디바이스에는 요청된 순서대로 도착하지 못하게 할 수 있는 - 디바이스가 +오동작을 하게 할 - 잠재적 문제가 생길 수 있습니다. + +리눅스 커널 내부에서, I/O 는 어떻게 액세스들을 적절히 순차적이게 만들 수 있는지 +알고 있는, - inb() 나 writel() 과 같은 - 적절한 액세스 루틴을 통해 이루어져야만 +합니다. 이것들은 대부분의 경우에는 명시적 메모리 배리어 와 함께 사용될 필요가 +없습니다만, 다음의 두가지 상황에서는 명시적 메모리 배리어가 필요할 수 있습니다: + + (1) 일부 시스템에서 I/O 스토어는 모든 CPU 에 일관되게 순서 맞춰지지 않는데, + 따라서 _모든_ 일반적인 드라이버들에 락이 사용되어야만 하고 이 크리티컬 + 섹션을 빠져나오기 전에 mmiowb() 가 꼭 호출되어야 합니다. + + (2) 만약 액세스 함수들이 완화된 메모리 액세스 속성을 갖는 I/O 메모리 윈도우를 + 사용한다면, 순서를 강제하기 위해선 _mandatory_ 메모리 배리어가 필요합니다. + +더 많은 정보를 위해선 Documentation/driver-api/device-io.rst 를 참고하십시오. + + +인터럽트 +-------- + +드라이버는 자신의 인터럽트 서비스 루틴에 의해 인터럽트 당할 수 있기 때문에 +드라이버의 이 두 부분은 서로의 디바이스 제어 또는 액세스 부분과 상호 간섭할 수 +있습니다. + +스스로에게 인터럽트 당하는 걸 불가능하게 하고, 드라이버의 크리티컬한 +오퍼레이션들을 모두 인터럽트가 불가능하게 된 영역에 집어넣거나 하는 방법 (락의 +한 형태) 으로 이런 상호 간섭을 - 최소한 부분적으로라도 - 줄일 수 있습니다. +드라이버의 인터럽트 루틴이 실행 중인 동안, 해당 드라이버의 코어는 같은 CPU 에서 +수행되지 않을 것이며, 현재의 인터럽트가 처리되는 중에는 또다시 인터럽트가 +일어나지 못하도록 되어 있으니 인터럽트 핸들러는 그에 대해서는 락을 잡지 않아도 +됩니다. + +하지만, 어드레스 레지스터와 데이터 레지스터를 갖는 이더넷 카드를 다루는 +드라이버를 생각해 봅시다. 만약 이 드라이버의 코어가 인터럽트를 비활성화시킨 +채로 이더넷 카드와 대화하고 드라이버의 인터럽트 핸들러가 호출되었다면: + + LOCAL IRQ DISABLE + writew(ADDR, 3); + writew(DATA, y); + LOCAL IRQ ENABLE + <interrupt> + writew(ADDR, 4); + q = readw(DATA); + </interrupt> + +만약 순서 규칙이 충분히 완화되어 있다면 데이터 레지스터에의 스토어는 어드레스 +레지스터에 두번째로 행해지는 스토어 뒤에 일어날 수도 있습니다: + + STORE *ADDR = 3, STORE *ADDR = 4, STORE *DATA = y, q = LOAD *DATA + + +만약 순서 규칙이 충분히 완화되어 있고 묵시적으로든 명시적으로든 배리어가 +사용되지 않았다면 인터럽트 비활성화 섹션에서 일어난 액세스가 바깥으로 새어서 +인터럽트 내에서 일어난 액세스와 섞일 수 있다고 - 그리고 그 반대도 - 가정해야만 +합니다. + +그런 영역 안에서 일어나는 I/O 액세스들은 엄격한 순서 규칙의 I/O 레지스터에 +묵시적 I/O 배리어를 형성하는 동기적 (synchronous) 로드 오퍼레이션을 포함하기 +때문에 일반적으로는 이런게 문제가 되지 않습니다. 만약 이걸로는 충분치 않다면 +mmiowb() 가 명시적으로 사용될 필요가 있습니다. + + +하나의 인터럽트 루틴과 별도의 CPU 에서 수행중이며 서로 통신을 하는 두 루틴 +사이에도 비슷한 상황이 일어날 수 있습니다. 만약 그런 경우가 발생할 가능성이 +있다면, 순서를 보장하기 위해 인터럽트 비활성화 락이 사용되어져야만 합니다. + + +====================== +커널 I/O 배리어의 효과 +====================== + +I/O 메모리에 액세스할 때, 드라이버는 적절한 액세스 함수를 사용해야 합니다: + + (*) inX(), outX(): + + 이것들은 메모리 공간보다는 I/O 공간에 이야기를 하려는 의도로 + 만들어졌습니다만, 그건 기본적으로 CPU 마다 다른 컨셉입니다. i386 과 + x86_64 프로세서들은 특별한 I/O 공간 액세스 사이클과 명령어를 실제로 가지고 + 있지만, 다른 많은 CPU 들에는 그런 컨셉이 존재하지 않습니다. + + 다른 것들 중에서도 PCI 버스가 I/O 공간 컨셉을 정의하는데, 이는 - i386 과 + x86_64 같은 CPU 에서 - CPU 의 I/O 공간 컨셉으로 쉽게 매치됩니다. 하지만, + 대체할 I/O 공간이 없는 CPU 에서는 CPU 의 메모리 맵의 가상 I/O 공간으로 + 매핑될 수도 있습니다. + + 이 공간으로의 액세스는 (i386 등에서는) 완전하게 동기화 됩니다만, 중간의 + (PCI 호스트 브리지와 같은) 브리지들은 이를 완전히 보장하진 않을수도 + 있습니다. + + 이것들의 상호간의 순서는 완전하게 보장됩니다. + + 다른 타입의 메모리 오퍼레이션, I/O 오퍼레이션에 대한 순서는 완전하게 + 보장되지는 않습니다. + + (*) readX(), writeX(): + + 이것들이 수행 요청되는 CPU 에서 서로에게 완전히 순서가 맞춰지고 독립적으로 + 수행되는지에 대한 보장 여부는 이들이 액세스 하는 메모리 윈도우에 정의된 + 특성에 의해 결정됩니다. 예를 들어, 최신의 i386 아키텍쳐 머신에서는 MTRR + 레지스터로 이 특성이 조정됩니다. + + 일반적으로는, 프리페치 (prefetch) 가능한 디바이스를 액세스 하는게 + 아니라면, 이것들은 완전히 순서가 맞춰지고 결합되지 않게 보장될 겁니다. + + 하지만, (PCI 브리지와 같은) 중간의 하드웨어는 자신이 원한다면 집행을 + 연기시킬 수 있습니다; 스토어 명령을 실제로 하드웨어로 내려보내기(flush) + 위해서는 같은 위치로부터 로드를 하는 방법이 있습니다만[*], PCI 의 경우는 + 같은 디바이스나 환경 구성 영역에서의 로드만으로도 충분할 겁니다. + + [*] 주의! 쓰여진 것과 같은 위치로부터의 로드를 시도하는 것은 오동작을 + 일으킬 수도 있습니다 - 예로 16650 Rx/Tx 시리얼 레지스터를 생각해 + 보세요. + + 프리페치 가능한 I/O 메모리가 사용되면, 스토어 명령들이 순서를 지키도록 + 하기 위해 mmiowb() 배리어가 필요할 수 있습니다. + + PCI 트랜잭션 사이의 상호작용에 대해 더 많은 정보를 위해선 PCI 명세서를 + 참고하시기 바랍니다. + + (*) readX_relaxed(), writeX_relaxed() + + 이것들은 readX() 와 writeX() 랑 비슷하지만, 더 완화된 메모리 순서 보장을 + 제공합니다. 구체적으로, 이것들은 일반적 메모리 액세스 (예: DMA 버퍼) 에도 + LOCK 이나 UNLOCK 오퍼레이션들에도 순서를 보장하지 않습니다. LOCK 이나 + UNLOCK 오퍼레이션들에 맞춰지는 순서가 필요하다면, mmiowb() 배리어가 사용될 + 수 있습니다. 같은 주변 장치에의 완화된 액세스끼리는 순서가 지켜짐을 알아 + 두시기 바랍니다. + + (*) ioreadX(), iowriteX() + + 이것들은 inX()/outX() 나 readX()/writeX() 처럼 실제로 수행하는 액세스의 + 종류에 따라 적절하게 수행될 것입니다. + + +=================================== +가정되는 가장 완화된 실행 순서 모델 +=================================== + +컨셉적으로 CPU 는 주어진 프로그램에 대해 프로그램 그 자체에는 인과성 (program +causality) 을 지키는 것처럼 보이게 하지만 일반적으로는 순서를 거의 지켜주지 +않는다고 가정되어야만 합니다. (i386 이나 x86_64 같은) 일부 CPU 들은 코드 +재배치에 (powerpc 나 frv 와 같은) 다른 것들에 비해 강한 제약을 갖지만, 아키텍쳐 +종속적 코드 이외의 코드에서는 순서에 대한 제약이 가장 완화된 경우 (DEC Alpha) +를 가정해야 합니다. + +이 말은, CPU 에게 주어지는 인스트럭션 스트림 내의 한 인스트럭션이 앞의 +인스트럭션에 종속적이라면 앞의 인스트럭션은 뒤의 종속적 인스트럭션이 실행되기 +전에 완료[*]될 수 있어야 한다는 제약 (달리 말해서, 인과성이 지켜지는 것으로 +보이게 함) 외에는 자신이 원하는 순서대로 - 심지어 병렬적으로도 - 그 스트림을 +실행할 수 있음을 의미합니다 + + [*] 일부 인스트럭션은 하나 이상의 영향 - 조건 코드를 바꾼다던지, 레지스터나 + 메모리를 바꾼다던지 - 을 만들어내며, 다른 인스트럭션은 다른 효과에 + 종속적일 수 있습니다. + +CPU 는 최종적으로 아무 효과도 만들지 않는 인스트럭션 시퀀스는 없애버릴 수도 +있습니다. 예를 들어, 만약 두개의 연속되는 인스트럭션이 둘 다 같은 레지스터에 +직접적인 값 (immediate value) 을 집어넣는다면, 첫번째 인스트럭션은 버려질 수도 +있습니다. + + +비슷하게, 컴파일러 역시 프로그램의 인과성만 지켜준다면 인스트럭션 스트림을 +자신이 보기에 올바르다 생각되는대로 재배치 할 수 있습니다. + + +=============== +CPU 캐시의 영향 +=============== + +캐시된 메모리 오퍼레이션들이 시스템 전체에 어떻게 인지되는지는 CPU 와 메모리 +사이에 존재하는 캐시들, 그리고 시스템 상태의 일관성을 관리하는 메모리 일관성 +시스템에 상당 부분 영향을 받습니다. + +한 CPU 가 시스템의 다른 부분들과 캐시를 통해 상호작용한다면, 메모리 시스템은 +CPU 의 캐시들을 포함해야 하며, CPU 와 CPU 자신의 캐시 사이에서의 동작을 위한 +메모리 배리어를 가져야 합니다. (메모리 배리어는 논리적으로는 다음 그림의 +점선에서 동작합니다): + + <--- CPU ---> : <----------- Memory -----------> + : + +--------+ +--------+ : +--------+ +-----------+ + | | | | : | | | | +--------+ + | CPU | | Memory | : | CPU | | | | | + | Core |--->| Access |----->| Cache |<-->| | | | + | | | Queue | : | | | |--->| Memory | + | | | | : | | | | | | + +--------+ +--------+ : +--------+ | | | | + : | Cache | +--------+ + : | Coherency | + : | Mechanism | +--------+ + +--------+ +--------+ : +--------+ | | | | + | | | | : | | | | | | + | CPU | | Memory | : | CPU | | |--->| Device | + | Core |--->| Access |----->| Cache |<-->| | | | + | | | Queue | : | | | | | | + | | | | : | | | | +--------+ + +--------+ +--------+ : +--------+ +-----------+ + : + : + +특정 로드나 스토어는 해당 오퍼레이션을 요청한 CPU 의 캐시 내에서 동작을 완료할 +수도 있기 때문에 해당 CPU 의 바깥에는 보이지 않을 수 있지만, 다른 CPU 가 관심을 +갖는다면 캐시 일관성 메커니즘이 해당 캐시라인을 해당 CPU 에게 전달하고, 해당 +메모리 영역에 대한 오퍼레이션이 발생할 때마다 그 영향을 전파시키기 때문에, 해당 +오퍼레이션은 메모리에 실제로 액세스를 한것처럼 나타날 것입니다. + +CPU 코어는 프로그램의 인과성이 유지된다고만 여겨진다면 인스트럭션들을 어떤 +순서로든 재배치해서 수행할 수 있습니다. 일부 인스트럭션들은 로드나 스토어 +오퍼레이션을 만드는데 이 오퍼레이션들은 이후 수행될 메모리 액세스 큐에 들어가게 +됩니다. 코어는 이 오퍼레이션들을 해당 큐에 어떤 순서로든 원하는대로 넣을 수 +있고, 다른 인스트럭션의 완료를 기다리도록 강제되기 전까지는 수행을 계속합니다. + +메모리 배리어가 하는 일은 CPU 쪽에서 메모리 쪽으로 넘어가는 액세스들의 순서, +그리고 그 액세스의 결과가 시스템의 다른 관찰자들에게 인지되는 순서를 제어하는 +것입니다. + +[!] CPU 들은 항상 그들 자신의 로드와 스토어는 프로그램 순서대로 일어난 것으로 +보기 때문에, 주어진 CPU 내에서는 메모리 배리어를 사용할 필요가 _없습니다_. + +[!] MMIO 나 다른 디바이스 액세스들은 캐시 시스템을 우회할 수도 있습니다. 우회 +여부는 디바이스가 액세스 되는 메모리 윈도우의 특성에 의해 결정될 수도 있고, CPU +가 가지고 있을 수 있는 특수한 디바이스 통신 인스트럭션의 사용에 의해서 결정될 +수도 있습니다. + + +캐시 일관성 +----------- + +하지만 삶은 앞에서 이야기한 것처럼 단순하지 않습니다: 캐시들은 일관적일 것으로 +기대되지만, 그 일관성이 순서에도 적용될 거라는 보장은 없습니다. 한 CPU 에서 +만들어진 변경 사항은 최종적으로는 시스템의 모든 CPU 에게 보여지게 되지만, 다른 +CPU 들에게도 같은 순서로 보이게 될 거라는 보장은 없다는 뜻입니다. + + +두개의 CPU (1 & 2) 가 달려 있고, 각 CPU 에 두개의 데이터 캐시(CPU 1 은 A/B 를, +CPU 2 는 C/D 를 갖습니다)가 병렬로 연결되어 있는 시스템을 다룬다고 생각해 +봅시다: + + : + : +--------+ + : +---------+ | | + +--------+ : +--->| Cache A |<------->| | + | | : | +---------+ | | + | CPU 1 |<---+ | | + | | : | +---------+ | | + +--------+ : +--->| Cache B |<------->| | + : +---------+ | | + : | Memory | + : +---------+ | System | + +--------+ : +--->| Cache C |<------->| | + | | : | +---------+ | | + | CPU 2 |<---+ | | + | | : | +---------+ | | + +--------+ : +--->| Cache D |<------->| | + : +---------+ | | + : +--------+ + : + +이 시스템이 다음과 같은 특성을 갖는다 생각해 봅시다: + + (*) 홀수번 캐시라인은 캐시 A, 캐시 C 또는 메모리에 위치할 수 있음; + + (*) 짝수번 캐시라인은 캐시 B, 캐시 D 또는 메모리에 위치할 수 있음; + + (*) CPU 코어가 한개의 캐시에 접근하는 동안, 다른 캐시는 - 더티 캐시라인을 + 메모리에 내리거나 추측성 로드를 하거나 하기 위해 - 시스템의 다른 부분에 + 액세스 하기 위해 버스를 사용할 수 있음; + + (*) 각 캐시는 시스템의 나머지 부분들과 일관성을 맞추기 위해 해당 캐시에 + 적용되어야 할 오퍼레이션들의 큐를 가짐; + + (*) 이 일관성 큐는 캐시에 이미 존재하는 라인에 가해지는 평범한 로드에 의해서는 + 비워지지 않는데, 큐의 오퍼레이션들이 이 로드의 결과에 영향을 끼칠 수 있다 + 할지라도 그러함. + +이제, 첫번째 CPU 에서 두개의 쓰기 오퍼레이션을 만드는데, 해당 CPU 의 캐시에 +요청된 순서로 오퍼레이션이 도달됨을 보장하기 위해 두 오퍼레이션 사이에 쓰기 +배리어를 사용하는 상황을 상상해 봅시다: + + CPU 1 CPU 2 COMMENT + =============== =============== ======================================= + u == 0, v == 1 and p == &u, q == &u + v = 2; + smp_wmb(); v 의 변경이 p 의 변경 전에 보일 것을 + 분명히 함 + <A:modify v=2> v 는 이제 캐시 A 에 독점적으로 존재함 + p = &v; + <B:modify p=&v> p 는 이제 캐시 B 에 독점적으로 존재함 + +여기서의 쓰기 메모리 배리어는 CPU 1 의 캐시가 올바른 순서로 업데이트 된 것으로 +시스템의 다른 CPU 들이 인지하게 만듭니다. 하지만, 이제 두번째 CPU 가 그 값들을 +읽으려 하는 상황을 생각해 봅시다: + + CPU 1 CPU 2 COMMENT + =============== =============== ======================================= + ... + q = p; + x = *q; + +위의 두개의 읽기 오퍼레이션은 예상된 순서로 일어나지 못할 수 있는데, 두번째 CPU +의 한 캐시에 다른 캐시 이벤트가 발생해 v 를 담고 있는 캐시라인의 해당 캐시에의 +업데이트가 지연되는 사이, p 를 담고 있는 캐시라인은 두번째 CPU 의 다른 캐시에 +업데이트 되어버렸을 수 있기 때문입니다. + + CPU 1 CPU 2 COMMENT + =============== =============== ======================================= + u == 0, v == 1 and p == &u, q == &u + v = 2; + smp_wmb(); + <A:modify v=2> <C:busy> + <C:queue v=2> + p = &v; q = p; + <D:request p> + <B:modify p=&v> <D:commit p=&v> + <D:read p> + x = *q; + <C:read *q> 캐시에 업데이트 되기 전의 v 를 읽음 + <C:unbusy> + <C:commit v=2> + +기본적으로, 두개의 캐시라인 모두 CPU 2 에 최종적으로는 업데이트 될 것이지만, +별도의 개입 없이는, 업데이트의 순서가 CPU 1 에서 만들어진 순서와 동일할 +것이라는 보장이 없습니다. + + +여기에 개입하기 위해선, 데이터 의존성 배리어나 읽기 배리어를 로드 오퍼레이션들 +사이에 넣어야 합니다 (v4.15 부터는 READ_ONCE() 매크로에 의해 무조건적으로 +그렇게 됩니다). 이렇게 함으로써 캐시가 다음 요청을 처리하기 전에 일관성 큐를 +처리하도록 강제하게 됩니다. + + CPU 1 CPU 2 COMMENT + =============== =============== ======================================= + u == 0, v == 1 and p == &u, q == &u + v = 2; + smp_wmb(); + <A:modify v=2> <C:busy> + <C:queue v=2> + p = &v; q = p; + <D:request p> + <B:modify p=&v> <D:commit p=&v> + <D:read p> + smp_read_barrier_depends() + <C:unbusy> + <C:commit v=2> + x = *q; + <C:read *q> 캐시에 업데이트 된 v 를 읽음 + + +이런 부류의 문제는 DEC Alpha 계열 프로세서들에서 발견될 수 있는데, 이들은 +데이터 버스를 좀 더 잘 사용해 성능을 개선할 수 있는, 분할된 캐시를 가지고 있기 +때문입니다. 대부분의 CPU 는 하나의 읽기 오퍼레이션의 메모리 액세스가 다른 읽기 +오퍼레이션에 의존적이라면 데이터 의존성 배리어를 내포시킵니다만, 모두가 그런건 +아니기 때문에 이점에 의존해선 안됩니다. + +다른 CPU 들도 분할된 캐시를 가지고 있을 수 있지만, 그런 CPU 들은 평범한 메모리 +액세스를 위해서도 이 분할된 캐시들 사이의 조정을 해야만 합니다. Alpha 는 가장 +약한 메모리 순서 시맨틱 (semantic) 을 선택함으로써 메모리 배리어가 명시적으로 +사용되지 않았을 때에는 그런 조정이 필요하지 않게 했으며, 이는 Alpha 가 당시에 +더 높은 CPU 클락 속도를 가질 수 있게 했습니다. 하지만, (다시 말하건대, v4.15 +이후부터는) Alpha 아키텍쳐 전용 코드와 READ_ONCE() 매크로 내부에서를 제외하고는 +smp_read_barrier_depends() 가 사용되지 않아야 함을 알아두시기 바랍니다. + + +캐시 일관성 VS DMA +------------------ + +모든 시스템이 DMA 를 하는 디바이스에 대해서까지 캐시 일관성을 유지하지는 +않습니다. 그런 경우, DMA 를 시도하는 디바이스는 RAM 으로부터 잘못된 데이터를 +읽을 수 있는데, 더티 캐시 라인이 CPU 의 캐시에 머무르고 있고, 바뀐 값이 아직 +RAM 에 써지지 않았을 수 있기 때문입니다. 이 문제를 해결하기 위해선, 커널의 +적절한 부분에서 각 CPU 캐시의 문제되는 비트들을 플러시 (flush) 시켜야만 합니다 +(그리고 그것들을 무효화 - invalidation - 시킬 수도 있겠죠). + +또한, 디바이스에 의해 RAM 에 DMA 로 쓰여진 값은 디바이스가 쓰기를 완료한 후에 +CPU 의 캐시에서 RAM 으로 쓰여지는 더티 캐시 라인에 의해 덮어써질 수도 있고, CPU +의 캐시에 존재하는 캐시 라인이 해당 캐시에서 삭제되고 다시 값을 읽어들이기 +전까지는 RAM 이 업데이트 되었다는 사실 자체가 숨겨져 버릴 수도 있습니다. 이 +문제를 해결하기 위해선, 커널의 적절한 부분에서 각 CPU 의 캐시 안의 문제가 되는 +비트들을 무효화 시켜야 합니다. + +캐시 관리에 대한 더 많은 정보를 위해선 Documentation/core-api/cachetlb.rst 를 +참고하세요. + + +캐시 일관성 VS MMIO +------------------- + +Memory mapped I/O 는 일반적으로 CPU 의 메모리 공간 내의 한 윈도우의 특정 부분 +내의 메모리 지역에 이루어지는데, 이 윈도우는 일반적인, RAM 으로 향하는 +윈도우와는 다른 특성을 갖습니다. + +그런 특성 가운데 하나는, 일반적으로 그런 액세스는 캐시를 완전히 우회하고 +디바이스 버스로 곧바로 향한다는 것입니다. 이 말은 MMIO 액세스는 먼저 +시작되어서 캐시에서 완료된 메모리 액세스를 추월할 수 있다는 뜻입니다. 이런 +경우엔 메모리 배리어만으로는 충분치 않고, 만약 캐시된 메모리 쓰기 오퍼레이션과 +MMIO 액세스가 어떤 방식으로든 의존적이라면 해당 캐시는 두 오퍼레이션 사이에 +비워져(flush)야만 합니다. + + +====================== +CPU 들이 저지르는 일들 +====================== + +프로그래머는 CPU 가 메모리 오퍼레이션들을 정확히 요청한대로 수행해 줄 것이라고 +생각하는데, 예를 들어 다음과 같은 코드를 CPU 에게 넘긴다면: + + a = READ_ONCE(*A); + WRITE_ONCE(*B, b); + c = READ_ONCE(*C); + d = READ_ONCE(*D); + WRITE_ONCE(*E, e); + +CPU 는 다음 인스트럭션을 처리하기 전에 현재의 인스트럭션을 위한 메모리 +오퍼레이션을 완료할 것이라 생각하고, 따라서 시스템 외부에서 관찰하기에도 정해진 +순서대로 오퍼레이션이 수행될 것으로 예상합니다: + + LOAD *A, STORE *B, LOAD *C, LOAD *D, STORE *E. + + +당연하지만, 실제로는 훨씬 엉망입니다. 많은 CPU 와 컴파일러에서 앞의 가정은 +성립하지 못하는데 그 이유는 다음과 같습니다: + + (*) 로드 오퍼레이션들은 실행을 계속 해나가기 위해 곧바로 완료될 필요가 있는 + 경우가 많은 반면, 스토어 오퍼레이션들은 종종 별다른 문제 없이 유예될 수 + 있습니다; + + (*) 로드 오퍼레이션들은 예측적으로 수행될 수 있으며, 필요없는 로드였다고 + 증명된 예측적 로드의 결과는 버려집니다; + + (*) 로드 오퍼레이션들은 예측적으로 수행될 수 있으므로, 예상된 이벤트의 + 시퀀스와 다른 시간에 로드가 이뤄질 수 있습니다; + + (*) 메모리 액세스 순서는 CPU 버스와 캐시를 좀 더 잘 사용할 수 있도록 재배치 + 될 수 있습니다; + + (*) 로드와 스토어는 인접한 위치에의 액세스들을 일괄적으로 처리할 수 있는 + 메모리나 I/O 하드웨어 (메모리와 PCI 디바이스 둘 다 이게 가능할 수 + 있습니다) 에 대해 요청되는 경우, 개별 오퍼레이션을 위한 트랜잭션 설정 + 비용을 아끼기 위해 조합되어 실행될 수 있습니다; 그리고 + + (*) 해당 CPU 의 데이터 캐시가 순서에 영향을 끼칠 수도 있고, 캐시 일관성 + 메커니즘이 - 스토어가 실제로 캐시에 도달한다면 - 이 문제를 완화시킬 수는 + 있지만 이 일관성 관리가 다른 CPU 들에도 같은 순서로 전달된다는 보장은 + 없습니다. + +따라서, 앞의 코드에 대해 다른 CPU 가 보는 결과는 다음과 같을 수 있습니다: + + LOAD *A, ..., LOAD {*C,*D}, STORE *E, STORE *B + + ("LOAD {*C,*D}" 는 조합된 로드입니다) + + +하지만, CPU 는 스스로는 일관적일 것을 보장합니다: CPU _자신_ 의 액세스들은 +자신에게는 메모리 배리어가 없음에도 불구하고 정확히 순서 세워진 것으로 보여질 +것입니다. 예를 들어 다음의 코드가 주어졌다면: + + U = READ_ONCE(*A); + WRITE_ONCE(*A, V); + WRITE_ONCE(*A, W); + X = READ_ONCE(*A); + WRITE_ONCE(*A, Y); + Z = READ_ONCE(*A); + +그리고 외부의 영향에 의한 간섭이 없다고 가정하면, 최종 결과는 다음과 같이 +나타날 것이라고 예상될 수 있습니다: + + U == *A 의 최초 값 + X == W + Z == Y + *A == Y + +앞의 코드는 CPU 가 다음의 메모리 액세스 시퀀스를 만들도록 할겁니다: + + U=LOAD *A, STORE *A=V, STORE *A=W, X=LOAD *A, STORE *A=Y, Z=LOAD *A + +하지만, 별다른 개입이 없고 프로그램의 시야에 이 세상이 여전히 일관적이라고 +보인다는 보장만 지켜진다면 이 시퀀스는 어떤 조합으로든 재구성될 수 있으며, 각 +액세스들은 합쳐지거나 버려질 수 있습니다. 일부 아키텍쳐에서 CPU 는 같은 위치에 +대한 연속적인 로드 오퍼레이션들을 재배치 할 수 있기 때문에 앞의 예에서의 +READ_ONCE() 와 WRITE_ONCE() 는 반드시 존재해야 함을 알아두세요. 그런 종류의 +아키텍쳐에서 READ_ONCE() 와 WRITE_ONCE() 는 이 문제를 막기 위해 필요한 일을 +뭐가 됐든지 하게 되는데, 예를 들어 Itanium 에서는 READ_ONCE() 와 WRITE_ONCE() +가 사용하는 volatile 캐스팅은 GCC 가 그런 재배치를 방지하는 특수 인스트럭션인 +ld.acq 와 stl.rel 인스트럭션을 각각 만들어 내도록 합니다. + +컴파일러 역시 이 시퀀스의 액세스들을 CPU 가 보기도 전에 합치거나 버리거나 뒤로 +미뤄버릴 수 있습니다. + +예를 들어: + + *A = V; + *A = W; + +는 다음과 같이 변형될 수 있습니다: + + *A = W; + +따라서, 쓰기 배리어나 WRITE_ONCE() 가 없다면 *A 로의 V 값의 저장의 효과는 +사라진다고 가정될 수 있습니다. 비슷하게: + + *A = Y; + Z = *A; + +는, 메모리 배리어나 READ_ONCE() 와 WRITE_ONCE() 없이는 다음과 같이 변형될 수 +있습니다: + + *A = Y; + Z = Y; + +그리고 이 LOAD 오퍼레이션은 CPU 바깥에는 아예 보이지 않습니다. + + +그리고, ALPHA 가 있다 +--------------------- + +DEC Alpha CPU 는 가장 완화된 메모리 순서의 CPU 중 하나입니다. 뿐만 아니라, +Alpha CPU 의 일부 버전은 분할된 데이터 캐시를 가지고 있어서, 의미적으로 +관계되어 있는 두개의 캐시 라인이 서로 다른 시간에 업데이트 되는게 가능합니다. +이게 데이터 의존성 배리어가 정말 필요해지는 부분인데, 데이터 의존성 배리어는 +메모리 일관성 시스템과 함께 두개의 캐시를 동기화 시켜서, 포인터 변경과 새로운 +데이터의 발견을 올바른 순서로 일어나게 하기 때문입니다. + +리눅스 커널의 메모리 배리어 모델은 Alpha 에 기초해서 정의되었습니다만, v4.15 +부터는 리눅스 커널이 READ_ONCE() 내에 smp_read_barrier_depends() 를 추가해서 +Alpha 의 메모리 모델로의 영향력이 크게 줄어들긴 했습니다. + +위의 "캐시 일관성" 서브섹션을 참고하세요. + + +가상 머신 게스트 +---------------- + +가상 머신에서 동작하는 게스트들은 게스트 자체는 SMP 지원 없이 컴파일 되었다 +해도 SMP 영향을 받을 수 있습니다. 이건 UP 커널을 사용하면서 SMP 호스트와 +결부되어 발생하는 부작용입니다. 이 경우에는 mandatory 배리어를 사용해서 문제를 +해결할 수 있겠지만 그런 해결은 대부분의 경우 최적의 해결책이 아닙니다. + +이 문제를 완벽하게 해결하기 위해, 로우 레벨의 virt_mb() 등의 매크로를 사용할 수 +있습니다. 이것들은 SMP 가 활성화 되어 있다면 smp_mb() 등과 동일한 효과를 +갖습니다만, SMP 와 SMP 아닌 시스템 모두에 대해 동일한 코드를 만들어냅니다. +예를 들어, 가상 머신 게스트들은 (SMP 일 수 있는) 호스트와 동기화를 할 때에는 +smp_mb() 가 아니라 virt_mb() 를 사용해야 합니다. + +이것들은 smp_mb() 류의 것들과 모든 부분에서 동일하며, 특히, MMIO 의 영향에 +대해서는 간여하지 않습니다: MMIO 의 영향을 제어하려면, mandatory 배리어를 +사용하시기 바랍니다. + + +======= +사용 예 +======= + +순환식 버퍼 +----------- + +메모리 배리어는 순환식 버퍼를 생성자(producer)와 소비자(consumer) 사이의 +동기화에 락을 사용하지 않고 구현하는데에 사용될 수 있습니다. 더 자세한 내용을 +위해선 다음을 참고하세요: + + Documentation/core-api/circular-buffers.rst + + +========= +참고 문헌 +========= + +Alpha AXP Architecture Reference Manual, Second Edition (Sites & Witek, +Digital Press) + Chapter 5.2: Physical Address Space Characteristics + Chapter 5.4: Caches and Write Buffers + Chapter 5.5: Data Sharing + Chapter 5.6: Read/Write Ordering + +AMD64 Architecture Programmer's Manual Volume 2: System Programming + Chapter 7.1: Memory-Access Ordering + Chapter 7.4: Buffering and Combining Memory Writes + +ARM Architecture Reference Manual (ARMv8, for ARMv8-A architecture profile) + Chapter B2: The AArch64 Application Level Memory Model + +IA-32 Intel Architecture Software Developer's Manual, Volume 3: +System Programming Guide + Chapter 7.1: Locked Atomic Operations + Chapter 7.2: Memory Ordering + Chapter 7.4: Serializing Instructions + +The SPARC Architecture Manual, Version 9 + Chapter 8: Memory Models + Appendix D: Formal Specification of the Memory Models + Appendix J: Programming with the Memory Models + +Storage in the PowerPC (Stone and Fitzgerald) + +UltraSPARC Programmer Reference Manual + Chapter 5: Memory Accesses and Cacheability + Chapter 15: Sparc-V9 Memory Models + +UltraSPARC III Cu User's Manual + Chapter 9: Memory Models + +UltraSPARC IIIi Processor User's Manual + Chapter 8: Memory Models + +UltraSPARC Architecture 2005 + Chapter 9: Memory + Appendix D: Formal Specifications of the Memory Models + +UltraSPARC T1 Supplement to the UltraSPARC Architecture 2005 + Chapter 8: Memory Models + Appendix F: Caches and Cache Coherency + +Solaris Internals, Core Kernel Architecture, p63-68: + Chapter 3.3: Hardware Considerations for Locks and + Synchronization + +Unix Systems for Modern Architectures, Symmetric Multiprocessing and Caching +for Kernel Programmers: + Chapter 13: Other Memory Models + +Intel Itanium Architecture Software Developer's Manual: Volume 1: + Section 2.6: Speculation + Section 4.4: Memory Access diff --git a/Documentation/translations/ko_KR/stable_api_nonsense.txt b/Documentation/translations/ko_KR/stable_api_nonsense.txt new file mode 100644 index 000000000..4d93af1ef --- /dev/null +++ b/Documentation/translations/ko_KR/stable_api_nonsense.txt @@ -0,0 +1,195 @@ +NOTE: +This is a version of Documentation/process/stable-api-nonsense.rst translated +into korean +This document is maintained by Minchan Kim <minchan@kernel.org> +If you find any difference between this document and the original file or +a problem with the translation, please contact the maintainer of this file. + +Please also note that the purpose of this file is to be easier to +read for non English (read: korean) speakers and is not intended as +a fork. So if you have any comments or updates for this file please +try to update the original English file first. + +================================== +이 문서는 +Documentation/process/stable-api-nonsense.rst +의 한글 번역입니다. + +역자： 김민찬 <minchan@kernel.org> +감수： 이제이미 <jamee.lee@samsung.com> +================================== + +리눅스 커널 드라이버 인터페이스 +(여러분들의 모든 질문에 대한 답 그리고 다른 몇가지) + +Greg Kroah-Hartman <greg@kroah.com> + +이 문서는 리눅스가 왜 바이너리 커널 인터페이스를 갖지 않는지, 왜 변하지 +않는(stable) 커널 인터페이스를 갖지 않는지를 설명하기 위해 쓰여졌다. +이 문서는 커널과 유저공간 사이의 인터페이스가 아니라 커널 내부의 +인터페이스들을 설명하고 있다는 것을 유념하라. 커널과 유저공간 사이의 +인터페이스는 응용프로그램이 사용하는 syscall 인터페이스이다. 그 인터페이스는 +오랫동안 거의 변하지 않았고 앞으로도 변하지 않을 것이다. 나는 pre 0.9에서 +만들어졌지만 최신의 2.6 커널 배포에서도 잘 동작하는 프로그램을 가지고 +있다. 이 인터페이스는 사용자와 응용프로그램 개발자들이 변하지 않을 것이라고 +여길수 있는 것이다. + + +초록 +---- +여러분은 변하지 않는 커널 인터페이스를 원한다고 생각하지만 실제로는 +그렇지 않으며 심지어는 그것을 알아채지 못한다. 여러분이 원하는 것은 +안정되게 실행되는 드라이버이며 드라이버가 메인 커널 트리에 있을 때 +그런 안정적인 드라이버를 얻을 수 있게 된다. 또한 여러분의 드라이버가 +메인 커널 트리에 있다면 다른 많은 좋은 이점들을 얻게 된다. 그러한 것들이 +리눅스를 강건하고, 안정적이며, 성숙한 운영체제로 만들어 놓음으로써 +여러분들로 하여금 바로 리눅스를 사용하게 만드는 이유이다. + + +소개 +---- + +커널 내부의 인터페이스가 바뀌는 것을 걱정하며 커널 드라이버를 작성하고 +싶어하는 사람은 정말 이상한 사람이다. 세상의 대다수의 사람들은 이 인터페이스를 +보지못할 것이며 전혀 걱정하지도 않는다. + +먼저, 나는 closed 소스, hidden 소스, binary blobs, 소스 wrappers, 또는 GPL로 +배포되었지만 소스 코드를 갖고 있지 않은 커널 드라이버들을 설명하는 어떤 다른 +용어들에 관한 어떤 법적인 문제에 관해서는 언급하지 않을 것이다. 어떤 법적인 +질문들을 가지고 있다면 변호사와 연락하라. 나는 프로그래머이므로 여기서 기술적인 +문제들만을 설명하려고 한다. (법적인 문제를 경시하는 것은 아니다. 그런 문제들은 +엄연히 현실에 있고 여러분들은 항상 그 문제들을 인식하고 있을 필요는 있다.) + +자, 두가지의 주요 주제가 있다. 바이너리 커널 인터페이스들과 변하지 않는 +커널 소스 인터페이들. 그것들은 서로 의존성을 가지고 있지만 바이너리 +문제를 먼저 풀고 넘어갈 것이다. + + + +바이너리 커널 인터페이스 +------------------------ +우리가 변하지 않는 커널 소스 인터페이스를 가지고 있다고 가정하자. 그러면 +바이너리 인터페이스 또한 자연적으로 변하지 않을까? 틀렸다. 리눅스 커널에 +관한 다음 사실들을 생각해보라. + - 여러분들이 사용하는 C 컴파일러의 버젼에 따라 다른 커널 자료 구조들은 + 다른 alignmnet들을 갖게 될것이고 다른 방법으로(함수들을 inline으로 + 했느냐, 아니냐) 다른 함수들을 포함하는 것도 가능한다. 중요한 것은 + 개별적인 함수 구성이 아니라 자료 구조 패딩이 달라진다는 점이다. + - 여러분이 선택한 커널 빌드 옵션에 따라서 커널은 다양한 것들을 가정할 + 수 있다. + - 다른 구조체들은 다른 필드들을 포함할 수 있다. + - 몇몇 함수들은 전혀 구현되지 않을 수도 있다(즉, 몇몇 lock들은 + non-SMP 빌드에서는 사라져 버릴수도 있다). + - 커널내에 메모리는 build optoin들에 따라 다른 방법으로 align될수 + 있다. + - 리눅스는 많은 다양한 프로세서 아키텍쳐에서 실행된다. 한 아키텍쳐의 + 바이너리 드라이버를 다른 아키텍쳐에서 정상적으로 실행시킬 방법은 + 없다. + +커널을 빌드했던 C 컴파일러와 정확하게 같은 것을 사용하고 정확하게 같은 +커널 구성(configuration)을 사용하여 여러분들의 모듈을 빌드하면 간단히 +많은 문제들을 해결할 수 있다. 이렇게 하는 것은 여러분들이 하나의 리눅스 +배포판의 하나의 배포 버젼을 위한 모듈만을 제공한다면 별일 아닐 것이다. +그러나 각기 다른 리눅스 배포판마다 한번씩 빌드하는 수를 각 리눅스 배포판마다 +제공하는 다른 릴리즈의 수와 곱하게 되면 이번에는 각 릴리즈들의 다른 빌드 +옵션의 악몽과 마주하게 것이다. 또한 각 리눅스 배포판들은 다른 하드웨어 +종류에(다른 프로세서 타입과 다른 옵션들) 맞춰져 있는 많은 다른 커널들을 +배포한다. 그러므로 한번의 배포에서조차 여러분들의 모듈은 여러 버젼을 +만들 필요가 있다. + +나를 믿어라. 여러분들은 이러한 종류의 배포를 지원하려고 시도한다면 시간이 +지나면 미칠지경이 될 것이다. 난 이러한 것을 오래전에 아주 어렵게 배웠다... + + + +변하지않는 커널 소스 인터페이스들 +--------------------------------- + +리눅스 커널 드라이버를 계속해서 메인 커널 트리에 반영하지 않고 +유지보수하려고 하는 사람들과 이 문제를 논의하게 되면 훨씬 더 +"논란의 여지가 많은" 주제가 될 것이다. + +리눅스 커널 개발은 끊임없이 빠른 속도로 이루어지고 있으며 결코 +느슨해진 적이 없다. 커널 개발자들이 현재 인터페이스들에서 버그를 +발견하거나 무엇인가 할 수 있는 더 좋은 방법을 찾게 되었다고 하자. +그들이 발견한 것을 실행한다면 아마도 더 잘 동작하도록 현재 인터페이스들을 +수정하게 될 것이다. 그들이 그런 일을 하게되면 함수 이름들은 변하게 되고, +구조체들은 늘어나거나 줄어들게 되고, 함수 파라미터들은 재작업될 것이다. +이러한 일이 발생되면 커널 내에 이 인터페이스를 사용했던 인스턴스들이 동시에 +수정될 것이며 이러한 과정은 모든 것이 계속해서 올바르게 동작할 것이라는 +것을 보장한다. + +이러한 것의 한 예로써, 커널 내부의 USB 인터페이스들은 이 서브시스템이 +생긴 이후로 적어도 3번의 다른 재작업을 겪었다. 이 재작업들은 많은 다른 +문제들을 풀었다. + - 데이터 스트림들의 동기적인 모델에서 비동기적인 모델로의 변화. 이것은 + 많은 드라이버들의 복잡성을 줄이고 처리량을 향상시켜 현재는 거의 모든 + USB 장치들의 거의 최대 속도로 실행되고 있다. + - USB 드라이버가 USB 코어로부터 데이터 패킷들을 할당받로록 한 변경으로 + 인해서 지금의 모든 드라이버들은 많은 문서화된 데드락을 수정하기 위하여 + USB 코어에게 더 많은 정보를 제공해야만 한다. + +이것은 오랫동안 자신의 오래된 USB 인터페이스들을 유지해야 하는 closed 운영체제들과는 +완전히 반대되는 것이다. closed된 운영체제들은 새로운 개발자들에게 우연히 낡은 +인터페이스를 사용하게 할 기회를 주게되며, 적절하지 못한 방법으로 처리하게 되어 +운영체제의 안정성을 해치는 문제를 야기하게 된다. + +이 두가지의 예들 모두, 모든 개발자들은 꼭 이루어져야 하는 중요한 변화들이라고 +동의를 하였고 비교적 적은 고통으로 변경되어졌다. 리눅스가 변하지 않는 소스 +인터페이스를 고집한다면, 새로운 인터페이스가 만들어지게 되며 반면 기존의 오래된 +것들, 그리고 깨진 것들은 계속해서 유지되어야 하며 이러한 일들은 USB 개발자들에게 +또 다른 일거리를 주게 된다. 모든 리눅스 USB 개발자들에게 자신의 그들의 업무를 +마친 후 시간을 투자하여 아무 득도 없는 무료 봉사를 해달라고 하는 것은 가능성이 +희박한 일이다. + +보안 문제 역시 리눅스에게는 매우 중요하다. 보안 문제가 발견되면 그것은 +매우 짧은 시간 안에 수정된다. 보안 문제는 그 문제를 해결하기 위하여 +여러번 내부 커널 인터페이스들을 재작업하게 만들었다. 이러한 문제가 +발생하였을 때 그 인터페이스들을 사용하는 모든 드라이버들도 동시에 +수정되어 보안 문제가 앞으로 갑작스럽게 생기지는 않을 것이라는 것을 +보장한다. 내부 인터페이스들의 변경이 허락되지 않으면 이러한 종류의 보안 +문제를 수정하고 그것이 다시 발생하지 않을 것이라고 보장하는 것은 가능하지 +않을 것이다. + +커널 인터페이스들은 계속해서 정리되고 있다. 현재 인터페이스를 사용하는 +사람이 한명도 없다면 그것은 삭제된다. 이것은 커널이 가능한한 가장 작게 +유지되며 존재하는 모든 가능성이 있는 인터페이스들이 테스트된다는 것을 +보장한다(사용되지 않는 인터페이스들은 유효성 검증을 하기가 거의 불가능하다). + + +무엇을 해야 하나 +--------------- +자, 여러분이 메인 커널 트리에 있지 않은 리눅스 커널 드라이버를 가지고 +있다면 여러분은 즉, 개발자는 무엇을 해야 하나? 모든 배포판마다 다른 +커널 버젼을 위한 바이너리 드라이버를 배포하는 것은 악몽이며 계속해서 +변하고 있는 커널 인터페이스들의 맞처 유지보수하려고 시도하는 것은 힘든 +일이다. + +간단하다. 여러분의 커널 드라이버를 메인 커널 트리에 반영하라(우리는 여기서 +GPL을 따르는 배포 드라이버에 관해 얘기하고 있다는 것을 상기하라. 여러분의 +코드가 이러한 분류에 해당되지 않는다면 행운을 빈다. 여러분 스스로 어떻게든 +해야만 한다). 여러분의 드라이버가 트리에 있게되면 커널 인터페이스가 +변경되더라도 가장 먼저 커널에 변경을 가했던 사람에 의해서 수정될 것이다. +이것은 여러분의 드라이버가 여러분의 별다른 노력없이 항상 빌드가 가능하며 +동작하는 것을 보장한다. + +메인 커널 트리에 여러분의 드라이버를 반영하면 얻게 되는 장점들은 다음과 같다. + - 관리에 드는 비용(원래 개발자의)은 줄어줄면서 드라이버의 질은 향상될 것이다. + - 다른 개발자들이 여러분의 드라이버에 기능들을 추가 할 것이다. + - 다른 사람들은 여러분의 드라이버에 버그를 발견하고 수정할 것이다. + - 다른 사람들은 여러분의 드라이버의 개선점을 찾을 줄 것이다. + - 외부 인터페이스 변경으로 인해 여러분의 드라이버의 수정이 필요하다면 다른 + 사람들이 드라이버를 업데이트할 것이다. + - 여러분의 드라이버는 별다른 노력 없이 모든 리눅스 배포판에 자동적으로 + 추가될 것이다. + +리눅스는 다른 운영 체제보다 "쉽게 쓸수 있는(out of the box)" 많은 다른 장치들을 +지원하고 어떤 다른 운영 체제보다 다양한 아키텍쳐위에서 이러한 장치들을 지원하기 때문에 +이러한 증명된 개발 모델은 틀림없이 바로 가고 있는 것이다. + + + +------ + +이 문서의 초안을 검토해주고 코멘트 해준 Randy Dunlap, Andrew Morton, David Brownell, +Hanna Linder, Robert Love, 그리고 Nishanth Aravamudan에게 감사한다. diff --git a/Documentation/translations/zh_CN/HOWTO b/Documentation/translations/zh_CN/HOWTO new file mode 100644 index 000000000..5f6d09edc --- /dev/null +++ b/Documentation/translations/zh_CN/HOWTO @@ -0,0 +1,534 @@ +Chinese translated version of Documentation/process/howto.rst + +If you have any comment or update to the content, please contact the +original document maintainer directly. However, if you have a problem +communicating in English you can also ask the Chinese maintainer for +help. Contact the Chinese maintainer if this translation is outdated +or if there is a problem with the translation. + +Maintainer: Greg Kroah-Hartman <greg@kroah.com> +Chinese maintainer: Li Yang <leoli@freescale.com> +--------------------------------------------------------------------- +Documentation/process/howto.rst 的中文翻译 + +如果想评论或更新本文的内容，请直接联系原文档的维护者。如果你使用英文 +交流有困难的话，也可以向中文版维护者求助。如果本翻译更新不及时或者翻 +译存在问题，请联系中文版维护者。 + +英文版维护者： Greg Kroah-Hartman <greg@kroah.com> +中文版维护者： 李阳 Li Yang <leoli@freescale.com> +中文版翻译者： 李阳 Li Yang <leoli@freescale.com> +中文版校译者： 钟宇 TripleX Chung <xxx.phy@gmail.com> + 陈琦 Maggie Chen <chenqi@beyondsoft.com> + 王聪 Wang Cong <xiyou.wangcong@gmail.com> + +以下为正文 +--------------------------------------------------------------------- + +如何参与Linux内核开发 +--------------------- + +这是一篇将如何参与Linux内核开发的相关问题一网打尽的终极秘笈。它将指导你 +成为一名Linux内核开发者，并且学会如何同Linux内核开发社区合作。它尽可能不 +包括任何关于内核编程的技术细节，但会给你指引一条获得这些知识的正确途径。 + +如果这篇文章中的任何内容不再适用，请给文末列出的文件维护者发送补丁。 + + +入门 +---- + +你想了解如何成为一名Linux内核开发者？或者老板吩咐你“给这个设备写个Linux +驱动程序”？这篇文章的目的就是教会你达成这些目标的全部诀窍，它将描述你需 +要经过的流程以及给出如何同内核社区合作的一些提示。它还将试图解释内核社区 +为何这样运作。 + +Linux内核大部分是由C语言写成的，一些体系结构相关的代码用到了汇编语言。要 +参与内核开发，你必须精通C语言。除非你想为某个架构开发底层代码，否则你并 +不需要了解（任何体系结构的）汇编语言。下面列举的书籍虽然不能替代扎实的C +语言教育和多年的开发经验，但如果需要的话，做为参考还是不错的： + - "The C Programming Language" by Kernighan and Ritchie [Prentice Hall] + 《C程序设计语言（第2版·新版）》（徐宝文 李志 译）[机械工业出版社] + - "Practical C Programming" by Steve Oualline [O'Reilly] + 《实用C语言编程（第三版）》（郭大海 译）[中国电力出版社] + - "C: A Reference Manual" by Harbison and Steele [Prentice Hall] + 《C语言参考手册（原书第5版）》（邱仲潘 等译）[机械工业出版社] + +Linux内核使用GNU C和GNU工具链开发。虽然它遵循ISO C89标准，但也用到了一些 +标准中没有定义的扩展。内核是自给自足的C环境，不依赖于标准C库的支持，所以 +并不支持C标准中的部分定义。比如long long类型的大数除法和浮点运算就不允许 +使用。有时候确实很难弄清楚内核对工具链的要求和它所使用的扩展，不幸的是目 +前还没有明确的参考资料可以解释它们。请查阅gcc信息页（使用“info gcc”命令 +显示）获得一些这方面信息。 + +请记住你是在学习怎么和已经存在的开发社区打交道。它由一群形形色色的人组成， +他们对代码、风格和过程有着很高的标准。这些标准是在长期实践中总结出来的， +适应于地理上分散的大型开发团队。它们已经被很好得整理成档，建议你在开发 +之前尽可能多的学习这些标准，而不要期望别人来适应你或者你公司的行为方式。 + + +法律问题 +-------- + +Linux内核源代码都是在GPL（通用公共许可证）的保护下发布的。要了解这种许可 +的细节请查看源代码主目录下的COPYING文件。如果你对它还有更深入问题请联系 +律师，而不要在Linux内核邮件组上提问。因为邮件组里的人并不是律师，不要期 +望他们的话有法律效力。 + +对于GPL的常见问题和解答，请访问以下链接： + http://www.gnu.org/licenses/gpl-faq.html + + +文档 +---- + +Linux内核代码中包含有大量的文档。这些文档对于学习如何与内核社区互动有着 +不可估量的价值。当一个新的功能被加入内核，最好把解释如何使用这个功能的文 +档也放进内核。当内核的改动导致面向用户空间的接口发生变化时，最好将相关信 +息或手册页(manpages)的补丁发到mtk.manpages@gmail.com，以向手册页(manpages) +的维护者解释这些变化。 + +以下是内核代码中需要阅读的文档： + README + 文件简要介绍了Linux内核的背景，并且描述了如何配置和编译内核。内核的 + 新用户应该从这里开始。 + + Documentation/process/changes.rst + 文件给出了用来编译和使用内核所需要的最小软件包列表。 + + Documentation/process/coding-style.rst + 描述Linux内核的代码风格和理由。所有新代码需要遵守这篇文档中定义的规 + 范。大多数维护者只会接收符合规定的补丁，很多人也只会帮忙检查符合风格 + 的代码。 + + Documentation/process/submitting-patches.rst + Documentation/process/submitting-drivers.rst + 这两份文档明确描述如何创建和发送补丁，其中包括（但不仅限于)： + - 邮件内容 + - 邮件格式 + - 选择收件人 + 遵守这些规定并不能保证提交成功（因为所有补丁需要通过严格的内容和风格 + 审查），但是忽视他们几乎就意味着失败。 + + 其他关于如何正确地生成补丁的优秀文档包括： + "The Perfect Patch" + http://www.ozlabs.org/~akpm/stuff/tpp.txt + "Linux kernel patch submission format" + http://linux.yyz.us/patch-format.html + + Documentation/process/stable-api-nonsense.rst + 论证内核为什么特意不包括稳定的内核内部API，也就是说不包括像这样的特 + 性： + - 子系统中间层（为了兼容性？） + - 在不同操作系统间易于移植的驱动程序 + - 减缓（甚至阻止）内核代码的快速变化 + 这篇文档对于理解Linux的开发哲学至关重要。对于将开发平台从其他操作系 + 统转移到Linux的人来说也很重要。 + + Documentation/admin-guide/security-bugs.rst + 如果你认为自己发现了Linux内核的安全性问题，请根据这篇文档中的步骤来 + 提醒其他内核开发者并帮助解决这个问题。 + + Documentation/process/management-style.rst + 描述内核维护者的工作方法及其共有特点。这对于刚刚接触内核开发（或者对 + 它感到好奇）的人来说很重要，因为它解释了很多对于内核维护者独特行为的 + 普遍误解与迷惑。 + + Documentation/process/stable-kernel-rules.rst + 解释了稳定版内核发布的规则，以及如何将改动放入这些版本的步骤。 + + Documentation/process/kernel-docs.rst + 有助于内核开发的外部文档列表。如果你在内核自带的文档中没有找到你想找 + 的内容，可以查看这些文档。 + + Documentation/process/applying-patches.rst + 关于补丁是什么以及如何将它打在不同内核开发分支上的好介绍 + +内核还拥有大量从代码自动生成的文档。它包含内核内部API的全面介绍以及如何 +妥善处理加锁的规则。生成的文档会放在 Documentation/DocBook/目录下。在内 +核源码的主目录中使用以下不同命令将会分别生成PDF、Postscript、HTML和手册 +页等不同格式的文档： + make pdfdocs + make htmldocs + + +如何成为内核开发者 +------------------ +如果你对Linux内核开发一无所知，你应该访问“Linux内核新手”计划： + http://kernelnewbies.org +它拥有一个可以问各种最基本的内核开发问题的邮件列表（在提问之前一定要记得 +查找已往的邮件，确认是否有人已经回答过相同的问题）。它还拥有一个可以获得 +实时反馈的IRC聊天频道，以及大量对于学习Linux内核开发相当有帮助的文档。 + +网站简要介绍了源代码组织结构、子系统划分以及目前正在进行的项目（包括内核 +中的和单独维护的）。它还提供了一些基本的帮助信息，比如如何编译内核和打补 +丁。 + +如果你想加入内核开发社区并协助完成一些任务，却找不到从哪里开始，可以访问 +“Linux内核房管员”计划： + http://kernelnewbies.org/KernelJanitors +这是极佳的起点。它提供一个相对简单的任务列表，列出内核代码中需要被重新 +整理或者改正的地方。通过和负责这个计划的开发者们一同工作，你会学到将补丁 +集成进内核的基本原理。如果还没有决定下一步要做什么的话，你还可能会得到方 +向性的指点。 + +如果你已经有一些现成的代码想要放到内核中，但是需要一些帮助来使它们拥有正 +确的格式。请访问“内核导师”计划。这个计划就是用来帮助你完成这个目标的。它 +是一个邮件列表，地址如下： + http://selenic.com/mailman/listinfo/kernel-mentors + +在真正动手修改内核代码之前，理解要修改的代码如何运作是必需的。要达到这个 +目的，没什么办法比直接读代码更有效了（大多数花招都会有相应的注释），而且 +一些特制的工具还可以提供帮助。例如，“Linux代码交叉引用”项目就是一个值得 +特别推荐的帮助工具，它将源代码显示在有编目和索引的网页上。其中一个更新及 +时的内核源码库，可以通过以下地址访问： + http://sosdg.org/~coywolf/lxr/ + + +开发流程 +-------- + +目前Linux内核开发流程包括几个“主内核分支”和很多子系统相关的内核分支。这 +些分支包括： + - 2.6.x主内核源码树 + - 2.6.x.y -stable内核源码树 + - 2.6.x -git内核补丁集 + - 2.6.x -mm内核补丁集 + - 子系统相关的内核源码树和补丁集 + + +2.6.x内核主源码树 +----------------- +2.6.x内核是由Linus Torvalds（Linux的创造者）亲自维护的。你可以在 +kernel.org网站的pub/linux/kernel/v2.6/目录下找到它。它的开发遵循以下步 +骤： + - 每当一个新版本的内核被发布，为期两周的集成窗口将被打开。在这段时间里 + 维护者可以向Linus提交大段的修改，通常这些修改已经被放到-mm内核中几个 + 星期了。提交大量修改的首选方式是使用git工具（内核的代码版本管理工具 + ，更多的信息可以在http://git-scm.com/获取），不过使用普通补丁也是可以 + 的。 + - 两个星期以后-rc1版本内核发布。之后只有不包含可能影响整个内核稳定性的 + 新功能的补丁才可能被接受。请注意一个全新的驱动程序（或者文件系统）有 + 可能在-rc1后被接受是因为这样的修改完全独立，不会影响其他的代码，所以 + 没有造成内核退步的风险。在-rc1以后也可以用git向Linus提交补丁，不过所 + 有的补丁需要同时被发送到相应的公众邮件列表以征询意见。 + - 当Linus认为当前的git源码树已经达到一个合理健全的状态足以发布供人测试 + 时，一个新的-rc版本就会被发布。计划是每周都发布新的-rc版本。 + - 这个过程一直持续下去直到内核被认为达到足够稳定的状态，持续时间大概是 + 6个星期。 + +关于内核发布，值得一提的是Andrew Morton在linux-kernel邮件列表中如是说： + “没有人知道新内核何时会被发布，因为发布是根据已知bug的情况来决定 + 的，而不是根据一个事先制定好的时间表。” + + +2.6.x.y -stable（稳定版）内核源码树 +----------------------------------- +由4个数字组成的内核版本号说明此内核是-stable版本。它们包含基于2.6.x版本 +内核的相对较小且至关重要的修补，这些修补针对安全性问题或者严重的内核退步。 + +这种版本的内核适用于那些期望获得最新的稳定版内核并且不想参与测试开发版或 +者实验版的用户。 + +如果没有2.6.x.y版本内核存在，那么最新的2.6.x版本内核就相当于是当前的稳定 +版内核。 + +2.6.x.y版本由“稳定版”小组（邮件地址<stable@vger.kernel.org>）维护，一般隔周发 +布新版本。 + +内核源码中的Documentation/process/stable-kernel-rules.rst文件具体描述了可被稳定 +版内核接受的修改类型以及发布的流程。 + + +2.6.x -git补丁集 +---------------- +Linus的内核源码树的每日快照，这个源码树是由git工具管理的（由此得名）。这 +些补丁通常每天更新以反映Linus的源码树的最新状态。它们比-rc版本的内核源码 +树更具试验性质，因为这个补丁集是全自动生成的，没有任何人来确认其是否真正 +健全。 + + +2.6.x -mm补丁集 +--------------- +这是由Andrew Morton维护的试验性内核补丁集。Andrew将所有子系统的内核源码 +和补丁拼凑到一起，并且加入了大量从linux-kernel邮件列表中采集的补丁。这个 +源码树是新功能和补丁的试炼场。当补丁在-mm补丁集里证明了其价值以后Andrew +或者相应子系统的维护者会将补丁发给Linus以便集成进主内核源码树。 + +在将所有新补丁发给Linus以集成到主内核源码树之前，我们非常鼓励先把这些补 +丁放在-mm版内核源码树中进行测试。 + +这些内核版本不适合在需要稳定运行的系统上运行，因为运行它们比运行任何其他 +内核分支都更具有风险。 + +如果你想为内核开发进程提供帮助，请尝试并使用这些内核版本，并在 +linux-kernel邮件列表中提供反馈，告诉大家你遇到了问题还是一切正常。 + +通常-mm版补丁集不光包括这些额外的试验性补丁，还包括发布时-git版主源码树 +中的改动。 + +-mm版内核没有固定的发布周期，但是通常在每两个-rc版内核发布之间都会有若干 +个-mm版内核发布（一般是1至3个）。 + + +子系统相关内核源码树和补丁集 +---------------------------- +相当一部分内核子系统开发者会公开他们自己的开发源码树，以便其他人能了解内 +核的不同领域正在发生的事情。如上所述，这些源码树会被集成到-mm版本内核中。 + +下面是目前可用的一些内核源码树的列表： + 通过git管理的源码树： + - Kbuild开发源码树， Sam Ravnborg <sam@ravnborg.org> + git.kernel.org:/pub/scm/linux/kernel/git/sam/kbuild.git + + - ACPI开发源码树, Len Brown <len.brown@intel.com> + git.kernel.org:/pub/scm/linux/kernel/git/lenb/linux-acpi-2.6.git + + - 块设备开发源码树, Jens Axboe <axboe@suse.de> + git.kernel.org:/pub/scm/linux/kernel/git/axboe/linux-2.6-block.git + + - DRM开发源码树, Dave Airlie <airlied@linux.ie> + git.kernel.org:/pub/scm/linux/kernel/git/airlied/drm-2.6.git + + - ia64开发源码树, Tony Luck <tony.luck@intel.com> + git.kernel.org:/pub/scm/linux/kernel/git/aegl/linux-2.6.git + + - ieee1394开发源码树, Jody McIntyre <scjody@modernduck.com> + git.kernel.org:/pub/scm/linux/kernel/git/scjody/ieee1394.git + + - infiniband开发源码树, Roland Dreier <rolandd@cisco.com> + git.kernel.org:/pub/scm/linux/kernel/git/roland/infiniband.git + + - libata开发源码树, Jeff Garzik <jgarzik@pobox.com> + git.kernel.org:/pub/scm/linux/kernel/git/jgarzik/libata-dev.git + + - 网络驱动程序开发源码树, Jeff Garzik <jgarzik@pobox.com> + git.kernel.org:/pub/scm/linux/kernel/git/jgarzik/netdev-2.6.git + + - pcmcia开发源码树, Dominik Brodowski <linux@dominikbrodowski.net> + git.kernel.org:/pub/scm/linux/kernel/git/brodo/pcmcia-2.6.git + + - SCSI开发源码树, James Bottomley <James.Bottomley@SteelEye.com> + git.kernel.org:/pub/scm/linux/kernel/git/jejb/scsi-misc-2.6.git + + 使用quilt管理的补丁集： + - USB, PCI, 驱动程序核心和I2C, Greg Kroah-Hartman <gregkh@linuxfoundation.org> + kernel.org/pub/linux/kernel/people/gregkh/gregkh-2.6/ + - x86-64, 部分i386, Andi Kleen <ak@suse.de> + ftp.firstfloor.org:/pub/ak/x86_64/quilt/ + + 其他内核源码树可以在http://git.kernel.org的列表中和MAINTAINERS文件里 + 找到。 + +报告bug +------- + +bugzilla.kernel.org是Linux内核开发者们用来跟踪内核Bug的网站。我们鼓励用 +户在这个工具中报告找到的所有bug。如何使用内核bugzilla的细节请访问： + http://test.kernel.org/bugzilla/faq.html + +内核源码主目录中的admin-guide/reporting-bugs.rst文件里有一个很好的模板。它指导用户如何报 +告可能的内核bug以及需要提供哪些信息来帮助内核开发者们找到问题的根源。 + + +利用bug报告 +----------- + +练习内核开发技能的最好办法就是修改其他人报告的bug。你不光可以帮助内核变 +得更加稳定，还可以学会如何解决实际问题从而提高自己的技能，并且让其他开发 +者感受到你的存在。修改bug是赢得其他开发者赞誉的最好办法，因为并不是很多 +人都喜欢浪费时间去修改别人报告的bug。 + +要尝试修改已知的bug，请访问http://bugzilla.kernel.org网址。如果你想获得 +最新bug的通知，可以订阅bugme-new邮件列表（只有新的bug报告会被寄到这里） +或者订阅bugme-janitor邮件列表（所有bugzilla的变动都会被寄到这里）。 + + https://lists.linux-foundation.org/mailman/listinfo/bugme-new + https://lists.linux-foundation.org/mailman/listinfo/bugme-janitors + + +邮件列表 +-------- + +正如上面的文档所描述，大多数的骨干内核开发者都加入了Linux Kernel邮件列 +表。如何订阅和退订列表的细节可以在这里找到： + http://vger.kernel.org/vger-lists.html#linux-kernel +网上很多地方都有这个邮件列表的存档(archive)。可以使用搜索引擎来找到这些 +存档。比如： + http://dir.gmane.org/gmane.linux.kernel +在发信之前，我们强烈建议你先在存档中搜索你想要讨论的问题。很多已经被详细 +讨论过的问题只在邮件列表的存档中可以找到。 + +大多数内核子系统也有自己独立的邮件列表来协调各自的开发工作。从 +MAINTAINERS文件中可以找到不同话题对应的邮件列表。 + +很多邮件列表架设在kernel.org服务器上。这些列表的信息可以在这里找到： + http://vger.kernel.org/vger-lists.html + +在使用这些邮件列表时，请记住保持良好的行为习惯。下面的链接提供了与这些列 +表（或任何其它邮件列表）交流的一些简单规则，虽然内容有点滥竽充数。 + http://www.albion.com/netiquette/ + +当有很多人回复你的邮件时，邮件的抄送列表会变得很长。请不要将任何人从抄送 +列表中删除，除非你有足够的理由这么做。也不要只回复到邮件列表。请习惯于同 +一封邮件接收两次（一封来自发送者一封来自邮件列表），而不要试图通过添加一 +些奇特的邮件头来解决这个问题，人们不会喜欢的。 + +记住保留你所回复内容的上下文和源头。在你回复邮件的顶部保留“某某某说到……” +这几行。将你的评论加在被引用的段落之间而不要放在邮件的顶部。 + +如果你在邮件中附带补丁，请确认它们是可以直接阅读的纯文本（如 +Documentation/process/submitting-patches.rst文档中所述）。内核开发者们不希望遇到附件 +或者被压缩了的补丁。只有这样才能保证他们可以直接评论你的每行代码。请确保 +你使用的邮件发送程序不会修改空格和制表符。一个防范性的测试方法是先将邮件 +发送给自己，然后自己尝试是否可以顺利地打上收到的补丁。如果测试不成功，请 +调整或者更换你的邮件发送程序直到它正确工作为止。 + +总而言之，请尊重其他的邮件列表订阅者。 + + +同内核社区合作 +---------------- + +内核社区的目标就是提供尽善尽美的内核。所以当你提交补丁期望被接受进内核的 +时候，它的技术价值以及其他方面都将被评审。那么你可能会得到什么呢？ + - 批评 + - 评论 + - 要求修改 + - 要求证明修改的必要性 + - 沉默 + +要记住，这些是把补丁放进内核的正常情况。你必须学会听取对补丁的批评和评论， +从技术层面评估它们，然后要么重写你的补丁要么简明扼要地论证修改是不必要 +的。如果你发的邮件没有得到任何回应，请过几天后再试一次，因为有时信件会湮 +没在茫茫信海中。 + +你不应该做的事情： + - 期望自己的补丁不受任何质疑就直接被接受 + - 翻脸 + - 忽略别人的评论 + - 没有按照别人的要求做任何修改就重新提交 + +在一个努力追寻最好技术方案的社区里，对于一个补丁有多少好处总会有不同的见 +解。你必须要抱着合作的态度，愿意改变自己的观点来适应内核的风格。或者至少 +愿意去证明你的想法是有价值的。记住，犯错误是允许的，只要你愿意朝着正确的 +方案去努力。 + +如果你的第一个补丁换来的是一堆修改建议，这是很正常的。这并不代表你的补丁 +不会被接受，也不意味着有人和你作对。你只需要改正所有提出的问题然后重新发 +送你的补丁。 + +内核社区和公司文化的差异 +------------------------ + +内核社区的工作模式同大多数传统公司开发队伍的工作模式并不相同。下面这些例 +子，可以帮助你避免某些可能发生问题： + 用这些话介绍你的修改提案会有好处： + - 它同时解决了多个问题 + - 它删除了2000行代码 + - 这是补丁，它已经解释了我想要说明的 + - 我在5种不同的体系结构上测试过它…… + - 这是一系列小补丁用来…… + - 这个修改提高了普通机器的性能…… + + 应该避免如下的说法： + - 我们在AIX/ptx/Solaris就是这么做的，所以这么做肯定是好的…… + - 我做这行已经20年了，所以…… + - 为了我们公司赚钱考虑必须这么做 + - 这是我们的企业产品线所需要的 + - 这里是描述我观点的1000页设计文档 + - 这是一个5000行的补丁用来…… + - 我重写了现在乱七八糟的代码，这就是…… + - 我被规定了最后期限，所以这个补丁需要立刻被接受 + +另外一个内核社区与大部分传统公司的软件开发队伍不同的地方是无法面对面地交 +流。使用电子邮件和IRC聊天工具做为主要沟通工具的一个好处是性别和种族歧视 +将会更少。Linux内核的工作环境更能接受妇女和少数族群，因为每个人在别人眼 +里只是一个邮件地址。国际化也帮助了公平的实现，因为你无法通过姓名来判断人 +的性别。男人有可能叫李丽，女人也有可能叫王刚。大多数在Linux内核上工作过 +并表达过看法的女性对在linux上工作的经历都给出了正面的评价。 + +对于一些不习惯使用英语的人来说，语言可能是一个引起问题的障碍。在邮件列表 +中要正确地表达想法必需良好地掌握语言，所以建议你在发送邮件之前最好检查一 +下英文写得是否正确。 + + +拆分修改 +-------- + +Linux内核社区并不喜欢一下接收大段的代码。修改需要被恰当地介绍、讨论并且 +拆分成独立的小段。这几乎完全和公司中的习惯背道而驰。你的想法应该在开发最 +开始的阶段就让大家知道，这样你就可以及时获得对你正在进行的开发的反馈。这 +样也会让社区觉得你是在和他们协作，而不是仅仅把他们当作倾销新功能的对象。 +无论如何，你不要一次性地向邮件列表发送50封信，你的补丁序列应该永远用不到 +这么多。 + +将补丁拆开的原因如下： + +1) 小的补丁更有可能被接受，因为它们不需要太多的时间和精力去验证其正确性。 + 一个5行的补丁，可能在维护者看了一眼以后就会被接受。而500行的补丁则 + 需要数个小时来审查其正确性（所需时间随补丁大小增加大约呈指数级增长）。 + + 当出了问题的时候，小的补丁也会让调试变得非常容易。一个一个补丁地回溯 + 将会比仔细剖析一个被打上的大补丁（这个补丁破坏了其他东西）容易得多。 + +2）不光发送小的补丁很重要，在提交之前重新编排、化简（或者仅仅重新排列） + 补丁也是很重要的。 + +这里有内核开发者Al Viro打的一个比方： + “想象一个老师正在给学生批改数学作业。老师并不希望看到学生为了得 + 到正确解法所进行的尝试和产生的错误。他希望看到的是最干净最优雅的 + 解答。好学生了解这点，绝不会把最终解决之前的中间方案提交上去。” + + 内核开发也是这样。维护者和评审者不希望看到一个人在解决问题时的思 + 考过程。他们只希望看到简单和优雅的解决方案。 + +直接给出一流的解决方案，和社区一起协作讨论尚未完成的工作，这两者之间似乎 +很难找到一个平衡点。所以最好尽早开始收集有利于你进行改进的反馈；同时也要 +保证修改分成很多小块，这样在整个项目都准备好被包含进内核之前，其中的一部 +分可能会先被接收。 + +必须了解这样做是不可接受的：试图将未完成的工作提交进内核，然后再找时间修 +复。 + + +证明修改的必要性 +---------------- +除了将补丁拆成小块，很重要的一点是让Linux社区了解他们为什么需要这样修改。 +你必须证明新功能是有人需要的并且是有用的。 + + +记录修改 +-------- + +当你发送补丁的时候，需要特别留意邮件正文的内容。因为这里的信息将会做为补 +丁的修改记录(ChangeLog)，会被一直保留以备大家查阅。它需要完全地描述补丁， +包括： + - 为什么需要这个修改 + - 补丁的总体设计 + - 实现细节 + - 测试结果 + +想了解它具体应该看起来像什么，请查阅以下文档中的“ChangeLog”章节： + “The Perfect Patch” + http://www.ozlabs.org/~akpm/stuff/tpp.txt + + +这些事情有时候做起来很难。要在任何方面都做到完美可能需要好几年时间。这是 +一个持续提高的过程，它需要大量的耐心和决心。只要不放弃，你一定可以做到。 +很多人已经做到了，而他们都曾经和现在的你站在同样的起点上。 + + +--------------- +感谢Paolo Ciarrocchi允许“开发流程”部分基于他所写的文章 +(http://www.kerneltravel.net/newbie/2.6-development_process)，感谢Randy +Dunlap和Gerrit Huizenga完善了应该说和不该说的列表。感谢Pat Mochel, Hanna +Linder, Randy Dunlap, Kay Sievers, Vojtech Pavlik, Jan Kara, Josh Boyer, +Kees Cook, Andrew Morton, Andi Kleen, Vadim Lobanov, Jesper Juhl, Adrian +Bunk, Keri Harris, Frans Pop, David A. Wheeler, Junio Hamano, Michael +Kerrisk和Alex Shepard的评审、建议和贡献。没有他们的帮助，这篇文档是不可 +能完成的。 + + + +英文版维护者： Greg Kroah-Hartman <greg@kroah.com> diff --git a/Documentation/translations/zh_CN/IRQ.txt b/Documentation/translations/zh_CN/IRQ.txt new file mode 100644 index 000000000..956026d5c --- /dev/null +++ b/Documentation/translations/zh_CN/IRQ.txt @@ -0,0 +1,39 @@ +Chinese translated version of Documentation/IRQ.txt + +If you have any comment or update to the content, please contact the +original document maintainer directly. However, if you have a problem +communicating in English you can also ask the Chinese maintainer for +help. Contact the Chinese maintainer if this translation is outdated +or if there is a problem with the translation. + +Maintainer: Eric W. Biederman <ebiederman@xmission.com> +Chinese maintainer: Fu Wei <tekkamanninja@gmail.com> +--------------------------------------------------------------------- +Documentation/IRQ.txt 的中文翻译 + +如果想评论或更新本文的内容，请直接联系原文档的维护者。如果你使用英文 +交流有困难的话，也可以向中文版维护者求助。如果本翻译更新不及时或者翻 +译存在问题，请联系中文版维护者。 +英文版维护者： Eric W. Biederman <ebiederman@xmission.com> +中文版维护者： 傅炜 Fu Wei <tekkamanninja@gmail.com> +中文版翻译者： 傅炜 Fu Wei <tekkamanninja@gmail.com> +中文版校译者： 傅炜 Fu Wei <tekkamanninja@gmail.com> + + +以下为正文 +--------------------------------------------------------------------- +何为 IRQ? + +一个 IRQ 是来自某个设备的一个中断请求。目前，它们可以来自一个硬件引脚， +或来自一个数据包。多个设备可能连接到同个硬件引脚，从而共享一个 IRQ。 + +一个 IRQ 编号是用于告知硬件中断源的内核标识。通常情况下，这是一个 +全局 irq_desc 数组的索引，但是除了在 linux/interrupt.h 中的实现， +具体的细节是体系结构特定的。 + +一个 IRQ 编号是设备上某个可能的中断源的枚举。通常情况下，枚举的编号是 +该引脚在系统内中断控制器的所有输入引脚中的编号。对于 ISA 总线中的情况， +枚举的是在两个 i8259 中断控制器中 16 个输入引脚。 + +架构可以对 IRQ 编号指定额外的含义，在硬件涉及任何手工配置的情况下， +是被提倡的。ISA 的 IRQ 是一个分配这类额外含义的典型例子。 diff --git a/Documentation/translations/zh_CN/SecurityBugs b/Documentation/translations/zh_CN/SecurityBugs new file mode 100644 index 000000000..2d0fffd12 --- /dev/null +++ b/Documentation/translations/zh_CN/SecurityBugs @@ -0,0 +1,50 @@ +Chinese translated version of Documentation/admin-guide/security-bugs.rst + +If you have any comment or update to the content, please contact the +original document maintainer directly. However, if you have a problem +communicating in English you can also ask the Chinese maintainer for +help. Contact the Chinese maintainer if this translation is outdated +or if there is a problem with the translation. + +Chinese maintainer: Harry Wei <harryxiyou@gmail.com> +--------------------------------------------------------------------- +Documentation/admin-guide/security-bugs.rst 的中文翻译 + +如果想评论或更新本文的内容，请直接联系原文档的维护者。如果你使用英文 +交流有困难的话，也可以向中文版维护者求助。如果本翻译更新不及时或者翻 +译存在问题，请联系中文版维护者。 + +中文版维护者： 贾威威 Harry Wei <harryxiyou@gmail.com> +中文版翻译者： 贾威威 Harry Wei <harryxiyou@gmail.com> +中文版校译者： 贾威威 Harry Wei <harryxiyou@gmail.com> + + +以下为正文 +--------------------------------------------------------------------- +Linux内核开发者认为安全非常重要。因此，我们想要知道当一个有关于 +安全的漏洞被发现的时候，并且它可能会被尽快的修复或者公开。请把这个安全 +漏洞报告给Linux内核安全团队。 + +1) 联系 + +linux内核安全团队可以通过email<security@kernel.org>来联系。这是 +一组独立的安全工作人员，可以帮助改善漏洞报告并且公布和取消一个修复。安 +全团队有可能会从部分的维护者那里引进额外的帮助来了解并且修复安全漏洞。 +当遇到任何漏洞，所能提供的信息越多就越能诊断和修复。如果你不清楚什么 +是有帮助的信息，那就请重温一下admin-guide/reporting-bugs.rst文件中的概述过程。任 +何攻击性的代码都是非常有用的，未经报告者的同意不会被取消，除非它已经 +被公布于众。 + +2) 公开 + +Linux内核安全团队的宗旨就是和漏洞提交者一起处理漏洞的解决方案直 +到公开。我们喜欢尽快地完全公开漏洞。当一个漏洞或者修复还没有被完全地理 +解，解决方案没有通过测试或者供应商协调，可以合理地延迟公开。然而，我们 +期望这些延迟尽可能的短些，是可数的几天，而不是几个星期或者几个月。公开 +日期是通过安全团队和漏洞提供者以及供应商洽谈后的结果。公开时间表是从很 +短（特殊的，它已经被公众所知道）到几个星期。作为一个基本的默认政策，我 +们所期望通知公众的日期是7天的安排。 + +3) 保密协议 + +Linux内核安全团队不是一个正式的团体，因此不能加入任何的保密协议。 diff --git a/Documentation/translations/zh_CN/SubmittingDrivers b/Documentation/translations/zh_CN/SubmittingDrivers new file mode 100644 index 000000000..15e73562f --- /dev/null +++ b/Documentation/translations/zh_CN/SubmittingDrivers @@ -0,0 +1,164 @@ +Chinese translated version of Documentation/process/submitting-drivers.rst + +If you have any comment or update to the content, please contact the +original document maintainer directly. However, if you have a problem +communicating in English you can also ask the Chinese maintainer for +help. Contact the Chinese maintainer if this translation is outdated +or if there is a problem with the translation. + +Chinese maintainer: Li Yang <leo@zh-kernel.org> +--------------------------------------------------------------------- +Documentation/process/submitting-drivers.rst 的中文翻译 + +如果想评论或更新本文的内容，请直接联系原文档的维护者。如果你使用英文 +交流有困难的话，也可以向中文版维护者求助。如果本翻译更新不及时或者翻 +译存在问题，请联系中文版维护者。 + +中文版维护者： 李阳 Li Yang <leo@zh-kernel.org> +中文版翻译者： 李阳 Li Yang <leo@zh-kernel.org> +中文版校译者： 陈琦 Maggie Chen <chenqi@beyondsoft.com> + 王聪 Wang Cong <xiyou.wangcong@gmail.com> + 张巍 Zhang Wei <Wei.Zhang@freescale.com> + +以下为正文 +--------------------------------------------------------------------- + +如何向 Linux 内核提交驱动程序 +----------------------------- + +这篇文档将会解释如何向不同的内核源码树提交设备驱动程序。请注意，如果你感 +兴趣的是显卡驱动程序，你也许应该访问 XFree86 项目(http://www.xfree86.org/) +和／或 X.org 项目 (http://x.org)。 + +另请参阅 Documentation/process/submitting-patches.rst 文档。 + + +分配设备号 +---------- + +块设备和字符设备的主设备号与从设备号是由 Linux 命名编号分配权威 LANANA（ +现在是 Torben Mathiasen）负责分配。申请的网址是 http://www.lanana.org/。 +即使不准备提交到主流内核的设备驱动也需要在这里分配设备号。有关详细信息， +请参阅 Documentation/admin-guide/devices.rst。 + +如果你使用的不是已经分配的设备号，那么当你提交设备驱动的时候，它将会被强 +制分配一个新的设备号，即便这个设备号和你之前发给客户的截然不同。 + +设备驱动的提交对象 +------------------ + +Linux 2.0: + 此内核源码树不接受新的驱动程序。 + +Linux 2.2: + 此内核源码树不接受新的驱动程序。 + +Linux 2.4: + 如果所属的代码领域在内核的 MAINTAINERS 文件中列有一个总维护者， + 那么请将驱动程序提交给他。如果此维护者没有回应或者你找不到恰当的 + 维护者，那么请联系 Willy Tarreau <w@1wt.eu>。 + +Linux 2.6: + 除了遵循和 2.4 版内核同样的规则外，你还需要在 linux-kernel 邮件 + 列表上跟踪最新的 API 变化。向 Linux 2.6 内核提交驱动的顶级联系人 + 是 Andrew Morton <akpm@linux-foundation.org>。 + +决定设备驱动能否被接受的条件 +---------------------------- + +许可： 代码必须使用 GNU 通用公开许可证 (GPL) 提交给 Linux，但是 + 我们并不要求 GPL 是唯一的许可。你或许会希望同时使用多种 + 许可证发布，如果希望驱动程序可以被其他开源社区（比如BSD） + 使用。请参考 include/linux/module.h 文件中所列出的可被 + 接受共存的许可。 + +版权： 版权所有者必须同意使用 GPL 许可。最好提交者和版权所有者 + 是相同个人或实体。否则，必需列出授权使用 GPL 的版权所有 + 人或实体，以备验证之需。 + +接口： 如果你的驱动程序使用现成的接口并且和其他同类的驱动程序行 + 为相似，而不是去发明无谓的新接口，那么它将会更容易被接受。 + 如果你需要一个 Linux 和 NT 的通用驱动接口，那么请在用 + 户空间实现它。 + +代码： 请使用 Documentation/process/coding-style.rst 中所描述的 Linux 代码风 + 格。如果你的某些代码段（例如那些与 Windows 驱动程序包共 + 享的代码段）需要使用其他格式，而你却只希望维护一份代码， + 那么请将它们很好地区分出来，并且注明原因。 + +可移植性： 请注意，指针并不永远是 32 位的，不是所有的计算机都使用小 + 尾模式 (little endian) 存储数据，不是所有的人都拥有浮点 + 单元，不要随便在你的驱动程序里嵌入 x86 汇编指令。只能在 + x86 上运行的驱动程序一般是不受欢迎的。虽然你可能只有 x86 + 硬件，很难测试驱动程序在其他平台上是否可用，但是确保代码 + 可以被轻松地移植却是很简单的。 + +清晰度： 做到所有人都能修补这个驱动程序将会很有好处，因为这样你将 + 会直接收到修复的补丁而不是 bug 报告。如果你提交一个试图 + 隐藏硬件工作机理的驱动程序，那么它将会被扔进废纸篓。 + +电源管理： 因为 Linux 正在被很多移动设备和桌面系统使用，所以你的驱 + 动程序也很有可能被使用在这些设备上。它应该支持最基本的电 + 源管理，即在需要的情况下实现系统级休眠和唤醒要用到的 + .suspend 和 .resume 函数。你应该检查你的驱动程序是否能正 + 确地处理休眠与唤醒，如果实在无法确认，请至少把 .suspend + 函数定义成返回 -ENOSYS（功能未实现）错误。你还应该尝试确 + 保你的驱动在什么都不干的情况下将耗电降到最低。要获得驱动 + 程序测试的指导，请参阅 + Documentation/power/drivers-testing.txt。有关驱动程序电 + 源管理问题相对全面的概述，请参阅 + Documentation/driver-api/pm/devices.rst。 + +管理： 如果一个驱动程序的作者还在进行有效的维护，那么通常除了那 + 些明显正确且不需要任何检查的补丁以外，其他所有的补丁都会 + 被转发给作者。如果你希望成为驱动程序的联系人和更新者，最 + 好在代码注释中写明并且在 MAINTAINERS 文件中加入这个驱动 + 程序的条目。 + +不影响设备驱动能否被接受的条件 +------------------------------ + +供应商： 由硬件供应商来维护驱动程序通常是一件好事。不过，如果源码 + 树里已经有其他人提供了可稳定工作的驱动程序，那么请不要期 + 望“我是供应商”会成为内核改用你的驱动程序的理由。理想的情 + 况是：供应商与现有驱动程序的作者合作，构建一个统一完美的 + 驱动程序。 + +作者： 驱动程序是由大的 Linux 公司研发还是由你个人编写，并不影 + 响其是否能被内核接受。没有人对内核源码树享有特权。只要你 + 充分了解内核社区，你就会发现这一点。 + + +资源列表 +-------- + +Linux 内核主源码树： + ftp.??.kernel.org:/pub/linux/kernel/... + ?? == 你的国家代码，例如 "cn"、"us"、"uk"、"fr" 等等 + +Linux 内核邮件列表： + linux-kernel@vger.kernel.org + [可通过向majordomo@vger.kernel.org发邮件来订阅] + +Linux 设备驱动程序，第三版（探讨 2.6.10 版内核）： + http://lwn.net/Kernel/LDD3/ （免费版） + +LWN.net: + 每周内核开发活动摘要 - http://lwn.net/ + 2.6 版中 API 的变更： + http://lwn.net/Articles/2.6-kernel-api/ + 将旧版内核的驱动程序移植到 2.6 版： + http://lwn.net/Articles/driver-porting/ + +内核新手(KernelNewbies): + 为新的内核开发者提供文档和帮助 + http://kernelnewbies.org/ + +Linux USB项目： + http://www.linux-usb.org/ + +写内核驱动的“不要”（Arjan van de Ven著）: + http://www.fenrus.org/how-to-not-write-a-device-driver-paper.pdf + +内核清洁工 (Kernel Janitor): + http://kernelnewbies.org/KernelJanitors diff --git a/Documentation/translations/zh_CN/SubmittingPatches b/Documentation/translations/zh_CN/SubmittingPatches new file mode 100644 index 000000000..e9098da8f --- /dev/null +++ b/Documentation/translations/zh_CN/SubmittingPatches @@ -0,0 +1,412 @@ +Chinese translated version of Documentation/process/submitting-patches.rst + +If you have any comment or update to the content, please contact the +original document maintainer directly. However, if you have a problem +communicating in English you can also ask the Chinese maintainer for +help. Contact the Chinese maintainer if this translation is outdated +or if there is a problem with the translation. + +Chinese maintainer: TripleX Chung <triplex@zh-kernel.org> +--------------------------------------------------------------------- +Documentation/process/submitting-patches.rst 的中文翻译 + +如果想评论或更新本文的内容，请直接联系原文档的维护者。如果你使用英文 +交流有困难的话，也可以向中文版维护者求助。如果本翻译更新不及时或者翻 +译存在问题，请联系中文版维护者。 + +中文版维护者： 钟宇 TripleX Chung <triplex@zh-kernel.org> +中文版翻译者： 钟宇 TripleX Chung <triplex@zh-kernel.org> +中文版校译者： 李阳 Li Yang <leo@zh-kernel.org> + 王聪 Wang Cong <xiyou.wangcong@gmail.com> + +以下为正文 +--------------------------------------------------------------------- + + 如何让你的改动进入内核 + 或者 + 获得亲爱的 Linus Torvalds 的关注和处理 +---------------------------------- + +对于想要将改动提交到 Linux 内核的个人或者公司来说，如果不熟悉“规矩”， +提交的流程会让人畏惧。本文档收集了一系列建议，这些建议可以大大的提高你 +的改动被接受的机会。 +阅读 Documentation/process/submit-checklist.rst 来获得在提交代码前需要检查的项目的列 +表。如果你在提交一个驱动程序，那么同时阅读一下 +Documentation/process/submitting-drivers.rst 。 + + +-------------------------- +第一节 - 创建并发送你的改动 +-------------------------- + +1) "diff -up" +----------- + +使用 "diff -up" 或者 "diff -uprN" 来创建补丁。 + +所有内核的改动，都是以补丁的形式呈现的，补丁由 diff(1) 生成。创建补丁的 +时候，要确认它是以 "unified diff" 格式创建的，这种格式由 diff(1) 的 '-u' +参数生成。而且，请使用 '-p' 参数，那样会显示每个改动所在的C函数，使得 +产生的补丁容易读得多。补丁应该基于内核源代码树的根目录，而不是里边的任 +何子目录。 +为一个单独的文件创建补丁，一般来说这样做就够了： + + SRCTREE= linux-2.6 + MYFILE= drivers/net/mydriver.c + + cd $SRCTREE + cp $MYFILE $MYFILE.orig + vi $MYFILE # make your change + cd .. + diff -up $SRCTREE/$MYFILE{.orig,} > /tmp/patch + +为多个文件创建补丁，你可以解开一个没有修改过的内核源代码树，然后和你自 +己的代码树之间做 diff 。例如： + + MYSRC= /devel/linux-2.6 + + tar xvfz linux-2.6.12.tar.gz + mv linux-2.6.12 linux-2.6.12-vanilla + diff -uprN -X linux-2.6.12-vanilla/Documentation/dontdiff \ + linux-2.6.12-vanilla $MYSRC > /tmp/patch + +"dontdiff" 是内核在编译的时候产生的文件的列表，列表中的文件在 diff(1) +产生的补丁里会被跳过。"dontdiff" 文件被包含在2.6.12和之后版本的内核源代 +码树中。对于更早的内核版本，你可以从 +<http://www.xenotime.net/linux/doc/dontdiff> 获取它。 +确定你的补丁里没有包含任何不属于这次补丁提交的额外文件。记得在用diff(1) +生成补丁之后，审阅一次补丁，以确保准确。 +如果你的改动很散乱，你应该研究一下如何将补丁分割成独立的部分，将改动分 +割成一系列合乎逻辑的步骤。这样更容易让其他内核开发者审核，如果你想你的 +补丁被接受，这是很重要的。下面这些脚本能够帮助你做这件事情： +Quilt: +http://savannah.nongnu.org/projects/quilt + +2)描述你的改动。 +描述你的改动包含的技术细节。 + +要多具体就写多具体。最糟糕的描述可能是像下面这些语句：“更新了某驱动程 +序”，“修正了某驱动程序的bug”，或者“这个补丁包含了某子系统的修改，请 +使用。” + +如果你的描述开始变长，这表示你也许需要拆分你的补丁了，请看第3小节， +继续。 + +3)拆分你的改动 + +将改动拆分，逻辑类似的放到同一个补丁文件里。 + +例如，如果你的改动里同时有bug修正和性能优化，那么把这些改动拆分到两个或 +者更多的补丁文件中。如果你的改动包含对API的修改，并且修改了驱动程序来适 +应这些新的API，那么把这些修改分成两个补丁。 + +另一方面，如果你将一个单独的改动做成多个补丁文件，那么将它们合并成一个 +单独的补丁文件。这样一个逻辑上单独的改动只被包含在一个补丁文件里。 + +如果有一个补丁依赖另外一个补丁来完成它的改动，那没问题。简单的在你的补 +丁描述里指出“这个补丁依赖某补丁”就好了。 + +如果你不能将补丁浓缩成更少的文件，那么每次大约发送出15个，然后等待审查 +和整合。 + +4)选择 e-mail 的收件人 + +看一遍 MAINTAINERS 文件和源代码，看看你所的改动所在的内核子系统有没有指 +定的维护者。如果有，给他们发e-mail。 + +如果没有找到维护者，或者维护者没有反馈，将你的补丁发送到内核开发者主邮 +件列表 linux-kernel@vger.kernel.org。大部分的内核开发者都跟踪这个邮件列 +表，可以评价你的改动。 + +每次不要发送超过15个补丁到 vger 邮件列表！！！ + +Linus Torvalds 是决定改动能否进入 Linux 内核的最终裁决者。他的 e-mail +地址是 <torvalds@linux-foundation.org> 。他收到的 e-mail 很多，所以一般 +的说，最好别给他发 e-mail。 + +那些修正bug，“显而易见”的修改或者是类似的只需要很少讨论的补丁可以直接 +发送或者CC给Linus。那些需要讨论或者没有很清楚的好处的补丁，一般先发送到 +linux-kernel邮件列表。只有当补丁被讨论得差不多了，才提交给Linus。 + +5)选择CC( e-mail 抄送)列表 + +除非你有理由不这样做，否则CC linux-kernel@vger.kernel.org。 + +除了 Linus 之外，其他内核开发者也需要注意到你的改动，这样他们才能评论你 +的改动并提供代码审查和建议。linux-kernel 是 Linux 内核开发者主邮件列表 +。其它的邮件列表为特定的子系统提供服务，比如 USB，framebuffer 设备，虚 +拟文件系统，SCSI 子系统，等等。查看 MAINTAINERS 文件来获得和你的改动有 +关的邮件列表。 + +Majordomo lists of VGER.KERNEL.ORG at: + <http://vger.kernel.org/vger-lists.html> + +如果改动影响了用户空间和内核之间的接口，请给 MAN-PAGES 的维护者（列在 +MAINTAINERS 文件里的）发送一个手册页（man-pages）补丁，或者至少通知一下改 +变，让一些信息有途径进入手册页。 + +即使在第四步的时候，维护者没有作出回应，也要确认在修改他们的代码的时候 +，一直将维护者拷贝到CC列表中。 + +对于小的补丁，你也许会CC到 Adrian Bunk 管理的搜集琐碎补丁的邮件列表 +(Trivial Patch Monkey)trivial@kernel.org，那里专门收集琐碎的补丁。下面这样 +的补丁会被看作“琐碎的”补丁： + 文档的拼写修正。 + 修正会影响到 grep(1) 的拼写。 + 警告信息修正(频繁的打印无用的警告是不好的。) + 编译错误修正（代码逻辑的确是对的，只是编译有问题。） + 运行时修正（只要真的修正了错误。） + 移除使用了被废弃的函数/宏的代码(例如 check_region。) + 联系方式和文档修正。 + 用可移植的代码替换不可移植的代码（即使在体系结构相关的代码中，既然有 + 人拷贝，只要它是琐碎的） + 任何文件的作者/维护者对该文件的改动（例如 patch monkey 在重传模式下） + +EMAIL: trivial@kernel.org + +(译注，关于“琐碎补丁”的一些说明：因为原文的这一部分写得比较简单，所以不得不 +违例写一下译注。"trivial"这个英文单词的本意是“琐碎的，不重要的。”但是在这里 +有稍微有一些变化，例如对一些明显的NULL指针的修正，属于运行时修正，会被归类 +到琐碎补丁里。虽然NULL指针的修正很重要，但是这样的修正往往很小而且很容易得到 +检验，所以也被归入琐碎补丁。琐碎补丁更精确的归类应该是 +“simple, localized & easy to verify”，也就是说简单的，局部的和易于检验的。 +trivial@kernel.org邮件列表的目的是针对这样的补丁，为提交者提供一个中心，来 +降低提交的门槛。) + +6)没有 MIME 编码，没有链接，没有压缩，没有附件，只有纯文本。 + +Linus 和其他的内核开发者需要阅读和评论你提交的改动。对于内核开发者来说 +，可以“引用”你的改动很重要，使用一般的 e-mail 工具，他们就可以在你的 +代码的任何位置添加评论。 + +因为这个原因，所有的提交的补丁都是 e-mail 中“内嵌”的。 +警告：如果你使用剪切-粘贴你的补丁，小心你的编辑器的自动换行功能破坏你的 +补丁。 + +不要将补丁作为 MIME 编码的附件，不管是否压缩。很多流行的 e-mail 软件不 +是任何时候都将 MIME 编码的附件当作纯文本发送的，这会使得别人无法在你的 +代码中加评论。另外，MIME 编码的附件会让 Linus 多花一点时间来处理，这就 +降低了你的改动被接受的可能性。 + +警告：一些邮件软件，比如 Mozilla 会将你的信息以如下格式发送： +---- 邮件头 ---- +Content-Type: text/plain; charset=us-ascii; format=flowed +---- 邮件头 ---- +问题在于 “format=flowed” 会让接收端的某些邮件软件将邮件中的制表符替换 +成空格以及做一些类似的替换。这样，你发送的时候看起来没问题的补丁就被破 +坏了。 + +要修正这个问题，只需要将你的 mozilla 的 defaults/pref/mailnews.js 文件 +里的 +pref("mailnews.send_plaintext_flowed", false); // RFC 2646======= +修改成 +pref("mailnews.display.disable_format_flowed_support", true); +就可以了。 + +7) e-mail 的大小 + +给 Linus 发送补丁的时候，永远按照第6小节说的做。 + +大的改动对邮件列表不合适，对某些维护者也不合适。如果你的补丁，在不压缩 +的情况下，超过了40kB，那么你最好将补丁放在一个能通过 internet 访问的服 +务器上，然后用指向你的补丁的 URL 替代。 + +8) 指出你的内核版本 + +在标题和在补丁的描述中，指出补丁对应的内核的版本，是很重要的。 + +如果补丁不能干净的在最新版本的内核上打上，Linus 是不会接受它的。 + +9) 不要气馁，继续提交。 + +当你提交了改动以后，耐心地等待。如果 Linus 喜欢你的改动并且同意它，那么 +它将在下一个内核发布版本中出现。 + +然而，如果你的改动没有出现在下一个版本的内核中，可能有若干原因。减少那 +些原因，修正错误，重新提交更新后的改动，是你自己的工作。 + +Linus不给出任何评论就“丢弃”你的补丁是常见的事情。在系统中这样的事情很 +平常。如果他没有接受你的补丁，也许是由于以下原因： +* 你的补丁不能在最新版本的内核上干净的打上。 +* 你的补丁在 linux-kernel 邮件列表中没有得到充分的讨论。 +* 风格问题（参照第2小节） +* 邮件格式问题（重读本节） +* 你的改动有技术问题。 +* 他收到了成吨的 e-mail，而你的在混乱中丢失了。 +* 你让人为难。 + +有疑问的时候，在 linux-kernel 邮件列表上请求评论。 + +10) 在标题上加上 PATCH 的字样 + +Linus 和 linux-kernel 邮件列表的 e-mail 流量都很高，一个通常的约定是标 +题行以 [PATCH] 开头。这样可以让 Linus 和其他内核开发人员可以从 e-mail +的讨论中很轻易的将补丁分辨出来。 + +11）为你的工作签名 + +为了加强对谁做了何事的追踪，尤其是对那些透过好几层的维护者的补丁，我们 +建议在发送出去的补丁上加一个 “sign-off” 的过程。 + +"sign-off" 是在补丁的注释的最后的简单的一行文字，认证你编写了它或者其他 +人有权力将它作为开放源代码的补丁传递。规则很简单：如果你能认证如下信息 +： + 开发者来源证书 1.1 + 对于本项目的贡献，我认证如下信息： + （a）这些贡献是完全或者部分的由我创建，我有权利以文件中指出 + 的开放源代码许可证提交它；或者 + （b）这些贡献基于以前的工作，据我所知，这些以前的工作受恰当的开放 + 源代码许可证保护，而且，根据许可证，我有权提交修改后的贡献， + 无论是完全还是部分由我创造，这些贡献都使用同一个开放源代码许可证 + （除非我被允许用其它的许可证），正如文件中指出的；或者 + （c）这些贡献由认证（a），（b）或者（c）的人直接提供给我，而 + 且我没有修改它。 + （d）我理解并同意这个项目和贡献是公开的，贡献的记录（包括我 + 一起提交的个人记录，包括 sign-off ）被永久维护并且可以和这个项目 + 或者开放源代码的许可证同步地再发行。 + 那么加入这样一行： + Signed-off-by: Random J Developer <random@developer.example.org> + +使用你的真名（抱歉，不能使用假名或者匿名。） + +有人在最后加上标签。现在这些东西会被忽略，但是你可以这样做，来标记公司 +内部的过程，或者只是指出关于 sign-off 的一些特殊细节。 + +12）标准补丁格式 + +标准的补丁，标题行是： + Subject: [PATCH 001/123] 子系统:一句话概述 + +标准补丁的信体存在如下部分： + + - 一个 "from" 行指出补丁作者。 + + - 一个空行 + + - 说明的主体，这些说明文字会被拷贝到描述该补丁的永久改动记录里。 + + - 一个由"---"构成的标记行 + + - 不合适放到改动记录里的额外的注解。 + + - 补丁本身（diff 输出） + +标题行的格式，使得对标题行按字母序排序非常的容易 - 很多 e-mail 客户端都 +可以支持 - 因为序列号是用零填充的，所以按数字排序和按字母排序是一样的。 + +e-mail 标题中的“子系统”标识哪个内核子系统将被打补丁。 + +e-mail 标题中的“一句话概述”扼要的描述 e-mail 中的补丁。“一句话概述” +不应该是一个文件名。对于一个补丁系列（“补丁系列”指一系列的多个相关补 +丁），不要对每个补丁都使用同样的“一句话概述”。 + +记住 e-mail 的“一句话概述”会成为该补丁的全局唯一标识。它会蔓延到 git +的改动记录里。然后“一句话概述”会被用在开发者的讨论里，用来指代这个补 +丁。用户将希望通过 google 来搜索"一句话概述"来找到那些讨论这个补丁的文 +章。 + +一些标题的例子： + + Subject: [patch 2/5] ext2: improve scalability of bitmap searching + Subject: [PATCHv2 001/207] x86: fix eflags tracking + +"from" 行是信体里的最上面一行，具有如下格式： + From: Original Author <author@example.com> + +"from" 行指明在永久改动日志里，谁会被确认为作者。如果没有 "from" 行，那 +么邮件头里的 "From: " 行会被用来决定改动日志中的作者。 + +说明的主题将会被提交到永久的源代码改动日志里，因此对那些早已经不记得和 +这个补丁相关的讨论细节的有能力的读者来说，是有意义的。 + +"---" 标记行对于补丁处理工具要找到哪里是改动日志信息的结束，是不可缺少 +的。 + +对于 "---" 标记之后的额外注解，一个好的用途就是用来写 diffstat，用来显 +示修改了什么文件和每个文件都增加和删除了多少行。diffstat 对于比较大的补 +丁特别有用。其余那些只是和时刻或者开发者相关的注解，不合适放到永久的改 +动日志里的，也应该放这里。 +使用 diffstat的选项 "-p 1 -w 70" 这样文件名就会从内核源代码树的目录开始 +，不会占用太宽的空间（很容易适合80列的宽度，也许会有一些缩进。） + +在后面的参考资料中能看到适当的补丁格式的更多细节。 + +------------------------------- +第二节 提示，建议和诀窍 +------------------------------- + +本节包含很多和提交到内核的代码有关的通常的"规则"。事情永远有例外...但是 +你必须真的有好的理由这样做。你可以把本节叫做Linus的计算机科学入门课。 + +1) 读 Document/process/coding-style.rst + +Nuff 说过，如果你的代码和这个偏离太多，那么它有可能会被拒绝，没有更多的 +审查，没有更多的评价。 + +2) #ifdef 是丑陋的 +混杂了 ifdef 的代码难以阅读和维护。别这样做。作为替代，将你的 ifdef 放 +在头文件里，有条件地定义 "static inline" 函数，或者宏，在代码里用这些东 +西。让编译器把那些"空操作"优化掉。 + +一个简单的例子，不好的代码： + + dev = alloc_etherdev (sizeof(struct funky_private)); + if (!dev) + return -ENODEV; + #ifdef CONFIG_NET_FUNKINESS + init_funky_net(dev); + #endif + +清理后的例子: + +(头文件里) + #ifndef CONFIG_NET_FUNKINESS + static inline void init_funky_net (struct net_device *d) {} + #endif + +(代码文件里) + dev = alloc_etherdev (sizeof(struct funky_private)); + if (!dev) + return -ENODEV; + init_funky_net(dev); + +3) 'static inline' 比宏好 + +Static inline 函数相比宏来说，是好得多的选择。Static inline 函数提供了 +类型安全，没有长度限制，没有格式限制，在 gcc 下开销和宏一样小。 + +宏只在 static inline 函数不是最优的时候[在 fast paths 里有很少的独立的 +案例]，或者不可能用 static inline 函数的时候[例如字符串分配]。 +应该用 'static inline' 而不是 'static __inline__', 'extern inline' 和 +'extern __inline__' 。 + +4) 不要过度设计 + +不要试图预计模糊的未来事情，这些事情也许有用也许没有用："让事情尽可能的 +简单，而不是更简单"。 + +---------------- +第三节 参考文献 +---------------- + +Andrew Morton, "The perfect patch" (tpp). + <http://www.ozlabs.org/~akpm/stuff/tpp.txt> + +Jeff Garzik, "Linux kernel patch submission format". + <http://linux.yyz.us/patch-format.html> + +Greg Kroah-Hartman, "How to piss off a kernel subsystem maintainer". + <http://www.kroah.com/log/2005/03/31/> + <http://www.kroah.com/log/2005/07/08/> + <http://www.kroah.com/log/2005/10/19/> + <http://www.kroah.com/log/2006/01/11/> + +NO!!!! No more huge patch bombs to linux-kernel@vger.kernel.org people! + <https://lkml.org/lkml/2005/7/11/336> + +Kernel Documentation/process/coding-style.rst: + <http://sosdg.org/~coywolf/lxr/source/Documentation/process/coding-style.rst> + +Linus Torvalds's mail on the canonical patch format: + <http://lkml.org/lkml/2005/4/7/183> +-- diff --git a/Documentation/translations/zh_CN/arm/Booting b/Documentation/translations/zh_CN/arm/Booting new file mode 100644 index 000000000..1fe866f82 --- /dev/null +++ b/Documentation/translations/zh_CN/arm/Booting @@ -0,0 +1,175 @@ +Chinese translated version of Documentation/arm/Booting + +If you have any comment or update to the content, please contact the +original document maintainer directly. However, if you have a problem +communicating in English you can also ask the Chinese maintainer for +help. Contact the Chinese maintainer if this translation is outdated +or if there is a problem with the translation. + +Maintainer: Russell King <linux@arm.linux.org.uk> +Chinese maintainer: Fu Wei <tekkamanninja@gmail.com> +--------------------------------------------------------------------- +Documentation/arm/Booting 的中文翻译 + +如果想评论或更新本文的内容，请直接联系原文档的维护者。如果你使用英文 +交流有困难的话，也可以向中文版维护者求助。如果本翻译更新不及时或者翻 +译存在问题，请联系中文版维护者。 + +英文版维护者： Russell King <linux@arm.linux.org.uk> +中文版维护者： 傅炜 Fu Wei <tekkamanninja@gmail.com> +中文版翻译者： 傅炜 Fu Wei <tekkamanninja@gmail.com> +中文版校译者： 傅炜 Fu Wei <tekkamanninja@gmail.com> + +以下为正文 +--------------------------------------------------------------------- + + 启动 ARM Linux + ============== + +作者：Russell King +日期：2002年5月18日 + +以下文档适用于 2.4.18-rmk6 及以上版本。 + +为了启动 ARM Linux，你需要一个引导装载程序（boot loader）， +它是一个在主内核启动前运行的一个小程序。引导装载程序需要初始化各种 +设备，并最终调用 Linux 内核，将信息传递给内核。 + +从本质上讲，引导装载程序应提供（至少）以下功能： + +1、设置和初始化 RAM。 +2、初始化一个串口。 +3、检测机器的类型（machine type）。 +4、设置内核标签列表（tagged list）。 +5、调用内核映像。 + + +1、设置和初始化 RAM +------------------- + +现有的引导加载程序: 强制 +新开发的引导加载程序: 强制 + +引导装载程序应该找到并初始化系统中所有内核用于保持系统变量数据的 RAM。 +这个操作的执行是设备依赖的。（它可能使用内部算法来自动定位和计算所有 +RAM，或可能使用对这个设备已知的 RAM 信息，还可能使用任何引导装载程序 +设计者想到的匹配方法。） + + +2、初始化一个串口 +----------------------------- + +现有的引导加载程序: 可选、建议 +新开发的引导加载程序: 可选、建议 + +引导加载程序应该初始化并使能一个目标板上的串口。这允许内核串口驱动 +自动检测哪个串口用于内核控制台。(一般用于调试或与目标板通信。) + +作为替代方案，引导加载程序也可以通过标签列表传递相关的'console=' +选项给内核以指定某个串口，而串口数据格式的选项在以下文档中描述： + + Documentation/admin-guide/kernel-parameters.rst。 + + +3、检测机器类型 +-------------------------- + +现有的引导加载程序: 可选 +新开发的引导加载程序: 强制 + +引导加载程序应该通过某些方式检测自身所处的机器类型。这是一个硬件 +代码或通过查看所连接的硬件用某些算法得到，这些超出了本文档的范围。 +引导加载程序最终必须能提供一个 MACH_TYPE_xxx 值给内核。 +(详见 linux/arch/arm/tools/mach-types )。 + +4、设置启动数据 +------------------ + +现有的引导加载程序: 可选、强烈建议 +新开发的引导加载程序: 强制 + +引导加载程序必须提供标签列表或者 dtb 映像以传递配置数据给内核。启动 +数据的物理地址通过寄存器 r2 传递给内核。 + +4a、设置内核标签列表 +-------------------------------- + +bootloader 必须创建和初始化内核标签列表。一个有效的标签列表以 +ATAG_CORE 标签开始，并以 ATAG_NONE 标签结束。ATAG_CORE 标签可以是 +空的，也可以是非空。一个空 ATAG_CORE 标签其 size 域设置为 +‘2’(0x00000002)。ATAG_NONE 标签的 size 域必须设置为零。 + +在列表中可以保存任意数量的标签。对于一个重复的标签是追加到之前标签 +所携带的信息之后，还是会覆盖原来的信息，是未定义的。某些标签的行为 +是前者，其他是后者。 + +bootloader 必须传递一个系统内存的位置和最小值，以及根文件系统位置。 +因此，最小的标签列表如下所示： + + +-----------+ +基地址 -> | ATAG_CORE | | + +-----------+ | + | ATAG_MEM | | 地址增长方向 + +-----------+ | + | ATAG_NONE | | + +-----------+ v + +标签列表应该保存在系统的 RAM 中。 + +标签列表必须置于内核自解压和 initrd'bootp' 程序都不会覆盖的内存区。 +建议放在 RAM 的头 16KiB 中。 + +4b、设置设备树 +------------------------- + +bootloader 必须以 64bit 地址对齐的形式加载一个设备树映像(dtb)到系统 +RAM 中，并用启动数据初始化它。dtb 格式在文档 +Documentation/devicetree/booting-without-of.txt 中。内核将会在 +dtb 物理地址处查找 dtb 魔数值（0xd00dfeed），以确定 dtb 是否已经代替 +标签列表被传递进来。 + +bootloader 必须传递一个系统内存的位置和最小值，以及根文件系统位置。 +dtb 必须置于内核自解压不会覆盖的内存区。建议将其放置于 RAM 的头 16KiB +中。但是不可将其放置于“0”物理地址处，因为内核认为：r2 中为 0，意味着 +没有标签列表和 dtb 传递过来。 + +5、调用内核映像 +--------------------------- + +现有的引导加载程序: 强制 +新开发的引导加载程序: 强制 + +调用内核映像 zImage 有两个选择。如果 zImge 保存在 flash 中，且是为了 +在 flash 中直接运行而被正确链接的。这样引导加载程序就可以在 flash 中 +直接调用 zImage。 + +zImage 也可以被放在系统 RAM（任意位置）中被调用。注意：内核使用映像 +基地址的前 16KB RAM 空间来保存页表。建议将映像置于 RAM 的 32KB 处。 + +对于以上任意一种情况，都必须符合以下启动状态： + +- 停止所有 DMA 设备，这样内存数据就不会因为虚假网络包或磁盘数据而被破坏。 + 这可能可以节省你许多的调试时间。 + +- CPU 寄存器配置 + r0 = 0， + r1 = （在上面 3 中获取的）机器类型码。 + r2 = 标签列表在系统 RAM 中的物理地址，或 + 设备树块(dtb)在系统 RAM 中的物理地址 + +- CPU 模式 + 所有形式的中断必须被禁止 (IRQs 和 FIQs) + CPU 必须处于 SVC 模式。(对于 Angel 调试有特例存在) + +- 缓存，MMUs + MMU 必须关闭。 + 指令缓存开启或关闭都可以。 + 数据缓存必须关闭。 + +- 引导加载程序应该通过直接跳转到内核映像的第一条指令来调用内核映像。 + + 对于支持 ARM 指令集的 CPU，跳入内核入口时必须处在 ARM 状态，即使 + 对于 Thumb-2 内核也是如此。 + + 对于仅支持 Thumb 指令集的 CPU，比如 Cortex-M 系列的 CPU，跳入 + 内核入口时必须处于 Thumb 状态。 diff --git a/Documentation/translations/zh_CN/arm/kernel_user_helpers.txt b/Documentation/translations/zh_CN/arm/kernel_user_helpers.txt new file mode 100644 index 000000000..cd7fc8f34 --- /dev/null +++ b/Documentation/translations/zh_CN/arm/kernel_user_helpers.txt @@ -0,0 +1,284 @@ +Chinese translated version of Documentation/arm/kernel_user_helpers.txt + +If you have any comment or update to the content, please contact the +original document maintainer directly. However, if you have a problem +communicating in English you can also ask the Chinese maintainer for +help. Contact the Chinese maintainer if this translation is outdated +or if there is a problem with the translation. + +Maintainer: Nicolas Pitre <nicolas.pitre@linaro.org> + Dave Martin <dave.martin@linaro.org> +Chinese maintainer: Fu Wei <tekkamanninja@gmail.com> +--------------------------------------------------------------------- +Documentation/arm/kernel_user_helpers.txt 的中文翻译 + +如果想评论或更新本文的内容，请直接联系原文档的维护者。如果你使用英文 +交流有困难的话，也可以向中文版维护者求助。如果本翻译更新不及时或者翻 +译存在问题，请联系中文版维护者。 +英文版维护者： Nicolas Pitre <nicolas.pitre@linaro.org> + Dave Martin <dave.martin@linaro.org> +中文版维护者： 傅炜 Fu Wei <tekkamanninja@gmail.com> +中文版翻译者： 傅炜 Fu Wei <tekkamanninja@gmail.com> +中文版校译者： 宋冬生 Dongsheng Song <dongshneg.song@gmail.com> + 傅炜 Fu Wei <tekkamanninja@gmail.com> + + +以下为正文 +--------------------------------------------------------------------- +内核提供的用户空间辅助代码 +========================= + +在内核内存空间的固定地址处，有一个由内核提供并可从用户空间访问的代码 +段。它用于向用户空间提供因在许多 ARM CPU 中未实现的特性和/或指令而需 +内核提供帮助的某些操作。这些代码直接在用户模式下执行的想法是为了获得 +最佳效率，但那些与内核计数器联系过于紧密的部分，则被留给了用户库实现。 +事实上，此代码甚至可能因不同的 CPU 而异，这取决于其可用的指令集或它 +是否为 SMP 系统。换句话说，内核保留在不作出警告的情况下根据需要更改 +这些代码的权利。只有本文档描述的入口及其结果是保证稳定的。 + +这与完全成熟的 VDSO 实现不同（但两者并不冲突），尽管如此，VDSO 可阻止 +某些通过常量高效跳转到那些代码段的汇编技巧。且由于那些代码段在返回用户 +代码前仅使用少量的代码周期，则一个 VDSO 间接远程调用将会在这些简单的 +操作上增加一个可测量的开销。 + +在对那些拥有原生支持的新型处理器进行代码优化时，仅在已为其他操作使用 +了类似的新增指令，而导致二进制结果已与早期 ARM 处理器不兼容的情况下， +用户空间才应绕过这些辅助代码，并在内联函数中实现这些操作（无论是通过 +编译器在代码中直接放置，还是作为库函数调用实现的一部分）。也就是说， +如果你编译的代码不会为了其他目的使用新指令，则不要仅为了避免使用这些 +内核辅助代码，导致二进制程序无法在早期处理器上运行。 + +新的辅助代码可能随着时间的推移而增加，所以新内核中的某些辅助代码在旧 +内核中可能不存在。因此，程序必须在对任何辅助代码调用假设是安全之前， +检测 __kuser_helper_version 的值（见下文）。理想情况下，这种检测应该 +只在进程启动时执行一次；如果内核版本不支持所需辅助代码，则该进程可尽早 +中止执行。 + +kuser_helper_version +-------------------- + +位置: 0xffff0ffc + +参考声明: + + extern int32_t __kuser_helper_version; + +定义: + + 这个区域包含了当前运行内核实现的辅助代码版本号。用户空间可以通过读 + 取此版本号以确定特定的辅助代码是否存在。 + +使用范例: + +#define __kuser_helper_version (*(int32_t *)0xffff0ffc) + +void check_kuser_version(void) +{ + if (__kuser_helper_version < 2) { + fprintf(stderr, "can't do atomic operations, kernel too old\n"); + abort(); + } +} + +注意: + + 用户空间可以假设这个域的值不会在任何单个进程的生存期内改变。也就 + 是说，这个域可以仅在库的初始化阶段或进程启动阶段读取一次。 + +kuser_get_tls +------------- + +位置: 0xffff0fe0 + +参考原型: + + void * __kuser_get_tls(void); + +输入: + + lr = 返回地址 + +输出: + + r0 = TLS 值 + +被篡改的寄存器: + + 无 + +定义: + + 获取之前通过 __ARM_NR_set_tls 系统调用设置的 TLS 值。 + +使用范例: + +typedef void * (__kuser_get_tls_t)(void); +#define __kuser_get_tls (*(__kuser_get_tls_t *)0xffff0fe0) + +void foo() +{ + void *tls = __kuser_get_tls(); + printf("TLS = %p\n", tls); +} + +注意: + + - 仅在 __kuser_helper_version >= 1 时，此辅助代码存在 + （从内核版本 2.6.12 开始）。 + +kuser_cmpxchg +------------- + +位置: 0xffff0fc0 + +参考原型: + + int __kuser_cmpxchg(int32_t oldval, int32_t newval, volatile int32_t *ptr); + +输入: + + r0 = oldval + r1 = newval + r2 = ptr + lr = 返回地址 + +输出: + + r0 = 成功代码 (零或非零) + C flag = 如果 r0 == 0 则置 1，如果 r0 != 0 则清零。 + +被篡改的寄存器: + + r3, ip, flags + +定义: + + 仅在 *ptr 为 oldval 时原子保存 newval 于 *ptr 中。 + 如果 *ptr 被改变，则返回值为零，否则为非零值。 + 如果 *ptr 被改变，则 C flag 也会被置 1，以实现调用代码中的汇编 + 优化。 + +使用范例: + +typedef int (__kuser_cmpxchg_t)(int oldval, int newval, volatile int *ptr); +#define __kuser_cmpxchg (*(__kuser_cmpxchg_t *)0xffff0fc0) + +int atomic_add(volatile int *ptr, int val) +{ + int old, new; + + do { + old = *ptr; + new = old + val; + } while(__kuser_cmpxchg(old, new, ptr)); + + return new; +} + +注意: + + - 这个例程已根据需要包含了内存屏障。 + + - 仅在 __kuser_helper_version >= 2 时，此辅助代码存在 + （从内核版本 2.6.12 开始）。 + +kuser_memory_barrier +-------------------- + +位置: 0xffff0fa0 + +参考原型: + + void __kuser_memory_barrier(void); + +输入: + + lr = 返回地址 + +输出: + + 无 + +被篡改的寄存器: + + 无 + +定义: + + 应用于任何需要内存屏障以防止手动数据修改带来的一致性问题，以及 + __kuser_cmpxchg 中。 + +使用范例: + +typedef void (__kuser_dmb_t)(void); +#define __kuser_dmb (*(__kuser_dmb_t *)0xffff0fa0) + +注意: + + - 仅在 __kuser_helper_version >= 3 时，此辅助代码存在 + （从内核版本 2.6.15 开始）。 + +kuser_cmpxchg64 +--------------- + +位置: 0xffff0f60 + +参考原型: + + int __kuser_cmpxchg64(const int64_t *oldval, + const int64_t *newval, + volatile int64_t *ptr); + +输入: + + r0 = 指向 oldval + r1 = 指向 newval + r2 = 指向目标值 + lr = 返回地址 + +输出: + + r0 = 成功代码 (零或非零) + C flag = 如果 r0 == 0 则置 1，如果 r0 != 0 则清零。 + +被篡改的寄存器: + + r3, lr, flags + +定义: + + 仅在 *ptr 等于 *oldval 指向的 64 位值时，原子保存 *newval + 指向的 64 位值于 *ptr 中。如果 *ptr 被改变，则返回值为零， + 否则为非零值。 + + 如果 *ptr 被改变，则 C flag 也会被置 1，以实现调用代码中的汇编 + 优化。 + +使用范例: + +typedef int (__kuser_cmpxchg64_t)(const int64_t *oldval, + const int64_t *newval, + volatile int64_t *ptr); +#define __kuser_cmpxchg64 (*(__kuser_cmpxchg64_t *)0xffff0f60) + +int64_t atomic_add64(volatile int64_t *ptr, int64_t val) +{ + int64_t old, new; + + do { + old = *ptr; + new = old + val; + } while(__kuser_cmpxchg64(&old, &new, ptr)); + + return new; +} + +注意: + + - 这个例程已根据需要包含了内存屏障。 + + - 由于这个过程的代码长度（此辅助代码跨越 2 个常规的 kuser “槽”）， + 因此 0xffff0f80 不被作为有效的入口点。 + + - 仅在 __kuser_helper_version >= 5 时，此辅助代码存在 + （从内核版本 3.1 开始）。 diff --git a/Documentation/translations/zh_CN/arm64/booting.txt b/Documentation/translations/zh_CN/arm64/booting.txt new file mode 100644 index 000000000..c1dd968c5 --- /dev/null +++ b/Documentation/translations/zh_CN/arm64/booting.txt @@ -0,0 +1,246 @@ +Chinese translated version of Documentation/arm64/booting.txt + +If you have any comment or update to the content, please contact the +original document maintainer directly. However, if you have a problem +communicating in English you can also ask the Chinese maintainer for +help. Contact the Chinese maintainer if this translation is outdated +or if there is a problem with the translation. + +M: Will Deacon <will.deacon@arm.com> +zh_CN: Fu Wei <wefu@redhat.com> +C: 55f058e7574c3615dea4615573a19bdb258696c6 +--------------------------------------------------------------------- +Documentation/arm64/booting.txt 的中文翻译 + +如果想评论或更新本文的内容，请直接联系原文档的维护者。如果你使用英文 +交流有困难的话，也可以向中文版维护者求助。如果本翻译更新不及时或者翻 +译存在问题，请联系中文版维护者。 + +英文版维护者： Will Deacon <will.deacon@arm.com> +中文版维护者： 傅炜 Fu Wei <wefu@redhat.com> +中文版翻译者： 傅炜 Fu Wei <wefu@redhat.com> +中文版校译者： 傅炜 Fu Wei <wefu@redhat.com> +本文翻译提交时的 Git 检出点为： 55f058e7574c3615dea4615573a19bdb258696c6 + +以下为正文 +--------------------------------------------------------------------- + 启动 AArch64 Linux + ================== + +作者: Will Deacon <will.deacon@arm.com> +日期: 2012 年 09 月 07 日 + +本文档基于 Russell King 的 ARM 启动文档，且适用于所有公开发布的 +AArch64 Linux 内核代码。 + +AArch64 异常模型由多个异常级（EL0 - EL3）组成，对于 EL0 和 EL1 异常级 +有对应的安全和非安全模式。EL2 是系统管理级，且仅存在于非安全模式下。 +EL3 是最高特权级，且仅存在于安全模式下。 + +基于本文档的目的，我们将简单地使用‘引导装载程序’（‘boot loader’） +这个术语来定义在将控制权交给 Linux 内核前 CPU 上执行的所有软件。 +这可能包含安全监控和系统管理代码，或者它可能只是一些用于准备最小启动 +环境的指令。 + +基本上，引导装载程序（至少）应实现以下操作： + +1、设置和初始化 RAM +2、设置设备树数据 +3、解压内核映像 +4、调用内核映像 + + +1、设置和初始化 RAM +----------------- + +必要性: 强制 + +引导装载程序应该找到并初始化系统中所有内核用于保持系统变量数据的 RAM。 +这个操作的执行方式因设备而异。（它可能使用内部算法来自动定位和计算所有 +RAM，或可能使用对这个设备已知的 RAM 信息，还可能是引导装载程序设计者 +想到的任何合适的方法。） + + +2、设置设备树数据 +--------------- + +必要性: 强制 + +设备树数据块（dtb）必须 8 字节对齐，且大小不能超过 2MB。由于设备树 +数据块将在使能缓存的情况下以 2MB 粒度被映射，故其不能被置于带任意 +特定属性被映射的 2MB 区域内。 + +注： v4.2 之前的版本同时要求设备树数据块被置于从内核映像以下 +text_offset 字节处算起第一个 512MB 内。 + +3、解压内核映像 +------------- + +必要性: 可选 + +AArch64 内核当前没有提供自解压代码，因此如果使用了压缩内核映像文件 +（比如 Image.gz），则需要通过引导装载程序（使用 gzip 等）来进行解压。 +若引导装载程序没有实现这个功能，就要使用非压缩内核映像文件。 + + +4、调用内核映像 +------------- + +必要性: 强制 + +已解压的内核映像包含一个 64 字节的头，内容如下： + + u32 code0; /* 可执行代码 */ + u32 code1; /* 可执行代码 */ + u64 text_offset; /* 映像装载偏移，小端模式 */ + u64 image_size; /* 映像实际大小, 小端模式 */ + u64 flags; /* 内核旗标, 小端模式 * + u64 res2 = 0; /* 保留 */ + u64 res3 = 0; /* 保留 */ + u64 res4 = 0; /* 保留 */ + u32 magic = 0x644d5241; /* 魔数, 小端, "ARM\x64" */ + u32 res5; /* 保留 （用于 PE COFF 偏移） */ + + +映像头注释： + +- 自 v3.17 起，除非另有说明，所有域都是小端模式。 + +- code0/code1 负责跳转到 stext. + +- 当通过 EFI 启动时， 最初 code0/code1 被跳过。 + res5 是到 PE 文件头的偏移，而 PE 文件头含有 EFI 的启动入口点 + （efi_stub_entry）。当 stub 代码完成了它的使命，它会跳转到 code0 + 继续正常的启动流程。 + +- v3.17 之前，未明确指定 text_offset 的字节序。此时，image_size 为零， + 且 text_offset 依照内核字节序为 0x80000。 + 当 image_size 非零，text_offset 为小端模式且是有效值，应被引导加载 + 程序使用。当 image_size 为零，text_offset 可假定为 0x80000。 + +- flags 域 (v3.17 引入) 为 64 位小端模式，其编码如下： + 位 0: 内核字节序。 1 表示大端模式，0 表示小端模式。 + 位 1-2: 内核页大小。 + 0 - 未指定。 + 1 - 4K + 2 - 16K + 3 - 64K + 位 3: 内核物理位置 + 0 - 2MB 对齐基址应尽量靠近内存起始处，因为 + 其基址以下的内存无法通过线性映射访问 + 1 - 2MB 对齐基址可以在物理内存的任意位置 + 位 4-63: 保留。 + +- 当 image_size 为零时，引导装载程序应试图在内核映像末尾之后尽可能 + 多地保留空闲内存供内核直接使用。对内存空间的需求量因所选定的内核 + 特性而异, 并无实际限制。 + +内核映像必须被放置在任意一个可用系统内存 2MB 对齐基址的 text_offset +字节处，并从该处被调用。2MB 对齐基址和内核映像起始地址之间的区域对于 +内核来说没有特殊意义，且可能被用于其他目的。 +从映像起始地址算起，最少必须准备 image_size 字节的空闲内存供内核使用。 +注： v4.6 之前的版本无法使用内核映像物理偏移以下的内存，所以当时建议 +将映像尽量放置在靠近系统内存起始的地方。 + +任何提供给内核的内存（甚至在映像起始地址之前），若未从内核中标记为保留 +(如在设备树（dtb）的 memreserve 区域），都将被认为对内核是可用。 + +在跳转入内核前，必须符合以下状态： + +- 停止所有 DMA 设备，这样内存数据就不会因为虚假网络包或磁盘数据而 + 被破坏。这可能可以节省你许多的调试时间。 + +- 主 CPU 通用寄存器设置 + x0 = 系统 RAM 中设备树数据块（dtb）的物理地址。 + x1 = 0 (保留，将来可能使用) + x2 = 0 (保留，将来可能使用) + x3 = 0 (保留，将来可能使用) + +- CPU 模式 + 所有形式的中断必须在 PSTATE.DAIF 中被屏蔽（Debug、SError、IRQ + 和 FIQ）。 + CPU 必须处于 EL2（推荐，可访问虚拟化扩展）或非安全 EL1 模式下。 + +- 高速缓存、MMU + MMU 必须关闭。 + 指令缓存开启或关闭皆可。 + 已载入的内核映像的相应内存区必须被清理，以达到缓存一致性点（PoC）。 + 当存在系统缓存或其他使能缓存的一致性主控器时，通常需使用虚拟地址 + 维护其缓存，而非 set/way 操作。 + 遵从通过虚拟地址操作维护构架缓存的系统缓存必须被配置，并可以被使能。 + 而不通过虚拟地址操作维护构架缓存的系统缓存（不推荐），必须被配置且 + 禁用。 + + *译者注：对于 PoC 以及缓存相关内容，请参考 ARMv8 构架参考手册 + ARM DDI 0487A + +- 架构计时器 + CNTFRQ 必须设定为计时器的频率，且 CNTVOFF 必须设定为对所有 CPU + 都一致的值。如果在 EL1 模式下进入内核，则 CNTHCTL_EL2 中的 + EL1PCTEN (bit 0) 必须置位。 + +- 一致性 + 通过内核启动的所有 CPU 在内核入口地址上必须处于相同的一致性域中。 + 这可能要根据具体实现来定义初始化过程，以使能每个CPU上对维护操作的 + 接收。 + +- 系统寄存器 + 在进入内核映像的异常级中，所有构架中可写的系统寄存器必须通过软件 + 在一个更高的异常级别下初始化，以防止在 未知 状态下运行。 + + 对于拥有 GICv3 中断控制器并以 v3 模式运行的系统： + - 如果 EL3 存在： + ICC_SRE_EL3.Enable (位 3) 必须初始化为 0b1。 + ICC_SRE_EL3.SRE (位 0) 必须初始化为 0b1。 + - 若内核运行在 EL1： + ICC_SRE_EL2.Enable (位 3) 必须初始化为 0b1。 + ICC_SRE_EL2.SRE (位 0) 必须初始化为 0b1。 + - 设备树（DT）或 ACPI 表必须描述一个 GICv3 中断控制器。 + + 对于拥有 GICv3 中断控制器并以兼容（v2）模式运行的系统： + - 如果 EL3 存在： + ICC_SRE_EL3.SRE (位 0) 必须初始化为 0b0。 + - 若内核运行在 EL1： + ICC_SRE_EL2.SRE (位 0) 必须初始化为 0b0。 + - 设备树（DT）或 ACPI 表必须描述一个 GICv2 中断控制器。 + +以上对于 CPU 模式、高速缓存、MMU、架构计时器、一致性、系统寄存器的 +必要条件描述适用于所有 CPU。所有 CPU 必须在同一异常级别跳入内核。 + +引导装载程序必须在每个 CPU 处于以下状态时跳入内核入口： + +- 主 CPU 必须直接跳入内核映像的第一条指令。通过此 CPU 传递的设备树 + 数据块必须在每个 CPU 节点中包含一个 ‘enable-method’ 属性，所 + 支持的 enable-method 请见下文。 + + 引导装载程序必须生成这些设备树属性，并在跳入内核入口之前将其插入 + 数据块。 + +- enable-method 为 “spin-table” 的 CPU 必须在它们的 CPU + 节点中包含一个 ‘cpu-release-addr’ 属性。这个属性标识了一个 + 64 位自然对齐且初始化为零的内存位置。 + + 这些 CPU 必须在内存保留区（通过设备树中的 /memreserve/ 域传递 + 给内核）中自旋于内核之外，轮询它们的 cpu-release-addr 位置（必须 + 包含在保留区中）。可通过插入 wfe 指令来降低忙循环开销，而主 CPU 将 + 发出 sev 指令。当对 cpu-release-addr 所指位置的读取操作返回非零值 + 时，CPU 必须跳入此值所指向的地址。此值为一个单独的 64 位小端值， + 因此 CPU 须在跳转前将所读取的值转换为其本身的端模式。 + +- enable-method 为 “psci” 的 CPU 保持在内核外（比如，在 + memory 节点中描述为内核空间的内存区外，或在通过设备树 /memreserve/ + 域中描述为内核保留区的空间中）。内核将会发起在 ARM 文档（编号 + ARM DEN 0022A：用于 ARM 上的电源状态协调接口系统软件）中描述的 + CPU_ON 调用来将 CPU 带入内核。 + + *译者注: ARM DEN 0022A 已更新到 ARM DEN 0022C。 + + 设备树必须包含一个 ‘psci’ 节点，请参考以下文档： + Documentation/devicetree/bindings/arm/psci.txt + + +- 辅助 CPU 通用寄存器设置 + x0 = 0 (保留，将来可能使用) + x1 = 0 (保留，将来可能使用) + x2 = 0 (保留，将来可能使用) + x3 = 0 (保留，将来可能使用) diff --git a/Documentation/translations/zh_CN/arm64/legacy_instructions.txt b/Documentation/translations/zh_CN/arm64/legacy_instructions.txt new file mode 100644 index 000000000..68362a1ab --- /dev/null +++ b/Documentation/translations/zh_CN/arm64/legacy_instructions.txt @@ -0,0 +1,72 @@ +Chinese translated version of Documentation/arm64/legacy_instructions.txt + +If you have any comment or update to the content, please contact the +original document maintainer directly. However, if you have a problem +communicating in English you can also ask the Chinese maintainer for +help. Contact the Chinese maintainer if this translation is outdated +or if there is a problem with the translation. + +Maintainer: Punit Agrawal <punit.agrawal@arm.com> + Suzuki K. Poulose <suzuki.poulose@arm.com> +Chinese maintainer: Fu Wei <wefu@redhat.com> +--------------------------------------------------------------------- +Documentation/arm64/legacy_instructions.txt 的中文翻译 + +如果想评论或更新本文的内容，请直接联系原文档的维护者。如果你使用英文 +交流有困难的话，也可以向中文版维护者求助。如果本翻译更新不及时或者翻 +译存在问题，请联系中文版维护者。 + +本文翻译提交时的 Git 检出点为： bc465aa9d045feb0e13b4a8f32cc33c1943f62d6 + +英文版维护者： Punit Agrawal <punit.agrawal@arm.com> + Suzuki K. Poulose <suzuki.poulose@arm.com> +中文版维护者： 傅炜 Fu Wei <wefu@redhat.com> +中文版翻译者： 傅炜 Fu Wei <wefu@redhat.com> +中文版校译者： 傅炜 Fu Wei <wefu@redhat.com> + +以下为正文 +--------------------------------------------------------------------- +Linux 内核在 arm64 上的移植提供了一个基础框架，以支持构架中正在被淘汰或已废弃指令的模拟执行。 +这个基础框架的代码使用未定义指令钩子（hooks）来支持模拟。如果指令存在，它也允许在硬件中启用该指令。 + +模拟模式可通过写 sysctl 节点（/proc/sys/abi）来控制。 +不同的执行方式及 sysctl 节点的相应值，解释如下： + +* Undef（未定义） + 值： 0 + 产生未定义指令终止异常。它是那些构架中已废弃的指令，如 SWP，的默认处理方式。 + +* Emulate（模拟） + 值： 1 + 使用软件模拟方式。为解决软件迁移问题，这种模拟指令模式的使用是被跟踪的，并会发出速率限制警告。 + 它是那些构架中正在被淘汰的指令，如 CP15 barriers（隔离指令），的默认处理方式。 + +* Hardware Execution（硬件执行） + 值： 2 + 虽然标记为正在被淘汰，但一些实现可能提供硬件执行这些指令的使能/禁用操作。 + 使用硬件执行一般会有更好的性能，但将无法收集运行时对正被淘汰指令的使用统计数据。 + +默认执行模式依赖于指令在构架中状态。正在被淘汰的指令应该以模拟（Emulate）作为默认模式， +而已废弃的指令必须默认使用未定义（Undef）模式 + +注意：指令模拟可能无法应对所有情况。更多详情请参考单独的指令注释。 + +受支持的遗留指令 +------------- +* SWP{B} +节点: /proc/sys/abi/swp +状态: 已废弃 +默认执行方式: Undef (0) + +* CP15 Barriers +节点: /proc/sys/abi/cp15_barrier +状态: 正被淘汰，不推荐使用 +默认执行方式: Emulate (1) + +* SETEND +节点: /proc/sys/abi/setend +状态: 正被淘汰，不推荐使用 +默认执行方式: Emulate (1)* +注：为了使能这个特性，系统中的所有 CPU 必须在 EL0 支持混合字节序。 +如果一个新的 CPU （不支持混合字节序） 在使能这个特性后被热插入系统， +在应用中可能会出现不可预期的结果。 diff --git a/Documentation/translations/zh_CN/arm64/memory.txt b/Documentation/translations/zh_CN/arm64/memory.txt new file mode 100644 index 000000000..19b3a52d5 --- /dev/null +++ b/Documentation/translations/zh_CN/arm64/memory.txt @@ -0,0 +1,114 @@ +Chinese translated version of Documentation/arm64/memory.txt + +If you have any comment or update to the content, please contact the +original document maintainer directly. However, if you have a problem +communicating in English you can also ask the Chinese maintainer for +help. Contact the Chinese maintainer if this translation is outdated +or if there is a problem with the translation. + +Maintainer: Catalin Marinas <catalin.marinas@arm.com> +Chinese maintainer: Fu Wei <wefu@redhat.com> +--------------------------------------------------------------------- +Documentation/arm64/memory.txt 的中文翻译 + +如果想评论或更新本文的内容，请直接联系原文档的维护者。如果你使用英文 +交流有困难的话，也可以向中文版维护者求助。如果本翻译更新不及时或者翻 +译存在问题，请联系中文版维护者。 + +本文翻译提交时的 Git 检出点为： bc465aa9d045feb0e13b4a8f32cc33c1943f62d6 + +英文版维护者： Catalin Marinas <catalin.marinas@arm.com> +中文版维护者： 傅炜 Fu Wei <wefu@redhat.com> +中文版翻译者： 傅炜 Fu Wei <wefu@redhat.com> +中文版校译者： 傅炜 Fu Wei <wefu@redhat.com> + +以下为正文 +--------------------------------------------------------------------- + Linux 在 AArch64 中的内存布局 + =========================== + +作者: Catalin Marinas <catalin.marinas@arm.com> + +本文档描述 AArch64 Linux 内核所使用的虚拟内存布局。此构架可以实现 +页大小为 4KB 的 4 级转换表和页大小为 64KB 的 3 级转换表。 + +AArch64 Linux 使用 3 级或 4 级转换表，其页大小配置为 4KB，对于用户和内核 +分别都有 39-bit (512GB) 或 48-bit (256TB) 的虚拟地址空间。 +对于页大小为 64KB的配置，仅使用 2 级转换表，有 42-bit (4TB) 的虚拟地址空间，但内存布局相同。 + +用户地址空间的 63:48 位为 0，而内核地址空间的相应位为 1。TTBRx 的 +选择由虚拟地址的 63 位给出。swapper_pg_dir 仅包含内核（全局）映射， +而用户 pgd 仅包含用户（非全局）映射。swapper_pg_dir 地址被写入 +TTBR1 中，且从不写入 TTBR0。 + + +AArch64 Linux 在页大小为 4KB，并使用 3 级转换表时的内存布局： + +起始地址 结束地址 大小 用途 +----------------------------------------------------------------------- +0000000000000000 0000007fffffffff 512GB 用户空间 +ffffff8000000000 ffffffffffffffff 512GB 内核空间 + + +AArch64 Linux 在页大小为 4KB，并使用 4 级转换表时的内存布局： + +起始地址 结束地址 大小 用途 +----------------------------------------------------------------------- +0000000000000000 0000ffffffffffff 256TB 用户空间 +ffff000000000000 ffffffffffffffff 256TB 内核空间 + + +AArch64 Linux 在页大小为 64KB，并使用 2 级转换表时的内存布局： + +起始地址 结束地址 大小 用途 +----------------------------------------------------------------------- +0000000000000000 000003ffffffffff 4TB 用户空间 +fffffc0000000000 ffffffffffffffff 4TB 内核空间 + + +AArch64 Linux 在页大小为 64KB，并使用 3 级转换表时的内存布局： + +起始地址 结束地址 大小 用途 +----------------------------------------------------------------------- +0000000000000000 0000ffffffffffff 256TB 用户空间 +ffff000000000000 ffffffffffffffff 256TB 内核空间 + + +更详细的内核虚拟内存布局，请参阅内核启动信息。 + + +4KB 页大小的转换表查找： + ++--------+--------+--------+--------+--------+--------+--------+--------+ +|63 56|55 48|47 40|39 32|31 24|23 16|15 8|7 0| ++--------+--------+--------+--------+--------+--------+--------+--------+ + | | | | | | + | | | | | v + | | | | | [11:0] 页内偏移 + | | | | +-> [20:12] L3 索引 + | | | +-----------> [29:21] L2 索引 + | | +---------------------> [38:30] L1 索引 + | +-------------------------------> [47:39] L0 索引 + +-------------------------------------------------> [63] TTBR0/1 + + +64KB 页大小的转换表查找： + ++--------+--------+--------+--------+--------+--------+--------+--------+ +|63 56|55 48|47 40|39 32|31 24|23 16|15 8|7 0| ++--------+--------+--------+--------+--------+--------+--------+--------+ + | | | | | + | | | | v + | | | | [15:0] 页内偏移 + | | | +----------> [28:16] L3 索引 + | | +--------------------------> [41:29] L2 索引 + | +-------------------------------> [47:42] L1 索引 + +-------------------------------------------------> [63] TTBR0/1 + + +当使用 KVM 时, 管理程序（hypervisor）在 EL2 中通过相对内核虚拟地址的 +一个固定偏移来映射内核页（内核虚拟地址的高 24 位设为零）: + +起始地址 结束地址 大小 用途 +----------------------------------------------------------------------- +0000004000000000 0000007fffffffff 256GB 在 HYP 中映射的内核对象 diff --git a/Documentation/translations/zh_CN/arm64/silicon-errata.txt b/Documentation/translations/zh_CN/arm64/silicon-errata.txt new file mode 100644 index 000000000..39477c75c --- /dev/null +++ b/Documentation/translations/zh_CN/arm64/silicon-errata.txt @@ -0,0 +1,74 @@ +Chinese translated version of Documentation/arm64/silicon-errata.txt + +If you have any comment or update to the content, please contact the +original document maintainer directly. However, if you have a problem +communicating in English you can also ask the Chinese maintainer for +help. Contact the Chinese maintainer if this translation is outdated +or if there is a problem with the translation. + +M: Will Deacon <will.deacon@arm.com> +zh_CN: Fu Wei <wefu@redhat.com> +C: 1926e54f115725a9248d0c4c65c22acaf94de4c4 +--------------------------------------------------------------------- +Documentation/arm64/silicon-errata.txt 的中文翻译 + +如果想评论或更新本文的内容，请直接联系原文档的维护者。如果你使用英文 +交流有困难的话，也可以向中文版维护者求助。如果本翻译更新不及时或者翻 +译存在问题，请联系中文版维护者。 + +英文版维护者： Will Deacon <will.deacon@arm.com> +中文版维护者： 傅炜 Fu Wei <wefu@redhat.com> +中文版翻译者： 傅炜 Fu Wei <wefu@redhat.com> +中文版校译者： 傅炜 Fu Wei <wefu@redhat.com> +本文翻译提交时的 Git 检出点为： 1926e54f115725a9248d0c4c65c22acaf94de4c4 + +以下为正文 +--------------------------------------------------------------------- + 芯片勘误和软件补救措施 + ================== + +作者: Will Deacon <will.deacon@arm.com> +日期: 2015年11月27日 + +一个不幸的现实：硬件经常带有一些所谓的“瑕疵（errata）”，导致其在 +某些特定情况下会违背构架定义的行为。就基于 ARM 的硬件而言，这些瑕疵 +大体可分为以下几类： + + A 类：无可行补救措施的严重缺陷。 + B 类：有可接受的补救措施的重大或严重缺陷。 + C 类：在正常操作中不会显现的小瑕疵。 + +更多资讯，请在 infocenter.arm.com （需注册）中查阅“软件开发者勘误 +笔记”（“Software Developers Errata Notice”）文档。 + +对于 Linux 而言，B 类缺陷可能需要操作系统的某些特别处理。例如，避免 +一个特殊的代码序列，或是以一种特定的方式配置处理器。在某种不太常见的 +情况下，为将 A 类缺陷当作 C 类处理，可能需要用类似的手段。这些手段被 +统称为“软件补救措施”，且仅在少数情况需要（例如，那些需要一个运行在 +非安全异常级的补救措施 *并且* 能被 Linux 触发的情况）。 + +对于尚在讨论中的可能对未受瑕疵影响的系统产生干扰的软件补救措施，有一个 +相应的内核配置（Kconfig）选项被加在 “内核特性（Kernel Features）”-> +“基于可选方法框架的 ARM 瑕疵补救措施（ARM errata workarounds via +the alternatives framework）"。这些选项被默认开启，若探测到受影响的CPU， +补丁将在运行时被使用。至于对系统运行影响较小的补救措施，内核配置选项 +并不存在，且代码以某种规避瑕疵的方式被构造（带注释为宜）。 + +这种做法对于在任意内核源代码树中准确地判断出哪个瑕疵已被软件方法所补救 +稍微有点麻烦，所以在 Linux 内核中此文件作为软件补救措施的注册表， +并将在新的软件补救措施被提交和向后移植（backported）到稳定内核时被更新。 + +| 实现者 | 受影响的组件 | 勘误编号 | 内核配置 | ++----------------+-----------------+-----------------+-------------------------+ +| ARM | Cortex-A53 | #826319 | ARM64_ERRATUM_826319 | +| ARM | Cortex-A53 | #827319 | ARM64_ERRATUM_827319 | +| ARM | Cortex-A53 | #824069 | ARM64_ERRATUM_824069 | +| ARM | Cortex-A53 | #819472 | ARM64_ERRATUM_819472 | +| ARM | Cortex-A53 | #845719 | ARM64_ERRATUM_845719 | +| ARM | Cortex-A53 | #843419 | ARM64_ERRATUM_843419 | +| ARM | Cortex-A57 | #832075 | ARM64_ERRATUM_832075 | +| ARM | Cortex-A57 | #852523 | N/A | +| ARM | Cortex-A57 | #834220 | ARM64_ERRATUM_834220 | +| | | | | +| Cavium | ThunderX ITS | #22375, #24313 | CAVIUM_ERRATUM_22375 | +| Cavium | ThunderX GICv3 | #23154 | CAVIUM_ERRATUM_23154 | diff --git a/Documentation/translations/zh_CN/arm64/tagged-pointers.txt b/Documentation/translations/zh_CN/arm64/tagged-pointers.txt new file mode 100644 index 000000000..2664d1bd5 --- /dev/null +++ b/Documentation/translations/zh_CN/arm64/tagged-pointers.txt @@ -0,0 +1,52 @@ +Chinese translated version of Documentation/arm64/tagged-pointers.txt + +If you have any comment or update to the content, please contact the +original document maintainer directly. However, if you have a problem +communicating in English you can also ask the Chinese maintainer for +help. Contact the Chinese maintainer if this translation is outdated +or if there is a problem with the translation. + +Maintainer: Will Deacon <will.deacon@arm.com> +Chinese maintainer: Fu Wei <wefu@redhat.com> +--------------------------------------------------------------------- +Documentation/arm64/tagged-pointers.txt 的中文翻译 + +如果想评论或更新本文的内容，请直接联系原文档的维护者。如果你使用英文 +交流有困难的话，也可以向中文版维护者求助。如果本翻译更新不及时或者翻 +译存在问题，请联系中文版维护者。 + +英文版维护者： Will Deacon <will.deacon@arm.com> +中文版维护者： 傅炜 Fu Wei <wefu@redhat.com> +中文版翻译者： 傅炜 Fu Wei <wefu@redhat.com> +中文版校译者： 傅炜 Fu Wei <wefu@redhat.com> + +以下为正文 +--------------------------------------------------------------------- + Linux 在 AArch64 中带标记的虚拟地址 + ================================= + +作者: Will Deacon <will.deacon@arm.com> +日期: 2013 年 06 月 12 日 + +本文档简述了在 AArch64 地址转换系统中提供的带标记的虚拟地址及其在 +AArch64 Linux 中的潜在用途。 + +内核提供的地址转换表配置使通过 TTBR0 完成的虚拟地址转换（即用户空间 +映射），其虚拟地址的最高 8 位（63:56）会被转换硬件所忽略。这种机制 +让这些位可供应用程序自由使用，其注意事项如下： + + (1) 内核要求所有传递到 EL1 的用户空间地址带有 0x00 标记。 + 这意味着任何携带用户空间虚拟地址的系统调用（syscall） + 参数 *必须* 在陷入内核前使它们的最高字节被清零。 + + (2) 非零标记在传递信号时不被保存。这意味着在应用程序中利用了 + 标记的信号处理函数无法依赖 siginfo_t 的用户空间虚拟 + 地址所携带的包含其内部域信息的标记。此规则的一个例外是 + 当信号是在调试观察点的异常处理程序中产生的，此时标记的 + 信息将被保存。 + + (3) 当使用带标记的指针时需特别留心，因为仅对两个虚拟地址 + 的高字节，C 编译器很可能无法判断它们是不同的。 + +此构架会阻止对带标记的 PC 指针的利用，因此在异常返回时，其高字节 +将被设置成一个为 “55” 的扩展符。 diff --git a/Documentation/translations/zh_CN/basic_profiling.txt b/Documentation/translations/zh_CN/basic_profiling.txt new file mode 100644 index 000000000..1e6bf0bdf --- /dev/null +++ b/Documentation/translations/zh_CN/basic_profiling.txt @@ -0,0 +1,71 @@ +Chinese translated version of Documentation/basic_profiling + +If you have any comment or update to the content, please post to LKML directly. +However, if you have problem communicating in English you can also ask the +Chinese maintainer for help. Contact the Chinese maintainer, if this +translation is outdated or there is problem with translation. + +Chinese maintainer: Liang Xie <xieliang@xiaomi.com> +--------------------------------------------------------------------- +Documentation/basic_profiling的中文翻译 + +如果想评论或更新本文的内容，请直接发信到LKML。如果你使用英文交流有困难的话，也可 +以向中文版维护者求助。如果本翻译更新不及时或者翻译存在问题，请联系中文版维护者。 + +中文版维护者： 谢良 Liang Xie <xieliang007@gmail.com> +中文版翻译者： 谢良 Liang Xie <xieliang007@gmail.com> +中文版校译者： +以下为正文 +--------------------------------------------------------------------- + +下面这些说明指令都是非常基础的，如果你想进一步了解请阅读相关专业文档：） +请不要再在本文档增加新的内容，但可以修复文档中的错误：）(mbligh@aracnet.com) +感谢John Levon，Dave Hansen等在撰写时的帮助 + +<test> 用于表示要测量的目标 +请先确保您已经有正确的System.map / vmlinux配置！ + +对于linux系统来说，配置vmlinuz最容易的方法可能就是使用“make install”，然后修改 +/sbin/installkernel将vmlinux拷贝到/boot目录，而System.map通常是默认安装好的 + +Readprofile +----------- +2.6系列内核需要版本相对较新的readprofile，比如util-linux 2.12a中包含的，可以从: + +http://www.kernel.org/pub/linux/utils/util-linux/ 下载 + +大部分linux发行版已经包含了. + +启用readprofile需要在kernel启动命令行增加”profile=2“ + +clear readprofile -r + <test> +dump output readprofile -m /boot/System.map > captured_profile + +Oprofile +-------- + +从http://oprofile.sourceforge.net/获取源代码（请参考Changes以获取匹配的版本） +在kernel启动命令行增加“idle=poll” + +配置CONFIG_PROFILING=y和CONFIG_OPROFILE=y然后重启进入新kernel + +./configure --with-kernel-support +make install + +想得到好的测量结果，请确保启用了本地APIC特性。如果opreport显示有0Hz CPU， +说明APIC特性没有开启。另外注意idle=poll选项可能有损性能。 + +One time setup: + opcontrol --setup --vmlinux=/boot/vmlinux + +clear opcontrol --reset +start opcontrol --start + <test> +stop opcontrol --stop +dump output opreport > output_file + +如果只看kernel相关的报告结果，请运行命令 opreport -l /boot/vmlinux > output_file + +通过reset选项可以清理过期统计数据，相当于重启的效果。 + diff --git a/Documentation/translations/zh_CN/coding-style.rst b/Documentation/translations/zh_CN/coding-style.rst new file mode 100644 index 000000000..1466aa64b --- /dev/null +++ b/Documentation/translations/zh_CN/coding-style.rst @@ -0,0 +1,950 @@ +Chinese translated version of Documentation/process/coding-style.rst + +If you have any comment or update to the content, please post to LKML directly. +However, if you have problem communicating in English you can also ask the +Chinese maintainer for help. Contact the Chinese maintainer, if this +translation is outdated or there is problem with translation. + +Chinese maintainer: Zhang Le <r0bertz@gentoo.org> + +--------------------------------------------------------------------- + +Documentation/process/coding-style.rst 的中文翻译 + +如果想评论或更新本文的内容，请直接发信到LKML。如果你使用英文交流有困难的话， +也可以向中文版维护者求助。如果本翻译更新不及时或者翻译存在问题，请联系中文版 +维护者:: + + 中文版维护者： 张乐 Zhang Le <r0bertz@gentoo.org> + 中文版翻译者： 张乐 Zhang Le <r0bertz@gentoo.org> + 中文版校译者： 王聪 Wang Cong <xiyou.wangcong@gmail.com> + wheelz <kernel.zeng@gmail.com> + 管旭东 Xudong Guan <xudong.guan@gmail.com> + Li Zefan <lizf@cn.fujitsu.com> + Wang Chen <wangchen@cn.fujitsu.com> + +以下为正文 + +--------------------------------------------------------------------- + +Linux 内核代码风格 +========================= + +这是一个简短的文档，描述了 linux 内核的首选代码风格。代码风格是因人而异的， +而且我不愿意把自己的观点强加给任何人，但这就像我去做任何事情都必须遵循的原则 +那样，我也希望在绝大多数事上保持这种的态度。请 (在写代码时) 至少考虑一下这里 +的代码风格。 + +首先，我建议你打印一份 GNU 代码规范，然后不要读。烧了它，这是一个具有重大象征 +性意义的动作。 + +不管怎样，现在我们开始： + + +1) 缩进 +-------------- + +制表符是 8 个字符，所以缩进也是 8 个字符。有些异端运动试图将缩进变为 4 (甚至 +2！) 字符深，这几乎相当于尝试将圆周率的值定义为 3。 + +理由：缩进的全部意义就在于清楚的定义一个控制块起止于何处。尤其是当你盯着你的 +屏幕连续看了 20 小时之后，你将会发现大一点的缩进会使你更容易分辨缩进。 + +现在，有些人会抱怨 8 个字符的缩进会使代码向右边移动的太远，在 80 个字符的终端 +屏幕上就很难读这样的代码。这个问题的答案是，如果你需要 3 级以上的缩进，不管用 +何种方式你的代码已经有问题了，应该修正你的程序。 + +简而言之，8 个字符的缩进可以让代码更容易阅读，还有一个好处是当你的函数嵌套太 +深的时候可以给你警告。留心这个警告。 + +在 switch 语句中消除多级缩进的首选的方式是让 ``switch`` 和从属于它的 ``case`` +标签对齐于同一列，而不要 ``两次缩进`` ``case`` 标签。比如： + +.. code-block:: c + + switch (suffix) { + case 'G': + case 'g': + mem <<= 30; + break; + case 'M': + case 'm': + mem <<= 20; + break; + case 'K': + case 'k': + mem <<= 10; + /* fall through */ + default: + break; + } + +不要把多个语句放在一行里，除非你有什么东西要隐藏： + +.. code-block:: c + + if (condition) do_this; + do_something_everytime; + +也不要在一行里放多个赋值语句。内核代码风格超级简单。就是避免可能导致别人误读 +的表达式。 + +除了注释、文档和 Kconfig 之外，不要使用空格来缩进，前面的例子是例外，是有意为 +之。 + +选用一个好的编辑器，不要在行尾留空格。 + + +2) 把长的行和字符串打散 +------------------------------ + +代码风格的意义就在于使用平常使用的工具来维持代码的可读性和可维护性。 + +每一行的长度的限制是 80 列，我们强烈建议您遵守这个惯例。 + +长于 80 列的语句要打散成有意义的片段。除非超过 80 列能显著增加可读性，并且不 +会隐藏信息。子片段要明显短于母片段，并明显靠右。这同样适用于有着很长参数列表 +的函数头。然而，绝对不要打散对用户可见的字符串，例如 printk 信息，因为这样就 +很难对它们 grep。 + + +3) 大括号和空格的放置 +------------------------------ + +C 语言风格中另外一个常见问题是大括号的放置。和缩进大小不同，选择或弃用某种放 +置策略并没有多少技术上的原因，不过首选的方式，就像 Kernighan 和 Ritchie 展示 +给我们的，是把起始大括号放在行尾，而把结束大括号放在行首，所以： + +.. code-block:: c + + if (x is true) { + we do y + } + +这适用于所有的非函数语句块 (if, switch, for, while, do)。比如： + +.. code-block:: c + + switch (action) { + case KOBJ_ADD: + return "add"; + case KOBJ_REMOVE: + return "remove"; + case KOBJ_CHANGE: + return "change"; + default: + return NULL; + } + +不过，有一个例外，那就是函数：函数的起始大括号放置于下一行的开头，所以： + +.. code-block:: c + + int function(int x) + { + body of function + } + +全世界的异端可能会抱怨这个不一致性是... 呃... 不一致的，不过所有思维健全的人 +都知道 (a) K&R 是 **正确的** 并且 (b) K&R 是正确的。此外，不管怎样函数都是特 +殊的 (C 函数是不能嵌套的)。 + +注意结束大括号独自占据一行，除非它后面跟着同一个语句的剩余部分，也就是 do 语 +句中的 "while" 或者 if 语句中的 "else"，像这样： + +.. code-block:: c + + do { + body of do-loop + } while (condition); + +和 + +.. code-block:: c + + if (x == y) { + .. + } else if (x > y) { + ... + } else { + .... + } + +理由：K&R。 + +也请注意这种大括号的放置方式也能使空 (或者差不多空的) 行的数量最小化，同时不 +失可读性。因此，由于你的屏幕上的新行是不可再生资源 (想想 25 行的终端屏幕)，你 +将会有更多的空行来放置注释。 + +当只有一个单独的语句的时候，不用加不必要的大括号。 + +.. code-block:: c + + if (condition) + action(); + +和 + +.. code-block:: c + + if (condition) + do_this(); + else + do_that(); + +这并不适用于只有一个条件分支是单语句的情况；这时所有分支都要使用大括号： + +.. code-block:: c + + if (condition) { + do_this(); + do_that(); + } else { + otherwise(); + } + +3.1) 空格 +******************** + +Linux 内核的空格使用方式 (主要) 取决于它是用于函数还是关键字。(大多数) 关键字 +后要加一个空格。值得注意的例外是 sizeof, typeof, alignof 和 __attribute__，这 +些关键字某些程度上看起来更像函数 (它们在 Linux 里也常常伴随小括号而使用，尽管 +在 C 里这样的小括号不是必需的，就像 ``struct fileinfo info;`` 声明过后的 +``sizeof info``)。 + +所以在这些关键字之后放一个空格:: + + if, switch, case, for, do, while + +但是不要在 sizeof, typeof, alignof 或者 __attribute__ 这些关键字之后放空格。 +例如， + +.. code-block:: c + + s = sizeof(struct file); + +不要在小括号里的表达式两侧加空格。这是一个 **反例** ： + +.. code-block:: c + + s = sizeof( struct file ); + +当声明指针类型或者返回指针类型的函数时， ``*`` 的首选使用方式是使之靠近变量名 +或者函数名，而不是靠近类型名。例子： + +.. code-block:: c + + char *linux_banner; + unsigned long long memparse(char *ptr, char **retptr); + char *match_strdup(substring_t *s); + +在大多数二元和三元操作符两侧使用一个空格，例如下面所有这些操作符:: + + = + - < > * / % | & ^ <= >= == != ? : + +但是一元操作符后不要加空格:: + + & * + - ~ ! sizeof typeof alignof __attribute__ defined + +后缀自加和自减一元操作符前不加空格:: + + ++ -- + +前缀自加和自减一元操作符后不加空格:: + + ++ -- + +``.`` 和 ``->`` 结构体成员操作符前后不加空格。 + +不要在行尾留空白。有些可以自动缩进的编辑器会在新行的行首加入适量的空白，然后 +你就可以直接在那一行输入代码。不过假如你最后没有在那一行输入代码，有些编辑器 +就不会移除已经加入的空白，就像你故意留下一个只有空白的行。包含行尾空白的行就 +这样产生了。 + +当 git 发现补丁包含了行尾空白的时候会警告你，并且可以应你的要求去掉行尾空白； +不过如果你是正在打一系列补丁，这样做会导致后面的补丁失败，因为你改变了补丁的 +上下文。 + + +4) 命名 +------------------------------ + +C 是一个简朴的语言，你的命名也应该这样。和 Modula-2 和 Pascal 程序员不同， +C 程序员不使用类似 ThisVariableIsATemporaryCounter 这样华丽的名字。C 程序员会 +称那个变量为 ``tmp`` ，这样写起来会更容易，而且至少不会令其难于理解。 + +不过，虽然混用大小写的名字是不提倡使用的，但是全局变量还是需要一个具描述性的 +名字。称一个全局函数为 ``foo`` 是一个难以饶恕的错误。 + +全局变量 (只有当你 **真正** 需要它们的时候再用它) 需要有一个具描述性的名字，就 +像全局函数。如果你有一个可以计算活动用户数量的函数，你应该叫它 +``count_active_users()`` 或者类似的名字，你不应该叫它 ``cntuser()`` 。 + +在函数名中包含函数类型 (所谓的匈牙利命名法) 是脑子出了问题——编译器知道那些类 +型而且能够检查那些类型，这样做只能把程序员弄糊涂了。难怪微软总是制造出有问题 +的程序。 + +本地变量名应该简短，而且能够表达相关的含义。如果你有一些随机的整数型的循环计 +数器，它应该被称为 ``i`` 。叫它 ``loop_counter`` 并无益处，如果它没有被误解的 +可能的话。类似的， ``tmp`` 可以用来称呼任意类型的临时变量。 + +如果你怕混淆了你的本地变量名，你就遇到另一个问题了，叫做函数增长荷尔蒙失衡综 +合症。请看第六章 (函数)。 + + +5) Typedef +----------- + +不要使用类似 ``vps_t`` 之类的东西。 + +对结构体和指针使用 typedef 是一个 **错误** 。当你在代码里看到： + +.. code-block:: c + + vps_t a; + +这代表什么意思呢？ + +相反，如果是这样 + +.. code-block:: c + + struct virtual_container *a; + +你就知道 ``a`` 是什么了。 + +很多人认为 typedef ``能提高可读性`` 。实际不是这样的。它们只在下列情况下有用： + + (a) 完全不透明的对象 (这种情况下要主动使用 typedef 来 **隐藏** 这个对象实际上 + 是什么)。 + + 例如： ``pte_t`` 等不透明对象，你只能用合适的访问函数来访问它们。 + + .. note:: + + 不透明性和 "访问函数" 本身是不好的。我们使用 pte_t 等类型的原因在于真 + 的是完全没有任何共用的可访问信息。 + + (b) 清楚的整数类型，如此，这层抽象就可以 **帮助** 消除到底是 ``int`` 还是 + ``long`` 的混淆。 + + u8/u16/u32 是完全没有问题的 typedef，不过它们更符合类别 (d) 而不是这里。 + + .. note:: + + 要这样做，必须事出有因。如果某个变量是 ``unsigned long`` ，那么没有必要 + + typedef unsigned long myflags_t; + + 不过如果有一个明确的原因，比如它在某种情况下可能会是一个 ``unsigned int`` + 而在其他情况下可能为 ``unsigned long`` ，那么就不要犹豫，请务必使用 + typedef。 + + (c) 当你使用 sparse 按字面的创建一个 **新** 类型来做类型检查的时候。 + + (d) 和标准 C99 类型相同的类型，在某些例外的情况下。 + + 虽然让眼睛和脑筋来适应新的标准类型比如 ``uint32_t`` 不需要花很多时间，可 + 是有些人仍然拒绝使用它们。 + + 因此，Linux 特有的等同于标准类型的 ``u8/u16/u32/u64`` 类型和它们的有符号 + 类型是被允许的——尽管在你自己的新代码中，它们不是强制要求要使用的。 + + 当编辑已经使用了某个类型集的已有代码时，你应该遵循那些代码中已经做出的选 + 择。 + + (e) 可以在用户空间安全使用的类型。 + + 在某些用户空间可见的结构体里，我们不能要求 C99 类型而且不能用上面提到的 + ``u32`` 类型。因此，我们在与用户空间共享的所有结构体中使用 __u32 和类似 + 的类型。 + +可能还有其他的情况，不过基本的规则是 **永远不要** 使用 typedef，除非你可以明 +确的应用上述某个规则中的一个。 + +总的来说，如果一个指针或者一个结构体里的元素可以合理的被直接访问到，那么它们 +就不应该是一个 typedef。 + + +6) 函数 +------------------------------ + +函数应该简短而漂亮，并且只完成一件事情。函数应该可以一屏或者两屏显示完 (我们 +都知道 ISO/ANSI 屏幕大小是 80x24)，只做一件事情，而且把它做好。 + +一个函数的最大长度是和该函数的复杂度和缩进级数成反比的。所以，如果你有一个理 +论上很简单的只有一个很长 (但是简单) 的 case 语句的函数，而且你需要在每个 case +里做很多很小的事情，这样的函数尽管很长，但也是可以的。 + +不过，如果你有一个复杂的函数，而且你怀疑一个天分不是很高的高中一年级学生可能 +甚至搞不清楚这个函数的目的，你应该严格遵守前面提到的长度限制。使用辅助函数， +并为之取个具描述性的名字 (如果你觉得它们的性能很重要的话，可以让编译器内联它 +们，这样的效果往往会比你写一个复杂函数的效果要好。) + +函数的另外一个衡量标准是本地变量的数量。此数量不应超过 5－10 个，否则你的函数 +就有问题了。重新考虑一下你的函数，把它分拆成更小的函数。人的大脑一般可以轻松 +的同时跟踪 7 个不同的事物，如果再增多的话，就会糊涂了。即便你聪颖过人，你也可 +能会记不清你 2 个星期前做过的事情。 + +在源文件里，使用空行隔开不同的函数。如果该函数需要被导出，它的 **EXPORT** 宏 +应该紧贴在它的结束大括号之下。比如： + +.. code-block:: c + + int system_is_up(void) + { + return system_state == SYSTEM_RUNNING; + } + EXPORT_SYMBOL(system_is_up); + +在函数原型中，包含函数名和它们的数据类型。虽然 C 语言里没有这样的要求，在 +Linux 里这是提倡的做法，因为这样可以很简单的给读者提供更多的有价值的信息。 + + +7) 集中的函数退出途径 +------------------------------ + +虽然被某些人声称已经过时，但是 goto 语句的等价物还是经常被编译器所使用，具体 +形式是无条件跳转指令。 + +当一个函数从多个位置退出，并且需要做一些类似清理的常见操作时，goto 语句就很方 +便了。如果并不需要清理操作，那么直接 return 即可。 + +选择一个能够说明 goto 行为或它为何存在的标签名。如果 goto 要释放 ``buffer``, +一个不错的名字可以是 ``out_free_buffer:`` 。别去使用像 ``err1:`` 和 ``err2:`` +这样的GW_BASIC 名称，因为一旦你添加或删除了 (函数的) 退出路径，你就必须对它们 +重新编号，这样会难以去检验正确性。 + +使用 goto 的理由是： + +- 无条件语句容易理解和跟踪 +- 嵌套程度减小 +- 可以避免由于修改时忘记更新个别的退出点而导致错误 +- 让编译器省去删除冗余代码的工作 ;) + +.. code-block:: c + + int fun(int a) + { + int result = 0; + char *buffer; + + buffer = kmalloc(SIZE, GFP_KERNEL); + if (!buffer) + return -ENOMEM; + + if (condition1) { + while (loop1) { + ... + } + result = 1; + goto out_free_buffer; + } + ... + out_free_buffer: + kfree(buffer); + return result; + } + +一个需要注意的常见错误是 ``一个 err 错误`` ，就像这样： + +.. code-block:: c + + err: + kfree(foo->bar); + kfree(foo); + return ret; + +这段代码的错误是，在某些退出路径上 ``foo`` 是 NULL。通常情况下，通过把它分离 +成两个错误标签 ``err_free_bar:`` 和 ``err_free_foo:`` 来修复这个错误： + +.. code-block:: c + + err_free_bar: + kfree(foo->bar); + err_free_foo: + kfree(foo); + return ret; + +理想情况下，你应该模拟错误来测试所有退出路径。 + + +8) 注释 +------------------------------ + +注释是好的，不过有过度注释的危险。永远不要在注释里解释你的代码是如何运作的： +更好的做法是让别人一看你的代码就可以明白，解释写的很差的代码是浪费时间。 + +一般的，你想要你的注释告诉别人你的代码做了什么，而不是怎么做的。也请你不要把 +注释放在一个函数体内部：如果函数复杂到你需要独立的注释其中的一部分，你很可能 +需要回到第六章看一看。你可以做一些小注释来注明或警告某些很聪明 (或者槽糕) 的 +做法，但不要加太多。你应该做的，是把注释放在函数的头部，告诉人们它做了什么， +也可以加上它做这些事情的原因。 + +当注释内核 API 函数时，请使用 kernel-doc 格式。请看 +Documentation/doc-guide/ 和 scripts/kernel-doc 以获得详细信息。 + +长 (多行) 注释的首选风格是： + +.. code-block:: c + + /* + * This is the preferred style for multi-line + * comments in the Linux kernel source code. + * Please use it consistently. + * + * Description: A column of asterisks on the left side, + * with beginning and ending almost-blank lines. + */ + +对于在 net/ 和 drivers/net/ 的文件，首选的长 (多行) 注释风格有些不同。 + +.. code-block:: c + + /* The preferred comment style for files in net/ and drivers/net + * looks like this. + * + * It is nearly the same as the generally preferred comment style, + * but there is no initial almost-blank line. + */ + +注释数据也是很重要的，不管是基本类型还是衍生类型。为了方便实现这一点，每一行 +应只声明一个数据 (不要使用逗号来一次声明多个数据)。这样你就有空间来为每个数据 +写一段小注释来解释它们的用途了。 + + +9) 你已经把事情弄糟了 +------------------------------ + +这没什么，我们都是这样。可能你的使用了很长时间 Unix 的朋友已经告诉你 +``GNU emacs`` 能自动帮你格式化 C 源代码，而且你也注意到了，确实是这样，不过它 +所使用的默认值和我们想要的相去甚远 (实际上，甚至比随机打的还要差——无数个猴子 +在 GNU emacs 里打字永远不会创造出一个好程序) (译注：Infinite Monkey Theorem) + +所以你要么放弃 GNU emacs，要么改变它让它使用更合理的设定。要采用后一个方案， +你可以把下面这段粘贴到你的 .emacs 文件里。 + +.. code-block:: none + + (defun c-lineup-arglist-tabs-only (ignored) + "Line up argument lists by tabs, not spaces" + (let* ((anchor (c-langelem-pos c-syntactic-element)) + (column (c-langelem-2nd-pos c-syntactic-element)) + (offset (- (1+ column) anchor)) + (steps (floor offset c-basic-offset))) + (* (max steps 1) + c-basic-offset))) + + (add-hook 'c-mode-common-hook + (lambda () + ;; Add kernel style + (c-add-style + "linux-tabs-only" + '("linux" (c-offsets-alist + (arglist-cont-nonempty + c-lineup-gcc-asm-reg + c-lineup-arglist-tabs-only)))))) + + (add-hook 'c-mode-hook + (lambda () + (let ((filename (buffer-file-name))) + ;; Enable kernel mode for the appropriate files + (when (and filename + (string-match (expand-file-name "~/src/linux-trees") + filename)) + (setq indent-tabs-mode t) + (setq show-trailing-whitespace t) + (c-set-style "linux-tabs-only"))))) + +这会让 emacs 在 ``~/src/linux-trees`` 下的 C 源文件获得更好的内核代码风格。 + +不过就算你尝试让 emacs 正确的格式化代码失败了，也并不意味着你失去了一切：还可 +以用 ``indent`` 。 + +不过，GNU indent 也有和 GNU emacs 一样有问题的设定，所以你需要给它一些命令选 +项。不过，这还不算太糟糕，因为就算是 GNU indent 的作者也认同 K&R 的权威性 +(GNU 的人并不是坏人，他们只是在这个问题上被严重的误导了)，所以你只要给 indent +指定选项 ``-kr -i8`` (代表 ``K&R，8 字符缩进``)，或使用 ``scripts/Lindent`` +这样就可以以最时髦的方式缩进源代码。 + +``indent`` 有很多选项，特别是重新格式化注释的时候，你可能需要看一下它的手册。 +不过记住： ``indent`` 不能修正坏的编程习惯。 + + +10) Kconfig 配置文件 +------------------------------ + +对于遍布源码树的所有 Kconfig* 配置文件来说，它们缩进方式有所不同。紧挨着 +``config`` 定义的行，用一个制表符缩进，然而 help 信息的缩进则额外增加 2 个空 +格。举个例子:: + + config AUDIT + bool "Auditing support" + depends on NET + help + Enable auditing infrastructure that can be used with another + kernel subsystem, such as SELinux (which requires this for + logging of avc messages output). Does not do system-call + auditing without CONFIG_AUDITSYSCALL. + +而那些危险的功能 (比如某些文件系统的写支持) 应该在它们的提示字符串里显著的声 +明这一点:: + + config ADFS_FS_RW + bool "ADFS write support (DANGEROUS)" + depends on ADFS_FS + ... + +要查看配置文件的完整文档，请看 Documentation/kbuild/kconfig-language.txt。 + + +11) 数据结构 +------------------------------ + +如果一个数据结构，在创建和销毁它的单线执行环境之外可见，那么它必须要有一个引 +用计数器。内核里没有垃圾收集 (并且内核之外的垃圾收集慢且效率低下)，这意味着你 +绝对需要记录你对这种数据结构的使用情况。 + +引用计数意味着你能够避免上锁，并且允许多个用户并行访问这个数据结构——而不需要 +担心这个数据结构仅仅因为暂时不被使用就消失了，那些用户可能不过是沉睡了一阵或 +者做了一些其他事情而已。 + +注意上锁 **不能** 取代引用计数。上锁是为了保持数据结构的一致性，而引用计数是一 +个内存管理技巧。通常二者都需要，不要把两个搞混了。 + +很多数据结构实际上有 2 级引用计数，它们通常有不同 ``类`` 的用户。子类计数器统 +计子类用户的数量，每当子类计数器减至零时，全局计数器减一。 + +这种 ``多级引用计数`` 的例子可以在内存管理 (``struct mm_struct``: mm_users 和 +mm_count)，和文件系统 (``struct super_block``: s_count 和 s_active) 中找到。 + +记住：如果另一个执行线索可以找到你的数据结构，但这个数据结构没有引用计数器， +这里几乎肯定是一个 bug。 + + +12) 宏，枚举和RTL +------------------------------ + +用于定义常量的宏的名字及枚举里的标签需要大写。 + +.. code-block:: c + + #define CONSTANT 0x12345 + +在定义几个相关的常量时，最好用枚举。 + +宏的名字请用大写字母，不过形如函数的宏的名字可以用小写字母。 + +一般的，如果能写成内联函数就不要写成像函数的宏。 + +含有多个语句的宏应该被包含在一个 do-while 代码块里： + +.. code-block:: c + + #define macrofun(a, b, c) \ + do { \ + if (a == 5) \ + do_this(b, c); \ + } while (0) + +使用宏的时候应避免的事情： + +1) 影响控制流程的宏： + +.. code-block:: c + + #define FOO(x) \ + do { \ + if (blah(x) < 0) \ + return -EBUGGERED; \ + } while (0) + +**非常** 不好。它看起来像一个函数，不过却能导致 ``调用`` 它的函数退出；不要打 +乱读者大脑里的语法分析器。 + +2) 依赖于一个固定名字的本地变量的宏： + +.. code-block:: c + + #define FOO(val) bar(index, val) + +可能看起来像是个不错的东西，不过它非常容易把读代码的人搞糊涂，而且容易导致看起 +来不相关的改动带来错误。 + +3) 作为左值的带参数的宏： FOO(x) = y；如果有人把 FOO 变成一个内联函数的话，这 + 种用法就会出错了。 + +4) 忘记了优先级：使用表达式定义常量的宏必须将表达式置于一对小括号之内。带参数 + 的宏也要注意此类问题。 + +.. code-block:: c + + #define CONSTANT 0x4000 + #define CONSTEXP (CONSTANT | 3) + +5) 在宏里定义类似函数的本地变量时命名冲突： + +.. code-block:: c + + #define FOO(x) \ + ({ \ + typeof(x) ret; \ + ret = calc_ret(x); \ + (ret); \ + }) + +ret 是本地变量的通用名字 - __foo_ret 更不容易与一个已存在的变量冲突。 + +cpp 手册对宏的讲解很详细。gcc internals 手册也详细讲解了 RTL，内核里的汇编语 +言经常用到它。 + + +13) 打印内核消息 +------------------------------ + +内核开发者应该是受过良好教育的。请一定注意内核信息的拼写，以给人以好的印象。 +不要用不规范的单词比如 ``dont``，而要用 ``do not`` 或者 ``don't`` 。保证这些信 +息简单明了,无歧义。 + +内核信息不必以英文句号结束。 + +在小括号里打印数字 (%d) 没有任何价值，应该避免这样做。 + +<linux/device.h> 里有一些驱动模型诊断宏，你应该使用它们，以确保信息对应于正确 +的设备和驱动，并且被标记了正确的消息级别。这些宏有：dev_err(), dev_warn(), +dev_info() 等等。对于那些不和某个特定设备相关连的信息，<linux/printk.h> 定义 +了 pr_notice(), pr_info(), pr_warn(), pr_err() 和其他。 + +写出好的调试信息可以是一个很大的挑战；一旦你写出后，这些信息在远程除错时能提 +供极大的帮助。然而打印调试信息的处理方式同打印非调试信息不同。其他 pr_XXX() +函数能无条件地打印，pr_debug() 却不；默认情况下它不会被编译，除非定义了 DEBUG +或设定了 CONFIG_DYNAMIC_DEBUG。实际这同样是为了 dev_dbg()，一个相关约定是在一 +个已经开启了 DEBUG 时，使用 VERBOSE_DEBUG 来添加 dev_vdbg()。 + +许多子系统拥有 Kconfig 调试选项来开启 -DDEBUG 在对应的 Makefile 里面；在其他 +情况下，特殊文件使用 #define DEBUG。当一条调试信息需要被无条件打印时，例如， +如果已经包含一个调试相关的 #ifdef 条件，printk(KERN_DEBUG ...) 就可被使用。 + + +14) 分配内存 +------------------------------ + +内核提供了下面的一般用途的内存分配函数： +kmalloc(), kzalloc(), kmalloc_array(), kcalloc(), vmalloc() 和 vzalloc()。 +请参考 API 文档以获取有关它们的详细信息。 + +传递结构体大小的首选形式是这样的： + +.. code-block:: c + + p = kmalloc(sizeof(*p), ...); + +另外一种传递方式中，sizeof 的操作数是结构体的名字，这样会降低可读性，并且可能 +会引入 bug。有可能指针变量类型被改变时，而对应的传递给内存分配函数的 sizeof +的结果不变。 + +强制转换一个 void 指针返回值是多余的。C 语言本身保证了从 void 指针到其他任何 +指针类型的转换是没有问题的。 + +分配一个数组的首选形式是这样的： + +.. code-block:: c + + p = kmalloc_array(n, sizeof(...), ...); + +分配一个零长数组的首选形式是这样的： + +.. code-block:: c + + p = kcalloc(n, sizeof(...), ...); + +两种形式检查分配大小 n * sizeof(...) 的溢出，如果溢出返回 NULL。 + + +15) 内联弊病 +------------------------------ + +有一个常见的误解是 ``内联`` 是 gcc 提供的可以让代码运行更快的一个选项。虽然使 +用内联函数有时候是恰当的 (比如作为一种替代宏的方式，请看第十二章)，不过很多情 +况下不是这样。inline 的过度使用会使内核变大，从而使整个系统运行速度变慢。 +因为体积大内核会占用更多的指令高速缓存，而且会导致 pagecache 的可用内存减少。 +想象一下，一次 pagecache 未命中就会导致一次磁盘寻址，将耗时 5 毫秒。5 毫秒的 +时间内 CPU 能执行很多很多指令。 + +一个基本的原则是如果一个函数有 3 行以上，就不要把它变成内联函数。这个原则的一 +个例外是，如果你知道某个参数是一个编译时常量，而且因为这个常量你确定编译器在 +编译时能优化掉你的函数的大部分代码，那仍然可以给它加上 inline 关键字。 +kmalloc() 内联函数就是一个很好的例子。 + +人们经常主张给 static 的而且只用了一次的函数加上 inline，如此不会有任何损失， +因为没有什么好权衡的。虽然从技术上说这是正确的，但是实际上这种情况下即使不加 +inline gcc 也可以自动使其内联。而且其他用户可能会要求移除 inline，由此而来的 +争论会抵消 inline 自身的潜在价值，得不偿失。 + + +16) 函数返回值及命名 +------------------------------ + +函数可以返回多种不同类型的值，最常见的一种是表明函数执行成功或者失败的值。这样 +的一个值可以表示为一个错误代码整数 (-Exxx＝失败，0＝成功) 或者一个 ``成功`` +布尔值 (0＝失败，非0＝成功)。 + +混合使用这两种表达方式是难于发现的 bug 的来源。如果 C 语言本身严格区分整形和 +布尔型变量，那么编译器就能够帮我们发现这些错误... 不过 C 语言不区分。为了避免 +产生这种 bug，请遵循下面的惯例:: + + 如果函数的名字是一个动作或者强制性的命令，那么这个函数应该返回错误代 + 码整数。如果是一个判断，那么函数应该返回一个 "成功" 布尔值。 + +比如， ``add work`` 是一个命令，所以 add_work() 在成功时返回 0，在失败时返回 +-EBUSY。类似的，因为 ``PCI device present`` 是一个判断，所以 pci_dev_present() +在成功找到一个匹配的设备时应该返回 1，如果找不到时应该返回 0。 + +所有 EXPORTed 函数都必须遵守这个惯例，所有的公共函数也都应该如此。私有 +(static) 函数不需要如此，但是我们也推荐这样做。 + +返回值是实际计算结果而不是计算是否成功的标志的函数不受此惯例的限制。一般的， +他们通过返回一些正常值范围之外的结果来表示出错。典型的例子是返回指针的函数， +他们使用 NULL 或者 ERR_PTR 机制来报告错误。 + + +17) 不要重新发明内核宏 +------------------------------ + +头文件 include/linux/kernel.h 包含了一些宏，你应该使用它们，而不要自己写一些 +它们的变种。比如，如果你需要计算一个数组的长度，使用这个宏 + +.. code-block:: c + + #define ARRAY_SIZE(x) (sizeof(x) / sizeof((x)[0])) + +类似的，如果你要计算某结构体成员的大小，使用 + +.. code-block:: c + + #define FIELD_SIZEOF(t, f) (sizeof(((t*)0)->f)) + +还有可以做严格的类型检查的 min() 和 max() 宏，如果你需要可以使用它们。你可以 +自己看看那个头文件里还定义了什么你可以拿来用的东西，如果有定义的话，你就不应 +在你的代码里自己重新定义。 + + +18) 编辑器模式行和其他需要罗嗦的事情 +-------------------------------------------------- + +有一些编辑器可以解释嵌入在源文件里的由一些特殊标记标明的配置信息。比如，emacs +能够解释被标记成这样的行： + +.. code-block:: c + + -*- mode: c -*- + +或者这样的： + +.. code-block:: c + + /* + Local Variables: + compile-command: "gcc -DMAGIC_DEBUG_FLAG foo.c" + End: + */ + +Vim 能够解释这样的标记： + +.. code-block:: c + + /* vim:set sw=8 noet */ + +不要在源代码中包含任何这样的内容。每个人都有他自己的编辑器配置，你的源文件不 +应该覆盖别人的配置。这包括有关缩进和模式配置的标记。人们可以使用他们自己定制 +的模式，或者使用其他可以产生正确的缩进的巧妙方法。 + + +19) 内联汇编 +------------------------------ + +在特定架构的代码中，你可能需要内联汇编与 CPU 和平台相关功能连接。需要这么做时 +就不要犹豫。然而，当 C 可以完成工作时，不要平白无故地使用内联汇编。在可能的情 +况下，你可以并且应该用 C 和硬件沟通。 + +请考虑去写捆绑通用位元 (wrap common bits) 的内联汇编的简单辅助函数，别去重复 +地写下只有细微差异内联汇编。记住内联汇编可以使用 C 参数。 + +大型，有一定复杂度的汇编函数应该放在 .S 文件内，用相应的 C 原型定义在 C 头文 +件中。汇编函数的 C 原型应该使用 ``asmlinkage`` 。 + +你可能需要把汇编语句标记为 volatile，用来阻止 GCC 在没发现任何副作用后就把它 +移除了。你不必总是这样做，尽管，这不必要的举动会限制优化。 + +在写一个包含多条指令的单个内联汇编语句时，把每条指令用引号分割而且各占一行， +除了最后一条指令外，在每个指令结尾加上 \n\t，让汇编输出时可以正确地缩进下一条 +指令： + +.. code-block:: c + + asm ("magic %reg1, #42\n\t" + "more_magic %reg2, %reg3" + : /* outputs */ : /* inputs */ : /* clobbers */); + + +20) 条件编译 +------------------------------ + +只要可能，就不要在 .c 文件里面使用预处理条件 (#if, #ifdef)；这样做让代码更难 +阅读并且更难去跟踪逻辑。替代方案是，在头文件中用预处理条件提供给那些 .c 文件 +使用，再给 #else 提供一个空桩 (no-op stub) 版本，然后在 .c 文件内无条件地调用 +那些 (定义在头文件内的) 函数。这样做，编译器会避免为桩函数 (stub) 的调用生成 +任何代码，产生的结果是相同的，但逻辑将更加清晰。 + +最好倾向于编译整个函数，而不是函数的一部分或表达式的一部分。与其放一个 ifdef +在表达式内，不如分解出部分或全部表达式，放进一个单独的辅助函数，并应用预处理 +条件到这个辅助函数内。 + +如果你有一个在特定配置中，可能变成未使用的函数或变量，编译器会警告它定义了但 +未使用，把它标记为 __maybe_unused 而不是将它包含在一个预处理条件中。(然而，如 +果一个函数或变量总是未使用，就直接删除它。) + +在代码中，尽可能地使用 IS_ENABLED 宏来转化某个 Kconfig 标记为 C 的布尔 +表达式，并在一般的 C 条件中使用它： + +.. code-block:: c + + if (IS_ENABLED(CONFIG_SOMETHING)) { + ... + } + +编译器会做常量折叠，然后就像使用 #ifdef 那样去包含或排除代码块，所以这不会带 +来任何运行时开销。然而，这种方法依旧允许 C 编译器查看块内的代码，并检查它的正 +确性 (语法，类型，符号引用，等等)。因此，如果条件不满足，代码块内的引用符号就 +不存在时，你还是必须去用 #ifdef。 + +在任何有意义的 #if 或 #ifdef 块的末尾 (超过几行的)，在 #endif 同一行的后面写下 +注解，注释这个条件表达式。例如： + +.. code-block:: c + + #ifdef CONFIG_SOMETHING + ... + #endif /* CONFIG_SOMETHING */ + + +附录 I) 参考 +------------------- + +The C Programming Language, 第二版 +作者：Brian W. Kernighan 和 Denni M. Ritchie. +Prentice Hall, Inc., 1988. +ISBN 0-13-110362-8 (软皮), 0-13-110370-9 (硬皮). + +The Practice of Programming +作者：Brian W. Kernighan 和 Rob Pike. +Addison-Wesley, Inc., 1999. +ISBN 0-201-61586-X. + +GNU 手册 - 遵循 K&R 标准和此文本 - cpp, gcc, gcc internals and indent, +都可以从 http://www.gnu.org/manual/ 找到 + +WG14 是 C 语言的国际标准化工作组，URL: http://www.open-std.org/JTC1/SC22/WG14/ + +Kernel process/coding-style.rst，作者 greg@kroah.com 发表于 OLS 2002： +http://www.kroah.com/linux/talks/ols_2002_kernel_codingstyle_talk/html/ diff --git a/Documentation/translations/zh_CN/email-clients.txt b/Documentation/translations/zh_CN/email-clients.txt new file mode 100644 index 000000000..ec31d97e8 --- /dev/null +++ b/Documentation/translations/zh_CN/email-clients.txt @@ -0,0 +1,210 @@ +Chinese translated version of Documentation/process/email-clients.rst + +If you have any comment or update to the content, please contact the +original document maintainer directly. However, if you have a problem +communicating in English you can also ask the Chinese maintainer for +help. Contact the Chinese maintainer if this translation is outdated +or if there is a problem with the translation. + +Chinese maintainer: Harry Wei <harryxiyou@gmail.com> +--------------------------------------------------------------------- +Documentation/process/email-clients.rst 的中文翻译 + +如果想评论或更新本文的内容，请直接联系原文档的维护者。如果你使用英文 +交流有困难的话，也可以向中文版维护者求助。如果本翻译更新不及时或者翻 +译存在问题，请联系中文版维护者。 + +中文版维护者： 贾威威 Harry Wei <harryxiyou@gmail.com> +中文版翻译者： 贾威威 Harry Wei <harryxiyou@gmail.com> +中文版校译者： Yinglin Luan <synmyth@gmail.com> + Xiaochen Wang <wangxiaochen0@gmail.com> + yaxinsn <yaxinsn@163.com> + +以下为正文 +--------------------------------------------------------------------- + +Linux邮件客户端配置信息 +====================================================================== + +普通配置 +---------------------------------------------------------------------- +Linux内核补丁是通过邮件被提交的，最好把补丁作为邮件体的内嵌文本。有些维护者 +接收附件，但是附件的内容格式应该是"text/plain"。然而，附件一般是不赞成的， +因为这会使补丁的引用部分在评论过程中变的很困难。 + +用来发送Linux内核补丁的邮件客户端在发送补丁时应该处于文本的原始状态。例如， +他们不能改变或者删除制表符或者空格，甚至是在每一行的开头或者结尾。 + +不要通过"format=flowed"模式发送补丁。这样会引起不可预期以及有害的断行。 + +不要让你的邮件客户端进行自动换行。这样也会破坏你的补丁。 + +邮件客户端不能改变文本的字符集编码方式。要发送的补丁只能是ASCII或者UTF-8编码方式， +如果你使用UTF-8编码方式发送邮件，那么你将会避免一些可能发生的字符集问题。 + +邮件客户端应该形成并且保持 References: 或者 In-Reply-To: 标题，那么 +邮件话题就不会中断。 + +复制粘帖(或者剪贴粘帖)通常不能用于补丁，因为制表符会转换为空格。使用xclipboard, xclip +或者xcutsel也许可以，但是最好测试一下或者避免使用复制粘帖。 + +不要在使用PGP/GPG署名的邮件中包含补丁。这样会使得很多脚本不能读取和适用于你的补丁。 +（这个问题应该是可以修复的） + +在给内核邮件列表发送补丁之前，给自己发送一个补丁是个不错的主意，保存接收到的 +邮件，将补丁用'patch'命令打上，如果成功了，再给内核邮件列表发送。 + + +一些邮件客户端提示 +---------------------------------------------------------------------- +这里给出一些详细的MUA配置提示，可以用于给Linux内核发送补丁。这些并不意味是 +所有的软件包配置总结。 + +说明： +TUI = 以文本为基础的用户接口 +GUI = 图形界面用户接口 + +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Alpine (TUI) + +配置选项： +在"Sending Preferences"部分： + +- "Do Not Send Flowed Text"必须开启 +- "Strip Whitespace Before Sending"必须关闭 + +当写邮件时，光标应该放在补丁会出现的地方，然后按下CTRL-R组合键，使指定的 +补丁文件嵌入到邮件中。 + +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Evolution (GUI) + +一些开发者成功的使用它发送补丁 + +当选择邮件选项：Preformat + 从Format->Heading->Preformatted (Ctrl-7)或者工具栏 + +然后使用： + Insert->Text File... (Alt-n x)插入补丁文件。 + +你还可以"diff -Nru old.c new.c | xclip"，选择Preformat，然后使用中间键进行粘帖。 + +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Kmail (GUI) + +一些开发者成功的使用它发送补丁。 + +默认设置不为HTML格式是合适的；不要启用它。 + +当书写一封邮件的时候，在选项下面不要选择自动换行。唯一的缺点就是你在邮件中输入的任何文本 +都不会被自动换行，因此你必须在发送补丁之前手动换行。最简单的方法就是启用自动换行来书写邮件， +然后把它保存为草稿。一旦你在草稿中再次打开它，它已经全部自动换行了，那么你的邮件虽然没有 +选择自动换行，但是还不会失去已有的自动换行。 + +在邮件的底部，插入补丁之前，放上常用的补丁定界符：三个连字号(---)。 + +然后在"Message"菜单条目，选择插入文件，接着选取你的补丁文件。还有一个额外的选项，你可以 +通过它配置你的邮件建立工具栏菜单，还可以带上"insert file"图标。 + +你可以安全地通过GPG标记附件，但是内嵌补丁最好不要使用GPG标记它们。作为内嵌文本的签发补丁， +当从GPG中提取7位编码时会使他们变的更加复杂。 + +如果你非要以附件的形式发送补丁，那么就右键点击附件，然后选中属性，突出"Suggest automatic +display"，这样内嵌附件更容易让读者看到。 + +当你要保存将要发送的内嵌文本补丁，你可以从消息列表窗格选择包含补丁的邮件，然后右击选择 +"save as"。你可以使用一个没有更改的包含补丁的邮件，如果它是以正确的形式组成。当你正真在它 +自己的窗口之下察看，那时没有选项可以保存邮件--已经有一个这样的bug被汇报到了kmail的bugzilla +并且希望这将会被处理。邮件是以只针对某个用户可读写的权限被保存的，所以如果你想把邮件复制到其他地方， +你不得不把他们的权限改为组或者整体可读。 + +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Lotus Notes (GUI) + +不要使用它。 + +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Mutt (TUI) + +很多Linux开发人员使用mutt客户端，所以证明它肯定工作的非常漂亮。 + +Mutt不自带编辑器，所以不管你使用什么编辑器都不应该带有自动断行。大多数编辑器都带有 +一个"insert file"选项，它可以通过不改变文件内容的方式插入文件。 + +'vim'作为mutt的编辑器： + set editor="vi" + + 如果使用xclip，敲入以下命令 + :set paste + 按中键之前或者shift-insert或者使用 + :r filename + +如果想要把补丁作为内嵌文本。 +(a)ttach工作的很好，不带有"set paste"。 + +配置选项： +它应该以默认设置的形式工作。 +然而，把"send_charset"设置为"us-ascii::utf-8"也是一个不错的主意。 + +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Pine (TUI) + +Pine过去有一些空格删减问题，但是这些现在应该都被修复了。 + +如果可以，请使用alpine(pine的继承者) + +配置选项： +- 最近的版本需要消除流程文本 +- "no-strip-whitespace-before-send"选项也是需要的。 + + +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Sylpheed (GUI) + +- 内嵌文本可以很好的工作（或者使用附件）。 +- 允许使用外部的编辑器。 +- 对于目录较多时非常慢。 +- 如果通过non-SSL连接，无法使用TLS SMTP授权。 +- 在组成窗口中有一个很有用的ruler bar。 +- 给地址本中添加地址就不会正确的了解显示名。 + +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Thunderbird (GUI) + +默认情况下，thunderbird很容易损坏文本，但是还有一些方法可以强制它变得更好。 + +- 在用户帐号设置里，组成和寻址，不要选择"Compose messages in HTML format"。 + +- 编辑你的Thunderbird配置设置来使它不要拆行使用：user_pref("mailnews.wraplength", 0); + +- 编辑你的Thunderbird配置设置，使它不要使用"format=flowed"格式：user_pref("mailnews. + send_plaintext_flowed", false); + +- 你需要使Thunderbird变为预先格式方式： + 如果默认情况下你书写的是HTML格式，那不是很难。仅仅从标题栏的下拉框中选择"Preformat"格式。 + 如果默认情况下你书写的是文本格式，你不得把它改为HTML格式（仅仅作为一次性的）来书写新的消息， + 然后强制使它回到文本格式，否则它就会拆行。要实现它，在写信的图标上使用shift键来使它变为HTML + 格式，然后标题栏的下拉框中选择"Preformat"格式。 + +- 允许使用外部的编辑器： + 针对Thunderbird打补丁最简单的方法就是使用一个"external editor"扩展，然后使用你最喜欢的 + $EDITOR来读取或者合并补丁到文本中。要实现它，可以下载并且安装这个扩展，然后添加一个使用它的 + 按键View->Toolbars->Customize...最后当你书写信息的时候仅仅点击它就可以了。 + +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +TkRat (GUI) + +可以使用它。使用"Insert file..."或者外部的编辑器。 + +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Gmail (Web GUI) + +不要使用它发送补丁。 + +Gmail网页客户端自动地把制表符转换为空格。 + +虽然制表符转换为空格问题可以被外部编辑器解决，同时它还会使用回车换行把每行拆分为78个字符。 + +另一个问题是Gmail还会把任何不是ASCII的字符的信息改为base64编码。它把东西变的像欧洲人的名字。 + + ### diff --git a/Documentation/translations/zh_CN/filesystems/sysfs.txt b/Documentation/translations/zh_CN/filesystems/sysfs.txt new file mode 100644 index 000000000..452271dda --- /dev/null +++ b/Documentation/translations/zh_CN/filesystems/sysfs.txt @@ -0,0 +1,372 @@ +Chinese translated version of Documentation/filesystems/sysfs.txt + +If you have any comment or update to the content, please contact the +original document maintainer directly. However, if you have a problem +communicating in English you can also ask the Chinese maintainer for +help. Contact the Chinese maintainer if this translation is outdated +or if there is a problem with the translation. + +Maintainer: Patrick Mochel <mochel@osdl.org> + Mike Murphy <mamurph@cs.clemson.edu> +Chinese maintainer: Fu Wei <tekkamanninja@gmail.com> +--------------------------------------------------------------------- +Documentation/filesystems/sysfs.txt 的中文翻译 + +如果想评论或更新本文的内容，请直接联系原文档的维护者。如果你使用英文 +交流有困难的话，也可以向中文版维护者求助。如果本翻译更新不及时或者翻 +译存在问题，请联系中文版维护者。 +英文版维护者： Patrick Mochel <mochel@osdl.org> + Mike Murphy <mamurph@cs.clemson.edu> +中文版维护者： 傅炜 Fu Wei <tekkamanninja@gmail.com> +中文版翻译者： 傅炜 Fu Wei <tekkamanninja@gmail.com> +中文版校译者： 傅炜 Fu Wei <tekkamanninja@gmail.com> + + +以下为正文 +--------------------------------------------------------------------- +sysfs - 用于导出内核对象(kobject)的文件系统 + +Patrick Mochel <mochel@osdl.org> +Mike Murphy <mamurph@cs.clemson.edu> + +修订: 16 August 2011 +原始版本: 10 January 2003 + + +sysfs 简介: +~~~~~~~~~~ + +sysfs 是一个最初基于 ramfs 且位于内存的文件系统。它提供导出内核 +数据结构及其属性，以及它们之间的关联到用户空间的方法。 + +sysfs 始终与 kobject 的底层结构紧密相关。请阅读 +Documentation/kobject.txt 文档以获得更多关于 kobject 接口的 +信息。 + + +使用 sysfs +~~~~~~~~~~~ + +只要内核配置中定义了 CONFIG_SYSFS ，sysfs 总是被编译进内核。你可 +通过以下命令挂载它: + + mount -t sysfs sysfs /sys + + +创建目录 +~~~~~~~~ + +任何 kobject 在系统中注册，就会有一个目录在 sysfs 中被创建。这个 +目录是作为该 kobject 的父对象所在目录的子目录创建的，以准确地传递 +内核的对象层次到用户空间。sysfs 中的顶层目录代表着内核对象层次的 +共同祖先；例如：某些对象属于某个子系统。 + +Sysfs 在与其目录关联的 kernfs_node 对象中内部保存一个指向实现 +目录的 kobject 的指针。以前，这个 kobject 指针被 sysfs 直接用于 +kobject 文件打开和关闭的引用计数。而现在的 sysfs 实现中，kobject +引用计数只能通过 sysfs_schedule_callback() 函数直接修改。 + + +属性 +~~~~ + +kobject 的属性可在文件系统中以普通文件的形式导出。Sysfs 为属性定义 +了面向文件 I/O 操作的方法，以提供对内核属性的读写。 + + +属性应为 ASCII 码文本文件。以一个文件只存储一个属性值为宜。但一个 +文件只包含一个属性值可能影响效率，所以一个包含相同数据类型的属性值 +数组也被广泛地接受。 + +混合类型、表达多行数据以及一些怪异的数据格式会遭到强烈反对。这样做是 +很丢脸的,而且其代码会在未通知作者的情况下被重写。 + + +一个简单的属性结构定义如下: + +struct attribute { + char * name; + struct module *owner; + umode_t mode; +}; + + +int sysfs_create_file(struct kobject * kobj, const struct attribute * attr); +void sysfs_remove_file(struct kobject * kobj, const struct attribute * attr); + + +一个单独的属性结构并不包含读写其属性值的方法。子系统最好为增删特定 +对象类型的属性定义自己的属性结构体和封装函数。 + +例如:驱动程序模型定义的 device_attribute 结构体如下: + +struct device_attribute { + struct attribute attr; + ssize_t (*show)(struct device *dev, struct device_attribute *attr, + char *buf); + ssize_t (*store)(struct device *dev, struct device_attribute *attr, + const char *buf, size_t count); +}; + +int device_create_file(struct device *, const struct device_attribute *); +void device_remove_file(struct device *, const struct device_attribute *); + +为了定义设备属性，同时定义了一下辅助宏: + +#define DEVICE_ATTR(_name, _mode, _show, _store) \ +struct device_attribute dev_attr_##_name = __ATTR(_name, _mode, _show, _store) + +例如:声明 + +static DEVICE_ATTR(foo, S_IWUSR | S_IRUGO, show_foo, store_foo); + +等同于如下代码： + +static struct device_attribute dev_attr_foo = { + .attr = { + .name = "foo", + .mode = S_IWUSR | S_IRUGO, + .show = show_foo, + .store = store_foo, + }, +}; + + +子系统特有的回调函数 +~~~~~~~~~~~~~~~~~~~ + +当一个子系统定义一个新的属性类型时，必须实现一系列的 sysfs 操作， +以帮助读写调用实现属性所有者的显示和储存方法。 + +struct sysfs_ops { + ssize_t (*show)(struct kobject *, struct attribute *, char *); + ssize_t (*store)(struct kobject *, struct attribute *, const char *, size_t); +}; + +[子系统应已经定义了一个 struct kobj_type 结构体作为这个类型的 +描述符，并在此保存 sysfs_ops 的指针。更多的信息参见 kobject 的 +文档] + +sysfs 会为这个类型调用适当的方法。当一个文件被读写时，这个方法会 +将一般的kobject 和 attribute 结构体指针转换为适当的指针类型后 +调用相关联的函数。 + + +示例: + +#define to_dev(obj) container_of(obj, struct device, kobj) +#define to_dev_attr(_attr) container_of(_attr, struct device_attribute, attr) + +static ssize_t dev_attr_show(struct kobject *kobj, struct attribute *attr, + char *buf) +{ + struct device_attribute *dev_attr = to_dev_attr(attr); + struct device *dev = to_dev(kobj); + ssize_t ret = -EIO; + + if (dev_attr->show) + ret = dev_attr->show(dev, dev_attr, buf); + if (ret >= (ssize_t)PAGE_SIZE) { + printk("dev_attr_show: %pS returned bad count\n", + dev_attr->show); + } + return ret; +} + + + +读写属性数据 +~~~~~~~~~~~~ + +在声明属性时，必须指定 show() 或 store() 方法，以实现属性的 +读或写。这些方法的类型应该和以下的设备属性定义一样简单。 + +ssize_t (*show)(struct device *dev, struct device_attribute *attr, char *buf); +ssize_t (*store)(struct device *dev, struct device_attribute *attr, + const char *buf, size_t count); + +也就是说,他们应只以一个处理对象、一个属性和一个缓冲指针作为参数。 + +sysfs 会分配一个大小为 (PAGE_SIZE) 的缓冲区并传递给这个方法。 +Sysfs 将会为每次读写操作调用一次这个方法。这使得这些方法在执行时 +会出现以下的行为: + +- 在读方面（read(2)），show() 方法应该填充整个缓冲区。回想属性 + 应只导出了一个属性值或是一个同类型属性值的数组，所以这个代价将 + 不会不太高。 + + 这使得用户空间可以局部地读和任意的向前搜索整个文件。如果用户空间 + 向后搜索到零或使用‘0’偏移执行一个pread(2)操作，show()方法将 + 再次被调用，以重新填充缓存。 + +- 在写方面（write(2)），sysfs 希望在第一次写操作时得到整个缓冲区。 + 之后 Sysfs 传递整个缓冲区给 store() 方法。 + + 当要写 sysfs 文件时，用户空间进程应首先读取整个文件，修该想要 + 改变的值，然后回写整个缓冲区。 + + 在读写属性值时，属性方法的执行应操作相同的缓冲区。 + +注记: + +- 写操作导致的 show() 方法重载，会忽略当前文件位置。 + +- 缓冲区应总是 PAGE_SIZE 大小。对于i386，这个值为4096。 + +- show() 方法应该返回写入缓冲区的字节数，也就是 snprintf()的 + 返回值。 + +- show() 应始终使用 snprintf()。 + +- store() 应返回缓冲区的已用字节数。如果整个缓存都已填满，只需返回 + count 参数。 + +- show() 或 store() 可以返回错误值。当得到一个非法值，必须返回一个 + 错误值。 + +- 一个传递给方法的对象将会通过 sysfs 调用对象内嵌的引用计数固定在 + 内存中。尽管如此，对象代表的物理实体(如设备)可能已不存在。如有必要， + 应该实现一个检测机制。 + +一个简单的(未经实验证实的)设备属性实现如下： + +static ssize_t show_name(struct device *dev, struct device_attribute *attr, + char *buf) +{ + return scnprintf(buf, PAGE_SIZE, "%s\n", dev->name); +} + +static ssize_t store_name(struct device *dev, struct device_attribute *attr, + const char *buf, size_t count) +{ + snprintf(dev->name, sizeof(dev->name), "%.*s", + (int)min(count, sizeof(dev->name) - 1), buf); + return count; +} + +static DEVICE_ATTR(name, S_IRUGO, show_name, store_name); + + +（注意：真正的实现不允许用户空间设置设备名。） + +顶层目录布局 +~~~~~~~~~~~~ + +sysfs 目录的安排显示了内核数据结构之间的关系。 + +顶层 sysfs 目录如下: + +block/ +bus/ +class/ +dev/ +devices/ +firmware/ +net/ +fs/ + +devices/ 包含了一个设备树的文件系统表示。他直接映射了内部的内核 +设备树，反映了设备的层次结构。 + +bus/ 包含了内核中各种总线类型的平面目录布局。每个总线目录包含两个 +子目录: + + devices/ + drivers/ + +devices/ 包含了系统中出现的每个设备的符号链接，他们指向 root/ 下的 +设备目录。 + +drivers/ 包含了每个已为特定总线上的设备而挂载的驱动程序的目录(这里 +假定驱动没有跨越多个总线类型)。 + +fs/ 包含了一个为文件系统设立的目录。现在每个想要导出属性的文件系统必须 +在 fs/ 下创建自己的层次结构(参见Documentation/filesystems/fuse.txt)。 + +dev/ 包含两个子目录： char/ 和 block/。在这两个子目录中，有以 +<major>:<minor> 格式命名的符号链接。这些符号链接指向 sysfs 目录 +中相应的设备。/sys/dev 提供一个通过一个 stat(2) 操作结果，查找 +设备 sysfs 接口快捷的方法。 + +更多有关 driver-model 的特性信息可以在 Documentation/driver-model/ +中找到。 + + +TODO: 完成这一节。 + + +当前接口 +~~~~~~~~ + +以下的接口层普遍存在于当前的sysfs中: + +- 设备 (include/linux/device.h) +---------------------------------- +结构体: + +struct device_attribute { + struct attribute attr; + ssize_t (*show)(struct device *dev, struct device_attribute *attr, + char *buf); + ssize_t (*store)(struct device *dev, struct device_attribute *attr, + const char *buf, size_t count); +}; + +声明: + +DEVICE_ATTR(_name, _mode, _show, _store); + +增/删属性: + +int device_create_file(struct device *dev, const struct device_attribute * attr); +void device_remove_file(struct device *dev, const struct device_attribute * attr); + + +- 总线驱动程序 (include/linux/device.h) +-------------------------------------- +结构体: + +struct bus_attribute { + struct attribute attr; + ssize_t (*show)(struct bus_type *, char * buf); + ssize_t (*store)(struct bus_type *, const char * buf, size_t count); +}; + +声明: + +BUS_ATTR(_name, _mode, _show, _store) + +增/删属性: + +int bus_create_file(struct bus_type *, struct bus_attribute *); +void bus_remove_file(struct bus_type *, struct bus_attribute *); + + +- 设备驱动程序 (include/linux/device.h) +----------------------------------------- + +结构体: + +struct driver_attribute { + struct attribute attr; + ssize_t (*show)(struct device_driver *, char * buf); + ssize_t (*store)(struct device_driver *, const char * buf, + size_t count); +}; + +声明: + +DRIVER_ATTR(_name, _mode, _show, _store) + +增/删属性： + +int driver_create_file(struct device_driver *, const struct driver_attribute *); +void driver_remove_file(struct device_driver *, const struct driver_attribute *); + + +文档 +~~~~ + +sysfs 目录结构以及其中包含的属性定义了一个内核与用户空间之间的 ABI。 +对于任何 ABI，其自身的稳定和适当的文档是非常重要的。所有新的 sysfs +属性必须在 Documentation/ABI 中有文档。详见 Documentation/ABI/README。 diff --git a/Documentation/translations/zh_CN/gpio.txt b/Documentation/translations/zh_CN/gpio.txt new file mode 100644 index 000000000..4cb1ba8b8 --- /dev/null +++ b/Documentation/translations/zh_CN/gpio.txt @@ -0,0 +1,650 @@ +Chinese translated version of Documentation/gpio + +If you have any comment or update to the content, please contact the +original document maintainer directly. However, if you have a problem +communicating in English you can also ask the Chinese maintainer for +help. Contact the Chinese maintainer if this translation is outdated +or if there is a problem with the translation. + +Maintainer: Grant Likely <grant.likely@secretlab.ca> + Linus Walleij <linus.walleij@linaro.org> +Chinese maintainer: Fu Wei <tekkamanninja@gmail.com> +--------------------------------------------------------------------- +Documentation/gpio 的中文翻译 + +如果想评论或更新本文的内容，请直接联系原文档的维护者。如果你使用英文 +交流有困难的话，也可以向中文版维护者求助。如果本翻译更新不及时或者翻 +译存在问题，请联系中文版维护者。 +英文版维护者： Grant Likely <grant.likely@secretlab.ca> + Linus Walleij <linus.walleij@linaro.org> +中文版维护者： 傅炜 Fu Wei <tekkamanninja@gmail.com> +中文版翻译者： 傅炜 Fu Wei <tekkamanninja@gmail.com> +中文版校译者： 傅炜 Fu Wei <tekkamanninja@gmail.com> + + +以下为正文 +--------------------------------------------------------------------- +GPIO 接口 + +本文档提供了一个在Linux下访问GPIO的公约概述。 + +这些函数以 gpio_* 作为前缀。其他的函数不允许使用这样的前缀或相关的 +__gpio_* 前缀。 + + +什么是GPIO? +========== +"通用输入/输出口"(GPIO)是一个灵活的由软件控制的数字信号。他们可 +由多种芯片提供,且对于从事嵌入式和定制硬件的 Linux 开发者来说是 +比较熟悉。每个GPIO 都代表一个连接到特定引脚或球栅阵列(BGA)封装中 +“球珠”的一个位。电路板原理图显示了 GPIO 与外部硬件的连接关系。 +驱动可以编写成通用代码，以使板级启动代码可传递引脚配置数据给驱动。 + +片上系统 (SOC) 处理器对 GPIO 有很大的依赖。在某些情况下,每个 +非专用引脚都可配置为 GPIO,且大多数芯片都最少有一些 GPIO。 +可编程逻辑器件(类似 FPGA) 可以方便地提供 GPIO。像电源管理和 +音频编解码器这样的多功能芯片经常留有一些这样的引脚来帮助那些引脚 +匮乏的 SOC。同时还有通过 I2C 或 SPI 串行总线连接的“GPIO扩展器” +芯片。大多数 PC 的南桥有一些拥有 GPIO 能力的引脚 (只有BIOS +固件才知道如何使用他们)。 + +GPIO 的实际功能因系统而异。通常用法有: + + - 输出值可写 (高电平=1，低电平=0)。一些芯片也有如何驱动这些值的选项, + 例如只允许输出一个值、支持“线与”及其他取值类似的模式(值得注意的是 + “开漏”信号) + + - 输入值可读(1、0)。一些芯片支持引脚在配置为“输出”时回读，这对于类似 + “线与”的情况(以支持双向信号)是非常有用的。GPIO 控制器可能有输入 + 去毛刺/消抖逻辑,这有时需要软件控制。 + + - 输入通常可作为 IRQ 信号,一般是沿触发,但有时是电平触发。这样的 IRQ + 可能配置为系统唤醒事件,以将系统从低功耗状态下唤醒。 + + - 通常一个 GPIO 根据不同产品电路板的需求,可以配置为输入或输出,也有仅 + 支持单向的。 + + - 大部分 GPIO 可以在持有自旋锁时访问,但是通常由串行总线扩展的 GPIO + 不允许持有自旋锁。但某些系统也支持这种类型。 + +对于给定的电路板,每个 GPIO 都用于某个特定的目的,如监控 MMC/SD 卡的 +插入/移除、检测卡的写保护状态、驱动 LED、配置收发器、模拟串行总线、 +复位硬件看门狗、感知开关状态等等。 + + +GPIO 公约 +========= +注意,这个叫做“公约”，因为这不是强制性的，不遵循这个公约是无伤大雅的， +因为此时可移植性并不重要。GPIO 常用于板级特定的电路逻辑,甚至可能 +随着电路板的版本而改变，且不可能在不同走线的电路板上使用。仅有在少数 +功能上才具有可移植性，其他功能是平台特定。这也是由于“胶合”的逻辑造成的。 + +此外，这不需要任何的执行框架，只是一个接口。某个平台可能通过一个简单地 +访问芯片寄存器的内联函数来实现它，其他平台可能通过委托一系列不同的GPIO +控制器的抽象函数来实现它。(有一些可选的代码能支持这种策略的实现,本文档 +后面会介绍，但作为 GPIO 接口的客户端驱动程序必须与它的实现无关。) + +也就是说,如果在他们的平台上支持这个公约，驱动应尽可能的使用它。同时，平台 +必须在 Kconfig 中选择 ARCH_REQUIRE_GPIOLIB 或者 ARCH_WANT_OPTIONAL_GPIOLIB +选项。那些调用标准 GPIO 函数的驱动应该在 Kconfig 入口中声明依赖GENERIC_GPIO。 +当驱动包含文件: + + #include <linux/gpio.h> + +则 GPIO 函数是可用,无论是“真实代码”还是经优化过的语句。如果你遵守 +这个公约，当你的代码完成后，对其他的开发者来说会更容易看懂和维护。 + +注意，这些操作包含所用平台的 I/O 屏障代码，驱动无须显式地调用他们。 + + +标识 GPIO +--------- +GPIO 是通过无符号整型来标识的,范围是 0 到 MAX_INT。保留“负”数 +用于其他目的,例如标识信号“在这个板子上不可用”或指示错误。未接触底层 +硬件的代码会忽略这些整数。 + +平台会定义这些整数的用法,且通常使用 #define 来定义 GPIO，这样 +板级特定的启动代码可以直接关联相应的原理图。相对来说，驱动应该仅使用 +启动代码传递过来的 GPIO 编号，使用 platform_data 保存板级特定 +引脚配置数据 (同时还有其他须要的板级特定数据)，避免可能出现的问题。 + +例如一个平台使用编号 32-159 来标识 GPIO,而在另一个平台使用编号0-63 +标识一组 GPIO 控制器,64-79标识另一类 GPIO 控制器,且在一个含有 +FPGA 的特定板子上使用 80-95。编号不一定要连续,那些平台中，也可以 +使用编号2000-2063来标识一个 I2C 接口的 GPIO 扩展器中的 GPIO。 + +如果你要初始化一个带有无效 GPIO 编号的结构体,可以使用一些负编码 +(如"-EINVAL")，那将使其永远不会是有效。来测试这样一个结构体中的编号 +是否关联一个 GPIO，你可使用以下断言: + + int gpio_is_valid(int number); + +如果编号不存在，则请求和释放 GPIO 的函数将拒绝执行相关操作(见下文)。 +其他编号也可能被拒绝,比如一个编号可能存在，但暂时在给定的电路上不可用。 + +一个平台是否支持多个 GPIO 控制器为平台特定的实现问题，就像是否可以 +在 GPIO 编号空间中有“空洞”和是否可以在运行时添加新的控制器一样。 +这些问题会影响其他事情，包括相邻的 GPIO 编号是否存在等。 + +使用 GPIO +--------- +对于一个 GPIO，系统应该做的第一件事情就是通过 gpio_request() +函数分配它，见下文。 + +接下来是设置I/O方向，这通常是在板级启动代码中为所使用的 GPIO 设置 +platform_device 时完成。 + + /* 设置为输入或输出, 返回 0 或负的错误代码 */ + int gpio_direction_input(unsigned gpio); + int gpio_direction_output(unsigned gpio, int value); + +返回值为零代表成功，否则返回一个负的错误代码。这个返回值需要检查，因为 +get/set(获取/设置)函数调用没法返回错误,且有可能是配置错误。通常， +你应该在进程上下文中调用这些函数。然而,对于自旋锁安全的 GPIO，在板子 +启动的早期、进程启动前使用他们也是可以的。 + +对于作为输出的 GPIO，为其提供初始输出值，对于避免在系统启动期间出现 +信号毛刺是很有帮助的。 + +为了与传统的 GPIO 接口兼容, 在设置一个 GPIO 方向时，如果它还未被申请， +则隐含了申请那个 GPIO 的操作(见下文)。这种兼容性正在从可选的 gpiolib +框架中移除。 + +如果这个 GPIO 编码不存在，或者特定的 GPIO 不能用于那种模式，则方向 +设置可能失败。依赖启动固件来正确地设置方向通常是一个坏主意，因为它可能 +除了启动Linux，并没有做更多的验证工作。(同理, 板子的启动代码可能需要 +将这个复用的引脚设置为 GPIO，并正确地配置上拉/下拉电阻。) + + +访问自旋锁安全的 GPIO +------------------- +大多数 GPIO 控制器可以通过内存读/写指令来访问。这些指令不会休眠,可以 +安全地在硬(非线程)中断例程和类似的上下文中完成。 + +对于那些用 gpio_cansleep()测试总是返回失败的 GPIO(见下文)，使用 +以下的函数访问: + + /* GPIO 输入:返回零或非零 */ + int gpio_get_value(unsigned gpio); + + /* GPIO 输出 */ + void gpio_set_value(unsigned gpio, int value); + +GPIO值是布尔值，零表示低电平，非零表示高电平。当读取一个输出引脚的值时， +返回值应该是引脚上的值。这个值不总是和输出值相符，因为存在开漏输出信号和 +输出延迟问题。 + +以上的 get/set 函数无错误返回值，因为之前 gpio_direction_*()应已检查过 +其是否为“无效GPIO”。此外，还需要注意的是并不是所有平台都可以从输出引脚 +中读取数据，对于不能读取的引脚应总返回零。另外，对那些在原子上下文中无法 +安全访问的 GPIO (译者注：因为访问可能导致休眠)使用这些函数是不合适的 +(见下文)。 + +在 GPIO 编号(还有输出、值)为常数的情况下,鼓励通过平台特定的实现来优化 +这两个函数来访问 GPIO 值。这种情况(读写一个硬件寄存器)下只需要几条指令 +是很正常的,且无须自旋锁。这种优化函数比起那些在子程序上花费许多指令的 +函数可以使得模拟接口(译者注:例如 GPIO 模拟 I2C、1-wire 或 SPI)的 +应用(在空间和时间上都)更具效率。 + + +访问可能休眠的 GPIO +----------------- +某些 GPIO 控制器必须通过基于总线(如 I2C 或 SPI)的消息访问。读或写这些 +GPIO 值的命令需要等待其信息排到队首才发送命令，再获得其反馈。期间需要 +休眠，这不能在 IRQ 例程(中断上下文)中执行。 + +支持此类 GPIO 的平台通过以下函数返回非零值来区分出这种 GPIO。(此函数需要 +一个之前通过 gpio_request 分配到的有效 GPIO 编号): + + int gpio_cansleep(unsigned gpio); + +为了访问这种 GPIO,内核定义了一套不同的函数: + + /* GPIO 输入:返回零或非零 ,可能会休眠 */ + int gpio_get_value_cansleep(unsigned gpio); + + /* GPIO 输出,可能会休眠 */ + void gpio_set_value_cansleep(unsigned gpio, int value); + + +访问这样的 GPIO 需要一个允许休眠的上下文，例如线程 IRQ 处理例程，并用以上的 +访问函数替换那些没有 cansleep()后缀的自旋锁安全访问函数。 + +除了这些访问函数可能休眠，且它们操作的 GPIO 不能在硬件 IRQ 处理例程中访问的 +事实，这些处理例程实际上和自旋锁安全的函数是一样的。 + +** 除此之外 ** 调用设置和配置此类 GPIO 的函数也必须在允许休眠的上下文中， +因为它们可能也需要访问 GPIO 控制器芯片: (这些设置函数通常在板级启动代码或者 +驱动探测/断开代码中，所以这是一个容易满足的约束条件。) + + gpio_direction_input() + gpio_direction_output() + gpio_request() + +## gpio_request_one() +## gpio_request_array() +## gpio_free_array() + + gpio_free() + gpio_set_debounce() + + + +声明和释放 GPIO +---------------------------- +为了有助于捕获系统配置错误,定义了两个函数。 + + /* 申请 GPIO, 返回 0 或负的错误代码. + * 非空标签可能有助于诊断. + */ + int gpio_request(unsigned gpio, const char *label); + + /* 释放之前声明的 GPIO */ + void gpio_free(unsigned gpio); + +将无效的 GPIO 编码传递给 gpio_request()会导致失败，申请一个已使用这个 +函数声明过的 GPIO 也会失败。gpio_request()的返回值必须检查。你应该在 +进程上下文中调用这些函数。然而,对于自旋锁安全的 GPIO,在板子启动的早期、 +进入进程之前是可以申请的。 + +这个函数完成两个基本的目标。一是标识那些实际上已作为 GPIO 使用的信号线， +这样便于更好地诊断;系统可能需要服务几百个可用的 GPIO，但是对于任何一个 +给定的电路板通常只有一些被使用。另一个目的是捕获冲突，查明错误:如两个或 +更多驱动错误地认为他们已经独占了某个信号线,或是错误地认为移除一个管理着 +某个已激活信号的驱动是安全的。也就是说，申请 GPIO 的作用类似一种锁机制。 + +某些平台可能也使用 GPIO 作为电源管理激活信号(例如通过关闭未使用芯片区和 +简单地关闭未使用时钟)。 + +对于 GPIO 使用 pinctrl 子系统已知的引脚，子系统应该被告知其使用情况； +一个 gpiolib 驱动的 .request()操作应调用 pinctrl_gpio_request()， +而 gpiolib 驱动的 .free()操作应调用 pinctrl_gpio_free()。pinctrl +子系统允许 pinctrl_gpio_request()在某个引脚或引脚组以复用形式“属于” +一个设备时都成功返回。 + +任何须将 GPIO 信号导向适当引脚的引脚复用硬件的编程应该发生在 GPIO +驱动的 .direction_input()或 .direction_output()函数中，以及 +任何输出 GPIO 值的设置之后。这样可使从引脚特殊功能到 GPIO 的转换 +不会在引脚产生毛刺波形。有时当用一个 GPIO 实现其信号驱动一个非 GPIO +硬件模块的解决方案时，就需要这种机制。 + +某些平台允许部分或所有 GPIO 信号使用不同的引脚。类似的，GPIO 或引脚的 +其他方面也需要配置，如上拉/下拉。平台软件应该在对这些 GPIO 调用 +gpio_request()前将这类细节配置好，例如使用 pinctrl 子系统的映射表， +使得 GPIO 的用户无须关注这些细节。 + +还有一个值得注意的是在释放 GPIO 前，你必须停止使用它。 + + +注意:申请一个 GPIO 并没有以任何方式配置它，只不过标识那个 GPIO 处于使用 +状态。必须有另外的代码来处理引脚配置(如控制 GPIO 使用的引脚、上拉/下拉)。 +考虑到大多数情况下声明 GPIO 之后就会立即配置它们,所以定义了以下三个辅助函数: + + /* 申请一个 GPIO 信号, 同时通过特定的'flags'初始化配置, + * 其他和 gpio_request()的参数和返回值相同 + * + */ + int gpio_request_one(unsigned gpio, unsigned long flags, const char *label); + + /* 在单个函数中申请多个 GPIO + */ + int gpio_request_array(struct gpio *array, size_t num); + + /* 在单个函数中释放多个 GPIO + */ + void gpio_free_array(struct gpio *array, size_t num); + +这里 'flags' 当前定义可指定以下属性: + + * GPIOF_DIR_IN - 配置方向为输入 + * GPIOF_DIR_OUT - 配置方向为输出 + + * GPIOF_INIT_LOW - 在作为输出时,初始值为低电平 + * GPIOF_INIT_HIGH - 在作为输出时,初始值为高电平 + * GPIOF_OPEN_DRAIN - gpio引脚为开漏信号 + * GPIOF_OPEN_SOURCE - gpio引脚为源极开路信号 + + * GPIOF_EXPORT_DIR_FIXED - 将 gpio 导出到 sysfs，并保持方向 + * GPIOF_EXPORT_DIR_CHANGEABLE - 同样是导出, 但允许改变方向 + +因为 GPIOF_INIT_* 仅有在配置为输出的时候才存在,所以有效的组合为: + + * GPIOF_IN - 配置为输入 + * GPIOF_OUT_INIT_LOW - 配置为输出,并初始化为低电平 + * GPIOF_OUT_INIT_HIGH - 配置为输出,并初始化为高电平 + +当设置 flag 为 GPIOF_OPEN_DRAIN 时，则假设引脚是开漏信号。这样的引脚 +将不会在输出模式下置1。这样的引脚需要连接上拉电阻。通过使能这个标志，gpio库 +将会在被要求输出模式下置1时将引脚变为输入状态来使引脚置高。引脚在输出模式下 +通过置0使其输出低电平。 + +当设置 flag 为 GPIOF_OPEN_SOURCE 时，则假设引脚为源极开路信号。这样的引脚 +将不会在输出模式下置0。这样的引脚需要连接下拉电阻。通过使能这个标志，gpio库 +将会在被要求输出模式下置0时将引脚变为输入状态来使引脚置低。引脚在输出模式下 +通过置1使其输出高电平。 + +将来这些标志可能扩展到支持更多的属性。 + +更进一步,为了更简单地声明/释放多个 GPIO,'struct gpio'被引进来封装所有 +这三个领域: + + struct gpio { + unsigned gpio; + unsigned long flags; + const char *label; + }; + +一个典型的用例: + + static struct gpio leds_gpios[] = { + { 32, GPIOF_OUT_INIT_HIGH, "Power LED" }, /* 默认开启 */ + { 33, GPIOF_OUT_INIT_LOW, "Green LED" }, /* 默认关闭 */ + { 34, GPIOF_OUT_INIT_LOW, "Red LED" }, /* 默认关闭 */ + { 35, GPIOF_OUT_INIT_LOW, "Blue LED" }, /* 默认关闭 */ + { ... }, + }; + + err = gpio_request_one(31, GPIOF_IN, "Reset Button"); + if (err) + ... + + err = gpio_request_array(leds_gpios, ARRAY_SIZE(leds_gpios)); + if (err) + ... + + gpio_free_array(leds_gpios, ARRAY_SIZE(leds_gpios)); + + +GPIO 映射到 IRQ +-------------------- +GPIO 编号是无符号整数;IRQ 编号也是。这些构成了两个逻辑上不同的命名空间 +(GPIO 0 不一定使用 IRQ 0)。你可以通过以下函数在它们之间实现映射: + + /* 映射 GPIO 编号到 IRQ 编号 */ + int gpio_to_irq(unsigned gpio); + + /* 映射 IRQ 编号到 GPIO 编号 (尽量避免使用) */ + int irq_to_gpio(unsigned irq); + +它们的返回值为对应命名空间的相关编号，或是负的错误代码(如果无法映射)。 +(例如,某些 GPIO 无法做为 IRQ 使用。)以下的编号错误是未经检测的:使用一个 +未通过 gpio_direction_input()配置为输入的 GPIO 编号，或者使用一个 +并非来源于gpio_to_irq()的 IRQ 编号。 + +这两个映射函数可能会在信号编号的加减计算过程上花些时间。它们不可休眠。 + +gpio_to_irq()返回的非错误值可以传递给 request_irq()或者 free_irq()。 +它们通常通过板级特定的初始化代码存放到平台设备的 IRQ 资源中。注意:IRQ +触发选项是 IRQ 接口的一部分，如 IRQF_TRIGGER_FALLING，系统唤醒能力 +也是如此。 + +irq_to_gpio()返回的非错误值大多数通常可以被 gpio_get_value()所使用， +比如在 IRQ 是沿触发时初始化或更新驱动状态。注意某些平台不支持反映射,所以 +你应该尽量避免使用它。 + + +模拟开漏信号 +---------------------------- +有时在只有低电平信号作为实际驱动结果(译者注:多个输出连接于一点，逻辑电平 +结果为所有输出的逻辑与)的时候,共享的信号线需要使用“开漏”信号。(该术语 +适用于 CMOS 管；而 TTL 用“集电极开路”。)一个上拉电阻使信号为高电平。这 +有时被称为“线与”。实际上，从负逻辑(低电平为真)的角度来看，这是一个“线或”。 + +一个开漏信号的常见例子是共享的低电平使能 IRQ 信号线。此外,有时双向数据总线 +信号也使用漏极开路信号。 + +某些 GPIO 控制器直接支持开漏输出，还有许多不支持。当你需要开漏信号，但 +硬件又不直接支持的时候，一个常用的方法是用任何即可作输入也可作输出的 GPIO +引脚来模拟: + + LOW: gpio_direction_output(gpio, 0) ... 这代码驱动信号并覆盖 + 上拉配置。 + + HIGH: gpio_direction_input(gpio) ... 这代码关闭输出,所以上拉电阻 + (或其他的一些器件)控制了信号。 + +如果你将信号线“驱动”为高电平，但是 gpio_get_value(gpio)报告了一个 +低电平(在适当的上升时间后)，你就可以知道是其他的一些组件将共享信号线拉低了。 +这不一定是错误的。一个常见的例子就是 I2C 时钟的延长：一个需要较慢时钟的 +从设备延迟 SCK 的上升沿，而 I2C 主设备相应地调整其信号传输速率。 + + +这些公约忽略了什么? +================ +这些公约忽略的最大一件事就是引脚复用，因为这属于高度芯片特定的属性且 +没有可移植性。某个平台可能不需要明确的复用信息；有的对于任意给定的引脚 +可能只有两个功能选项；有的可能每个引脚有八个功能选项；有的可能可以将 +几个引脚中的任何一个作为给定的 GPIO。(是的，这些例子都来自于当前运行 +Linux 的系统。) + +在某些系统中,与引脚复用相关的是配置和使能集成的上、下拉模式。并不是所有 +平台都支持这种模式,或者不会以相同的方式来支持这种模式；且任何给定的电路板 +可能使用外置的上拉(或下拉)电阻,这时芯片上的就不应该使用。(当一个电路需要 +5kOhm 的拉动电阻,芯片上的 100 kOhm 电阻就不能做到。)同样的，驱动能力 +(2 mA vs 20 mA)和电压(1.8V vs 3.3V)是平台特定问题,就像模型一样在 +可配置引脚和 GPIO 之间(没)有一一对应的关系。 + +还有其他一些系统特定的机制没有在这里指出，例如上述的输入去毛刺和线与输出 +选项。硬件可能支持批量读或写 GPIO，但是那一般是配置相关的：对于处于同一 +块区(bank)的GPIO。(GPIO 通常以 16 或 32 个组成一个区块，一个给定的 +片上系统一般有几个这样的区块。)某些系统可以通过输出 GPIO 触发 IRQ， +或者从并非以 GPIO 管理的引脚取值。这些机制的相关代码没有必要具有可移植性。 + +当前，动态定义 GPIO 并不是标准的，例如作为配置一个带有某些 GPIO 扩展器的 +附加电路板的副作用。 + +GPIO 实现者的框架 (可选) +===================== +前面提到了，有一个可选的实现框架，让平台使用相同的编程接口，更加简单地支持 +不同种类的 GPIO 控制器。这个框架称为"gpiolib"。 + +作为一个辅助调试功能，如果 debugfs 可用，就会有一个 /sys/kernel/debug/gpio +文件。通过这个框架，它可以列出所有注册的控制器,以及当前正在使用中的 GPIO +的状态。 + + +控制器驱动: gpio_chip +------------------- +在框架中每个 GPIO 控制器都包装为一个 "struct gpio_chip"，他包含了 +该类型的每个控制器的常用信息: + + - 设置 GPIO 方向的方法 + - 用于访问 GPIO 值的方法 + - 告知调用其方法是否可能休眠的标志 + - 可选的 debugfs 信息导出方法 (显示类似上拉配置一样的额外状态) + - 诊断标签 + +也包含了来自 device.platform_data 的每个实例的数据：它第一个 GPIO 的 +编号和它可用的 GPIO 的数量。 + +实现 gpio_chip 的代码应支持多控制器实例，这可能使用驱动模型。那些代码要 +配置每个 gpio_chip，并发起gpiochip_add()。卸载一个 GPIO 控制器很少见， +但在必要的时候可以使用 gpiochip_remove()。 + +大部分 gpio_chip 是一个实例特定结构体的一部分，而并不将 GPIO 接口单独 +暴露出来,比如编址、电源管理等。类似编解码器这样的芯片会有复杂的非 GPIO +状态。 + +任何一个 debugfs 信息导出方法通常应该忽略还未申请作为 GPIO 的信号线。 +他们可以使用 gpiochip_is_requested()测试，当这个 GPIO 已经申请过了 +就返回相关的标签，否则返回 NULL。 + + +平台支持 +------- +为了支持这个框架，一个平台的 Kconfig 文件将会 "select"(选择) +ARCH_REQUIRE_GPIOLIB 或 ARCH_WANT_OPTIONAL_GPIOLIB，并让它的 +<asm/gpio.h> 包含 <asm-generic/gpio.h>，同时定义三个方法: +gpio_get_value()、gpio_set_value()和 gpio_cansleep()。 + +它也应提供一个 ARCH_NR_GPIOS 的定义值，这样可以更好地反映该平台 GPIO +的实际数量,节省静态表的空间。(这个定义值应该包含片上系统内建 GPIO 和 +GPIO 扩展器中的数据。) + +ARCH_REQUIRE_GPIOLIB 意味着 gpiolib 核心在这个构架中将总是编译进内核。 + +ARCH_WANT_OPTIONAL_GPIOLIB 意味着 gpiolib 核心默认关闭,且用户可以 +使能它,并将其编译进内核(可选)。 + +如果这些选项都没被选择,该平台就不通过 GPIO-lib 支持 GPIO,且代码不可以 +被用户使能。 + +以下这些方法的实现可以直接使用框架代码,并总是通过 gpio_chip 调度: + + #define gpio_get_value __gpio_get_value + #define gpio_set_value __gpio_set_value + #define gpio_cansleep __gpio_cansleep + +这些定义可以用更理想的实现方法替代，那就是使用经过逻辑优化的内联函数来访问 +基于特定片上系统的 GPIO。例如,若引用的 GPIO (寄存器位偏移)是常量“12”， +读取或设置它可能只需少则两或三个指令，且不会休眠。当这样的优化无法实现时， +那些函数必须使用框架提供的代码，那就至少要几十条指令才可以实现。对于用 GPIO +模拟的 I/O 接口, 如此精简指令是很有意义的。 + +对于片上系统，平台特定代码为片上 GPIO 每个区(bank)定义并注册 gpio_chip +实例。那些 GPIO 应该根据芯片厂商的文档进行编码/标签,并直接和电路板原理图 +对应。他们应该开始于零并终止于平台特定的限制。这些 GPIO(代码)通常从 +arch_initcall()或者更早的地方集成进平台初始化代码，使这些 GPIO 总是可用， +且他们通常可以作为 IRQ 使用。 + +板级支持 +------- +对于外部 GPIO 控制器(例如 I2C 或 SPI 扩展器、专用芯片、多功能器件、FPGA +或 CPLD)，大多数常用板级特定代码都可以注册控制器设备，并保证他们的驱动知道 +gpiochip_add()所使用的 GPIO 编号。他们的起始编号通常跟在平台特定的 GPIO +编号之后。 + +例如板级启动代码应该创建结构体指明芯片公开的 GPIO 范围，并使用 platform_data +将其传递给每个 GPIO 扩展器芯片。然后芯片驱动中的 probe()例程可以将这个 +数据传递给 gpiochip_add()。 + +初始化顺序很重要。例如，如果一个设备依赖基于 I2C 的(扩展)GPIO，那么它的 +probe()例程就应该在那个 GPIO 有效以后才可以被调用。这意味着设备应该在 +GPIO 可以工作之后才可被注册。解决这类依赖的的一种方法是让这种 gpio_chip +控制器向板级特定代码提供 setup()和 teardown()回调函数。一旦所有必须的 +资源可用之后，这些板级特定的回调函数将会注册设备，并可以在这些 GPIO 控制器 +设备变成无效时移除它们。 + + +用户空间的 Sysfs 接口(可选) +======================== +使用“gpiolib”实现框架的平台可以选择配置一个 GPIO 的 sysfs 用户接口。 +这不同于 debugfs 接口，因为它提供的是对 GPIO方向和值的控制，而不只显示 +一个GPIO 的状态摘要。此外,它可以出现在没有调试支持的产品级系统中。 + +例如，通过适当的系统硬件文档，用户空间可以知道 GIOP #23 控制 Flash +存储器的写保护(用于保护其中 Bootloader 分区)。产品的系统升级可能需要 +临时解除这个保护：首先导入一个 GPIO，改变其输出状态，然后在重新使能写保护 +前升级代码。通常情况下,GPIO #23 是不会被触及的，并且内核也不需要知道他。 + +根据适当的硬件文档，某些系统的用户空间 GPIO 可以用于确定系统配置数据， +这些数据是标准内核不知道的。在某些任务中，简单的用户空间 GPIO 驱动可能是 +系统真正需要的。 + +注意：标准内核驱动中已经存在通用的“LED 和按键”GPIO 任务，分别是: +"leds-gpio" 和 "gpio_keys"。请使用这些来替代直接访问 GPIO，因为集成在 +内核框架中的这类驱动比你在用户空间的代码更好。 + + +Sysfs 中的路径 +-------------- +在/sys/class/gpio 中有 3 类入口: + + - 用于在用户空间控制 GPIO 的控制接口; + + - GPIOs 本身;以及 + + - GPIO 控制器 ("gpio_chip" 实例)。 + +除了这些标准的文件,还包含“device”符号链接。 + +控制接口是只写的: + + /sys/class/gpio/ + + "export" ... 用户空间可以通过写其编号到这个文件，要求内核导出 + 一个 GPIO 的控制到用户空间。 + + 例如: 如果内核代码没有申请 GPIO #19,"echo 19 > export" + 将会为 GPIO #19 创建一个 "gpio19" 节点。 + + "unexport" ... 导出到用户空间的逆操作。 + + 例如: "echo 19 > unexport" 将会移除使用"export"文件导出的 + "gpio19" 节点。 + +GPIO 信号的路径类似 /sys/class/gpio/gpio42/ (对于 GPIO #42 来说)， +并有如下的读/写属性: + + /sys/class/gpio/gpioN/ + + "direction" ... 读取得到 "in" 或 "out"。这个值通常运行写入。 + 写入"out" 时,其引脚的默认输出为低电平。为了确保无故障运行， + "low" 或 "high" 的电平值应该写入 GPIO 的配置，作为初始输出值。 + + 注意:如果内核不支持改变 GPIO 的方向，或者在导出时内核代码没有 + 明确允许用户空间可以重新配置 GPIO 方向，那么这个属性将不存在。 + + "value" ... 读取得到 0 (低电平) 或 1 (高电平)。如果 GPIO 配置为 + 输出,这个值允许写操作。任何非零值都以高电平看待。 + + 如果引脚可以配置为中断信号，且如果已经配置了产生中断的模式 + （见"edge"的描述），你可以对这个文件使用轮询操作(poll(2))， + 且轮询操作会在任何中断触发时返回。如果你使用轮询操作(poll(2))， + 请在 events 中设置 POLLPRI 和 POLLERR。如果你使用轮询操作 + (select(2))，请在 exceptfds 设置你期望的文件描述符。在 + 轮询操作(poll(2))返回之后，既可以通过 lseek(2)操作读取 + sysfs 文件的开始部分，也可以关闭这个文件并重新打开它来读取数据。 + + "edge" ... 读取得到“none”、“rising”、“falling”或者“both”。 + 将这些字符串写入这个文件可以选择沿触发模式，会使得轮询操作 + (select(2))在"value"文件中返回。 + + 这个文件仅有在这个引脚可以配置为可产生中断输入引脚时，才存在。 + + "active_low" ... 读取得到 0 (假) 或 1 (真)。写入任何非零值可以 + 翻转这个属性的(读写)值。已存在或之后通过"edge"属性设置了"rising" + 和 "falling" 沿触发模式的轮询操作(poll(2))将会遵循这个设置。 + +GPIO 控制器的路径类似 /sys/class/gpio/gpiochip42/ (对于从#42 GPIO +开始实现控制的控制器),并有着以下只读属性: + + /sys/class/gpio/gpiochipN/ + + "base" ... 与以上的 N 相同,代表此芯片管理的第一个 GPIO 的编号 + + "label" ... 用于诊断 (并不总是只有唯一值) + + "ngpio" ... 此控制器所管理的 GPIO 数量(而 GPIO 编号从 N 到 + N + ngpio - 1) + +大多数情况下,电路板的文档应当标明每个 GPIO 的使用目的。但是那些编号并不总是 +固定的,例如在扩展卡上的 GPIO会根据所使用的主板或所在堆叠架构中其他的板子而 +有所不同。在这种情况下,你可能需要使用 gpiochip 节点(尽可能地结合电路图)来 +确定给定信号所用的 GPIO 编号。 + + +从内核代码中导出 +------------- +内核代码可以明确地管理那些已通过 gpio_request()申请的 GPIO 的导出: + + /* 导出 GPIO 到用户空间 */ + int gpio_export(unsigned gpio, bool direction_may_change); + + /* gpio_export()的逆操作 */ + void gpio_unexport(); + + /* 创建一个 sysfs 连接到已导出的 GPIO 节点 */ + int gpio_export_link(struct device *dev, const char *name, + unsigned gpio) + +在一个内核驱动申请一个 GPIO 之后，它可以通过 gpio_export()使其在 sysfs +接口中可见。该驱动可以控制信号方向是否可修改。这有助于防止用户空间代码无意间 +破坏重要的系统状态。 + +这个明确的导出有助于(通过使某些实验更容易来)调试，也可以提供一个始终存在的接口， +与文档配合作为板级支持包的一部分。 + +在 GPIO 被导出之后，gpio_export_link()允许在 sysfs 文件系统的任何地方 +创建一个到这个 GPIO sysfs 节点的符号链接。这样驱动就可以通过一个描述性的 +名字，在 sysfs 中他们所拥有的设备下提供一个(到这个 GPIO sysfs 节点的)接口。 diff --git a/Documentation/translations/zh_CN/index.rst b/Documentation/translations/zh_CN/index.rst new file mode 100644 index 000000000..75956d669 --- /dev/null +++ b/Documentation/translations/zh_CN/index.rst @@ -0,0 +1,12 @@ +.. raw:: latex + + \renewcommand\thesection* + \renewcommand\thesubsection* + +Chinese translations +==================== + +.. toctree:: + :maxdepth: 1 + + coding-style diff --git a/Documentation/translations/zh_CN/io_ordering.txt b/Documentation/translations/zh_CN/io_ordering.txt new file mode 100644 index 000000000..1f8127bdd --- /dev/null +++ b/Documentation/translations/zh_CN/io_ordering.txt @@ -0,0 +1,67 @@ +Chinese translated version of Documentation/io_ordering.txt + +If you have any comment or update to the content, please contact the +original document maintainer directly. However, if you have a problem +communicating in English you can also ask the Chinese maintainer for +help. Contact the Chinese maintainer if this translation is outdated +or if there is a problem with the translation. + +Chinese maintainer: Lin Yongting <linyongting@gmail.com> +--------------------------------------------------------------------- +Documentation/io_ordering.txt 的中文翻译 + +如果想评论或更新本文的内容，请直接联系原文档的维护者。如果你使用英文 +交流有困难的话，也可以向中文版维护者求助。如果本翻译更新不及时或者翻 +译存在问题，请联系中文版维护者。 + +中文版维护者： 林永听 Lin Yongting <linyongting@gmail.com> +中文版翻译者： 林永听 Lin Yongting <linyongting@gmail.com> +中文版校译者： 林永听 Lin Yongting <linyongting@gmail.com> + + +以下为正文 +--------------------------------------------------------------------- + +在某些平台上，所谓的内存映射I/O是弱顺序。在这些平台上，驱动开发者有责任 +保证I/O内存映射地址的写操作按程序图意的顺序达到设备。通常读取一个“安全” +设备寄存器或桥寄存器，触发IO芯片清刷未处理的写操作到达设备后才处理读操作， +而达到保证目的。驱动程序通常在spinlock保护的临界区退出之前使用这种技术。 +这也可以保证后面的写操作只在前面的写操作之后到达设备（这非常类似于内存 +屏障操作，mb()，不过仅适用于I/O）。 + +假设一个设备驱动程的具体例子： + + ... +CPU A: spin_lock_irqsave(&dev_lock, flags) +CPU A: val = readl(my_status); +CPU A: ... +CPU A: writel(newval, ring_ptr); +CPU A: spin_unlock_irqrestore(&dev_lock, flags) + ... +CPU B: spin_lock_irqsave(&dev_lock, flags) +CPU B: val = readl(my_status); +CPU B: ... +CPU B: writel(newval2, ring_ptr); +CPU B: spin_unlock_irqrestore(&dev_lock, flags) + ... + +上述例子中，设备可能会先接收到newval2的值，然后接收到newval的值，问题就 +发生了。不过很容易通过下面方法来修复： + + ... +CPU A: spin_lock_irqsave(&dev_lock, flags) +CPU A: val = readl(my_status); +CPU A: ... +CPU A: writel(newval, ring_ptr); +CPU A: (void)readl(safe_register); /* 配置寄存器？*/ +CPU A: spin_unlock_irqrestore(&dev_lock, flags) + ... +CPU B: spin_lock_irqsave(&dev_lock, flags) +CPU B: val = readl(my_status); +CPU B: ... +CPU B: writel(newval2, ring_ptr); +CPU B: (void)readl(safe_register); /* 配置寄存器？*/ +CPU B: spin_unlock_irqrestore(&dev_lock, flags) + +在解决方案中，读取safe_register寄存器，触发IO芯片清刷未处理的写操作， +再处理后面的读操作，防止引发数据不一致问题。 diff --git a/Documentation/translations/zh_CN/magic-number.txt b/Documentation/translations/zh_CN/magic-number.txt new file mode 100644 index 000000000..7159cec04 --- /dev/null +++ b/Documentation/translations/zh_CN/magic-number.txt @@ -0,0 +1,153 @@ +Chinese translated version of Documentation/process/magic-number.rst + +If you have any comment or update to the content, please post to LKML directly. +However, if you have problem communicating in English you can also ask the +Chinese maintainer for help. Contact the Chinese maintainer, if this +translation is outdated or there is problem with translation. + +Chinese maintainer: Jia Wei Wei <harryxiyou@gmail.com> +--------------------------------------------------------------------- +Documentation/process/magic-number.rst的中文翻译 + +如果想评论或更新本文的内容，请直接发信到LKML。如果你使用英文交流有困难的话，也可 +以向中文版维护者求助。如果本翻译更新不及时或者翻译存在问题，请联系中文版维护者。 + +中文版维护者： 贾威威 Jia Wei Wei <harryxiyou@gmail.com> +中文版翻译者： 贾威威 Jia Wei Wei <harryxiyou@gmail.com> +中文版校译者： 贾威威 Jia Wei Wei <harryxiyou@gmail.com> + +以下为正文 +--------------------------------------------------------------------- +这个文件是有关当前使用的魔术值注册表。当你给一个结构添加了一个魔术值，你也应该把这个魔术值添加到这个文件，因为我们最好把用于各种结构的魔术值统一起来。 + +使用魔术值来保护内核数据结构是一个非常好的主意。这就允许你在运行期检查(a)一个结构是否已经被攻击，或者(b)你已经给一个例行程序通过了一个错误的结构。后一种情况特别地有用---特别是当你通过一个空指针指向结构体的时候。tty源码，例如，经常通过特定驱动使用这种方法并且反复地排列特定方面的结构。 + +使用魔术值的方法是在结构的开始处声明的，如下： + +struct tty_ldisc { + int magic; + ... +}; + +当你以后给内核添加增强功能的时候，请遵守这条规则！这样就会节省数不清的调试时间，特别是一些古怪的情况，例如，数组超出范围并且重新写了超出部分。遵守这个规则，这些情况可以被快速地，安全地避免。 + + Theodore Ts'o + 31 Mar 94 + +给当前的Linux 2.1.55添加魔术表。 + + Michael Chastain + <mailto:mec@shout.net> + 22 Sep 1997 + +现在应该最新的Linux 2.1.112.因为在特性冻结期间，不能在2.2.x前改变任何东西。这些条目被数域所排序。 + + Krzysztof G.Baranowski + <mailto: kgb@knm.org.pl> + 29 Jul 1998 + +更新魔术表到Linux 2.5.45。刚好越过特性冻结，但是有可能还会有一些新的魔术值在2.6.x之前融入到内核中。 + + Petr Baudis + <pasky@ucw.cz> + 03 Nov 2002 + +更新魔术表到Linux 2.5.74。 + + Fabian Frederick + <ffrederick@users.sourceforge.net> + 09 Jul 2003 + +魔术名 地址 结构 所在文件 +=========================================================================== +PG_MAGIC 'P' pg_{read,write}_hdr include/linux/pg.h +CMAGIC 0x0111 user include/linux/a.out.h +MKISS_DRIVER_MAGIC 0x04bf mkiss_channel drivers/net/mkiss.h +HDLC_MAGIC 0x239e n_hdlc drivers/char/n_hdlc.c +APM_BIOS_MAGIC 0x4101 apm_user arch/x86/kernel/apm_32.c +CYCLADES_MAGIC 0x4359 cyclades_port include/linux/cyclades.h +DB_MAGIC 0x4442 fc_info drivers/net/iph5526_novram.c +DL_MAGIC 0x444d fc_info drivers/net/iph5526_novram.c +FASYNC_MAGIC 0x4601 fasync_struct include/linux/fs.h +FF_MAGIC 0x4646 fc_info drivers/net/iph5526_novram.c +ISICOM_MAGIC 0x4d54 isi_port include/linux/isicom.h +PTY_MAGIC 0x5001 drivers/char/pty.c +PPP_MAGIC 0x5002 ppp include/linux/if_pppvar.h +SERIAL_MAGIC 0x5301 async_struct include/linux/serial.h +SSTATE_MAGIC 0x5302 serial_state include/linux/serial.h +SLIP_MAGIC 0x5302 slip drivers/net/slip.h +STRIP_MAGIC 0x5303 strip drivers/net/strip.c +X25_ASY_MAGIC 0x5303 x25_asy drivers/net/x25_asy.h +SIXPACK_MAGIC 0x5304 sixpack drivers/net/hamradio/6pack.h +AX25_MAGIC 0x5316 ax_disp drivers/net/mkiss.h +TTY_MAGIC 0x5401 tty_struct include/linux/tty.h +MGSL_MAGIC 0x5401 mgsl_info drivers/char/synclink.c +TTY_DRIVER_MAGIC 0x5402 tty_driver include/linux/tty_driver.h +MGSLPC_MAGIC 0x5402 mgslpc_info drivers/char/pcmcia/synclink_cs.c +TTY_LDISC_MAGIC 0x5403 tty_ldisc include/linux/tty_ldisc.h +USB_SERIAL_MAGIC 0x6702 usb_serial drivers/usb/serial/usb-serial.h +FULL_DUPLEX_MAGIC 0x6969 drivers/net/ethernet/dec/tulip/de2104x.c +USB_BLUETOOTH_MAGIC 0x6d02 usb_bluetooth drivers/usb/class/bluetty.c +RFCOMM_TTY_MAGIC 0x6d02 net/bluetooth/rfcomm/tty.c +USB_SERIAL_PORT_MAGIC 0x7301 usb_serial_port drivers/usb/serial/usb-serial.h +CG_MAGIC 0x00090255 ufs_cylinder_group include/linux/ufs_fs.h +RPORT_MAGIC 0x00525001 r_port drivers/char/rocket_int.h +LSEMAGIC 0x05091998 lse drivers/fc4/fc.c +GDTIOCTL_MAGIC 0x06030f07 gdth_iowr_str drivers/scsi/gdth_ioctl.h +RIEBL_MAGIC 0x09051990 drivers/net/atarilance.c +NBD_REQUEST_MAGIC 0x12560953 nbd_request include/linux/nbd.h +RED_MAGIC2 0x170fc2a5 (any) mm/slab.c +BAYCOM_MAGIC 0x19730510 baycom_state drivers/net/baycom_epp.c +ISDN_X25IFACE_MAGIC 0x1e75a2b9 isdn_x25iface_proto_data + drivers/isdn/isdn_x25iface.h +ECP_MAGIC 0x21504345 cdkecpsig include/linux/cdk.h +LSOMAGIC 0x27091997 lso drivers/fc4/fc.c +LSMAGIC 0x2a3b4d2a ls drivers/fc4/fc.c +WANPIPE_MAGIC 0x414C4453 sdla_{dump,exec} include/linux/wanpipe.h +CS_CARD_MAGIC 0x43525553 cs_card sound/oss/cs46xx.c +LABELCL_MAGIC 0x4857434c labelcl_info_s include/asm/ia64/sn/labelcl.h +ISDN_ASYNC_MAGIC 0x49344C01 modem_info include/linux/isdn.h +CTC_ASYNC_MAGIC 0x49344C01 ctc_tty_info drivers/s390/net/ctctty.c +ISDN_NET_MAGIC 0x49344C02 isdn_net_local_s drivers/isdn/i4l/isdn_net_lib.h +SAVEKMSG_MAGIC2 0x4B4D5347 savekmsg arch/*/amiga/config.c +CS_STATE_MAGIC 0x4c4f4749 cs_state sound/oss/cs46xx.c +SLAB_C_MAGIC 0x4f17a36d kmem_cache mm/slab.c +COW_MAGIC 0x4f4f4f4d cow_header_v1 arch/um/drivers/ubd_user.c +I810_CARD_MAGIC 0x5072696E i810_card sound/oss/i810_audio.c +TRIDENT_CARD_MAGIC 0x5072696E trident_card sound/oss/trident.c +ROUTER_MAGIC 0x524d4157 wan_device [in wanrouter.h pre 3.9] +SAVEKMSG_MAGIC1 0x53415645 savekmsg arch/*/amiga/config.c +GDA_MAGIC 0x58464552 gda arch/mips/include/asm/sn/gda.h +RED_MAGIC1 0x5a2cf071 (any) mm/slab.c +EEPROM_MAGIC_VALUE 0x5ab478d2 lanai_dev drivers/atm/lanai.c +HDLCDRV_MAGIC 0x5ac6e778 hdlcdrv_state include/linux/hdlcdrv.h +PCXX_MAGIC 0x5c6df104 channel drivers/char/pcxx.h +KV_MAGIC 0x5f4b565f kernel_vars_s arch/mips/include/asm/sn/klkernvars.h +I810_STATE_MAGIC 0x63657373 i810_state sound/oss/i810_audio.c +TRIDENT_STATE_MAGIC 0x63657373 trient_state sound/oss/trident.c +M3_CARD_MAGIC 0x646e6f50 m3_card sound/oss/maestro3.c +FW_HEADER_MAGIC 0x65726F66 fw_header drivers/atm/fore200e.h +SLOT_MAGIC 0x67267321 slot drivers/hotplug/cpqphp.h +SLOT_MAGIC 0x67267322 slot drivers/hotplug/acpiphp.h +LO_MAGIC 0x68797548 nbd_device include/linux/nbd.h +OPROFILE_MAGIC 0x6f70726f super_block drivers/oprofile/oprofilefs.h +M3_STATE_MAGIC 0x734d724d m3_state sound/oss/maestro3.c +VMALLOC_MAGIC 0x87654320 snd_alloc_track sound/core/memory.c +KMALLOC_MAGIC 0x87654321 snd_alloc_track sound/core/memory.c +PWC_MAGIC 0x89DC10AB pwc_device drivers/usb/media/pwc.h +NBD_REPLY_MAGIC 0x96744668 nbd_reply include/linux/nbd.h +ENI155_MAGIC 0xa54b872d midway_eprom drivers/atm/eni.h +CODA_MAGIC 0xC0DAC0DA coda_file_info include/linux/coda_fs_i.h +DPMEM_MAGIC 0xc0ffee11 gdt_pci_sram drivers/scsi/gdth.h +YAM_MAGIC 0xF10A7654 yam_port drivers/net/hamradio/yam.c +CCB_MAGIC 0xf2691ad2 ccb drivers/scsi/ncr53c8xx.c +QUEUE_MAGIC_FREE 0xf7e1c9a3 queue_entry drivers/scsi/arm/queue.c +QUEUE_MAGIC_USED 0xf7e1cc33 queue_entry drivers/scsi/arm/queue.c +HTB_CMAGIC 0xFEFAFEF1 htb_class net/sched/sch_htb.c +NMI_MAGIC 0x48414d4d455201 nmi_s arch/mips/include/asm/sn/nmi.h + +请注意，在声音记忆管理中仍然有一些特殊的为每个驱动定义的魔术值。查看include/sound/sndmagic.h来获取他们完整的列表信息。很多OSS声音驱动拥有自己从声卡PCI ID构建的魔术值-他们也没有被列在这里。 + +IrDA子系统也使用了大量的自己的魔术值，查看include/net/irda/irda.h来获取他们完整的信息。 + +HFS是另外一个比较大的使用魔术值的文件系统-你可以在fs/hfs/hfs.h中找到他们。 diff --git a/Documentation/translations/zh_CN/oops-tracing.txt b/Documentation/translations/zh_CN/oops-tracing.txt new file mode 100644 index 000000000..a893f04df --- /dev/null +++ b/Documentation/translations/zh_CN/oops-tracing.txt @@ -0,0 +1,212 @@ +Chinese translated version of Documentation/admin-guide/bug-hunting.rst + +If you have any comment or update to the content, please contact the +original document maintainer directly. However, if you have a problem +communicating in English you can also ask the Chinese maintainer for +help. Contact the Chinese maintainer if this translation is outdated +or if there is a problem with the translation. + +Chinese maintainer: Dave Young <hidave.darkstar@gmail.com> +--------------------------------------------------------------------- +Documentation/admin-guide/bug-hunting.rst 的中文翻译 + +如果想评论或更新本文的内容，请直接联系原文档的维护者。如果你使用英文 +交流有困难的话，也可以向中文版维护者求助。如果本翻译更新不及时或者翻 +译存在问题，请联系中文版维护者。 + +中文版维护者： 杨瑞 Dave Young <hidave.darkstar@gmail.com> +中文版翻译者： 杨瑞 Dave Young <hidave.darkstar@gmail.com> +中文版校译者： 李阳 Li Yang <leo@zh-kernel.org> + 王聪 Wang Cong <xiyou.wangcong@gmail.com> + +以下为正文 +--------------------------------------------------------------------- + +注意： ksymoops 在2.6中是没有用的。 请以原有格式使用Oops(来自dmesg，等等)。 +忽略任何这样那样关于“解码Oops”或者“通过ksymoops运行”的文档。 如果你贴出运行过 +ksymoops的来自2.6的Oops，人们只会让你重贴一次。 + +快速总结 +------------- + +发现Oops并发送给看似相关的内核领域的维护者。别太担心对不上号。如果你不确定就发给 +和你所做的事情相关的代码的负责人。 如果可重现试着描述怎样重构。 那甚至比oops更有 +价值。 + +如果你对于发送给谁一无所知， 发给linux-kernel@vger.kernel.org。感谢你帮助Linux +尽可能地稳定。 + +Oops在哪里? +---------------------- + +通常Oops文本由klogd从内核缓冲区里读取并传给syslogd，由syslogd写到syslog文件中， +典型地是/var/log/messages(依赖于/etc/syslog.conf)。有时klogd崩溃了,这种情况下你 +能够运行dmesg > file来从内核缓冲区中读取数据并保存下来。 否则你可以 +cat /proc/kmsg > file， 然而你必须介入中止传输， kmsg是一个“永不结束的文件”。如 +果机器崩溃坏到你不能输入命令或者磁盘不可用那么你有三种选择:- + +（1） 手抄屏幕上的文本待机器重启后再输入计算机。 麻烦但如果没有针对崩溃的准备， +这是仅有的选择。 另外，你可以用数码相机把屏幕拍下来-不太好，但比没有强。 如果信 +息滚动到了终端的上面，你会发现以高分辩率启动（比如，vga=791）会让你读到更多的文 +本。（注意：这需要vesafb，所以对‘早期’的oops没有帮助） + +（2）用串口终端启动（请参看Documentation/admin-guide/serial-console.rst），运行一个null +modem到另一台机器并用你喜欢的通讯工具获取输出。Minicom工作地很好。 + +（3）使用Kdump（请参看Documentation/kdump/kdump.txt）， +使用在Documentation/kdump/gdbmacros.txt中定义的dmesg gdb宏，从旧的内存中提取内核 +环形缓冲区。 + +完整信息 +---------------- + +注意：以下来自于Linus的邮件适用于2.4内核。 我因为历史原因保留了它，并且因为其中 +一些信息仍然适用。 特别注意的是，请忽略任何ksymoops的引用。 + +From: Linus Torvalds <torvalds@osdl.org> + +怎样跟踪Oops.. [原发到linux-kernel的一封邮件] + +主要的窍门是有五年和这些烦人的oops消息打交道的经验;-) + +实际上，你有办法使它更简单。我有两个不同的方法： + + gdb /usr/src/linux/vmlinux + gdb> disassemble <offending_function> + +那是发现问题的简单办法，至少如果bug报告做的好的情况下（象这个一样-运行ksymoops +得到oops发生的函数及函数内的偏移）。 + +哦，如果报告发生的内核以相同的编译器和相似的配置编译它会有帮助的。 + +另一件要做的事是反汇编bug报告的“Code”部分：ksymoops也会用正确的工具来做这件事， +但如果没有那些工具你可以写一个傻程序： + + char str[] = "\xXX\xXX\xXX..."; + main(){} + +并用gcc -g编译它然后执行“disassemble str”（XX部分是由Oops报告的值-你可以仅剪切 +粘贴并用“\x”替换空格-我就是这么做的，因为我懒得写程序自动做这一切）。 + +另外，你可以用scripts/decodecode这个shell脚本。它的使用方法是： +decodecode < oops.txt + +“Code”之后的十六进制字节可能（在某些架构上）有一些当前指令之前的指令字节以及 +当前和之后的指令字节 + +Code: f9 0f 8d f9 00 00 00 8d 42 0c e8 dd 26 11 c7 a1 60 ea 2b f9 8b 50 08 a1 +64 ea 2b f9 8d 34 82 8b 1e 85 db 74 6d 8b 15 60 ea 2b f9 <8b> 43 04 39 42 54 +7e 04 40 89 42 54 8b 43 04 3b 05 00 f6 52 c0 + +最后，如果你想知道代码来自哪里，你可以： + + cd /usr/src/linux + make fs/buffer.s # 或任何产生BUG的文件 + +然后你会比gdb反汇编更清楚的知道发生了什么。 + +现在，问题是把你所拥有的所有数据结合起来：C源码（关于它应该怎样的一般知识）， +汇编代码及其反汇编得到的代码（另外还有从“oops”消息得到的寄存器状态-对了解毁坏的 +指针有用，而且当你有了汇编代码你也能拿其它的寄存器和任何它们对应的C表达式做匹配 +）。 + +实际上，你仅需看看哪里不匹配（这个例子是“Code”反汇编和编译器生成的代码不匹配）。 +然后你须要找出为什么不匹配。通常很简单-你看到代码使用了空指针然后你看代码想知道 +空指针是怎么出现的，还有检查它是否合法.. + +现在，如果明白这是一项耗时的工作而且需要一丁点儿的专心，没错。这就是我为什么大多 +只是忽略那些没有符号表信息的崩溃报告的原因：简单的说太难查找了（我有一些 +程序用于在内核代码段中搜索特定的模式，而且有时我也已经能找出那些崩溃的地方，但是 +仅仅是找出正确的序列也确实需要相当扎实的内核知识） + +_有时_会发生这种情况，我仅看到崩溃中的反汇编代码序列， 然后我马上就明白问题出在 +哪里。这时我才意识到自己干这个工作已经太长时间了;-) + + Linus + + +--------------------------------------------------------------------------- +关于Oops跟踪的注解： + +为了帮助Linus和其它内核开发者，klogd纳入了大量的支持来处理保护错误。为了拥有对 +地址解析的完整支持至少应该使用1.3-pl3的sysklogd包。 + +当保护错误发生时，klogd守护进程自动把内核日志信息中的重要地址翻译成它们相应的符 +号。 + +klogd执行两种类型的地址解析。首先是静态翻译其次是动态翻译。静态翻译和ksymoops +一样使用System.map文件。为了做静态翻译klogd守护进程必须在初始化时能找到system +map文件。关于klogd怎样搜索map文件请参看klogd手册页。 + +动态地址翻译在使用内核可装载模块时很重要。 因为内核模块的内存是从内核动态内存池 +里分配的，所以不管是模块开始位置还是模块中函数和符号的位置都不是固定的。 + +内核支持允许程序决定装载哪些模块和它们在内存中位置的系统调用。使用这些系统调用 +klogd守护进程生成一张符号表用于调试发生在可装载模块中的保护错误。 + +至少klogd会提供产生保护错误的模块名。还可有额外的符号信息供可装载模块开发者选择 +以从模块中输出符号信息。 + +因为内核模块环境可能是动态的，所以必须有一种机制当模块环境发生改变时来通知klogd +守护进程。 有一些可用的命令行选项允许klogd向当前执行中的守护进程发送信号，告知符 +号信息应该被刷新了。 更多信息请参看klogd手册页。 + +sysklogd发布时包含一个补丁修改了modules-2.0.0包，无论何时一个模块装载或者卸载都 +会自动向klogd发送信号。打上这个补丁提供了必要的对调试发生于内核可装载模块的保护 +错误的无缝支持。 + +以下是被klogd处理过的发生在可装载模块中的一个保护错误例子： +--------------------------------------------------------------------------- +Aug 29 09:51:01 blizard kernel: Unable to handle kernel paging request at virtual address f15e97cc +Aug 29 09:51:01 blizard kernel: current->tss.cr3 = 0062d000, %cr3 = 0062d000 +Aug 29 09:51:01 blizard kernel: *pde = 00000000 +Aug 29 09:51:01 blizard kernel: Oops: 0002 +Aug 29 09:51:01 blizard kernel: CPU: 0 +Aug 29 09:51:01 blizard kernel: EIP: 0010:[oops:_oops+16/3868] +Aug 29 09:51:01 blizard kernel: EFLAGS: 00010212 +Aug 29 09:51:01 blizard kernel: eax: 315e97cc ebx: 003a6f80 ecx: 001be77b edx: 00237c0c +Aug 29 09:51:01 blizard kernel: esi: 00000000 edi: bffffdb3 ebp: 00589f90 esp: 00589f8c +Aug 29 09:51:01 blizard kernel: ds: 0018 es: 0018 fs: 002b gs: 002b ss: 0018 +Aug 29 09:51:01 blizard kernel: Process oops_test (pid: 3374, process nr: 21, stackpage=00589000) +Aug 29 09:51:01 blizard kernel: Stack: 315e97cc 00589f98 0100b0b4 bffffed4 0012e38e 00240c64 003a6f80 00000001 +Aug 29 09:51:01 blizard kernel: 00000000 00237810 bfffff00 0010a7fa 00000003 00000001 00000000 bfffff00 +Aug 29 09:51:01 blizard kernel: bffffdb3 bffffed4 ffffffda 0000002b 0007002b 0000002b 0000002b 00000036 +Aug 29 09:51:01 blizard kernel: Call Trace: [oops:_oops_ioctl+48/80] [_sys_ioctl+254/272] [_system_call+82/128] +Aug 29 09:51:01 blizard kernel: Code: c7 00 05 00 00 00 eb 08 90 90 90 90 90 90 90 90 89 ec 5d c3 +--------------------------------------------------------------------------- + +Dr. G.W. Wettstein Oncology Research Div. Computing Facility +Roger Maris Cancer Center INTERNET: greg@wind.rmcc.com +820 4th St. N. +Fargo, ND 58122 +Phone: 701-234-7556 + + +--------------------------------------------------------------------------- +受污染的内核 + +一些oops报告在程序记数器之后包含字符串'Tainted: '。这表明内核已经被一些东西给污 +染了。 该字符串之后紧跟着一系列的位置敏感的字符，每个代表一个特定的污染值。 + + 1：'G'如果所有装载的模块都有GPL或相容的许可证，'P'如果装载了任何的专有模块。 +没有模块MODULE_LICENSE或者带有insmod认为是与GPL不相容的的MODULE_LICENSE的模块被 +认定是专有的。 + + 2：'F'如果有任何通过“insmod -f”被强制装载的模块，' '如果所有模块都被正常装载。 + + 3：'S'如果oops发生在SMP内核中，运行于没有证明安全运行多处理器的硬件。 当前这种 +情况仅限于几种不支持SMP的速龙处理器。 + + 4：'R'如果模块通过“insmod -f”被强制装载，' '如果所有模块都被正常装载。 + + 5：'M'如果任何处理器报告了机器检查异常，' '如果没有发生机器检查异常。 + + 6：'B'如果页释放函数发现了一个错误的页引用或者一些非预期的页标志。 + + 7：'U'如果用户或者用户应用程序特别请求设置污染标志，否则' '。 + + 8：'D'如果内核刚刚死掉，比如有OOPS或者BUG。 + +使用'Tainted: '字符串的主要原因是要告诉内核调试者，这是否是一个干净的内核亦或发 +生了任何的不正常的事。污染是永久的：即使出错的模块已经被卸载了，污染值仍然存在， +以表明内核不再值得信任。 diff --git a/Documentation/translations/zh_CN/sparse.txt b/Documentation/translations/zh_CN/sparse.txt new file mode 100644 index 000000000..2f728962a --- /dev/null +++ b/Documentation/translations/zh_CN/sparse.txt @@ -0,0 +1,95 @@ +Chinese translated version of Documentation/dev-tools/sparse.rst + +If you have any comment or update to the content, please contact the +original document maintainer directly. However, if you have a problem +communicating in English you can also ask the Chinese maintainer for +help. Contact the Chinese maintainer if this translation is outdated +or if there is a problem with the translation. + +Chinese maintainer: Li Yang <leo@zh-kernel.org> +--------------------------------------------------------------------- +Documentation/dev-tools/sparse.rst 的中文翻译 + +如果想评论或更新本文的内容，请直接联系原文档的维护者。如果你使用英文 +交流有困难的话，也可以向中文版维护者求助。如果本翻译更新不及时或者翻 +译存在问题，请联系中文版维护者。 + +中文版维护者： 李阳 Li Yang <leo@zh-kernel.org> +中文版翻译者： 李阳 Li Yang <leo@zh-kernel.org> + + +以下为正文 +--------------------------------------------------------------------- + +Copyright 2004 Linus Torvalds +Copyright 2004 Pavel Machek <pavel@ucw.cz> +Copyright 2006 Bob Copeland <me@bobcopeland.com> + +使用 sparse 工具做类型检查 +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +"__bitwise" 是一种类型属性，所以你应该这样使用它： + + typedef int __bitwise pm_request_t; + + enum pm_request { + PM_SUSPEND = (__force pm_request_t) 1, + PM_RESUME = (__force pm_request_t) 2 + }; + +这样会使 PM_SUSPEND 和 PM_RESUME 成为位方式(bitwise)整数（使用"__force" +是因为 sparse 会抱怨改变位方式的类型转换，但是这里我们确实需要强制进行转 +换）。而且因为所有枚举值都使用了相同的类型，这里的"enum pm_request"也将 +会使用那个类型做为底层实现。 + +而且使用 gcc 编译的时候，所有的 __bitwise/__force 都会消失，最后在 gcc +看来它们只不过是普通的整数。 + +坦白来说，你并不需要使用枚举类型。上面那些实际都可以浓缩成一个特殊的"int +__bitwise"类型。 + +所以更简单的办法只要这样做： + + typedef int __bitwise pm_request_t; + + #define PM_SUSPEND ((__force pm_request_t) 1) + #define PM_RESUME ((__force pm_request_t) 2) + +现在你就有了严格的类型检查所需要的所有基础架构。 + +一个小提醒：常数整数"0"是特殊的。你可以直接把常数零当作位方式整数使用而 +不用担心 sparse 会抱怨。这是因为"bitwise"（恰如其名）是用来确保不同位方 +式类型不会被弄混（小尾模式，大尾模式，cpu尾模式，或者其他），对他们来说 +常数"0"确实是特殊的。 + +获取 sparse 工具 +~~~~~~~~~~~~~~~~ + +你可以从 Sparse 的主页获取最新的发布版本： + + http://www.kernel.org/pub/linux/kernel/people/josh/sparse/ + +或者，你也可以使用 git 克隆最新的 sparse 开发版本： + + git://git.kernel.org/pub/scm/linux/kernel/git/josh/sparse.git + +DaveJ 把每小时自动生成的 git 源码树 tar 包放在以下地址： + + http://www.codemonkey.org.uk/projects/git-snapshots/sparse/ + +一旦你下载了源码，只要以普通用户身份运行： + + make + make install + +它将会被自动安装到你的 ~/bin 目录下。 + +使用 sparse 工具 +~~~~~~~~~~~~~~~~ + +用"make C=1"命令来编译内核，会对所有重新编译的 C 文件使用 sparse 工具。 +或者使用"make C=2"命令，无论文件是否被重新编译都会对其使用 sparse 工具。 +如果你已经编译了内核，用后一种方式可以很快地检查整个源码树。 + +make 的可选变量 CHECKFLAGS 可以用来向 sparse 工具传递参数。编译系统会自 +动向 sparse 工具传递 -Wbitwise 参数。 diff --git a/Documentation/translations/zh_CN/stable_api_nonsense.txt b/Documentation/translations/zh_CN/stable_api_nonsense.txt new file mode 100644 index 000000000..a2b27fab3 --- /dev/null +++ b/Documentation/translations/zh_CN/stable_api_nonsense.txt @@ -0,0 +1,157 @@ +Chinese translated version of Documentation/process/stable-api-nonsense.rst + +If you have any comment or update to the content, please contact the +original document maintainer directly. However, if you have problem +communicating in English you can also ask the Chinese maintainer for help. +Contact the Chinese maintainer, if this translation is outdated or there +is problem with translation. + +Maintainer: Greg Kroah-Hartman <greg@kroah.com> +Chinese maintainer: TripleX Chung <zhongyu@18mail.cn> +--------------------------------------------------------------------- +Documentation/process/stable-api-nonsense.rst 的中文翻译 + +如果想评论或更新本文的内容，请直接联系原文档的维护者。如果你使用英文 +交流有困难的话，也可以向中文版维护者求助。如果本翻译更新不及时或者翻 +译存在问题，请联系中文版维护者。 + +英文版维护者： Greg Kroah-Hartman <greg@kroah.com> +中文版维护者： 钟宇 TripleX Chung <zhongyu@18mail.cn> +中文版翻译者： 钟宇 TripleX Chung <zhongyu@18mail.cn> +中文版校译者： 李阳 Li Yang <leoli@freescale.com> +以下为正文 +--------------------------------------------------------------------- + +写作本文档的目的，是为了解释为什么Linux既没有二进制内核接口，也没有稳定 +的内核接口。这里所说的内核接口，是指内核里的接口，而不是内核和用户空间 +的接口。内核到用户空间的接口，是提供给应用程序使用的系统调用，系统调用 +在历史上几乎没有过变化，将来也不会有变化。我有一些老应用程序是在0.9版本 +或者更早版本的内核上编译的，在使用2.6版本内核的Linux发布上依然用得很好 +。用户和应用程序作者可以将这个接口看成是稳定的。 + + +执行纲要 +-------- + +你也许以为自己想要稳定的内核接口，但是你不清楚你要的实际上不是它。你需 +要的其实是稳定的驱动程序，而你只有将驱动程序放到公版内核的源代码树里， +才有可能达到这个目的。而且这样做还有很多其它好处，正是因为这些好处使得 +Linux能成为强壮，稳定，成熟的操作系统，这也是你最开始选择Linux的原因。 + + +入门 +----- + +只有那些写驱动程序的“怪人”才会担心内核接口的改变，对广大用户来说，既 +看不到内核接口，也不需要去关心它。 + +首先，我不打算讨论关于任何非GPL许可的内核驱动的法律问题，这些非GPL许可 +的驱动程序包括不公开源代码，隐藏源代码，二进制或者是用源代码包装，或者 +是其它任何形式的不能以GPL许可公开源代码的驱动程序。如果有法律问题，请咨 +询律师，我只是一个程序员，所以我只打算探讨技术问题（不是小看法律问题， +法律问题很实际，并且需要一直关注）。 + +既然只谈技术问题，我们就有了下面两个主题：二进制内核接口和稳定的内核源 +代码接口。这两个问题是互相关联的，让我们先解决掉二进制接口的问题。 + + +二进制内核接口 +-------------- +假如我们有一个稳定的内核源代码接口，那么自然而然的，我们就拥有了稳定的 +二进制接口，是这样的吗？错。让我们看看关于Linux内核的几点事实： + - 取决于所用的C编译器的版本，不同的内核数据结构里的结构体的对齐方 +式会有差别，代码中不同函数的表现形式也不一样（函数是不是被inline编译取 +决于编译器行为）。不同的函数的表现形式并不重要，但是数据结构内部的对齐 +方式很关键。 + - 取决于内核的配置选项，不同的选项会让内核的很多东西发生改变： + - 同一个结构体可能包含不同的成员变量 + - 有的函数可能根本不会被实现（比如编译的时候没有选择SMP支持 +，一些锁函数就会被定义成空函数）。 + - 内核使用的内存会以不同的方式对齐，这取决于不同的内核配置选 +项。 + - Linux可以在很多的不同体系结构的处理器上运行。在某个体系结构上编 +译好的二进制驱动程序，不可能在另外一个体系结构上正确的运行。 + +对于一个特定的内核，满足这些条件并不难，使用同一个C编译器和同样的内核配 +置选项来编译驱动程序模块就可以了。这对于给一个特定Linux发布的特定版本提 +供驱动程序，是完全可以满足需求的。但是如果你要给不同发布的不同版本都发 +布一个驱动程序，就需要在每个发布上用不同的内核设置参数都编译一次内核， +这简直跟噩梦一样。而且还要注意到，每个Linux发布还提供不同的Linux内核， +这些内核都针对不同的硬件类型进行了优化（有很多种不同的处理器，还有不同 +的内核设置选项）。所以每发布一次驱动程序，都需要提供很多不同版本的内核 +模块。 + +相信我，如果你真的要采取这种发布方式，一定会慢慢疯掉，我很久以前就有过 +深刻的教训... + + +稳定的内核源代码接口 +-------------------- + +如果有人不将他的内核驱动程序，放入公版内核的源代码树，而又想让驱动程序 +一直保持在最新的内核中可用，那么这个话题将会变得没完没了。 + 内核开发是持续而且快节奏的，从来都不会慢下来。内核开发人员在当前接口中 +找到bug，或者找到更好的实现方式。一旦发现这些，他们就很快会去修改当前的 +接口。修改接口意味着，函数名可能会改变，结构体可能被扩充或者删减，函数 +的参数也可能发生改变。一旦接口被修改，内核中使用这些接口的地方需要同时 +修正，这样才能保证所有的东西继续工作。 + +举一个例子，内核的USB驱动程序接口在USB子系统的整个生命周期中，至少经历 +了三次重写。这些重写解决以下问题： + - 把数据流从同步模式改成非同步模式，这个改动减少了一些驱动程序的 +复杂度，提高了所有USB驱动程序的吞吐率，这样几乎所有的USB设备都能以最大 +速率工作了。 + - 修改了USB核心代码中为USB驱动分配数据包内存的方式，所有的驱动都 +需要提供更多的参数给USB核心，以修正了很多已经被记录在案的死锁。 + +这和一些封闭源代码的操作系统形成鲜明的对比，在那些操作系统上，不得不额 +外的维护旧的USB接口。这导致了一个可能性，新的开发者依然会不小心使用旧的 +接口，以不恰当的方式编写代码，进而影响到操作系统的稳定性。 + 在上面的例子中，所有的开发者都同意这些重要的改动，在这样的情况下修改代 +价很低。如果Linux保持一个稳定的内核源代码接口，那么就得创建一个新的接口 +；旧的，有问题的接口必须一直维护，给Linux USB开发者带来额外的工作。既然 +所有的Linux USB驱动的作者都是利用自己的时间工作，那么要求他们去做毫无意 +义的免费额外工作，是不可能的。 + 安全问题对Linux来说十分重要。一个安全问题被发现，就会在短时间内得到修 +正。在很多情况下，这将导致Linux内核中的一些接口被重写，以从根本上避免安 +全问题。一旦接口被重写，所有使用这些接口的驱动程序，必须同时得到修正， +以确定安全问题已经得到修复并且不可能在未来还有同样的安全问题。如果内核 +内部接口不允许改变，那么就不可能修复这样的安全问题，也不可能确认这样的 +安全问题以后不会发生。 +开发者一直在清理内核接口。如果一个接口没有人在使用了，它就会被删除。这 +样可以确保内核尽可能的小，而且所有潜在的接口都会得到尽可能完整的测试 +（没有人使用的接口是不可能得到良好的测试的）。 + + +要做什么 +------- + +如果你写了一个Linux内核驱动，但是它还不在Linux源代码树里，作为一个开发 +者，你应该怎么做？为每个发布的每个版本提供一个二进制驱动，那简直是一个 +噩梦，要跟上永远处于变化之中的内核接口，也是一件辛苦活。 +很简单，让你的驱动进入内核源代码树（要记得我们在谈论的是以GPL许可发行 +的驱动，如果你的代码不符合GPL，那么祝你好运，你只能自己解决这个问题了， +你这个吸血鬼<把Andrew和Linus对吸血鬼的定义链接到这里>）。当你的代码加入 +公版内核源代码树之后，如果一个内核接口改变，你的驱动会直接被修改接口的 +那个人修改。保证你的驱动永远都可以编译通过，并且一直工作，你几乎不需要 +做什么事情。 + +把驱动放到内核源代码树里会有很多的好处： + - 驱动的质量会提升，而维护成本（对原始作者来说）会下降。 + - 其他人会给驱动添加新特性。 + - 其他人会找到驱动中的bug并修复。 + - 其他人会在驱动中找到性能优化的机会。 + - 当外部的接口的改变需要修改驱动程序的时候，其他人会修改驱动程序 +。 + - 不需要联系任何发行商，这个驱动会自动的随着所有的Linux发布一起发 +布。 + +和别的操作系统相比，Linux为更多不同的设备提供现成的驱动，而且能在更多不 +同体系结构的处理器上支持这些设备。这个经过考验的开发模式，必然是错不了 +的 :) + +------------- +感谢 Randy Dunlap, Andrew Morton, David Brownell, Hanna Linder, +Robert Love, and Nishanth Aravamudan 对于本文档早期版本的评审和建议。 + +英文版维护者： Greg Kroah-Hartman <greg@kroah.com> diff --git a/Documentation/translations/zh_CN/stable_kernel_rules.txt b/Documentation/translations/zh_CN/stable_kernel_rules.txt new file mode 100644 index 000000000..db4ba5a0c --- /dev/null +++ b/Documentation/translations/zh_CN/stable_kernel_rules.txt @@ -0,0 +1,66 @@ +Chinese translated version of Documentation/process/stable-kernel-rules.rst + +If you have any comment or update to the content, please contact the +original document maintainer directly. However, if you have a problem +communicating in English you can also ask the Chinese maintainer for +help. Contact the Chinese maintainer if this translation is outdated +or if there is a problem with the translation. + +Chinese maintainer: TripleX Chung <triplex@zh-kernel.org> +--------------------------------------------------------------------- +Documentation/process/stable-kernel-rules.rst 的中文翻译 + +如果想评论或更新本文的内容，请直接联系原文档的维护者。如果你使用英文 +交流有困难的话，也可以向中文版维护者求助。如果本翻译更新不及时或者翻 +译存在问题，请联系中文版维护者。 + + +中文版维护者： 钟宇 TripleX Chung <triplex@zh-kernel.org> +中文版翻译者： 钟宇 TripleX Chung <triplex@zh-kernel.org> +中文版校译者： 李阳 Li Yang <leo@zh-kernel.org> + Kangkai Yin <e12051@motorola.com> + +以下为正文 +--------------------------------------------------------------------- + +关于Linux 2.6稳定版发布，所有你想知道的事情。 + +关于哪些类型的补丁可以被接收进入稳定版代码树，哪些不可以的规则： + + - 必须是显而易见的正确，并且经过测试的。 + - 连同上下文，不能大于100行。 + - 必须只修正一件事情。 + - 必须修正了一个给大家带来麻烦的真正的bug（不是“这也许是一个问题...” + 那样的东西）。 + - 必须修正带来如下后果的问题：编译错误（对被标记为CONFIG_BROKEN的例外）， + 内核崩溃，挂起，数据损坏，真正的安全问题，或者一些类似“哦，这不 + 好”的问题。简短的说，就是一些致命的问题。 + - 没有“理论上的竞争条件”，除非能给出竞争条件如何被利用的解释。 + - 不能存在任何的“琐碎的”修正（拼写修正，去掉多余空格之类的）。 + - 必须被相关子系统的维护者接受。 + - 必须遵循Documentation/process/submitting-patches.rst里的规则。 + +向稳定版代码树提交补丁的过程： + + - 在确认了补丁符合以上的规则后，将补丁发送到stable@vger.kernel.org。 + - 如果补丁被接受到队列里，发送者会收到一个ACK回复，如果没有被接受，收 + 到的是NAK回复。回复需要几天的时间，这取决于开发者的时间安排。 + - 被接受的补丁会被加到稳定版本队列里，等待其他开发者的审查。 + - 安全方面的补丁不要发到这个列表，应该发送到security@kernel.org。 + +审查周期： + + - 当稳定版的维护者决定开始一个审查周期，补丁将被发送到审查委员会，以 + 及被补丁影响的领域的维护者（除非提交者就是该领域的维护者）并且抄送 + 到linux-kernel邮件列表。 + - 审查委员会有48小时的时间，用来决定给该补丁回复ACK还是NAK。 + - 如果委员会中有成员拒绝这个补丁，或者linux-kernel列表上有人反对这个 + 补丁，并提出维护者和审查委员会之前没有意识到的问题，补丁会从队列中 + 丢弃。 + - 在审查周期结束的时候，那些得到ACK回应的补丁将会被加入到最新的稳定版 + 发布中，一个新的稳定版发布就此产生。 + - 安全性补丁将从内核安全小组那里直接接收到稳定版代码树中，而不是通过 + 通常的审查周期。请联系内核安全小组以获得关于这个过程的更多细节。 + +审查委员会： + - 由一些自愿承担这项任务的内核开发者，和几个非志愿的组成。 diff --git a/Documentation/translations/zh_CN/video4linux/omap3isp.txt b/Documentation/translations/zh_CN/video4linux/omap3isp.txt new file mode 100644 index 000000000..e9f29375a --- /dev/null +++ b/Documentation/translations/zh_CN/video4linux/omap3isp.txt @@ -0,0 +1,277 @@ +Chinese translated version of Documentation/media/v4l-drivers/omap3isp.rst + +If you have any comment or update to the content, please contact the +original document maintainer directly. However, if you have a problem +communicating in English you can also ask the Chinese maintainer for +help. Contact the Chinese maintainer if this translation is outdated +or if there is a problem with the translation. + +Maintainer: Laurent Pinchart <laurent.pinchart@ideasonboard.com> + Sakari Ailus <sakari.ailus@iki.fi> + David Cohen <dacohen@gmail.com> +Chinese maintainer: Fu Wei <tekkamanninja@gmail.com> +--------------------------------------------------------------------- +Documentation/media/v4l-drivers/omap3isp.rst 的中文翻译 + +如果想评论或更新本文的内容，请直接联系原文档的维护者。如果你使用英文 +交流有困难的话，也可以向中文版维护者求助。如果本翻译更新不及时或者翻 +译存在问题，请联系中文版维护者。 +英文版维护者： Laurent Pinchart <laurent.pinchart@ideasonboard.com> + Sakari Ailus <sakari.ailus@iki.fi> + David Cohen <dacohen@gmail.com> +中文版维护者： 傅炜 Fu Wei <tekkamanninja@gmail.com> +中文版翻译者： 傅炜 Fu Wei <tekkamanninja@gmail.com> +中文版校译者： 傅炜 Fu Wei <tekkamanninja@gmail.com> + + +以下为正文 +--------------------------------------------------------------------- +OMAP 3 图像信号处理器 (ISP) 驱动 + +Copyright (C) 2010 Nokia Corporation +Copyright (C) 2009 Texas Instruments, Inc. + +联系人: Laurent Pinchart <laurent.pinchart@ideasonboard.com> + Sakari Ailus <sakari.ailus@iki.fi> + David Cohen <dacohen@gmail.com> + + +介绍 +=== + +本文档介绍了由 drivers/media/video/omap3isp 加载的德州仪器 +（TI）OMAP 3 图像信号处理器 (ISP) 驱动。原始驱动由德州仪器（TI） +编写，但此后由诺基亚重写了两次。 + +驱动已在以下 OMAP 3 系列的芯片中成功使用： + + 3430 + 3530 + 3630 + +驱动实现了 V4L2、媒体控制器和 v4l2_subdev 接口。支持内核中使用 +v4l2_subdev 接口的传感器、镜头和闪光灯驱动。 + + +拆分为子设备 +========== + +OMAP 3 ISP 被拆分为 V4L2 子设备，ISP中的每个模块都由一个子设备 +来表示。每个子设备向用户空间提供一个 V4L2 子设备接口。 + + OMAP3 ISP CCP2 + OMAP3 ISP CSI2a + OMAP3 ISP CCDC + OMAP3 ISP preview + OMAP3 ISP resizer + OMAP3 ISP AEWB + OMAP3 ISP AF + OMAP3 ISP histogram + +ISP 中每个可能的连接都通过一个链接嵌入到媒体控制器接口中。详见例程 [2]。 + + +控制 OMAP 3 ISP +============== + +通常，对 OMAP 3 ISP 的配置会在下一帧起始时生效。在传感器垂直消隐期间， +模块变为空闲时完成配置。在内存到内存的操作中，视频管道一次处理一帧。 +应用配置应在帧间完成。 + +ISP 中的所有模块，除 CSI-2 和 （可能存在的）CCP2 接收器外，都必须 +接收完整的帧数据。因此，传感器必须保证从不发送部分帧数据给ISP。 + +Autoidle（自动空闲）功能至少在 3430 的 ISP 模块中确实存在一些问题。 +当 omap3isp 模块参数 autoidle 非零时，autoidle（自动空闲）功能 +仅在 3630 中启用了。 + + +事件机制 +====== + +OMAP 3 ISP 驱动在 CCDC 和统计（AEWB、AF 和 直方图）子设备中支持 +V4L2 事件机制接口。 + +CCDC 子设备通过 HS_VS 中断，处理 V4L2_EVENT_FRAME_SYNC 类型 +事件，用于告知帧起始。早期版本的驱动则使用 V4L2_EVENT_OMAP3ISP_HS_VS。 +当在 CCDC 模块中接收到起始帧的第一行时，会准确地触发事件。这个事件 +可以在 CCDC 子设备中“订阅”。 + +（当使用并行接口时，必须注意正确地配置 VS 信号极性。而当使用串行接收时 +这个会自动校正。） + +每个统计子设备都可以产生事件。每当一个统计缓冲区可由用户空间应用程序 +通过 VIDIOC_OMAP3ISP_STAT_REQ IOCTL 操作获取时，就会产生一个 +事件。当前存在以下事件： + + V4L2_EVENT_OMAP3ISP_AEWB + V4L2_EVENT_OMAP3ISP_AF + V4L2_EVENT_OMAP3ISP_HIST + +这些 ioctl 的事件数据类型为 struct omap3isp_stat_event_status +结构体。如果出现计算错误的统计，也同样会产生一个事件，但没有相关的统计 +数据缓冲区。这种情况下 omap3isp_stat_event_status.buf_err 会被 +设置为非零值。 + + +私有 IOCTL +========== + +OMAP 3 ISP 驱动支持标准的 V4L2 IOCTL 以及可能存在且实用的控制。但 +ISP 提供的许多功能都不在标准 IOCTL 之列，例如 gamma（伽马）表和统计 +数据采集配置等。 + +通常，会有一个私有 ioctl 用于配置每个包含硬件依赖功能的模块。 + +支持以下私有 IOCTL： + + VIDIOC_OMAP3ISP_CCDC_CFG + VIDIOC_OMAP3ISP_PRV_CFG + VIDIOC_OMAP3ISP_AEWB_CFG + VIDIOC_OMAP3ISP_HIST_CFG + VIDIOC_OMAP3ISP_AF_CFG + VIDIOC_OMAP3ISP_STAT_REQ + VIDIOC_OMAP3ISP_STAT_EN + +在 include/linux/omap3isp.h 中描述了这些 ioctl 使用的参数结构体。 +与特定 ISP 模块相关的 ISP 自身的详细功能在技术参考手册 (TRMs)中有 +描述，详见文档结尾。 + +虽然在不使用任何私有 IOCTL 的情况下使用 ISP 驱动是可能的，但这样无法 +获得最佳的图像质量。AEWB、AF 和 直方图（译者注：一般用于自动曝光和增益 +控制，以及图像均衡等）模块无法在未使用适当的私有 IOCTL 配置的情况下使用。 + + +CCDC 和 preview（预览）模块 IOCTL +=============================== + +VIDIOC_OMAP3ISP_CCDC_CFG 和 VIDIOC_OMAP3ISP_PRV_CFG IOCTL +被分别用于配置、启用和禁用 CCDC 和 preview（预览）模块的功能。在它们 +所控制的模块中，两个 IOCTL 控制多种功能。VIDIOC_OMAP3ISP_CCDC_CFG IOCTL +接受一个指向 omap3isp_ccdc_update_config 结构体的指针作为它的参数。 +同样的，VIDIOC_OMAP3ISP_PRV_CFG 接受一个指向 omap3isp_prev_update_config +结构体的指针。以上两个结构体定义位于 [1]。 + +这些结构体中的 update 域标识是否针对指定的功能更新配置，而 flag 域 +则标识是启用还是禁用此功能。 + +update 和 flag 位接受以下掩码值。CCDC 和 preview（预览）模块的 +每个单独功能都与一个 flag 关联（禁用或启用；在结构体中 flag 域的 +一部分）和一个指向功能配置数据的指针。 + +对于 VIDIOC_OMAP3ISP_CCDC_CFG，下面列出了 update 和 flag 域 +中的有效值。 这些值可能会在同一个 IOCTL 调用中配置多个功能。 + + OMAP3ISP_CCDC_ALAW + OMAP3ISP_CCDC_LPF + OMAP3ISP_CCDC_BLCLAMP + OMAP3ISP_CCDC_BCOMP + OMAP3ISP_CCDC_FPC + OMAP3ISP_CCDC_CULL + OMAP3ISP_CCDC_CONFIG_LSC + OMAP3ISP_CCDC_TBL_LSC + +针对 VIDIOC_OMAP3ISP_PRV_CFG 的相应值如下： + + OMAP3ISP_PREV_LUMAENH + OMAP3ISP_PREV_INVALAW + OMAP3ISP_PREV_HRZ_MED + OMAP3ISP_PREV_CFA + OMAP3ISP_PREV_CHROMA_SUPP + OMAP3ISP_PREV_WB + OMAP3ISP_PREV_BLKADJ + OMAP3ISP_PREV_RGB2RGB + OMAP3ISP_PREV_COLOR_CONV + OMAP3ISP_PREV_YC_LIMIT + OMAP3ISP_PREV_DEFECT_COR + OMAP3ISP_PREV_GAMMABYPASS + OMAP3ISP_PREV_DRK_FRM_CAPTURE + OMAP3ISP_PREV_DRK_FRM_SUBTRACT + OMAP3ISP_PREV_LENS_SHADING + OMAP3ISP_PREV_NF + OMAP3ISP_PREV_GAMMA + +在启用某个功能的时候，相关的配置数据指针不可为 NULL。在禁用某个功能时， +配置数据指针会被忽略。 + + +统计模块 IOCTL +============= + +统计子设备相较于其他子设备提供了更多动态配置选项。在图像处理流水线处于 +工作状态时，它们可以被启用、禁用和重配。 + +统计模块总是从 CCDC 中获取输入的图像数据（由于直方图内存读取未实现）。 +统计数据可由用户通过统计子设备节点使用私有 IOCTL 获取。 + +AEWB、AF 和 直方图子设备提供的私有 IOCTL 极大程度上反应了 ISP 硬件 +提供的寄存器级接口。有些方面纯粹和驱动程序的实现相关，这些将在下面讨论。 + +VIDIOC_OMAP3ISP_STAT_EN +----------------------- + +这个私有 IOCTL 启用/禁用 一个统计模块。如果这个申请在视频流启动前完成， +它将在视频流水线开始工作时生效。如果视频流水线已经处于工作状态了，它将在 +CCDC 变为空闲时生效。 + +VIDIOC_OMAP3ISP_AEWB_CFG, VIDIOC_OMAP3ISP_HIST_CFG and VIDIOC_OMAP3ISP_AF_CFG +----------------------------------------------------------------------------- + +这些 IOCTL 用于配置模块。它们要求用户应用程序对硬件有深入的认识。对 +大多数域的解释可以在 OMAP 的 TRM 中找到。以下两个域对于以上所有的 +私有 IOCTL 配置都很常见，由于他们没有在 TRM 中提及，故需要对其有 +更好的认识。 + +omap3isp_[h3a_af/h3a_aewb/hist]_config.buf_size: + +模块在内部处理自身缓冲。对模块数据输出所必需的缓存大小依赖于已申请的配置。 +虽然驱动支持在视频流工作时重新配置，但对于所需缓存量大于模块启用时内部 +所分配数量的情况，则不支持重新配置。在这种情况下将返回 -EBUSY。为了避免 +此类状况，无论是禁用/重配/启用模块，还是第一次配置时申请必须的缓存大小， +都应在模块禁用的情况下进行。 + +内部缓冲分配的大小需综合考虑所申请配置的最小缓存量以及 buf_size 域中 +所设的值。如果 buf_size 域在[minimum（最小值）, maximum（最大值）] +缓冲大小范围之外，则应该将其调整到其范围中。驱动则会选择最大值。正确的 +buf_size 值将回写到用户应用程序中。 + +omap3isp_[h3a_af/h3a_aewb/hist]_config.config_counter: + +由于配置并未在申请之后同步生效，驱动必须提供一个跟踪这类信息的方法， +以提供更准确的数据。在一个配置被申请之后，返回到用户空间应用程序的 +config_counter 是一个与其配置相关的唯一值。当用户应用程序接收到 +一个缓冲可用或一个新的缓冲申请事件时，这个 config_counter 用于 +一个缓冲数据和一个配置的匹配。 + +VIDIOC_OMAP3ISP_STAT_REQ +------------------------ + +将内部缓冲队列中最早的数据发送到用户空间，然后丢弃此缓冲区。 +omap3isp_stat_data.frame_number 域与视频缓冲的 field_count +域相匹配。 + + +技术参考手册 (TRMs) 和其他文档 +========================== + +OMAP 3430 TRM: +<URL:http://focus.ti.com/pdfs/wtbu/OMAP34xx_ES3.1.x_PUBLIC_TRM_vZM.zip> +参考于 2011-03-05. + +OMAP 35xx TRM: +<URL:http://www.ti.com/litv/pdf/spruf98o> 参考于 2011-03-05. + +OMAP 3630 TRM: +<URL:http://focus.ti.com/pdfs/wtbu/OMAP36xx_ES1.x_PUBLIC_TRM_vQ.zip> +参考于 2011-03-05. + +DM 3730 TRM: +<URL:http://www.ti.com/litv/pdf/sprugn4h> 参考于 2011-03-06. + + +参考资料 +======= + +[1] include/linux/omap3isp.h + +[2] http://git.ideasonboard.org/?p=media-ctl.git;a=summary diff --git a/Documentation/translations/zh_CN/video4linux/v4l2-framework.txt b/Documentation/translations/zh_CN/video4linux/v4l2-framework.txt new file mode 100644 index 000000000..66c7c568b --- /dev/null +++ b/Documentation/translations/zh_CN/video4linux/v4l2-framework.txt @@ -0,0 +1,976 @@ +Chinese translated version of Documentation/media/media_kapi.rst + +If you have any comment or update to the content, please contact the +original document maintainer directly. However, if you have a problem +communicating in English you can also ask the Chinese maintainer for +help. Contact the Chinese maintainer if this translation is outdated +or if there is a problem with the translation. + +Maintainer: Mauro Carvalho Chehab <mchehab@kernel.org> +Chinese maintainer: Fu Wei <tekkamanninja@gmail.com> +--------------------------------------------------------------------- +Documentation/media/media_kapi.rst 的中文翻译 + +如果想评论或更新本文的内容，请直接联系原文档的维护者。如果你使用英文 +交流有困难的话，也可以向中文版维护者求助。如果本翻译更新不及时或者翻 +译存在问题，请联系中文版维护者。 +英文版维护者： Mauro Carvalho Chehab <mchehab@kernel.org> +中文版维护者： 傅炜 Fu Wei <tekkamanninja@gmail.com> +中文版翻译者： 傅炜 Fu Wei <tekkamanninja@gmail.com> +中文版校译者： 傅炜 Fu Wei <tekkamanninja@gmail.com> + + +以下为正文 +--------------------------------------------------------------------- +V4L2 驱动框架概览 +============== + +本文档描述 V4L2 框架所提供的各种结构和它们之间的关系。 + + +介绍 +---- + +大部分现代 V4L2 设备由多个 IC 组成，在 /dev 下导出多个设备节点， +并同时创建非 V4L2 设备（如 DVB、ALSA、FB、I2C 和红外输入设备）。 +由于这种硬件的复杂性，V4L2 驱动也变得非常复杂。 + +尤其是 V4L2 必须支持 IC 实现音视频的多路复用和编解码，这就更增加了其 +复杂性。通常这些 IC 通过一个或多个 I2C 总线连接到主桥驱动器，但也可 +使用其他总线。这些设备称为“子设备”。 + +长期以来，这个框架仅限于通过 video_device 结构体创建 V4L 设备节点， +并使用 video_buf 处理视频缓冲（注：本文不讨论 video_buf 框架）。 + +这意味着所有驱动必须自己设置设备实例并连接到子设备。其中一部分要正确地 +完成是比较复杂的，使得许多驱动都没有正确地实现。 + +由于框架的缺失，有很多通用代码都不可重复利用。 + +因此，这个框架构建所有驱动都需要的基本结构块，而统一的框架将使通用代码 +创建成实用函数并在所有驱动中共享变得更加容易。 + + +驱动结构 +------- + +所有 V4L2 驱动都有如下结构： + +1) 每个设备实例的结构体--包含其设备状态。 + +2) 初始化和控制子设备的方法（如果有）。 + +3) 创建 V4L2 设备节点 (/dev/videoX、/dev/vbiX 和 /dev/radioX) + 并跟踪设备节点的特定数据。 + +4) 特定文件句柄结构体--包含每个文件句柄的数据。 + +5) 视频缓冲处理。 + +以下是它们的初略关系图： + + device instances（设备实例） + | + +-sub-device instances（子设备实例） + | + \-V4L2 device nodes（V4L2 设备节点） + | + \-filehandle instances（文件句柄实例） + + +框架结构 +------- + +该框架非常类似驱动结构：它有一个 v4l2_device 结构用于保存设备 +实例的数据；一个 v4l2_subdev 结构体代表子设备实例；video_device +结构体保存 V4L2 设备节点的数据；将来 v4l2_fh 结构体将跟踪文件句柄 +实例（暂未尚未实现）。 + +V4L2 框架也可与媒体框架整合（可选的）。如果驱动设置了 v4l2_device +结构体的 mdev 域，子设备和视频节点的入口将自动出现在媒体框架中。 + + +v4l2_device 结构体 +---------------- + +每个设备实例都通过 v4l2_device (v4l2-device.h)结构体来表示。 +简单设备可以仅分配这个结构体，但在大多数情况下，都会将这个结构体 +嵌入到一个更大的结构体中。 + +你必须注册这个设备实例： + + v4l2_device_register(struct device *dev, struct v4l2_device *v4l2_dev); + +注册操作将会初始化 v4l2_device 结构体。如果 dev->driver_data 域 +为 NULL，就将其指向 v4l2_dev。 + +需要与媒体框架整合的驱动必须手动设置 dev->driver_data，指向包含 +v4l2_device 结构体实例的驱动特定设备结构体。这可以在注册 V4L2 设备 +实例前通过 dev_set_drvdata() 函数完成。同时必须设置 v4l2_device +结构体的 mdev 域，指向适当的初始化并注册过的 media_device 实例。 + +如果 v4l2_dev->name 为空，则它将被设置为从 dev 中衍生出的值（为了 +更加精确，形式为驱动名后跟 bus_id）。如果你在调用 v4l2_device_register +前已经设置好了，则不会被修改。如果 dev 为 NULL，则你*必须*在调用 +v4l2_device_register 前设置 v4l2_dev->name。 + +你可以基于驱动名和驱动的全局 atomic_t 类型的实例编号，通过 +v4l2_device_set_name() 设置 name。这样会生成类似 ivtv0、ivtv1 等 +名字。若驱动名以数字结尾，则会在编号和驱动名间插入一个破折号，如： +cx18-0、cx18-1 等。此函数返回实例编号。 + +第一个 “dev” 参数通常是一个指向 pci_dev、usb_interface 或 +platform_device 的指针。很少使其为 NULL，除非是一个ISA设备或者 +当一个设备创建了多个 PCI 设备，使得 v4l2_dev 无法与一个特定的父设备 +关联。 + +你也可以提供一个 notify() 回调，使子设备可以调用它实现事件通知。 +但这个设置与子设备相关。子设备支持的任何通知必须在 +include/media/<subdevice>.h 中定义一个消息头。 + +注销 v4l2_device 使用如下函数： + + v4l2_device_unregister(struct v4l2_device *v4l2_dev); + +如果 dev->driver_data 域指向 v4l2_dev，将会被重置为 NULL。注销同时 +会自动从设备中注销所有子设备。 + +如果你有一个热插拔设备（如USB设备），则当断开发生时，父设备将无效。 +由于 v4l2_device 有一个指向父设备的指针必须被清除，同时标志父设备 +已消失，所以必须调用以下函数： + + v4l2_device_disconnect(struct v4l2_device *v4l2_dev); + +这个函数并*不*注销子设备，因此你依然要调用 v4l2_device_unregister() +函数。如果你的驱动器并非热插拔的，就没有必要调用 v4l2_device_disconnect()。 + +有时你需要遍历所有被特定驱动注册的设备。这通常发生在多个设备驱动使用 +同一个硬件的情况下。如：ivtvfb 驱动是一个使用 ivtv 硬件的帧缓冲驱动， +同时 alsa 驱动也使用此硬件。 + +你可以使用如下例程遍历所有注册的设备： + +static int callback(struct device *dev, void *p) +{ + struct v4l2_device *v4l2_dev = dev_get_drvdata(dev); + + /* 测试这个设备是否已经初始化 */ + if (v4l2_dev == NULL) + return 0; + ... + return 0; +} + +int iterate(void *p) +{ + struct device_driver *drv; + int err; + + /* 在PCI 总线上查找ivtv驱动。 + pci_bus_type是全局的. 对于USB总线使用usb_bus_type。 */ + drv = driver_find("ivtv", &pci_bus_type); + /* 遍历所有的ivtv设备实例 */ + err = driver_for_each_device(drv, NULL, p, callback); + put_driver(drv); + return err; +} + +有时你需要一个设备实例的运行计数。这个通常用于映射一个设备实例到一个 +模块选择数组的索引。 + +推荐方法如下： + +static atomic_t drv_instance = ATOMIC_INIT(0); + +static int drv_probe(struct pci_dev *pdev, const struct pci_device_id *pci_id) +{ + ... + state->instance = atomic_inc_return(&drv_instance) - 1; +} + +如果你有多个设备节点，对于热插拔设备，知道何时注销 v4l2_device 结构体 +就比较困难。为此 v4l2_device 有引用计数支持。当调用 video_register_device +时增加引用计数，而设备节点释放时减小引用计数。当引用计数为零，则 +v4l2_device 的release() 回调将被执行。你就可以在此时做最后的清理工作。 + +如果创建了其他设备节点（比如 ALSA），则你可以通过以下函数手动增减 +引用计数： + +void v4l2_device_get(struct v4l2_device *v4l2_dev); + +或: + +int v4l2_device_put(struct v4l2_device *v4l2_dev); + +由于引用技术初始化为 1 ，你也需要在 disconnect() 回调（对于 USB 设备）中 +调用 v4l2_device_put，或者 remove() 回调（例如对于 PCI 设备），否则 +引用计数将永远不会为 0 。 + +v4l2_subdev结构体 +------------------ + +许多驱动需要与子设备通信。这些设备可以完成各种任务，但通常他们负责 +音视频复用和编解码。如网络摄像头的子设备通常是传感器和摄像头控制器。 + +这些一般为 I2C 接口设备，但并不一定都是。为了给驱动提供调用子设备的 +统一接口，v4l2_subdev 结构体（v4l2-subdev.h）产生了。 + +每个子设备驱动都必须有一个 v4l2_subdev 结构体。这个结构体可以单独 +代表一个简单的子设备，也可以嵌入到一个更大的结构体中，与更多设备状态 +信息保存在一起。通常有一个下级设备结构体（比如：i2c_client）包含了 +内核创建的设备数据。建议使用 v4l2_set_subdevdata() 将这个结构体的 +指针保存在 v4l2_subdev 的私有数据域(dev_priv)中。这使得通过 v4l2_subdev +找到实际的低层总线特定设备数据变得容易。 + +你同时需要一个从低层结构体获取 v4l2_subdev 指针的方法。对于常用的 +i2c_client 结构体，i2c_set_clientdata() 函数可用于保存一个 v4l2_subdev +指针；对于其他总线你可能需要使用其他相关函数。 + +桥驱动中也应保存每个子设备的私有数据，比如一个指向特定桥的各设备私有 +数据的指针。为此 v4l2_subdev 结构体提供主机私有数据域(host_priv)， +并可通过 v4l2_get_subdev_hostdata() 和 v4l2_set_subdev_hostdata() +访问。 + +从总线桥驱动的视角，驱动加载子设备模块并以某种方式获得 v4l2_subdev +结构体指针。对于 i2c 总线设备相对简单：调用 i2c_get_clientdata()。 +对于其他总线也需要做类似的操作。针对 I2C 总线上的子设备辅助函数帮你 +完成了大部分复杂的工作。 + +每个 v4l2_subdev 都包含子设备驱动需要实现的函数指针（如果对此设备 +不适用，可为NULL）。由于子设备可完成许多不同的工作，而在一个庞大的 +函数指针结构体中通常仅有少数有用的函数实现其功能肯定不合适。所以， +函数指针根据其实现的功能被分类，每一类都有自己的函数指针结构体。 + +顶层函数指针结构体包含了指向各类函数指针结构体的指针，如果子设备驱动 +不支持该类函数中的任何一个功能，则指向该类结构体的指针为NULL。 + +这些结构体定义如下： + +struct v4l2_subdev_core_ops { + int (*log_status)(struct v4l2_subdev *sd); + int (*init)(struct v4l2_subdev *sd, u32 val); + ... +}; + +struct v4l2_subdev_tuner_ops { + ... +}; + +struct v4l2_subdev_audio_ops { + ... +}; + +struct v4l2_subdev_video_ops { + ... +}; + +struct v4l2_subdev_pad_ops { + ... +}; + +struct v4l2_subdev_ops { + const struct v4l2_subdev_core_ops *core; + const struct v4l2_subdev_tuner_ops *tuner; + const struct v4l2_subdev_audio_ops *audio; + const struct v4l2_subdev_video_ops *video; + const struct v4l2_subdev_pad_ops *video; +}; + +其中 core（核心）函数集通常可用于所有子设备，其他类别的实现依赖于 +子设备。如视频设备可能不支持音频操作函数，反之亦然。 + +这样的设置在限制了函数指针数量的同时，还使增加新的操作函数和分类 +变得较为容易。 + +子设备驱动可使用如下函数初始化 v4l2_subdev 结构体： + + v4l2_subdev_init(sd, &ops); + +然后，你必须用一个唯一的名字初始化 subdev->name，并初始化模块的 +owner 域。若使用 i2c 辅助函数，这些都会帮你处理好。 + +若需同媒体框架整合，你必须调用 media_entity_pads_init() 初始化 v4l2_subdev +结构体中的 media_entity 结构体（entity 域）： + + struct media_pad *pads = &my_sd->pads; + int err; + + err = media_entity_pads_init(&sd->entity, npads, pads); + +pads 数组必须预先初始化。无须手动设置 media_entity 的 type 和 +name 域，但如有必要，revision 域必须初始化。 + +当（任何）子设备节点被打开/关闭，对 entity 的引用将被自动获取/释放。 + +在子设备被注销之后，不要忘记清理 media_entity 结构体： + + media_entity_cleanup(&sd->entity); + +如果子设备驱动趋向于处理视频并整合进了媒体框架，必须使用 v4l2_subdev_pad_ops +替代 v4l2_subdev_video_ops 实现格式相关的功能。 + +这种情况下，子设备驱动应该设置 link_validate 域，以提供它自身的链接 +验证函数。链接验证函数应对管道（两端链接的都是 V4L2 子设备）中的每个 +链接调用。驱动还要负责验证子设备和视频节点间格式配置的正确性。 + +如果 link_validate 操作没有设置，默认的 v4l2_subdev_link_validate_default() +函数将会被调用。这个函数保证宽、高和媒体总线像素格式在链接的收发两端 +都一致。子设备驱动除了它们自己的检测外，也可以自由使用这个函数以执行 +上面提到的检查。 + +设备（桥）驱动程序必须向 v4l2_device 注册 v4l2_subdev： + + int err = v4l2_device_register_subdev(v4l2_dev, sd); + +如果子设备模块在它注册前消失，这个操作可能失败。在这个函数成功返回后， +subdev->dev 域就指向了 v4l2_device。 + +如果 v4l2_device 父设备的 mdev 域为非 NULL 值，则子设备实体将被自动 +注册为媒体设备。 + +注销子设备则可用如下函数： + + v4l2_device_unregister_subdev(sd); + +此后，子设备模块就可卸载，且 sd->dev == NULL。 + +注册之设备后，可通过以下方式直接调用其操作函数： + + err = sd->ops->core->g_std(sd, &norm); + +但使用如下宏会比较容易且合适： + + err = v4l2_subdev_call(sd, core, g_std, &norm); + +这个宏将会做 NULL 指针检查，如果 subdev 为 NULL，则返回-ENODEV；如果 +subdev->core 或 subdev->core->g_std 为 NULL，则返回 -ENOIOCTLCMD； +否则将返回 subdev->ops->core->g_std ops 调用的实际结果。 + +有时也可能同时调用所有或一系列子设备的某个操作函数： + + v4l2_device_call_all(v4l2_dev, 0, core, g_std, &norm); + +任何不支持此操作的子设备都会被跳过，并忽略错误返回值。但如果你需要 +检查出错码，则可使用如下函数： + + err = v4l2_device_call_until_err(v4l2_dev, 0, core, g_std, &norm); + +除 -ENOIOCTLCMD 外的任何错误都会跳出循环并返回错误值。如果（除 -ENOIOCTLCMD +外）没有错误发生，则返回 0。 + +对于以上两个函数的第二个参数为组 ID。如果为 0，则所有子设备都会执行 +这个操作。如果为非 0 值，则只有那些组 ID 匹配的子设备才会执行此操作。 +在桥驱动注册一个子设备前，可以设置 sd->grp_id 为任何期望值（默认值为 +0）。这个值属于桥驱动，且子设备驱动将不会修改和使用它。 + +组 ID 赋予了桥驱动更多对于如何调用回调的控制。例如，电路板上有多个 +音频芯片，每个都有改变音量的能力。但当用户想要改变音量的时候，通常 +只有一个会被实际使用。你可以对这样的子设备设置组 ID 为（例如 AUDIO_CONTROLLER） +并在调用 v4l2_device_call_all() 时指定它为组 ID 值。这就保证了只有 +需要的子设备才会执行这个回调。 + +如果子设备需要通知它的 v4l2_device 父设备一个事件，可以调用 +v4l2_subdev_notify(sd, notification, arg)。这个宏检查是否有一个 +notify() 回调被注册，如果没有，返回 -ENODEV。否则返回 notify() 调用 +结果。 + +使用 v4l2_subdev 的好处在于它是一个通用结构体，且不包含任何底层硬件 +信息。所有驱动可以包含多个 I2C 总线的子设备，但也有子设备是通过 GPIO +控制。这个区别仅在配置设备时有关系，一旦子设备注册完成，对于 v4l2 +子系统来说就完全透明了。 + + +V4L2 子设备用户空间API +-------------------- + +除了通过 v4l2_subdev_ops 结构导出的内核 API，V4L2 子设备也可以直接 +通过用户空间应用程序来控制。 + +可以在 /dev 中创建名为 v4l-subdevX 设备节点，以通过其直接访问子设备。 +如果子设备支持用户空间直接配置，必须在注册前设置 V4L2_SUBDEV_FL_HAS_DEVNODE +标志。 + +注册子设备之后， v4l2_device 驱动会通过调用 v4l2_device_register_subdev_nodes() +函数为所有已注册并设置了 V4L2_SUBDEV_FL_HAS_DEVNODE 的子设备创建 +设备节点。这些设备节点会在子设备注销时自动删除。 + +这些设备节点处理 V4L2 API 的一个子集。 + +VIDIOC_QUERYCTRL +VIDIOC_QUERYMENU +VIDIOC_G_CTRL +VIDIOC_S_CTRL +VIDIOC_G_EXT_CTRLS +VIDIOC_S_EXT_CTRLS +VIDIOC_TRY_EXT_CTRLS + + 这些 ioctls 控制与 V4L2 中定义的一致。他们行为相同，唯一的 + 不同是他们只处理子设备的控制实现。根据驱动程序，这些控制也 + 可以通过一个（或多个） V4L2 设备节点访问。 + +VIDIOC_DQEVENT +VIDIOC_SUBSCRIBE_EVENT +VIDIOC_UNSUBSCRIBE_EVENT + + 这些 ioctls 事件与 V4L2 中定义的一致。他们行为相同，唯一的 + 不同是他们只处理子设备产生的事件。根据驱动程序，这些事件也 + 可以通过一个（或多个） V4L2 设备节点上报。 + + 要使用事件通知的子设备驱动，在注册子设备前必须在 v4l2_subdev::flags + 中设置 V4L2_SUBDEV_USES_EVENTS 并在 v4l2_subdev::nevents + 中初始化事件队列深度。注册完成后，事件会在 v4l2_subdev::devnode + 设备节点中像通常一样被排队。 + + 为正确支持事件机制，poll() 文件操作也应被实现。 + +私有 ioctls + + 不在以上列表中的所有 ioctls 会通过 core::ioctl 操作直接传递 + 给子设备驱动。 + + +I2C 子设备驱动 +------------- + +由于这些驱动很常见，所以内特提供了特定的辅助函数(v4l2-common.h)让这些 +设备的使用更加容易。 + +添加 v4l2_subdev 支持的推荐方法是让 I2C 驱动将 v4l2_subdev 结构体 +嵌入到为每个 I2C 设备实例创建的状态结构体中。而最简单的设备没有状态 +结构体，此时可以直接创建一个 v4l2_subdev 结构体。 + +一个典型的状态结构体如下所示（‘chipname’用芯片名代替）： + +struct chipname_state { + struct v4l2_subdev sd; + ... /* 附加的状态域*/ +}; + +初始化 v4l2_subdev 结构体的方法如下： + + v4l2_i2c_subdev_init(&state->sd, client, subdev_ops); + +这个函数将填充 v4l2_subdev 结构体中的所有域，并保证 v4l2_subdev 和 +i2c_client 都指向彼此。 + +同时，你也应该为从 v4l2_subdev 指针找到 chipname_state 结构体指针 +添加一个辅助内联函数。 + +static inline struct chipname_state *to_state(struct v4l2_subdev *sd) +{ + return container_of(sd, struct chipname_state, sd); +} + +使用以下函数可以通过 v4l2_subdev 结构体指针获得 i2c_client 结构体 +指针： + + struct i2c_client *client = v4l2_get_subdevdata(sd); + +而以下函数则相反，通过 i2c_client 结构体指针获得 v4l2_subdev 结构体 +指针： + + struct v4l2_subdev *sd = i2c_get_clientdata(client); + +当 remove()函数被调用前，必须保证先调用 v4l2_device_unregister_subdev(sd)。 +此操作将会从桥驱动中注销子设备。即使子设备没有注册，调用此函数也是 +安全的。 + +必须这样做的原因是：当桥驱动注销 i2c 适配器时，remove()回调函数 +会被那个适配器上的 i2c 设备调用。此后，相应的 v4l2_subdev 结构体 +就不存在了，所有它们必须先被注销。在 remove()回调函数中调用 +v4l2_device_unregister_subdev(sd)，可以保证执行总是正确的。 + + +桥驱动也有一些辅组函数可用： + +struct v4l2_subdev *sd = v4l2_i2c_new_subdev(v4l2_dev, adapter, + "module_foo", "chipid", 0x36, NULL); + +这个函数会加载给定的模块（如果没有模块需要加载，可以为 NULL）， +并用给定的 i2c 适配器结构体指针（i2c_adapter）和 器件地址（chip/address） +作为参数调用 i2c_new_device()。如果一切顺利，则就在 v4l2_device +中注册了子设备。 + +你也可以利用 v4l2_i2c_new_subdev()的最后一个参数，传递一个可能的 +I2C 地址数组，让函数自动探测。这些探测地址只有在前一个参数为 0 的 +情况下使用。非零参数意味着你知道准确的 i2c 地址，所以此时无须进行 +探测。 + +如果出错，两个函数都返回 NULL。 + +注意：传递给 v4l2_i2c_new_subdev()的 chipid 通常与模块名一致。 +它允许你指定一个芯片的变体，比如“saa7114”或“saa7115”。一般通过 +i2c 驱动自动探测。chipid 的使用是在今后需要深入了解的事情。这个与 +i2c 驱动不同，较容易混淆。要知道支持哪些芯片变体，你可以查阅 i2c +驱动代码的 i2c_device_id 表，上面列出了所有可能支持的芯片。 + +还有两个辅助函数： + +v4l2_i2c_new_subdev_cfg：这个函数添加新的 irq 和 platform_data +参数，并有‘addr’和‘probed_addrs’参数：如果 addr 非零，则被使用 +（不探测变体），否则 probed_addrs 中的地址将用于自动探测。 + +例如：以下代码将会探测地址（0x10）： + +struct v4l2_subdev *sd = v4l2_i2c_new_subdev_cfg(v4l2_dev, adapter, + "module_foo", "chipid", 0, NULL, 0, I2C_ADDRS(0x10)); + +v4l2_i2c_new_subdev_board 使用一个 i2c_board_info 结构体，将其 +替代 irq、platform_data 和 add r参数传递给 i2c 驱动。 + +如果子设备支持 s_config 核心操作，这个操作会在子设备配置好之后以 irq 和 +platform_data 为参数调用。早期的 v4l2_i2c_new_(probed_)subdev 函数 +同样也会调用 s_config，但仅在 irq 为 0 且 platform_data 为 NULL 时。 + +video_device结构体 +----------------- + +在 /dev 目录下的实际设备节点根据 video_device 结构体(v4l2-dev.h) +创建。此结构体既可以动态分配也可以嵌入到一个更大的结构体中。 + +动态分配方法如下： + + struct video_device *vdev = video_device_alloc(); + + if (vdev == NULL) + return -ENOMEM; + + vdev->release = video_device_release; + +如果将其嵌入到一个大结构体中，则必须自己实现 release()回调。 + + struct video_device *vdev = &my_vdev->vdev; + + vdev->release = my_vdev_release; + +release()回调必须被设置，且在最后一个 video_device 用户退出之后 +被调用。 + +默认的 video_device_release()回调只是调用 kfree 来释放之前分配的 +内存。 + +你应该设置这些域： + +- v4l2_dev: 设置为 v4l2_device 父设备。 + +- name: 设置为唯一的描述性设备名。 + +- fops: 设置为已有的 v4l2_file_operations 结构体。 + +- ioctl_ops: 如果你使用v4l2_ioctl_ops 来简化 ioctl 的维护 + (强烈建议使用，且将来可能变为强制性的!)，然后设置你自己的 + v4l2_ioctl_ops 结构体. + +- lock: 如果你要在驱动中实现所有的锁操作，则设为 NULL 。否则 + 就要设置一个指向 struct mutex_lock 结构体的指针，这个锁将 + 在 unlocked_ioctl 文件操作被调用前由内核获得，并在调用返回后 + 释放。详见下一节。 + +- prio: 保持对优先级的跟踪。用于实现 VIDIOC_G/S_PRIORITY。如果 + 设置为 NULL，则会使用 v4l2_device 中的 v4l2_prio_state 结构体。 + 如果要对每个设备节点（组）实现独立的优先级，可以将其指向自己 + 实现的 v4l2_prio_state 结构体。 + +- parent: 仅在使用 NULL 作为父设备结构体参数注册 v4l2_device 时 + 设置此参数。只有在一个硬件设备包含多一个 PCI 设备，共享同一个 + v4l2_device 核心时才会发生。 + + cx88 驱动就是一个例子：一个 v4l2_device 结构体核心，被一个裸的 + 视频 PCI 设备(cx8800)和一个 MPEG PCI 设备(cx8802)共用。由于 + v4l2_device 无法与特定的 PCI 设备关联，所有没有设置父设备。但当 + video_device 配置后，就知道使用哪个父 PCI 设备了。 + +如果你使用 v4l2_ioctl_ops，则应该在 v4l2_file_operations 结构体中 +设置 .unlocked_ioctl 指向 video_ioctl2。 + +请勿使用 .ioctl！它已被废弃，今后将消失。 + +某些情况下你要告诉核心：你在 v4l2_ioctl_ops 指定的某个函数应被忽略。 +你可以在 video_device_register 被调用前通过以下函数标记这个 ioctls。 + +void v4l2_disable_ioctl(struct video_device *vdev, unsigned int cmd); + +基于外部因素（例如某个板卡已被使用），在不创建新结构体的情况下，你想 +要关闭 v4l2_ioctl_ops 中某个特性往往需要这个机制。 + +v4l2_file_operations 结构体是 file_operations 的一个子集。其主要 +区别在于：因 inode 参数从未被使用，它将被忽略。 + +如果需要与媒体框架整合，你必须通过调用 media_entity_pads_init() 初始化 +嵌入在 video_device 结构体中的 media_entity（entity 域）结构体： + + struct media_pad *pad = &my_vdev->pad; + int err; + + err = media_entity_pads_init(&vdev->entity, 1, pad); + +pads 数组必须预先初始化。没有必要手动设置 media_entity 的 type 和 +name 域。 + +当（任何）子设备节点被打开/关闭，对 entity 的引用将被自动获取/释放。 + +v4l2_file_operations 与锁 +-------------------------- + +你可以在 video_device 结构体中设置一个指向 mutex_lock 的指针。通常 +这既可是一个顶层互斥锁也可为设备节点自身的互斥锁。默认情况下，此锁 +用于 unlocked_ioctl，但为了使用 ioctls 你通过以下函数可禁用锁定： + + void v4l2_disable_ioctl_locking(struct video_device *vdev, unsigned int cmd); + +例如: v4l2_disable_ioctl_locking(vdev, VIDIOC_DQBUF); + +你必须在注册 video_device 前调用这个函数。 + +特别是对于 USB 驱动程序，某些命令（如设置控制）需要很长的时间，可能 +需要自行为缓冲区队列的 ioctls 实现锁定。 + +如果你需要更细粒度的锁，你必须设置 mutex_lock 为 NULL，并完全自己实现 +锁机制。 + +这完全由驱动开发者决定使用何种方法。然而，如果你的驱动存在长延时操作 +（例如，改变 USB 摄像头的曝光时间可能需要较长时间），而你又想让用户 +在等待长延时操作完成期间做其他的事，则你最好自己实现锁机制。 + +如果指定一个锁，则所有 ioctl 操作将在这个锁的作用下串行执行。如果你 +使用 videobuf，则必须将同一个锁传递给 videobuf 队列初始化函数；如 +videobuf 必须等待一帧的到达，则可临时解锁并在这之后重新上锁。如果驱动 +也在代码执行期间等待，则可做同样的工作（临时解锁，再上锁）让其他进程 +可以在第一个进程阻塞时访问设备节点。 + +在使用 videobuf2 的情况下，必须实现 wait_prepare 和 wait_finish 回调 +在适当的时候解锁/加锁。进一步来说，如果你在 video_device 结构体中使用 +锁，则必须在 wait_prepare 和 wait_finish 中对这个互斥锁进行解锁/加锁。 + +热插拔的断开实现也必须在调用 v4l2_device_disconnect 前获得锁。 + +video_device注册 +--------------- + +接下来你需要注册视频设备：这会为你创建一个字符设备。 + + err = video_register_device(vdev, VFL_TYPE_GRABBER, -1); + if (err) { + video_device_release(vdev); /* or kfree(my_vdev); */ + return err; + } + +如果 v4l2_device 父设备的 mdev 域为非 NULL 值，视频设备实体将自动 +注册为媒体设备。 + +注册哪种设备是根据类型（type）参数。存在以下类型： + +VFL_TYPE_GRABBER: 用于视频输入/输出设备的 videoX +VFL_TYPE_VBI: 用于垂直消隐数据的 vbiX (例如，隐藏式字幕，图文电视) +VFL_TYPE_RADIO: 用于广播调谐器的 radioX + +最后一个参数让你确定一个所控制设备的设备节点号数量(例如 videoX 中的 X)。 +通常你可以传入-1，让 v4l2 框架自己选择第一个空闲的编号。但是有时用户 +需要选择一个特定的节点号。驱动允许用户通过驱动模块参数选择一个特定的 +设备节点号是很普遍的。这个编号将会传递给这个函数，且 video_register_device +将会试图选择这个设备节点号。如果这个编号被占用，下一个空闲的设备节点 +编号将被选中，并向内核日志中发送一个警告信息。 + +另一个使用场景是当驱动创建多个设备时。这种情况下，对不同的视频设备在 +编号上使用不同的范围是很有用的。例如，视频捕获设备从 0 开始，视频 +输出设备从 16 开始。所以你可以使用最后一个参数来指定设备节点号最小值， +而 v4l2 框架会试图选择第一个的空闲编号（等于或大于你提供的编号）。 +如果失败，则它会就选择第一个空闲的编号。 + +由于这种情况下，你会忽略无法选择特定设备节点号的警告，则可调用 +video_register_device_no_warn() 函数避免警告信息的产生。 + +只要设备节点被创建，一些属性也会同时创建。在 /sys/class/video4linux +目录中你会找到这些设备。例如进入其中的 video0 目录，你会看到‘name’和 +‘index’属性。‘name’属性值就是 video_device 结构体中的‘name’域。 + +‘index’属性值就是设备节点的索引值：每次调用 video_register_device()， +索引值都递增 1 。第一个视频设备节点总是从索引值 0 开始。 + +用户可以设置 udev 规则，利用索引属性生成花哨的设备名（例如：用‘mpegX’ +代表 MPEG 视频捕获设备节点）。 + +在设备成功注册后，就可以使用这些域： + +- vfl_type: 传递给 video_register_device 的设备类型。 +- minor: 已指派的次设备号。 +- num: 设备节点编号 (例如 videoX 中的 X)。 +- index: 设备索引号。 + +如果注册失败，你必须调用 video_device_release() 来释放已分配的 +video_device 结构体；如果 video_device 是嵌入在自己创建的结构体中， +你也必须释放它。vdev->release() 回调不会在注册失败之后被调用， +你也不应试图在注册失败后注销设备。 + + +video_device 注销 +---------------- + +当视频设备节点已被移除，不论是卸载驱动还是USB设备断开，你都应注销 +它们： + + video_unregister_device(vdev); + +这个操作将从 sysfs 中移除设备节点（导致 udev 将其从 /dev 中移除）。 + +video_unregister_device() 返回之后，就无法完成打开操作。尽管如此， +USB 设备的情况则不同，某些应用程序可能依然打开着其中一个已注销设备 +节点。所以在注销之后，所有文件操作（当然除了 release ）也应返回错误值。 + +当最后一个视频设备节点的用户退出，则 vdev->release() 回调会被调用， +并且你可以做最后的清理操作。 + +不要忘记清理与视频设备相关的媒体入口（如果被初始化过）： + + media_entity_cleanup(&vdev->entity); + +这可以在 release 回调中完成。 + + +video_device 辅助函数 +--------------------- + +一些有用的辅助函数如下： + +- file/video_device 私有数据 + +你可以用以下函数在 video_device 结构体中设置/获取驱动私有数据： + +void *video_get_drvdata(struct video_device *vdev); +void video_set_drvdata(struct video_device *vdev, void *data); + +注意：在调用 video_register_device() 前执行 video_set_drvdata() +是安全的。 + +而以下函数： + +struct video_device *video_devdata(struct file *file); + +返回 file 结构体中拥有的的 video_device 指针。 + +video_drvdata 辅助函数结合了 video_get_drvdata 和 video_devdata +的功能： + +void *video_drvdata(struct file *file); + +你可以使用如下代码从 video_device 结构体中获取 v4l2_device 结构体 +指针： + +struct v4l2_device *v4l2_dev = vdev->v4l2_dev; + +- 设备节点名 + +video_device 设备节点在内核中的名称可以通过以下函数获得 + +const char *video_device_node_name(struct video_device *vdev); + +这个名字被用户空间工具（例如 udev）作为提示信息使用。应尽可能使用 +此功能，而非访问 video_device::num 和 video_device::minor 域。 + + +视频缓冲辅助函数 +--------------- + +v4l2 核心 API 提供了一个处理视频缓冲的标准方法(称为“videobuf”)。 +这些方法使驱动可以通过统一的方式实现 read()、mmap() 和 overlay()。 +目前在设备上支持视频缓冲的方法有分散/聚集 DMA(videobuf-dma-sg)、 +线性 DMA(videobuf-dma-contig)以及大多用于 USB 设备的用 vmalloc +分配的缓冲(videobuf-vmalloc)。 + +请参阅 Documentation/media/kapi/v4l2-videobuf.rst，以获得更多关于 videobuf +层的使用信息。 + +v4l2_fh 结构体 +------------- + +v4l2_fh 结构体提供一个保存用于 V4L2 框架的文件句柄特定数据的简单方法。 +如果 video_device 标志，新驱动 +必须使用 v4l2_fh 结构体，因为它也用于实现优先级处理（VIDIOC_G/S_PRIORITY）。 + +v4l2_fh 的用户（位于 V4l2 框架中，并非驱动）可通过测试 +video_device->flags 中的 V4L2_FL_USES_V4L2_FH 位得知驱动是否使用 +v4l2_fh 作为他的 file->private_data 指针。这个位会在调用 v4l2_fh_init() +时被设置。 + +v4l2_fh 结构体作为驱动自身文件句柄结构体的一部分被分配，且驱动在 +其打开函数中将 file->private_data 指向它。 + +在许多情况下，v4l2_fh 结构体会嵌入到一个更大的结构体中。这钟情况下， +应该在 open() 中调用 v4l2_fh_init+v4l2_fh_add，并在 release() 中 +调用 v4l2_fh_del+v4l2_fh_exit。 + +驱动可以通过使用 container_of 宏提取他们自己的文件句柄结构体。例如： + +struct my_fh { + int blah; + struct v4l2_fh fh; +}; + +... + +int my_open(struct file *file) +{ + struct my_fh *my_fh; + struct video_device *vfd; + int ret; + + ... + + my_fh = kzalloc(sizeof(*my_fh), GFP_KERNEL); + + ... + + v4l2_fh_init(&my_fh->fh, vfd); + + ... + + file->private_data = &my_fh->fh; + v4l2_fh_add(&my_fh->fh); + return 0; +} + +int my_release(struct file *file) +{ + struct v4l2_fh *fh = file->private_data; + struct my_fh *my_fh = container_of(fh, struct my_fh, fh); + + ... + v4l2_fh_del(&my_fh->fh); + v4l2_fh_exit(&my_fh->fh); + kfree(my_fh); + return 0; +} + +以下是 v4l2_fh 函数使用的简介： + +void v4l2_fh_init(struct v4l2_fh *fh, struct video_device *vdev) + + 初始化文件句柄。这*必须*在驱动的 v4l2_file_operations->open() + 函数中执行。 + +void v4l2_fh_add(struct v4l2_fh *fh) + + 添加一个 v4l2_fh 到 video_device 文件句柄列表。一旦文件句柄 + 初始化完成就必须调用。 + +void v4l2_fh_del(struct v4l2_fh *fh) + + 从 video_device() 中解除文件句柄的关联。文件句柄的退出函数也 + 将被调用。 + +void v4l2_fh_exit(struct v4l2_fh *fh) + + 清理文件句柄。在清理完 v4l2_fh 后，相关内存会被释放。 + + +如果 v4l2_fh 不是嵌入在其他结构体中的，则可以用这些辅助函数： + +int v4l2_fh_open(struct file *filp) + + 分配一个 v4l2_fh 结构体空间，初始化并将其添加到 file 结构体相关的 + video_device 结构体中。 + +int v4l2_fh_release(struct file *filp) + + 从 file 结构体相关的 video_device 结构体中删除 v4l2_fh ，清理 + v4l2_fh 并释放空间。 + +这两个函数可以插入到 v4l2_file_operation 的 open() 和 release() +操作中。 + + +某些驱动需要在第一个文件句柄打开和最后一个文件句柄关闭的时候做些 +工作。所以加入了两个辅助函数以检查 v4l2_fh 结构体是否是相关设备 +节点打开的唯一文件句柄。 + +int v4l2_fh_is_singular(struct v4l2_fh *fh) + + 如果此文件句柄是唯一打开的文件句柄，则返回 1 ，否则返回 0 。 + +int v4l2_fh_is_singular_file(struct file *filp) + + 功能相同，但通过 filp->private_data 调用 v4l2_fh_is_singular。 + + +V4L2 事件机制 +----------- + +V4L2 事件机制提供了一个通用的方法将事件传递到用户空间。驱动必须使用 +v4l2_fh 才能支持 V4L2 事件机制。 + + +事件通过一个类型和选择 ID 来定义。ID 对应一个 V4L2 对象，例如 +一个控制 ID。如果未使用，则 ID 为 0。 + +当用户订阅一个事件，驱动会为此分配一些 kevent 结构体。所以每个 +事件组（类型、ID）都会有自己的一套 kevent 结构体。这保证了如果 +一个驱动短时间内产生了许多同类事件，不会覆盖其他类型的事件。 + +但如果你收到的事件数量大于同类事件 kevent 的保存数量，则最早的 +事件将被丢弃，并加入新事件。 + +此外，v4l2_subscribed_event 结构体内部有可供驱动设置的 merge() 和 +replace() 回调，这些回调会在新事件产生且没有多余空间的时候被调用。 +replace() 回调让你可以将早期事件的净荷替换为新事件的净荷，将早期 +净荷的相关数据合并到替换进来的新净荷中。当该类型的事件仅分配了一个 +kevent 结构体时，它将被调用。merge() 回调让你可以合并最早的事件净荷 +到在它之后的那个事件净荷中。当该类型的事件分配了两个或更多 kevent +结构体时，它将被调用。 + +这种方法不会有状态信息丢失，只会导致中间步骤信息丢失。 + + +关于 replace/merge 回调的一个不错的例子在 v4l2-event.c 中：用于 +控制事件的 ctrls_replace() 和 ctrls_merge() 回调。 + +注意：这些回调可以在中断上下文中调用，所以它们必须尽快完成并退出。 + +有用的函数： + +void v4l2_event_queue(struct video_device *vdev, const struct v4l2_event *ev) + + 将事件加入视频设备的队列。驱动仅负责填充 type 和 data 域。 + 其他域由 V4L2 填充。 + +int v4l2_event_subscribe(struct v4l2_fh *fh, + struct v4l2_event_subscription *sub, unsigned elems, + const struct v4l2_subscribed_event_ops *ops) + + video_device->ioctl_ops->vidioc_subscribe_event 必须检测驱动能 + 产生特定 id 的事件。然后调用 v4l2_event_subscribe() 来订阅该事件。 + + elems 参数是该事件的队列大小。若为 0，V4L2 框架将会（根据事件类型） + 填充默认值。 + + ops 参数允许驱动指定一系列回调： + * add: 当添加一个新监听者时调用（重复订阅同一个事件，此回调 + 仅被执行一次）。 + * del: 当一个监听者停止监听时调用。 + * replace: 用‘新’事件替换‘早期‘事件。 + * merge: 将‘早期‘事件合并到‘新’事件中。 + 这四个调用都是可选的，如果不想指定任何回调，则 ops 可为 NULL。 + +int v4l2_event_unsubscribe(struct v4l2_fh *fh, + struct v4l2_event_subscription *sub) + + v4l2_ioctl_ops 结构体中的 vidioc_unsubscribe_event 回调函数。 + 驱动程序可以直接使用 v4l2_event_unsubscribe() 实现退订事件过程。 + + 特殊的 V4L2_EVENT_ALL 类型，可用于退订所有事件。驱动可能在特殊 + 情况下需要做此操作。 + +int v4l2_event_pending(struct v4l2_fh *fh) + + 返回未决事件的数量。有助于实现轮询（poll）操作。 + +事件通过 poll 系统调用传递到用户空间。驱动可用 +v4l2_fh->wait (wait_queue_head_t 类型)作为参数调用 poll_wait()。 + +事件分为标准事件和私有事件。新的标准事件必须使用可用的最小事件类型 +编号。驱动必须从他们本类型的编号起始处分配事件。类型的编号起始为 +V4L2_EVENT_PRIVATE_START + n * 1000 ，其中 n 为可用最小编号。每个 +类型中的第一个事件类型编号是为以后的使用保留的，所以第一个可用事件 +类型编号是‘class base + 1’。 + +V4L2 事件机制的使用实例可以在 OMAP3 ISP 的驱动 +(drivers/media/video/omap3isp)中找到。 diff --git a/Documentation/translations/zh_CN/volatile-considered-harmful.txt b/Documentation/translations/zh_CN/volatile-considered-harmful.txt new file mode 100644 index 000000000..475125967 --- /dev/null +++ b/Documentation/translations/zh_CN/volatile-considered-harmful.txt @@ -0,0 +1,113 @@ +Chinese translated version of Documentation/process/volatile-considered-harmful.rst + +If you have any comment or update to the content, please contact the +original document maintainer directly. However, if you have a problem +communicating in English you can also ask the Chinese maintainer for +help. Contact the Chinese maintainer if this translation is outdated +or if there is a problem with the translation. + +Maintainer: Jonathan Corbet <corbet@lwn.net> +Chinese maintainer: Bryan Wu <bryan.wu@analog.com> +--------------------------------------------------------------------- +Documentation/process/volatile-considered-harmful.rst 的中文翻译 + +如果想评论或更新本文的内容，请直接联系原文档的维护者。如果你使用英文 +交流有困难的话，也可以向中文版维护者求助。如果本翻译更新不及时或者翻 +译存在问题，请联系中文版维护者。 + +英文版维护者： Jonathan Corbet <corbet@lwn.net> +中文版维护者： 伍鹏 Bryan Wu <bryan.wu@analog.com> +中文版翻译者： 伍鹏 Bryan Wu <bryan.wu@analog.com> +中文版校译者： 张汉辉 Eugene Teo <eugeneteo@kernel.sg> + 杨瑞 Dave Young <hidave.darkstar@gmail.com> +以下为正文 +--------------------------------------------------------------------- + +为什么不应该使用“volatile”类型 +------------------------------ + +C程序员通常认为volatile表示某个变量可以在当前执行的线程之外被改变；因此，在内核 +中用到共享数据结构时，常常会有C程序员喜欢使用volatile这类变量。换句话说，他们经 +常会把volatile类型看成某种简易的原子变量，当然它们不是。在内核中使用volatile几 +乎总是错误的；本文档将解释为什么这样。 + +理解volatile的关键是知道它的目的是用来消除优化，实际上很少有人真正需要这样的应 +用。在内核中，程序员必须防止意外的并发访问破坏共享的数据结构，这其实是一个完全 +不同的任务。用来防止意外并发访问的保护措施，可以更加高效的避免大多数优化相关的 +问题。 + +像volatile一样，内核提供了很多原语来保证并发访问时的数据安全（自旋锁, 互斥量,内 +存屏障等等），同样可以防止意外的优化。如果可以正确使用这些内核原语，那么就没有 +必要再使用volatile。如果仍然必须使用volatile，那么几乎可以肯定在代码的某处有一 +个bug。在正确设计的内核代码中，volatile能带来的仅仅是使事情变慢。 + +思考一下这段典型的内核代码： + + spin_lock(&the_lock); + do_something_on(&shared_data); + do_something_else_with(&shared_data); + spin_unlock(&the_lock); + +如果所有的代码都遵循加锁规则，当持有the_lock的时候，不可能意外的改变shared_data的 +值。任何可能访问该数据的其他代码都会在这个锁上等待。自旋锁原语跟内存屏障一样—— 它 +们显式的用来书写成这样 —— 意味着数据访问不会跨越它们而被优化。所以本来编译器认为 +它知道在shared_data里面将有什么，但是因为spin_lock()调用跟内存屏障一样，会强制编 +译器忘记它所知道的一切。那么在访问这些数据时不会有优化的问题。 + +如果shared_data被声名为volatile，锁操作将仍然是必须的。就算我们知道没有其他人正在 +使用它，编译器也将被阻止优化对临界区内shared_data的访问。在锁有效的同时， +shared_data不是volatile的。在处理共享数据的时候，适当的锁操作可以不再需要 +volatile —— 并且是有潜在危害的。 + +volatile的存储类型最初是为那些内存映射的I/O寄存器而定义。在内核里，寄存器访问也应 +该被锁保护，但是人们也不希望编译器“优化”临界区内的寄存器访问。内核里I/O的内存访问 +是通过访问函数完成的；不赞成通过指针对I/O内存的直接访问，并且不是在所有体系架构上 +都能工作。那些访问函数正是为了防止意外优化而写的，因此，再说一次，volatile类型不 +是必需的。 + +另一种引起用户可能使用volatile的情况是当处理器正忙着等待一个变量的值。正确执行一 +个忙等待的方法是： + + while (my_variable != what_i_want) + cpu_relax(); + +cpu_relax()调用会降低CPU的能量消耗或者让位于超线程双处理器；它也作为内存屏障一样出 +现，所以，再一次，volatile不是必需的。当然，忙等待一开始就是一种反常规的做法。 + +在内核中，一些稀少的情况下volatile仍然是有意义的： + + - 在一些体系架构的系统上，允许直接的I/0内存访问，那么前面提到的访问函数可以使用 + volatile。基本上，每一个访问函数调用它自己都是一个小的临界区域并且保证了按照 + 程序员期望的那样发生访问操作。 + + - 某些会改变内存的内联汇编代码虽然没有什么其他明显的附作用，但是有被GCC删除的可 + 能性。在汇编声明中加上volatile关键字可以防止这种删除操作。 + + - Jiffies变量是一种特殊情况，虽然每次引用它的时候都可以有不同的值，但读jiffies + 变量时不需要任何特殊的加锁保护。所以jiffies变量可以使用volatile，但是不赞成 + 其他跟jiffies相同类型变量使用volatile。Jiffies被认为是一种“愚蠢的遗留物" + （Linus的话）因为解决这个问题比保持现状要麻烦的多。 + + - 由于某些I/0设备可能会修改连续一致的内存,所以有时,指向连续一致内存的数据结构 + 的指针需要正确的使用volatile。网络适配器使用的环状缓存区正是这类情形的一个例 + 子，其中适配器用改变指针来表示哪些描述符已经处理过了。 + +对于大多代码，上述几种可以使用volatile的情况都不适用。所以，使用volatile是一种 +bug并且需要对这样的代码额外仔细检查。那些试图使用volatile的开发人员需要退一步想想 +他们真正想实现的是什么。 + +非常欢迎删除volatile变量的补丁 － 只要证明这些补丁完整的考虑了并发问题。 + +注释 +---- + +[1] http://lwn.net/Articles/233481/ +[2] http://lwn.net/Articles/233482/ + +致谢 +---- + +最初由Randy Dunlap推动并作初步研究 +由Jonathan Corbet撰写 +参考Satyam Sharma，Johannes Stezenbach，Jesper Juhl，Heikki Orsila， +H. Peter Anvin，Philipp Hahn和Stefan Richter的意见改善了本档。 |