diff options
Diffstat (limited to 'Documentation/translations')
162 files changed, 12199 insertions, 2658 deletions
diff --git a/Documentation/translations/conf.py b/Documentation/translations/conf.py deleted file mode 100644 index 92cdbba74229..000000000000 --- a/Documentation/translations/conf.py +++ /dev/null @@ -1,12 +0,0 @@ -# -*- coding: utf-8 -*- -# SPDX-License-Identifier: GPL-2.0 - -# -- Additinal options for LaTeX output ---------------------------------- -# font config for ascii-art alignment - -latex_elements['preamble'] += ''' - \\IfFontExistsTF{Noto Sans CJK SC}{ - % For CJK ascii-art alignment - \\setmonofont{Noto Sans Mono CJK SC}[AutoFakeSlant] - }{} -''' diff --git a/Documentation/translations/it_IT/core-api/symbol-namespaces.rst b/Documentation/translations/it_IT/core-api/symbol-namespaces.rst index 42f5d04e38ec..0f6898860d6d 100644 --- a/Documentation/translations/it_IT/core-api/symbol-namespaces.rst +++ b/Documentation/translations/it_IT/core-api/symbol-namespaces.rst @@ -50,9 +50,9 @@ Di conseguenza, nella tabella dei simboli del kernel ci sarà una voce rappresentata dalla struttura ``kernel_symbol`` che avrà il campo ``namespace`` (spazio dei nomi) impostato. Un simbolo esportato senza uno spazio dei nomi avrà questo campo impostato a ``NULL``. Non esiste uno spazio dei nomi -di base. Il programma ``modpost`` e il codice in kernel/module.c usano lo spazio -dei nomi, rispettivamente, durante la compilazione e durante il caricamento -di un modulo. +di base. Il programma ``modpost`` e il codice in kernel/module/main.c usano lo +spazio dei nomi, rispettivamente, durante la compilazione e durante il +caricamento di un modulo. 2.2 Usare il simbolo di preprocessore DEFAULT_SYMBOL_NAMESPACE ============================================================== diff --git a/Documentation/translations/it_IT/devicetree/bindings/submitting-patches.rst b/Documentation/translations/it_IT/devicetree/bindings/submitting-patches.rst new file mode 100644 index 000000000000..b473cd2190be --- /dev/null +++ b/Documentation/translations/it_IT/devicetree/bindings/submitting-patches.rst @@ -0,0 +1,11 @@ +.. SPDX-License-Identifier: GPL-2.0 + +.. include:: ../../disclaimer-ita.rst + +:Original: Documentation/devicetree/bindings/submitting-patches.rst + +================================================ +Sottomettere patch per devicetree (DT) *binding* +================================================ + +.. note:: to be translated diff --git a/Documentation/translations/it_IT/doc-guide/kernel-doc.rst b/Documentation/translations/it_IT/doc-guide/kernel-doc.rst index 009cdac014b6..78082281acf9 100644 --- a/Documentation/translations/it_IT/doc-guide/kernel-doc.rst +++ b/Documentation/translations/it_IT/doc-guide/kernel-doc.rst @@ -5,6 +5,7 @@ .. _it_kernel_doc: +================================= Scrivere i commenti in kernel-doc ================================= @@ -469,6 +470,7 @@ 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 ======================================= diff --git a/Documentation/translations/it_IT/doc-guide/sphinx.rst b/Documentation/translations/it_IT/doc-guide/sphinx.rst index 9762452c584c..64528790dc34 100644 --- a/Documentation/translations/it_IT/doc-guide/sphinx.rst +++ b/Documentation/translations/it_IT/doc-guide/sphinx.rst @@ -5,8 +5,9 @@ .. _it_sphinxdoc: -Introduzione -============ +============================================= +Usare Sphinx per la documentazione del kernel +============================================= Il kernel Linux usa `Sphinx`_ per la generazione della documentazione a partire dai file `reStructuredText`_ che si trovano nella cartella ``Documentation``. @@ -158,6 +159,9 @@ 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 anche personalizzare l'ouptut html passando un livello aggiuntivo +DOCS_CSS usando la rispettiva variabile d'ambiente ``DOCS_CSS``. + Potete eliminare la documentazione generata tramite il comando ``make cleandocs``. @@ -276,11 +280,11 @@ incrociato quando questa ha una voce nell'indice. Se trovate degli usi di 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. +Il formato ``list-table`` può essere utile per tutte quelle tabelle che non +possono essere facilmente scritte usando il formato ASCII-art di Sphinx. Però, +questo genere di tabelle sono illeggibili per chi legge direttamente i file di +testo. Dunque, questo formato dovrebbe essere evitato senza forti argomenti che +ne giustifichino l'uso. La ``flat-table`` è anch'essa una lista di liste simile alle ``list-table`` ma con delle funzionalità aggiuntive: diff --git a/Documentation/translations/it_IT/kernel-hacking/hacking.rst b/Documentation/translations/it_IT/kernel-hacking/hacking.rst index d5c521327f6a..560f1d0482d2 100644 --- a/Documentation/translations/it_IT/kernel-hacking/hacking.rst +++ b/Documentation/translations/it_IT/kernel-hacking/hacking.rst @@ -129,8 +129,7 @@ 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. + con i 'processi' ('tasks'). Potete determinate se siete in un softirq (o tasklet) utilizzando la macro :c:func:`in_softirq()` (``include/linux/preempt.h``). @@ -308,7 +307,7 @@ esse copiano una quantità arbitraria di dati da e verso lo spazio utente. 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 +[Sì, questa interfaccia mi imbarazza. La battaglia torna in auge anno dopo anno. --RR] Le funzioni potrebbero dormire implicitamente. Queste non dovrebbero mai essere @@ -679,9 +678,8 @@ 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**. +più adatta; cercate negli archivi. Solitamente eseguire una semplice +sostituzione su tutto un file rendere le cose **peggiori**. Inizializzazione dei campi d'una struttura ------------------------------------------ @@ -759,14 +757,14 @@ 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 +- Trovare chi è responsabile del codice che state modificando. 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 è + tutti i file che create o che maneggiate significativamente. Questo è il primo posto dove le persone guarderanno quando troveranno un baco, o quando **loro** vorranno fare una modifica. @@ -787,16 +785,15 @@ anche per avere patch pulite, c'è del lavoro amministrativo da fare: "obj-$(CONFIG_xxx) += xxx.o". La sintassi è documentata nel file ``Documentation/kbuild/makefiles.rst``. -- 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 +- Aggiungete voi stessi in ``CREDITS`` se credete di aver 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. + 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``. + ``Documentation/process/submitting-patches.rst``. Trucchetti del kernel ===================== diff --git a/Documentation/translations/it_IT/kernel-hacking/locking.rst b/Documentation/translations/it_IT/kernel-hacking/locking.rst index 163f1bd4e857..51af37f2d621 100644 --- a/Documentation/translations/it_IT/kernel-hacking/locking.rst +++ b/Documentation/translations/it_IT/kernel-hacking/locking.rst @@ -102,16 +102,11 @@ 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**. +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 ------------------------------------------------------------ @@ -316,7 +311,7 @@ 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)``). + il mutex e dormire (``copy_from_user(`` o ``kmalloc(x,GFP_KERNEL)``). - Altrimenti (== i dati possono essere manipolati da un'interruzione) usate spin_lock_irqsave() e spin_unlock_irqrestore(). @@ -979,9 +974,6 @@ 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 -------------------------------------------------- diff --git a/Documentation/translations/it_IT/maintainer/configure-git.rst b/Documentation/translations/it_IT/maintainer/configure-git.rst new file mode 100644 index 000000000000..8316fa53946f --- /dev/null +++ b/Documentation/translations/it_IT/maintainer/configure-git.rst @@ -0,0 +1,10 @@ +.. include:: ../disclaimer-ita.rst + +:Original: Documentation/process/botching-up-ioctls.rst + +.. _it_configuregit: + +Configurare Git +=============== + +.. note:: To be translated diff --git a/Documentation/translations/it_IT/networking/netdev-FAQ.rst b/Documentation/translations/it_IT/networking/netdev-FAQ.rst index 7e2456bb7d92..8a1e049585c0 100644 --- a/Documentation/translations/it_IT/networking/netdev-FAQ.rst +++ b/Documentation/translations/it_IT/networking/netdev-FAQ.rst @@ -1,6 +1,6 @@ .. include:: ../disclaimer-ita.rst -:Original: :ref:`Documentation/networking/netdev-FAQ.rst <netdev-FAQ>` +:Original: :ref:`Documentation/process/maintainer-netdev.rst <netdev-FAQ>` .. _it_netdev-FAQ: diff --git a/Documentation/translations/it_IT/process/3.Early-stage.rst b/Documentation/translations/it_IT/process/3.Early-stage.rst index 443ac1e5558f..0809de39108a 100644 --- a/Documentation/translations/it_IT/process/3.Early-stage.rst +++ b/Documentation/translations/it_IT/process/3.Early-stage.rst @@ -168,14 +168,15 @@ in questa ricerca: .../scripts/get_maintainer.pl -Se questo script viene eseguito con l'opzione "-f" ritornerà il -manutentore(i) attuale per un dato file o cartella. Se viene passata una -patch sulla linea di comando, lo script elencherà i manutentori che -dovrebbero riceverne una copia. Ci sono svariate opzioni che regolano -quanto a fondo get_maintainer.pl debba cercare i manutentori; -siate quindi prudenti nell'utilizzare le opzioni più aggressive poiché -potreste finire per includere sviluppatori che non hanno un vero interesse -per il codice che state modificando. +Se questo script viene eseguito con l'opzione "-f" ritornerà il manutentore(i) +attuale per un dato file o cartella. Se viene passata una patch sulla linea di +comando, lo script elencherà i manutentori che dovrebbero riceverne una copia. +Questo è la maniera raccomandata (non quella con "-f") per ottenere la lista di +persone da aggiungere a Cc per le vostre patch. Ci sono svariate opzioni che +regolano quanto a fondo get_maintainer.pl debba cercare i manutentori; siate +quindi prudenti nell'utilizzare le opzioni più aggressive poiché potreste finire +per includere sviluppatori che non hanno un vero interesse per il codice che +state modificando. Se tutto ciò dovesse fallire, parlare con Andrew Morton potrebbe essere un modo efficace per capire chi è il manutentore di un dato pezzo di codice. diff --git a/Documentation/translations/it_IT/process/5.Posting.rst b/Documentation/translations/it_IT/process/5.Posting.rst index 1476d51eb5e5..cf92a16ed7e5 100644 --- a/Documentation/translations/it_IT/process/5.Posting.rst +++ b/Documentation/translations/it_IT/process/5.Posting.rst @@ -16,9 +16,8 @@ e di procedure per la pubblicazione delle patch; seguirle renderà la vita più facile a tutti quanti. Questo documento cercherà di coprire questi argomenti con un ragionevole livello di dettaglio; più informazioni possono essere trovare nella cartella 'Documentation', nei file -:ref:`translations/it_IT/process/submitting-patches.rst <it_submittingpatches>`, -:ref:`translations/it_IT/process/submitting-drivers.rst <it_submittingdrivers>`, e -:ref:`translations/it_IT/process/submit-checklist.rst <it_submitchecklist>`. +:ref:`translations/it_IT/process/submitting-patches.rst <it_submittingpatches>` +e :ref:`translations/it_IT/process/submit-checklist.rst <it_submitchecklist>`. Quando pubblicarle @@ -214,13 +213,28 @@ irrilevanti (quelli generati dal processo di generazione, per esempio, o i file di backup del vostro editor). Il file "dontdiff" nella cartella Documentation potrà esservi d'aiuto su questo punto; passatelo a diff con l'opzione "-X". -Le etichette sopra menzionante sono usate per descrivere come i vari -sviluppatori sono stati associati allo sviluppo di una patch. Sono descritte -in dettaglio nel documento :ref:`translations/it_IT/process/submitting-patches.rst <it_submittingpatches>`; -quello che segue è un breve riassunto. Ognuna di queste righe ha il seguente -formato: +Le etichette sopracitate danno un'idea di come una patch prende vita e sono +descritte nel dettaglio nel documento +:ref:`Documentation/translations/it_IT/process/submitting-patches.rst <it_submittingpatches>`. +Qui di seguito un breve riassunto. -:: +Un'etichetta ci può dire quale commit ha introdotto il problema che viene corretto nella patch:: + + Fixes: 1f2e3d4c5b6a ("The first line of the commit specified by the first 12 characters of its SHA-1 ID") + +Un'altra etichetta viene usata per fornire collegamenti a pagine web contenenti +maggiori informazioni, per esempio un rapporto circa il baco risolto dalla +patch, oppure un documento con le specifiche implementate dalla patch:: + + Link: https://example.com/somewhere.html optional-other-stuff + +Alcuni manutentori aggiungono quest'etichetta alla patch per fare riferimento +alla più recente discussione pubblica. A volte questo è fatto automaticamente da +alcuni strumenti come b4 or un *hook* git come quello descritto qui +'Documentation/translations/it_IT/maintainer/configure-git.rst' + +Un terzo tipo di etichetta viene usato per indicare chi ha contribuito allo +sviluppo della patch. Tutte queste etichette seguono il formato:: tag: Full Name <email address> optional-other-stuff diff --git a/Documentation/translations/it_IT/process/8.Conclusion.rst b/Documentation/translations/it_IT/process/8.Conclusion.rst index 039bfc5a4108..32659ff467c0 100644 --- a/Documentation/translations/it_IT/process/8.Conclusion.rst +++ b/Documentation/translations/it_IT/process/8.Conclusion.rst @@ -13,9 +13,8 @@ e argomenti correlati. Primo tra questi sarà sempre la cartella Documentation che si trova nei sorgenti kernel. Il file :ref:`process/howto.rst <it_process_howto>` è un punto di partenza -importante; :ref:`process/submitting-patches.rst <it_submittingpatches>` e -:ref:`process/submitting-drivers.rst <it_submittingdrivers>` sono -anch'essi qualcosa che tutti gli sviluppatori del kernel dovrebbero leggere. +importante; :ref:`process/submitting-patches.rst <it_submittingpatches>` è +anch'esso qualcosa che tutti gli sviluppatori del kernel dovrebbero leggere. Molte API interne al kernel sono documentate utilizzando il meccanismo kerneldoc; "make htmldocs" o "make pdfdocs" possono essere usati per generare quei documenti in HTML o PDF (sebbene le versioni di TeX di alcune diff --git a/Documentation/translations/it_IT/process/changes.rst b/Documentation/translations/it_IT/process/changes.rst index dc7193377b7f..10e0ef9c34b7 100644 --- a/Documentation/translations/it_IT/process/changes.rst +++ b/Documentation/translations/it_IT/process/changes.rst @@ -11,8 +11,8 @@ Requisiti minimi per compilare il kernel Introduzione ============ -Questo documento fornisce una lista dei software necessari per eseguire i -kernel 4.x. +Questo documento fornisce una lista dei software necessari per eseguire questa +versione del kernel. Questo documento è basato sul file "Changes" del kernel 2.0.x e quindi le persone che lo scrissero meritano credito (Jared Mauch, Axel Boldt, @@ -32,12 +32,13 @@ PC Card, per esempio, probabilmente non dovreste preoccuparvi di pcmciautils. ====================== ================= ======================================== Programma Versione minima Comando per verificare la versione ====================== ================= ======================================== -GNU C 4.9 gcc --version -Clang/LLVM (optional) 10.0.1 clang --version +GNU C 5.1 gcc --version +Clang/LLVM (optional) 11.0.0 clang --version GNU make 3.81 make --version binutils 2.23 ld -v flex 2.5.35 flex --version bison 2.0 bison --version +pahole 1.16 pahole --version util-linux 2.10o fdformat --version kmod 13 depmod -V e2fsprogs 1.41.4 e2fsck -V @@ -58,6 +59,7 @@ iptables 1.4.2 iptables -V openssl & libcrypto 1.0.0 openssl version bc 1.06.95 bc --version Sphinx\ [#f1]_ 1.7 sphinx-build --version +cpio any cpio --version ====================== ================= ======================================== .. [#f1] Sphinx è necessario solo per produrre la documentazione del Kernel @@ -111,6 +113,16 @@ Bison Dalla versione 4.16, il sistema di compilazione, durante l'esecuzione, genera un parsificatore. Questo richiede bison 2.0 o successivo. +pahole +------ + +Dalla versione 5.2, quando viene impostato CONFIG_DEBUG_INFO_BTF, il sistema di +compilazione genera BTF (BPF Type Format) a partire da DWARF per vmlinux. Più +tardi anche per i moduli. Questo richiede pahole v1.16 o successivo. + +A seconda della distribuzione, lo si può trovare nei pacchetti 'dwarves' o +'pahole'. Oppure lo si può trovare qui: https://fedorapeople.org/~acme/dwarves/. + Perl ---- @@ -455,6 +467,11 @@ mcelog - <http://www.mcelog.org/> +cpio +---- + +- <https://www.gnu.org/software/cpio/> + Rete **** diff --git a/Documentation/translations/it_IT/process/coding-style.rst b/Documentation/translations/it_IT/process/coding-style.rst index ecc74ba50d3e..a393ee4182af 100644 --- a/Documentation/translations/it_IT/process/coding-style.rst +++ b/Documentation/translations/it_IT/process/coding-style.rst @@ -466,14 +466,52 @@ la riga della parentesi graffa di chiusura. Ad esempio: } EXPORT_SYMBOL(system_is_up); +6.1) Prototipi di funzione +************************** + Nei prototipi di funzione, includete i nomi dei parametri e i loro tipi. Nonostante questo non sia richiesto dal linguaggio C, in Linux viene preferito perché è un modo semplice per aggiungere informazioni importanti per il lettore. -Non usate la parola chiave ``extern`` coi prototipi di funzione perché +Non usate la parola chiave ``extern`` con le dichiarazioni di funzione perché rende le righe più lunghe e non è strettamente necessario. +Quando scrivete i prototipi di funzione mantenete `l'ordine degli elementi <https://lore.kernel.org/mm-commits/CAHk-=wiOCLRny5aifWNhr621kYrJwhfURsa0vFPeUEm8mF0ufg@mail.gmail.com/>`_. + +Prendiamo questa dichiarazione di funzione come esempio:: + + __init void * __must_check action(enum magic value, size_t size, u8 count, + char *fmt, ...) __printf(4, 5) __malloc; + +L'ordine suggerito per gli elementi di un prototipo di funzione è il seguente: + +- classe d'archiviazione (in questo caso ``static __always_inline``. Da notare + che ``__always_inline`` è tecnicamente un attributo ma che viene trattato come + ``inline``) +- attributi della classe di archiviazione (in questo caso ``__init``, in altre + parole la sezione, ma anche cose tipo ``__cold``) +- il tipo di ritorno (in questo caso, ``void *``) +- attributi per il valore di ritorno (in questo caso, ``__must_check``) +- il nome della funzione (in questo caso, ``action``) +- i parametri della funzione(in questo caso, + ``(enum magic value, size_t size, u8 count, char *fmt, ...)``, + da notare che va messo anche il nome del parametro) +- attributi dei parametri (in questo caso, ``__printf(4, 5)``) +- attributi per il comportamento della funzione (in questo caso, ``__malloc_``) + +Notate che per la **definizione** di una funzione (il altre parole il corpo +della funzione), il compilatore non permette di usare gli attributi per i +parametri dopo i parametri. In questi casi, devono essere messi dopo gli +attributi della classe d'archiviazione (notate che la posizione di +``__printf(4,5)`` cambia rispetto alla **dichiarazione**):: + + static __always_inline __init __printf(4, 5) void * __must_check action(enum magic value, + size_t size, u8 count, char *fmt, ...) __malloc + { + ... + }*)**``)**``)``)``*)``)``)``)``*``)``)``)*) + 7) Centralizzare il ritorno delle funzioni ------------------------------------------ @@ -855,7 +893,7 @@ I messaggi del kernel non devono terminare con un punto fermo. Scrivere i numeri fra parentesi (%d) non migliora alcunché e per questo dovrebbero essere evitati. -Ci sono alcune macro per la diagnostica in <linux/device.h> che dovreste +Ci sono alcune macro per la diagnostica in <linux/dev_printk.h> che dovreste usare per assicurarvi che i messaggi vengano associati correttamente ai dispositivi e ai driver, e che siano etichettati correttamente: dev_err(), dev_warn(), dev_info(), e così via. Per messaggi che non sono associati ad diff --git a/Documentation/translations/it_IT/process/deprecated.rst b/Documentation/translations/it_IT/process/deprecated.rst index 987f45ee1804..febf83897783 100644 --- a/Documentation/translations/it_IT/process/deprecated.rst +++ b/Documentation/translations/it_IT/process/deprecated.rst @@ -69,8 +69,8 @@ dovrebbero essere fatto negli argomenti di funzioni di allocazione di memoria piccoli di quelli che il chiamante si aspettava. L'uso di questo modo di allocare può portare ad un overflow della memoria di heap e altri malfunzionamenti. (Si fa eccezione per valori numerici per i quali il -compilatore può generare avvisi circa un potenziale overflow. Tuttavia usare -i valori numerici come suggerito di seguito è innocuo). +compilatore può generare avvisi circa un potenziale overflow. Tuttavia, anche in +questi casi è preferibile riscrivere il codice come suggerito di seguito). Per esempio, non usate ``count * size`` come argomento:: @@ -80,6 +80,9 @@ Al suo posto, si dovrebbe usare l'allocatore a due argomenti:: foo = kmalloc_array(count, size, GFP_KERNEL); +Nello specifico, kmalloc() può essere sostituta da kmalloc_array(), e kzalloc() +da kcalloc(). + Se questo tipo di allocatore non è disponibile, allora dovrebbero essere usate le funzioni del tipo *saturate-on-overflow*:: @@ -100,9 +103,20 @@ Invece, usate la seguente funzione:: invitati a riorganizzare il vostro codice usando il `flexible array member <#zero-length-and-one-element-arrays>`_. -Per maggiori dettagli fate riferimento a array_size(), -array3_size(), e struct_size(), così come la famiglia di -funzioni check_add_overflow() e check_mul_overflow(). +Per altri calcoli, usate le funzioni size_mul(), size_add(), e size_sub(). Per +esempio, al posto di:: + + foo = krealloc(current_size + chunk_size * (count - 3), GFP_KERNEL); + +dovreste scrivere: + + foo = krealloc(size_add(current_size, + size_mul(chunk_size, + size_sub(count, 3))), GFP_KERNEL); + +Per maggiori dettagli fate riferimento a array3_size() e flex_array_size(), ma +anche le funzioni della famiglia check_mul_overflow(), check_add_overflow(), +check_sub_overflow(), e check_shl_overflow(). simple_strtol(), simple_strtoll(), simple_strtoul(), simple_strtoull() ---------------------------------------------------------------------- diff --git a/Documentation/translations/it_IT/process/howto.rst b/Documentation/translations/it_IT/process/howto.rst index 9554368a2ae2..052f1b3610cb 100644 --- a/Documentation/translations/it_IT/process/howto.rst +++ b/Documentation/translations/it_IT/process/howto.rst @@ -44,7 +44,7 @@ altro, utili riferimenti: - "C: A Reference Manual" di Harbison and Steele [Prentice Hall] Il kernel è stato scritto usando GNU C e la toolchain GNU. -Sebbene si attenga allo standard ISO C89, esso utilizza una serie di +Sebbene si attenga allo standard ISO C11, esso utilizza una serie di estensioni che non sono previste in questo standard. Il kernel è un ambiente C indipendente, che non ha alcuna dipendenza dalle librerie C standard, così alcune parti del C standard non sono supportate. @@ -109,8 +109,7 @@ Di seguito una lista di file che sono presenti nei sorgente del kernel e che accetteranno patch solo se queste osserveranno tali regole, e molte persone revisioneranno il codice solo se scritto nello stile appropriato. - :ref:`Documentation/translations/it_IT/process/submitting-patches.rst <it_submittingpatches>` e - :ref:`Documentation/translations/it_IT/process/submitting-drivers.rst <it_submittingdrivers>` + :ref:`Documentation/translations/it_IT/process/submitting-patches.rst <it_submittingpatches>` Questo file descrive dettagliatamente come creare ed inviare una patch con successo, includendo (ma non solo questo): @@ -395,7 +394,7 @@ trovati al sito: Ci sono diversi archivi della lista di discussione. Usate un qualsiasi motore di ricerca per trovarli. Per esempio: - http://dir.gmane.org/gmane.linux.kernel + https://lore.kernel.org/lkml/ É caldamente consigliata una ricerca in questi archivi sul tema che volete sollevare, prima di pubblicarlo sulla lista. Molte cose sono già state diff --git a/Documentation/translations/it_IT/process/index.rst b/Documentation/translations/it_IT/process/index.rst index c4c867132c88..8d4e36a07ff4 100644 --- a/Documentation/translations/it_IT/process/index.rst +++ b/Documentation/translations/it_IT/process/index.rst @@ -41,12 +41,12 @@ degli sviluppatori: :maxdepth: 1 changes - submitting-drivers stable-api-nonsense management-style stable-kernel-rules submit-checklist kernel-docs + maintainers Ed infine, qui ci sono alcune guide più tecniche che son state messe qua solo perché non si è trovato un posto migliore. diff --git a/Documentation/translations/it_IT/process/magic-number.rst b/Documentation/translations/it_IT/process/magic-number.rst index f452fafb1e84..02eb7eb2448e 100644 --- a/Documentation/translations/it_IT/process/magic-number.rst +++ b/Documentation/translations/it_IT/process/magic-number.rst @@ -75,87 +75,17 @@ Registro dei cambiamenti:: Nome magico Numero Struttura File ===================== ================ ======================== ========================================== 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`` -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`` -PTY_MAGIC 0x5001 ``drivers/char/pty.c`` -PPP_MAGIC 0x5002 ppp ``include/linux/if_pppvar.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`` -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`` -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`` -LSEMAGIC 0x05091998 lse ``drivers/fc4/fc.c`` -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`` -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 ``fs/coda/coda_fs_i.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`` ===================== ================ ======================== ========================================== - -Da notare che ci sono anche dei numeri magici specifici per driver nel -*sound memory management*. Consultate ``include/sound/sndmagic.h`` per una -lista completa. Molti driver audio OSS hanno i loro numeri magici costruiti a -partire dall'identificativo PCI della scheda audio - nemmeno questi sono -elencati in questo file. - -Il file-system HFS è un altro grande utilizzatore di numeri magici - potete -trovarli qui ``fs/hfs/hfs.h``. diff --git a/Documentation/translations/it_IT/process/maintainer-handbooks.rst b/Documentation/translations/it_IT/process/maintainer-handbooks.rst new file mode 100644 index 000000000000..d840145bcceb --- /dev/null +++ b/Documentation/translations/it_IT/process/maintainer-handbooks.rst @@ -0,0 +1,24 @@ +.. SPDX-License-Identifier: GPL-2.0 + +.. include:: ../disclaimer-ita.rst + +:Original: Documentation/process/maintainer-handbooks.rst +:Translator: Federico Vaga <federico.vaga@vaga.pv.it> + +.. _it_maintainer_handbooks_main: + +Note sul processo di sviluppo dei sottosistemi e dei sorgenti dei manutentori +============================================================================= + +Lo scopo di questo documento è quello di fornire informazioni sul processo di +sviluppo dedicate ai sottosistemi che vanno ad integrare quelle più generali +descritte in :ref:`Documentation/translations/it_IT/process +<it_development_process_main>`. + +Indice: + +.. toctree:: + :numbered: + :maxdepth: 2 + + maintainer-tip diff --git a/Documentation/translations/it_IT/process/maintainer-pgp-guide.rst b/Documentation/translations/it_IT/process/maintainer-pgp-guide.rst index f3c8e8d377ee..a1e98ec9532e 100644 --- a/Documentation/translations/it_IT/process/maintainer-pgp-guide.rst +++ b/Documentation/translations/it_IT/process/maintainer-pgp-guide.rst @@ -931,12 +931,11 @@ che avete nel vostro portachiavi:: uid [ unknown] Linus Torvalds <torvalds@kernel.org> sub rsa2048 2011-09-20 [E] -Poi, aprite il `PGP pathfinder`_. Nel campo "From", incollate l'impronta -digitale della chiave di Linus Torvalds che si vede nell'output qui sopra. -Nel campo "to", incollate il key-id della chiave sconosciuta che avete -trovato con ``gpg --search``, e poi verificare il risultato: - -- `Finding paths to Linus`_ +Poi, cercate un percorso affidabile da Linux Torvalds alla chiave che avete +trovato con ``gpg --search`` usando la chiave sconosciuta.Per farlo potete usare +diversi strumenti come https://github.com/mricon/wotmate, +https://git.kernel.org/pub/scm/docs/kernel/pgpkeys.git/tree/graphs, e +https://the.earth.li/~noodles/pathfind.html. Se trovate un paio di percorsi affidabili è un buon segno circa la validità della chiave. Ora, potete aggiungerla al vostro portachiavi dal keyserver:: @@ -948,6 +947,3 @@ fiducia nell'amministratore del servizio *PGP Pathfinder* sperando che non sia malintenzionato (infatti, questo va contro :ref:`it_devs_not_infra`). Tuttavia, se mantenete con cura la vostra rete di fiducia sarà un deciso miglioramento rispetto alla cieca fiducia nei keyserver. - -.. _`PGP pathfinder`: https://pgp.cs.uu.nl/ -.. _`Finding paths to Linus`: https://pgp.cs.uu.nl/paths/79BE3E4300411886/to/C94035C21B4F2AEB.html diff --git a/Documentation/translations/it_IT/process/maintainer-tip.rst b/Documentation/translations/it_IT/process/maintainer-tip.rst new file mode 100644 index 000000000000..126f17ee541e --- /dev/null +++ b/Documentation/translations/it_IT/process/maintainer-tip.rst @@ -0,0 +1,10 @@ +.. SPDX-License-Identifier: GPL-2.0 + +.. include:: ../disclaimer-ita.rst + +:Original: Documentation/process/maintainer-tip.rst + +Il tascabile dei sorgenti tip +============================= + +.. note:: To be translated diff --git a/Documentation/translations/it_IT/process/maintainers.rst b/Documentation/translations/it_IT/process/maintainers.rst new file mode 100644 index 000000000000..3225f7c89fda --- /dev/null +++ b/Documentation/translations/it_IT/process/maintainers.rst @@ -0,0 +1,13 @@ +:Original: Documentation/process/maintainers.rst + +Lista dei manutentori e come inviare modifiche al kernel +======================================================== + +Questa pagina non verrà tradotta. Fate riferimento alla versione originale in +inglese. + +.. note:: La pagina originale usa una direttiva speciale per integrare il file + `MAINTAINERS` in sphinx. La parte di quel documento che si potrebbe + tradurre contiene comunque informazioni già presenti in + :ref:`Documentation/translations/it_IT/process/submitting-patches.rst + <it_submittingpatches>`. diff --git a/Documentation/translations/it_IT/process/programming-language.rst b/Documentation/translations/it_IT/process/programming-language.rst index 41db2598ce11..c1a9b481a6f9 100644 --- a/Documentation/translations/it_IT/process/programming-language.rst +++ b/Documentation/translations/it_IT/process/programming-language.rst @@ -10,8 +10,8 @@ Linguaggio di programmazione Il kernel è scritto nel linguaggio di programmazione C [it-c-language]_. Più precisamente, il kernel viene compilato con ``gcc`` [it-gcc]_ usando -l'opzione ``-std=gnu89`` [it-gcc-c-dialect-options]_: il dialetto GNU -dello standard ISO C90 (con l'aggiunta di alcune funzionalità da C99). +l'opzione ``-std=gnu11`` [it-gcc-c-dialect-options]_: il dialetto GNU +dello standard ISO C11. Linux supporta anche ``clang`` [it-clang]_, leggete la documentazione :ref:`Building Linux with Clang/LLVM <kbuild_llvm>`. diff --git a/Documentation/translations/it_IT/process/stable-kernel-rules.rst b/Documentation/translations/it_IT/process/stable-kernel-rules.rst index 83f48afe48b9..0be675b03199 100644 --- a/Documentation/translations/it_IT/process/stable-kernel-rules.rst +++ b/Documentation/translations/it_IT/process/stable-kernel-rules.rst @@ -41,10 +41,10 @@ Regole sul tipo di patch che vengono o non vengono accettate nei sorgenti Procedura per sottomettere patch per i sorgenti -stable ------------------------------------------------------- - - Una patch di sicurezza non dovrebbero essere gestite (solamente) dal processo - di revisione -stable, ma dovrebbe seguire le procedure descritte in - :ref:`Documentation/translations/it_IT/admin-guide/security-bugs.rst <it_securitybugs>`. - +.. note:: + Una patch di sicurezza non dovrebbe essere gestita (solamente) dal processo + di revisione -stable, ma dovrebbe seguire le procedure descritte in + :ref:`Documentation/translations/it_IT/admin-guide/security-bugs.rst <it_securitybugs>`. Per tutte le altre sottomissioni, scegliere una delle seguenti procedure ------------------------------------------------------------------------ @@ -90,9 +90,9 @@ L':ref:`it_option_2` e l':ref:`it_option_3` sono più utili quando, al momento dell'inclusione dei sorgenti principali, si ritiene che non debbano essere incluse anche in quelli stabili (per esempio, perché si crede che si dovrebbero fare più verifiche per eventuali regressioni). L':ref:`it_option_3` è -particolarmente utile se la patch ha bisogno di qualche modifica per essere -applicata ad un kernel più vecchio (per esempio, perché nel frattempo l'API è -cambiata). +particolarmente utile se una patch dev'essere riportata su una versione +precedente (per esempio la patch richiede modifiche a causa di cambiamenti di +API). Notate che per l':ref:`it_option_3`, se la patch è diversa da quella nei sorgenti principali (per esempio perché è stato necessario un lavoro di @@ -167,9 +167,18 @@ Ciclo di una revisione della lista linux-kernel obietta la bontà della patch, sollevando problemi che i manutentori ed i membri non avevano compreso, allora la patch verrà rimossa dalla coda. - - Alla fine del ciclo di revisione tutte le patch che hanno ricevuto l'ACK - verranno aggiunte per il prossimo rilascio -stable, e successivamente - questo nuovo rilascio verrà fatto. + - Le patch che hanno ricevuto un ACK verranno inviate nuovamente come parte di + un rilascio candidato (-rc) al fine di essere verificate dagli sviluppatori e + dai testatori. + - Solitamente si pubblica solo una -rc, tuttavia se si riscontrano problemi + importanti, alcune patch potrebbero essere modificate o essere scartate, + oppure nuove patch potrebbero essere messe in coda. Dunque, verranno pubblicate + nuove -rc e così via finché non si ritiene che non vi siano più problemi. + - Si può rispondere ad una -rc scrivendo sulla lista di discussione un'email + con l'etichetta "Tested-by:". Questa etichetta verrà raccolta ed aggiunta al + commit rilascio. + - Alla fine del ciclo di revisione il nuovo rilascio -stable conterrà tutte le + patch che erano in coda e sono state verificate. - Le patch di sicurezza verranno accettate nei sorgenti -stable direttamente dalla squadra per la sicurezza del kernel, e non passerà per il normale ciclo di revisione. Contattate la suddetta squadra per maggiori dettagli @@ -186,8 +195,19 @@ Sorgenti - Il rilascio definitivo, e marchiato, di tutti i kernel stabili può essere trovato in rami distinti per versione al seguente indirizzo: - https://git.kernel.org/pub/scm/linux/kernel/git/stable/linux-stable.git + https://git.kernel.org/pub/scm/linux/kernel/git/stable/linux.git + + - I rilasci candidati di tutti i kernel stabili possono essere trovati al + seguente indirizzo: + + https://git.kernel.org/pub/scm/linux/kernel/git/stable/linux-stable-rc.git/ + + .. warning:: + I sorgenti -stable-rc sono un'istantanea dei sorgenti stable-queue e + subirà frequenti modifiche, dunque verrà anche trapiantato spesso. + Dovrebbe essere usato solo allo scopo di verifica (per esempio in un + sistema di CI) Comitato per la revisione ------------------------- diff --git a/Documentation/translations/it_IT/process/submitting-drivers.rst b/Documentation/translations/it_IT/process/submitting-drivers.rst deleted file mode 100644 index dadd77e47613..000000000000 --- a/Documentation/translations/it_IT/process/submitting-drivers.rst +++ /dev/null @@ -1,16 +0,0 @@ -.. include:: ../disclaimer-ita.rst - -:Original: :ref:`Documentation/process/submitting-drivers.rst <submittingdrivers>` -:Translator: Federico Vaga <federico.vaga@vaga.pv.it> - -.. _it_submittingdrivers: - -Sottomettere driver per il kernel Linux -======================================= - -.. note:: - - Questo documento è vecchio e negli ultimi anni non è stato più aggiornato; - dovrebbe essere aggiornato, o forse meglio, rimosso. La maggior parte di - quello che viene detto qui può essere trovato anche negli altri documenti - dedicati allo sviluppo. Per questo motivo il documento non verrà tradotto. diff --git a/Documentation/translations/it_IT/process/submitting-patches.rst b/Documentation/translations/it_IT/process/submitting-patches.rst index 4fb5b3aa306d..a3bb0008837a 100644 --- a/Documentation/translations/it_IT/process/submitting-patches.rst +++ b/Documentation/translations/it_IT/process/submitting-patches.rst @@ -18,16 +18,18 @@ Questo documento contiene un vasto numero di suggerimenti concisi. Per maggiori dettagli su come funziona il processo di sviluppo del kernel leggete Documentation/translations/it_IT/process/development-process.rst. Leggete anche Documentation/translations/it_IT/process/submit-checklist.rst per una lista di -punti da verificare prima di inviare del codice. Se state inviando un driver, -allora leggete anche -Documentation/translations/it_IT/process/submitting-drivers.rst; per delle patch -relative alle associazioni per Device Tree leggete +punti da verificare prima di inviare del codice. +Per delle patch relative alle associazioni per Device Tree leggete Documentation/translations/it_IT/process/submitting-patches.rst. Questa documentazione assume che sappiate usare ``git`` per preparare le patch. Se non siete pratici di ``git``, allora è bene che lo impariate; renderà la vostra vita di sviluppatore del kernel molto più semplice. +I sorgenti di alcuni sottosistemi e manutentori contengono più informazioni +riguardo al loro modo di lavorare ed aspettative. Consultate +:ref:`Documentation/translations/it_IT/process/maintainer-handbooks.rst <it_maintainer_handbooks_main>` + Ottenere i sorgenti attuali --------------------------- @@ -84,11 +86,11 @@ comporti come descritto. I manutentori vi saranno grati se scrivete la descrizione della patch in un formato che sia compatibile con il gestore dei sorgenti usato dal kernel, -``git``, come un "commit log". Leggete :ref:`it_explicit_in_reply_to`. +``git``, come un "commit log". Leggete :ref:`it_the_canonical_patch_format`. Risolvete solo un problema per patch. Se la vostra descrizione inizia ad essere lunga, potrebbe essere un segno che la vostra patch necessita d'essere -divisa. Leggete :ref:`split_changes`. +divisa. Leggete :ref:`it_split_changes`. Quando inviate o rinviate una patch o una serie, includete la descrizione completa delle modifiche e la loro giustificazione. Non limitatevi a dire che @@ -104,17 +106,28 @@ do frotz" piuttosto che "[This patch] makes xyzzy do frotz" or "[I] changed xyzzy to do frotz", come se steste dando ordini al codice di cambiare il suo comportamento. -Se la patch corregge un baco conosciuto, fare riferimento a quel baco inserendo -il suo numero o il suo URL. Se la patch è la conseguenza di una discussione -su una lista di discussione, allora fornite l'URL all'archivio di quella -discussione; usate i collegamenti a https://lore.kernel.org/ con il -``Message-Id``, in questo modo vi assicurerete che il collegamento non diventi -invalido nel tempo. +Se ci sono delle discussioni, o altre informazioni d'interesse, che fanno +riferimento alla patch, allora aggiungete l'etichetta 'Link:' per farvi +riferimento. Per esempio, se la vostra patch corregge un baco potete aggiungere +quest'etichetta per fare riferimento ad un rapporto su una lista di discussione +o un *bug tracker*. Un altro esempio; potete usare quest'etichetta per far +riferimento ad una discussione precedentemente avvenuta su una lista di +discussione, o qualcosa di documentato sul web, da cui poi è nata la patch in +questione. + +Quando volete fare riferimento ad una lista di discussione, preferite il +servizio d'archiviazione lore.kernel.org. Per create un collegamento URL è +sufficiente usare il campo ``Message-Id``, presente nell'intestazione del +messaggio, senza parentesi angolari. Per esempio:: + + Link: https://lore.kernel.org/r/30th.anniversary.repost@klaava.Helsinki.FI/ + +Prima d'inviare il messaggio ricordatevi di verificare che il collegamento così +creato funzioni e che indirizzi verso il messaggio desiderato. -Tuttavia, cercate di rendere la vostra spiegazione comprensibile anche senza -far riferimento a fonti esterne. In aggiunta ai collegamenti a bachi e liste -di discussione, riassumente i punti più importanti della discussione che hanno -portato alla creazione della patch. +Tuttavia, provate comunque a dare una spiegazione comprensibile anche senza +accedere alle fonti esterne. Inoltre, riassumente i punti più salienti che hanno +condotto all'invio della patch. Se volete far riferimento a uno specifico commit, non usate solo l'identificativo SHA-1. Per cortesia, aggiungete anche la breve riga @@ -226,10 +239,11 @@ nella vostra patch. Dovreste sempre inviare una copia della patch ai manutentori dei sottosistemi interessati dalle modifiche; date un'occhiata al file MAINTAINERS e alla storia -delle revisioni per scoprire chi si occupa del codice. Lo script -scripts/get_maintainer.pl può esservi d'aiuto. Se non riuscite a trovare un -manutentore per il sottosistema su cui state lavorando, allora Andrew Morton -(akpm@linux-foundation.org) sarà la vostra ultima possibilità. +delle revisioni per scoprire chi si occupa del codice. Lo script +scripts/get_maintainer.pl può esservi d'aiuto (passategli il percorso alle +vostre patch). Se non riuscite a trovare un manutentore per il sottosistema su +cui state lavorando, allora Andrew Morton (akpm@linux-foundation.org) sarà la +vostra ultima possibilità. Normalmente, dovreste anche scegliere una lista di discussione a cui inviare la vostra serie di patch. La lista di discussione linux-kernel@vger.kernel.org @@ -324,14 +338,19 @@ cosa stia accadendo. Assicuratevi di dire ai revisori quali cambiamenti state facendo e di ringraziarli per il loro tempo. Revisionare codice è un lavoro faticoso e che -richiede molto tempo, e a volte i revisori diventano burberi. Tuttavia, anche -in questo caso, rispondete con educazione e concentratevi sul problema che -hanno evidenziato. +richiede molto tempo, e a volte i revisori diventano burberi. Tuttavia, anche in +questo caso, rispondete con educazione e concentratevi sul problema che hanno +evidenziato. Quando inviate una version successiva ricordatevi di aggiungere un +``patch changelog`` alla email di intestazione o ad ogni singola patch spiegando +le differenze rispetto a sottomissioni precedenti (vedere +:ref:`it_the_canonical_patch_format`). Leggete Documentation/translations/it_IT/process/email-clients.rst per le raccomandazioni sui programmi di posta elettronica e l'etichetta da usare sulle liste di discussione. +.. _it_resend_reminders: + Non scoraggiatevi - o impazientitevi ------------------------------------ @@ -504,7 +523,8 @@ Utilizzare Reported-by:, Tested-by:, Reviewed-by:, Suggested-by: e Fixes: L'etichetta Reported-by da credito alle persone che trovano e riportano i bachi e si spera che questo possa ispirarli ad aiutarci nuovamente in futuro. Rammentate che se il baco è stato riportato in privato, dovrete chiedere il -permesso prima di poter utilizzare l'etichetta Reported-by. +permesso prima di poter utilizzare l'etichetta Reported-by. Questa etichetta va +usata per i bachi, dunque non usatela per richieste di nuove funzionalità. L'etichetta Tested-by: indica che la patch è stata verificata con successo (su un qualche sistema) dalla persona citata. Questa etichetta informa i @@ -574,6 +594,8 @@ previste per i kernel stabili, e nemmeno dalla necessità di aggiungere in copia conoscenza stable@vger.kernel.org su tutte le patch per suddetti kernel. +.. _it_the_canonical_patch_format: + Il formato canonico delle patch ------------------------------- @@ -719,6 +741,8 @@ messe correttamente oltre la riga.:: Maggiori dettagli sul formato delle patch nei riferimenti qui di seguito. +.. _it_backtraces: + Aggiungere i *backtrace* nei messaggi di commit ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ diff --git a/Documentation/translations/ja_JP/SubmittingPatches b/Documentation/translations/ja_JP/SubmittingPatches index 0d308edef781..04deb77b20c6 100644 --- a/Documentation/translations/ja_JP/SubmittingPatches +++ b/Documentation/translations/ja_JP/SubmittingPatches @@ -35,8 +35,7 @@ Linux カーネルに変更を加えたいと思っている個人又は会社 てもらえやすくする提案を集めたものです。 コードを投稿する前に、Documentation/process/submit-checklist.rst の項目リストに目 -を通してチェックしてください。もしあなたがドライバーを投稿しようとし -ているなら、Documentation/process/submitting-drivers.rst にも目を通してください。 +を通してチェックしてください。 -------------------------------------------- セクション1 パッチの作り方と送り方 @@ -81,9 +80,7 @@ Linux カーネルに対する全ての変更は diff(1) コマンドによる dontdiff ファイルには Linux カーネルのビルドプロセスの過程で生成された ファイルの一覧がのっています。そして、それらはパッチを生成する diff(1) コマンドで無視されるべきです。dontdiff ファイルは 2.6.12 以後のバージョ -ンの Linux カーネルソースツリーに含まれています。それより前のバージョン -の Linux カーネルソースツリーに対する dontdiff ファイルは、 -<http://www.xenotime.net/linux/doc/dontdiff>から取得することができます。 +ンの Linux カーネルソースツリーに含まれています。 投稿するパッチの中に関係のない余分なファイルが含まれていないことを確 認してください。diff(1) コマンドで生成したパッチがあなたの意図したとお @@ -125,6 +122,17 @@ http://savannah.nongnu.org/projects/quilt 登録済みのバグエントリを修正するパッチであれば、そのバグエントリを示すバグ ID や URL を明記してください。 +特定のコミットを参照したい場合は、その SHA-1 ID だけでなく、一行サマリ +も含めてください。それにより、それが何に関するコミットなのかがレビューする +人にわかりやすくなります。 +例 (英文のママ): + + Commit e21d2170f36602ae2708 ("video: remove unnecessary + platform_set_drvdata()") removed the unnecessary + platform_set_drvdata(), but left the variable "dev" unused, + delete it. + + 3) パッチの分割 意味のあるひとまとまりごとに変更を個々のパッチファイルに分けてください。 @@ -162,7 +170,8 @@ http://savannah.nongnu.org/projects/quilt MAINTAINERS ファイルとソースコードに目を通してください。そして、その変 更がメンテナのいる特定のサブシステムに加えられるものであることが分か -れば、その人に電子メールを送ってください。 +れば、その人に電子メールを送ってください。その際 +./scripts/get_maintainers.pl のスクリプトが有用です。 もし、メンテナが載っていなかったり、メンテナからの応答がないなら、 LKML ( linux-kernel@vger.kernel.org )へパッチを送ってください。ほとんど @@ -400,7 +409,7 @@ Acked-by: が必ずしもパッチ全体の承認を示しているわけでは このタグはパッチに関心があると思われる人達がそのパッチの議論に含まれていたこと を明文化します。 -14) Reported-by と Tested-by: と Reviewed-by: の利用 +14) Reported-by:, Tested-by:, Reviewed-by: および Suggested-by: の利用 他の誰かによって報告された問題を修正するパッチであれば、問題報告者という寄与を クレジットするために、Reported-by: タグを追加することを検討してください。 @@ -449,6 +458,13 @@ Reviewd-by タグはそのパッチがカーネルに対して適切な修正で レビューを実施したレビューアによって提供される時、Reviewed-by: タグがあなたの パッチをカーネルにマージする可能性を高めるでしょう。 +Suggested-by: タグは、パッチのアイデアがその人からの提案に基づくものである +ことを示し、アイデアの提供をクレジットするものです。提案者の明示的な許可が +ない場合、特にそのアイデアが公開のフォーラムで示されていない場合には、この +タグをつけないように注意してください。とはいえ、アイデアの提供者をこつこつ +クレジットしていけば、望むらくはその人たちが将来別の機会に再度力を貸す気に +なってくれるかもしれません。 + 15) 標準的なパッチのフォーマット 標準的なパッチのサブジェクトは以下のとおりです。 @@ -681,10 +697,11 @@ Jeff Garzik, "Linux kernel patch submission format". <https://web.archive.org/web/20180829112450/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/> + <http://www.kroah.com/log/linux/maintainer.html> + <http://www.kroah.com/log/linux/maintainer-02.html> + <http://www.kroah.com/log/linux/maintainer-03.html> + <http://www.kroah.com/log/linux/maintainer-04.html> + <http://www.kroah.com/log/linux/maintainer-05.html> NO!!!! No more huge patch bombs to linux-kernel@vger.kernel.org people! <https://lore.kernel.org/r/20050711.125305.08322243.davem@davemloft.net> diff --git a/Documentation/translations/ja_JP/howto.rst b/Documentation/translations/ja_JP/howto.rst index d667f9d8a02a..b8eeb45a02d4 100644 --- a/Documentation/translations/ja_JP/howto.rst +++ b/Documentation/translations/ja_JP/howto.rst @@ -65,7 +65,7 @@ Linux カーネル開発のやり方 - 『新・詳説 C 言語 H&S リファレンス』 (サミュエル P ハービソン/ガイ L スティール共著 斉藤 信男監訳)[ソフトバンク] カーネルは GNU C と GNU ツールチェインを使って書かれています。カーネル -は ISO C89 仕様に準拠して書く一方で、標準には無い言語拡張を多く使って +は ISO C11 仕様に準拠して書く一方で、標準には無い言語拡張を多く使って います。カーネルは標準 C ライブラリに依存しない、C 言語非依存環境です。 そのため、C の標準の中で使えないものもあります。特に任意の long long の除算や浮動小数点は使えません。カーネルがツールチェインや C 言語拡張 @@ -129,8 +129,8 @@ linux-api@vger.kernel.org に送ることを勧めます。 ルに従っているものだけを受け付け、多くの人は正しいスタイルのコード だけをレビューします。 - :ref:`Documentation/process/submitting-patches.rst <codingstyle>` と :ref:`Documentation/process/submitting-drivers.rst <submittingdrivers>` - これらのファイルには、どうやってうまくパッチを作って投稿するかにつ + :ref:`Documentation/process/submitting-patches.rst <codingstyle>` + このファイルには、どうやってうまくパッチを作って投稿するかにつ いて非常に詳しく書かれており、以下を含みます (これだけに限らない けれども) @@ -262,21 +262,21 @@ Linux カーネルの開発プロセスは現在幾つかの異なるメイン チ」と多数のサブシステム毎のカーネルブランチから構成されます。これらの ブランチとは - - - メインの 4.x カーネルツリー - - 4.x.y -stable カーネルツリー - - サブシステム毎のカーネルツリーとパッチ - - 統合テストのための 4.x -next カーネルツリー + - Linus のメインラインツリー + - メジャー番号をまたぐ数本の安定版ツリー + - サブシステム毎のカーネルツリー + - 統合テストのための linux-next カーネルツリー -4.x カーネルツリー +メインラインツリー ~~~~~~~~~~~~~~~~~~ -4.x カーネルは Linus Torvalds によってメンテナンスされ、 -https://kernel.org の pub/linux/kernel/v4.x/ ディレクトリに存在します。 +メインラインツリーは Linus Torvalds によってメンテナンスされ、 +https://kernel.org のリポジトリに存在します。 この開発プロセスは以下のとおり - - 新しいカーネルがリリースされた直後に、2週間の特別期間が設けられ、 この期間中に、メンテナ達は Linus に大きな差分を送ることができます。 - このような差分は通常 -next カーネルに数週間含まれてきたパッチです。 + このような差分は通常 linux-next カーネルに数週間含まれてきたパッチです。 大きな変更は git(カーネルのソース管理ツール、詳細は http://git-scm.com/ 参照) を使って送るのが好ましいやり方ですが、パッ チファイルの形式のまま送るのでも十分です。 @@ -303,20 +303,18 @@ Andrew Morton が Linux-kernel メーリングリストにカーネルリリー 前もって決められた計画によってリリースされるものではないから です。」* -4.x.y -stable カーネルツリー -~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +メジャー番号をまたぐ数本の安定版ツリー +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ バージョン番号が3つの数字に分かれているカーネルは -stable カーネルです。 -これには、4.x カーネルで見つかったセキュリティ問題や重大な後戻りに対す -る比較的小さい重要な修正が含まれます。 +これには最初の2つのバージョン番号の数字に対応した、 +メインラインリリースで見つかったセキュリティ問題や +重大な後戻りに対する比較的小さい重要な修正が含まれます。 これは、開発/実験的バージョンのテストに協力することに興味が無く、最新 の安定したカーネルを使いたいユーザに推奨するブランチです。 -もし、4.x.y カーネルが存在しない場合には、番号が一番大きい 4.x が最新 -の安定版カーネルです。 - -4.x.y は "stable" チーム <stable@vger.kernel.org> でメンテされており、 +安定版ツリーは"stable" チーム <stable@vger.kernel.org> でメンテされており、 必要に応じてリリースされます。通常のリリース期間は 2週間毎ですが、差 し迫った問題がなければもう少し長くなることもあります。セキュリティ関 連の問題の場合はこれに対してだいたいの場合、すぐにリリースがされます。 @@ -326,7 +324,7 @@ Documentation/process/stable-kernel-rules.rst ファイルにはどのような 類の変更が -stable ツリーに受け入れ可能か、またリリースプロセスがどう 動くかが記述されています。 -サブシステム毎のカーネルツリーとパッチ +サブシステム毎のカーネルツリー ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ それぞれのカーネルサブシステムのメンテナ達は --- そして多くのカーネル @@ -351,19 +349,19 @@ quilt シリーズとして公開されているパッチキューも使われ けることができます。大部分のこれらの patchwork のサイトは https://patchwork.kernel.org/ でリストされています。 -統合テストのための 4.x -next カーネルツリー -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +統合テストのための linux-next カーネルツリー +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -サブシステムツリーの更新内容がメインラインの 4.x ツリーにマージされる +サブシステムツリーの更新内容がメインラインツリーにマージされる 前に、それらは統合テストされる必要があります。この目的のため、実質的に 全サブシステムツリーからほぼ毎日プルされてできる特別なテスト用のリポジ トリが存在します- https://git.kernel.org/?p=linux/kernel/git/next/linux-next.git -このやり方によって、-next カーネルは次のマージ機会でどんなものがメイン -ラインカーネルにマージされるか、おおまかなの展望を提供します。-next カー -ネルの実行テストを行う冒険好きなテスターは大いに歓迎されます。 +このやり方によって、linux-next は次のマージ機会でどんなものがメイン +ラインにマージされるか、おおまかな展望を提供します。 +linux-next の実行テストを行う冒険好きなテスターは大いに歓迎されます。 バグレポート ------------- @@ -412,7 +410,7 @@ https://bugzilla.kernel.org に行ってください。もし今後のバグレ このメーリングリストのアーカイブは web 上の多数の場所に存在します。こ れらのアーカイブを探すにはサーチエンジンを使いましょう。例えば- - http://dir.gmane.org/gmane.linux.kernel + https://lore.kernel.org/lkml/ リストに投稿する前にすでにその話題がアーカイブに存在するかどうかを検索 することを是非やってください。多数の事がすでに詳細に渡って議論されてお diff --git a/Documentation/translations/ja_JP/index.rst b/Documentation/translations/ja_JP/index.rst index 88d4d98eed15..43b9fb7246d3 100644 --- a/Documentation/translations/ja_JP/index.rst +++ b/Documentation/translations/ja_JP/index.rst @@ -3,9 +3,9 @@ \renewcommand\thesection* \renewcommand\thesubsection* \kerneldocCJKon - \kerneldocBeginJP + \kerneldocBeginJP{ -Japanese translations +日本語訳 ===================== .. toctree:: @@ -15,4 +15,4 @@ Japanese translations .. raw:: latex - \kerneldocEndJP + }\kerneldocEndJP diff --git a/Documentation/translations/ko_KR/howto.rst b/Documentation/translations/ko_KR/howto.rst index e3cdf0c84892..969e91a95bb0 100644 --- a/Documentation/translations/ko_KR/howto.rst +++ b/Documentation/translations/ko_KR/howto.rst @@ -62,7 +62,7 @@ Documentation/process/howto.rst - "Practical C Programming" by Steve Oualline [O'Reilly] - "C: A Reference Manual" by Harbison and Steele [Prentice Hall] -커널은 GNU C와 GNU 툴체인을 사용하여 작성되었다. 이 툴들은 ISO C89 표준을 +커널은 GNU C와 GNU 툴체인을 사용하여 작성되었다. 이 툴들은 ISO C11 표준을 따르는 반면 표준에 있지 않은 많은 확장기능도 가지고 있다. 커널은 표준 C 라이브러리와는 관계없이 freestanding C 환경이어서 C 표준의 일부는 지원되지 않는다. 임의의 long long 나누기나 floating point는 지원되지 않는다. @@ -124,7 +124,7 @@ mtk.manpages@gmail.com의 메인테이너에게 보낼 것을 권장한다. 메인테이너들은 이 규칙을 따르는 패치들만을 받아들일 것이고 많은 사람들이 그 패치가 올바른 스타일일 경우만 코드를 검토할 것이다. - :ref:`Documentation/process/submitting-patches.rst <submittingpatches>` 와 :ref:`Documentation/process/submitting-drivers.rst <submittingdrivers>` + :ref:`Documentation/process/submitting-patches.rst <submittingpatches>` 이 파일들은 성공적으로 패치를 만들고 보내는 법을 다음의 내용들로 굉장히 상세히 설명하고 있다(그러나 다음으로 한정되진 않는다). @@ -386,7 +386,7 @@ https://bugzilla.kernel.org 를 체크하고자 할 수도 있다; 소수의 커 웹상의 많은 다른 곳에도 메일링 리스트의 아카이브들이 있다. 이러한 아카이브들을 찾으려면 검색 엔진을 사용하라. 예를 들어: - http://dir.gmane.org/gmane.linux.kernel + https://lore.kernel.org/lkml/ 여러분이 새로운 문제에 관해 리스트에 올리기 전에 말하고 싶은 주제에 관한 것을 아카이브에서 먼저 찾아보기를 강력히 권장한다. 이미 상세하게 토론된 많은 diff --git a/Documentation/translations/ko_KR/index.rst b/Documentation/translations/ko_KR/index.rst index f636b482fb4c..4add6b2fe1f2 100644 --- a/Documentation/translations/ko_KR/index.rst +++ b/Documentation/translations/ko_KR/index.rst @@ -3,7 +3,7 @@ \renewcommand\thesection* \renewcommand\thesubsection* \kerneldocCJKon - \kerneldocBeginKR + \kerneldocBeginKR{ 한국어 번역 =========== @@ -26,5 +26,4 @@ .. raw:: latex - \normalsize - \kerneldocEndKR + }\kerneldocEndKR diff --git a/Documentation/translations/zh_CN/IRQ.txt b/Documentation/translations/zh_CN/IRQ.txt deleted file mode 100644 index 9aec8dca4fcf..000000000000 --- a/Documentation/translations/zh_CN/IRQ.txt +++ /dev/null @@ -1,39 +0,0 @@ -Chinese translated version of Documentation/core-api/irq/index.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: Eric W. Biederman <ebiederman@xmission.com> -Chinese maintainer: Fu Wei <tekkamanninja@gmail.com> ---------------------------------------------------------------------- -Documentation/core-api/irq/index.rst 的中文翻译 - -如果想评论或更新本文的内容，请直接联系原文档的维护者。如果你使用英文 -交流有困难的话，也可以向中文版维护者求助。如果本翻译更新不及时或者翻 -译存在问题，请联系中文版维护者。 -英文版维护者： 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/PCI/acpi-info.rst b/Documentation/translations/zh_CN/PCI/acpi-info.rst new file mode 100644 index 000000000000..a35f39dcd858 --- /dev/null +++ b/Documentation/translations/zh_CN/PCI/acpi-info.rst @@ -0,0 +1,139 @@ +.. SPDX-License-Identifier: GPL-2.0 +.. include:: ../disclaimer-zh_CN.rst + +:Original: Documentation/PCI/acpi-info.rst + +:翻译: + + 司延腾 Yanteng Si <siyanteng@loongson.cn> + +:校译: + + +===================== +PCI主桥的ACPI注意事项 +===================== + +一般的规则是，ACPI命名空间应该描述操作系统可能使用的所有东西，除非有其他方法让操作系 +统找到它[1, 2]。 + +例如，没有标准的硬件机制来枚举PCI主桥，所以ACPI命名空间必须描述每个主桥、访问它 +下面的PCI配置空间的方法、主桥转发到PCI的地址空间窗口（使用_CRS）以及传统的INTx +中断的路由（使用_PRT）。 + +在主桥下面的PCI设备，通常不需要通过ACPI描述。操作系统可以通过标准的PCI枚举机制来 +发现它们，使用配置访问来发现和识别设备，并读取和测量它们的BAR。然而，如果ACPI为它们 +提供电源管理或热插拔功能，或者如果设备有由平台中断控制器连接的INTx中断，需要一个_PRT +来描述这些连接，这种情况下ACPI可以描述PCI设备。 + +ACPI资源描述是通过ACPI命名空间中设备的_CRS对象完成的[2]。_CRS就像一个通用的PCI BAR： +操作系统可以读取_CRS并找出正在消耗的资源，即使它没有该设备的驱动程序[3]。这一点很重要， +因为它意味着一个旧的操作系统可以正确地工作，即使是在操作系统不知道的新设备的系统上。新设 +备可能什么都不做，但操作系统至少可以确保没有资源与它们冲突。 + +像MCFG、HPET、ECDT等静态表，不是保留地址空间的机制。静态表是在操作系统在启动初期且在它 +能够解析ACPI命名空间之前需要知道的东西。如果定义了一个新的表，即使旧的操作系统忽略了这 +个表，它也需要正常运行。_CRS允许这样做，因为它是通用的，可以被旧的操作系统解析；而静态表 +则不允许。 + +如果操作系统要管理一个通过ACPI描述的不可发现的设备，该设备将有一个特定的_HID/_CID，以 +告诉操作系统与之绑定的驱动程序，并且_CRS告诉操作系统和驱动程序该设备的寄存器在哪里。 + +PCI主桥是PNP0A03或PNP0A08设备。它们的_CRS应该描述它们所消耗的所有地址空间。这包括它 +们转发到PCI总线上的所有窗口，以及不转发到PCI的主桥本身的寄存器。主桥的寄存器包括次要/下 +级总线寄存器，决定了桥下面的总线范围，窗口寄存器描述了桥洞，等等。这些都是设备相关的，非 +架构相关的东西，所以PNP0A03/PNP0A08驱动可以管理它们的唯一方法是通过_PRS/_CRS/_SRS， +它包含了特定于设备的细节。主桥寄存器也包括ECAM空间，因为它是由主桥消耗的。 + +ACPI定义了一个Consumer/Producer位来区分桥寄存器（“Consumer”下文译作消费者）和 +桥洞（“Producer”下文译作生产者）[4, 5]，但是早期的BIOS没有正确使用这个位。其结果 +是，目前的ACPI规范只为扩展地址空间描述符定义了消费者/生产者；在旧的QWord/Word/Word地 +址空间描述符中，该位应该被忽略。因此，操作系统必须假定所有的QWord/Word/Word描述符都是 +窗口。 + +在增加扩展地址空间描述符之前，消费者/生产者的失败意味着没有办法描述PNP0A03/PNP0A08设 +备本身的桥寄存器。解决办法是在PNP0C02捕捉器中描述桥寄存器（包括ECAM空间）[6]。 +除了ECAM之外，桥寄存器空间反正是特定于设备的，所以通用的PNP0A03/PNP0A08驱动程 +序(pci_root.c)没有必要了解它。 + +新的架构应该能够在PNP0A03设备中使用“消费者”扩展地址空间描述符，用于桥寄存器，包括 +ECAM，尽管对[6]的严格解释可能禁止这样做。旧的x86和ia64内核假定所有的地址空间描述 +符，包括“消费者”扩展地址空间的描述符，都是窗口，所以在这些架构上以这种方式描述桥寄 +存器是不安全的。 + +PNP0C02“主板”设备基本上是万能的。除了“不要将这些资源用于其他用途”之外，没有其他的编 +程模型。因此，PNP0C02 _CRS应该声明ACPI命名空间中(1)没有被_CRS声明的任何其他设备对 +象的地址空间，(2)不应该被OS分配给其他东西。 + +除非有一个标准的固件接口用于配置访问，例如ia64 SAL接口[7]，否则PCIe规范要求使用增强 +型配置访问方法（ECAM）。主桥消耗ECAM内存地址空间并将内存访问转换为PCI配置访问。该规范 +定义了ECAM地址空间的布局和功能；只有地址空间的基础是特定于设备的。ACPI操作系统从静态 +MCFG表或PNP0A03设备中的_CBA方法中了解基础地址。 + +MCFG表必须描述非热插拔主桥的ECAM空间[8]。由于MCFG是一个静态表，不能通过热插拔更新， +PNP0A03设备中的_CBA方法描述了可热插拔主桥的ECAM空间[9]。请注意，对于MCFG和_CBA， +基址总是对应于总线0，即使桥器下面的总线范围（通过_CRS报告）不从0开始。 + + +[1] ACPI 6.2, sec 6.1: + 对于任何在非枚举类型的总线上的设备（例如，ISA总线），OSPM会枚举设备的标识符，ACPI + 系统固件必须为每个设备提供一个_HID对象...以使OSPM能够做到这一点。 + +[2] ACPI 6.2, sec 3.7: + 操作系统枚举主板设备时，只需通过读取ACPI命名空间来寻找具有硬件ID的设备。 + + ACPI枚举的每个设备都包括ACPI命名空间中ACPI定义的对象，该对象报告设备可能占用的硬 + 件资源[_PRS]，报告设备当前使用的资源[_CRS]的对象，以及配置这些资源的对象[_SRS]。 + 这些信息被即插即用操作系统（OSPM）用来配置设备。 + +[3] ACPI 6.2, sec 6.2: + OSPM使用设备配置对象来配置通过ACPI列举的设备的硬件资源。设备配置对象提供了关于当前 + 和可能的资源需求的信息，共享资源之间的关系，以及配置硬件资源的方法。 + + 当OSPM枚举一个设备时，它调用_PRS来确定该设备的资源需求。它也可以调用_CRS来找到该设 + 备的当前资源设置。利用这些信息，即插即用系统决定设备应该消耗什么资源，并通过调用设备 + 的_SRS控制方法来设置这些资源。 + + 在ACPI中，设备可以消耗资源（例如，传统的键盘），提供资源（例如，一个专有的PCI桥）， + 或者两者都做。除非另有规定，设备的资源被假定为来自设备层次结构中设备上方最近的匹配资 + 源。 + +[4] ACPI 6.2, sec 6.4.3.5.1, 2, 3, 4: + QWord/DWord/Word 地址空间描述符 (.1, .2, .3) + 常规标志: Bit [0] 被忽略。 + + 扩展地址空间描述符 (.4) + 常规标志: Bit [0] 消费者/生产者: + + * 1 – 这个设备消费这个资源 + * 0 – 该设备生产和消费该资源 + +[5] ACPI 6.2, sec 19.6.43: + ResourceUsage指定内存范围是由这个设备（ResourceConsumer）消费还是传递给子设备 + （ResourceProducer）。如果没有指定，那么就假定是ResourceConsumer。 + +[6] PCI Firmware 3.2, sec 4.1.2: + 如果操作系统不能原生的懂得保留MMCFG区域，MMCFG区域必须由固件保留。在MCFG表中或通 + 过_CBA方法（见第4.1.3节）报告的地址范围必须通过声明主板资源来保留。对于大多数系统， + 主板资源将出现在ACPI命名空间的根部（在_SB下），在一个节点的_HID为EISAID（PNP0C0 + 2），在这种情况下的资源不应该要求在根PCI总线的_CRS。这些资源可以选择在Int15 E820 + 或EFIGetMemoryMap中作为保留内存返回，但必须始终通过ACPI作为主板资源报告。 + +[7] PCI Express 4.0, sec 7.2.2: + 对于PC兼容的系统，或者没有实现允许访问配置空间的处理器架构特定固件接口标准的系统，需 + 要使用本节中定义的ECAM。 + +[8] PCI Firmware 3.2, sec 4.1.2: + MCFG表是一个ACPI表，用于沟通的基础地址对应的非热的可移动的PCI段组范围内的PCI段组在 + 启动时提供给操作系统。这对PC兼容系统来说是必需的。 + + MCFG表仅用于沟通在启动时系统可用的PCI段组对应的基址。 + +[9] PCI Firmware 3.2, sec 4.1.3: + _CBA (Memory mapped Configuration Base Address) 控制方法是一个可选的ACPI对 + 象，用于返回热插拔主桥的64位内存映射的配置基址。_CBA 返回的基址是与处理器相关的地址。 + _CBA 控制方法被评估为一个整数。 + + 这个控制方法出现在主桥对象下。当_CBA方法出现在一个活动的主桥对象下时，操作系统会评 + 估这个结构，以确定内存映射的配置基址，对应于_CRS方法中指定的总线编号范围的PCI段组。 + 一个包含_CBA方法的ACPI命名空间对象也必须包含一个相应的_SEG方法。 diff --git a/Documentation/translations/zh_CN/PCI/index.rst b/Documentation/translations/zh_CN/PCI/index.rst index 16acb2bd9b58..cbeb33c34a98 100644 --- a/Documentation/translations/zh_CN/PCI/index.rst +++ b/Documentation/translations/zh_CN/PCI/index.rst @@ -10,9 +10,6 @@ :校译: - -.. _cn_PCI_index.rst: - =================== Linux PCI总线子系统 =================== @@ -26,12 +23,12 @@ Linux PCI总线子系统 pci-iov-howto msi-howto sysfs-pci + acpi-info Todolist: - acpi-info - pci-error-recovery - pcieaer-howto - endpoint/index - boot-interrupts +* pci-error-recovery +* pcieaer-howto +* endpoint/index +* boot-interrupts diff --git a/Documentation/translations/zh_CN/PCI/pci-iov-howto.rst b/Documentation/translations/zh_CN/PCI/pci-iov-howto.rst index fbc83dfdcead..fb023ea1374d 100644 --- a/Documentation/translations/zh_CN/PCI/pci-iov-howto.rst +++ b/Documentation/translations/zh_CN/PCI/pci-iov-howto.rst @@ -123,14 +123,14 @@ nr_virtfn'是要启用的VF的编号。 ... } - static int dev_suspend(struct pci_dev *dev, pm_message_t state) + static int dev_suspend(struct device *dev) { ... return 0; } - static int dev_resume(struct pci_dev *dev) + static int dev_resume(struct device *dev) { ... @@ -163,8 +163,7 @@ nr_virtfn'是要启用的VF的编号。 .id_table = dev_id_table, .probe = dev_probe, .remove = dev_remove, - .suspend = dev_suspend, - .resume = dev_resume, + .driver.pm = &dev_pm_ops .shutdown = dev_shutdown, .sriov_configure = dev_sriov_configure, }; diff --git a/Documentation/translations/zh_CN/PCI/pci.rst b/Documentation/translations/zh_CN/PCI/pci.rst index 520707787256..83c2a41d38d3 100644 --- a/Documentation/translations/zh_CN/PCI/pci.rst +++ b/Documentation/translations/zh_CN/PCI/pci.rst @@ -255,13 +255,13 @@ pci_set_master()将通过设置PCI_COMMAND寄存器中的总线主控位来启 虽然所有的驱动程序都应该明确指出PCI总线主控的DMA功能（如32位或64位），但对于流式 数据来说，具有超过32位总线主站功能的设备需要驱动程序通过调用带有适当参数的 -``pci_set_dma_mask()`` 来“注册”这种功能。一般来说，在系统RAM高于4G物理地址的情 +``dma_set_mask()`` 来“注册”这种功能。一般来说，在系统RAM高于4G物理地址的情 况下，这允许更有效的DMA。 -所有PCI-X和PCIe兼容设备的驱动程序必须调用 ``pci_set_dma_mask()`` ，因为它们 +所有PCI-X和PCIe兼容设备的驱动程序必须调用 ``dma_set_mask()`` ，因为它们 是64位DMA设备。 -同样，如果设备可以通过调用 ``pci_set_consistent_dma_mask()`` 直接寻址到 +同样，如果设备可以通过调用 ``dma_set_coherent_mask()`` 直接寻址到 4G物理地址以上的系统RAM中的“一致性内存”，那么驱动程序也必须“注册”这种功能。同 样，这包括所有PCI-X和PCIe兼容设备的驱动程序。许多64位“PCI”设备（在PCI-X之前） 和一些PCI-X设备对有效载荷（“流式”）数据具有64位DMA功能，但对控制（“一致性”）数 diff --git a/Documentation/translations/zh_CN/accounting/delay-accounting.rst b/Documentation/translations/zh_CN/accounting/delay-accounting.rst index 67d5606e5401..f1849411018e 100644 --- a/Documentation/translations/zh_CN/accounting/delay-accounting.rst +++ b/Documentation/translations/zh_CN/accounting/delay-accounting.rst @@ -17,6 +17,8 @@ a) 等待一个CPU（任务为可运行） b) 完成由该任务发起的块I/O同步请求 c) 页面交换 d) 内存回收 +e) 页缓存抖动 +f) 直接规整 并将这些统计信息通过taskstats接口提供给用户空间。 @@ -37,10 +39,10 @@ d) 内存回收 向用户态返回一个通用数据结构，对应每pid或每tgid的统计信息。延时计数功能填写 该数据结构的特定字段。见 - include/linux/taskstats.h + include/uapi/linux/taskstats.h 其描述了延时计数相关字段。系统通常以计数器形式返回 CPU、同步块 I/O、交换、内存 -回收等的累积延时。 +回收、页缓存抖动、直接规整等的累积延时。 取任务某计数器两个连续读数的差值，将得到任务在该时间间隔内等待对应资源的总延时。 @@ -72,40 +74,36 @@ kernel.task_delayacct进行开关。注意，只有在启用延时计数后启 getdelays命令的一般格式:: - getdelays [-t tgid] [-p pid] [-c cmd...] + getdelays [-dilv] [-t tgid] [-p pid] 获取pid为10的任务从系统启动后的延时信息:: - # ./getdelays -p 10 + # ./getdelays -d -p 10 （输出信息和下例相似） 获取所有tgid为5的任务从系统启动后的总延时信息:: - # ./getdelays -t 5 - - - CPU count real total virtual total delay total - 7876 92005750 100000000 24001500 - IO count delay total - 0 0 - SWAP count delay total - 0 0 - RECLAIM count delay total - 0 0 - -获取指定简单命令运行时的延时信息:: - - # ./getdelays -c ls / - - bin data1 data3 data5 dev home media opt root srv sys usr - boot data2 data4 data6 etc lib mnt proc sbin subdomain tmp var - - - CPU count real total virtual total delay total - 6 4000250 4000000 0 - IO count delay total - 0 0 - SWAP count delay total - 0 0 - RECLAIM count delay total - 0 0 + # ./getdelays -d -t 5 + print delayacct stats ON + TGID 5 + + + CPU count real total virtual total delay total delay average + 8 7000000 6872122 3382277 0.423ms + IO count delay total delay average + 0 0 0ms + SWAP count delay total delay average + 0 0 0ms + RECLAIM count delay total delay average + 0 0 0ms + THRASHING count delay total delay average + 0 0 0ms + COMPACT count delay total delay average + 0 0 0ms + +获取pid为1的IO计数，它只和-p一起使用:: + # ./getdelays -i -p 1 + printing IO accounting + linuxrc: read=65536, write=0, cancelled_write=0 + +上面的命令与-v一起使用，可以获取更多调试信息。 diff --git a/Documentation/translations/zh_CN/admin-guide/README.rst b/Documentation/translations/zh_CN/admin-guide/README.rst index d20949e8bf6f..e679cbc3c89d 100644 --- a/Documentation/translations/zh_CN/admin-guide/README.rst +++ b/Documentation/translations/zh_CN/admin-guide/README.rst @@ -6,10 +6,10 @@ 吴想成 Wu XiangCheng <bobwxc@email.cn> -Linux内核5.x版本 <http://kernel.org/> +Linux内核6.x版本 <http://kernel.org/> ========================================= -以下是Linux版本5的发行注记。仔细阅读它们， +以下是Linux版本6的发行注记。仔细阅读它们， 它们会告诉你这些都是什么，解释如何安装内核，以及遇到问题时该如何做。 什么是Linux？ @@ -61,27 +61,27 @@ Linux内核5.x版本 <http://kernel.org/> - 如果您要安装完整的源代码，请把内核tar档案包放在您有权限的目录中（例如您 的主目录）并将其解包:: - xz -cd linux-5.x.tar.xz | tar xvf - + xz -cd linux-6.x.tar.xz | tar xvf - 将“X”替换成最新内核的版本号。 【不要】使用 /usr/src/linux 目录！这里有一组库头文件使用的内核头文件 （通常是不完整的）。它们应该与库匹配，而不是被内核的变化搞得一团糟。 - - 您还可以通过打补丁在5.x版本之间升级。补丁以xz格式分发。要通过打补丁进行 - 安装，请获取所有较新的补丁文件，进入内核源代码（linux-5.x）的目录并 + - 您还可以通过打补丁在6.x版本之间升级。补丁以xz格式分发。要通过打补丁进行 + 安装，请获取所有较新的补丁文件，进入内核源代码（linux-6.x）的目录并 执行:: - xz -cd ../patch-5.x.xz | patch -p1 + xz -cd ../patch-6.x.xz | patch -p1 请【按顺序】替换所有大于当前源代码树版本的“x”，这样就可以了。您可能想要 删除备份文件（文件名类似xxx~ 或 xxx.orig)，并确保没有失败的补丁（文件名 类似xxx# 或 xxx.rej）。如果有，不是你就是我犯了错误。 - 与5.x内核的补丁不同，5.x.y内核（也称为稳定版内核）的补丁不是增量的，而是 - 直接应用于基本的5.x内核。例如，如果您的基本内核是5.0，并且希望应用5.0.3 - 补丁，则不应先应用5.0.1和5.0.2的补丁。类似地，如果您运行的是5.0.2内核， - 并且希望跳转到5.0.3，那么在应用5.0.3补丁之前，必须首先撤销5.0.2补丁 + 与6.x内核的补丁不同，6.x.y内核（也称为稳定版内核）的补丁不是增量的，而是 + 直接应用于基本的6.x内核。例如，如果您的基本内核是6.0，并且希望应用6.0.3 + 补丁，则不应先应用6.0.1和6.0.2的补丁。类似地，如果您运行的是6.0.2内核， + 并且希望跳转到6.0.3，那么在应用6.0.3补丁之前，必须首先撤销6.0.2补丁 （即patch -R）。更多关于这方面的内容，请阅读 :ref:`Documentation/process/applying-patches.rst <applying_patches>` 。 @@ -103,7 +103,7 @@ Linux内核5.x版本 <http://kernel.org/> 软件要求 --------- - 编译和运行5.x内核需要各种软件包的最新版本。请参考 + 编译和运行6.x内核需要各种软件包的最新版本。请参考 :ref:`Documentation/process/changes.rst <changes>` 来了解最低版本要求以及如何升级软件包。请注意，使用过旧版本的这些包可能会 导致很难追踪的间接错误，因此不要以为在生成或操作过程中出现明显问题时可以 @@ -116,12 +116,12 @@ Linux内核5.x版本 <http://kernel.org/> ``make O=output/dir`` 选项可以为输出文件（包括 .config）指定备用位置。 例如:: - kernel source code: /usr/src/linux-5.x + kernel source code: /usr/src/linux-6.x build directory: /home/name/build/kernel 要配置和构建内核，请使用:: - cd /usr/src/linux-5.x + cd /usr/src/linux-6.x make O=/home/name/build/kernel menuconfig make O=/home/name/build/kernel sudo make O=/home/name/build/kernel modules_install install @@ -227,8 +227,6 @@ Linux内核5.x版本 <http://kernel.org/> - 确保您至少有gcc 5.1可用。 有关更多信息，请参阅 :ref:`Documentation/process/changes.rst <changes>` 。 - 请注意，您仍然可以使用此内核运行a.out用户程序。 - - 执行 ``make`` 来创建压缩内核映像。如果您安装了lilo以适配内核makefile， 那么也可以进行 ``make install`` ，但是您可能需要先检查特定的lilo设置。 @@ -282,67 +280,12 @@ Linux内核5.x版本 <http://kernel.org/> 若遇到问题 ----------- - - 如果您发现了一些可能由于内核缺陷所导致的问题，请检查MAINTAINERS（维护者） - 文件看看是否有人与令您遇到麻烦的内核部分相关。如果无人在此列出，那么第二 - 个最好的方案就是把它们发给我（torvalds@linux-foundation.org），也可能发送 - 到任何其他相关的邮件列表或新闻组。 - - - 在所有的缺陷报告中，【请】告诉我们您在说什么内核，如何复现问题，以及您的 - 设置是什么的（使用您的常识）。如果问题是新的，请告诉我；如果问题是旧的， - 请尝试告诉我您什么时候首次注意到它。 - - - 如果缺陷导致如下消息:: - - unable to handle kernel paging request at address C0000010 - Oops: 0002 - EIP: 0010:XXXXXXXX - eax: xxxxxxxx ebx: xxxxxxxx ecx: xxxxxxxx edx: xxxxxxxx - esi: xxxxxxxx edi: xxxxxxxx ebp: xxxxxxxx - ds: xxxx es: xxxx fs: xxxx gs: xxxx - Pid: xx, process nr: xx - xx xx xx xx xx xx xx xx xx xx - - 或者类似的内核调试信息显示在屏幕上或在系统日志里，请【如实】复制它。 - 可能对你来说转储（dump）看起来不可理解，但它确实包含可能有助于调试问题的 - 信息。转储上方的文本也很重要：它说明了内核转储代码的原因（在上面的示例中， - 是由于内核指针错误）。更多关于如何理解转储的信息，请参见 - Documentation/admin-guide/bug-hunting.rst。 - - - 如果使用 CONFIG_KALLSYMS 编译内核，则可以按原样发送转储，否则必须使用 - ``ksymoops`` 程序来理解转储（但通常首选使用CONFIG_KALLSYMS编译）。 - 此实用程序可从 - https://www.kernel.org/pub/linux/utils/kernel/ksymoops/ 下载。 - 或者，您可以手动执行转储查找： - - - 在调试像上面这样的转储时，如果您可以查找EIP值的含义，这将非常有帮助。 - 十六进制值本身对我或其他任何人都没有太大帮助：它会取决于特定的内核设置。 - 您应该做的是从EIP行获取十六进制值（忽略 ``0010:`` ），然后在内核名字列表 - 中查找它，以查看哪个内核函数包含有问题的地址。 - - 要找到内核函数名，您需要找到与显示症状的内核相关联的系统二进制文件。就是 - 文件“linux/vmlinux”。要提取名字列表并将其与内核崩溃中的EIP进行匹配， - 请执行:: - - nm vmlinux | sort | less - - 这将为您提供一个按升序排序的内核地址列表，从中很容易找到包含有问题的地址 - 的函数。请注意，内核调试消息提供的地址不一定与函数地址完全匹配（事实上， - 这是不可能的），因此您不能只“grep”列表：不过列表将为您提供每个内核函数 - 的起点，因此通过查找起始地址低于你正在搜索的地址，但后一个函数的高于的 - 函数，你会找到您想要的。实际上，在您的问题报告中加入一些“上下文”可能是 - 一个好主意，给出相关的上下几行。 - - 如果您由于某些原因无法完成上述操作（如您使用预编译的内核映像或类似的映像）， - 请尽可能多地告诉我您的相关设置信息，这会有所帮助。有关详细信息请阅读 - ‘Documentation/admin-guide/reporting-issues.rst’。 - - - 或者，您可以在正在运行的内核上使用gdb（只读的；即不能更改值或设置断点）。 - 为此，请首先使用-g编译内核；适当地编辑arch/x86/Makefile，然后执行 ``make - clean`` 。您还需要启用CONFIG_PROC_FS（通过 ``make config`` ）。 - - 使用新内核重新启动后，执行 ``gdb vmlinux /proc/kcore`` 。现在可以使用所有 - 普通的gdb命令。查找系统崩溃点的命令是 ``l *0xXXXXXXXX`` （将xxx替换为EIP - 值）。 - - 用gdb无法调试一个当前未运行的内核是由于gdb（错误地）忽略了编译内核的起始 - 偏移量。 +如果您发现了一些可能由于内核缺陷所导致的问题，请参阅： +Documentation/translations/zh_CN/admin-guide/reporting-issues.rst 。 + +想要理解内核错误报告，请参阅： +Documentation/translations/zh_CN/admin-guide/bug-hunting.rst 。 + +更多用GDB调试内核的信息，请参阅： +Documentation/translations/zh_CN/dev-tools/gdb-kernel-debugging.rst +和 Documentation/dev-tools/kgdb.rst 。 diff --git a/Documentation/translations/zh_CN/admin-guide/bootconfig.rst b/Documentation/translations/zh_CN/admin-guide/bootconfig.rst new file mode 100644 index 000000000000..072d17f5f199 --- /dev/null +++ b/Documentation/translations/zh_CN/admin-guide/bootconfig.rst @@ -0,0 +1,293 @@ +.. SPDX-License-Identifier: GPL-2.0 + +.. include:: ../disclaimer-zh_CN.rst + +:Original: Documentation/admin-guide/bootconfig.rst + +:译者: 吴想成 Wu XiangCheng <bobwxc@email.cn> + +======== +引导配置 +======== + +:作者: Masami Hiramatsu <mhiramat@kernel.org> + +概述 +==== + +引导配置扩展了现有的内核命令行，以一种更有效率的方式在引导内核时进一步支持 +键值数据。这允许管理员传递一份结构化关键字的配置文件。 + +配置文件语法 +============ + +引导配置文件的语法采用非常简单的键值结构。每个关键字由点连接的单词组成，键 +和值由 ``=`` 连接。值以分号（ ``;`` ）或换行符（ ``\n`` ）结尾。数组值中每 +个元素由逗号（ ``,`` ）分隔。:: + + KEY[.WORD[...]] = VALUE[, VALUE2[...]][;] + +与内核命令行语法不同，逗号和 ``=`` 周围允许有空格。 + +关键字只允许包含字母、数字、连字符（ ``-`` ）和下划线（ ``_`` ）。值可包含 +可打印字符和空格，但分号（ ``;`` ）、换行符（ ``\n`` ）、逗号（ ``,`` ）、 +井号（ ``#`` ）和右大括号（ ``}`` ）等分隔符除外。 + +如果你需要在值中使用这些分隔符，可以用双引号（ ``"VALUE"`` ）或单引号 +（ ``'VALUE'`` ）括起来。注意，引号无法转义。 + +键的值可以为空或不存在。这些键用于检查该键是否存在（类似布尔值）。 + +键值语法 +-------- + +引导配置文件语法允许用户通过大括号合并键名部分相同的关键字。例如:: + + foo.bar.baz = value1 + foo.bar.qux.quux = value2 + +也可以写成:: + + foo.bar { + baz = value1 + qux.quux = value2 + } + +或者更紧凑一些，写成:: + + foo.bar { baz = value1; qux.quux = value2 } + +在这两种样式中，引导解析时相同的关键字都会自动合并。因此可以追加类似的树或 +键值。 + +相同关键字的值 +-------------- + +禁止两个或多个值或数组共享同一个关键字。例如:: + + foo = bar, baz + foo = qux # !错误! 我们不可以重定义相同的关键字 + +如果你想要更新值，必须显式使用覆盖操作符 ``:=`` 。例如:: + + foo = bar, baz + foo := qux + +这样 ``foo`` 关键字的值就变成了 ``qux`` 。这对于通过添加（部分）自定义引导 +配置来覆盖默认值非常有用，免于解析默认引导配置。 + +如果你想对现有关键字追加值作为数组成员，可以使用 ``+=`` 操作符。例如:: + + foo = bar, baz + foo += qux + +这样， ``foo`` 关键字就同时拥有了 ``bar`` ， ``baz`` 和 ``qux`` 。 + +此外，父关键字下可同时存在值和子关键字。 +例如，下列配置是可行的。:: + + foo = value1 + foo.bar = value2 + foo := value3 # 这会更新foo的值。 + +注意，裸值不能直接放进结构化关键字中，必须在大括号外定义它。例如:: + + foo { + bar = value1 + bar { + baz = value2 + qux = value3 + } + } + +同时，关键字下值节点的顺序是固定的。如果值和子关键字同时存在，值永远是该关 +键字的第一个子节点。因此如果用户先指定子关键字，如:: + + foo.bar = value1 + foo = value2 + +则在程序（和/proc/bootconfig）中，它会按如下显示:: + + foo = value2 + foo.bar = value1 + +注释 +---- + +配置语法接受shell脚本风格的注释。注释以井号（ ``#`` ）开始，到换行符 +（ ``\n`` ）结束。 + +:: + + # comment line + foo = value # value is set to foo. + bar = 1, # 1st element + 2, # 2nd element + 3 # 3rd element + +会被解析为:: + + foo = value + bar = 1, 2, 3 + +注意你不能把注释放在值和分隔符（ ``,`` 或 ``;`` ）之间。如下配置语法是错误的:: + + key = 1 # comment + ,2 + + +/proc/bootconfig +================ + +/proc/bootconfig是引导配置的用户空间接口。与/proc/cmdline不同，此文件内容以 +键值列表样式显示。 +每个键值对一行，样式如下:: + + KEY[.WORDS...] = "[VALUE]"[,"VALUE2"...] + + +用引导配置引导内核 +================== + +用引导配置引导内核有两种方法：将引导配置附加到initrd镜像或直接嵌入内核中。 + +*initrd: initial RAM disk，初始内存磁盘* + +将引导配置附加到initrd +---------------------- + +由于默认情况下引导配置文件是用initrd加载的，因此它将被添加到initrd（initramfs） +镜像文件的末尾，其中包含填充、大小、校验值和12字节幻数，如下所示:: + + [initrd][bootconfig][padding][size(le32)][checksum(le32)][#BOOTCONFIG\n] + +大小和校验值为小端序存放的32位无符号值。 + +当引导配置被加到initrd镜像时，整个文件大小会对齐到4字节。空字符（ ``\0`` ） +会填补对齐空隙。因此 ``size`` 就是引导配置文件的长度+填充的字节。 + +Linux内核在内存中解码initrd镜像的最后部分以获取引导配置数据。由于这种“背负式” +的方法，只要引导加载器传递了正确的initrd文件大小，就无需更改或更新引导加载器 +和内核镜像本身。如果引导加载器意外传递了更长的大小，内核将无法找到引导配置数 +据。 + +Linux内核在tools/bootconfig下提供了 ``bootconfig`` 命令来完成此操作，管理员 +可以用它从initrd镜像中删除或追加配置文件。你可以用以下命令来构建它:: + + # make -C tools/bootconfig + +要向initrd镜像添加你的引导配置文件，请按如下命令操作（旧数据会自动移除）:: + + # tools/bootconfig/bootconfig -a your-config /boot/initrd.img-X.Y.Z + +要从镜像中移除配置，可以使用-d选项:: + + # tools/bootconfig/bootconfig -d /boot/initrd.img-X.Y.Z + +然后在内核命令行上添加 ``bootconfig`` 告诉内核去initrd文件末尾寻找内核配置。 + +将引导配置嵌入内核 +------------------ + +如果你不能使用initrd，也可以通过Kconfig选项将引导配置文件嵌入内核中。在此情 +况下，你需要用以下选项重新编译内核:: + + CONFIG_BOOT_CONFIG_EMBED=y + CONFIG_BOOT_CONFIG_EMBED_FILE="/引导配置/文件/的/路径" + +``CONFIG_BOOT_CONFIG_EMBED_FILE`` 需要从源码树或对象树开始的引导配置文件的 +绝对/相对路径。内核会将其嵌入作为默认引导配置。 + +与将引导配置附加到initrd一样，你也需要在内核命令行上添加 ``bootconfig`` 告诉 +内核去启用内嵌的引导配置。 + +注意，即使你已经设置了此选项，仍可用附加到initrd的其他引导配置覆盖内嵌的引导 +配置。 + +通过引导配置传递内核参数 +======================== + +除了内核命令行，引导配置也可以用于传递内核参数。所有 ``kernel`` 关键字下的键 +值对都将直接传递给内核命令行。此外， ``init`` 下的键值对将通过命令行传递给 +init进程。参数按以下顺序与用户给定的内核命令行字符串相连，因此命令行参数可以 +覆盖引导配置参数（这取决于子系统如何处理参数，但通常前面的参数将被后面的参数 +覆盖）:: + + [bootconfig params][cmdline params] -- [bootconfig init params][cmdline init params] + +如果引导配置文件给出的kernel/init参数是:: + + kernel { + root = 01234567-89ab-cdef-0123-456789abcd + } + init { + splash + } + +这将被复制到内核命令行字符串中，如下所示:: + + root="01234567-89ab-cdef-0123-456789abcd" -- splash + +如果用户给出的其他命令行是:: + + ro bootconfig -- quiet + +则最后的内核命令行如下:: + + root="01234567-89ab-cdef-0123-456789abcd" ro bootconfig -- splash quiet + + +配置文件的限制 +============== + +当前最大的配置大小是32KB，关键字总数（不是键值条目）必须少于1024个节点。 +注意：这不是条目数而是节点数，条目必须消耗超过2个节点（一个关键字和一个值）。 +所以从理论上讲最多512个键值对。如果关键字平均包含3个单词，则可有256个键值对。 +在大多数情况下，配置项的数量将少于100个条目，小于8KB，因此这应该足够了。如果 +节点数超过1024，解析器将返回错误，即使文件大小小于32KB。（请注意，此最大尺寸 +不包括填充的空字符。） +无论如何，因为 ``bootconfig`` 命令在附加启动配置到initrd映像时会验证它，用户 +可以在引导之前注意到它。 + + +引导配置API +=========== + +用户可以查询或遍历键值对，也可以查找（前缀）根关键字节点，并在查找该节点下的 +键值。 + +如果您有一个关键字字符串，则可以直接使用 xbc_find_value() 查询该键的值。如果 +你想知道引导配置里有哪些关键字，可以使用 xbc_for_each_key_value() 迭代键值对。 +请注意，您需要使用 xbc_array_for_each_value() 访问数组的值，例如:: + + vnode = NULL; + xbc_find_value("key.word", &vnode); + if (vnode && xbc_node_is_array(vnode)) + xbc_array_for_each_value(vnode, value) { + printk("%s ", value); + } + +如果您想查找具有前缀字符串的键，可以使用 xbc_find_node() 通过前缀字符串查找 +节点，然后用 xbc_node_for_each_key_value() 迭代前缀节点下的键。 + +但最典型的用法是获取前缀下的命名值或前缀下的命名数组，例如:: + + root = xbc_find_node("key.prefix"); + value = xbc_node_find_value(root, "option", &vnode); + ... + xbc_node_for_each_array_value(root, "array-option", value, anode) { + ... + } + +这将访问值“key.prefix.option”的值和“key.prefix.array-option”的数组。 + +锁是不需要的，因为在初始化之后配置只读。如果需要修改，必须复制所有数据和关键字。 + + +函数与结构体 +============ + +相关定义的kernel-doc参见： + + - include/linux/bootconfig.h + - lib/bootconfig.c diff --git a/Documentation/translations/zh_CN/admin-guide/index.rst b/Documentation/translations/zh_CN/admin-guide/index.rst index 548e57f4b3f1..ac2960da33e6 100644 --- a/Documentation/translations/zh_CN/admin-guide/index.rst +++ b/Documentation/translations/zh_CN/admin-guide/index.rst @@ -20,15 +20,15 @@ Linux 内核用户和管理员指南 Todolist: - kernel-parameters - devices - sysctl/index +* kernel-parameters +* devices +* sysctl/index 本节介绍CPU漏洞及其缓解措施。 Todolist: - hw-vuln/index +* hw-vuln/index 下面的一组文档，针对的是试图跟踪问题和bug的用户。 @@ -36,6 +36,7 @@ Todolist: :maxdepth: 1 reporting-issues + reporting-regressions security-bugs bug-hunting bug-bisect @@ -44,18 +45,17 @@ Todolist: Todolist: - reporting-bugs - ramoops - dynamic-debug-howto - kdump/index - perf/index +* ramoops +* dynamic-debug-howto +* kdump/index +* perf/index 这是应用程序开发人员感兴趣的章节的开始。可以在这里找到涵盖内核ABI各个 方面的文档。 Todolist: - sysfs-rules +* sysfs-rules 本手册的其余部分包括各种指南，介绍如何根据您的喜好配置内核的特定行为。 @@ -63,67 +63,67 @@ Todolist: .. toctree:: :maxdepth: 1 + bootconfig clearing-warn-once cpu-load cputopology lockup-watchdogs unicode sysrq + mm/index Todolist: - acpi/index - aoe/index - auxdisplay/index - bcache - binderfs - binfmt-misc - blockdev/index - bootconfig - braille-console - btmrvl - cgroup-v1/index - cgroup-v2 - cifs/index - dell_rbu - device-mapper/index - edid - efi-stub - ext4 - nfs/index - gpio/index - highuid - hw_random - initrd - iostats - java - jfs - kernel-per-CPU-kthreads - laptops/index - lcd-panel-cgram - ldm - LSM/index - md - media/index - mm/index - module-signing - mono - namespaces/index - numastat - parport - perf-security - pm/index - pnp - rapidio - ras - rtc - serial-console - svga - thunderbolt - ufs - vga-softcursor - video-output - xfs +* acpi/index +* aoe/index +* auxdisplay/index +* bcache +* binderfs +* binfmt-misc +* blockdev/index +* braille-console +* btmrvl +* cgroup-v1/index +* cgroup-v2 +* cifs/index +* dell_rbu +* device-mapper/index +* edid +* efi-stub +* ext4 +* nfs/index +* gpio/index +* highuid +* hw_random +* initrd +* iostats +* java +* jfs +* kernel-per-CPU-kthreads +* laptops/index +* lcd-panel-cgram +* ldm +* LSM/index +* md +* media/index +* module-signing +* mono +* namespaces/index +* numastat +* parport +* perf-security +* pm/index +* pnp +* rapidio +* ras +* rtc +* serial-console +* svga +* thunderbolt +* ufs +* vga-softcursor +* video-output +* xfs .. only:: subproject and html diff --git a/Documentation/translations/zh_CN/admin-guide/mm/damon/index.rst b/Documentation/translations/zh_CN/admin-guide/mm/damon/index.rst new file mode 100644 index 000000000000..30c69e1f44fe --- /dev/null +++ b/Documentation/translations/zh_CN/admin-guide/mm/damon/index.rst @@ -0,0 +1,28 @@ +.. SPDX-License-Identifier: GPL-2.0 +.. include:: ../../../disclaimer-zh_CN.rst + +:Original: Documentation/admin-guide/mm/damon/index.rst + +:翻译: + + 司延腾 Yanteng Si <siyanteng@loongson.cn> + +:校译: + +============ +监测数据访问 +============ + +:doc:`DAMON </mm/damon/index>` 允许轻量级的数据访问监测。使用DAMON， +用户可以分析他们系统的内存访问模式，并优化它们。 + +.. toctree:: + :maxdepth: 2 + + start + usage + reclaim + + + + diff --git a/Documentation/translations/zh_CN/admin-guide/mm/damon/reclaim.rst b/Documentation/translations/zh_CN/admin-guide/mm/damon/reclaim.rst new file mode 100644 index 000000000000..c976f3e33ffd --- /dev/null +++ b/Documentation/translations/zh_CN/admin-guide/mm/damon/reclaim.rst @@ -0,0 +1,232 @@ +.. SPDX-License-Identifier: GPL-2.0 +.. include:: ../../../disclaimer-zh_CN.rst + +:Original: Documentation/admin-guide/mm/damon/reclaim.rst + +:翻译: + + 司延腾 Yanteng Si <siyanteng@loongson.cn> + +:校译: + +=============== +基于DAMON的回收 +=============== + +基于DAMON的回收（DAMON_RECLAIM）是一个静态的内核模块，旨在用于轻度内存压力下的主动和轻 +量级的回收。它的目的不是取代基于LRU列表的页面回收，而是有选择地用于不同程度的内存压力和要 +求。 + +哪些地方需要主动回收？ +====================== + +在一般的内存超量使用（over-committed systems，虚拟化相关术语）的系统上，主动回收冷页 +有助于节省内存和减少延迟高峰，这些延迟是由直接回收进程或kswapd的CPU消耗引起的，同时只产 +生最小的性能下降 [1]_ [2]_ 。 + +基于空闲页报告 [3]_ 的内存过度承诺的虚拟化系统就是很好的例子。在这样的系统中，客户机 +向主机报告他们的空闲内存，而主机则将报告的内存重新分配给其他客户。因此，系统的内存得到了充 +分的利用。然而，客户可能不那么节省内存，主要是因为一些内核子系统和用户空间应用程序被设计为 +使用尽可能多的内存。然后，客户机可能只向主机报告少量的内存是空闲的，导致系统的内存利用率下降。 +在客户中运行主动回收可以缓解这个问题。 + +它是如何工作的？ +================ + +DAMON_RECLAIM找到在特定时间内没有被访问的内存区域并分页。为了避免它在分页操作中消耗过多 +的CPU，可以配置一个速度限制。在这个速度限制下，它首先分页出那些没有被访问过的内存区域。系 +统管理员还可以配置在什么情况下这个方案应该自动激活和停用三个内存压力水位。 + +接口: 模块参数 +============== + +要使用这个功能，你首先要确保你的系统运行在一个以 ``CONFIG_DAMON_RECLAIM=y`` 构建的内 +核上。 + +为了让系统管理员启用或禁用它，并为给定的系统进行调整，DAMON_RECLAIM利用了模块参数。也就 +是说，你可以把 ``damon_reclaim.<parameter>=<value>`` 放在内核启动命令行上，或者把 +适当的值写入 ``/sys/modules/damon_reclaim/parameters/<parameter>`` 文件。 + +注意，除 ``启用`` 外的参数值只在DAMON_RECLAIM启动时应用。因此，如果你想在运行时应用新 +的参数值，而DAMON_RECLAIM已经被启用，你应该通过 ``启用`` 的参数文件禁用和重新启用它。 +在重新启用之前，应将新的参数值写入适当的参数值中。 + +下面是每个参数的描述。 + +enabled +------- + +启用或禁用DAMON_RECLAIM。 + +你可以通过把这个参数的值设置为 ``Y`` 来启用DAMON_RCLAIM，把它设置为 ``N`` 可以禁用 +DAMON_RECLAIM。注意，由于基于水位的激活条件，DAMON_RECLAIM不能进行真正的监测和回收。 +这一点请参考下面关于水位参数的描述。 + +min_age +------- + +识别冷内存区域的时间阈值，单位是微秒。 + +如果一个内存区域在这个时间或更长的时间内没有被访问，DAMON_RECLAIM会将该区域识别为冷的， +并回收它。 + +默认为120秒。 + +quota_ms +-------- + +回收的时间限制，以毫秒为单位。 + +DAMON_RECLAIM 试图在一个时间窗口（quota_reset_interval_ms）内只使用到这个时间，以 +尝试回收冷页。这可以用来限制DAMON_RECLAIM的CPU消耗。如果该值为零，则该限制被禁用。 + +默认为10ms。 + +quota_sz +-------- + +回收的内存大小限制，单位为字节。 + +DAMON_RECLAIM 收取在一个时间窗口（quota_reset_interval_ms）内试图回收的内存量，并 +使其不超过这个限制。这可以用来限制CPU和IO的消耗。如果该值为零，则限制被禁用。 + +默认情况下是128 MiB。 + +quota_reset_interval_ms +----------------------- + +时间/大小配额收取重置间隔，单位为毫秒。 + +时间（quota_ms）和大小（quota_sz）的配额的目标重置间隔。也就是说，DAMON_RECLAIM在 +尝试回收‘不’超过quota_ms毫秒或quota_sz字节的内存。 + +默认为1秒。 + +wmarks_interval +--------------- + +当DAMON_RECLAIM被启用但由于其水位规则而不活跃时，在检查水位之前的最小等待时间。 + +wmarks_high +----------- + +高水位的可用内存率（每千字节）。 + +如果系统的可用内存（以每千字节为单位）高于这个数值，DAMON_RECLAIM就会变得不活跃，所以 +它什么也不做，只是定期检查水位。 + +wmarks_mid +---------- + +中间水位的可用内存率（每千字节）。 + +如果系统的空闲内存（以每千字节为单位）在这个和低水位线之间，DAMON_RECLAIM就会被激活， +因此开始监测和回收。 + +wmarks_low +---------- + +低水位的可用内存率（每千字节）。 + +如果系统的空闲内存（以每千字节为单位）低于这个数值，DAMON_RECLAIM就会变得不活跃，所以 +它除了定期检查水位外什么都不做。在这种情况下，系统会退回到基于LRU列表的页面粒度回收逻辑。 + +sample_interval +--------------- + +监测的采样间隔，单位是微秒。 + +DAMON用于监测冷内存的采样间隔。更多细节请参考DAMON文档 (:doc:`usage`) 。 + +aggr_interval +------------- + +监测的聚集间隔，单位是微秒。 + +DAMON对冷内存监测的聚集间隔。更多细节请参考DAMON文档 (:doc:`usage`)。 + +min_nr_regions +-------------- + +监测区域的最小数量。 + +DAMON用于冷内存监测的最小监测区域数。这可以用来设置监测质量的下限。但是，设 +置的太高可能会导致监测开销的增加。更多细节请参考DAMON文档 (:doc:`usage`) 。 + +max_nr_regions +-------------- + +监测区域的最大数量。 + +DAMON用于冷内存监测的最大监测区域数。这可以用来设置监测开销的上限值。但是， +设置得太低可能会导致监测质量不好。更多细节请参考DAMON文档 (:doc:`usage`) 。 + +monitor_region_start +-------------------- + +目标内存区域的物理地址起点。 + +DAMON_RECLAIM将对其进行工作的内存区域的起始物理地址。也就是说，DAMON_RECLAIM +将在这个区域中找到冷的内存区域并进行回收。默认情况下，该区域使用最大系统内存区。 + +monitor_region_end +------------------ + +目标内存区域的结束物理地址。 + +DAMON_RECLAIM将对其进行工作的内存区域的末端物理地址。也就是说，DAMON_RECLAIM将 +在这个区域内找到冷的内存区域并进行回收。默认情况下，该区域使用最大系统内存区。 + +kdamond_pid +----------- + +DAMON线程的PID。 + +如果DAMON_RECLAIM被启用，这将成为工作线程的PID。否则，为-1。 + +nr_reclaim_tried_regions +------------------------ + +试图通过DAMON_RECLAIM回收的内存区域的数量。 + +bytes_reclaim_tried_regions +--------------------------- + +试图通过DAMON_RECLAIM回收的内存区域的总字节数。 + +nr_reclaimed_regions +-------------------- + +通过DAMON_RECLAIM成功回收的内存区域的数量。 + +bytes_reclaimed_regions +----------------------- + +通过DAMON_RECLAIM成功回收的内存区域的总字节数。 + +nr_quota_exceeds +---------------- + +超过时间/空间配额限制的次数。 + +例子 +==== + +下面的运行示例命令使DAMON_RECLAIM找到30秒或更长时间没有访问的内存区域并“回收”？ +为了避免DAMON_RECLAIM在分页操作中消耗过多的CPU时间，回收被限制在每秒1GiB以内。 +它还要求DAMON_RECLAIM在系统的可用内存率超过50%时不做任何事情，但如果它低于40%时 +就开始真正的工作。如果DAMON_RECLAIM没有取得进展，因此空闲内存率低于20%，它会要求 +DAMON_RECLAIM再次什么都不做，这样我们就可以退回到基于LRU列表的页面粒度回收了:: + + # cd /sys/modules/damon_reclaim/parameters + # echo 30000000 > min_age + # echo $((1 * 1024 * 1024 * 1024)) > quota_sz + # echo 1000 > quota_reset_interval_ms + # echo 500 > wmarks_high + # echo 400 > wmarks_mid + # echo 200 > wmarks_low + # echo Y > enabled + +.. [1] https://research.google/pubs/pub48551/ +.. [2] https://lwn.net/Articles/787611/ +.. [3] https://www.kernel.org/doc/html/latest/mm/free_page_reporting.html diff --git a/Documentation/translations/zh_CN/admin-guide/mm/damon/start.rst b/Documentation/translations/zh_CN/admin-guide/mm/damon/start.rst new file mode 100644 index 000000000000..67d1b49481dc --- /dev/null +++ b/Documentation/translations/zh_CN/admin-guide/mm/damon/start.rst @@ -0,0 +1,132 @@ +.. SPDX-License-Identifier: GPL-2.0 +.. include:: ../../../disclaimer-zh_CN.rst + +:Original: Documentation/admin-guide/mm/damon/start.rst + +:翻译: + + 司延腾 Yanteng Si <siyanteng@loongson.cn> + +:校译: + +======== +入门指南 +======== + +本文通过演示DAMON的默认用户空间工具，简要地介绍了如何使用DAMON。请注意，为了简洁 +起见，本文档只描述了它的部分功能。更多细节请参考该工具的使用文档。 +`doc <https://github.com/awslabs/damo/blob/next/USAGE.md>`_ . + + +前提条件 +======== + +内核 +---- + +首先，你要确保你当前系统中跑的内核构建时选定了这个功能选项 ``CONFIG_DAMON_*=y``. + + +用户空间工具 +------------ + +在演示中，我们将使用DAMON的默认用户空间工具，称为DAMON Operator（DAMO）。它可以在 +https://github.com/awslabs/damo找到。下面的例子假设DAMO在你的$PATH上。当然，但 +这并不是强制性的。 + +因为DAMO使用的是DAMON的debugfs接口(详情请参考 :doc:`usage` 中的使用方法) 你应该 +确保debugfs被挂载。手动挂载它，如下所示:: + + # mount -t debugfs none /sys/kernel/debug/ + +或者在你的 ``/etc/fstab`` 文件中添加以下一行，这样你的系统就可以在启动时自动挂载 +debugfs了:: + + debugfs /sys/kernel/debug debugfs defaults 0 0 + + +记录数据访问模式 +================ + +下面的命令记录了一个程序的内存访问模式，并将监测结果保存到文件中。 :: + + $ git clone https://github.com/sjp38/masim + $ cd masim; make; ./masim ./configs/zigzag.cfg & + $ sudo damo record -o damon.data $(pidof masim) + +命令的前两行下载了一个人工内存访问生成器程序并在后台运行。生成器将重复地逐一访问两个 +100 MiB大小的内存区域。你可以用你的真实工作负载来代替它。最后一行要求 ``damo`` 将 +访问模式记录在 ``damon.data`` 文件中。 + + +将记录的模式可视化 +================== + +你可以在heatmap中直观地看到这种模式，显示哪个内存区域（X轴）何时被访问（Y轴）以及访 +问的频率（数字）。:: + + $ sudo damo report heats --heatmap stdout + 22222222222222222222222222222222222222211111111111111111111111111111111111111100 + 44444444444444444444444444444444444444434444444444444444444444444444444444443200 + 44444444444444444444444444444444444444433444444444444444444444444444444444444200 + 33333333333333333333333333333333333333344555555555555555555555555555555555555200 + 33333333333333333333333333333333333344444444444444444444444444444444444444444200 + 22222222222222222222222222222222222223355555555555555555555555555555555555555200 + 00000000000000000000000000000000000000288888888888888888888888888888888888888400 + 00000000000000000000000000000000000000288888888888888888888888888888888888888400 + 33333333333333333333333333333333333333355555555555555555555555555555555555555200 + 88888888888888888888888888888888888888600000000000000000000000000000000000000000 + 88888888888888888888888888888888888888600000000000000000000000000000000000000000 + 33333333333333333333333333333333333333444444444444444444444444444444444444443200 + 00000000000000000000000000000000000000288888888888888888888888888888888888888400 + [...] + # access_frequency: 0 1 2 3 4 5 6 7 8 9 + # x-axis: space (139728247021568-139728453431248: 196.848 MiB) + # y-axis: time (15256597248362-15326899978162: 1 m 10.303 s) + # resolution: 80x40 (2.461 MiB and 1.758 s for each character) + +你也可以直观地看到工作集的大小分布，按大小排序。:: + + $ sudo damo report wss --range 0 101 10 + # <percentile> <wss> + # target_id 18446632103789443072 + # avr: 107.708 MiB + 0 0 B | | + 10 95.328 MiB |**************************** | + 20 95.332 MiB |**************************** | + 30 95.340 MiB |**************************** | + 40 95.387 MiB |**************************** | + 50 95.387 MiB |**************************** | + 60 95.398 MiB |**************************** | + 70 95.398 MiB |**************************** | + 80 95.504 MiB |**************************** | + 90 190.703 MiB |********************************************************* | + 100 196.875 MiB |***********************************************************| + +在上述命令中使用 ``--sortby`` 选项，可以显示工作集的大小是如何按时间顺序变化的。:: + + $ sudo damo report wss --range 0 101 10 --sortby time + # <percentile> <wss> + # target_id 18446632103789443072 + # avr: 107.708 MiB + 0 3.051 MiB | | + 10 190.703 MiB |***********************************************************| + 20 95.336 MiB |***************************** | + 30 95.328 MiB |***************************** | + 40 95.387 MiB |***************************** | + 50 95.332 MiB |***************************** | + 60 95.320 MiB |***************************** | + 70 95.398 MiB |***************************** | + 80 95.398 MiB |***************************** | + 90 95.340 MiB |***************************** | + 100 95.398 MiB |***************************** | + + +数据访问模式感知的内存管理 +========================== + +以下三个命令使每一个大小>=4K的内存区域在你的工作负载中没有被访问>=60秒，就会被换掉。 :: + + $ echo "#min-size max-size min-acc max-acc min-age max-age action" > test_scheme + $ echo "4K max 0 0 60s max pageout" >> test_scheme + $ damo schemes -c test_scheme <pid of your workload> diff --git a/Documentation/translations/zh_CN/admin-guide/mm/damon/usage.rst b/Documentation/translations/zh_CN/admin-guide/mm/damon/usage.rst new file mode 100644 index 000000000000..aeae2ab65dd8 --- /dev/null +++ b/Documentation/translations/zh_CN/admin-guide/mm/damon/usage.rst @@ -0,0 +1,559 @@ +.. SPDX-License-Identifier: GPL-2.0 +.. include:: ../../../disclaimer-zh_CN.rst + +:Original: Documentation/admin-guide/mm/damon/usage.rst + +:翻译: + + 司延腾 Yanteng Si <siyanteng@loongson.cn> + +:校译: + +======== +详细用法 +======== + +DAMON 为不同的用户提供了下面这些接口。 + +- *DAMON用户空间工具。* + `这 <https://github.com/awslabs/damo>`_ 为有这特权的人， 如系统管理员，希望有一个刚好 + 可以工作的人性化界面。 + 使用它，用户可以以人性化的方式使用DAMON的主要功能。不过，它可能不会为特殊情况进行高度调整。 + 它同时支持虚拟和物理地址空间的监测。更多细节，请参考它的 `使用文档 + <https://github.com/awslabs/damo/blob/next/USAGE.md>`_。 +- *sysfs接口。* + :ref:`这 <sysfs_interface>` 是为那些希望更高级的使用DAMON的特权用户空间程序员准备的。 + 使用它，用户可以通过读取和写入特殊的sysfs文件来使用DAMON的主要功能。因此，你可以编写和使 + 用你个性化的DAMON sysfs包装程序，代替你读/写sysfs文件。 `DAMON用户空间工具 + <https://github.com/awslabs/damo>`_ 就是这种程序的一个例子 它同时支持虚拟和物理地址 + 空间的监测。注意，这个界面只提供简单的监测结果 :ref:`统计 <damos_stats>`。对于详细的监测 + 结果，DAMON提供了一个:ref:`跟踪点 <tracepoint>`。 +- *debugfs interface.* + :ref:`这 <debugfs_interface>` 几乎与:ref:`sysfs interface <sysfs_interface>` 接 + 口相同。这将在下一个LTS内核发布后被移除，所以用户应该转移到 + :ref:`sysfs interface <sysfs_interface>`。 +- *内核空间编程接口。* + :doc:`这 </mm/damon/api>` 这是为内核空间程序员准备的。使用它，用户可以通过为你编写内 + 核空间的DAMON应用程序，最灵活有效地利用DAMON的每一个功能。你甚至可以为各种地址空间扩展DAMON。 + 详细情况请参考接口 :doc:`文件 </mm/damon/api>`。 + +sysfs接口 +========= +DAMON的sysfs接口是在定义 ``CONFIG_DAMON_SYSFS`` 时建立的。它在其sysfs目录下创建多 +个目录和文件， ``<sysfs>/kernel/mm/damon/`` 。你可以通过对该目录下的文件进行写入和 +读取来控制DAMON。 + +对于一个简短的例子，用户可以监测一个给定工作负载的虚拟地址空间，如下所示:: + + # cd /sys/kernel/mm/damon/admin/ + # echo 1 > kdamonds/nr && echo 1 > kdamonds/0/contexts/nr + # echo vaddr > kdamonds/0/contexts/0/operations + # echo 1 > kdamonds/0/contexts/0/targets/nr + # echo $(pidof <workload>) > kdamonds/0/contexts/0/targets/0/pid + # echo on > kdamonds/0/state + +文件层次结构 +------------ + +DAMON sysfs接口的文件层次结构如下图所示。在下图中，父子关系用缩进表示，每个目录有 +``/`` 后缀，每个目录中的文件用逗号（","）分开。 :: + + /sys/kernel/mm/damon/admin + │ kdamonds/nr_kdamonds + │ │ 0/state,pid + │ │ │ contexts/nr_contexts + │ │ │ │ 0/operations + │ │ │ │ │ monitoring_attrs/ + │ │ │ │ │ │ intervals/sample_us,aggr_us,update_us + │ │ │ │ │ │ nr_regions/min,max + │ │ │ │ │ targets/nr_targets + │ │ │ │ │ │ 0/pid_target + │ │ │ │ │ │ │ regions/nr_regions + │ │ │ │ │ │ │ │ 0/start,end + │ │ │ │ │ │ │ │ ... + │ │ │ │ │ │ ... + │ │ │ │ │ schemes/nr_schemes + │ │ │ │ │ │ 0/action + │ │ │ │ │ │ │ access_pattern/ + │ │ │ │ │ │ │ │ sz/min,max + │ │ │ │ │ │ │ │ nr_accesses/min,max + │ │ │ │ │ │ │ │ age/min,max + │ │ │ │ │ │ │ quotas/ms,bytes,reset_interval_ms + │ │ │ │ │ │ │ │ weights/sz_permil,nr_accesses_permil,age_permil + │ │ │ │ │ │ │ watermarks/metric,interval_us,high,mid,low + │ │ │ │ │ │ │ stats/nr_tried,sz_tried,nr_applied,sz_applied,qt_exceeds + │ │ │ │ │ │ ... + │ │ │ │ ... + │ │ ... + +根 +-- + +DAMON sysfs接口的根是 ``<sysfs>/kernel/mm/damon/`` ，它有一个名为 ``admin`` 的 +目录。该目录包含特权用户空间程序控制DAMON的文件。拥有根权限的用户空间工具或deamons可以 +使用这个目录。 + +kdamonds/ +--------- + +与监测相关的信息包括请求规格和结果被称为DAMON上下文。DAMON用一个叫做kdamond的内核线程 +执行每个上下文，多个kdamonds可以并行运行。 + +在 ``admin`` 目录下，有一个目录，即``kdamonds``，它有控制kdamonds的文件存在。在开始 +时，这个目录只有一个文件，``nr_kdamonds``。向该文件写入一个数字（``N``），就会创建名为 +``0`` 到 ``N-1`` 的子目录数量。每个目录代表每个kdamond。 + +kdamonds/<N>/ +------------- + +在每个kdamond目录中，存在两个文件（``state`` 和 ``pid`` ）和一个目录( ``contexts`` )。 + +读取 ``state`` 时，如果kdamond当前正在运行，则返回 ``on`` ，如果没有运行则返回 ``off`` 。 +写入 ``on`` 或 ``off`` 使kdamond处于状态。向 ``state`` 文件写 ``update_schemes_stats`` ， +更新kdamond的每个基于DAMON的操作方案的统计文件的内容。关于统计信息的细节，请参考 +:ref:`stats section <sysfs_schemes_stats>`. + +如果状态为 ``on``，读取 ``pid`` 显示kdamond线程的pid。 + +``contexts`` 目录包含控制这个kdamond要执行的监测上下文的文件。 + +kdamonds/<N>/contexts/ +---------------------- + +在开始时，这个目录只有一个文件，即 ``nr_contexts`` 。向该文件写入一个数字( ``N`` )，就会创 +建名为``0`` 到 ``N-1`` 的子目录数量。每个目录代表每个监测背景。目前，每个kdamond只支持 +一个上下文，所以只有 ``0`` 或 ``1`` 可以被写入文件。 + +contexts/<N>/ +------------- + +在每个上下文目录中，存在一个文件(``operations``)和三个目录(``monitoring_attrs``, +``targets``, 和 ``schemes``)。 + +DAMON支持多种类型的监测操作，包括对虚拟地址空间和物理地址空间的监测。你可以通过向文件 +中写入以下关键词之一，并从文件中读取，来设置和获取DAMON将为上下文使用何种类型的监测操作。 + + - vaddr: 监测特定进程的虚拟地址空间 + - paddr: 监视系统的物理地址空间 + +contexts/<N>/monitoring_attrs/ +------------------------------ + +用于指定监测属性的文件，包括所需的监测质量和效率，都在 ``monitoring_attrs`` 目录中。 +具体来说，这个目录下有两个目录，即 ``intervals`` 和 ``nr_regions`` 。 + +在 ``intervals`` 目录下，存在DAMON的采样间隔(``sample_us``)、聚集间隔(``aggr_us``) +和更新间隔(``update_us``)三个文件。你可以通过写入和读出这些文件来设置和获取微秒级的值。 + +在 ``nr_regions`` 目录下，有两个文件分别用于DAMON监测区域的下限和上限（``min`` 和 ``max`` ）， +这两个文件控制着监测的开销。你可以通过向这些文件的写入和读出来设置和获取这些值。 + +关于间隔和监测区域范围的更多细节，请参考设计文件 (:doc:`/mm/damon/design`)。 + +contexts/<N>/targets/ +--------------------- + +在开始时，这个目录只有一个文件 ``nr_targets`` 。向该文件写入一个数字(``N``)，就可以创建 +名为 ``0`` 到 ``N-1`` 的子目录的数量。每个目录代表每个监测目标。 + +targets/<N>/ +------------ + +在每个目标目录中，存在一个文件(``pid_target``)和一个目录(``regions``)。 + +如果你把 ``vaddr`` 写到 ``contexts/<N>/operations`` 中，每个目标应该是一个进程。你 +可以通过将进程的pid写到 ``pid_target`` 文件中来指定DAMON的进程。 + +targets/<N>/regions +------------------- + +当使用 ``vaddr`` 监测操作集时（ ``vaddr`` 被写入 ``contexts/<N>/operations`` 文 +件），DAMON自动设置和更新监测目标区域，这样就可以覆盖目标进程的整个内存映射。然而，用户可 +能希望将初始监测区域设置为特定的地址范围。 + +相反，当使用 ``paddr`` 监测操作集时，DAMON不会自动设置和更新监测目标区域（ ``paddr`` +被写入 ``contexts/<N>/operations`` 中）。因此，在这种情况下，用户应该自己设置监测目标 +区域。 + +在这种情况下，用户可以按照自己的意愿明确设置初始监测目标区域，将适当的值写入该目录下的文件。 + +开始时，这个目录只有一个文件， ``nr_regions`` 。向该文件写入一个数字(``N``)，就可以创 +建名为 ``0`` 到 ``N-1`` 的子目录。每个目录代表每个初始监测目标区域。 + +regions/<N>/ +------------ + +在每个区域目录中，你会发现两个文件（ ``start`` 和 ``end`` ）。你可以通过向文件写入 +和从文件中读出，分别设置和获得初始监测目标区域的起始和结束地址。 + +contexts/<N>/schemes/ +--------------------- + +对于一版的基于DAMON的数据访问感知的内存管理优化，用户通常希望系统对特定访问模式的内存区 +域应用内存管理操作。DAMON从用户那里接收这种形式化的操作方案，并将这些方案应用于目标内存 +区域。用户可以通过读取和写入这个目录下的文件来获得和设置这些方案。 + +在开始时，这个目录只有一个文件，``nr_schemes``。向该文件写入一个数字(``N``)，就可以 +创建名为``0``到``N-1``的子目录的数量。每个目录代表每个基于DAMON的操作方案。 + +schemes/<N>/ +------------ + +在每个方案目录中，存在四个目录(``access_pattern``, ``quotas``,``watermarks``, +和 ``stats``)和一个文件(``action``)。 + +``action`` 文件用于设置和获取你想应用于具有特定访问模式的内存区域的动作。可以写入文件 +和从文件中读取的关键词及其含义如下。 + + - ``willneed``: 对有 ``MADV_WILLNEED`` 的区域调用 ``madvise()`` 。 + - ``cold``: 对具有 ``MADV_COLD`` 的区域调用 ``madvise()`` 。 + - ``pageout``: 为具有 ``MADV_PAGEOUT`` 的区域调用 ``madvise()`` 。 + - ``hugepage``: 为带有 ``MADV_HUGEPAGE`` 的区域调用 ``madvise()`` 。 + - ``nohugepage``: 为带有 ``MADV_NOHUGEPAGE`` 的区域调用 ``madvise()``。 + - ``lru_prio``: 在其LRU列表上对区域进行优先排序。 + - ``lru_deprio``: 对区域的LRU列表进行降低优先处理。 + - ``stat``: 什么都不做，只计算统计数据 + +schemes/<N>/access_pattern/ +--------------------------- + +每个基于DAMON的操作方案的目标访问模式由三个范围构成，包括以字节为单位的区域大小、每个 +聚合区间的监测访问次数和区域年龄的聚合区间数。 + +在 ``access_pattern`` 目录下，存在三个目录（ ``sz``, ``nr_accesses``, 和 ``age`` ）， +每个目录有两个文件（``min`` 和 ``max`` ）。你可以通过向 ``sz``, ``nr_accesses``, 和 +``age`` 目录下的 ``min`` 和 ``max`` 文件分别写入和读取来设置和获取给定方案的访问模式。 + +schemes/<N>/quotas/ +------------------- + +每个 ``动作`` 的最佳 ``目标访问模式`` 取决于工作负载，所以不容易找到。更糟糕的是，将某些动作 +的方案设置得过于激进会造成严重的开销。为了避免这种开销，用户可以为每个方案限制时间和大小配额。 +具体来说，用户可以要求DAMON尽量只使用特定的时间（``时间配额``）来应用行动，并且在给定的时间间 +隔（``重置间隔``）内，只对具有目标访问模式的内存区域应用行动，而不使用特定数量（``大小配额``）。 + +当预计超过配额限制时，DAMON会根据 ``目标访问模式`` 的大小、访问频率和年龄，对找到的内存区域 +进行优先排序。为了进行个性化的优先排序，用户可以为这三个属性设置权重。 + +在 ``quotas`` 目录下，存在三个文件（``ms``, ``bytes``, ``reset_interval_ms``）和一个 +目录(``weights``)，其中有三个文件(``sz_permil``, ``nr_accesses_permil``, 和 +``age_permil``)。 + +你可以设置以毫秒为单位的 ``时间配额`` ，以字节为单位的 ``大小配额`` ，以及以毫秒为单位的 ``重 +置间隔`` ，分别向这三个文件写入数值。你还可以通过向 ``weights`` 目录下的三个文件写入数值来设 +置大小、访问频率和年龄的优先权，单位为千分之一。 + +schemes/<N>/watermarks/ +----------------------- + +为了便于根据系统状态激活和停用每个方案，DAMON提供了一个称为水位的功能。该功能接收五个值，称为 +``度量`` 、``间隔`` 、``高`` 、``中`` 、``低`` 。``度量值`` 是指可以测量的系统度量值，如 +自由内存比率。如果系统的度量值 ``高`` 于memoent的高值或 ``低`` 于低值，则该方案被停用。如果 +该值低于 ``中`` ，则该方案被激活。 + +在水位目录下，存在五个文件(``metric``, ``interval_us``,``high``, ``mid``, and ``low``) +用于设置每个值。你可以通过向这些文件的写入来分别设置和获取这五个值。 + +可以写入 ``metric`` 文件的关键词和含义如下。 + + - none: 忽略水位 + - free_mem_rate: 系统的自由内存率（千分比）。 + +``interval`` 应以微秒为单位写入。 + +schemes/<N>/stats/ +------------------ + +DAMON统计每个方案被尝试应用的区域的总数量和字节数，每个方案被成功应用的区域的两个数字，以及 +超过配额限制的总数量。这些统计数据可用于在线分析或调整方案。 + +可以通过读取 ``stats`` 目录下的文件(``nr_tried``, ``sz_tried``, ``nr_applied``, +``sz_applied``, 和 ``qt_exceeds``)）分别检索这些统计数据。这些文件不是实时更新的，所以 +你应该要求DAMON sysfs接口通过在相关的 ``kdamonds/<N>/state`` 文件中写入一个特殊的关键字 +``update_schemes_stats`` 来更新统计信息的文件内容。 + +用例 +~~~~ + +下面的命令应用了一个方案：”如果一个大小为[4KiB, 8KiB]的内存区域在[10, 20]的聚合时间间隔内 +显示出每一个聚合时间间隔[0, 5]的访问量，请分页该区域。对于分页，每秒最多只能使用10ms，而且每 +秒分页不能超过1GiB。在这一限制下，首先分页出具有较长年龄的内存区域。另外，每5秒钟检查一次系统 +的可用内存率，当可用内存率低于50%时开始监测和分页，但如果可用内存率大于60%，或低于30%，则停 +止监测。“ :: + + # cd <sysfs>/kernel/mm/damon/admin + # # populate directories + # echo 1 > kdamonds/nr_kdamonds; echo 1 > kdamonds/0/contexts/nr_contexts; + # echo 1 > kdamonds/0/contexts/0/schemes/nr_schemes + # cd kdamonds/0/contexts/0/schemes/0 + # # set the basic access pattern and the action + # echo 4096 > access_patterns/sz/min + # echo 8192 > access_patterns/sz/max + # echo 0 > access_patterns/nr_accesses/min + # echo 5 > access_patterns/nr_accesses/max + # echo 10 > access_patterns/age/min + # echo 20 > access_patterns/age/max + # echo pageout > action + # # set quotas + # echo 10 > quotas/ms + # echo $((1024*1024*1024)) > quotas/bytes + # echo 1000 > quotas/reset_interval_ms + # # set watermark + # echo free_mem_rate > watermarks/metric + # echo 5000000 > watermarks/interval_us + # echo 600 > watermarks/high + # echo 500 > watermarks/mid + # echo 300 > watermarks/low + +请注意，我们强烈建议使用用户空间的工具，如 `damo <https://github.com/awslabs/damo>`_ ， +而不是像上面那样手动读写文件。以上只是一个例子。 + +debugfs接口 +=========== + +DAMON导出了八个文件, ``attrs``, ``target_ids``, ``init_regions``, +``schemes``, ``monitor_on``, ``kdamond_pid``, ``mk_contexts`` 和 +``rm_contexts`` under its debugfs directory, ``<debugfs>/damon/``. + + +属性 +---- + +用户可以通过读取和写入 ``attrs`` 文件获得和设置 ``采样间隔`` 、 ``聚集间隔`` 、 ``更新间隔`` +以及监测目标区域的最小/最大数量。要详细了解监测属性，请参考 `:doc:/mm/damon/design` 。例如， +下面的命令将这些值设置为5ms、100ms、1000ms、10和1000，然后再次检查:: + + # cd <debugfs>/damon + # echo 5000 100000 1000000 10 1000 > attrs + # cat attrs + 5000 100000 1000000 10 1000 + + +目标ID +------ + +一些类型的地址空间支持多个监测目标。例如，虚拟内存地址空间的监测可以有多个进程作为监测目标。用户 +可以通过写入目标的相关id值来设置目标，并通过读取 ``target_ids`` 文件来获得当前目标的id。在监 +测虚拟地址空间的情况下，这些值应该是监测目标进程的pid。例如，下面的命令将pid为42和4242的进程设 +为监测目标，并再次检查:: + + # cd <debugfs>/damon + # echo 42 4242 > target_ids + # cat target_ids + 42 4242 + +用户还可以通过在文件中写入一个特殊的关键字 "paddr\n" 来监测系统的物理内存地址空间。因为物理地 +址空间监测不支持多个目标，读取文件会显示一个假值，即 ``42`` ，如下图所示:: + + # cd <debugfs>/damon + # echo paddr > target_ids + # cat target_ids + 42 + +请注意，设置目标ID并不启动监测。 + + +初始监测目标区域 +---------------- + +在虚拟地址空间监测的情况下，DAMON自动设置和更新监测的目标区域，这样就可以覆盖目标进程的整个 +内存映射。然而，用户可能希望将监测区域限制在特定的地址范围内，如堆、栈或特定的文件映射区域。 +或者，一些用户可以知道他们工作负载的初始访问模式，因此希望为“自适应区域调整”设置最佳初始区域。 + +相比之下，DAMON在物理内存监测的情况下不会自动设置和更新监测目标区域。因此，用户应该自己设置 +监测目标区域。 + +在这种情况下，用户可以通过在 ``init_regions`` 文件中写入适当的值，明确地设置他们想要的初 +始监测目标区域。输入的每一行应代表一个区域，形式如下:: + + <target idx> <start address> <end address> + +目标idx应该是 ``target_ids`` 文件中目标的索引，从 ``0`` 开始，区域应该按照地址顺序传递。 +例如，下面的命令将设置几个地址范围， ``1-100`` 和 ``100-200`` 作为pid 42的初始监测目标 +区域，这是 ``target_ids`` 中的第一个（索引 ``0`` ），另外几个地址范围， ``20-40`` 和 +``50-100`` 作为pid 4242的地址，这是 ``target_ids`` 中的第二个（索引 ``1`` ）:: + + # cd <debugfs>/damon + # cat target_ids + 42 4242 + # echo "0 1 100 + 0 100 200 + 1 20 40 + 1 50 100" > init_regions + +请注意，这只是设置了初始的监测目标区域。在虚拟内存监测的情况下，DAMON会在一个 ``更新间隔`` +后自动更新区域的边界。因此，在这种情况下，如果用户不希望更新的话，应该把 ``更新间隔`` 设 +置得足够大。 + + +方案 +---- + +对于通常的基于DAMON的数据访问感知的内存管理优化，用户只是希望系统对特定访问模式的内存区域应用内 +存管理操作。DAMON从用户那里接收这种形式化的操作方案，并将这些方案应用到目标进程中。 + +用户可以通过读取和写入 ``scheme`` debugfs文件来获得和设置这些方案。读取该文件还可以显示每个 +方案的统计数据。在文件中，每一个方案都应该在每一行中以下列形式表示出来:: + + <target access pattern> <action> <quota> <watermarks> + +你可以通过简单地在文件中写入一个空字符串来禁用方案。 + +目标访问模式 +~~~~~~~~~~~~ + +``<目标访问模式>`` 是由三个范围构成的，形式如下:: + + min-size max-size min-acc max-acc min-age max-age + +具体来说，区域大小的字节数（ `min-size` 和 `max-size` ），访问频率的每聚合区间的监测访问次 +数（ `min-acc` 和 `max-acc` ），区域年龄的聚合区间数（ `min-age` 和 `max-age` ）都被指定。 +请注意，这些范围是封闭区间。 + +动作 +~~~~ + +``<action>`` 是一个预定义的内存管理动作的整数，DAMON将应用于具有目标访问模式的区域。支持 +的数字和它们的含义如下:: + + - 0: Call ``madvise()`` for the region with ``MADV_WILLNEED`` + - 1: Call ``madvise()`` for the region with ``MADV_COLD`` + - 2: Call ``madvise()`` for the region with ``MADV_PAGEOUT`` + - 3: Call ``madvise()`` for the region with ``MADV_HUGEPAGE`` + - 4: Call ``madvise()`` for the region with ``MADV_NOHUGEPAGE`` + - 5: Do nothing but count the statistics + +配额 +~~~~ + +每个 ``动作`` 的最佳 ``目标访问模式`` 取决于工作负载，所以不容易找到。更糟糕的是，将某个 +动作的方案设置得过于激进会导致严重的开销。为了避免这种开销，用户可以通过下面表格中的 ``<quota>`` +来限制方案的时间和大小配额:: + + <ms> <sz> <reset interval> <priority weights> + +这使得DAMON在 ``<reset interval>`` 毫秒内，尽量只用 ``<ms>`` 毫秒的时间对 ``目标访 +问模式`` 的内存区域应用动作，并在 ``<reset interval>`` 内只对最多<sz>字节的内存区域应 +用动作。将 ``<ms>`` 和 ``<sz>`` 都设置为零，可以禁用配额限制。 + +当预计超过配额限制时，DAMON会根据 ``目标访问模式`` 的大小、访问频率和年龄，对发现的内存 +区域进行优先排序。为了实现个性化的优先级，用户可以在 ``<优先级权重>`` 中设置这三个属性的 +权重，具体形式如下:: + + <size weight> <access frequency weight> <age weight> + +水位 +~~~~ + +有些方案需要根据系统特定指标的当前值来运行，如自由内存比率。对于这种情况，用户可以为该条 +件指定水位。:: + + <metric> <check interval> <high mark> <middle mark> <low mark> + +``<metric>`` 是一个预定义的整数，用于要检查的度量。支持的数字和它们的含义如下。 + + - 0: 忽视水位 + - 1: 系统空闲内存率 (千分比) + +每隔 ``<检查间隔>`` 微秒检查一次公制的值。 + +如果该值高于 ``<高标>`` 或低于 ``<低标>`` ，该方案被停用。如果该值低于 ``<中标>`` ， +该方案将被激活。 + +统计数据 +~~~~~~~~ + +它还统计每个方案被尝试应用的区域的总数量和字节数，每个方案被成功应用的区域的两个数量，以 +及超过配额限制的总数量。这些统计数据可用于在线分析或调整方案。 + +统计数据可以通过读取方案文件来显示。读取该文件将显示你在每一行中输入的每个 ``方案`` ， +统计的五个数字将被加在每一行的末尾。 + +例子 +~~~~ + +下面的命令应用了一个方案：”如果一个大小为[4KiB, 8KiB]的内存区域在[10, 20]的聚合时间 +间隔内显示出每一个聚合时间间隔[0, 5]的访问量，请分页出该区域。对于分页，每秒最多只能使 +用10ms，而且每秒分页不能超过1GiB。在这一限制下，首先分页出具有较长年龄的内存区域。另外， +每5秒钟检查一次系统的可用内存率，当可用内存率低于50%时开始监测和分页，但如果可用内存率 +大于60%，或低于30%，则停止监测“:: + + # cd <debugfs>/damon + # scheme="4096 8192 0 5 10 20 2" # target access pattern and action + # scheme+=" 10 $((1024*1024*1024)) 1000" # quotas + # scheme+=" 0 0 100" # prioritization weights + # scheme+=" 1 5000000 600 500 300" # watermarks + # echo "$scheme" > schemes + + +开关 +---- + +除非你明确地启动监测，否则如上所述的文件设置不会产生效果。你可以通过写入和读取 ``monitor_on`` +文件来启动、停止和检查监测的当前状态。写入 ``on`` 该文件可以启动对有属性的目标的监测。写入 +``off`` 该文件则停止这些目标。如果每个目标进程被终止，DAMON也会停止。下面的示例命令开启、关 +闭和检查DAMON的状态:: + + # cd <debugfs>/damon + # echo on > monitor_on + # echo off > monitor_on + # cat monitor_on + off + +请注意，当监测开启时，你不能写到上述的debugfs文件。如果你在DAMON运行时写到这些文件，将会返 +回一个错误代码，如 ``-EBUSY`` 。 + + +监测线程PID +----------- + +DAMON通过一个叫做kdamond的内核线程来进行请求监测。你可以通过读取 ``kdamond_pid`` 文件获 +得该线程的 ``pid`` 。当监测被 ``关闭`` 时，读取该文件不会返回任何信息:: + + # cd <debugfs>/damon + # cat monitor_on + off + # cat kdamond_pid + none + # echo on > monitor_on + # cat kdamond_pid + 18594 + + +使用多个监测线程 +---------------- + +每个监测上下文都会创建一个 ``kdamond`` 线程。你可以使用 ``mk_contexts`` 和 ``rm_contexts`` +文件为多个 ``kdamond`` 需要的用例创建和删除监测上下文。 + +将新上下文的名称写入 ``mk_contexts`` 文件，在 ``DAMON debugfs`` 目录上创建一个该名称的目录。 +该目录将有该上下文的 ``DAMON debugfs`` 文件:: + + # cd <debugfs>/damon + # ls foo + # ls: cannot access 'foo': No such file or directory + # echo foo > mk_contexts + # ls foo + # attrs init_regions kdamond_pid schemes target_ids + +如果不再需要上下文，你可以通过把上下文的名字放到 ``rm_contexts`` 文件中来删除它和相应的目录:: + + # echo foo > rm_contexts + # ls foo + # ls: cannot access 'foo': No such file or directory + +注意， ``mk_contexts`` 、 ``rm_contexts`` 和 ``monitor_on`` 文件只在根目录下。 + + +监测结果的监测点 +================ + +DAMON通过一个tracepoint ``damon:damon_aggregated`` 提供监测结果. 当监测开启时，你可 +以记录追踪点事件，并使用追踪点支持工具如perf显示结果。比如说:: + + # echo on > monitor_on + # perf record -e damon:damon_aggregated & + # sleep 5 + # kill 9 $(pidof perf) + # echo off > monitor_on + # perf script diff --git a/Documentation/translations/zh_CN/admin-guide/mm/index.rst b/Documentation/translations/zh_CN/admin-guide/mm/index.rst new file mode 100644 index 000000000000..702271c5b683 --- /dev/null +++ b/Documentation/translations/zh_CN/admin-guide/mm/index.rst @@ -0,0 +1,49 @@ +.. include:: ../../disclaimer-zh_CN.rst + +:Original: Documentation/admin-guide/mm/index.rst + +:翻译: + + 徐鑫 xu xin <xu.xin16@zte.com.cn> + + +======== +内存管理 +======== + +Linux内存管理子系统，顾名思义，是负责系统中的内存管理。它包括了虚拟内存与请求 +分页的实现，内核内部结构和用户空间程序的内存分配、将文件映射到进程地址空间以 +及许多其他很酷的事情。 + +Linux内存管理是一个具有许多可配置设置的复杂系统, 且这些设置中的大多数都可以通 +过 ``/proc`` 文件系统获得，并且可以使用 ``sysctl`` 进行查询和调整。这些API接 +口被描述在Documentation/admin-guide/sysctl/vm.rst文件和 `man 5 proc`_ 中。 + +.. _man 5 proc: http://man7.org/linux/man-pages/man5/proc.5.html + +Linux内存管理有它自己的术语，如果你还不熟悉它，请考虑阅读下面参考： +:ref:`Documentation/admin-guide/mm/concepts.rst <mm_concepts>`. + +在此目录下，我们详细描述了如何与Linux内存管理中的各种机制交互。 + +.. toctree:: + :maxdepth: 1 + + damon/index + ksm + +Todolist: +* concepts +* cma_debugfs +* hugetlbpage +* idle_page_tracking +* memory-hotplug +* nommu-mmap +* numa_memory_policy +* numaperf +* pagemap +* soft-dirty +* swap_numa +* transhuge +* userfaultfd +* zswap diff --git a/Documentation/translations/zh_CN/admin-guide/mm/ksm.rst b/Documentation/translations/zh_CN/admin-guide/mm/ksm.rst new file mode 100644 index 000000000000..4829156ef1ae --- /dev/null +++ b/Documentation/translations/zh_CN/admin-guide/mm/ksm.rst @@ -0,0 +1,148 @@ +.. include:: ../../disclaimer-zh_CN.rst + +:Original: Documentation/admin-guide/mm/ksm.rst + +:翻译: + + 徐鑫 xu xin <xu.xin16@zte.com.cn> + + +============ +内核同页合并 +============ + + +概述 +==== + +KSM是一种能节省内存的数据去重功能，由CONFIG_KSM=y启用，并在2.6.32版本时被添 +加到Linux内核。详见 ``mm/ksm.c`` 的实现，以及http://lwn.net/Articles/306704 +和https://lwn.net/Articles/330589 + +KSM最初目的是为了与KVM（即著名的内核共享内存）一起使用而开发的，通过共享虚拟机 +之间的公共数据，将更多虚拟机放入物理内存。但它对于任何会生成多个相同数据实例的 +应用程序都是很有用的。 + +KSM的守护进程ksmd会定期扫描那些已注册的用户内存区域，查找内容相同的页面，这些 +页面可以被单个写保护页面替换（如果进程以后想要更新其内容，将自动复制）。使用： +引用:`sysfs intraface <ksm_sysfs>` 接口来配置KSM守护程序在单个过程中所扫描的页 +数以及两个过程之间的间隔时间。 + +KSM只合并匿名（私有）页面，从不合并页缓存（文件）页面。KSM的合并页面最初只能被 +锁定在内核内存中，但现在可以就像其他用户页面一样被换出（但当它们被交换回来时共 +享会被破坏: ksmd必须重新发现它们的身份并再次合并）。 + +以madvise控制KSM +================ + +KSM仅在特定的地址空间区域时运行，即应用程序通过使用如下所示的madvise(2)系统调 +用来请求某块地址成为可能的合并候选者的地址空间:: + + int madvise(addr, length, MADV_MERGEABLE) + +应用程序当然也可以通过调用:: + + int madvise(addr, length, MADV_UNMERGEABLE) + +来取消该请求，并恢复为非共享页面：此时KSM将去除合并在该范围内的任何合并页。注意： +这个去除合并的调用可能突然需要的内存量超过实际可用的内存量-那么可能会出现EAGAIN +失败，但更可能会唤醒OOM killer。 + +如果KSM未被配置到正在运行的内核中，则madvise MADV_MERGEABLE 和 MADV_UNMERGEABLE +的调用只会以EINVAL 失败。如果正在运行的内核是用CONFIG_KSM=y方式构建的，那么这些 +调用通常会成功：即使KSM守护程序当前没有运行，MADV_MERGEABLE 仍然会在KSM守护程序 +启动时注册范围，即使该范围不能包含KSM实际可以合并的任何页面，即使MADV_UNMERGEABLE +应用于从未标记为MADV_MERGEABLE的范围。 + +如果一块内存区域必须被拆分为至少一个新的MADV_MERGEABLE区域或MADV_UNMERGEABLE区域， +当该进程将超过 ``vm.max_map_count`` 的设定，则madvise可能返回ENOMEM。（请参阅文档 +Documentation/admin-guide/sysctl/vm.rst）。 + +与其他madvise调用一样，它们在用户地址空间的映射区域上使用：如果指定的范围包含未 +映射的间隙（尽管在中间的映射区域工作），它们将报告ENOMEM，如果没有足够的内存用于 +内部结构，则可能会因EAGAIN而失败。 + +KSM守护进程sysfs接口 +==================== + +KSM守护进程可以由``/sys/kernel/mm/ksm/`` 中的sysfs文件控制，所有人都可以读取，但 +只能由root用户写入。各接口解释如下： + + +pages_to_scan + ksmd进程进入睡眠前要扫描的页数。 + 例如， ``echo 100 > /sys/kernel/mm/ksm/pages_to_scan`` + + 默认值：100（该值被选择用于演示目的） + +sleep_millisecs + ksmd在下次扫描前应休眠多少毫秒 + 例如， ``echo 20 > /sys/kernel/mm/ksm/sleep_millisecs`` + + 默认值：20（该值被选择用于演示目的） + +merge_across_nodes + 指定是否可以合并来自不同NUMA节点的页面。当设置为0时，ksm仅合并在物理上位 + 于同一NUMA节点的内存区域中的页面。这降低了访问共享页面的延迟。在有明显的 + NUMA距离上，具有更多节点的系统可能受益于设置该值为0时的更低延迟。而对于 + 需要对内存使用量最小化的较小系统来说，设置该值为1（默认设置）则可能会受 + 益于更大共享页面。在决定使用哪种设置之前，您可能希望比较系统在每种设置下 + 的性能。 ``merge_across_nodes`` 仅当系统中没有ksm共享页面时，才能被更改设 + 置：首先将接口`run` 设置为2从而对页进行去合并，然后在修改 + ``merge_across_nodes`` 后再将‘run’又设置为1，以根据新设置来重新合并。 + + 默认值：1（如早期的发布版本一样合并跨站点） + +run + * 设置为0可停止ksmd运行，但保留合并页面， + * 设置为1可运行ksmd，例如， ``echo 1 > /sys/kernel/mm/ksm/run`` ， + * 设置为2可停止ksmd运行，并且对所有目前已合并的页进行去合并，但保留可合并 + 区域以供下次运行。 + + 默认值：0（必须设置为1才能激活KSM，除非禁用了CONFIG_SYSFS） + +use_zero_pages + 指定是否应当特殊处理空页（即那些仅含zero的已分配页）。当该值设置为1时， + 空页与内核零页合并，而不是像通常情况下那样空页自身彼此合并。这可以根据 + 工作负载的不同，在具有着色零页的架构上可以提高性能。启用此设置时应小心， + 因为它可能会降低某些工作负载的KSM性能，比如，当待合并的候选页面的校验和 + 与空页面的校验和恰好匹配的时候。此设置可随时更改，仅对那些更改后再合并 + 的页面有效。 + + 默认值：0（如同早期版本的KSM正常表现） + +max_page_sharing + 单个KSM页面允许的最大共享站点数。这将强制执行重复数据消除限制，以避免涉 + 及遍历共享KSM页面的虚拟映射的虚拟内存操作的高延迟。最小值为2，因为新创 + 建的KSM页面将至少有两个共享者。该值越高，KSM合并内存的速度越快，去重 + 因子也越高，但是对于任何给定的KSM页面，虚拟映射的最坏情况遍历的速度也会 + 越慢。减慢了这种遍历速度就意味着在交换、压缩、NUMA平衡和页面迁移期间， + 某些虚拟内存操作将有更高的延迟，从而降低这些虚拟内存操作调用者的响应能力。 + 其他任务如果不涉及执行虚拟映射遍历的VM操作，其任务调度延迟不受此参数的影 + 响，因为这些遍历本身是调度友好的。 + +stable_node_chains_prune_millisecs + 指定KSM检查特定页面的元数据的频率（即那些达到过时信息数据去重限制标准的 + 页面）单位是毫秒。较小的毫秒值将以更低的延迟来释放KSM元数据，但它们将使 + ksmd在扫描期间使用更多CPU。如果还没有一个KSM页面达到 ``max_page_sharing`` + 标准，那就没有什么用。 + +KSM与MADV_MERGEABLE的工作有效性体现于 ``/sys/kernel/mm/ksm/`` 路径下的接口： + +pages_shared + 表示多少共享页正在被使用 +pages_sharing + 表示还有多少站点正在共享这些共享页，即节省了多少 +pages_unshared + 表示有多少页是唯一的，但被反复检查以进行合并 +pages_volatile + 表示有多少页因变化太快而无法放在tree中 +full_scans + 表示所有可合并区域已扫描多少次 +stable_node_chains + 达到 ``max_page_sharing`` 限制的KSM页数 +stable_node_dups + 重复的KSM页数 + +比值 ``pages_sharing/pages_shared`` 的最大值受限制于 ``max_page_sharing`` +的设定。要想增加该比值，则相应地要增加 ``max_page_sharing`` 的值。 diff --git a/Documentation/translations/zh_CN/admin-guide/reporting-issues.rst b/Documentation/translations/zh_CN/admin-guide/reporting-issues.rst index 6b4988da2c5a..59e51e3539b4 100644 --- a/Documentation/translations/zh_CN/admin-guide/reporting-issues.rst +++ b/Documentation/translations/zh_CN/admin-guide/reporting-issues.rst @@ -1,13 +1,6 @@ .. SPDX-License-Identifier: (GPL-2.0+ OR CC-BY-4.0) -.. - If you want to distribute this text under CC-BY-4.0 only, please use 'The - Linux kernel developers' for author attribution and link this as source: - https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/plain/Documentation/admin-guide/reporting-issues.rst -.. - Note: Only the content of this RST file as found in the Linux kernel sources - is available under CC-BY-4.0, as versions of this text that were processed - (for example by the kernel's build system) might contain content taken from - files which use a more restrictive license. +.. See the bottom of this file for additional redistribution information. + .. include:: ../disclaimer-zh_CN.rst @@ -29,7 +22,9 @@ 请搜索 `LKML内核邮件列表 <https://lore.kernel.org/lkml/>`_ 和 `Linux稳定版邮件列表 <https://lore.kernel.org/stable/>`_ 存档中匹配的报告并 加入讨论。如果找不到匹配的报告，请安装该系列的最新版本。如果它仍然出现问题， -报告给稳定版邮件列表（stable@vger.kernel.org）。 +请报告给稳定版邮件列表（stable@vger.kernel.org）并抄送回归邮件列表 +（regressions@lists.linux.dev）；理想情况下，还可以抄送维护者和相关子系统的 +邮件列表。 在所有其他情况下，请尽可能猜测是哪个内核部分导致了问题。查看MAINTAINERS文件， 了解开发人员希望如何得知问题，大多数情况下，报告问题都是通过电子邮件和抄送 @@ -46,9 +41,10 @@ 有使用附加模块）。还要确保它是在一个正常的环境中构建和运行，并且在问题发生 之前没有被污染（tainted）。 -在编写报告时，要涵盖与问题相关的所有信息，如使用的内核和发行版。在碰见回归时， -尝试给出引入它的更改的提交ID，二分可以找到它。如果您同时面临Linux内核的多个 -问题，请分别报告每个问题。 +当你同时面临Linux内核的多个问题时，请分别报告。在编写报告时，要涵盖与问题 +相关的所有信息，如使用的内核和发行版。如果碰见回归，请把报告抄送回归邮件列表 +（regressions@lists.linux.dev）。也请试试用二分法找出源头；如果成功找到，请 +在报告中写上它的提交ID并抄送sign-off-by链中的所有人。 一旦报告发出，请回答任何出现的问题，并尽可能地提供帮助。这包括通过不时重新 测试新版本并发送状态更新来推动进展。 @@ -156,9 +152,10 @@ 存在问题，因为问题可能已经在那里被修复了。如果您第一次发现供应商内核的问题， 请检查已知最新版本的普通构建是否可以正常运行。 - * 向Linux稳定版邮件列表发送一个简短的问题报告(stable@vger.kernel.org)。大致 - 描述问题，并解释如何复现。讲清楚首个出现问题的版本和最后一个工作正常的版本。 - 然后等待进一步的指示。 + * 向Linux稳定版邮件列表发送一个简短的问题报告（stable@vger.kernel.org）并抄送 + Linux回归邮件列表（regressions@lists.linux.dev）；如果你怀疑是由某子系统 + 引起的，请抄送其维护人员和子系统邮件列表。大致描述问题，并解释如何复现。 + 讲清楚首个出现问题的版本和最后一个工作正常的版本。然后等待进一步的指示。 下面的参考章节部分详细解释了这些步骤中的每一步。 @@ -296,17 +293,14 @@ Linus Torvalds和主要的Linux内核开发人员希望看到一些问题尽快 报告过程中有一些“高优先级问题”的处理略有不同。有三种情况符合条件:回归、安全 问题和非常严重的问题。 -如果在旧版本的Linux内核中工作的东西不能在新版本的Linux内核中工作，或者某种 -程度上在新版本的Linux内核中工作得更差，那么你就需要处理“回归”。因此，当一个 -在Linux 5.7中表现良好的WiFi驱动程序在5.8中表现不佳或根本不能工作时，这是一 -种回归。如果应用程序在新的内核中出现不稳定的现象，这也是一种回归，这可能是 -由于内核和用户空间之间的接口（如procfs和sysfs）发生不兼容的更改造成的。显著 -的性能降低或功耗增加也可以称为回归。但是请记住:新内核需要使用与旧内核相似的 -配置来构建（参见下面如何实现这一点）。这是因为内核开发人员在实现新特性时有 -时无法避免不兼容性；但是为了避免回归，这些特性必须在构建配置期间显式地启用。 +如果某个应用程序或实际用例在原先的Linux内核上运行良好，但在使用类似配置编译的 +较新版本上效果更差、或者根本不能用，那么你就需要处理回归问题。 +Documentation/admin-guide/reporting-regressions.rst 对此进行了更详细的解释。 +它还提供了很多你可能想知道的关于回归的其他信息；例如，它解释了如何将您的问题 +添加到回归跟踪列表中，以确保它不会被忽略。 什么是安全问题留给您自己判断。在继续之前，请考虑阅读 -“Documentation/translations/zh_CN/admin-guide/security-bugs.rst”， +Documentation/translations/zh_CN/admin-guide/security-bugs.rst ， 因为它提供了如何最恰当地处理安全问题的额外细节。 当发生了完全无法接受的糟糕事情时，此问题就是一个“非常严重的问题”。例如， @@ -390,7 +384,7 @@ Linux内核破坏了它处理的数据或损坏了它运行的硬件。当内核 核未被污染，那么它应该以“Not infected”结束；如果你看到“Tainted:”且后跟一些 空格和字母，那就被污染了。 -如果你的内核被污染了，请阅读“Documentation/translations/zh_CN/admin-guide/tainted-kernels.rst” +如果你的内核被污染了，请阅读 Documentation/translations/zh_CN/admin-guide/tainted-kernels.rst 以找出原因。设法消除污染因素。通常是由以下三种因素之一引起的： 1. 发生了一个可恢复的错误（“kernel Oops”），内核污染了自己，因为内核知道在 @@ -591,7 +585,8 @@ ath10k@lists.infradead.org”，将引导您到ath10k邮件列表的信息页， 搜索引擎，并添加类似“site:lists.infadead.org/pipermail/ath10k/”这 样的搜索条件，这会把结果限制在该链接中的档案。 -也请进一步搜索网络、LKML和bugzilla.kernel.org网站。 +也请进一步搜索网络、LKML和bugzilla.kernel.org网站。如果你的报告需要发送到缺陷 +跟踪器中，那么您可能还需要检查子系统的邮件列表存档，因为可能有人只在那里报告了它。 有关如何搜索以及在找到匹配报告时如何操作的详细信息，请参阅上面的“搜索现有报告 （第一部分）”。 @@ -802,10 +797,10 @@ Linux 首席开发者 Linus Torvalds 认为 Linux 内核永远不应恶化，这 重现它。 有一个叫做“二分”的过程可以来寻找变化，这在 -“Documentation/translations/zh_CN/admin-guide/bug-bisect.rst”文档中进行了详细 +Documentation/translations/zh_CN/admin-guide/bug-bisect.rst 文档中进行了详细 的描述，这个过程通常需要你构建十到二十个内核镜像，每次都尝试在构建下一个镜像 之前重现问题。是的，这需要花费一些时间，但不用担心，它比大多数人想象的要快得多。 -多亏了“binary search二进制搜索”，这将引导你在源代码管理系统中找到导致回归的提交。 +多亏了“binary search二分搜索”，这将引导你在源代码管理系统中找到导致回归的提交。 一旦你找到它，就在网上搜索其主题、提交ID和缩短的提交ID（提交ID的前12个字符）。 如果有的话，这将引导您找到关于它的现有报告。 @@ -823,10 +818,10 @@ Linux 首席开发者 Linus Torvalds 认为 Linux 内核永远不应恶化，这 当处理回归问题时，请确保你所面临的问题真的是由内核引起的，而不是由其他东西 引起的，如上文所述。 -在整个过程中，请记住：只有当旧内核和新内核的配置相似时，问题才算回归。最好 -的方法是：把配置文件（``.config``）从旧的工作内核直接复制到你尝试的每个新内 -核版本。之后运行 ``make oldnoconfig`` 来调整它以适应新版本的需要，而不启用 -任何新的功能，因为那些功能也可能导致回归。 +在整个过程中，请记住：只有当旧内核和新内核的配置相似时，问题才算回归。这可以 +通过 ``make olddefconfig`` 来实现，详细解释参见 +Documentation/admin-guide/reporting-regressions.rst ；它还提供了大量其他您 +可能希望了解的有关回归的信息。 撰写并发送报告 @@ -959,11 +954,19 @@ Linux 首席开发者 Linus Torvalds 认为 Linux 内核永远不应恶化，这 **非常严重的缺陷** ：确保在主题或工单标题以及第一段中明显标出 severeness （非常严重的）。 -**回归** ：如果问题是一个回归，请在邮件的主题或缺陷跟踪器的标题中添加 -[REGRESSION]。如果您没有进行二分，请至少注明您测试的最新主线版本（比如 5.7） -和出现问题的最新版本（比如 5.8）。如果您成功地进行了二分，请注明导致回归 -的提交ID和主题。也请添加该变更的作者到你的报告中；如果您需要将您的缺陷提交 -到缺陷跟踪器中，请将报告以私人邮件的形式转发给他，并注明报告提交地点。 +**回归** ：报告的主题应以“[REGRESSION]”开头。 + +如果您成功用二分法定位了问题，请使用引入回归之更改的标题作为主题的第二部分。 +请在报告中写明“罪魁祸首”的提交ID。如果未能成功二分，请在报告中讲明最后一个 +正常工作的版本（例如5.7）和最先发生问题的版本（例如5.8-rc1）。 + +通过邮件发送报告时，请抄送Linux回归邮件列表（regressions@lists.linux.dev）。 +如果报告需要提交到某个web追踪器，请继续提交；并在提交后，通过邮件将报告转发 +至回归列表；抄送相关子系统的维护人员和邮件列表。请确保报告是内联转发的，不要 +把它作为附件。另外请在顶部添加一个简短的说明，在那里写上工单的网址。 + +在邮寄或转发报告时，如果成功二分，需要将“罪魁祸首”的作者添加到收件人中；同时 +抄送signed-off-by链中的每个人，您可以在提交消息的末尾找到。 **安全问题** ：对于这种问题，你将必须评估：如果细节被公开披露，是否会对其他 用户产生短期风险。如果不会，只需按照所述继续报告问题。如果有此风险，你需要 @@ -980,7 +983,7 @@ Linux 首席开发者 Linus Torvalds 认为 Linux 内核永远不应恶化，这 报告，请将报告的文本转发到这些地址；但请在报告的顶部加上注释，表明您提交了 报告，并附上工单链接。 -更多信息请参见“Documentation/translations/zh_CN/admin-guide/security-bugs.rst”。 +更多信息请参见 Documentation/translations/zh_CN/admin-guide/security-bugs.rst 。 发布报告后的责任 @@ -1173,14 +1176,18 @@ FLOSS 问题报告的人看，询问他们的意见。同时征求他们关于 报告回归 ~~~~~~~~~~ - *向Linux稳定版邮件列表发送一个简短的问题报告(stable@vger.kernel.org)。 - 大致描述问题，并解释如何复现。讲清楚首个出现问题的版本和最后一个工作正常 - 的版本。然后等待进一步的指示。* + *向Linux稳定版邮件列表发送一个简短的问题报告(stable@vger.kernel.org)并 + 抄送Linux回归邮件列表（regressions@lists.linux.dev）；如果你怀疑是由某 + 子系统引起的，请抄送其维护人员和子系统邮件列表。大致描述问题，并解释如 + 何复现。讲清楚首个出现问题的版本和最后一个工作正常的版本。然后等待进一 + 步的指示。* 当报告在稳定版或长期支持内核线内发生的回归（例如在从5.10.4更新到5.10.5时）， -一份简短的报告足以快速报告问题。因此只需要粗略的描述。 +一份简短的报告足以快速报告问题。因此只需向稳定版和回归邮件列表发送粗略的描述； +不过如果你怀疑某子系统导致此问题的话，请一并抄送其维护人员和子系统邮件列表， +这会加快进程。 -但是请注意，如果您能够指明引入问题的确切版本，这将对开发人员有很大帮助。因此 +请注意，如果您能够指明引入问题的确切版本，这将对开发人员有很大帮助。因此 如果有时间的话，请尝试使用普通内核找到该版本。让我们假设发行版发布Linux内核 5.10.5到5.10.8的更新时发生了故障。那么按照上面的指示，去检查该版本线中的最新 内核，比如5.10.9。如果问题出现，请尝试普通5.10.5，以确保供应商应用的补丁不会 @@ -1190,7 +1197,9 @@ FLOSS 问题报告的人看，询问他们的意见。同时征求他们关于 前一段基本粗略地概述了“二分”方法。一旦报告出来，您可能会被要求做一个正确的 报告，因为它允许精确地定位导致问题的确切更改（然后很容易被恢复以快速修复问题）。 因此如果时间允许，考虑立即进行适当的二分。有关如何详细信息，请参阅“对回归的 -特别关照”部分和文档“Documentation/translations/zh_CN/admin-guide/bug-bisect.rst”。 +特别关照”部分和文档 Documentation/translations/zh_CN/admin-guide/bug-bisect.rst 。 +如果成功二分的话，请将“罪魁祸首”的作者添加到收件人中；同时抄送所有在 +signed-off-by链中的人，您可以在提交消息的末尾找到。 “报告仅在旧内核版本线中发生的问题”的参考 @@ -1207,7 +1216,7 @@ FLOSS 问题报告的人看，询问他们的意见。同时征求他们关于 即使是微小的、看似明显的代码变化，有时也会带来新的、完全意想不到的问题。稳 定版和长期支持内核的维护者非常清楚这一点，因此他们只对这些内核进行符合 -“Documentation/translations/zh_CN/process/stable-kernel-rules.rst”中所列出的 +Documentation/translations/zh_CN/process/stable-kernel-rules.rst 中所列出的 规则的修改。 复杂或有风险的修改不符合条件，因此只能应用于主线。其他的修复很容易被回溯到 @@ -1333,3 +1342,27 @@ FLOSS 问题报告的人看，询问他们的意见。同时征求他们关于 向 Linux 内核开发者报告问题是很难的：这个文档的长度和复杂性以及字里行间的内 涵都说明了这一点。但目前就是这样了。这篇文字的主要作者希望通过记录现状来为 以后改善这种状况打下一些基础。 + + +.. + end-of-content +.. + This English version of this document is maintained by Thorsten Leemhuis + <linux@leemhuis.info>. If you spot a typo or small mistake, feel free to + let him know directly and he'll fix it. For translation problems, please + contact with translators. You are free to do the same in a mostly informal + way if you want to contribute changes to the text, but for copyright + reasons please CC linux-doc@vger.kernel.org and "sign-off" your + contribution as Documentation/process/submitting-patches.rst outlines in + the section "Sign your work - the Developer's Certificate of Origin". +.. + This text is available under GPL-2.0+ or CC-BY-4.0, as stated at the top + of the file. If you want to distribute this text under CC-BY-4.0 only, + please use "The Linux kernel developers" for author attribution and link + this as source: + https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/plain/Documentation/admin-guide/reporting-issues.rst +.. + Note: Only the content of this RST file as found in the Linux kernel sources + is available under CC-BY-4.0, as versions of this text that were processed + (for example by the kernel's build system) might contain content taken from + files which use a more restrictive license. diff --git a/Documentation/translations/zh_CN/admin-guide/reporting-regressions.rst b/Documentation/translations/zh_CN/admin-guide/reporting-regressions.rst new file mode 100644 index 000000000000..c0461ee855bc --- /dev/null +++ b/Documentation/translations/zh_CN/admin-guide/reporting-regressions.rst @@ -0,0 +1,370 @@ +.. SPDX-License-Identifier: (GPL-2.0+ OR CC-BY-4.0) +.. 【重分发信息参见本文件结尾】 + +.. include:: ../disclaimer-zh_CN.rst + +:Original: Documentation/admin-guide/reporting-regressions.rst + +:译者: + + 吴想成 Wu XiangCheng <bobwxc@email.cn> + + +============ +报告回归问题 +============ + +“*我们拒绝出现回归*”是Linux内核开发的首要规则；Linux的发起者和领军开发者Linus +Torvalds立下了此规则并确保它被落实。 + +本文档描述了这条规则对用户的意义，以及Linux内核开发模型如何确保解决所有被报告 +的回归；关于内核开发者如何处理的方面参见 Documentation/process/handling-regressions.rst 。 + + +本文重点（亦即“太长不看”） +========================== + +#. 如果某程序在原先的Linux内核上运行良好，但在较新版本上效果更差、或者根本不 + 能用，那么你就碰见回归问题了。注意，新内核需要使用类似配置编译；更多相关细 + 节参见下方。 + +#. 按照 Documentation/translations/zh_CN/admin-guide/reporting-issues.rst 中 + 所说的报告你的问题，该文档已经包含了所有关于回归的重要方面，为了方便起见也 + 复制到了下面。两个重点：在报告主题中使用“[REGRESSION]”开头并抄送或转发到 + `回归邮件列表 <https://lore.kernel.org/regressions/>`_ + （regressions@lists.linux.dev）。 + +#. 可选但是建议：在发送或转发报告时，指明该回归发生的起点，以便Linux内核回归 + 追踪机器人“regzbot”可以追踪此问题:: + + #regzbot introduced v5.13..v5.14-rc1 + + +与用户相关的所有Linux内核回归细节 +================================= + + +基本重点 +-------- + + +什么是“回归”以及什么是“无回归规则”？ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +如果某程序/实例在原先的Linux内核上运行良好，但在较新版本上效果更差、或者根本 +不能用，那么你就碰见回归问题了。“无回归规则”不允许出现这种情况。如果偶然发 +生了，导致问题的开发者应当迅速修复问题。 + +也就是说，若Linux 5.13中的WiFi驱动程序运行良好，但是在5.14版本上却不能用、速 +度明显变慢或出现错误，那就出现了回归。如果某正常工作的应用程序突然在新内核上 +出现不稳定，这也是回归；这些问题可能是由于procfs、sysfs或Linux提供给用户空间 +软件的许多其他接口之一的变化。但请记住，前述例子中的5.14需要使用类似于5.13的 +配置构建。这可以用 ``make olddefconfig`` 实现，详细解释见下。 + +注意本节第一句话中的“实例”：即使开发者需要遵循“无回归”规则，但仍可自由地改 +变内核的任何方面，甚至是导出到用户空间的API或ABI，只要别破坏现有的应用程序或 +用例。 + +还需注意，“无回归”规则只限制内核提供给用户空间的接口。它不适用于内核内部接 +口，比如一些外部开发的驱动程序用来插入钩子到内核的模块API。 + +如何报告回归？ +~~~~~~~~~~~~~~ + +只需按照 Documentation/translations/zh_CN/admin-guide/reporting-issues.rst 中 +所说的报告你的问题，该文档已经包含了要点。下面几点概述了一下只在回归中重要的 +方面： + + * 在检查可加入讨论的现有报告时，别忘了搜索 `Linux回归邮件列表 + <https://lore.kernel.org/regressions/>`_ 和 `regzbot网页界面 + <https://linux-regtracking.leemhuis.info/regzbot/>`_ 。 + + * 在报告主题的开头加上“[REGRESSION]”。 + + * 在你的报告中明确最后一个正常工作的内核版本和首个出问题的版本。如若可能， + 用二分法尝试找出导致回归的变更，更多细节见下。 + + * 记得把报告发到Linux回归邮件列表（regressions@lists.linux.dev）。 + + * 如果通过邮件报告回归，请抄送回归列表。 + + * 如果你使用某些缺陷追踪器报告回归，请通过邮件转发已提交的报告到回归列表， + 并抄送维护者以及出问题的相关子系统的邮件列表。 + + 如果是稳定版或长期支持版系列（如v5.15.3…v5.15.5）的回归，请记得抄送 + `Linux稳定版邮件列表 <https://lore.kernel.org/stable/>`_ （stable@vger.kernel.org）。 + + 如果你成功地执行了二分，请抄送肇事提交的信息中所有签了“Signed-off-by:”的人。 + +在抄送你的报告到列表时，也请记得通知前述的Linux内核回归追踪机器人。只需在邮件 +中包含如下片段:: + + #regzbot introduced: v5.13..v5.14-rc1 + +Regzbot会就将你的邮件视为在某个特定版本区间的回归报告。上例中即linux v5.13仍 +然正常，而Linux 5.14-rc1是首个您遇到问题的版本。如果你执行了二分以查找导致回 +归的提交，请使用指定肇事提交的id代替:: + + #regzbot introduced: 1f2e3d4c5d + +添加这样的“regzbot命令”对你是有好处的，它会确保报告不会被忽略。如果你省略了 +它，Linux内核的回归跟踪者会把你的回归告诉regzbot，只要你发送了一个副本到回归 +邮件列表。但是回归跟踪者只有一个人，有时不得不休息或甚至偶尔享受可以远离电脑 +的时光（听起来很疯狂）。因此，依赖此人手动将回归添加到 `已追踪且尚未解决的 +Linux内核回归列表 <https://linux-regtracking.leemhuis.info/regzbot/>`_ 和 +regzbot发送的每周回归报告，可能会出现延迟。 这样的延误会导致Linus Torvalds +在决定“继续开发还是发布新版本？”时忽略严重的回归。 + +真的修复了所有的回归吗？ +~~~~~~~~~~~~~~~~~~~~~~~~ + +几乎所有都是，只要引起问题的变更（肇事提交）被可靠定位。也有些回归可以不用这 +样，但通常是必须的。 + +谁需要找出回归的根本原因？ +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +受影响代码区域的开发者应该自行尝试定位问题所在。但仅靠他们的努力往往是不可 +能做到的，很多问题只发生在开发者的无法接触的其他特定外部环境中——例如特定的 +硬件平台、固件、Linux发行版、系统的配置或应用程序。这就是为什么最终往往是报 +告者定位肇事提交；有时用户甚至需要再运行额外测试以查明确切的根本原因。开发 +者应该提供建议和可能的帮助，以使普通用户更容易完成该流程。 + +如何找到罪魁祸首？ +~~~~~~~~~~~~~~~~~~ + +如 Documentation/translations/zh_CN/admin-guide/reporting-issues.rst （简要） +和 Documentation/translations/zh_CN/admin-guide/bug-bisect.rst （详细）中所 +述，执行二分。听起来工作量很大，但大部分情况下很快就能找到罪魁祸首。如果这很 +困难或可靠地重现问题很耗时，请考虑与其他受影响的用户合作，一起缩小搜索范围。 + +当出现回归时我可以向谁寻求建议？ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +发送邮件到回归邮件列表（regressions@lists.linux.dev）同时抄送Linux内核的回归 +跟踪者（regressions@leemhuis.info）;如果问题需要保密处理，可以省略列表。 + + +关于回归的更多细节 +------------------ + + +“无回归规则”的目标是什么？ +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +用户应该放心升级内核版本，而不必担心有程序可能崩溃。这符合内核开发者的利益， +可以使更新有吸引力：他们不希望用户停留在停止维护或超过一年半的稳定/长期Linux +版本系列上。这也符合所有人的利益，因为 `那些系列可能含有已知的缺陷、安全问题 +或其他后续版本已经修复的问题 +<http://www.kroah.com/log/blog/2018/08/24/what-stable-kernel-should-i-use/>`_ 。 +此外，内核开发者希望使用户测试最新的预发行版或常规发行版变得简单而有吸引力。 +这同样符合所有人的利益，如果新版本出来后很快就有相关报告，会使追踪和修复问题 +更容易。 + +实际中“无回归”规则真的可行吗？ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +这不是句玩笑话，请见Linux创建者和主要开发人员Linus Torvalds在邮件列表中的许 +多发言，其中一些在 Documentation/process/handling-regressions.rst 中被引用。 + +此规则的例外情况极为罕见；之前当开发者认为某个特定的情况有必要援引例外时， +基本都被证明错了。 + +谁来确保“无回归”被落实？ +~~~~~~~~~~~~~~~~~~~~~~~~ + +照看和支撑树的子系统维护者应该关心这一点——例如，Linus Torvalds之于主线， +Greg Kroah-Hartman等人之于各种稳定/长期系列。 + +他们都得到了别人的帮助，以确保回归报告不会被遗漏。其中之一是Thorsten +Leemhuis，他目前担任Linux内核的“回归跟踪者”；为了做好这项工作，他使用了 +regzbot——Linux内核回归跟踪机器人。所以这就是为什么要抄送或转发你的报告到 +回归邮件列表来通知这些人，已经最好在你的邮件中包含“regzbot命令”来立即追踪它。 + +回归通常多久能修复？ +~~~~~~~~~~~~~~~~~~~~ + +开发者应该尽快修复任何被报告的回归，以提供及时为受影响的用户提供解决方案，并 +防止更多用户遇到问题；然而，开发人员需要花足够的时间和注意力确保回归修复不会 +造成额外的损害。 + +因此，答案取决于各种因素，如回归的影响、存在时长或出现于哪个Linux版本系列。 +但最终，大多数的回归应该在两周内修复。 + +当问题可以通过升级某些软件解决时，是回归吗？ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +基本都是。如果开发人员告诉您其他情况，请咨询上述回归跟踪者。 + +当新内核变慢或能耗增加，是回归吗？ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +是的，但有一些差别。在微型基准测试中变慢5%不太可能被视为回归，除非它也会对 +广泛基准测试的结果产生超过1%的影响。如果有疑问，请寻求建议。 + +当更新Linux时外部内核模块崩溃了，是回归吗？ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +不，因为“无回归”规则仅限于Linux内核提供给用户空间的接口和服务。因此，它不包括 +构建或运行外部开发的内核模块，因为它们在内核空间中运行与挂进内核使用的内部接 +口偶尔会变化。 + +如何处理安全修复引起的回归？ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +在极为罕见的情况下，安全问题无法在不引起回归的情况下修复；这些修复都被放弃了， +因为它们终究会引起问题。幸运的是这种两难境地基本都可以避免，受影响区域的主要 +开发者以及Linus Torvalds本人通常都会努力在不引入回归的情况下解决安全问题。 + +如果你仍然面临此种情况，请查看邮件列表档案是否有人尽力避免过回归。如果没有， +请报告它；如有疑问，请如上所述寻求建议。 + +当修复回归时不可避免会引入另一个，如何处理？ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +很遗憾这种事确实会出现，但幸运的是并不经常出现；如果发生了，受影响代码区的资 +深开发者应当调查该问题以找到避免回归的解决方法，至少避免它们的影响。如果你遇 +到这样的情况，如上所述：检查之前的讨论是否有人已经尽了最大努力，如有疑问请寻 +求建议。 + +小提示：如果人们在每个开发周期中定期给出主线预发布（即v5.15-rc1或-rc3）以供 +测试，则可以避免这种情况。为了更好地解释，可以设想一个在Linux v5.14和v5.15-rc1 +之间集成的更改，该更改导致了回归，但同时是应用于5.15-rc1的其他改进的强依赖。 +如果有人在5.15发布之前就发现并报告了这个问题，那么所有更改都可以直接撤销，从 +而解决回归问题。而就在几天或几周后，此解决方案变成了不可能，因为一些软件可能 +已经开始依赖于后续更改之一：撤销所有更改将导致上述用户软件出现回归，这是不可 +接受的。 + +若我所依赖的功能在数月前被移除了，是回归吗？ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +是的，但如前节所述，通常很难修复此类回归。因此需要逐案处理。这也是定期测试主 +线预发布对所有人有好处的另一个原因。 + +如果我似乎是唯一受影响的人，是否仍适用“无回归”规则？ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +适用，但仅限于实际使用：Linux开发人员希望能够自由地取消那些只能在阁楼和博物 +馆中找到的硬件的支持。 + +请注意，有时为了取得进展，不得不出现回归——后者也是防止Linux停滞不前所必需 +的。因此如果回归所影响的用户很少，那么为了他们和其他人更大的利益，还是让事情 +过去吧。尤其是存在某种规避回归的简单方法，例如更新一些软件或者使用专门为此目 +的创建的内核参数。 + +回归规则是否也适用于staging树中的代码？ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +不，参见 `适用于所有staging代码配置选项的帮助文本 +<https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/drivers/staging/Kconfig>`_ ， +其早已声明:: + + 请注意：这些驱动正在积极开发中，可能无法正常工作，并可能包含会在不久的 + 将来发生变化的用户接口。 + +虽然staging开发人员通常坚持“无回归”的原则，但有时为了取得进展也会违背它。这就 +是为什么当staging树的WiFi驱动被基本推倒重来时，有些用户不得不处理回归（通常可 +以忽略）。 + +为什么较新版本必须“使用相似配置编译”？ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +因为Linux内核开发人员有时会集成已知的会导致回归的变更，但使它们成为可选的，并 +在内核的默认配置下禁用它们。这一技巧允许进步，否则“无回归”规则将导致停滞。 + +例如，试想一个新的可以阻止恶意软件滥用某个内核的接口的安全特性，同时又需要满足 +另一个很罕见的应用程序。上述的方法可使两方都满意：使用这些应用程序的人可以关闭 +新的安全功能，而其他不会遇到麻烦的人可以启用它。 + +如何创建与旧内核相似的配置？ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +用一个已知良好的内核启动机器，并用 ``make olddefconfig`` 配置新版的Linux。这 +会让内核的构建脚本从正在运行的内核中摘录配置文件（“.config”文件），作为即将编 +译的新版本的基础配置；同时将所有新的配置选项设为默认值，以禁用可能导致回归的 +新功能。 + +如何报告在预编译的普通内核中发现的回归？ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +您需要确保新的内核是用与旧版相似的配置编译（见上文），因为那些构建它们的人可 +能启用了一些已知的与新内核不兼容的特性。如有疑问，请向内核的提供者报告问题并 +寻求建议。 + + +用“regzbot”追踪回归的更多信息 +----------------------------- + +什么是回归追踪？为啥我需要关心它？ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +像“无回归”这样的规则需要有人来确保它们被遵守，否则会被有意/无意打破。历史证 +明了这一点对于Linux内核开发也适用。这就是为什么Linux内核的回归跟踪者Thorsten +Leemhuis，，和另一些人尽力关注所有的回归直到他们解决。他们从未为此获得报酬， +因此这项工作是在尽最大努力的基础上完成的。 + +为什么/如何使用机器人追踪Linux内核回归？ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +由于Linux内核开发过程的分布式和松散结构，完全手动跟踪回归已经被证明是相当困难 +的。因此Linux内核的回归跟踪者开发了regzbot来促进这项工作，其长期目标是尽可能为 +所有相关人员自动化回归跟踪。 + +Regzbot通过监视跟踪的回归报告的回复来工作。此外，它还查找用“Link:”标签引用这 +些报告的补丁；对这些补丁的回复也会被跟踪。结合这些数据，可以很好地了解当前修 +复过程的状态。 + +如何查看regzbot当前追踪的回归？ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +参见 `regzbot在线 <https://linux-regtracking.leemhuis.info/regzbot/>`_ 。 + +何种问题可以由regzbot追踪？ +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +该机器人只为了跟踪回归，因此请不要让regzbot涉及常规问题。但是对于Linux内核的 +回归跟踪者来说，让regzbot跟踪严重问题也可以，如有关挂起、损坏数据或内部错误 +（Panic、Oops、BUG（）、warning…）的报告。 + +如何修改被追踪回归的相关信息？ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +在直接或间接回复报告邮件时使用“regzbot命令”即可。最简单的方法是：在“已发送”文 +件夹或邮件列表存档中找到报告，然后使用邮件客户端的“全部回复”功能对其进行回复。 +在该邮件中的独立段落中可使用以下命令之一（即使用空行将这些命令中的一个或多个与 +其余邮件文本分隔开）。 + + * 更新回归引入起点，例如在执行二分之后:: + + #regzbot introduced: 1f2e3d4c5d + + * 设置或更新标题:: + + #regzbot title: foo + + * 监视讨论或bugzilla.kernel.org上有关讨论或修复的工单:: + + #regzbot monitor: https://lore.kernel.org/r/30th.anniversary.repost@klaava.Helsinki.FI/ + #regzbot monitor: https://bugzilla.kernel.org/show_bug.cgi?id=123456789 + + * 标记一个有更多相关细节的地方，例如有关但主题不同的邮件列表帖子或缺陷追踪器中的工单:: + + #regzbot link: https://bugzilla.kernel.org/show_bug.cgi?id=123456789 + + * 标记回归已失效:: + + #regzbot invalid: wasn't a regression, problem has always existed + +Regzbot还支持其他一些主要由开发人员或回归追踪人员使用的命令。命令的更多细节请 +参考 `入门指南 <https://gitlab.com/knurd42/regzbot/-/blob/main/docs/getting_started.md>`_ +和 `参考手册 <https://gitlab.com/knurd42/regzbot/-/blob/main/docs/reference.md>`_ 。 + +.. + 正文结束 +.. + 如本文件开头所述，本文以GPL-2.0+或CC-BY-4.0许可发行。如您想仅在CC-BY-4.0许 + 可下重分发本文，请用“Linux内核开发者”作为作者，并用如下链接作为来源： + https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/plain/Documentation/translations/zh_CN/admin-guide/reporting-regressions.rst +.. + 注意：本RST文件内容只有在来自Linux内核源代码时是使用CC-BY-4.0许可的，因为经 + 过处理的版本（如经内核的构建系统）可能包含来自使用更严格许可证的文件的内容。 diff --git a/Documentation/translations/zh_CN/arch.rst b/Documentation/translations/zh_CN/arch.rst new file mode 100644 index 000000000000..690e173d8b2a --- /dev/null +++ b/Documentation/translations/zh_CN/arch.rst @@ -0,0 +1,29 @@ +.. SPDX-License-Identifier: GPL-2.0 + +处理器体系结构 +============== + +以下文档提供了具体架构实现的编程细节。 + +.. toctree:: + :maxdepth: 2 + + mips/index + arm64/index + riscv/index + openrisc/index + parisc/index + loongarch/index + +TODOList: + +* arm/index +* ia64/index +* m68k/index +* nios2/index +* powerpc/index +* s390/index +* sh/index +* sparc/index +* x86/index +* xtensa/index diff --git a/Documentation/translations/zh_CN/core-api/cachetlb.rst b/Documentation/translations/zh_CN/core-api/cachetlb.rst index 6fee45fe5e80..b4a76ec75daa 100644 --- a/Documentation/translations/zh_CN/core-api/cachetlb.rst +++ b/Documentation/translations/zh_CN/core-api/cachetlb.rst @@ -5,6 +5,7 @@ :翻译: 司延腾 Yanteng Si <siyanteng@loongson.cn> + 周彬彬 Binbin Zhou <zhoubinbin@loongson.cn> :校译: @@ -278,6 +279,11 @@ HyperSparc cpu就是这样一个具有这种属性的cpu。 CPU上，因为它将cpu存储到页面上，使其变脏。同样，请看 sparc64关于如何处理这个问题的例子。 + ``void flush_dcache_folio(struct folio *folio)`` + + 该函数的调用情形与flush_dcache_page()相同。它允许架构针对刷新整个 + folio页面进行优化，而不是一次刷新一页。 + ``void copy_to_user_page(struct vm_area_struct *vma, struct page *page, unsigned long user_vaddr, void *dst, void *src, int len)`` ``void copy_from_user_page(struct vm_area_struct *vma, struct page *page, diff --git a/Documentation/translations/zh_CN/core-api/circular-buffers.rst b/Documentation/translations/zh_CN/core-api/circular-buffers.rst new file mode 100644 index 000000000000..694ad8e61070 --- /dev/null +++ b/Documentation/translations/zh_CN/core-api/circular-buffers.rst @@ -0,0 +1,210 @@ +.. SPDX-License-Identifier: GPL-2.0+ + +.. include:: ../disclaimer-zh_CN.rst + +:Original: Documentation/core-api/circular-buffers.rst + +:翻译: + + 周彬彬 Binbin Zhou <zhoubinbin@loongson.cn> + +:校译: + + 司延腾 Yanteng Si <siyanteng@loongson.cn> + 吴想成 Wu Xiangcheng <bobwxc@email.cn> + 时奎亮 Alex Shi <alexs@kernel.org> + +========== +环形缓冲区 +========== + +:作者: David Howells <dhowells@redhat.com> +:作者: Paul E. McKenney <paulmck@linux.ibm.com> + + +Linux 提供了许多可用于实现循环缓冲的特性。有两组这样的特性： + + (1) 用于确定2次方大小的缓冲区信息的便利函数。 + + (2) 可以代替缓冲区中对象的生产者和消费者共享锁的内存屏障。 + +如下所述，要使用这些设施，只需要一个生产者和一个消费者。可以通过序列化来处理多个 +生产者，并通过序列化来处理多个消费者。 + +.. Contents: + + (*) 什么是环形缓冲区？ + + (*) 测量2次幂缓冲区 + + (*) 内存屏障与环形缓冲区的结合使用 + - 生产者 + - 消费者 + + (*) 延伸阅读 + + + +什么是环形缓冲区？ +================== + +首先，什么是环形缓冲区？环形缓冲区是具有固定的有限大小的缓冲区，它有两个索引： + + (1) 'head'索引 - 生产者将元素插入缓冲区的位置。 + + (2) 'tail'索引 - 消费者在缓冲区中找到下一个元素的位置。 + +通常，当tail指针等于head指针时，表明缓冲区是空的；而当head指针比tail指针少一个时， +表明缓冲区是满的。 + +添加元素时，递增head索引；删除元素时，递增tail索引。tail索引不应该跳过head索引， +两个索引在到达缓冲区末端时都应该被赋值为0，从而允许海量的数据流过缓冲区。 + +通常情况下，元素都有相同的单元大小，但这并不是使用以下技术的严格要求。如果要在缓 +冲区中包含多个元素或可变大小的元素，则索引可以增加超过1，前提是两个索引都没有超过 +另一个。然而，实现者必须小心，因为超过一个单位大小的区域可能会覆盖缓冲区的末端并 +且缓冲区会被分成两段。 + +测量2次幂缓冲区 +=============== + +计算任意大小的环形缓冲区的占用或剩余容量通常是一个费时的操作，需要使用模（除法） +指令。但是如果缓冲区的大小为2次幂，则可以使用更快的按位与指令代替。 + +Linux提供了一组用于处理2次幂环形缓冲区的宏。可以通过以下方式使用:: + + #include <linux/circ_buf.h> + +这些宏包括： + + (#) 测量缓冲区的剩余容量:: + + CIRC_SPACE(head_index, tail_index, buffer_size); + + 返回缓冲区[1]中可插入元素的剩余空间大小。 + + + (#) 测量缓冲区中的最大连续立即可用空间:: + + CIRC_SPACE_TO_END(head_index, tail_index, buffer_size); + + 返回缓冲区[1]中剩余的连续空间的大小，元素可以立即插入其中，而不必绕回到缓冲 + 区的开头。 + + + (#) 测量缓冲区的使用数:: + + CIRC_CNT(head_index, tail_index, buffer_size); + + 返回当前占用缓冲区[2]的元素数量。 + + + (#) 测量缓冲区的连续使用数:: + + CIRC_CNT_TO_END(head_index, tail_index, buffer_size); + + 返回可以从缓冲区中提取的连续元素[2]的数量，而不必绕回到缓冲区的开头。 + +这里的每一个宏名义上都会返回一个介于0和buffer_size-1之间的值，但是： + + (1) CIRC_SPACE*()是为了在生产者中使用。对生产者来说，它们将返回一个下限，因为生 + 产者控制着head索引，但消费者可能仍然在另一个CPU上耗尽缓冲区并移动tail索引。 + + 对消费者来说，它将显示一个上限，因为生产者可能正忙于耗尽空间。 + + (2) CIRC_CNT*()是为了在消费者中使用。对消费者来说，它们将返回一个下限，因为消费 + 者控制着tail索引，但生产者可能仍然在另一个CPU上填充缓冲区并移动head索引。 + + 对于生产者，它将显示一个上限，因为消费者可能正忙于清空缓冲区。 + + (3) 对于第三方来说，生产者和消费者对索引的写入顺序是无法保证的，因为它们是独立的， + 而且可能是在不同的CPU上进行的，所以在这种情况下的结果只是一种猜测，甚至可能 + 是错误的。 + +内存屏障与环形缓冲区的结合使用 +============================== + +通过将内存屏障与环形缓冲区结合使用，可以避免以下需求： + + (1) 使用单个锁来控制对缓冲区两端的访问，从而允许同时填充和清空缓冲区；以及 + + (2) 使用原子计数器操作。 + +这有两个方面：填充缓冲区的生产者和清空缓冲区的消费者。在任何时候，只应有一个生产 +者在填充缓冲区，同样的也只应有一个消费者在清空缓冲区，但双方可以同时操作。 + + +生产者 +------ + +生产者看起来像这样:: + + spin_lock(&producer_lock); + + unsigned long head = buffer->head; + /* spin_unlock()和下一个spin_lock()提供必要的排序。 */ + unsigned long tail = READ_ONCE(buffer->tail); + + if (CIRC_SPACE(head, tail, buffer->size) >= 1) { + /* 添加一个元素到缓冲区 */ + struct item *item = buffer[head]; + + produce_item(item); + + smp_store_release(buffer->head, + (head + 1) & (buffer->size - 1)); + + /* wake_up()将确保在唤醒任何人之前提交head */ + wake_up(consumer); + } + + spin_unlock(&producer_lock); + +这将表明CPU必须在head索引使其对消费者可用之前写入新项目的内容，同时CPU必须在唤醒 +消费者之前写入修改后的head索引。 + +请注意，wake_up()并不保证任何形式的屏障，除非确实唤醒了某些东西。因此我们不能依靠 +它来进行排序。但是数组中始终有一个元素留空，因此生产者必须产生两个元素，然后才可 +能破坏消费者当前正在读取的元素。同时，消费者连续调用之间成对的解锁-加锁提供了索引 +读取（指示消费者已清空给定元素）和生产者对该相同元素的写入之间的必要顺序。 + + +消费者 +------ + +消费者看起来像这样:: + + spin_lock(&consumer_lock); + + /* 读取该索引处的内容之前，先读取索引 */ + unsigned long head = smp_load_acquire(buffer->head); + unsigned long tail = buffer->tail; + + if (CIRC_CNT(head, tail, buffer->size) >= 1) { + + /* 从缓冲区中提取一个元素 */ + struct item *item = buffer[tail]; + + consume_item(item); + + /* 在递增tail之前完成对描述符的读取。 */ + smp_store_release(buffer->tail, + (tail + 1) & (buffer->size - 1)); + } + + spin_unlock(&consumer_lock); + +这表明CPU在读取新元素之前确保索引是最新的，然后在写入新的尾指针之前应确保CPU已完 +成读取该元素，这将擦除该元素。 + +请注意，使用READ_ONCE()和smp_load_acquire()来读取反向（head）索引。这可以防止编译 +器丢弃并重新加载其缓存值。如果您能确定反向（head）索引将仅使用一次，则这不是必须 +的。smp_load_acquire()还可以强制CPU对后续的内存引用进行排序。类似地，两种算法都使 +用smp_store_release()来写入线程的索引。这记录了我们正在写入可以并发读取的内容的事 +实，以防止编译器破坏存储，并强制对以前的访问进行排序。 + + +延伸阅读 +======== + +关于Linux的内存屏障设施的描述，请查看Documentation/memory-barriers.txt。 diff --git a/Documentation/translations/zh_CN/core-api/cpu_hotplug.rst b/Documentation/translations/zh_CN/core-api/cpu_hotplug.rst index 85a264287426..4772a900c37a 100644 --- a/Documentation/translations/zh_CN/core-api/cpu_hotplug.rst +++ b/Documentation/translations/zh_CN/core-api/cpu_hotplug.rst @@ -4,6 +4,7 @@ :翻译: 司延腾 Yanteng Si <siyanteng@loongson.cn> + 周彬彬 Binbin Zhou <zhoubinbin@loongson.cn> :校译: @@ -15,12 +16,13 @@ 内核中的CPU热拔插 ================= -:时间: 2016年12月 +:时间: 2021年9月 :作者: Sebastian Andrzej Siewior <bigeasy@linutronix.de>, - Rusty Russell <rusty@rustcorp.com.au>, - Srivatsa Vaddagiri <vatsa@in.ibm.com>, - Ashok Raj <ashok.raj@intel.com>, - Joel Schopp <jschopp@austin.ibm.com> + Rusty Russell <rusty@rustcorp.com.au>, + Srivatsa Vaddagiri <vatsa@in.ibm.com>, + Ashok Raj <ashok.raj@intel.com>, + Joel Schopp <jschopp@austin.ibm.com>, + Thomas Gleixner <tglx@linutronix.de> 简介 ==== @@ -139,7 +141,7 @@ CPU的热拔插协作 下线情况 -------- -一旦CPU被逻辑关闭，注册的热插拔状态的清除回调将被调用，从 ``CPUHP_ONLINE`` 开始，在 +一旦CPU被逻辑关闭，注册的热插拔状态的清除回调将被调用，从 ``CPUHP_ONLINE`` 开始，到 ``CPUHP_OFFLINE`` 状态结束。这包括: * 如果任务因暂停操作而被冻结，那么 *cpuhp_tasks_frozen* 将被设置为true。 @@ -154,82 +156,399 @@ CPU的热拔插协作 * 一旦所有的服务被迁移，内核会调用一个特定的例程 ``__cpu_disable()`` 来进行特定的清 理。 -使用热插拔API -------------- +CPU热插拔API +============ + +CPU热拔插状态机 +--------------- + +CPU热插拔使用一个从CPUHP_OFFLINE到CPUHP_ONLINE的线性状态空间的普通状态机。每个状态都 +有一个startup和teardown的回调。 + +当一个CPU上线时，将按顺序调用startup回调，直到达到CPUHP_ONLINE状态。当设置状态的回调 +或将实例添加到多实例状态时，也可以调用它们。 + +当一个CPU下线时，将按相反的顺序依次调用teardown回调，直到达到CPUHP_OFFLINE状态。当删 +除状态的回调或从多实例状态中删除实例时，也可以调用它们。 + +如果某个使用场景只需要一个方向的热插拔操作回调（CPU上线或CPU下线），则在设置状态时， +可以将另一个不需要的回调设置为NULL。 + +状态空间被划分成三个阶段: + +* PREPARE阶段 + + PREPARE阶段涵盖了从CPUHP_OFFLINE到CPUHP_BRINGUP_CPU之间的状态空间。 + + 在该阶段中，startup回调在CPU上线操作启动CPU之前被调用，teardown回调在CPU下线操作使 + CPU功能失效之后被调用。 + + 这些回调是在控制CPU上调用的，因为它们显然不能在热插拔的CPU上运行，此时热插拔的CPU要 + 么还没有启动，要么已经功能失效。 + + startup回调用于设置CPU成功上线所需要的资源。teardown回调用于释放资源或在热插拔的CPU + 功能失效后，将待处理的工作转移到在线的CPU上。 + + 允许startup回调失败。如果回调失败，CPU上线操作被中止，CPU将再次被降到之前的状态（通 + 常是CPUHP_OFFLINE）。 + + 本阶段中的teardown回调不允许失败。 + +* STARTING阶段 + + STARTING阶段涵盖了CPUHP_BRINGUP_CPU + 1到CPUHP_AP_ONLINE之间的状态空间。 + + 该阶段中的startup回调是在早期CPU设置代码中的CPU上线操作期间，禁用中断的情况下在热拔 + 插的CPU上被调用。teardown回调是在CPU完全关闭前不久的CPU下线操作期间，禁用中断的情况 + 下在热拔插的CPU上被调用。 + + 该阶段中的回调不允许失败。 + + 回调用于低级别的硬件初始化/关机和核心子系统。 + +* ONLINE阶段 + + ONLINE阶段涵盖了CPUHP_AP_ONLINE + 1到CPUHP_ONLINE之间的状态空间。 + + 该阶段中的startup回调是在CPU上线时在热插拔的CPU上调用的。teardown回调是在CPU下线操 + 作时在热插拔CPU上调用的。 + + 回调是在每个CPU热插拔线程的上下文中调用的，该线程绑定在热插拔的CPU上。回调是在启用 + 中断和抢占的情况下调用的。 + + 允许回调失败。如果回调失败，CPU热插拔操作被中止，CPU将恢复到之前的状态。 + +CPU 上线/下线操作 +----------------- + +一个成功的上线操作如下:: + + [CPUHP_OFFLINE] + [CPUHP_OFFLINE + 1]->startup() -> 成功 + [CPUHP_OFFLINE + 2]->startup() -> 成功 + [CPUHP_OFFLINE + 3] -> 略过，因为startup == NULL + ... + [CPUHP_BRINGUP_CPU]->startup() -> 成功 + === PREPARE阶段结束 + [CPUHP_BRINGUP_CPU + 1]->startup() -> 成功 + ... + [CPUHP_AP_ONLINE]->startup() -> 成功 + === STARTUP阶段结束 + [CPUHP_AP_ONLINE + 1]->startup() -> 成功 + ... + [CPUHP_ONLINE - 1]->startup() -> 成功 + [CPUHP_ONLINE] + +一个成功的下线操作如下:: + + [CPUHP_ONLINE] + [CPUHP_ONLINE - 1]->teardown() -> 成功 + ... + [CPUHP_AP_ONLINE + 1]->teardown() -> 成功 + === STARTUP阶段开始 + [CPUHP_AP_ONLINE]->teardown() -> 成功 + ... + [CPUHP_BRINGUP_ONLINE - 1]->teardown() + ... + === PREPARE阶段开始 + [CPUHP_BRINGUP_CPU]->teardown() + [CPUHP_OFFLINE + 3]->teardown() + [CPUHP_OFFLINE + 2] -> 略过，因为teardown == NULL + [CPUHP_OFFLINE + 1]->teardown() + [CPUHP_OFFLINE] + +一个失败的上线操作如下:: + + [CPUHP_OFFLINE] + [CPUHP_OFFLINE + 1]->startup() -> 成功 + [CPUHP_OFFLINE + 2]->startup() -> 成功 + [CPUHP_OFFLINE + 3] -> 略过，因为startup == NULL + ... + [CPUHP_BRINGUP_CPU]->startup() -> 成功 + === PREPARE阶段结束 + [CPUHP_BRINGUP_CPU + 1]->startup() -> 成功 + ... + [CPUHP_AP_ONLINE]->startup() -> 成功 + === STARTUP阶段结束 + [CPUHP_AP_ONLINE + 1]->startup() -> 成功 + --- + [CPUHP_AP_ONLINE + N]->startup() -> 失败 + [CPUHP_AP_ONLINE + (N - 1)]->teardown() + ... + [CPUHP_AP_ONLINE + 1]->teardown() + === STARTUP阶段开始 + [CPUHP_AP_ONLINE]->teardown() + ... + [CPUHP_BRINGUP_ONLINE - 1]->teardown() + ... + === PREPARE阶段开始 + [CPUHP_BRINGUP_CPU]->teardown() + [CPUHP_OFFLINE + 3]->teardown() + [CPUHP_OFFLINE + 2] -> 略过，因为teardown == NULL + [CPUHP_OFFLINE + 1]->teardown() + [CPUHP_OFFLINE] + +一个失败的下线操作如下:: + + [CPUHP_ONLINE] + [CPUHP_ONLINE - 1]->teardown() -> 成功 + ... + [CPUHP_ONLINE - N]->teardown() -> 失败 + [CPUHP_ONLINE - (N - 1)]->startup() + ... + [CPUHP_ONLINE - 1]->startup() + [CPUHP_ONLINE] + +递归失败不能被合理地处理。 +请看下面的例子，由于下线操作失败而导致的递归失败:: + + [CPUHP_ONLINE] + [CPUHP_ONLINE - 1]->teardown() -> 成功 + ... + [CPUHP_ONLINE - N]->teardown() -> 失败 + [CPUHP_ONLINE - (N - 1)]->startup() -> 成功 + [CPUHP_ONLINE - (N - 2)]->startup() -> 失败 + +CPU热插拔状态机在此停止，且不再尝试回滚，因为这可能会导致死循环:: + + [CPUHP_ONLINE - (N - 1)]->teardown() -> 成功 + [CPUHP_ONLINE - N]->teardown() -> 失败 + [CPUHP_ONLINE - (N - 1)]->startup() -> 成功 + [CPUHP_ONLINE - (N - 2)]->startup() -> 失败 + [CPUHP_ONLINE - (N - 1)]->teardown() -> 成功 + [CPUHP_ONLINE - N]->teardown() -> 失败 + +周而复始，不断重复。在这种情况下，CPU留在该状态中:: + + [CPUHP_ONLINE - (N - 1)] + +这至少可以让系统取得进展，让用户有机会进行调试，甚至解决这个问题。 + +分配一个状态 +------------ + +有两种方式分配一个CPU热插拔状态: + +* 静态分配 + + 当子系统或驱动程序有相对于其他CPU热插拔状态的排序要求时，必须使用静态分配。例如， + 在CPU上线操作期间，PERF核心startup回调必须在PERF驱动startup回调之前被调用。在CPU + 下线操作中，驱动teardown回调必须在核心teardown回调之前调用。静态分配的状态由 + cpuhp_state枚举中的常量描述，可以在include/linux/cpuhotplug.h中找到。 + + 在适当的位置将状态插入枚举中，这样就满足了排序要求。状态常量必须被用于状态的设置 + 和移除。 + + 当状态回调不是在运行时设置的，并且是kernel/cpu.c中CPU热插拔状态数组初始化的一部分 + 时，也需要静态分配。 + +* 动态分配 + + 当对状态回调没有排序要求时，动态分配是首选方法。状态编号由setup函数分配，并在成功 + 后返回给调用者。 + + 只有PREPARE和ONLINE阶段提供了一个动态分配范围。STARTING阶段则没有，因为该部分的大多 + 数回调都有明确的排序要求。 + +CPU热插拔状态的设置 +------------------- + +核心代码提供了以下函数用来设置状态： + +* cpuhp_setup_state(state, name, startup, teardown) +* cpuhp_setup_state_nocalls(state, name, startup, teardown) +* cpuhp_setup_state_cpuslocked(state, name, startup, teardown) +* cpuhp_setup_state_nocalls_cpuslocked(state, name, startup, teardown) + +对于一个驱动程序或子系统有多个实例，并且每个实例都需要调用相同的CPU hotplug状态回 +调的情况，CPU hotplug核心提供多实例支持。与驱动程序特定的实例列表相比，其优势在于 +与实例相关的函数完全针对CPU hotplug操作进行序列化，并在添加和删除时提供状态回调的 +自动调用。要设置这样一个多实例状态，可以使用以下函数： + +* cpuhp_setup_state_multi(state, name, startup, teardown) + +@state参数要么是静态分配的状态，要么是动态分配状态（PUHP_PREPARE_DYN，CPUHP_ONLINE_DYN） +的常量之一， 具体取决于应该分配动态状态的状态阶段（PREPARE，ONLINE）。 + +@name参数用于sysfs输出和检测。命名惯例是"subsys:mode"或"subsys/driver:mode"， +例如 "perf:mode"或"perf/x86:mode"。常见的mode名称有： + +======== ============================================ +prepare 对应PREPARE阶段中的状态 + +dead 对应PREPARE阶段中不提供startup回调的状态 + +starting 对应STARTING阶段中的状态 + +dying 对应STARTING阶段中不提供startup回调的状态 + +online 对应ONLINE阶段中的状态 + +offline 对应ONLINE阶段中不提供startup回调的状态 +======== ============================================ + +由于@name参数只用于sysfs和检测，如果其他mode描述符比常见的描述符更好地描述状态的性质， +也可以使用。 + +@name参数的示例："perf/online", "perf/x86:prepare", "RCU/tree:dying", "sched/waitempty" + +@startup参数是一个指向回调的函数指针，在CPU上线操作时被调用。若应用不需要startup +回调，则将该指针设为NULL。 + +@teardown参数是一个指向回调的函数指针，在CPU下线操作时调用。若应用不需要teardown +回调，则将该指针设为NULL。 + +这些函数在处理已注册回调的方式上有所不同: + + * cpuhp_setup_state_nocalls(), cpuhp_setup_state_nocalls_cpuslocked()和 + cpuhp_setup_state_multi()只注册回调。 + + * cpuhp_setup_state()和cpuhp_setup_state_cpuslocked()注册回调，并对当前状态大于新 + 安装状态的所有在线CPU调用@startup回调（如果不是NULL）。根据状态阶段，回调要么在 + 当前的CPU上调用（PREPARE阶段），要么在CPU的热插拔线程中调用每个在线CPU（ONLINE阶段）。 + + 如果CPU N的回调失败，那么CPU 0...N-1的teardown回调被调用以回滚操作。状态设置失败， + 状态的回调没有被注册，在动态分配的情况下，分配的状态被释放。 + +状态设置和回调调用是针对CPU热拔插操作进行序列化的。如果设置函数必须从CPU热插拔的读 +锁定区域调用，那么必须使用_cpuslocked()变体。这些函数不能在CPU热拔插回调中使用。 + +函数返回值： + ======== ========================================================== + 0 静态分配的状态设置成功 + + >0 动态分配的状态设置成功 + + 返回的数值是被分配的状态编号。如果状态回调后来必须被移除， + 例如模块移除，那么这个数值必须由调用者保存，并作为状态移 + 除函数的@state参数。对于多实例状态，动态分配的状态编号也 + 需要作为实例添加/删除操作的@state参数。 + + <0 操作失败 + ======== ========================================================== + +移除CPU热拔插状态 +----------------- + +为了移除一个之前设置好的状态，提供了如下函数： + +* cpuhp_remove_state(state) +* cpuhp_remove_state_nocalls(state) +* cpuhp_remove_state_nocalls_cpuslocked(state) +* cpuhp_remove_multi_state(state) + +@state参数要么是静态分配的状态，要么是由cpuhp_setup_state*()在动态范围内分配 +的状态编号。如果状态在动态范围内，则状态编号被释放，可再次进行动态分配。 + +这些函数在处理已注册回调的方式上有所不同: + + * cpuhp_remove_state_nocalls(), cpuhp_remove_state_nocalls_cpuslocked() + 和 cpuhp_remove_multi_state()只删除回调。 + + * cpuhp_remove_state()删除回调，并调用所有当前状态大于被删除状态的在线CPU的 + teardown回调（如果不是NULL）。根据状态阶段，回调要么在当前的CPU上调用 + （PREPARE阶段），要么在CPU的热插拔线程中调用每个在线CPU（ONLINE阶段）。 + + 为了完成移除工作，teardown回调不能失败。 + +状态移除和回调调用是针对CPU热拔插操作进行序列化的。如果移除函数必须从CPU hotplug +读取锁定区域调用，那么必须使用_cpuslocked()变体。这些函数不能从CPU热插拔的回调中使用。 + +如果一个多实例的状态被移除，那么调用者必须先移除所有的实例。 + +多实例状态实例管理 +------------------ + +一旦多实例状态被建立，实例就可以被添加到状态中： -一旦一个CPU下线或上线，就有可能收到通知。这对某些需要根据可用CPU数量执行某种设置或清 -理功能的驱动程序来说可能很重要:: + * cpuhp_state_add_instance(state, node) + * cpuhp_state_add_instance_nocalls(state, node) - #include <linux/cpuhotplug.h> +@state参数是一个静态分配的状态或由cpuhp_setup_state_multi()在动态范围内分配的状 +态编号。 - ret = cpuhp_setup_state(CPUHP_AP_ONLINE_DYN, "X/Y:online", - Y_online, Y_prepare_down); +@node参数是一个指向hlist_node的指针，它被嵌入到实例的数据结构中。这个指针被交给 +多实例状态的回调，可以被回调用来通过container_of()检索到实例。 -*X* 是子系统， *Y* 是特定的驱动程序。 *Y_online* 回调将在所有在线CPU的注册过程中被调用。 -如果在线回调期间发生错误， *Y_prepare_down* 回调将在所有之前调用过在线回调的CPU上调 -用。注册完成后，一旦有CPU上线， *Y_online* 回调将被调用，当CPU关闭时， *Y_prepare_down* -将被调用。所有之前在 *Y_online* 中分配的资源都应该在 *Y_prepare_down* 中释放。如果在 -注册过程中发生错误，返回值 *ret* 为负值。否则会返回一个正值，其中包含动态分配状态 -（ *CPUHP_AP_ONLINE_DYN* ）的分配热拔插。对于预定义的状态，它将返回0。 +这些函数在处理已注册回调的方式上有所不同: -该回调可以通过调用 ``cpuhp_remove_state()`` 来删除。如果是动态分配的状态 -（ *CPUHP_AP_ONLINE_DYN* ），则使用返回的状态。在移除热插拔状态的过程中，将调用拆解回调。 + * cpuhp_state_add_instance_nocalls()只将实例添加到多实例状态的节点列表中。 -多个实例 -~~~~~~~~ + * cpuhp_state_add_instance()为所有当前状态大于@state的在线CPU添加实例并调用与 + @state相关的startup回调（如果不是NULL）。该回调只对将要添加的实例进行调用。 + 根据状态阶段，回调要么在当前的CPU上调用（PREPARE阶段），要么在CPU的热插拔线 + 程中调用每个在线CPU（ONLINE阶段）。 -如果一个驱动程序有多个实例，并且每个实例都需要独立执行回调，那么很可能应该使用 -``multi-state`` 。首先需要注册一个多状态的状态:: + 如果CPU N的回调失败，那么CPU 0 ... N-1的teardown回调被调用以回滚操作，该函数 + 失败，实例不会被添加到多实例状态的节点列表中。 - ret = cpuhp_setup_state_multi(CPUHP_AP_ONLINE_DYN, "X/Y:online, - Y_online, Y_prepare_down); - Y_hp_online = ret; +要从状态的节点列表中删除一个实例，可以使用这些函数: -``cpuhp_setup_state_multi()`` 的行为与 ``cpuhp_setup_state()`` 类似，只是它 -为多状态准备了回调，但不调用回调。这是一个一次性的设置。 -一旦分配了一个新的实例，你需要注册这个新实例:: + * cpuhp_state_remove_instance(state, node) + * cpuhp_state_remove_instance_nocalls(state, node) - ret = cpuhp_state_add_instance(Y_hp_online, &d->node); +参数与上述cpuhp_state_add_instance*()变体相同。 -这个函数将把这个实例添加到你先前分配的 ``Y_hp_online`` 状态，并在所有在线的 -CPU上调用先前注册的回调（ ``Y_online`` ）。 *node* 元素是你的每个实例数据结构 -中的一个 ``struct hlist_node`` 成员。 +这些函数在处理已注册回调的方式上有所不同: -在移除该实例时:: + * cpuhp_state_remove_instance_nocalls()只从状态的节点列表中删除实例。 - cpuhp_state_remove_instance(Y_hp_online, &d->node) + * cpuhp_state_remove_instance()删除实例并调用与@state相关的回调（如果不是NULL）， + 用于所有当前状态大于@state的在线CPU。 该回调只对将要被移除的实例进行调用。 + 根据状态阶段，回调要么在当前的CPU上调用（PREPARE阶段），要么在CPU的热插拔 + 线程中调用每个在线CPU（ONLINE阶段）。 -应该被调用，这将在所有在线CPU上调用拆分回调。 + 为了完成移除工作，teardown回调不能失败。 -手动设置 -~~~~~~~~ +节点列表的添加/删除操作和回调调用是针对CPU热拔插操作进行序列化。这些函数不能在 +CPU hotplug回调和CPU hotplug读取锁定区域内使用。 -通常情况下，在注册或移除状态时调用setup和teamdown回调是很方便的，因为通常在CPU上线 -（下线）和驱动的初始设置（关闭）时需要执行该操作。然而，每个注册和删除功能也有一个 -_nocalls的后缀，如果不希望调用回调，则不调用所提供的回调。在手动设置（或关闭）期间， -应该使用 ``get_online_cpus()`` 和 ``put_online_cpus()`` 函数来抑制CPU热插拔操作。 +样例 +---- +在STARTING阶段设置和取消静态分配的状态，以获取上线和下线操作的通知:: -事件的顺序 ----------- + ret = cpuhp_setup_state(CPUHP_SUBSYS_STARTING, "subsys:starting", subsys_cpu_starting, subsys_cpu_dying); + if (ret < 0) + return ret; + .... + cpuhp_remove_state(CPUHP_SUBSYS_STARTING); -热插拔状态被定义在 ``include/linux/cpuhotplug.h``: +在ONLINE阶段设置和取消动态分配的状态，以获取下线操作的通知:: -* ``CPUHP_OFFLINE`` ... ``CPUHP_AP_OFFLINE`` 状态是在CPU启动前调用的。 + state = cpuhp_setup_state(CPUHP_ONLINE_DYN, "subsys:offline", NULL, subsys_cpu_offline); + if (state < 0) + return state; + .... + cpuhp_remove_state(state); -* ``CPUHP_AP_OFFLINE`` ... ``CPUHP_AP_ONLINE`` 状态是在CPU被启动后被调用的。 - 中断是关闭的，调度程序还没有在这个CPU上活动。从 ``CPUHP_AP_OFFLINE`` 开始， - 回调被调用到目标CPU上。 +在ONLINE阶段设置和取消动态分配的状态，以获取有关上线操作的通知，而无需调用回调:: -* ``CPUHP_AP_ONLINE_DYN`` 和 ``CPUHP_AP_ONLINE_DYN_END`` 之间的状态被保留 - 给动态分配。 + state = cpuhp_setup_state_nocalls(CPUHP_ONLINE_DYN, "subsys:online", subsys_cpu_online, NULL); + if (state < 0) + return state; + .... + cpuhp_remove_state_nocalls(state); -* 这些状态在CPU关闭时以相反的顺序调用，从 ``CPUHP_ONLINE`` 开始，在 ``CPUHP_OFFLINE`` - 停止。这里的回调是在将被关闭的CPU上调用的，直到 ``CPUHP_AP_OFFLINE`` 。 +在ONLINE阶段设置、使用和取消动态分配的多实例状态，以获得上线和下线操作的通知:: -通过 ``CPUHP_AP_ONLINE_DYN`` 动态分配的状态通常已经足够了。然而，如果在启动或关闭 -期间需要更早的调用，那么应该获得一个显式状态。如果热拔插事件需要相对于另一个热拔插事 -件的特定排序，也可能需要一个显式状态。 + state = cpuhp_setup_state_multi(CPUHP_ONLINE_DYN, "subsys:online", subsys_cpu_online, subsys_cpu_offline); + if (state < 0) + return state; + .... + ret = cpuhp_state_add_instance(state, &inst1->node); + if (ret) + return ret; + .... + ret = cpuhp_state_add_instance(state, &inst2->node); + if (ret) + return ret; + .... + cpuhp_remove_instance(state, &inst1->node); + .... + cpuhp_remove_instance(state, &inst2->node); + .... + remove_multi_state(state); 测试热拔插状态 ============== diff --git a/Documentation/translations/zh_CN/core-api/generic-radix-tree.rst b/Documentation/translations/zh_CN/core-api/generic-radix-tree.rst new file mode 100644 index 000000000000..eacd1d2ebddc --- /dev/null +++ b/Documentation/translations/zh_CN/core-api/generic-radix-tree.rst @@ -0,0 +1,23 @@ +.. SPDX-License-Identifier: GPL-2.0+ + +.. include:: ../disclaimer-zh_CN.rst + +:Original: Documentation/core-api/generic-radix-tree.rst + +:翻译: + + 周彬彬 Binbin Zhou <zhoubinbin@loongson.cn> + +=================== +通用基数树/稀疏数组 +=================== + +通用基数树/稀疏数组的相关内容请见include/linux/generic-radix-tree.h文件中的 +“DOC: Generic radix trees/sparse arrays”。 + +通用基数树函数 +-------------- + +该API在以下内核代码中: + +include/linux/generic-radix-tree.h diff --git a/Documentation/translations/zh_CN/core-api/idr.rst b/Documentation/translations/zh_CN/core-api/idr.rst new file mode 100644 index 000000000000..97a16e76b81b --- /dev/null +++ b/Documentation/translations/zh_CN/core-api/idr.rst @@ -0,0 +1,80 @@ +.. SPDX-License-Identifier: GPL-2.0+ + +.. include:: ../disclaimer-zh_CN.rst + +:Original: Documentation/core-api/idr.rst + +:翻译: + + 周彬彬 Binbin Zhou <zhoubinbin@loongson.cn> + +:校译: + + 司延腾 Yanteng Si <siyanteng@loongson.cn> + 吴想成 Wu Xiangcheng <bobwxc@email.cn> + 时奎亮 Alex Shi <alexs@kernel.org> + +====== +ID分配 +====== + +:作者: Matthew Wilcox + +概述 +==== + +要解决的一个常见问题是分配标识符（IDs）；它通常是标识事物的数字。比如包括文件描述 +符、进程ID、网络协议中的数据包标识符、SCSI标记和设备实例编号。IDR和IDA为这个问题 +提供了一个合理的解决方案，以避免每个人都自创。IDR提供将ID映射到指针的能力，而IDA +仅提供ID分配，因此内存效率更高。 + +IDR接口已经被废弃，请使用 ``XArray`` 。 + +IDR的用法 +========= + +首先初始化一个IDR，对于静态分配的IDR使用DEFINE_IDR()，或者对于动态分配的IDR使用 +idr_init()。 + +您可以调用idr_alloc()来分配一个未使用的ID。通过调用idr_find()查询与该ID相关的指针， +并通过调用idr_remove()释放该ID。 + +如果需要更改与一个ID相关联的指针，可以调用idr_replace()。这样做的一个常见原因是通 +过将 ``NULL`` 指针传递给分配函数来保留ID；用保留的ID初始化对象，最后将初始化的对 +象插入IDR。 + +一些用户需要分配大于 ``INT_MAX`` 的ID。到目前为止，所有这些用户都满足 ``UINT_MAX`` +的限制，他们使用idr_alloc_u32()。如果您需要超出u32的ID，我们将与您合作以满足您的 +需求。 + +如果需要按顺序分配ID，可以使用idr_alloc_cyclic()。处理较大数量的ID时，IDR的效率会 +降低，所以使用这个函数会有一点代价。 + +要对IDR使用的所有指针进行操作，您可以使用基于回调的idr_for_each()或迭代器样式的 +idr_for_each_entry()。您可能需要使用idr_for_each_entry_continue()来继续迭代。如果 +迭代器不符合您的需求，您也可以使用idr_get_next()。 + +当使用完IDR后，您可以调用idr_destroy()来释放IDR占用的内存。这并不会释放IDR指向的 +对象；如果您想这样做，请使用其中一个迭代器来执行此操作。 + +您可以使用idr_is_empty()来查看当前是否分配了任何ID。 + +如果在从IDR分配一个新ID时需要带锁，您可能需要传递一组限制性的GFP标志，但这可能导 +致IDR无法分配内存。为了解决该问题，您可以在获取锁之前调用idr_preload()，然后在分 +配之后调用idr_preload_end()。 + +IDR同步的相关内容请见include/linux/idr.h文件中的“DOC: idr sync”。 + +IDA的用法 +========= + +IDA的用法的相关内容请见lib/idr.c文件中的“DOC: IDA description”。 + +函数和数据结构 +============== + +该API在以下内核代码中: + +include/linux/idr.h + +lib/idr.c diff --git a/Documentation/translations/zh_CN/core-api/index.rst b/Documentation/translations/zh_CN/core-api/index.rst index d10191c45cf1..37756d240b5e 100644 --- a/Documentation/translations/zh_CN/core-api/index.rst +++ b/Documentation/translations/zh_CN/core-api/index.rst @@ -28,6 +28,7 @@ printk-basics printk-formats workqueue + watch_queue symbol-namespaces 数据结构和低级实用程序 @@ -42,17 +43,16 @@ kref assoc_array xarray + rbtree + idr + circular-buffers + generic-radix-tree + packing Todolist: - idr - circular-buffers - rbtree - generic-radix-tree - packing - bus-virt-phys-mapping this_cpu_ops timekeeping errseq @@ -101,7 +101,7 @@ Todolist: ======== 如何在内核中分配和使用内存。请注意，在 -:doc:`/vm/index` 中有更多的内存管理文档。 +:doc:`/mm/index` 中有更多的内存管理文档。 .. toctree:: :maxdepth: 1 diff --git a/Documentation/translations/zh_CN/core-api/irq/irq-domain.rst b/Documentation/translations/zh_CN/core-api/irq/irq-domain.rst index 7d077742f758..9174fce12c1b 100644 --- a/Documentation/translations/zh_CN/core-api/irq/irq-domain.rst +++ b/Documentation/translations/zh_CN/core-api/irq/irq-domain.rst @@ -5,6 +5,7 @@ :翻译: 司延腾 Yanteng Si <siyanteng@loongson.cn> + 周彬彬 Binbin Zhou <zhoubinbin@loongson.cn> .. _cn_irq-domain.rst: @@ -52,8 +53,18 @@ irq_domain和一个hwirq号作为参数。 如果hwirq的映射还不存在， 一个新的Linux irq_desc，将其与hwirq关联起来，并调用.map()回调，这样驱动 程序就可以执行任何必要的硬件设置。 -当接收到一个中断时，应该使用irq_find_mapping()函数从hwirq号中找到 -Linux IRQ号。 +一旦建立了映射，可以通过多种方法检索或使用它： + +- irq_resolve_mapping()返回一个指向给定域和hwirq号的irq_desc结构指针， + 如果没有映射则返回NULL。 + +- irq_find_mapping()返回给定域和hwirq的Linux IRQ号，如果没有映射则返回0。 + +- irq_linear_revmap()现与irq_find_mapping()相同，已被废弃。 + +- generic_handle_domain_irq()处理一个由域和hwirq号描述的中断。 + +请注意，irq域的查找必须发生在与RCU读临界区兼容的上下文中。 在调用irq_find_mapping()之前，至少要调用一次irq_create_mapping()函数， 以免描述符不能被分配。 @@ -119,7 +130,8 @@ irq_domain_add_tree()和irq_domain_create_tree()在功能上是等价的，除 Linux IRQ号编入硬件本身，这样就不需要映射了。 调用irq_create_direct_mapping() 会分配一个Linux IRQ号，并调用.map()回调，这样驱动就可以将Linux IRQ号编入硬件中。 -大多数驱动程序不能使用这个映射。 +大多数驱动程序无法使用此映射，现在它由CONFIG_IRQ_DOMAIN_NOMAP选项控制。 +请不要引入此API的新用户。 传统映射类型 ------------ @@ -128,7 +140,6 @@ Linux IRQ号编入硬件本身，这样就不需要映射了。 调用irq_create irq_domain_add_simple() irq_domain_add_legacy() - irq_domain_add_legacy_isa() irq_domain_create_simple() irq_domain_create_legacy() @@ -137,6 +148,9 @@ Linux IRQ号编入硬件本身，这样就不需要映射了。 调用irq_create 一组用于IRQ号的定义（#define），这些定义被传递给struct设备注册。 在这种情况下， 不能动态分配Linux IRQ号，应该使用传统映射。 +顾名思义，\*_legacy()系列函数已被废弃，只是为了方便对古老平台的支持而存在。 +不应该增加新的用户。当\*_simple()系列函数的使用导致遗留行为时，他们也是如此。 + 传统映射假设已经为控制器分配了一个连续的IRQ号范围，并且可以通过向hwirq号添加一 个固定的偏移来计算IRQ号，反之亦然。 缺点是需要中断控制器管理IRQ分配，并且需要为每 个hwirq分配一个irq_desc，即使它没有被使用。 diff --git a/Documentation/translations/zh_CN/core-api/kernel-api.rst b/Documentation/translations/zh_CN/core-api/kernel-api.rst index ab7d81889340..c22662679065 100644 --- a/Documentation/translations/zh_CN/core-api/kernel-api.rst +++ b/Documentation/translations/zh_CN/core-api/kernel-api.rst @@ -5,6 +5,7 @@ :翻译: 司延腾 Yanteng Si <siyanteng@loongson.cn> + 周彬彬 Binbin Zhou <zhoubinbin@loongson.cn> .. _cn_kernel-api.rst: @@ -224,7 +225,7 @@ kernel/kmod.c 模块接口支持 ------------ -更多信息请参考文件kernel/module.c。 +更多信息请参阅kernel/module/目录下的文件。 硬件接口 ======== @@ -282,6 +283,8 @@ kernel/acct.c 该API在以下内核代码中: +include/linux/bio.h + block/blk-core.c block/blk-core.c @@ -292,8 +295,6 @@ block/blk-sysfs.c block/blk-settings.c -block/blk-exec.c - block/blk-flush.c block/blk-lib.c diff --git a/Documentation/translations/zh_CN/core-api/kobject.rst b/Documentation/translations/zh_CN/core-api/kobject.rst index b7c37794cc7f..0747b472fdea 100644 --- a/Documentation/translations/zh_CN/core-api/kobject.rst +++ b/Documentation/translations/zh_CN/core-api/kobject.rst @@ -258,7 +258,6 @@ kobject_put()以避免错误的发生是一个很好的做法。 struct kobj_type { void (*release)(struct kobject *kobj); const struct sysfs_ops *sysfs_ops; - struct attribute **default_attrs; const struct attribute_group **default_groups; const struct kobj_ns_type_operations *(*child_ns_type)(struct kobject *kobj); const void *(*namespace)(struct kobject *kobj); @@ -271,10 +270,10 @@ kobject_init()或kobject_init_and_add()时必须指定一个指向该结构的 指针。 当然，kobj_type结构中的release字段是指向这种类型的kobject的release() -方法的一个指针。另外两个字段（sysfs_ops 和 default_attrs）控制这种 +方法的一个指针。另外两个字段（sysfs_ops 和 default_groups）控制这种 类型的对象如何在 sysfs 中被表示；它们超出了本文的范围。 -default_attrs 指针是一个默认属性的列表，它将为任何用这个 ktype 注册 +default_groups 指针是一个默认属性的列表，它将为任何用这个 ktype 注册 的 kobject 自动创建。 @@ -325,10 +324,9 @@ ksets 结构体kset_uevent_ops来处理它:: struct kset_uevent_ops { - int (* const filter)(struct kset *kset, struct kobject *kobj); - const char *(* const name)(struct kset *kset, struct kobject *kobj); - int (* const uevent)(struct kset *kset, struct kobject *kobj, - struct kobj_uevent_env *env); + int (* const filter)(struct kobject *kobj); + const char *(* const name)(struct kobject *kobj); + int (* const uevent)(struct kobject *kobj, struct kobj_uevent_env *env); }; diff --git a/Documentation/translations/zh_CN/core-api/mm-api.rst b/Documentation/translations/zh_CN/core-api/mm-api.rst index 0ea43dc67953..a732b0eebf16 100644 --- a/Documentation/translations/zh_CN/core-api/mm-api.rst +++ b/Documentation/translations/zh_CN/core-api/mm-api.rst @@ -5,6 +5,7 @@ :翻译: 司延腾 Yanteng Si <siyanteng@loongson.cn> + 周彬彬 Binbin Zhou <zhoubinbin@loongson.cn> :校译: @@ -66,12 +67,24 @@ mm/vmalloc.c 该API在以下内核代码中: -mm/readahead.c +文件映射 +-------- mm/filemap.c +预读 +---- + +mm/readahead.c + +回写 +---- + mm/page-writeback.c +截断 +---- + mm/truncate.c include/linux/pagemap.h @@ -105,6 +118,14 @@ mm/mempolicy.c include/linux/mm_types.h +include/linux/mm_inline.h + +include/linux/page-flags.h + include/linux/mm.h +include/linux/page_ref.h + include/linux/mmzone.h + +mm/util.c diff --git a/Documentation/translations/zh_CN/core-api/packing.rst b/Documentation/translations/zh_CN/core-api/packing.rst new file mode 100644 index 000000000000..c0aab3a349d0 --- /dev/null +++ b/Documentation/translations/zh_CN/core-api/packing.rst @@ -0,0 +1,160 @@ +.. SPDX-License-Identifier: GPL-2.0+ + +.. include:: ../disclaimer-zh_CN.rst + +:Original: Documentation/core-api/packing.rst + +:翻译: + + 周彬彬 Binbin Zhou <zhoubinbin@loongson.cn> + +:校译: + + 司延腾 Yanteng Si <siyanteng@loongson.cn> + 吴想成 Wu Xiangcheng <bobwxc@email.cn> + 时奎亮 Alex Shi <alexs@kernel.org> + +======================== +通用的位域打包和解包函数 +======================== + +问题陈述 +-------- + +使用硬件时，必须在几种与其交互的方法之间进行选择。 + +可以将指针映射到在硬件设备的内存区上精心设计的结构体，并将其字段作为结构成员（可 +能声明为位域）访问。但是由于CPU和硬件设备之间潜在的字节顺序不匹配，以这种方式编写 +代码会降低其可移植性。 + +此外，必须密切注意将硬件文档中的寄存器定义转换为结构的位域索引。此外，一些硬件 +（通常是网络设备）倾向于以违反任何合理字边界（有时甚至是64位）的方式对其寄存器字 +段进行分组。这就造成了不得不在结构中定义寄存器字段的“高”和“低”部分的不便。 + +结构域定义的更可靠的替代方法是通过移动适当数量的位来提取所需的字段。但这仍然不能 +防止字节顺序不匹配，除非所有内存访问都是逐字节执行的。此外，代码很容易变得杂乱无 +章，同时可能会在所需的许多位移操作中丢失一些高层次的想法。 + +许多驱动程序采用了位移的方法，然后试图用定制的宏来减少杂乱无章的东西，但更多的时 +候，这些宏所采用的捷径依旧妨碍了代码真正的可移植性。 + +解决方案 +-------- + +该API涉及2个基本操作： + + - 将一个CPU可使用的数字打包到内存缓冲区中（具有硬件约束/特殊性）。 + - 将内存缓冲区（具有硬件约束/特殊性）解压缩为一个CPU可使用的数字。 + +该API提供了对所述硬件约束和特殊性以及CPU字节序的抽象，因此这两者之间可能不匹配。 + +这些API函数的基本单元是u64。从CPU的角度来看，位63总是意味着字节7的位偏移量7，尽管 +只是逻辑上的。问题是：我们将这个比特放在内存的什么位置？ + +以下示例介绍了打包u64字段的内存布局。打包缓冲区中的字节偏移量始终默认为0，1...7。 +示例显示的是逻辑字节和位所在的位置。 + +1. 通常情况下（无特殊性），我们会这样做： + +:: + + 63 62 61 60 59 58 57 56 55 54 53 52 51 50 49 48 47 46 45 44 43 42 41 40 39 38 37 36 35 34 33 32 + 7 6 5 4 + 31 30 29 28 27 26 25 24 23 22 21 20 19 18 17 16 15 14 13 12 11 10 9 8 7 6 5 4 3 2 1 0 + 3 2 1 0 + +也就是说，CPU可使用的u64的MSByte(7)位于内存偏移量0处，而u64的LSByte(0)位于内存偏移量7处。 + +这对应于大多数人认为的“大端”，其中位i对应于数字2^i。这在代码注释中也称为“逻辑”符号。 + + +2. 如果设置了QUIRK_MSB_ON_THE_RIGHT，我们按如下方式操作： + +:: + + 56 57 58 59 60 61 62 63 48 49 50 51 52 53 54 55 40 41 42 43 44 45 46 47 32 33 34 35 36 37 38 39 + 7 6 5 4 + 24 25 26 27 28 29 30 31 16 17 18 19 20 21 22 23 8 9 10 11 12 13 14 15 0 1 2 3 4 5 6 7 + 3 2 1 0 + +也就是说，QUIRK_MSB_ON_THE_RIGHT不会影响字节定位，但会反转字节内的位偏移量。 + + +3. 如果设置了QUIRK_LITTLE_ENDIAN，我们按如下方式操作： + +:: + + 39 38 37 36 35 34 33 32 47 46 45 44 43 42 41 40 55 54 53 52 51 50 49 48 63 62 61 60 59 58 57 56 + 4 5 6 7 + 7 6 5 4 3 2 1 0 15 14 13 12 11 10 9 8 23 22 21 20 19 18 17 16 31 30 29 28 27 26 25 24 + 0 1 2 3 + +因此，QUIRK_LITTLE_ENDIAN意味着在内存区域内，每个4字节的字的每个字节都被放置在与 +该字的边界相比的镜像位置。 + + +4. 如果设置了QUIRK_MSB_ON_THE_RIGHT和QUIRK_LITTLE_ENDIAN，我们这样做： + +:: + + 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 + 4 5 6 7 + 0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 + 0 1 2 3 + + +5. 如果只设置了QUIRK_LSW32_IS_FIRST，我们这样做： + +:: + + 31 30 29 28 27 26 25 24 23 22 21 20 19 18 17 16 15 14 13 12 11 10 9 8 7 6 5 4 3 2 1 0 + 3 2 1 0 + 63 62 61 60 59 58 57 56 55 54 53 52 51 50 49 48 47 46 45 44 43 42 41 40 39 38 37 36 35 34 33 32 + 7 6 5 4 + +在这种情况下，8字节内存区域解释如下：前4字节对应最不重要的4字节的字，后4字节对应 +更重要的4字节的字。 + +6. 如果设置了QUIRK_LSW32_IS_FIRST和QUIRK_MSB_ON_THE_RIGHT，我们这样做： + +:: + + 24 25 26 27 28 29 30 31 16 17 18 19 20 21 22 23 8 9 10 11 12 13 14 15 0 1 2 3 4 5 6 7 + 3 2 1 0 + 56 57 58 59 60 61 62 63 48 49 50 51 52 53 54 55 40 41 42 43 44 45 46 47 32 33 34 35 36 37 38 39 + 7 6 5 4 + + +7. 如果设置了QUIRK_LSW32_IS_FIRST和QUIRK_LITTLE_ENDIAN，则如下所示： + +:: + + 7 6 5 4 3 2 1 0 15 14 13 12 11 10 9 8 23 22 21 20 19 18 17 16 31 30 29 28 27 26 25 24 + 0 1 2 3 + 39 38 37 36 35 34 33 32 47 46 45 44 43 42 41 40 55 54 53 52 51 50 49 48 63 62 61 60 59 58 57 56 + 4 5 6 7 + + +8. 如果设置了QUIRK_LSW32_IS_FIRST，QUIRK_LITTLE_ENDIAN和QUIRK_MSB_ON_THE_RIGHT， + 则如下所示： + +:: + + 0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 + 0 1 2 3 + 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 + 4 5 6 7 + + +我们总是认为我们的偏移量好像没有特殊性，然后在访问内存区域之前翻译它们。 + +预期用途 +-------- + +选择使用该API的驱动程序首先需要确定上述3种quirk组合（共8种）中的哪一种与硬件文档 +中描述的相匹配。然后，他们应该封装packing()函数，创建一个新的xxx_packing()，使用 +适当的QUIRK_* one-hot 位集合来调用它。 + +packing()函数返回一个int类型的错误码，以防止程序员使用不正确的API。这些错误预计不 +会在运行时发生，因此xxx_packing()返回void并简单地接受这些错误是合理的。它可以选择 +转储栈或打印错误描述。 diff --git a/Documentation/translations/zh_CN/core-api/printk-basics.rst b/Documentation/translations/zh_CN/core-api/printk-basics.rst index d574de3167c8..59c6efb3fc41 100644 --- a/Documentation/translations/zh_CN/core-api/printk-basics.rst +++ b/Documentation/translations/zh_CN/core-api/printk-basics.rst @@ -6,6 +6,7 @@ :翻译: 司延腾 Yanteng Si <siyanteng@loongson.cn> + 周彬彬 Binbin Zhou <zhoubinbin@loongson.cn> .. _cn_printk-basics.rst: @@ -107,6 +108,4 @@ pr_debug()和pr_devel()，除非定义了 ``DEBUG`` (或者在pr_debug()的情 该API在以下内核代码中: -kernel/printk/printk.c - include/linux/printk.h diff --git a/Documentation/translations/zh_CN/core-api/printk-formats.rst b/Documentation/translations/zh_CN/core-api/printk-formats.rst index ce39c788cf5a..bd36d35eba4e 100644 --- a/Documentation/translations/zh_CN/core-api/printk-formats.rst +++ b/Documentation/translations/zh_CN/core-api/printk-formats.rst @@ -5,6 +5,7 @@ :翻译: 司延腾 Yanteng Si <siyanteng@loongson.cn> + 周彬彬 Binbin Zhou <zhoubinbin@loongson.cn> .. _cn_printk-formats.rst: @@ -548,7 +549,7 @@ nodemask_pr_args()来方便打印cpumask和nodemask。 :: - %pGp referenced|uptodate|lru|active|private|node=0|zone=2|lastcpupid=0x1fffff + %pGp 0x17ffffc0002036(referenced|uptodate|lru|active|private|node=0|zone=2|lastcpupid=0x1fffff) %pGg GFP_USER|GFP_DMA32|GFP_NOWARN %pGv read|exec|mayread|maywrite|mayexec|denywrite diff --git a/Documentation/translations/zh_CN/core-api/rbtree.rst b/Documentation/translations/zh_CN/core-api/rbtree.rst new file mode 100644 index 000000000000..a3e1555cb974 --- /dev/null +++ b/Documentation/translations/zh_CN/core-api/rbtree.rst @@ -0,0 +1,391 @@ +.. SPDX-License-Identifier: GPL-2.0 +.. include:: ../disclaimer-zh_CN.rst + +:Original: Documentation/core-api/rbtree.rst + +:翻译: + + 唐艺舟 Tang Yizhou <tangyeechou@gmail.com> + +========================= +Linux中的红黑树（rbtree） +========================= + + +:日期: 2007年1月18日 +:作者: Rob Landley <rob@landley.net> + +何为红黑树，它们有什么用？ +-------------------------- + +红黑树是一种自平衡二叉搜索树，被用来存储可排序的键/值数据对。这与基数树（被用来高效 +存储稀疏数组，因此使用长整型下标来插入/访问/删除结点）和哈希表（没有保持排序因而无法 +容易地按序遍历，同时必须调节其大小和哈希函数，然而红黑树可以优雅地伸缩以便存储任意 +数量的键）不同。 + +红黑树和AVL树类似，但在插入和删除时提供了更快的实时有界的最坏情况性能（分别最多两次 +旋转和三次旋转，来平衡树），查询时间轻微变慢（但时间复杂度仍然是O(log n)）。 + +引用Linux每周新闻（Linux Weekly News）： + + 内核中有多处红黑树的使用案例。最后期限调度器和完全公平排队（CFQ）I/O调度器利用 + 红黑树跟踪请求；数据包CD/DVD驱动程序也是如此。高精度时钟代码使用一颗红黑树组织 + 未完成的定时器请求。ext3文件系统用红黑树跟踪目录项。虚拟内存区域（VMAs）、epoll + 文件描述符、密码学密钥和在“分层令牌桶”调度器中的网络数据包都由红黑树跟踪。 + +本文档涵盖了对Linux红黑树实现的使用方法。更多关于红黑树的性质和实现的信息，参见： + + Linux每周新闻关于红黑树的文章 + https://lwn.net/Articles/184495/ + + 维基百科红黑树词条 + https://en.wikipedia.org/wiki/Red-black_tree + +红黑树的Linux实现 +----------------- + +Linux的红黑树实现在文件“lib/rbtree.c”中。要使用它，需要“#include <linux/rbtree.h>”。 + +Linux的红黑树实现对速度进行了优化，因此比传统的实现少一个间接层（有更好的缓存局部性）。 +每个rb_node结构体的实例嵌入在它管理的数据结构中，因此不需要靠指针来分离rb_node和它 +管理的数据结构。用户应该编写他们自己的树搜索和插入函数，来调用已提供的红黑树函数， +而不是使用一个比较回调函数指针。加锁代码也留给红黑树的用户编写。 + +创建一颗红黑树 +-------------- + +红黑树中的数据结点是包含rb_node结构体成员的结构体:: + + struct mytype { + struct rb_node node; + char *keystring; + }; + +当处理一个指向内嵌rb_node结构体的指针时，包住rb_node的结构体可用标准的container_of() +宏访问。此外，个体成员可直接用rb_entry(node, type, member)访问。 + +每颗红黑树的根是一个rb_root数据结构，它由以下方式初始化为空: + + struct rb_root mytree = RB_ROOT; + +在一颗红黑树中搜索值 +-------------------- + +为你的树写一个搜索函数是相当简单的：从树根开始，比较每个值，然后根据需要继续前往左边或 +右边的分支。 + +示例:: + + struct mytype *my_search(struct rb_root *root, char *string) + { + struct rb_node *node = root->rb_node; + + while (node) { + struct mytype *data = container_of(node, struct mytype, node); + int result; + + result = strcmp(string, data->keystring); + + if (result < 0) + node = node->rb_left; + else if (result > 0) + node = node->rb_right; + else + return data; + } + return NULL; + } + +在一颗红黑树中插入数据 +---------------------- + +在树中插入数据的步骤包括：首先搜索插入新结点的位置，然后插入结点并对树再平衡 +（"recoloring"）。 + +插入的搜索和上文的搜索不同，它要找到嫁接新结点的位置。新结点也需要一个指向它的父节点 +的链接，以达到再平衡的目的。 + +示例:: + + int my_insert(struct rb_root *root, struct mytype *data) + { + struct rb_node **new = &(root->rb_node), *parent = NULL; + + /* Figure out where to put new node */ + while (*new) { + struct mytype *this = container_of(*new, struct mytype, node); + int result = strcmp(data->keystring, this->keystring); + + parent = *new; + if (result < 0) + new = &((*new)->rb_left); + else if (result > 0) + new = &((*new)->rb_right); + else + return FALSE; + } + + /* Add new node and rebalance tree. */ + rb_link_node(&data->node, parent, new); + rb_insert_color(&data->node, root); + + return TRUE; + } + +在一颗红黑树中删除或替换已经存在的数据 +-------------------------------------- + +若要从树中删除一个已经存在的结点，调用:: + + void rb_erase(struct rb_node *victim, struct rb_root *tree); + +示例:: + + struct mytype *data = mysearch(&mytree, "walrus"); + + if (data) { + rb_erase(&data->node, &mytree); + myfree(data); + } + +若要用一个新结点替换树中一个已经存在的键值相同的结点，调用:: + + void rb_replace_node(struct rb_node *old, struct rb_node *new, + struct rb_root *tree); + +通过这种方式替换结点不会对树做重排序：如果新结点的键值和旧结点不同，红黑树可能被 +破坏。 + +（按排序的顺序）遍历存储在红黑树中的元素 +---------------------------------------- + +我们提供了四个函数，用于以排序的方式遍历一颗红黑树的内容。这些函数可以在任意红黑树 +上工作，并且不需要被修改或包装（除非加锁的目的）:: + + struct rb_node *rb_first(struct rb_root *tree); + struct rb_node *rb_last(struct rb_root *tree); + struct rb_node *rb_next(struct rb_node *node); + struct rb_node *rb_prev(struct rb_node *node); + +要开始迭代，需要使用一个指向树根的指针调用rb_first()或rb_last()，它将返回一个指向 +树中第一个或最后一个元素所包含的节点结构的指针。要继续的话，可以在当前结点上调用 +rb_next()或rb_prev()来获取下一个或上一个结点。当没有剩余的结点时，将返回NULL。 + +迭代器函数返回一个指向被嵌入的rb_node结构体的指针，由此，包住rb_node的结构体可用 +标准的container_of()宏访问。此外，个体成员可直接用rb_entry(node, type, member) +访问。 + +示例:: + + struct rb_node *node; + for (node = rb_first(&mytree); node; node = rb_next(node)) + printk("key=%s\n", rb_entry(node, struct mytype, node)->keystring); + +带缓存的红黑树 +-------------- + +计算最左边（最小的）结点是二叉搜索树的一个相当常见的任务，例如用于遍历，或用户根据 +他们自己的逻辑依赖一个特定的顺序。为此，用户可以使用'struct rb_root_cached'来优化 +时间复杂度为O(logN)的rb_first()的调用，以简单地获取指针，避免了潜在的昂贵的树迭代。 +维护操作的额外运行时间开销可忽略，不过内存占用较大。 + +和rb_root结构体类似，带缓存的红黑树由以下方式初始化为空:: + + struct rb_root_cached mytree = RB_ROOT_CACHED; + +带缓存的红黑树只是一个常规的rb_root，加上一个额外的指针来缓存最左边的节点。这使得 +rb_root_cached可以存在于rb_root存在的任何地方，并且只需增加几个接口来支持带缓存的 +树:: + + struct rb_node *rb_first_cached(struct rb_root_cached *tree); + void rb_insert_color_cached(struct rb_node *, struct rb_root_cached *, bool); + void rb_erase_cached(struct rb_node *node, struct rb_root_cached *); + +操作和删除也有对应的带缓存的树的调用:: + + void rb_insert_augmented_cached(struct rb_node *node, struct rb_root_cached *, + bool, struct rb_augment_callbacks *); + void rb_erase_augmented_cached(struct rb_node *, struct rb_root_cached *, + struct rb_augment_callbacks *); + + +对增强型红黑树的支持 +-------------------- + +增强型红黑树是一种在每个结点里存储了“一些”附加数据的红黑树，其中结点N的附加数据 +必须是以N为根的子树中所有结点的内容的函数。它是建立在红黑树基础设施之上的可选特性。 +想要使用这个特性的红黑树用户，插入和删除结点时必须调用增强型接口并提供增强型回调函数。 + +实现增强型红黑树操作的C文件必须包含<linux/rbtree_augmented.h>而不是<linux/rbtree.h>。 +注意，linux/rbtree_augmented.h暴露了一些红黑树实现的细节而你不应依赖它们，请坚持 +使用文档记录的API，并且不要在头文件中包含<linux/rbtree_augmented.h>，以最小化你的 +用户意外地依赖这些实现细节的可能。 + +插入时，用户必须更新通往被插入节点的路径上的增强信息，然后像往常一样调用rb_link_node()， +然后是rb_augment_inserted()而不是平时的rb_insert_color()调用。如果 +rb_augment_inserted()再平衡了红黑树，它将回调至一个用户提供的函数来更新受影响的 +子树上的增强信息。 + +删除一个结点时，用户必须调用rb_erase_augmented()而不是rb_erase()。 +rb_erase_augmented()回调至一个用户提供的函数来更新受影响的子树上的增强信息。 + +在两种情况下，回调都是通过rb_augment_callbacks结构体提供的。必须定义3个回调： + +- 一个传播回调，它更新一个给定结点和它的祖先们的增强数据，直到一个给定的停止点 + （如果是NULL，将更新一路更新到树根）。 + +- 一个复制回调，它将一颗给定子树的增强数据复制到一个新指定的子树树根。 + +- 一个树旋转回调，它将一颗给定的子树的增强值复制到新指定的子树树根上，并重新计算 + 先前的子树树根的增强值。 + +rb_erase_augmented()编译后的代码可能会内联传播、复制回调，这将导致函数体积更大， +因此每个增强型红黑树的用户应该只有一个rb_erase_augmented()的调用点，以限制编译后 +的代码大小。 + + +使用示例 +^^^^^^^^ + +区间树是增强型红黑树的一个例子。参考Cormen，Leiserson，Rivest和Stein写的 +《算法导论》。区间树的更多细节： + +经典的红黑树只有一个键，它不能直接用来存储像[lo:hi]这样的区间范围，也不能快速查找 +与新的lo:hi重叠的部分，或者查找是否有与新的lo:hi完全匹配的部分。 + +然而，红黑树可以被增强，以一种结构化的方式来存储这种区间范围，从而使高效的查找和 +精确匹配成为可能。 + +这个存储在每个节点中的“额外信息”是其所有后代结点中的最大hi（max_hi）值。这个信息 +可以保持在每个结点上，只需查看一下该结点和它的直系子结点们。这将被用于时间复杂度 +为O(log n)的最低匹配查找（所有可能的匹配中最低的起始地址），就像这样:: + + struct interval_tree_node * + interval_tree_first_match(struct rb_root *root, + unsigned long start, unsigned long last) + { + struct interval_tree_node *node; + + if (!root->rb_node) + return NULL; + node = rb_entry(root->rb_node, struct interval_tree_node, rb); + + while (true) { + if (node->rb.rb_left) { + struct interval_tree_node *left = + rb_entry(node->rb.rb_left, + struct interval_tree_node, rb); + if (left->__subtree_last >= start) { + /* + * Some nodes in left subtree satisfy Cond2. + * Iterate to find the leftmost such node N. + * If it also satisfies Cond1, that's the match + * we are looking for. Otherwise, there is no + * matching interval as nodes to the right of N + * can't satisfy Cond1 either. + */ + node = left; + continue; + } + } + if (node->start <= last) { /* Cond1 */ + if (node->last >= start) /* Cond2 */ + return node; /* node is leftmost match */ + if (node->rb.rb_right) { + node = rb_entry(node->rb.rb_right, + struct interval_tree_node, rb); + if (node->__subtree_last >= start) + continue; + } + } + return NULL; /* No match */ + } + } + +插入/删除是通过以下增强型回调来定义的:: + + static inline unsigned long + compute_subtree_last(struct interval_tree_node *node) + { + unsigned long max = node->last, subtree_last; + if (node->rb.rb_left) { + subtree_last = rb_entry(node->rb.rb_left, + struct interval_tree_node, rb)->__subtree_last; + if (max < subtree_last) + max = subtree_last; + } + if (node->rb.rb_right) { + subtree_last = rb_entry(node->rb.rb_right, + struct interval_tree_node, rb)->__subtree_last; + if (max < subtree_last) + max = subtree_last; + } + return max; + } + + static void augment_propagate(struct rb_node *rb, struct rb_node *stop) + { + while (rb != stop) { + struct interval_tree_node *node = + rb_entry(rb, struct interval_tree_node, rb); + unsigned long subtree_last = compute_subtree_last(node); + if (node->__subtree_last == subtree_last) + break; + node->__subtree_last = subtree_last; + rb = rb_parent(&node->rb); + } + } + + static void augment_copy(struct rb_node *rb_old, struct rb_node *rb_new) + { + struct interval_tree_node *old = + rb_entry(rb_old, struct interval_tree_node, rb); + struct interval_tree_node *new = + rb_entry(rb_new, struct interval_tree_node, rb); + + new->__subtree_last = old->__subtree_last; + } + + static void augment_rotate(struct rb_node *rb_old, struct rb_node *rb_new) + { + struct interval_tree_node *old = + rb_entry(rb_old, struct interval_tree_node, rb); + struct interval_tree_node *new = + rb_entry(rb_new, struct interval_tree_node, rb); + + new->__subtree_last = old->__subtree_last; + old->__subtree_last = compute_subtree_last(old); + } + + static const struct rb_augment_callbacks augment_callbacks = { + augment_propagate, augment_copy, augment_rotate + }; + + void interval_tree_insert(struct interval_tree_node *node, + struct rb_root *root) + { + struct rb_node **link = &root->rb_node, *rb_parent = NULL; + unsigned long start = node->start, last = node->last; + struct interval_tree_node *parent; + + while (*link) { + rb_parent = *link; + parent = rb_entry(rb_parent, struct interval_tree_node, rb); + if (parent->__subtree_last < last) + parent->__subtree_last = last; + if (start < parent->start) + link = &parent->rb.rb_left; + else + link = &parent->rb.rb_right; + } + + node->__subtree_last = last; + rb_link_node(&node->rb, rb_parent, link); + rb_insert_augmented(&node->rb, root, &augment_callbacks); + } + + void interval_tree_remove(struct interval_tree_node *node, + struct rb_root *root) + { + rb_erase_augmented(&node->rb, root, &augment_callbacks); + } diff --git a/Documentation/translations/zh_CN/core-api/symbol-namespaces.rst b/Documentation/translations/zh_CN/core-api/symbol-namespaces.rst index 6abf7ed534ca..bb16f0611046 100644 --- a/Documentation/translations/zh_CN/core-api/symbol-namespaces.rst +++ b/Documentation/translations/zh_CN/core-api/symbol-namespaces.rst @@ -52,7 +52,7 @@ 相应的 ksymtab 条目结构体 ``kernel_symbol`` 将有相应的成员 ``命名空间`` 集。 导出时未指明命名空间的符号将指向 ``NULL`` 。如果没有定义命名空间，则默认没有。 -``modpost`` 和kernel/module.c分别在构建时或模块加载时使用名称空间。 +``modpost`` 和kernel/module/main.c分别在构建时或模块加载时使用名称空间。 2.2 使用DEFAULT_SYMBOL_NAMESPACE定义 ==================================== diff --git a/Documentation/translations/zh_CN/core-api/watch_queue.rst b/Documentation/translations/zh_CN/core-api/watch_queue.rst new file mode 100644 index 000000000000..23b17ae2e4e2 --- /dev/null +++ b/Documentation/translations/zh_CN/core-api/watch_queue.rst @@ -0,0 +1,313 @@ +.. SPDX-License-Identifier: GPL-2.0+ + +.. include:: ../disclaimer-zh_CN.rst + +:Original: Documentation/core-api/watch_queue.rst + +:翻译: + +周彬彬 Binbin Zhou <zhoubinbin@loongson.cn> + +:校译: + +司延腾 Yanteng Si <siyanteng@loongson.cn> +吴想成 Wu Xiangcheng <bobwxc@email.cn> + + +============ +通用通知机制 +============ + +通用通知机制是建立在标准管道驱动之上的，它可以有效地将来自内核的通知消息拼接到用 +户空间打开的管道中。这可以与以下方面结合使用:: + + * Key/keyring 通知 + +通知缓冲区可以通过以下方式启用： + + “General setup”/“General notification queue” + (CONFIG_WATCH_QUEUE) + +文档包含以下章节： + +.. contents:: :local: + + +概述 +==== + +该设施以一种特殊模式打开的管道形式出现，管道的内部环形缓冲区用于保存内核生成的消 +息。然后通过read()读出这些消息。在此类管道上禁用拼接以及类似的操作，因为它们希望 +在某些情况下将其添加的内容还原到环中-这可能最终会与通知消息重叠。 + +管道的所有者必须告诉内核它想通过该管道观察哪些源。只有连接到该管道上的源才会将消 +息插入其中。请注意，一个源可能绑定到多个管道，并同时将消息插入到所有管道中。 + +还可以将过滤器放置在管道上，以便在不感兴趣时可以忽略某些源类型和子事件。 + +如果环中没有可用的插槽，或者没有预分配的消息缓冲区可用，则将丢弃消息。在这两种情 +况下，read()都会在读取缓冲区中当前的最后一条消息后，将WATCH_META_LOSS_NOTIFICATION +插入到输出缓冲区中。 + +请注意，当生成一个通知时，内核不会等待消费者收集它，而是继续执行。这意味着可以在 +持有自旋锁的同时生成通知，并且还可以保护内核不被用户空间故障无限期地阻碍。 + + +消息结构 +======== + +通知消息由一个简短的头部开始:: + + struct watch_notification { + __u32 type:24; + __u32 subtype:8; + __u32 info; + }; + +“type”表示通知记录的来源，“subtype”表示该来源的记录类型（见下文观测源章节）。该类 +型也可以是“WATCH_TYPE_META”。这是一个由观测队列本身在内部生成的特殊记录类型。有两 +个子类型： + + * WATCH_META_REMOVAL_NOTIFICATION + * WATCH_META_LOSS_NOTIFICATION + +第一个表示安装了观察的对象已被删除或销毁，第二个表示某些消息已丢失。 + +“info”表示一系列东西，包括： + + * 消息的长度，以字节为单位，包括头（带有WATCH_INFO_LENGTH的掩码，并按 + WATCH_INFO_LENGTH__SHIFT移位）。这表示记录的大小，可能在8到127字节之间。 + + * 观测ID（带有WATCH_INFO_ID掩码，并按WATCH_INFO_ID__SHIFT移位）。这表示观测的主 + 叫ID，可能在0到255之间。多个观测组可以共享一个队列，这提供了一种区分它们的方法。 + + * 特定类型的字段（WATCH_INFO_TYPE_INFO）。这是由通知生产者设置的，以指示类型和 + 子类型的某些特定含义。 + +除长度外，信息中的所有内容都可以用于过滤。 + +头部后面可以有补充信息。此格式是由类型和子类型决定的。 + + +观测列表（通知源）API +===================== + +“观测列表“是订阅通知源的观测者的列表。列表可以附加到对象（比如键或超级块），也可 +以是全局的（比如对于设备事件）。从用户空间的角度来看，一个非全局的观测列表通常是 +通过引用它所属的对象来引用的（比如使用KEYCTL_NOTIFY并给它一个密钥序列号来观测特定 +的密钥）。 + +为了管理观测列表，提供了以下函数： + + * :: + + void init_watch_list(struct watch_list *wlist, + void (*release_watch)(struct watch *wlist)); + + 初始化一个观测列表。 如果 ``release_watch`` 不是NULL，那么这表示当watch_list对 + 象被销毁时，应该调用函数来丢弃观测列表对被观测对象的任何引用。 + + * ``void remove_watch_list(struct watch_list *wlist);`` + + 这将删除订阅watch_list的所有观测，并释放它们，然后销毁watch_list对象本身。 + + +观测队列（通知输出）API +======================= + +“观测队列”是由应用程序分配的用以记录通知的缓冲区，其工作原理完全隐藏在管道设备驱 +动中，但必须获得对它的引用才能设置观测。可以通过以下方式进行管理： + + * ``struct watch_queue *get_watch_queue(int fd);`` + + 由于观测队列在内核中通过实现缓冲区的管道的文件描述符表示，用户空间必须通过系 + 统调用传递该文件描述符，这可以用于从系统调用中查找指向观测队列的不透明指针。 + + * ``void put_watch_queue(struct watch_queue *wqueue);`` + + 该函数用以丢弃从 ``get_watch_queue()`` 获得的引用。 + + +观测订阅API +=========== + +“观测”是观测列表上的订阅，表示观测队列，从而表示应写入通知记录的缓冲区。观测队列 +对象还可以携带该对象的过滤规则，由用户空间设置。watch结构体的某些部分可以由驱动程 +序设置:: + + struct watch { + union { + u32 info_id; /* 在info字段中进行OR运算的ID */ + ... + }; + void *private; /* 被观测对象的私有数据 */ + u64 id; /* 内部标识符 */ + ... + }; + +``info_id`` 值是从用户空间获得并按WATCH_INFO_ID__SHIFT移位的8位数字。当通知写入关 +联的观测队列缓冲区时，这将与struct watch_notification::info的WATCH_INFO_ID字段进 +行或运算。 + +``private`` 字段是与watch_list相关联的驱动程序数据，并由 ``watch_list::release_watch()`` +函数清除。 + +``id`` 字段是源的ID。使用不同ID发布的通知将被忽略。 + +提供以下函数来管理观测: + + * ``void init_watch(struct watch *watch, struct watch_queue *wqueue);`` + + 初始化一个观测对象，把它的指针设置到观察队列中，使用适当的限制来避免死锁。 + + * ``int add_watch_to_object(struct watch *watch, struct watch_list *wlist);`` + + 将观测订阅到观测列表（通知源）。watch结构体中的driver-settable字段必须在调用 + 它之前设置。 + + * :: + + int remove_watch_from_object(struct watch_list *wlist, + struct watch_queue *wqueue, + u64 id, false); + + 从观测列表中删除一个观测，该观测必须与指定的观测队列（``wqueue``）和对象标识 + 符（``id``）匹配。通知（``WATCH_META_REMOVAL_NOTIFICATION``）被发送到观测队列 + 表示该观测已被删除。 + + * ``int remove_watch_from_object(struct watch_list *wlist, NULL, 0, true);`` + + 从观测列表中删除所有观测。预计这将被称为销毁前的准备工作，届时新的观测将无法 + 访问观测列表。通知（``WATCH_META_REMOVAL_NOTIFICATION``）被发送到每个订阅观测 + 的观测队列，以表明该观测已被删除。 + + +通知发布API +=========== + +要将通知发布到观测列表以便订阅的观测可以看到，应使用以下函数:: + + void post_watch_notification(struct watch_list *wlist, + struct watch_notification *n, + const struct cred *cred, + u64 id); + +应预先设置通知格式，并应传入一个指向头部（``n``）的指针。通知可能大于此值，并且缓 +冲槽为单位的大小在 ``n->info & WATCH_INFO_LENGTH`` 中注明。 + +``cred`` 结构体表示源（对象）的证书，并传递给LSM，例如SELinux，以允许或禁止根据该队 +列（对象）的证书在每个单独队列中记录注释。 + +``id`` 是源对象ID（如密钥上的序列号）。只有设置相同ID的观测才能看到这个通知。 + + +观测源 +====== + +任何特定的缓冲区都可以从多个源获取信息。 这些源包括: + + * WATCH_TYPE_KEY_NOTIFY + + 这种类型的通知表示密钥和密钥环的变化，包括密钥环内容或密钥属性的变化。 + + 更多信息请参见Documentation/security/keys/core.rst。 + + +事件过滤 +======== + +当创建观测队列后，我们可以应用一组过滤器以限制接收的事件:: + + struct watch_notification_filter filter = { + ... + }; + ioctl(fd, IOC_WATCH_QUEUE_SET_FILTER, &filter) + +过滤器的描述的类型变量是:: + + struct watch_notification_filter { + __u32 nr_filters; + __u32 __reserved; + struct watch_notification_type_filter filters[]; + }; + +其中“nr_filters”表示filters[]数组中过滤器的数量，而“__reserved”应为0。 +“filter”数组有以下类型的元素:: + + struct watch_notification_type_filter { + __u32 type; + __u32 info_filter; + __u32 info_mask; + __u32 subtype_filter[8]; + }; + +其中： + + * ``type`` 是过滤的事件类型，应类似于“WATCH_TYPE_KEY_NOTIFY”。 + + * ``info_filter`` 与 ``info_mask`` 充当通知记录的信息字段的过滤器，只有在以下情 + 况，通知才会写入缓冲区:: + + (watch.info & info_mask) == info_filter + + 例如，这可以用于忽略不在一个挂载树上的观测点的事件。 + + * ``subtype_filter`` 是一个位掩码，表示感兴趣的子类型。subtype_filter[0]的 + bit[0]对应子类型0，bit[1]对应子类型1，以此类推。 + +若ioctl()的参数为NULL，则过滤器将被移除，并且来自观测源的所有事件都将通过。 + + +用户空间代码示例 +================ + +缓冲区的创建如下所示:: + + pipe2(fds, O_TMPFILE); + ioctl(fds[1], IOC_WATCH_QUEUE_SET_SIZE, 256); + +它可以被设置成接收密钥环变化的通知:: + + keyctl(KEYCTL_WATCH_KEY, KEY_SPEC_SESSION_KEYRING, fds[1], 0x01); + +然后，这些通知可以被如下方式所使用:: + + static void consumer(int rfd, struct watch_queue_buffer *buf) + { + unsigned char buffer[128]; + ssize_t buf_len; + + while (buf_len = read(rfd, buffer, sizeof(buffer)), + buf_len > 0 + ) { + void *p = buffer; + void *end = buffer + buf_len; + while (p < end) { + union { + struct watch_notification n; + unsigned char buf1[128]; + } n; + size_t largest, len; + + largest = end - p; + if (largest > 128) + largest = 128; + memcpy(&n, p, largest); + + len = (n->info & WATCH_INFO_LENGTH) >> + WATCH_INFO_LENGTH__SHIFT; + if (len == 0 || len > largest) + return; + + switch (n.n.type) { + case WATCH_TYPE_META: + got_meta(&n.n); + case WATCH_TYPE_KEY_NOTIFY: + saw_key_change(&n.n); + break; + } + + p += len; + } + } + } diff --git a/Documentation/translations/zh_CN/core-api/workqueue.rst b/Documentation/translations/zh_CN/core-api/workqueue.rst index e372fa5cf101..f6567cf9d3fb 100644 --- a/Documentation/translations/zh_CN/core-api/workqueue.rst +++ b/Documentation/translations/zh_CN/core-api/workqueue.rst @@ -6,6 +6,7 @@ :翻译: 司延腾 Yanteng Si <siyanteng@loongson.cn> + 周彬彬 Binbin Zhou <zhoubinbin@loongson.cn> .. _cn_workqueue.rst: @@ -178,10 +179,6 @@ workqueue将自动创建与属性相匹配的后备工作者池。调节并发 这个标志对于未绑定的wq来说是没有意义的。 -请注意，标志 ``WQ_NON_REENTRANT`` 不再存在，因为现在所有的工作 -队列都是不可逆的——任何工作项都保证在任何时间内最多被整个系统的一 -个工作者执行。 - ``max_active`` -------------- @@ -328,6 +325,22 @@ And with cmwq with ``@max_active`` >= 3, :: 工作项函数在堆栈追踪中应该是微不足道的。 +不可重入条件 +============ + +工作队列保证，如果在工作项排队后满足以下条件，则工作项不能重入： + + + 1. 工作函数没有被改变。 + 2. 没有人将该工作项排到另一个工作队列中。 + 3. 该工作项尚未被重新启动。 + +换言之，如果上述条件成立，则保证在任何给定时间最多由一个系统范围内的工作程序执行 +该工作项。 + +请注意，在self函数中将工作项重新排队（到同一队列）不会破坏这些条件，因此可以安全 +地执行此操作。否则在破坏工作函数内部的条件时需要小心。 + 内核内联文档参考 ================ diff --git a/Documentation/translations/zh_CN/core-api/xarray.rst b/Documentation/translations/zh_CN/core-api/xarray.rst index ff2d9bcb7c34..fb19324966ce 100644 --- a/Documentation/translations/zh_CN/core-api/xarray.rst +++ b/Documentation/translations/zh_CN/core-api/xarray.rst @@ -6,6 +6,7 @@ :翻译: 司延腾 Yanteng Si <siyanteng@loongson.cn> + 周彬彬 Binbin Zhou <zhoubinbin@loongson.cn> :校译: @@ -254,7 +255,8 @@ __xa_set_mark() 和 __xa_clear_mark() 函数也适用于你查找一个条目并 高级API是基于xa_state的。这是一个不透明的数据结构，你使用XA_STATE()宏在堆栈中声明。这个宏初始化了 xa_state，准备开始在XArray上移动。它被用作一个游标来保持在XArray中的位置，并让你把各种操作组合在一 -起，而不必每次都从头开始。 +起，而不必每次都从头开始。xa_state的内容受rcu_read_lock()或xas_lock()的保护。如果需要删除保护状态 +和树的这些锁中的任何一个，你必须调用xas_pause()以便将来的调用不会依赖于状态中未受保护的部分。 xa_state也被用来存储错误(store errors)。你可以调用xas_error()来检索错误。所有的操作在进行之前都 会检查xa_state是否处于错误状态，所以你没有必要在每次调用之后检查错误；你可以连续进行多次调用，只在 diff --git a/Documentation/translations/zh_CN/cpu-freq/cpu-drivers.rst b/Documentation/translations/zh_CN/cpu-freq/cpu-drivers.rst index 87a36044f828..2ca92042767b 100644 --- a/Documentation/translations/zh_CN/cpu-freq/cpu-drivers.rst +++ b/Documentation/translations/zh_CN/cpu-freq/cpu-drivers.rst @@ -84,6 +84,8 @@ CPUfreq核心层注册一个cpufreq_driver结构体。 .resume - 一个指向per-policy恢复函数的指针，该函数在关中断且在调节器再一次启动前被 调用。 + .ready - 一个指向per-policy准备函数的指针，该函数在策略完全初始化之后被调用。 + .attr - 一个指向NULL结尾的"struct freq_attr"列表的指针，该列表允许导出值到 sysfs。 diff --git a/Documentation/translations/zh_CN/dev-tools/gdb-kernel-debugging.rst b/Documentation/translations/zh_CN/dev-tools/gdb-kernel-debugging.rst new file mode 100644 index 000000000000..17b5ce85a90c --- /dev/null +++ b/Documentation/translations/zh_CN/dev-tools/gdb-kernel-debugging.rst @@ -0,0 +1,167 @@ +.. highlight:: none + +.. include:: ../disclaimer-zh_CN.rst + +:Original: Documentation/dev-tools/gdb-kernel-debugging.rst +:Translator: 高超 gao chao <gaochao49@huawei.com> + +通过gdb调试内核和模块 +===================== + +Kgdb内核调试器、QEMU等虚拟机管理程序或基于JTAG的硬件接口，支持在运行时使用gdb +调试Linux内核及其模块。Gdb提供了一个强大的python脚本接口，内核也提供了一套 +辅助脚本以简化典型的内核调试步骤。本文档为如何启用和使用这些脚本提供了一个简要的教程。 +此教程基于QEMU/KVM虚拟机，但文中示例也适用于其他gdb stub。 + + +环境配置要求 +------------ + +- gdb 7.2+ (推荐版本: 7.4+) 且开启python支持 (通常发行版上都已支持) + +设置 +---- + +- 创建一个QEMU/KVM的linux虚拟机（详情请参考 www.linux-kvm.org 和 www.qemu.org ）。 + 对于交叉开发，https://landley.net/aboriginal/bin 提供了一些镜像和工具链， + 可以帮助搭建交叉开发环境。 + +- 编译内核时开启CONFIG_GDB_SCRIPTS，关闭CONFIG_DEBUG_INFO_REDUCED。 + 如果架构支持CONFIG_FRAME_POINTER，请保持开启。 + +- 在guest环境上安装该内核。如有必要，通过在内核command line中添加“nokaslr”来关闭KASLR。 + 此外，QEMU允许通过-kernel、-append、-initrd这些命令行选项直接启动内核。 + 但这通常仅在不依赖内核模块时才有效。有关此模式的更多详细信息，请参阅QEMU文档。 + 在这种情况下，如果架构支持KASLR，应该在禁用CONFIG_RANDOMIZE_BASE的情况下构建内核。 + +- 启用QEMU/KVM的gdb stub，可以通过如下方式实现 + + - 在VM启动时，通过在QEMU命令行中添加“-s”参数 + + 或 + + - 在运行时通过从QEMU监视控制台发送“gdbserver” + +- 切换到/path/to/linux-build(内核源码编译)目录 + +- 启动gdb：gdb vmlinux + + 注意：某些发行版可能会将gdb脚本的自动加载限制在已知的安全目录中。 + 如果gdb报告拒绝加载vmlinux-gdb.py（相关命令找不到），请将:: + + add-auto-load-safe-path /path/to/linux-build + + 添加到~/.gdbinit。更多详细信息，请参阅gdb帮助信息。 + +- 连接到已启动的guest环境:: + + (gdb) target remote :1234 + + +使用Linux提供的gdb脚本的示例 +---------------------------- + +- 加载模块（以及主内核）符号:: + + (gdb) lx-symbols + loading vmlinux + scanning for modules in /home/user/linux/build + loading @0xffffffffa0020000: /home/user/linux/build/net/netfilter/xt_tcpudp.ko + loading @0xffffffffa0016000: /home/user/linux/build/net/netfilter/xt_pkttype.ko + loading @0xffffffffa0002000: /home/user/linux/build/net/netfilter/xt_limit.ko + loading @0xffffffffa00ca000: /home/user/linux/build/net/packet/af_packet.ko + loading @0xffffffffa003c000: /home/user/linux/build/fs/fuse/fuse.ko + ... + loading @0xffffffffa0000000: /home/user/linux/build/drivers/ata/ata_generic.ko + +- 对一些尚未加载的模块中的函数函数设置断点，例如:: + + (gdb) b btrfs_init_sysfs + Function "btrfs_init_sysfs" not defined. + Make breakpoint pending on future shared library load? (y or [n]) y + Breakpoint 1 (btrfs_init_sysfs) pending. + +- 继续执行:: + + (gdb) c + +- 加载模块并且能观察到正在加载的符号以及断点命中:: + + loading @0xffffffffa0034000: /home/user/linux/build/lib/libcrc32c.ko + loading @0xffffffffa0050000: /home/user/linux/build/lib/lzo/lzo_compress.ko + loading @0xffffffffa006e000: /home/user/linux/build/lib/zlib_deflate/zlib_deflate.ko + loading @0xffffffffa01b1000: /home/user/linux/build/fs/btrfs/btrfs.ko + + Breakpoint 1, btrfs_init_sysfs () at /home/user/linux/fs/btrfs/sysfs.c:36 + 36 btrfs_kset = kset_create_and_add("btrfs", NULL, fs_kobj); + +- 查看内核的日志缓冲区:: + + (gdb) lx-dmesg + [ 0.000000] Initializing cgroup subsys cpuset + [ 0.000000] Initializing cgroup subsys cpu + [ 0.000000] Linux version 3.8.0-rc4-dbg+ (... + [ 0.000000] Command line: root=/dev/sda2 resume=/dev/sda1 vga=0x314 + [ 0.000000] e820: BIOS-provided physical RAM map: + [ 0.000000] BIOS-e820: [mem 0x0000000000000000-0x000000000009fbff] usable + [ 0.000000] BIOS-e820: [mem 0x000000000009fc00-0x000000000009ffff] reserved + .... + +- 查看当前task struct结构体的字段（仅x86和arm64支持）:: + + (gdb) p $lx_current().pid + $1 = 4998 + (gdb) p $lx_current().comm + $2 = "modprobe\000\000\000\000\000\000\000" + +- 对当前或指定的CPU使用per-cpu函数:: + + (gdb) p $lx_per_cpu("runqueues").nr_running + $3 = 1 + (gdb) p $lx_per_cpu("runqueues", 2).nr_running + $4 = 0 + +- 使用container_of查看更多hrtimers信息:: + + (gdb) set $next = $lx_per_cpu("hrtimer_bases").clock_base[0].active.next + (gdb) p *$container_of($next, "struct hrtimer", "node") + $5 = { + node = { + node = { + __rb_parent_color = 18446612133355256072, + rb_right = 0x0 <irq_stack_union>, + rb_left = 0x0 <irq_stack_union> + }, + expires = { + tv64 = 1835268000000 + } + }, + _softexpires = { + tv64 = 1835268000000 + }, + function = 0xffffffff81078232 <tick_sched_timer>, + base = 0xffff88003fd0d6f0, + state = 1, + start_pid = 0, + start_site = 0xffffffff81055c1f <hrtimer_start_range_ns+20>, + start_comm = "swapper/2\000\000\000\000\000\000" + } + + +命令和辅助调试功能列表 +---------------------- + +命令和辅助调试功能可能会随着时间的推移而改进，此文显示的是初始版本的部分示例:: + + (gdb) apropos lx + function lx_current -- Return current task + function lx_module -- Find module by name and return the module variable + function lx_per_cpu -- Return per-cpu variable + function lx_task_by_pid -- Find Linux task by PID and return the task_struct variable + function lx_thread_info -- Calculate Linux thread_info from task variable + lx-dmesg -- Print Linux kernel log buffer + lx-lsmod -- List currently loaded modules + lx-symbols -- (Re-)load symbols of Linux kernel and currently loaded modules + +可以通过“help <command-name>”或“help function <function-name>”命令 +获取指定命令或指定调试功能的更多详细信息。 diff --git a/Documentation/translations/zh_CN/dev-tools/index.rst b/Documentation/translations/zh_CN/dev-tools/index.rst index 77a8c44cdf49..02577c379007 100644 --- a/Documentation/translations/zh_CN/dev-tools/index.rst +++ b/Documentation/translations/zh_CN/dev-tools/index.rst @@ -25,6 +25,7 @@ Documentation/translations/zh_CN/dev-tools/testing-overview.rst sparse gcov kasan + gdb-kernel-debugging Todolist: @@ -34,7 +35,6 @@ Todolist: - kmemleak - kcsan - kfence - - gdb-kernel-debugging - kgdb - kselftest - kunit/index diff --git a/Documentation/translations/zh_CN/dev-tools/kasan.rst b/Documentation/translations/zh_CN/dev-tools/kasan.rst index 23db9d419047..fe76cbe77ad6 100644 --- a/Documentation/translations/zh_CN/dev-tools/kasan.rst +++ b/Documentation/translations/zh_CN/dev-tools/kasan.rst @@ -11,34 +11,65 @@ 概述 ---- -KernelAddressSANitizer(KASAN)是一种动态内存安全错误检测工具，主要功能是 -检查内存越界访问和使用已释放内存的问题。KASAN有三种模式: +Kernel Address SANitizer(KASAN)是一种动态内存安全错误检测工具，主要功能是 +检查内存越界访问和使用已释放内存的问题。 -1. 通用KASAN（与用户空间的ASan类似） -2. 基于软件标签的KASAN（与用户空间的HWASan类似） -3. 基于硬件标签的KASAN（基于硬件内存标签） +KASAN有三种模式: -由于通用KASAN的内存开销较大，通用KASAN主要用于调试。基于软件标签的KASAN -可用于dogfood测试，因为它具有较低的内存开销，并允许将其用于实际工作量。 -基于硬件标签的KASAN具有较低的内存和性能开销，因此可用于生产。同时可用于 -检测现场内存问题或作为安全缓解措施。 +1. 通用KASAN +2. 基于软件标签的KASAN +3. 基于硬件标签的KASAN -软件KASAN模式（#1和#2）使用编译时工具在每次内存访问之前插入有效性检查， -因此需要一个支持它的编译器版本。 +用CONFIG_KASAN_GENERIC启用的通用KASAN，是用于调试的模式，类似于用户空 +间的ASan。这种模式在许多CPU架构上都被支持，但它有明显的性能和内存开销。 -通用KASAN在GCC和Clang受支持。GCC需要8.3.0或更高版本。任何受支持的Clang -版本都是兼容的，但从Clang 11才开始支持检测全局变量的越界访问。 +基于软件标签的KASAN或SW_TAGS KASAN，通过CONFIG_KASAN_SW_TAGS启用， +可以用于调试和自我测试，类似于用户空间HWASan。这种模式只支持arm64，但其 +适度的内存开销允许在内存受限的设备上用真实的工作负载进行测试。 -基于软件标签的KASAN模式仅在Clang中受支持。 +基于硬件标签的KASAN或HW_TAGS KASAN，用CONFIG_KASAN_HW_TAGS启用，被 +用作现场内存错误检测器或作为安全缓解的模式。这种模式只在支持MTE（内存标签 +扩展）的arm64 CPU上工作，但它的内存和性能开销很低，因此可以在生产中使用。 -硬件KASAN模式（#3）依赖硬件来执行检查，但仍需要支持内存标签指令的编译器 -版本。GCC 10+和Clang 11+支持此模式。 +关于每种KASAN模式的内存和性能影响的细节，请参见相应的Kconfig选项的描述。 -两种软件KASAN模式都适用于SLUB和SLAB内存分配器，而基于硬件标签的KASAN目前 -仅支持SLUB。 +通用模式和基于软件标签的模式通常被称为软件模式。基于软件标签的模式和基于 +硬件标签的模式被称为基于标签的模式。 -目前x86_64、arm、arm64、xtensa、s390、riscv架构支持通用KASAN模式，仅 -arm64架构支持基于标签的KASAN模式。 +支持 +---- + +体系架构 +~~~~~~~~ + +在x86_64、arm、arm64、powerpc、riscv、s390和xtensa上支持通用KASAN， +而基于标签的KASAN模式只在arm64上支持。 + +编译器 +~~~~~~ + +软件KASAN模式使用编译时工具在每个内存访问之前插入有效性检查，因此需要一个 +提供支持的编译器版本。基于硬件标签的模式依靠硬件来执行这些检查，但仍然需要 +一个支持内存标签指令的编译器版本。 + +通用KASAN需要GCC 8.3.0版本或更高版本，或者内核支持的任何Clang版本。 + +基于软件标签的KASAN需要GCC 11+或者内核支持的任何Clang版本。 + +基于硬件标签的KASAN需要GCC 10+或Clang 12+。 + +内存类型 +~~~~~~~~ + +通用KASAN支持在所有的slab、page_alloc、vmap、vmalloc、堆栈和全局内存 +中查找错误。 + +基于软件标签的KASAN支持slab、page_alloc、vmalloc和堆栈内存。 + +基于硬件标签的KASAN支持slab、page_alloc和不可执行的vmalloc内存。 + +对于slab，两种软件KASAN模式都支持SLUB和SLAB分配器，而基于硬件标签的 +KASAN只支持SLUB。 用法 ---- @@ -53,7 +84,7 @@ arm64架构支持基于标签的KASAN模式。 对于软件模式，还可以在 ``CONFIG_KASAN_OUTLINE`` 和 ``CONFIG_KASAN_INLINE`` 之间进行选择。outline和inline是编译器插桩类型。前者产生较小的二进制文件， -而后者快1.1-2倍。 +而后者快2倍。 要将受影响的slab对象的alloc和free堆栈跟踪包含到报告中，请启用 ``CONFIG_STACKTRACE`` 。要包括受影响物理页面的分配和释放堆栈跟踪的话， @@ -172,21 +203,29 @@ KASAN受通用 ``panic_on_warn`` 命令行参数的影响。启用该功能后 默认情况下，KASAN只为第一次无效内存访问打印错误报告。使用 ``kasan_multi_shot`` ， KASAN会针对每个无效访问打印报告。这有效地禁用了KASAN报告的 ``panic_on_warn`` 。 +另外，独立于 ``panic_on_warn`` , ``kasan.fault=`` 引导参数可以用来控制恐慌和报 +告行为: + +- ``kasan.fault=report`` 或 ``=panic`` 控制是只打印KASAN报告还是同时使内核恐慌 + (默认: ``report`` )。即使启用了 ``kasan_multi_shot`` ，也会发生内核恐慌。 + 基于硬件标签的KASAN模式（请参阅下面有关各种模式的部分）旨在在生产中用作安全缓解 -措施。因此，它支持允许禁用KASAN或控制其功能的引导参数。 +措施。因此，它支持允许禁用KASAN或控制其功能的附加引导参数。 - ``kasan=off`` 或 ``=on`` 控制KASAN是否启用 (默认: ``on`` )。 -- ``kasan.mode=sync`` 或 ``=async`` 控制KASAN是否配置为同步或异步执行模式(默认: - ``sync`` )。同步模式：当标签检查错误发生时，立即检测到错误访问。异步模式： - 延迟错误访问检测。当标签检查错误发生时，信息存储在硬件中（在arm64的 +- ``kasan.mode=sync`` 、 ``=async`` 或 ``=asymm`` 控制KASAN是否配置 + 为同步或异步执行模式(默认:``sync`` )。 + 同步模式：当标签检查错误发生时，立即检测到错误访问。 + 异步模式：延迟错误访问检测。当标签检查错误发生时，信息存储在硬件中（在arm64的 TFSR_EL1寄存器中）。内核会定期检查硬件，并且仅在这些检查期间报告标签错误。 + 非对称模式：读取时同步检测不良访问，写入时异步检测。 + +- ``kasan.vmalloc=off`` 或 ``=on`` 禁用或启用vmalloc分配的标记（默认：``on`` ）。 - ``kasan.stacktrace=off`` 或 ``=on`` 禁用或启用alloc和free堆栈跟踪收集 (默认: ``on`` )。 -- ``kasan.fault=report`` 或 ``=panic`` 控制是只打印KASAN报告还是同时使内核恐慌 - (默认: ``report`` )。即使启用了 ``kasan_multi_shot`` ，也会发生内核恐慌。 实施细则 -------- @@ -244,7 +283,6 @@ KASAN会针对每个无效访问打印报告。这有效地禁用了KASAN报告 基于软件标签的KASAN使用0xFF作为匹配所有指针标签（不检查通过带有0xFF指针标签 的指针进行的访问）。值0xFE当前保留用于标记已释放的内存区域。 -基于软件标签的KASAN目前仅支持对Slab和page_alloc内存进行标记。 基于硬件标签的KASAN模式 ~~~~~~~~~~~~~~~~~~~~~~~ @@ -262,8 +300,6 @@ KASAN会针对每个无效访问打印报告。这有效地禁用了KASAN报告 基于硬件标签的KASAN使用0xFF作为匹配所有指针标签（不检查通过带有0xFF指针标签的 指针进行的访问）。值0xFE当前保留用于标记已释放的内存区域。 -基于硬件标签的KASAN目前仅支持对Slab和page_alloc内存进行标记。 - 如果硬件不支持MTE（ARMv8.5之前），则不会启用基于硬件标签的KASAN。在这种情况下， 所有KASAN引导参数都将被忽略。 @@ -275,6 +311,8 @@ KASAN会针对每个无效访问打印报告。这有效地禁用了KASAN报告 影子内存 -------- +本节的内容只适用于软件KASAN模式。 + 内核将内存映射到地址空间的几个不同部分。内核虚拟地址的范围很大：没有足够的真实 内存来支持内核可以访问的每个地址的真实影子区域。因此，KASAN只为地址空间的某些 部分映射真实的影子。 @@ -297,7 +335,7 @@ CONFIG_KASAN_VMALLOC ~~~~~~~~~~~~~~~~~~~~ 使用 ``CONFIG_KASAN_VMALLOC`` ，KASAN可以以更大的内存使用为代价覆盖vmalloc -空间。目前，这在x86、riscv、s390和powerpc上受支持。 +空间。目前，这在arm64、x86、riscv、s390和powerpc上受支持。 这通过连接到vmalloc和vmap并动态分配真实的影子内存来支持映射。 @@ -349,10 +387,10 @@ KASAN连接到vmap基础架构以懒清理未使用的影子内存。 ``kasan_disable_current()``/``kasan_enable_current()`` 部分注释这部分代码。 这也会禁用通过函数调用发生的间接访问的报告。 -对于基于标签的KASAN模式（包括硬件模式），要禁用访问检查，请使用 -``kasan_reset_tag()`` 或 ``page_kasan_tag_reset()`` 。请注意，通过 -``page_kasan_tag_reset()`` 临时禁用访问检查需要通过 ``page_kasan_tag`` -/ ``page_kasan_tag_set`` 保存和恢复每页KASAN标签。 +对于基于标签的KASAN模式，要禁用访问检查，请使用 ``kasan_reset_tag()`` 或 +``page_kasan_tag_reset()`` 。请注意，通过 ``page_kasan_tag_reset()`` +临时禁用访问检查需要通过 ``page_kasan_tag`` / ``page_kasan_tag_set`` 保 +存和恢复每页KASAN标签。 测试 ~~~~ @@ -381,11 +419,10 @@ KASAN连接到vmap基础架构以懒清理未使用的影子内存。 当由于缺少KASAN报告而导致测试失败时:: - # kmalloc_double_kzfree: EXPECTATION FAILED at lib/test_kasan.c:629 - Expected kasan_data->report_expected == kasan_data->report_found, but - kasan_data->report_expected == 1 - kasan_data->report_found == 0 - not ok 28 - kmalloc_double_kzfree + # kmalloc_double_kzfree: EXPECTATION FAILED at lib/test_kasan.c:974 + KASAN failure expected in "kfree_sensitive(ptr)", but none occurred + not ok 44 - kmalloc_double_kzfree + 最后打印所有KASAN测试的累积状态。成功:: diff --git a/Documentation/translations/zh_CN/dev-tools/sparse.rst b/Documentation/translations/zh_CN/dev-tools/sparse.rst index 556282437aad..0664c634bc4f 100644 --- a/Documentation/translations/zh_CN/dev-tools/sparse.rst +++ b/Documentation/translations/zh_CN/dev-tools/sparse.rst @@ -106,3 +106,5 @@ __releases - 指定的锁在函数进入时被持有，但在退出时不被持 make 的可选变量 CHECKFLAGS 可以用来向 sparse 工具传递参数。编译系统会自 动向 sparse 工具传递 -Wbitwise 参数。 + +注意sparse定义了__CHECKER__预处理器符号。
\ No newline at end of file diff --git a/Documentation/translations/zh_CN/dev-tools/testing-overview.rst b/Documentation/translations/zh_CN/dev-tools/testing-overview.rst index b7a1d13da6c6..d6f2c65ed511 100644 --- a/Documentation/translations/zh_CN/dev-tools/testing-overview.rst +++ b/Documentation/translations/zh_CN/dev-tools/testing-overview.rst @@ -107,3 +107,28 @@ Documentation/dev-tools/kcov.rst 是能够构建在内核之中，用于在每 之后你就能确保这些错误在测试过程中都不会发生了。 一些工具与KUnit和kselftest集成，并且在检测到问题时会自动打断测试。 + +静态分析工具 +============ + +除了测试运行中的内核，我们还可以使用**静态分析**工具直接分析内核的源代 +码（**在编译时**）。内核中常用的工具允许人们检查整个源代码树或其中的特 +定文件。它们使得在开发过程中更容易发现和修复问题。 + + Sparse可以通过执行类型检查、锁检查、值范围检查来帮助测试内核，此外还 + 可以在检查代码时报告各种错误和警告。关于如何使用它的细节，请参阅 + Documentation/translations/zh_CN/dev-tools/sparse.rst。 + + Smatch扩展了Sparse，并提供了对编程逻辑错误的额外检查，如开关语句中 + 缺少断点，错误检查中未使用的返回值，忘记在错误路径的返回中设置错误代 + 码等。Smatch也有针对更严重问题的测试，如整数溢出、空指针解除引用和内 + 存泄漏。见项目页面http://smatch.sourceforge.net/。 + + Coccinelle是我们可以使用的另一个静态分析器。Coccinelle经常被用来 + 帮助源代码的重构和并行演化，但它也可以帮助避免常见代码模式中出现的某 + 些错误。可用的测试类型包括API测试、内核迭代器的正确使用测试、自由操 + 作的合理性检查、锁定行为的分析，以及已知的有助于保持内核使用一致性的 + 进一步测试。详情请见Documentation/dev-tools/coccinelle.rst。 + + 不过要注意的是，静态分析工具存在**假阳性**的问题。在试图修复错误和警 + 告之前，需要仔细评估它们。 diff --git a/Documentation/translations/zh_CN/devicetree/changesets.rst b/Documentation/translations/zh_CN/devicetree/changesets.rst new file mode 100644 index 000000000000..3df1b03c5695 --- /dev/null +++ b/Documentation/translations/zh_CN/devicetree/changesets.rst @@ -0,0 +1,37 @@ +.. SPDX-License-Identifier: GPL-2.0 +.. include:: ../disclaimer-zh_CN.rst + +:Original: Documentation/devicetree/changesets.rst + +:翻译: + + 司延腾 Yanteng Si <siyanteng@loongson.cn> + +:校译: + + +============ +设备树变更集 +============ + +设备树变更集是一种方法，它允许人们以这样一种方式在实时树中使用变化，即要么使用全部的 +变化，要么不使用。如果在使用变更集的过程中发生错误，那么树将被回滚到之前的状态。一个 +变更集也可以在使用后被删除。 + +当一个变更集被使用时，所有的改变在发出OF_RECONFIG通知器之前被一次性使用到树上。这是 +为了让接收者在收到通知时看到一个完整的、一致的树的状态。 + +一个变化集的顺序如下。 + +1. of_changeset_init() - 初始化一个变更集。 + +2. 一些DT树变化的调用，of_changeset_attach_node(), of_changeset_detach_node(), + of_changeset_add_property(), of_changeset_remove_property, + of_changeset_update_property()来准备一组变更。此时不会对活动树做任何变更。所有 + 的变更操作都记录在of_changeset的 `entries` 列表中。 + +3. of_changeset_apply() - 将变更使用到树上。要么整个变更集被使用，要么如果有错误， + 树会被恢复到之前的状态。核心通过锁确保正确的顺序。如果需要的话，可以使用一个解锁的 + __of_changeset_apply版本。 + +如果一个成功使用的变更集需要被删除，可以用of_changeset_revert()来完成。 diff --git a/Documentation/translations/zh_CN/devicetree/dynamic-resolution-notes.rst b/Documentation/translations/zh_CN/devicetree/dynamic-resolution-notes.rst new file mode 100644 index 000000000000..6dfd946d7093 --- /dev/null +++ b/Documentation/translations/zh_CN/devicetree/dynamic-resolution-notes.rst @@ -0,0 +1,31 @@ +.. SPDX-License-Identifier: GPL-2.0 +.. include:: ../disclaimer-zh_CN.rst + +:Original: Documentation/devicetree/dynamic-resolution-notes.rst + +:翻译: + + 司延腾 Yanteng Si <siyanteng@loongson.cn> + +:校译: + +======================== +Devicetree动态解析器说明 +======================== + +本文描述了内核内DeviceTree解析器的实现，它位于drivers/of/resolver.c中。 + +解析器如何工作？ +---------------- + +解析器被赋予一个任意的树作为输入，该树用适当的dtc选项编译，并有一个/plugin/标签。这就产 +生了适当的__fixups__和__local_fixups__节点。 + +解析器依次通过以下步骤工作: + +1. 从实时树中获取最大的设备树phandle值 + 1. +2. 调整树的所有本地 phandles，以解决这个量。 +3. 使用 __local__fixups__ 节点信息以相同的量调整所有本地引用。 +4. 对于__fixups__节点中的每个属性，找到它在实时树中引用的节点。这是用来标记该节点的标签。 +5. 检索fixup的目标的phandle。 +6. 对于属性中的每个fixup，找到节点:属性:偏移的位置，并用phandle值替换它。 diff --git a/Documentation/translations/zh_CN/devicetree/index.rst b/Documentation/translations/zh_CN/devicetree/index.rst new file mode 100644 index 000000000000..7451dbfdd3e5 --- /dev/null +++ b/Documentation/translations/zh_CN/devicetree/index.rst @@ -0,0 +1,45 @@ +.. SPDX-License-Identifier: GPL-2.0 +.. include:: ../disclaimer-zh_CN.rst + +:Original: Documentation/devicetree/index.rst + +:翻译: + + 司延腾 Yanteng Si <siyanteng@loongson.cn> + +:校译: + + +============================= +Open Firmware 和 Devicetree +============================= + +该文档是整个设备树文档的总目录，标题中多是业内默认的术语，初见就翻译成中文， +晦涩难懂，因此尽量保留，后面翻译其子文档时，可能会根据语境，灵活地翻译为中文。 + +内核Devicetree的使用 +======================= +.. toctree:: + :maxdepth: 1 + + usage-model + of_unittest + kernel-api + +Devicetree Overlays +=================== +.. toctree:: + :maxdepth: 1 + + changesets + dynamic-resolution-notes + overlay-notes + +Devicetree Bindings +=================== +.. toctree:: + :maxdepth: 1 + +Todolist: + +* bindings/index diff --git a/Documentation/translations/zh_CN/devicetree/kernel-api.rst b/Documentation/translations/zh_CN/devicetree/kernel-api.rst new file mode 100644 index 000000000000..2fb729368b40 --- /dev/null +++ b/Documentation/translations/zh_CN/devicetree/kernel-api.rst @@ -0,0 +1,58 @@ +.. SPDX-License-Identifier: GPL-2.0 +.. include:: ../disclaimer-zh_CN.rst + +:Original: Documentation/devicetree/kernel-api.rst + +:翻译: + + 司延腾 Yanteng Si <siyanteng@loongson.cn> + +:校译: + + +================= +内核中的设备树API +================= + +核心函数 +-------- + +该API在以下内核代码中: + +drivers/of/base.c + +include/linux/of.h + +drivers/of/property.c + +include/linux/of_graph.h + +drivers/of/address.c + +drivers/of/irq.c + +drivers/of/fdt.c + +驱动模型函数 +------------ + +该API在以下内核代码中: + +include/linux/of_device.h + +drivers/of/device.c + +include/linux/of_platform.h + +drivers/of/platform.c + +覆盖和动态DT函数 +---------------- + +该API在以下内核代码中: + +drivers/of/resolver.c + +drivers/of/dynamic.c + +drivers/of/overlay.c diff --git a/Documentation/translations/zh_CN/devicetree/of_unittest.rst b/Documentation/translations/zh_CN/devicetree/of_unittest.rst new file mode 100644 index 000000000000..11eb08ca8866 --- /dev/null +++ b/Documentation/translations/zh_CN/devicetree/of_unittest.rst @@ -0,0 +1,189 @@ +.. SPDX-License-Identifier: GPL-2.0 +.. include:: ../disclaimer-zh_CN.rst + +:Original: Documentation/devicetree/of_unittest.rst + +:翻译: + + 司延腾 Yanteng Si <siyanteng@loongson.cn> + +:校译: + +================================= +Open Firmware Devicetree 单元测试 +================================= + +作者: Gaurav Minocha <gaurav.minocha.os@gmail.com> + +1. 概述 +======= + +本文档解释了执行 OF 单元测试所需的测试数据是如何动态地附加到实时树上的，与机器的架构无关。 + +建议在继续读下去之前，先阅读以下文件。 + +(1) Documentation/devicetree/usage-model.rst +(2) http://www.devicetree.org/Device_Tree_Usage + +OF Selftest被设计用来测试提供给设备驱动开发者的接口（include/linux/of.h），以从未扁平 +化的设备树数据结构中获取设备信息等。这个接口被大多数设备驱动在各种使用情况下使用。 + + +2. 测试数据 +=========== + +设备树源文件（drivers/of/unittest-data/testcases.dts）包含执行drivers/of/unittest.c +中自动化单元测试所需的测试数据。目前，以下设备树源包含文件（.dtsi）被包含在testcases.dt中:: + + drivers/of/unittest-data/tests-interrupts.dtsi + drivers/of/unittest-data/tests-platform.dtsi + drivers/of/unittest-data/tests-phandle.dtsi + drivers/of/unittest-data/tests-match.dtsi + +当内核在启用OF_SELFTEST的情况下被构建时，那么下面的make规则:: + + $(obj)/%.dtb: $(src)/%.dts FORCE + $(call if_changed_dep, dtc) + +用于将DT源文件（testcases.dts）编译成二进制blob（testcases.dtb），也被称为扁平化的DT。 + +之后，使用以下规则将上述二进制blob包装成一个汇编文件（testcases.dtb.S）:: + + $(obj)/%.dtb.S: $(obj)/%.dtb + $(call cmd, dt_S_dtb) + +汇编文件被编译成一个对象文件（testcases.dtb.o），并被链接到内核镜像中。 + + +2.1. 添加测试数据 +----------------- + +未扁平化的设备树结构体: + +未扁平化的设备树由连接的设备节点组成，其树状结构形式如下所述:: + + // following struct members are used to construct the tree + struct device_node { + ... + struct device_node *parent; + struct device_node *child; + struct device_node *sibling; + ... + }; + +图1描述了一个机器的未扁平化设备树的通用结构，只考虑了子节点和同级指针。存在另一个指针， +``*parent`` ，用于反向遍历该树。因此，在一个特定的层次上，子节点和所有的兄弟姐妹节点将 +有一个指向共同节点的父指针（例如，child1、sibling2、sibling3、sibling4的父指针指向 +根节点）:: + + root ('/') + | + child1 -> sibling2 -> sibling3 -> sibling4 -> null + | | | | + | | | null + | | | + | | child31 -> sibling32 -> null + | | | | + | | null null + | | + | child21 -> sibling22 -> sibling23 -> null + | | | | + | null null null + | + child11 -> sibling12 -> sibling13 -> sibling14 -> null + | | | | + | | | null + | | | + null null child131 -> null + | + null + +Figure 1: 未扁平化的设备树的通用结构 + + +在执行OF单元测试之前，需要将测试数据附加到机器的设备树上（如果存在）。因此，当调用 +selftest_data_add()时，首先会读取通过以下内核符号链接到内核镜像中的扁平化设备树 +数据:: + + __dtb_testcases_begin - address marking the start of test data blob + __dtb_testcases_end - address marking the end of test data blob + +其次，它调用of_fdt_unflatten_tree()来解除扁平化的blob。最后，如果机器的设备树 +（即实时树）是存在的，那么它将未扁平化的测试数据树附加到实时树上，否则它将自己作为 +实时设备树附加。 + +attach_node_and_children()使用of_attach_node()将节点附加到实时树上，如下所 +述。为了解释这一点，图2中描述的测试数据树被附加到图1中描述的实时树上:: + + root ('/') + | + testcase-data + | + test-child0 -> test-sibling1 -> test-sibling2 -> test-sibling3 -> null + | | | | + test-child01 null null null + + +Figure 2: 将测试数据树附在实时树上的例子。 + +根据上面的方案，实时树已经存在，所以不需要附加根('/')节点。所有其他节点都是通过在 +每个节点上调用of_attach_node()来附加的。 + +在函数of_attach_node()中，新的节点被附在实时树中给定的父节点的子节点上。但是，如 +果父节点已经有了一个孩子，那么新节点就会取代当前的孩子，并将其变成其兄弟姐妹。因此， +当测试案例的数据节点被连接到上面的实时树（图1）时，最终的结构如图3所示:: + + root ('/') + | + testcase-data -> child1 -> sibling2 -> sibling3 -> sibling4 -> null + | | | | | + (...) | | | null + | | child31 -> sibling32 -> null + | | | | + | | null null + | | + | child21 -> sibling22 -> sibling23 -> null + | | | | + | null null null + | + child11 -> sibling12 -> sibling13 -> sibling14 -> null + | | | | + null null | null + | + child131 -> null + | + null + ----------------------------------------------------------------------- + + root ('/') + | + testcase-data -> child1 -> sibling2 -> sibling3 -> sibling4 -> null + | | | | | + | (...) (...) (...) null + | + test-sibling3 -> test-sibling2 -> test-sibling1 -> test-child0 -> null + | | | | + null null null test-child01 + + +Figure 3: 附加测试案例数据后的实时设备树结构。 + + +聪明的读者会注意到，与先前的结构相比，test-child0节点成为最后一个兄弟姐妹（图2）。 +在连接了第一个test-child0节点之后，又连接了test-sibling1节点，该节点推动子节点 +（即test-child0）成为兄弟姐妹，并使自己成为子节点，如上所述。 + +如果发现一个重复的节点（即如果一个具有相同full_name属性的节点已经存在于实时树中）， +那么该节点不会被附加，而是通过调用函数update_node_properties()将其属性更新到活 +树的节点中。 + + +2.2. 删除测试数据 +----------------- + +一旦测试用例执行完，selftest_data_remove被调用，以移除最初连接的设备节点（首先是 +叶子节点被分离，然后向上移动父节点被移除，最后是整个树）。selftest_data_remove() +调用detach_node_and_children()，使用of_detach_node()将节点从实时设备树上分离。 + +为了分离一个节点，of_detach_node()要么将给定节点的父节点的子节点指针更新为其同级节 +点，要么根据情况将前一个同级节点附在给定节点的同级节点上。就这样吧。 :) diff --git a/Documentation/translations/zh_CN/devicetree/overlay-notes.rst b/Documentation/translations/zh_CN/devicetree/overlay-notes.rst new file mode 100644 index 000000000000..43e3c0bc5a9f --- /dev/null +++ b/Documentation/translations/zh_CN/devicetree/overlay-notes.rst @@ -0,0 +1,140 @@ +.. SPDX-License-Identifier: GPL-2.0 +.. include:: ../disclaimer-zh_CN.rst + +:Original: Documentation/devicetree/overlay-notes.rst + +:翻译: + + 司延腾 Yanteng Si <siyanteng@loongson.cn> + +:校译: + +============== +设备树覆盖说明 +============== + +本文档描述了drivers/of/overlay.c中的内核内设备树覆盖功能的实现，是 +Documentation/devicetree/dynamic-resolution-notes.rst[1]的配套文档。 + +覆盖如何工作 +------------ + +设备树覆盖的目的是修改内核的实时树，并使修改以反映变化的方式影响内核的状态。 +由于内核主要处理的是设备，任何新的设备节点如果导致一个活动的设备，就应该创建它， +而如果设备节点被禁用或被全部删除，受影响的设备应该被取消注册。 + +让我们举个例子，我们有一个foo板，它的基本树形图如下:: + + ---- foo.dts --------------------------------------------------------------- + /* FOO平台 */ + /dts-v1/; + / { + compatible = "corp,foo"; + + /* 共享的资源 */ + res: res { + }; + + /* 芯片上的外围设备 */ + ocp: ocp { + /* 总是被实例化的外围设备 */ + peripheral1 { ... }; + }; + }; + ---- foo.dts --------------------------------------------------------------- + +覆盖bar.dts, +:: + + ---- bar.dts - 按标签覆盖目标位置 ---------------------------- + /dts-v1/; + /插件/; + &ocp { + /* bar外围 */ + bar { + compatible = "corp,bar"; + ... /* 各种属性和子节点 */ + }; + }; + ---- bar.dts --------------------------------------------------------------- + +当加载（并按照[1]中描述的方式解决）时，应该产生foo+bar.dts:: + + ---- foo+bar.dts ----------------------------------------------------------- + /* FOO平台 + bar外围 */ + / { + compatible = "corp,foo"; + + /* 共享资源 */ + res: res { + }; + + /* 芯片上的外围设备 */ + ocp: ocp { + /* 总是被实例化的外围设备 */ + peripheral1 { ... }; + + /* bar外围 */ + bar { + compatible = "corp,bar"; + ... /* 各种属性和子节点 */ + }; + }; + }; + ---- foo+bar.dts ----------------------------------------------------------- + +作为覆盖的结果，已经创建了一个新的设备节点（bar），因此将注册一个bar平台设备， +如果加载了匹配的设备驱动程序，将按预期创建设备。 + +如果基础DT不是用-@选项编译的，那么“&ocp”标签将不能用于将覆盖节点解析到基础 +DT中的适当位置。在这种情况下，可以提供目标路径。通过标签的目标位置的语法是比 +较好的，因为不管标签在DT中出现在哪里，覆盖都可以被应用到任何包含标签的基础DT上。 + +上面的bar.dts例子被修改为使用目标路径语法，即为:: + + ---- bar.dts - 通过明确的路径覆盖目标位置 -------------------- + /dts-v1/; + /插件/; + &{/ocp} { + /* bar外围 */ + bar { + compatible = "corp,bar"; + ... /* 各种外围设备和子节点 */ + } + }; + ---- bar.dts --------------------------------------------------------------- + + +内核中关于覆盖的API +------------------- + +该API相当容易使用。 + +1) 调用of_overlay_fdt_apply()来创建和应用一个覆盖的变更集。返回值是一个 + 错误或一个识别这个覆盖的cookie。 + +2) 调用of_overlay_remove()来删除和清理先前通过调用of_overlay_fdt_apply() + 而创建的覆盖变更集。不允许删除一个被另一个覆盖的覆盖变化集。 + +最后，如果你需要一次性删除所有的覆盖，只需调用of_overlay_remove_all()， +它将以正确的顺序删除每一个覆盖。 + +你可以选择注册在覆盖操作中被调用的通知器。详见 +of_overlay_notifier_register/unregister和enum of_overlay_notify_action。 + +OF_OVERLAY_PRE_APPLY、OF_OVERLAY_POST_APPLY或OF_OVERLAY_PRE_REMOVE +的通知器回调可以存储指向覆盖层中的设备树节点或其内容的指针，但这些指针不能持 +续到OF_OVERLAY_POST_REMOVE的通知器回调。在OF_OVERLAY_POST_REMOVE通 +知器被调用后，包含覆盖层的内存将被kfree()ed。请注意，即使OF_OVERLAY_POST_REMOVE +的通知器返回错误，内存也会被kfree()ed。 + +drivers/of/dynamic.c中的变更集通知器是第二种类型的通知器，可以通过应用或移除 +覆盖层来触发。这些通知器不允许在覆盖层或其内容中存储指向设备树节点的指针。当包含 +覆盖层的内存因移除覆盖层而被释放时，覆盖层代码并不能防止这类指针仍然有效。 + +任何其他保留指向覆盖层节点或数据的指针的代码都被认为是一个错误，因为在移除覆盖层 +后，该指针将指向已释放的内存。 + +覆盖层的用户必须特别注意系统上发生的整体操作，以确保其他内核代码不保留任何指向覆 +盖层节点或数据的指针。任何无意中使用这种指针的例子是，如果一个驱动或子系统模块在 +应用了覆盖后被加载，并且该驱动或子系统扫描了整个设备树或其大部分，包括覆盖节点。 diff --git a/Documentation/translations/zh_CN/devicetree/usage-model.rst b/Documentation/translations/zh_CN/devicetree/usage-model.rst new file mode 100644 index 000000000000..c6aee82c7e6e --- /dev/null +++ b/Documentation/translations/zh_CN/devicetree/usage-model.rst @@ -0,0 +1,330 @@ +.. SPDX-License-Identifier: GPL-2.0 +.. include:: ../disclaimer-zh_CN.rst + +:Original: Documentation/devicetree/usage-model.rst + +:翻译: + + 司延腾 Yanteng Si <siyanteng@loongson.cn> + +:校译: + + +=================== +Linux 和 Devicetree +=================== + +Linux对设备树数据的使用模型 + +:作者: Grant Likely <grant.likely@secretlab.ca> + +这篇文章描述了Linux如何使用设备树。关于设备树数据格式的概述可以在 +devicetree.org\ [1]_ 的设备树使用页面上找到。 + +.. [1] https://www.devicetree.org/specifications/ + +"Open Firmware Device Tree"，或简称为Devicetree（DT），是一种用于描述硬 +件的数据结构和语言。更确切地说，它是一种操作系统可读的硬件描述，这样操作系统就不 +需要对机器的细节进行硬编码。 + +从结构上看，DT是一棵树，或者说是带有命名节点的无环图，节点可以有任意数量的命名 +属性来封装任意的数据。还存在一种机制，可以在自然的树状结构之外创建从一个节点到 +另一个节点的任意链接。 + +从概念上讲，一套通用的使用惯例，称为 "bindings"（后文译为绑定），被定义为数据 +应该如何出现在树中，以描述典型的硬件特性，包括数据总线、中断线、GPIO连接和外围 +设备。 + +尽可能使用现有的绑定来描述硬件，以最大限度地利用现有的支持代码，但由于属性和节 +点名称是简单的文本字符串，通过定义新的节点和属性来扩展现有的绑定或创建新的绑定 +很容易。然而，要警惕的是，在创建一个新的绑定之前，最好先对已经存在的东西做一些 +功课。目前有两种不同的、不兼容的i2c总线的绑定，这是因为在创建新的绑定时没有事先 +调查i2c设备在现有系统中是如何被枚举的。 + +1. 历史 +------- +DT最初是由Open Firmware创建的，作为将数据从Open Firmware传递给客户程序 +（如传递给操作系统）的通信方法的一部分。操作系统使用设备树在运行时探测硬件的拓 +扑结构，从而在没有硬编码信息的情况下支持大多数可用的硬件（假设所有设备的驱动程 +序都可用）。 + +由于Open Firmware通常在PowerPC和SPARC平台上使用，长期以来，对这些架构的 +Linux支持一直使用设备树。 + +2005年，当PowerPC Linux开始大规模清理并合并32位和64位支持时，决定在所有 +Powerpc平台上要求DT支持，无论它们是否使用Open Firmware。为了做到这一点， +我们创建了一个叫做扁平化设备树（FDT）的DT表示法，它可以作为一个二进制的blob +传递给内核，而不需要真正的Open Firmware实现。U-Boot、kexec和其他引导程序 +被修改，以支持传递设备树二进制（dtb）和在引导时修改dtb。DT也被添加到PowerPC +引导包装器（arch/powerpc/boot/\*）中，这样dtb就可以被包裹在内核镜像中，以 +支持引导现有的非DT察觉的固件。 + +一段时间后，FDT基础架构被普及到了所有的架构中。在写这篇文章的时候，6个主线架 +构（arm、microblaze、mips、powerpc、sparc和x86）和1个非主线架构（ios） +有某种程度的DT支持。 + +1. 数据模型 +----------- +如果你还没有读过设备树用法\ [1]_页，那么现在就去读吧。没关系，我等着.... + +2.1 高层次视角 +-------------- +最重要的是要明白，DT只是一个描述硬件的数据结构。它没有什么神奇之处，也不会神 +奇地让所有的硬件配置问题消失。它所做的是提供一种语言，将硬件配置与Linux内核 +（或任何其他操作系统）中的板卡和设备驱动支持解耦。使用它可以使板卡和设备支持 +变成数据驱动；根据传递到内核的数据做出设置决定，而不是根据每台机器的硬编码选 +择。 + +理想情况下，数据驱动的平台设置应该导致更少的代码重复，并使其更容易用一个内核 +镜像支持各种硬件。 + +Linux使用DT数据有三个主要目的: + +1) 平台识别。 +2) 运行时配置，以及 +3) 设备数量。 + +2.2 平台识别 +------------ +首先，内核将使用DT中的数据来识别特定的机器。在一个理想的世界里，具体的平台对 +内核来说并不重要，因为所有的平台细节都会被设备树以一致和可靠的方式完美描述。 +但是，硬件并不完美，所以内核必须在早期启动时识别机器，以便有机会运行特定于机 +器的修复程序。 + +在大多数情况下，机器的身份是不相关的，而内核将根据机器的核心CPU或SoC来选择 +设置代码。例如，在ARM上，arch/arm/kernel/setup.c中的setup_arch()将调 +用arch/arm/kernel/devtree.c中的setup_machine_fdt()，它通过 +machine_desc表搜索并选择与设备树数据最匹配的machine_desc。它通过查看根 +设备树节点中的'compatible'属性，并将其与struct machine_desc中的 +dt_compat列表（如果你好奇，该列表定义在arch/arm/include/asm/mach/arch.h +中）进行比较，从而确定最佳匹配。 + +“compatible” 属性包含一个排序的字符串列表，以机器的确切名称开始，后面是 +一个可选的与之兼容的板子列表，从最兼容到最不兼容排序。例如，TI BeagleBoard +和它的后继者BeagleBoard xM板的根兼容属性可能看起来分别为:: + + compatible = "ti,omap3-beagleboard", "ti,omap3450", "ti,omap3"; + compatible = "ti,omap3-beagleboard-xm", "ti,omap3450", "ti,omap3"; + +其中 "ti,map3-beagleboard-xm "指定了确切的型号，它还声称它与OMAP 3450 SoC +以及一般的OMP3系列SoC兼容。你会注意到，该列表从最具体的（确切的板子）到最 +不具体的（SoC系列）进行排序。 + +聪明的读者可能会指出，Beagle xM也可以声称与原Beagle板兼容。然而，我们应 +该当心在板级上这样做，因为通常情况下，即使在同一产品系列中，每块板都有很高 +的变化，而且当一块板声称与另一块板兼容时，很难确定到底是什么意思。对于高层 +来说，最好是谨慎行事，不要声称一块板子与另一块板子兼容。值得注意的例外是， +当一块板子是另一块板子的载体时，例如CPU模块连接到一个载体板上。 + +关于兼容值还有一个注意事项。在兼容属性中使用的任何字符串都必须有文件说明它 +表示什么。在Documentation/devicetree/bindings中添加兼容字符串的文档。 + +同样在ARM上，对于每个machine_desc，内核会查看是否有任何dt_compat列表条 +目出现在兼容属性中。如果有，那么该machine_desc就是驱动该机器的候选者。在搜索 +了整个machine_descs表之后，setup_machine_fdt()根据每个machine_desc +在兼容属性中匹配的条目，返回 “最兼容” 的machine_desc。如果没有找到匹配 +的machine_desc，那么它将返回NULL。 + +这个方案背后的原因是观察到，在大多数情况下，如果它们都使用相同的SoC或相同 +系列的SoC，一个machine_desc可以支持大量的电路板。然而，不可避免地会有一些例 +外情况，即特定的板子需要特殊的设置代码，这在一般情况下是没有用的。特殊情况 +可以通过在通用设置代码中明确检查有问题的板子来处理，但如果超过几个情况下， +这样做很快就会变得很难看和/或无法维护。 + +相反，兼容列表允许通用machine_desc通过在dt_compat列表中指定“不太兼容”的值 +来提供对广泛的通用板的支持。在上面的例子中，通用板支持可以声称与“ti,ompa3” +或“ti,ompa3450”兼容。如果在最初的beagleboard上发现了一个bug，需要在 +早期启动时使用特殊的变通代码，那么可以添加一个新的machine_desc，实现变通， +并且只在“ti,omap3-beagleboard”上匹配。 + +PowerPC使用了一个稍微不同的方案，它从每个machine_desc中调用.probe()钩子， +并使用第一个返回TRUE的钩子。然而，这种方法没有考虑到兼容列表的优先级，对于 +新的架构支持可能应该避免。 + +2.3 运行时配置 +-------------- +在大多数情况下，DT是将数据从固件传递给内核的唯一方法，所以也被用来传递运行 +时和配置数据，如内核参数字符串和initrd镜像的位置。 + +这些数据大部分都包含在/chosen节点中，当启动Linux时，它看起来就像这样:: + + chosen { + bootargs = "console=ttyS0,115200 loglevel=8"; + initrd-start = <0xc8000000>; + initrd-end = <0xc8200000>; + }; + +bootargs属性包含内核参数，initrd-\*属性定义initrd blob的地址和大小。注 +意initrd-end是initrd映像后的第一个地址，所以这与结构体资源的通常语义不一 +致。选择的节点也可以选择包含任意数量的额外属性，用于平台特定的配置数据。 + +在早期启动过程中，架构设置代码通过不同的辅助回调函数多次调用 +of_scan_flat_dt()来解析设备树数据，然后进行分页设置。of_scan_flat_dt() +代码扫描设备树，并使用辅助函数来提取早期启动期间所需的信息。通常情况下， +early_init_dt_scan_chosen()辅助函数用于解析所选节点，包括内核参数， +early_init_dt_scan_root()用于初始化DT地址空间模型，early_init_dt_scan_memory() +用于确定可用RAM的大小和位置。 + +在ARM上，函数setup_machine_fdt()负责在选择支持板子的正确machine_desc +后，对设备树进行早期扫描。 + +2.4 设备数量 +------------ +在电路板被识别后，在早期配置数据被解析后，内核初始化可以以正常方式进行。在 +这个过程中的某个时刻，unflatten_device_tree()被调用以将数据转换成更有 +效的运行时表示。这也是调用机器特定设置钩子的时候，比如ARM上的machine_desc +.init_early()、.init_irq()和.init_machine()钩子。本节的其余部分使用 +了ARM实现的例子，但所有架构在使用DT时都会做几乎相同的事情。 + +从名称上可以猜到，.init_early()用于在启动过程早期需要执行的任何机器特定设 +置，而.init_irq()则用于设置中断处理。使用DT并不会实质性地改变这两个函数的 +行为。如果提供了DT，那么.init_early()和.init_irq()都能调用任何一个DT查 +询函数（of_* in include/linux/of*.h），以获得关于平台的额外数据。 + +DT上下文中最有趣的钩子是.init_machine()，它主要负责将平台的数据填充到 +Linux设备模型中。历史上，这在嵌入式平台上是通过在板卡support .c文件中定 +义一组静态时钟结构、platform_devices和其他数据，并在.init_machine()中 +大量注册来实现的。当使用DT时，就不用为每个平台的静态设备进行硬编码，可以通过 +解析DT获得设备列表，并动态分配设备结构体。 + +最简单的情况是，.init_machine()只负责注册一个platform_devices。 +platform_device是Linux使用的一个概念，用于不能被硬件检测到的内存或I/O映 +射的设备，以及“复合”或 “虚拟”设备（后面会详细介绍）。虽然DT没有“平台设备”的 +术语，但平台设备大致对应于树根的设备节点和简单内存映射总线节点的子节点。 + +现在是举例说明的好时机。下面是NVIDIA Tegra板的设备树的一部分:: + + /{ + compatible = "nvidia,harmony", "nvidia,tegra20"; + #address-cells = <1>; + #size-cells = <1>; + interrupt-parent = <&intc>; + + chosen { }; + aliases { }; + + memory { + device_type = "memory"; + reg = <0x00000000 0x40000000>; + }; + + soc { + compatible = "nvidia,tegra20-soc", "simple-bus"; + #address-cells = <1>; + #size-cells = <1>; + ranges; + + intc: interrupt-controller@50041000 { + compatible = "nvidia,tegra20-gic"; + interrupt-controller; + #interrupt-cells = <1>; + reg = <0x50041000 0x1000>, < 0x50040100 0x0100 >; + }; + + serial@70006300 { + compatible = "nvidia,tegra20-uart"; + reg = <0x70006300 0x100>; + interrupts = <122>; + }; + + i2s1: i2s@70002800 { + compatible = "nvidia,tegra20-i2s"; + reg = <0x70002800 0x100>; + interrupts = <77>; + codec = <&wm8903>; + }; + + i2c@7000c000 { + compatible = "nvidia,tegra20-i2c"; + #address-cells = <1>; + #size-cells = <0>; + reg = <0x7000c000 0x100>; + interrupts = <70>; + + wm8903: codec@1a { + compatible = "wlf,wm8903"; + reg = <0x1a>; + interrupts = <347>; + }; + }; + }; + + sound { + compatible = "nvidia,harmony-sound"; + i2s-controller = <&i2s1>; + i2s-codec = <&wm8903>; + }; + }; + +在.init_machine()时，Tegra板支持代码将需要查看这个DT，并决定为哪些节点 +创建platform_devices。然而，看一下这个树，并不能立即看出每个节点代表什么 +类型的设备，甚至不能看出一个节点是否代表一个设备。/chosen、/aliases和 +/memory节点是信息节点，并不描述设备（尽管可以说内存可以被认为是一个设备）。 +/soc节点的子节点是内存映射的设备，但是codec@1a是一个i2c设备，而sound节 +点代表的不是一个设备，而是其他设备是如何连接在一起以创建音频子系统的。我知 +道每个设备是什么，因为我熟悉电路板的设计，但是内核怎么知道每个节点该怎么做？ + +诀窍在于，内核从树的根部开始，寻找具有“兼容”属性的节点。首先，一般认为任何 +具有“兼容”属性的节点都代表某种设备；其次，可以认为树根的任何节点要么直接连 +接到处理器总线上，要么是无法用其他方式描述的杂项系统设备。对于这些节点中的 +每一个，Linux都会分配和注册一个platform_device，它又可能被绑定到一个 +platform_driver。 + +为什么为这些节点使用platform_device是一个安全的假设？嗯，就Linux对设备 +的建模方式而言，几乎所有的总线类型都假定其设备是总线控制器的孩子。例如，每 +个i2c_client是i2c_master的一个子节点。每个spi_device都是SPI总线的一 +个子节点。类似的还有USB、PCI、MDIO等。同样的层次结构也出现在DT中，I2C设 +备节点只作为I2C总线节点的子节点出现。同理，SPI、MDIO、USB等等。唯一不需 +要特定类型的父设备的设备是platform_devices（和amba_devices，但后面会 +详细介绍），它们将愉快地运行在Linux/sys/devices树的底部。因此，如果一个 +DT节点位于树的根部，那么它真的可能最好注册为platform_device。 + +Linux板支持代码调用of_platform_populate(NULL, NULL, NULL, NULL)来 +启动树根的设备发现。参数都是NULL，因为当从树的根部开始时，不需要提供一个起 +始节点（第一个NULL），一个父结构设备（最后一个NULL），而且我们没有使用匹配 +表（尚未）。对于只需要注册设备的板子，除了of_platform_populate()的调用， +.init_machine()可以完全为空。 + +在Tegra的例子中，这说明了/soc和/sound节点，但是SoC节点的子节点呢？它们 +不应该也被注册为平台设备吗？对于Linux DT支持，一般的行为是子设备在驱动 +.probe()时被父设备驱动注册。因此，一个i2c总线设备驱动程序将为每个子节点 +注册一个i2c_client，一个SPI总线驱动程序将注册其spi_device子节点，其他 +总线类型也是如此。根据该模型，可以编写一个与SoC节点绑定的驱动程序，并简单 +地为其每个子节点注册platform_device。板卡支持代码将分配和注册一个SoC设 +备，一个（理论上的）SoC设备驱动程序可以绑定到SoC设备，并在其.probe()钩 +中为/soc/interruptcontroller、/soc/serial、/soc/i2s和/soc/i2c注 +册platform_devices。很简单，对吗？ + +实际上，事实证明，将一些platform_device的子设备注册为更多的platform_device +是一种常见的模式，设备树支持代码反映了这一点，并使上述例子更简单。 +of_platform_populate()的第二个参数是一个of_device_id表，任何与该表 +中的条目相匹配的节点也将获得其子节点的注册。在Tegra的例子中，代码可以是 +这样的:: + + static void __init harmony_init_machine(void) + { + /* ... */ + of_platform_populate(NULL, of_default_bus_match_table, NULL, NULL); + } + +“simple-bus”在Devicetree规范中被定义为一个属性，意味着一个简单的内存映射 +的总线，所以of_platform_populate()代码可以被写成只是假设简单总线兼容的节 +点将总是被遍历。然而，我们把它作为一个参数传入，以便电路板支持代码可以随时覆 +盖默认行为。 + +[需要添加关于添加i2c/spi/etc子设备的讨论] 。 + +附录A：AMBA设备 +--------------- + +ARM Primecell是连接到ARM AMBA总线的某种设备，它包括对硬件检测和电源管理 +的一些支持。在Linux中，amba_device和amba_bus_type结构体被用来表示 +Primecell设备。然而，棘手的一点是，AMBA总线上的所有设备并非都是Primecell， +而且对于Linux来说，典型的情况是amba_device和platform_device实例都是同 +一总线段的同义词。 + +当使用DT时，这给of_platform_populate()带来了问题，因为它必须决定是否将 +每个节点注册为platform_device或amba_device。不幸的是，这使设备创建模型 +变得有点复杂，但解决方案原来并不是太具有侵略性。如果一个节点与“arm,amba-primecell” +兼容，那么of_platform_populate()将把它注册为amba_device而不是 +platform_device。 diff --git a/Documentation/translations/zh_CN/doc-guide/kernel-doc.rst b/Documentation/translations/zh_CN/doc-guide/kernel-doc.rst index 82ec84470c0b..ccfb9b8329c2 100644 --- a/Documentation/translations/zh_CN/doc-guide/kernel-doc.rst +++ b/Documentation/translations/zh_CN/doc-guide/kernel-doc.rst @@ -14,7 +14,7 @@ Linux内核源文件可以包含kernel-doc格式的结构化文档注释，用 实际有着明显的不同。内核源包含成千上万个kernel-doc注释。请坚持遵循 此处描述的风格。 -.. note:: kernel-doc无法包含Rust代码：请参考 Documentation/rust/docs.rst 。 +.. note:: kernel-doc无法包含Rust代码：请参考 Documentation/rust/general-information.rst 。 从注释中提取kernel-doc结构，并从中生成适当的 `Sphinx C 域`_ 函数和带有锚点的 类型描述。这些注释将被过滤以生成特殊kernel-doc高亮和交叉引用。详见下文。 diff --git a/Documentation/translations/zh_CN/driver-api/gpio/index.rst b/Documentation/translations/zh_CN/driver-api/gpio/index.rst new file mode 100644 index 000000000000..9ab64e94aced --- /dev/null +++ b/Documentation/translations/zh_CN/driver-api/gpio/index.rst @@ -0,0 +1,69 @@ +.. SPDX-License-Identifier: GPL-2.0 + +.. include:: ../../disclaimer-zh_CN.rst + +:Original: Documentation/driver-api/gpio/index.rst + +:翻译: + + 司延腾 Yanteng Si <siyanteng@loongson.cn> + +:校译: + +======================= +通用型输入/输出（GPIO） +======================= + +目录: + +.. toctree:: + :maxdepth: 2 + + legacy + +Todolist: + +* intro +* using-gpio +* driver +* consumer +* board +* drivers-on-gpio +* bt8xxgpio + +核心 +==== + +该API在以下内核代码中: + +include/linux/gpio/driver.h + +drivers/gpio/gpiolib.c + +ACPI支持 +======== + +该API在以下内核代码中: + +drivers/gpio/gpiolib-acpi.c + +设备树支持 +========== + +该API在以下内核代码中: + +drivers/gpio/gpiolib-of.c + +设备管理支持 +============ + +该API在以下内核代码中: + +drivers/gpio/gpiolib-devres.c + +sysfs帮助（函数） +================= + +该API在以下内核代码中: + +drivers/gpio/gpiolib-sysfs.c diff --git a/Documentation/translations/zh_CN/gpio.txt b/Documentation/translations/zh_CN/driver-api/gpio/legacy.rst index a23ee14fc927..6399521d0548 100644 --- a/Documentation/translations/zh_CN/gpio.txt +++ b/Documentation/translations/zh_CN/driver-api/gpio/legacy.rst @@ -1,39 +1,28 @@ -Chinese translated version of Documentation/admin-guide/gpio +.. SPDX-License-Identifier: GPL-2.0 -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. +.. include:: ../../disclaimer-zh_CN.rst -Maintainer: Grant Likely <grant.likely@secretlab.ca> - Linus Walleij <linus.walleij@linaro.org> -Chinese maintainer: Fu Wei <tekkamanninja@gmail.com> ---------------------------------------------------------------------- -Documentation/admin-guide/gpio 的中文翻译 +:Original: Documentation/driver-api/gpio/legacy.rst -如果想评论或更新本文的内容，请直接联系原文档的维护者。如果你使用英文 -交流有困难的话，也可以向中文版维护者求助。如果本翻译更新不及时或者翻 -译存在问题，请联系中文版维护者。 -英文版维护者： 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> +:翻译: + 傅炜 Fu Wei <tekkamanninja@gmail.com> + 司延腾 Yanteng Si <siyanteng@loongson.cn> -以下为正文 ---------------------------------------------------------------------- -GPIO 接口 +:校译: -本文档提供了一个在Linux下访问GPIO的公约概述。 + +传统GPIO接口 +============ + +本文档概述了Linux下的GPIO访问公约。 这些函数以 gpio_* 作为前缀。其他的函数不允许使用这样的前缀或相关的 __gpio_* 前缀。 -什么是GPIO? -========== +什么是GPIO？ +============ "通用输入/输出口"(GPIO)是一个灵活的由软件控制的数字信号。他们可 由多种芯片提供,且对于从事嵌入式和定制硬件的 Linux 开发者来说是 比较熟悉。每个GPIO 都代表一个连接到特定引脚或球栅阵列(BGA)封装中 @@ -99,6 +88,7 @@ GPIO 公约 标识 GPIO --------- + GPIO 是通过无符号整型来标识的,范围是 0 到 MAX_INT。保留“负”数 用于其他目的,例如标识信号“在这个板子上不可用”或指示错误。未接触底层 硬件的代码会忽略这些整数。 @@ -115,7 +105,7 @@ FPGA 的特定板子上使用 80-95。编号不一定要连续,那些平台中 如果你要初始化一个带有无效 GPIO 编号的结构体,可以使用一些负编码 (如"-EINVAL")，那将使其永远不会是有效。来测试这样一个结构体中的编号 -是否关联一个 GPIO，你可使用以下断言: +是否关联一个 GPIO，你可使用以下断言:: int gpio_is_valid(int number); @@ -128,11 +118,12 @@ FPGA 的特定板子上使用 80-95。编号不一定要连续,那些平台中 使用 GPIO --------- + 对于一个 GPIO，系统应该做的第一件事情就是通过 gpio_request() 函数分配它，见下文。 接下来是设置I/O方向，这通常是在板级启动代码中为所使用的 GPIO 设置 -platform_device 时完成。 +platform_device 时完成:: /* 设置为输入或输出, 返回 0 或负的错误代码 */ int gpio_direction_input(unsigned gpio); @@ -157,12 +148,13 @@ get/set(获取/设置)函数调用没法返回错误,且有可能是配置错误 访问自旋锁安全的 GPIO -------------------- +--------------------- + 大多数 GPIO 控制器可以通过内存读/写指令来访问。这些指令不会休眠,可以 安全地在硬(非线程)中断例程和类似的上下文中完成。 对于那些用 gpio_cansleep()测试总是返回失败的 GPIO(见下文)，使用 -以下的函数访问: +以下的函数访问:: /* GPIO 输入:返回零或非零 */ int gpio_get_value(unsigned gpio); @@ -188,17 +180,18 @@ GPIO值是布尔值，零表示低电平，非零表示高电平。当读取一 访问可能休眠的 GPIO ------------------ +------------------- + 某些 GPIO 控制器必须通过基于总线(如 I2C 或 SPI)的消息访问。读或写这些 GPIO 值的命令需要等待其信息排到队首才发送命令，再获得其反馈。期间需要 休眠，这不能在 IRQ 例程(中断上下文)中执行。 支持此类 GPIO 的平台通过以下函数返回非零值来区分出这种 GPIO。(此函数需要 -一个之前通过 gpio_request 分配到的有效 GPIO 编号): +一个之前通过 gpio_request 分配到的有效 GPIO 编号):: int gpio_cansleep(unsigned gpio); -为了访问这种 GPIO,内核定义了一套不同的函数: +为了访问这种 GPIO,内核定义了一套不同的函数:: /* GPIO 输入:返回零或非零 ,可能会休眠 */ int gpio_get_value_cansleep(unsigned gpio); @@ -214,25 +207,26 @@ GPIO 值的命令需要等待其信息排到队首才发送命令，再获得其 事实，这些处理例程实际上和自旋锁安全的函数是一样的。 ** 除此之外 ** 调用设置和配置此类 GPIO 的函数也必须在允许休眠的上下文中， -因为它们可能也需要访问 GPIO 控制器芯片: (这些设置函数通常在板级启动代码或者 -驱动探测/断开代码中，所以这是一个容易满足的约束条件。) +因为它们可能也需要访问 GPIO 控制器芯片 (这些设置函数通常在板级启动代码或者 +驱动探测/断开代码中，所以这是一个容易满足的约束条件。) :: - gpio_direction_input() - gpio_direction_output() - gpio_request() + gpio_direction_input() + gpio_direction_output() + gpio_request() -## gpio_request_one() -## gpio_request_array() -## gpio_free_array() + ## gpio_request_one() + ## gpio_request_array() + ## gpio_free_array() - gpio_free() - gpio_set_debounce() + gpio_free() + gpio_set_debounce() 声明和释放 GPIO ----------------------------- -为了有助于捕获系统配置错误,定义了两个函数。 +---------------- + +为了有助于捕获系统配置错误,定义了两个函数:: /* 申请 GPIO, 返回 0 或负的错误代码. * 非空标签可能有助于诊断. @@ -256,9 +250,9 @@ GPIO 值的命令需要等待其信息排到队首才发送命令，再获得其 某些平台可能也使用 GPIO 作为电源管理激活信号(例如通过关闭未使用芯片区和 简单地关闭未使用时钟)。 -对于 GPIO 使用 pinctrl 子系统已知的引脚，子系统应该被告知其使用情况； +对于 GPIO 使用引脚控制子系统已知的引脚，子系统应该被告知其使用情况； 一个 gpiolib 驱动的 .request()操作应调用 pinctrl_gpio_request()， -而 gpiolib 驱动的 .free()操作应调用 pinctrl_gpio_free()。pinctrl +而 gpiolib 驱动的 .free()操作应调用 pinctrl_gpio_free()。引脚控制 子系统允许 pinctrl_gpio_request()在某个引脚或引脚组以复用形式“属于” 一个设备时都成功返回。 @@ -270,7 +264,7 @@ GPIO 值的命令需要等待其信息排到队首才发送命令，再获得其 某些平台允许部分或所有 GPIO 信号使用不同的引脚。类似的，GPIO 或引脚的 其他方面也需要配置，如上拉/下拉。平台软件应该在对这些 GPIO 调用 -gpio_request()前将这类细节配置好，例如使用 pinctrl 子系统的映射表， +gpio_request()前将这类细节配置好，例如使用引脚控制子系统的映射表， 使得 GPIO 的用户无须关注这些细节。 还有一个值得注意的是在释放 GPIO 前，你必须停止使用它。 @@ -278,7 +272,7 @@ gpio_request()前将这类细节配置好，例如使用 pinctrl 子系统的映 注意:申请一个 GPIO 并没有以任何方式配置它，只不过标识那个 GPIO 处于使用 状态。必须有另外的代码来处理引脚配置(如控制 GPIO 使用的引脚、上拉/下拉)。 -考虑到大多数情况下声明 GPIO 之后就会立即配置它们,所以定义了以下三个辅助函数: +考虑到大多数情况下声明 GPIO 之后就会立即配置它们,所以定义了以下三个辅助函数:: /* 申请一个 GPIO 信号, 同时通过特定的'flags'初始化配置, * 其他和 gpio_request()的参数和返回值相同 @@ -326,7 +320,7 @@ gpio_request()前将这类细节配置好，例如使用 pinctrl 子系统的映 将来这些标志可能扩展到支持更多的属性。 更进一步,为了更简单地声明/释放多个 GPIO,'struct gpio'被引进来封装所有 -这三个领域: +这三个领域:: struct gpio { unsigned gpio; @@ -334,7 +328,7 @@ gpio_request()前将这类细节配置好，例如使用 pinctrl 子系统的映 const char *label; }; -一个典型的用例: +一个典型的用例:: static struct gpio leds_gpios[] = { { 32, GPIOF_OUT_INIT_HIGH, "Power LED" }, /* 默认开启 */ @@ -356,9 +350,10 @@ gpio_request()前将这类细节配置好，例如使用 pinctrl 子系统的映 GPIO 映射到 IRQ --------------------- +---------------- + GPIO 编号是无符号整数;IRQ 编号也是。这些构成了两个逻辑上不同的命名空间 -(GPIO 0 不一定使用 IRQ 0)。你可以通过以下函数在它们之间实现映射: +(GPIO 0 不一定使用 IRQ 0)。你可以通过以下函数在它们之间实现映射:: /* 映射 GPIO 编号到 IRQ 编号 */ int gpio_to_irq(unsigned gpio); @@ -384,7 +379,8 @@ irq_to_gpio()返回的非错误值大多数通常可以被 gpio_get_value()所 模拟开漏信号 ----------------------------- +------------ + 有时在只有低电平信号作为实际驱动结果(译者注:多个输出连接于一点，逻辑电平 结果为所有输出的逻辑与)的时候,共享的信号线需要使用“开漏”信号。(该术语 适用于 CMOS 管；而 TTL 用“集电极开路”。)一个上拉电阻使信号为高电平。这 @@ -408,9 +404,44 @@ irq_to_gpio()返回的非错误值大多数通常可以被 gpio_get_value()所 这不一定是错误的。一个常见的例子就是 I2C 时钟的延长：一个需要较慢时钟的 从设备延迟 SCK 的上升沿，而 I2C 主设备相应地调整其信号传输速率。 +GPIO控制器和引脚控制子系统 +-------------------------- + +SOC上的GPIO控制器可能与引脚控制子系统紧密结合，即引脚可以与可选的gpio功 +能一起被其他功能使用。我们已经涵盖了这样的情况，例如一个GPIO控制器需要保 +留一个引脚或通过调用以下任何一个引脚来设置其方向:: + + pinctrl_gpio_request() + pinctrl_gpio_free() + pinctrl_gpio_direction_input() + pinctrl_gpio_direction_output() + +但是，引脚控制子系统是如何将GPIO号码（这是一个全局事项）与某个引脚控制器 +上的某个引脚交叉关联的？ + +这是通过注册引脚的“范围”来实现的，这基本上是交叉参考表。这些描述是在 +Documentation/driver-api/pin-control.rst + +虽然引脚分配完全由引脚控制子系统管理，但gpio（在gpiolib下）仍由gpio驱动 +维护。可能发生的情况是，SoC中的不同引脚范围由不同的gpio驱动器管理。 + +这使得在调用 "pinctrl_gpio_request" 之前，让gpio驱动向pin ctrl子系 +统宣布它们的引脚范围是合理的，以便在使用任何gpio之前要求引脚控制子系统准 +备相应的引脚。 + +为此，gpio控制器可以用引脚控制子系统注册其引脚范围。目前有两种方法：有或 +无DT。 + +关于对DT的支持，请参考 Documentation/devicetree/bindings/gpio/gpio.txt. + +对于非DT支持，用户可以用适当的参数调用gpiochip_add_pin_range()，将一 +系列的gpio引脚注册到引脚控制驱动上。为此，必须将引脚控制设备的名称字符串 +作为参数之一传给这个程序。 + + +这些公约忽略了什么？ +==================== -这些公约忽略了什么? -================ 这些公约忽略的最大一件事就是引脚复用，因为这属于高度芯片特定的属性且 没有可移植性。某个平台可能不需要明确的复用信息；有的对于任意给定的引脚 可能只有两个功能选项；有的可能每个引脚有八个功能选项；有的可能可以将 @@ -433,8 +464,9 @@ Linux 的系统。) 当前，动态定义 GPIO 并不是标准的，例如作为配置一个带有某些 GPIO 扩展器的 附加电路板的副作用。 -GPIO 实现者的框架 (可选) -===================== +GPIO 实现者的框架（可选） +========================= + 前面提到了，有一个可选的实现框架，让平台使用相同的编程接口，更加简单地支持 不同种类的 GPIO 控制器。这个框架称为"gpiolib"。 @@ -444,15 +476,16 @@ GPIO 实现者的框架 (可选) 控制器驱动: gpio_chip -------------------- +--------------------- + 在框架中每个 GPIO 控制器都包装为一个 "struct gpio_chip"，他包含了 该类型的每个控制器的常用信息: - - 设置 GPIO 方向的方法 - - 用于访问 GPIO 值的方法 - - 告知调用其方法是否可能休眠的标志 - - 可选的 debugfs 信息导出方法 (显示类似上拉配置一样的额外状态) - - 诊断标签 + - 设置 GPIO 方向的方法 + - 用于访问 GPIO 值的方法 + - 告知调用其方法是否可能休眠的标志 + - 可选的 debugfs 信息导出方法 (显示类似上拉配置一样的额外状态) + - 诊断标签 也包含了来自 device.platform_data 的每个实例的数据：它第一个 GPIO 的 编号和它可用的 GPIO 的数量。 @@ -471,7 +504,8 @@ GPIO 实现者的框架 (可选) 平台支持 -------- +-------- + 为了支持这个框架，一个平台的 Kconfig 文件将会 "select"(选择) ARCH_REQUIRE_GPIOLIB 或 ARCH_WANT_OPTIONAL_GPIOLIB，并让它的 <asm/gpio.h> 包含 <asm-generic/gpio.h>，同时定义三个方法: @@ -489,7 +523,7 @@ ARCH_WANT_OPTIONAL_GPIOLIB 意味着 gpiolib 核心默认关闭,且用户可以 如果这些选项都没被选择,该平台就不通过 GPIO-lib 支持 GPIO,且代码不可以 被用户使能。 -以下这些方法的实现可以直接使用框架代码,并总是通过 gpio_chip 调度: +以下这些方法的实现可以直接使用框架代码,并总是通过 gpio_chip 调度:: #define gpio_get_value __gpio_get_value #define gpio_set_value __gpio_set_value @@ -508,7 +542,8 @@ arch_initcall()或者更早的地方集成进平台初始化代码，使这些 G 且他们通常可以作为 IRQ 使用。 板级支持 -------- +-------- + 对于外部 GPIO 控制器(例如 I2C 或 SPI 扩展器、专用芯片、多功能器件、FPGA 或 CPLD)，大多数常用板级特定代码都可以注册控制器设备，并保证他们的驱动知道 gpiochip_add()所使用的 GPIO 编号。他们的起始编号通常跟在平台特定的 GPIO @@ -526,8 +561,9 @@ GPIO 可以工作之后才可被注册。解决这类依赖的的一种方法是 设备变成无效时移除它们。 -用户空间的 Sysfs 接口(可选) -======================== +用户空间的 Sysfs 接口（可选） +============================= + 使用“gpiolib”实现框架的平台可以选择配置一个 GPIO 的 sysfs 用户接口。 这不同于 debugfs 接口，因为它提供的是对 GPIO方向和值的控制，而不只显示 一个GPIO 的状态摘要。此外,它可以出现在没有调试支持的产品级系统中。 @@ -548,6 +584,7 @@ GPIO 可以工作之后才可被注册。解决这类依赖的的一种方法是 Sysfs 中的路径 -------------- + 在/sys/class/gpio 中有 3 类入口: - 用于在用户空间控制 GPIO 的控制接口; @@ -625,8 +662,9 @@ GPIO 控制器的路径类似 /sys/class/gpio/gpiochip42/ (对于从#42 GPIO 从内核代码中导出 -------------- -内核代码可以明确地管理那些已通过 gpio_request()申请的 GPIO 的导出: +---------------- + +内核代码可以明确地管理那些已通过 gpio_request()申请的 GPIO 的导出:: /* 导出 GPIO 到用户空间 */ int gpio_export(unsigned gpio, bool direction_may_change); @@ -648,3 +686,9 @@ GPIO 控制器的路径类似 /sys/class/gpio/gpiochip42/ (对于从#42 GPIO 在 GPIO 被导出之后，gpio_export_link()允许在 sysfs 文件系统的任何地方 创建一个到这个 GPIO sysfs 节点的符号链接。这样驱动就可以通过一个描述性的 名字，在 sysfs 中他们所拥有的设备下提供一个(到这个 GPIO sysfs 节点的)接口。 + + +API参考 +======= + +本节中列出的函数已被废弃。在新的代码中应该使用基于GPIO描述符的API。 diff --git a/Documentation/translations/zh_CN/driver-api/index.rst b/Documentation/translations/zh_CN/driver-api/index.rst new file mode 100644 index 000000000000..ba354e1f4e6d --- /dev/null +++ b/Documentation/translations/zh_CN/driver-api/index.rst @@ -0,0 +1,132 @@ +.. SPDX-License-Identifier: GPL-2.0 + +.. include:: ../disclaimer-zh_CN.rst + +:Original: Documentation/driver-api/index.rst + +:翻译: + + 司延腾 Yanteng Si <siyanteng@loongson.cn> + +:校译: + +======================== +Linux驱动实现者的API指南 +======================== + +内核提供了各种各样的接口来支持设备驱动的开发。这份文档只是对其中一些接口进行了 +一定程度的整理——希望随着时间的推移，它能变得更好！可用的小节可以在下面看到。 + +.. class:: toc-title + + 目录列表： + +.. toctree:: + :maxdepth: 2 + + gpio/index + io_ordering + +Todolist: + +* driver-model/index +* basics +* infrastructure +* ioctl +* early-userspace/index +* pm/index +* clk +* device-io +* dma-buf +* device_link +* component +* message-based +* infiniband +* aperture +* frame-buffer +* regulator +* reset +* iio/index +* input +* usb/index +* firewire +* pci/index +* cxl/index +* spi +* i2c +* ipmb +* ipmi +* i3c/index +* interconnect +* devfreq +* hsi +* edac +* scsi +* libata +* target +* mailbox +* mtdnand +* miscellaneous +* mei/index +* mtd/index +* mmc/index +* nvdimm/index +* w1 +* rapidio/index +* s390-drivers +* vme +* 80211/index +* uio-howto +* firmware/index +* pin-control +* md/index +* media/index +* misc_devices +* nfc/index +* dmaengine/index +* slimbus +* soundwire/index +* thermal/index +* fpga/index +* acpi/index +* auxiliary_bus +* backlight/lp855x-driver.rst +* connector +* console +* dcdbas +* eisa +* isa +* isapnp +* io-mapping +* generic-counter +* memory-devices/index +* men-chameleon-bus +* ntb +* nvmem +* parport-lowlevel +* pps +* ptp +* phy/index +* pwm +* pldmfw/index +* rfkill +* serial/index +* sm501 +* surface_aggregator/index +* switchtec +* sync_file +* tty/index +* vfio-mediated-device +* vfio +* vfio-pci-device-specific-driver-acceptance +* xilinx/index +* xillybus +* zorro +* hte/index + +.. only:: subproject and html + + Indices + ======= + + * :ref:`genindex` diff --git a/Documentation/translations/zh_CN/driver-api/io_ordering.rst b/Documentation/translations/zh_CN/driver-api/io_ordering.rst new file mode 100644 index 000000000000..4dbfa4ce92a0 --- /dev/null +++ b/Documentation/translations/zh_CN/driver-api/io_ordering.rst @@ -0,0 +1,60 @@ +.. SPDX-License-Identifier: GPL-2.0 + +.. include:: ../disclaimer-zh_CN.rst + +:Original: Documentation/driver-api/io_ordering.rst + +:翻译: + + 林永听 Lin Yongting <linyongting@gmail.com> + 司延腾 Yanteng Si <siyanteng@loongson.cn> + +:校译: + +=========================== +对内存映射地址的I/O写入排序 +=========================== + +在某些平台上，所谓的内存映射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/iio/iio_configfs.rst b/Documentation/translations/zh_CN/iio/iio_configfs.rst index d5460e951804..eccaf1c644b4 100644 --- a/Documentation/translations/zh_CN/iio/iio_configfs.rst +++ b/Documentation/translations/zh_CN/iio/iio_configfs.rst @@ -37,10 +37,10 @@ configfs轻松配置的对象（例如：设备，触发器）。 3. 软件触发器 ============= -IIO默认configfs组之一是“触发器”组。 挂载configfs后可以自动访问它，并且可 +IIO默认configfs组之一是“触发器”组。挂载configfs后可以自动访问它，并且可 以在/config/iio/triggers下找到。 -IIO软件触发器为创建多种触发器类型提供了支持。 通常在include/linux/iio +IIO软件触发器为创建多种触发器类型提供了支持。通常在include/linux/iio /sw_trigger.h：中的接口下将新的触发器类型实现为单独的内核模块： :: @@ -76,10 +76,10 @@ IIO软件触发器为创建多种触发器类型提供了支持。 通常在incl .ops = &iio_trig_sample_ops, }; -module_iio_sw_trigger_driver(iio_trig_sample); + module_iio_sw_trigger_driver(iio_trig_sample); -每种触发器类型在/config/iio/triggers下都有其自己的目录。 加载iio-trig-sample -模块将创建“ trig-sample”触发器类型目录/config/iio/triggers/trig-sample. +每种触发器类型在/config/iio/triggers下都有其自己的目录。加载iio-trig-sample +模块将创建“trig-sample”触发器类型目录/config/iio/triggers/trig-sample. 我们支持以下中断源（触发器类型） @@ -102,3 +102,5 @@ module_iio_sw_trigger_driver(iio_trig_sample); ---------------------------- "hrtimer”触发器类型没有来自/config dir的任何可配置属性。 +它确实引入了触发目录的sampling_frequency属性。 +该属性以Hz为单位设置轮询频率，精度为mHz。
\ No newline at end of file diff --git a/Documentation/translations/zh_CN/index.rst b/Documentation/translations/zh_CN/index.rst index 46e14ec9963d..ec99ef5fe990 100644 --- a/Documentation/translations/zh_CN/index.rst +++ b/Documentation/translations/zh_CN/index.rst @@ -5,7 +5,7 @@ \renewcommand\thesection* \renewcommand\thesubsection* \kerneldocCJKon - \kerneldocBeginSC + \kerneldocBeginSC{ .. _linux_doc_zh: @@ -26,159 +26,100 @@ 顺便说下，中文文档也需要遵守内核编码风格，风格中中文和英文的主要不同就是中文 的字符标点占用两个英文字符宽度， 所以，当英文要求不要超过每行100个字符时， 中文就不要超过50个字符。另外，也要注意'-'，'=' 等符号与相关标题的对齐。在将 -补丁提交到社区之前，一定要进行必要的checkpatch.pl检查和编译测试。 +补丁提交到社区之前，一定要进行必要的 ``checkpatch.pl`` 检查和编译测试。 -许可证文档 ----------- - -下面的文档介绍了Linux内核源代码的许可证（GPLv2）、如何在源代码树中正确标记 -单个文件的许可证、以及指向完整许可证文本的链接。 - -* Documentation/translations/zh_CN/process/license-rules.rst +与Linux 内核社区一起工作 +------------------------ -用户文档 --------- - -下面的手册是为内核用户编写的——即那些试图让它在给定系统上以最佳方式工作的 -用户。 +与内核开发社区进行协作并将工作推向上游的基本指南。 .. toctree:: - :maxdepth: 2 + :maxdepth: 1 - admin-guide/index + process/development-process + process/submitting-patches + 行为准则 <process/code-of-conduct> + maintainer/index + 完整开发流程文档 <process/index> -TODOList: +内部API文档 +----------- -* kbuild/index +开发人员使用的内核内部交互接口手册。 -固件相关文档 ------------- +.. toctree:: + :maxdepth: 1 -下列文档描述了内核需要的平台固件相关信息。 + core-api/index + driver-api/index + 内核中的锁 <locking/index> TODOList: -* firmware-guide/index -* devicetree/index - -应用程序开发人员文档 --------------------- +* subsystem-apis -用户空间API手册涵盖了描述应用程序开发人员可见内核接口方面的文档。 - -TODOlist: - -* userspace-api/index - -内核开发简介 ------------- +开发工具和流程 +-------------- -这些手册包含有关如何开发内核的整体信息。内核社区非常庞大，一年下来有数千名 -开发人员做出贡献。与任何大型社区一样，知道如何完成任务将使得更改合并的过程 -变得更加容易。 +为所有内核开发人员提供有用信息的各种其他手册。 .. toctree:: - :maxdepth: 2 + :maxdepth: 1 - process/index - dev-tools/index + process/license-rules doc-guide/index + dev-tools/index + dev-tools/testing-overview kernel-hacking/index - maintainer/index TODOList: * trace/index * fault-injection/index * livepatch/index -* rust/index -内核API文档 ------------ +面向用户的文档 +-------------- -以下手册从内核开发人员的角度详细介绍了特定的内核子系统是如何工作的。这里的 -大部分信息都是直接从内核源代码获取的，并根据需要添加补充材料（或者至少是在 -我们设法添加的时候——可能不是所有的都是有需要的）。 +下列手册针对 +希望内核在给定系统上以最佳方式工作的*用户*， +和查找内核用户空间API信息的程序开发人员。 .. toctree:: - :maxdepth: 2 + :maxdepth: 1 - core-api/index - cpu-freq/index - iio/index - sound/index - filesystems/index - virt/index - infiniband/index - accounting/index - scheduler/index + admin-guide/index + admin-guide/reporting-issues.rst TODOList: -* driver-api/index -* locking/index -* block/index -* cdrom/index -* ide/index -* fb/index -* fpga/index -* hid/index -* i2c/index -* isdn/index -* leds/index -* netlabel/index -* networking/index -* pcmcia/index -* power/index -* target/index -* timers/index -* spi/index -* w1/index -* watchdog/index -* input/index -* hwmon/index -* gpu/index -* security/index -* crypto/index -* vm/index -* bpf/index -* usb/index -* PCI/index -* scsi/index -* misc-devices/index -* mhi/index - -体系结构无关文档 ----------------- +* 内核构建系统 <kbuild/index> +* 用户空间工具 <tools/index> +* userspace-api/index -TODOList: +也可参考独立于内核文档的 `Linux 手册页 <https://www.kernel.org/doc/man-pages/>`_ 。 -* asm-annotations +固件相关文档 +------------ -特定体系结构文档 ----------------- +下列文档描述了内核需要的平台固件相关信息。 .. toctree:: :maxdepth: 2 - mips/index - arm64/index - riscv/index - openrisc/index - parisc/index + devicetree/index TODOList: -* arm/index -* ia64/index -* m68k/index -* nios2/index -* powerpc/index -* s390/index -* sh/index -* sparc/index -* x86/index -* xtensa/index +* firmware-guide/index + +体系结构文档 +------------ + +.. toctree:: + :maxdepth: 2 + + arch 其他文档 -------- @@ -189,13 +130,13 @@ TODOList: TODOList: * staging/index -* watch_queue -目录和表格 + +索引和表格 ---------- * :ref:`genindex` .. raw:: latex - \kerneldocEndSC + }\kerneldocEndSC diff --git a/Documentation/translations/zh_CN/io_ordering.txt b/Documentation/translations/zh_CN/io_ordering.txt deleted file mode 100644 index 7bb3086227ae..000000000000 --- a/Documentation/translations/zh_CN/io_ordering.txt +++ /dev/null @@ -1,67 +0,0 @@ -Chinese translated version of Documentation/driver-api/io_ordering.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: Lin Yongting <linyongting@gmail.com> ---------------------------------------------------------------------- -Documentation/driver-api/io_ordering.rst 的中文翻译 - -如果想评论或更新本文的内容，请直接联系原文档的维护者。如果你使用英文 -交流有困难的话，也可以向中文版维护者求助。如果本翻译更新不及时或者翻 -译存在问题，请联系中文版维护者。 - -中文版维护者： 林永听 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/kernel-hacking/hacking.rst b/Documentation/translations/zh_CN/kernel-hacking/hacking.rst index f2bc154c5bcc..9112949b993c 100644 --- a/Documentation/translations/zh_CN/kernel-hacking/hacking.rst +++ b/Documentation/translations/zh_CN/kernel-hacking/hacking.rst @@ -81,7 +81,7 @@ 过硬件中断）的“软件中断”将运行（ ``kernel/softirq.c`` ）。 此处完成了许多真正的中断处理工作。在向SMP过渡的早期，只有“bottom halves下半 -部”（BHs）机制，无法利用多个CPU的优势。在从那些一团糟的就电脑切换过来后不久， +部”（BHs）机制，无法利用多个CPU的优势。在从那些一团糟的旧电脑切换过来后不久， 我们放弃了这个限制，转而使用“软中断”。 ``include/linux/interrupt.h`` 列出了不同的软中断。定时器软中断是一个非常重要 @@ -95,8 +95,7 @@ .. warning:: - “tasklet”这个名字是误导性的：它们与“任务”无关，可能更多与当时 - 阿列克谢·库兹涅佐夫享用的糟糕伏特加有关。 + “tasklet”这个名字是误导性的：它们与“任务”无关。 你可以使用 :c:func:`in_softirq()` 宏（ ``include/linux/preempt.h`` ）来确认 是否处于软中断（或子任务）中。 @@ -247,7 +246,7 @@ Provide mechanism not policy”。 与 :c:func:`put_user()` 和 :c:func:`get_user()` 不同，它们返回未复制的 数据量（即0仍然意味着成功）。 -【是的，这个愚蠢的接口真心让我尴尬。火爆的口水仗大概每年都会发生。 +【是的，这个讨厌的接口真心让我尴尬。火爆的口水仗大概每年都会发生。 —— Rusty Russell】 这些函数可以隐式睡眠。它不应该在用户上下文之外调用（没有意义）、调用时禁用中断 @@ -538,9 +537,9 @@ Documentation/core-api/symbol-namespaces.rst 。 Linus和其他开发人员有时会更改开发内核中的函数或结构体名称；这样做不仅是为了 让每个人都保持警惕，还反映了一个重大的更改（例如，不能再在打开中断的情况下 -调用，或者执行额外的检查，或者不执行以前捕获的检查）。通常这会附带一个linux -内核邮件列表中相当全面的注释；请搜索存档以查看。简单地对文件进行全局替换通常 -会让事情变得 **更糟** 。 +调用，或者执行额外的检查，或者不执行以前捕获的检查）。通常这会附带发送一个 +相当全面的注释到相应的内核邮件列表中；请搜索存档以查看。简单地对文件进行全局 +替换通常只会让事情变得 **更糟** 。 初始化结构体成员 ------------------ @@ -610,7 +609,7 @@ C++ 为了让你的东西更正式、补丁更整洁，还有一些工作要做： -- 搞清楚你在谁的地界儿上干活。查看源文件的顶部、 ``MAINTAINERS`` 文件以及 +- 搞清楚你修改的代码属于谁。查看源文件的根目录、 ``MAINTAINERS`` 文件以及 ``CREDITS`` 文件的最后一部分。你应该和此人协调，确保你没有重新发明轮子， 或者尝试一些已经被拒绝的东西。 @@ -629,12 +628,12 @@ C++ “obj-$(CONFIG_xxx) += xxx.o”。语法记录在 Documentation/kbuild/makefiles.rst 。 -- 如果你做了一些有意义的事情，那可以把自己放进 ``CREDITS`` ，通常不止一个 - 文件（无论如何你的名字都应该在源文件的顶部）。维护人员意味着您希望在对 - 子系统进行更改时得到询问，并了解缺陷；这意味着对某部分代码做出更多承诺。 +- 如果你认为自己做了一些有意义的事情，可以把自己放进 ``CREDITS`` ，通常不 + 止一个文件（无论如何你的名字都应该在源文件的顶部）。 ``MAINTAINERS`` + 意味着您希望在对子系统进行更改时得到询问，并了解缺陷；这意味着对某部分 + 代码做出更多承诺。 -- 最后，别忘记去阅读 Documentation/process/submitting-patches.rst ， - 也许还有 Documentation/process/submitting-drivers.rst 。 +- 最后，别忘记去阅读 Documentation/process/submitting-patches.rst。 Kernel 仙女棒 =============== diff --git a/Documentation/translations/zh_CN/locking/index.rst b/Documentation/translations/zh_CN/locking/index.rst new file mode 100644 index 000000000000..f0b10707668d --- /dev/null +++ b/Documentation/translations/zh_CN/locking/index.rst @@ -0,0 +1,43 @@ +.. SPDX-License-Identifier: GPL-2.0 +.. include:: ../disclaimer-zh_CN.rst + +:Original: Documentation/locking/index.rst + +:翻译: + + 唐艺舟 Tang Yizhou <tangyeechou@gmail.com> + +== +锁 +== + +.. toctree:: + :maxdepth: 1 + + mutex-design + spinlocks + +TODOList: + + * locktypes + * lockdep-design + * lockstat + * locktorture + * rt-mutex-design + * rt-mutex + * seqlock + * ww-mutex-design + * preempt-locking + * pi-futex + * futex-requeue-pi + * hwspinlock + * percpu-rw-semaphore + * robust-futexes + * robust-futex-ABI + +.. only:: subproject and html + + Indices + ======= + + * :ref:`genindex` diff --git a/Documentation/translations/zh_CN/locking/mutex-design.rst b/Documentation/translations/zh_CN/locking/mutex-design.rst new file mode 100644 index 000000000000..6aad54372a6c --- /dev/null +++ b/Documentation/translations/zh_CN/locking/mutex-design.rst @@ -0,0 +1,145 @@ +.. SPDX-License-Identifier: GPL-2.0 +.. include:: ../disclaimer-zh_CN.rst + +:Original: Documentation/locking/mutex-design.rst + +:翻译: + + 唐艺舟 Tang Yizhou <tangyeechou@gmail.com> + +================ +通用互斥锁子系统 +================ + +:初稿: + + Ingo Molnar <mingo@redhat.com> + +:更新: + + Davidlohr Bueso <davidlohr@hp.com> + +什么是互斥锁？ +-------------- + +在Linux内核中，互斥锁（mutex）指的是一个特殊的加锁原语，它在共享内存系统上 +强制保证序列化，而不仅仅是指在学术界或类似的理论教科书中出现的通用术语“相互 +排斥”。互斥锁是一种睡眠锁，它的行为类似于二进制信号量（semaphores），在 +2006年被引入时[1]，作为后者的替代品。这种新的数据结构提供了许多优点，包括更 +简单的接口，以及在当时更少的代码量（见缺陷）。 + +[1] https://lwn.net/Articles/164802/ + +实现 +---- + +互斥锁由“struct mutex”表示，在include/linux/mutex.h中定义，并在 +kernel/locking/mutex.c中实现。这些锁使用一个原子变量（->owner）来跟踪 +它们生命周期内的锁状态。字段owner实际上包含的是指向当前锁所有者的 +`struct task_struct *` 指针，因此如果无人持有锁，则它的值为空（NULL）。 +由于task_struct的指针至少按L1_CACHE_BYTES对齐，低位（3）被用来存储额外 +的状态（例如，等待者列表非空）。在其最基本的形式中，它还包括一个等待队列和 +一个确保对其序列化访问的自旋锁。此外，CONFIG_MUTEX_SPIN_ON_OWNER=y的 +系统使用一个自旋MCS锁（->osq，译注：MCS是两个人名的合并缩写），在下文的 +（ii）中描述。 + +准备获得一把自旋锁时，有三种可能经过的路径，取决于锁的状态： + +(i) 快速路径：试图通过调用cmpxchg()修改锁的所有者为当前任务，以此原子化地 + 获取锁。这只在无竞争的情况下有效（cmpxchg()检查值是否为0，所以3个状态 + 比特必须为0）。如果锁处在竞争状态，代码进入下一个可能的路径。 + +(ii) 中速路径：也就是乐观自旋，当锁的所有者正在运行并且没有其它优先级更高的 + 任务（need_resched，需要重新调度）准备运行时，当前任务试图自旋来获得 + 锁。原理是，如果锁的所有者正在运行，它很可能不久就会释放锁。互斥锁自旋体 + 使用MCS锁排队，这样只有一个自旋体可以竞争互斥锁。 + + MCS锁（由Mellor-Crummey和Scott提出）是一个简单的自旋锁，它具有一些 + 理想的特性，比如公平，以及每个CPU在试图获得锁时在一个本地变量上自旋。 + 它避免了常见的“检测-设置”自旋锁实现导致的（CPU核间）缓存行回弹 + （cacheline bouncing）这种昂贵的开销。一个类MCS锁是为实现睡眠锁的 + 乐观自旋而专门定制的。这种定制MCS锁的一个重要特性是，它有一个额外的属性， + 当自旋体需要重新调度时，它们能够退出MCS自旋锁队列。这进一步有助于避免 + 以下场景：需要重新调度的MCS自旋体将继续自旋等待自旋体所有者，即将获得 + MCS锁时却直接进入慢速路径。 + +(iii) 慢速路径：最后的手段，如果仍然无法获得锁，该任务会被添加到等待队列中， + 休眠直到被解锁路径唤醒。在通常情况下，它以TASK_UNINTERRUPTIBLE状态 + 阻塞。 + +虽然从形式上看，内核互斥锁是可睡眠的锁，路径(ii)使它实际上成为混合类型。通过 +简单地不中断一个任务并忙着等待几个周期，而不是立即睡眠，这种锁已经被认为显著 +改善一些工作负载的性能。注意，这种技术也被用于读写信号量（rw-semaphores）。 + +语义 +---- + +互斥锁子系统检查并强制执行以下规则: + + - 每次只有一个任务可以持有该互斥锁。 + - 只有锁的所有者可以解锁该互斥锁。 + - 不允许多次解锁。 + - 不允许递归加锁/解锁。 + - 互斥锁只能通过API进行初始化（见下文）。 + - 一个任务不能在持有互斥锁的情况下退出。 + - 持有锁的内存区域不得被释放。 + - 被持有的锁不能被重新初始化。 + - 互斥锁不能用于硬件或软件中断上下文，如小任务（tasklet）和定时器。 + +当CONFIG DEBUG_MUTEXES被启用时，这些语义将被完全强制执行。此外，互斥锁 +调试代码还实现了一些其它特性，使锁的调试更容易、更快速： + + - 当打印到调试输出时，总是使用互斥锁的符号名称。 + - 加锁点跟踪，函数名符号化查找，系统持有的全部锁的列表，打印出它们。 + - 所有者跟踪。 + - 检测自我递归的锁并打印所有相关信息。 + - 检测多任务环形依赖死锁，并打印所有受影响的锁和任务（并且只限于这些任务）。 + + +接口 +---- +静态定义互斥锁:: + + DEFINE_MUTEX(name); + +动态初始化互斥锁:: + + mutex_init(mutex); + +以不可中断方式（uninterruptible）获取互斥锁:: + + void mutex_lock(struct mutex *lock); + void mutex_lock_nested(struct mutex *lock, unsigned int subclass); + int mutex_trylock(struct mutex *lock); + +以可中断方式（interruptible）获取互斥锁:: + + int mutex_lock_interruptible_nested(struct mutex *lock, + unsigned int subclass); + int mutex_lock_interruptible(struct mutex *lock); + +当原子变量减为0时，以可中断方式（interruptible）获取互斥锁:: + + int atomic_dec_and_mutex_lock(atomic_t *cnt, struct mutex *lock); + +释放互斥锁:: + + void mutex_unlock(struct mutex *lock); + +检测是否已经获取互斥锁:: + + int mutex_is_locked(struct mutex *lock); + +缺陷 +---- + +与它最初的设计和目的不同，'struct mutex' 是内核中最大的锁之一。例如：在 +x86-64上它是32字节，而 'struct semaphore' 是24字节，rw_semaphore是 +40字节。更大的结构体大小意味着更多的CPU缓存和内存占用。 + + +何时使用互斥锁 +-------------- + +总是优先选择互斥锁而不是任何其它锁原语，除非互斥锁的严格语义不合适，和/或临界区 +阻止锁被共享。 diff --git a/Documentation/translations/zh_CN/locking/spinlocks.rst b/Documentation/translations/zh_CN/locking/spinlocks.rst new file mode 100644 index 000000000000..2017c01f0a4b --- /dev/null +++ b/Documentation/translations/zh_CN/locking/spinlocks.rst @@ -0,0 +1,149 @@ +.. SPDX-License-Identifier: GPL-2.0 +.. include:: ../disclaimer-zh_CN.rst + +:Original: Documentation/locking/spinlocks.rst + +:翻译: + + 唐艺舟 Tang Yizhou <tangyeechou@gmail.com> + +========== +加锁的教训 +========== + +教训 1：自旋锁 +============== + +加锁最基本的原语是自旋锁（spinlock）:: + + static DEFINE_SPINLOCK(xxx_lock); + + unsigned long flags; + + spin_lock_irqsave(&xxx_lock, flags); + ... 这里是临界区 .. + spin_unlock_irqrestore(&xxx_lock, flags); + +上述代码总是安全的。自旋锁将在 _本地_ 禁用中断，但它本身将保证全局锁定。所以它 +将保证在该锁保护的区域内只有一个控制线程。即使在单处理器（UP）下也能很好的工作， +所以代码 _不_ 需要担心UP还是SMP的问题：自旋锁在两种情况下都能正常工作。 + + 注意！自旋锁对内存的潜在影响由下述文档进一步描述： + + Documentation/memory-barriers.txt + + (5) ACQUIRE operations. + + (6) RELEASE operations. + +上述代码通常非常简单（对大部分情况，你通常需要并且只希望有一个自旋锁——使用多个 +自旋锁会使事情变得更复杂，甚至更慢，而且通常仅仅在你 **理解的** 序列有被拆分的 +需求时才值得这么做：如果你不确定的话，请不惜一切代价避免这样做）。 + +这是关于自旋锁的唯一真正困难的部分：一旦你开始使用自旋锁，它们往往会扩展到你以前 +可能没有注意到的领域，因为你必须确保自旋锁正确地保护共享数据结构 **每一处** 被 +使用的地方。自旋锁是最容易被添加到完全独立于其它代码的地方（例如，没有人访问的 +内部驱动数据结构）的。 + + 注意！仅当你在跨CPU核访问时使用 **同一把** 自旋锁，对它的使用才是安全的。 + 这意味着所有访问共享变量的代码必须对它们想使用的自旋锁达成一致。 + +---- + +教训 2：读-写自旋锁 +=================== + +如果你的数据访问有一个非常自然的模式，倾向于从共享变量中读取数据，读-写自旋锁 +（rw_lock）有时是有用的。它们允许多个读者同时出现在同一个临界区，但是如果有人想 +改变变量，它必须获得一个独占的写锁。 + + 注意！读-写自旋锁比原始自旋锁需要更多的原子内存操作。除非读者的临界区很长， + 否则你最好只使用原始自旋锁。 + +例程看起来和上面一样:: + + rwlock_t xxx_lock = __RW_LOCK_UNLOCKED(xxx_lock); + + unsigned long flags; + + read_lock_irqsave(&xxx_lock, flags); + .. 仅读取信息的临界区 ... + read_unlock_irqrestore(&xxx_lock, flags); + + write_lock_irqsave(&xxx_lock, flags); + .. 读取和独占写信息 ... + write_unlock_irqrestore(&xxx_lock, flags); + +上面这种锁对于复杂的数据结构如链表可能会有用，特别是在不改变链表的情况下搜索其中 +的条目。读锁允许许多并发的读者。任何希望 **修改** 链表的代码将必须先获取写锁。 + + 注意！RCU锁更适合遍历链表，但需要仔细注意设计细节（见Documentation/RCU/listRCU.rst）。 + +另外，你不能把读锁“升级”为写锁，所以如果你在 _任何_ 时候需要做任何修改 +（即使你不是每次都这样做），你必须在一开始就获得写锁。 + + 注意！我们正在努力消除大多数情况下的读-写自旋锁的使用，所以请不要在没有达成 + 共识的情况下增加一个新的（相反，请参阅Documentation/RCU/rcu.rst以获得完整 + 信息）。 + +---- + +教训 3：重新审视自旋锁 +====================== + +上述的自旋锁原语绝不是唯一的。它们是最安全的，在所有情况下都能正常工作，但部分 +**因为** 它们是安全的，它们也是相当慢的。它们比原本需要的更慢，因为它们必须要 +禁用中断（在X86上只是一条指令，但却是一条昂贵的指令——而在其他体系结构上，情况 +可能更糟）。 + +如果你有必须保护跨CPU访问的数据结构且你想使用自旋锁的场景，你有可能使用代价小的 +自旋锁版本。当且仅当你知道某自旋锁永远不会在中断处理程序中使用，你可以使用非中断 +的版本:: + + spin_lock(&lock); + ... + spin_unlock(&lock); + +（当然，也可以使用相应的读-写锁版本）。这种自旋锁将同样可以保证独占访问，而且 +速度会快很多。如果你知道有关的数据只在“进程上下文”中被存取，即，不涉及中断， +这种自旋锁就有用了。 + +当这些版本的自旋锁涉及中断时，你不能使用的原因是会陷入死锁:: + + spin_lock(&lock); + ... + <- 中断来临： + spin_lock(&lock); + +一个中断试图对一个已经锁定的变量上锁。如果中断发生在另一个CPU上，不会有问题； +但如果中断发生在已经持有自旋锁的同一个CPU上，将 _会_ 有问题，因为该锁显然永远 +不会被释放（因为中断正在等待该锁，而锁的持有者被中断打断，并且无法继续执行， +直到中断处理结束）。 + +（这也是自旋锁的中断版本只需要禁用 _本地_ 中断的原因——在发生于其它CPU的中断中 +使用同一把自旋锁是没问题的，因为发生于其它CPU的中断不会打断已经持锁的CPU，所以 +锁的持有者可以继续执行并最终释放锁）。 + + Linus + +---- + +参考信息 +======== + +对于动态初始化，使用spin_lock_init()或rwlock_init()是合适的:: + + spinlock_t xxx_lock; + rwlock_t xxx_rw_lock; + + static int __init xxx_init(void) + { + spin_lock_init(&xxx_lock); + rwlock_init(&xxx_rw_lock); + ... + } + + module_init(xxx_init); + +对于静态初始化，使用DEFINE_SPINLOCK() / DEFINE_RWLOCK()或 +__SPIN_LOCK_UNLOCKED() / __RW_LOCK_UNLOCKED()是合适的。 diff --git a/Documentation/translations/zh_CN/loongarch/features.rst b/Documentation/translations/zh_CN/loongarch/features.rst new file mode 100644 index 000000000000..3886e635ec06 --- /dev/null +++ b/Documentation/translations/zh_CN/loongarch/features.rst @@ -0,0 +1,8 @@ +.. SPDX-License-Identifier: GPL-2.0 + +.. include:: ../disclaimer-zh_CN.rst + +:Original: Documentation/loongarch/features.rst +:Translator: Huacai Chen <chenhuacai@loongson.cn> + +.. kernel-feat:: $srctree/Documentation/features loongarch diff --git a/Documentation/translations/zh_CN/loongarch/index.rst b/Documentation/translations/zh_CN/loongarch/index.rst new file mode 100644 index 000000000000..7d23eb78379d --- /dev/null +++ b/Documentation/translations/zh_CN/loongarch/index.rst @@ -0,0 +1,26 @@ +.. SPDX-License-Identifier: GPL-2.0 + +.. include:: ../disclaimer-zh_CN.rst + +:Original: Documentation/loongarch/index.rst +:Translator: Huacai Chen <chenhuacai@loongson.cn> + +================= +LoongArch体系结构 +================= + +.. toctree:: + :maxdepth: 2 + :numbered: + + introduction + irq-chip-model + + features + +.. only:: subproject and html + + Indices + ======= + + * :ref:`genindex` diff --git a/Documentation/translations/zh_CN/loongarch/introduction.rst b/Documentation/translations/zh_CN/loongarch/introduction.rst new file mode 100644 index 000000000000..128878f5bb70 --- /dev/null +++ b/Documentation/translations/zh_CN/loongarch/introduction.rst @@ -0,0 +1,353 @@ +.. SPDX-License-Identifier: GPL-2.0 + +.. include:: ../disclaimer-zh_CN.rst + +:Original: Documentation/loongarch/introduction.rst +:Translator: Huacai Chen <chenhuacai@loongson.cn> + +============= +LoongArch介绍 +============= + +LoongArch是一种新的RISC ISA，在一定程度上类似于MIPS和RISC-V。LoongArch指令集 +包括一个精简32位版（LA32R）、一个标准32位版（LA32S）、一个64位版（LA64）。 +LoongArch定义了四个特权级（PLV0~PLV3），其中PLV0是最高特权级，用于内核；而PLV3 +是最低特权级，用于应用程序。本文档介绍了LoongArch的寄存器、基础指令集、虚拟内 +存以及其他一些主题。 + +寄存器 +====== + +LoongArch的寄存器包括通用寄存器（GPRs）、浮点寄存器（FPRs）、向量寄存器（VRs） +和用于特权模式（PLV0）的控制状态寄存器（CSRs）。 + +通用寄存器 +---------- + +LoongArch包括32个通用寄存器（ ``$r0`` ~ ``$r31`` ），LA32中每个寄存器为32位宽， +LA64中每个寄存器为64位宽。 ``$r0`` 的内容总是固定为0，而其他寄存器在体系结构层面 +没有特殊功能。（ ``$r1`` 算是一个例外，在BL指令中固定用作链接返回寄存器。） + +内核使用了一套LoongArch寄存器约定，定义在LoongArch ELF psABI规范中，详细描述参见 +:ref:`参考文献 <loongarch-references-zh_CN>`: + +================= =============== =================== ========== +寄存器名 别名 用途 跨调用保持 +================= =============== =================== ========== +``$r0`` ``$zero`` 常量0 不使用 +``$r1`` ``$ra`` 返回地址 否 +``$r2`` ``$tp`` TLS/线程信息指针 不使用 +``$r3`` ``$sp`` 栈指针 是 +``$r4``-``$r11`` ``$a0``-``$a7`` 参数寄存器 否 +``$r4``-``$r5`` ``$v0``-``$v1`` 返回值 否 +``$r12``-``$r20`` ``$t0``-``$t8`` 临时寄存器 否 +``$r21`` ``$u0`` 每CPU变量基地址 不使用 +``$r22`` ``$fp`` 帧指针 是 +``$r23``-``$r31`` ``$s0``-``$s8`` 静态寄存器 是 +================= =============== =================== ========== + +.. note:: + 注意： ``$r21`` 寄存器在ELF psABI中保留未使用，但是在Linux内核用于保 + 存每CPU变量基地址。该寄存器没有ABI命名，不过在内核中称为 ``$u0`` 。在 + 一些遗留代码中有时可能见到 ``$v0`` 和 ``$v1`` ，它们是 ``$a0`` 和 + ``$a1`` 的别名，属于已经废弃的用法。 + +浮点寄存器 +---------- + +当系统中存在FPU时，LoongArch有32个浮点寄存器（ ``$f0`` ~ ``$f31`` ）。在LA64 +的CPU核上，每个寄存器均为64位宽。 + +浮点寄存器的使用约定与LoongArch ELF psABI规范的描述相同： + +================= ================== =================== ========== +寄存器名 别名 用途 跨调用保持 +================= ================== =================== ========== +``$f0``-``$f7`` ``$fa0``-``$fa7`` 参数寄存器 否 +``$f0``-``$f1`` ``$fv0``-``$fv1`` 返回值 否 +``$f8``-``$f23`` ``$ft0``-``$ft15`` 临时寄存器 否 +``$f24``-``$f31`` ``$fs0``-``$fs7`` 静态寄存器 是 +================= ================== =================== ========== + +.. note:: + 注意：在一些遗留代码中有时可能见到 ``$v0`` 和 ``$v1`` ，它们是 + ``$a0`` 和 ``$a1`` 的别名，属于已经废弃的用法。 + + +向量寄存器 +---------- + +LoongArch现有两种向量扩展： + +- 128位向量扩展LSX（全称Loongson SIMD eXtention）， +- 256位向量扩展LASX（全称Loongson Advanced SIMD eXtention）。 + +LSX使用 ``$v0`` ~ ``$v31`` 向量寄存器，而LASX则使用 ``$x0`` ~ ``$x31`` 。 + +浮点寄存器和向量寄存器是复用的，比如：在一个实现了LSX和LASX的核上， ``$x0`` 的 +低128位与 ``$v0`` 共用， ``$v0`` 的低64位与 ``$f0`` 共用，其他寄存器依此类推。 + +控制状态寄存器 +-------------- + +控制状态寄存器只能在特权模式（PLV0）下访问: + +================= ==================================== ========== +地址 全称描述 简称 +================= ==================================== ========== +0x0 当前模式信息 CRMD +0x1 异常前模式信息 PRMD +0x2 扩展部件使能 EUEN +0x3 杂项控制 MISC +0x4 异常配置 ECFG +0x5 异常状态 ESTAT +0x6 异常返回地址 ERA +0x7 出错(Faulting)虚拟地址 BADV +0x8 出错(Faulting)指令字 BADI +0xC 异常入口地址 EENTRY +0x10 TLB索引 TLBIDX +0x11 TLB表项高位 TLBEHI +0x12 TLB表项低位0 TLBELO0 +0x13 TLB表项低位1 TLBELO1 +0x18 地址空间标识符 ASID +0x19 低半地址空间页全局目录基址 PGDL +0x1A 高半地址空间页全局目录基址 PGDH +0x1B 页全局目录基址 PGD +0x1C 页表遍历控制低半部分 PWCL +0x1D 页表遍历控制高半部分 PWCH +0x1E STLB页大小 STLBPS +0x1F 缩减虚地址配置 RVACFG +0x20 CPU编号 CPUID +0x21 特权资源配置信息1 PRCFG1 +0x22 特权资源配置信息2 PRCFG2 +0x23 特权资源配置信息3 PRCFG3 +0x30+n (0≤n≤15) 数据保存寄存器 SAVEn +0x40 定时器编号 TID +0x41 定时器配置 TCFG +0x42 定时器值 TVAL +0x43 计时器补偿 CNTC +0x44 定时器中断清除 TICLR +0x60 LLBit相关控制 LLBCTL +0x80 实现相关控制1 IMPCTL1 +0x81 实现相关控制2 IMPCTL2 +0x88 TLB重填异常入口地址 TLBRENTRY +0x89 TLB重填异常出错(Faulting)虚地址 TLBRBADV +0x8A TLB重填异常返回地址 TLBRERA +0x8B TLB重填异常数据保存 TLBRSAVE +0x8C TLB重填异常表项低位0 TLBRELO0 +0x8D TLB重填异常表项低位1 TLBRELO1 +0x8E TLB重填异常表项高位 TLBEHI +0x8F TLB重填异常前模式信息 TLBRPRMD +0x90 机器错误控制 MERRCTL +0x91 机器错误信息1 MERRINFO1 +0x92 机器错误信息2 MERRINFO2 +0x93 机器错误异常入口地址 MERRENTRY +0x94 机器错误异常返回地址 MERRERA +0x95 机器错误异常数据保存 MERRSAVE +0x98 高速缓存标签 CTAG +0x180+n (0≤n≤3) 直接映射配置窗口n DMWn +0x200+2n (0≤n≤31) 性能监测配置n PMCFGn +0x201+2n (0≤n≤31) 性能监测计数器n PMCNTn +0x300 内存读写监视点整体控制 MWPC +0x301 内存读写监视点整体状态 MWPS +0x310+8n (0≤n≤7) 内存读写监视点n配置1 MWPnCFG1 +0x311+8n (0≤n≤7) 内存读写监视点n配置2 MWPnCFG2 +0x312+8n (0≤n≤7) 内存读写监视点n配置3 MWPnCFG3 +0x313+8n (0≤n≤7) 内存读写监视点n配置4 MWPnCFG4 +0x380 取指监视点整体控制 FWPC +0x381 取指监视点整体状态 FWPS +0x390+8n (0≤n≤7) 取指监视点n配置1 FWPnCFG1 +0x391+8n (0≤n≤7) 取指监视点n配置2 FWPnCFG2 +0x392+8n (0≤n≤7) 取指监视点n配置3 FWPnCFG3 +0x393+8n (0≤n≤7) 取指监视点n配置4 FWPnCFG4 +0x500 调试寄存器 DBG +0x501 调试异常返回地址 DERA +0x502 调试数据保存 DSAVE +================= ==================================== ========== + +ERA，TLBRERA，MERRERA和DERA有时也分别称为EPC，TLBREPC，MERREPC和DEPC。 + +基础指令集 +========== + +指令格式 +-------- + +LoongArch的指令字长为32位，一共有9种基本指令格式（以及一些变体）: + +=========== ========================== +格式名称 指令构成 +=========== ========================== +2R Opcode + Rj + Rd +3R Opcode + Rk + Rj + Rd +4R Opcode + Ra + Rk + Rj + Rd +2RI8 Opcode + I8 + Rj + Rd +2RI12 Opcode + I12 + Rj + Rd +2RI14 Opcode + I14 + Rj + Rd +2RI16 Opcode + I16 + Rj + Rd +1RI21 Opcode + I21L + Rj + I21H +I26 Opcode + I26L + I26H +=========== ========================== + +Opcode是指令操作码，Rj和Rk是源操作数（寄存器），Rd是目标操作数（寄存器），Ra是 +4R-type格式特有的附加操作数（寄存器）。I8/I12/I14/I16/I21/I26分别是8位/12位/14位/ +16位/21位/26位的立即数。其中较长的21位和26位立即数在指令字中被分割为高位部分与低位 +部分，所以你们在这里的格式描述中能够看到I21L/I21H和I26L/I26H这样带后缀的表述。 + +指令列表 +-------- + +为了简便起见，我们在此只罗列一下指令名称（助记符），需要详细信息请阅读 +:ref:`参考文献 <loongarch-references-zh_CN>` 中的文档。 + +1. 算术运算指令:: + + ADD.W SUB.W ADDI.W ADD.D SUB.D ADDI.D + SLT SLTU SLTI SLTUI + AND OR NOR XOR ANDN ORN ANDI ORI XORI + MUL.W MULH.W MULH.WU DIV.W DIV.WU MOD.W MOD.WU + MUL.D MULH.D MULH.DU DIV.D DIV.DU MOD.D MOD.DU + PCADDI PCADDU12I PCADDU18I + LU12I.W LU32I.D LU52I.D ADDU16I.D + +2. 移位运算指令:: + + SLL.W SRL.W SRA.W ROTR.W SLLI.W SRLI.W SRAI.W ROTRI.W + SLL.D SRL.D SRA.D ROTR.D SLLI.D SRLI.D SRAI.D ROTRI.D + +3. 位域操作指令:: + + EXT.W.B EXT.W.H CLO.W CLO.D SLZ.W CLZ.D CTO.W CTO.D CTZ.W CTZ.D + BYTEPICK.W BYTEPICK.D BSTRINS.W BSTRINS.D BSTRPICK.W BSTRPICK.D + REVB.2H REVB.4H REVB.2W REVB.D REVH.2W REVH.D BITREV.4B BITREV.8B BITREV.W BITREV.D + MASKEQZ MASKNEZ + +4. 分支转移指令:: + + BEQ BNE BLT BGE BLTU BGEU BEQZ BNEZ B BL JIRL + +5. 访存读写指令:: + + LD.B LD.BU LD.H LD.HU LD.W LD.WU LD.D ST.B ST.H ST.W ST.D + LDX.B LDX.BU LDX.H LDX.HU LDX.W LDX.WU LDX.D STX.B STX.H STX.W STX.D + LDPTR.W LDPTR.D STPTR.W STPTR.D + PRELD PRELDX + +6. 原子操作指令:: + + LL.W SC.W LL.D SC.D + AMSWAP.W AMSWAP.D AMADD.W AMADD.D AMAND.W AMAND.D AMOR.W AMOR.D AMXOR.W AMXOR.D + AMMAX.W AMMAX.D AMMIN.W AMMIN.D + +7. 栅障指令:: + + IBAR DBAR + +8. 特殊指令:: + + SYSCALL BREAK CPUCFG NOP IDLE ERTN(ERET) DBCL(DBGCALL) RDTIMEL.W RDTIMEH.W RDTIME.D + ASRTLE.D ASRTGT.D + +9. 特权指令:: + + CSRRD CSRWR CSRXCHG + IOCSRRD.B IOCSRRD.H IOCSRRD.W IOCSRRD.D IOCSRWR.B IOCSRWR.H IOCSRWR.W IOCSRWR.D + CACOP TLBP(TLBSRCH) TLBRD TLBWR TLBFILL TLBCLR TLBFLUSH INVTLB LDDIR LDPTE + +虚拟内存 +======== + +LoongArch可以使用直接映射虚拟内存和分页映射虚拟内存。 + +直接映射虚拟内存通过CSR.DMWn（n=0~3）来进行配置，虚拟地址（VA）和物理地址（PA） +之间有简单的映射关系:: + + VA = PA + 固定偏移 + +分页映射的虚拟地址（VA）和物理地址（PA）有任意的映射关系，这种关系记录在TLB和页 +表中。LoongArch的TLB包括一个全相联的MTLB（Multiple Page Size TLB，多样页大小TLB） +和一个组相联的STLB（Single Page Size TLB，单一页大小TLB）。 + +缺省状态下，LA32的整个虚拟地址空间配置如下： + +============ =========================== =========================== +区段名 地址范围 属性 +============ =========================== =========================== +``UVRANGE`` ``0x00000000 - 0x7FFFFFFF`` 分页映射, 可缓存, PLV0~3 +``KPRANGE0`` ``0x80000000 - 0x9FFFFFFF`` 直接映射, 非缓存, PLV0 +``KPRANGE1`` ``0xA0000000 - 0xBFFFFFFF`` 直接映射, 可缓存, PLV0 +``KVRANGE`` ``0xC0000000 - 0xFFFFFFFF`` 分页映射, 可缓存, PLV0 +============ =========================== =========================== + +用户态（PLV3）只能访问UVRANGE，对于直接映射的KPRANGE0和KPRANGE1，将虚拟地址的第 +30~31位清零就等于物理地址。例如：物理地址0x00001000对应的非缓存直接映射虚拟地址 +是0x80001000，而其可缓存直接映射虚拟地址是0xA0001000。 + +缺省状态下，LA64的整个虚拟地址空间配置如下： + +============ ====================== ================================== +区段名 地址范围 属性 +============ ====================== ================================== +``XUVRANGE`` ``0x0000000000000000 - 分页映射, 可缓存, PLV0~3 + 0x3FFFFFFFFFFFFFFF`` +``XSPRANGE`` ``0x4000000000000000 - 直接映射, 可缓存 / 非缓存, PLV0 + 0x7FFFFFFFFFFFFFFF`` +``XKPRANGE`` ``0x8000000000000000 - 直接映射, 可缓存 / 非缓存, PLV0 + 0xBFFFFFFFFFFFFFFF`` +``XKVRANGE`` ``0xC000000000000000 - 分页映射, 可缓存, PLV0 + 0xFFFFFFFFFFFFFFFF`` +============ ====================== ================================== + +用户态（PLV3）只能访问XUVRANGE，对于直接映射的XSPRANGE和XKPRANGE，将虚拟地址的第 +60~63位清零就等于物理地址，而其缓存属性是通过虚拟地址的第60~61位配置的（0表示强序 +非缓存，1表示一致可缓存，2表示弱序非缓存）。 + +目前，我们仅用XKPRANGE来进行直接映射，XSPRANGE保留给以后用。 + +此处给出一个直接映射的例子：物理地址0x00000000_00001000的强序非缓存直接映射虚拟地址 +（在XKPRANGE中）是0x80000000_00001000，其一致可缓存直接映射虚拟地址（在XKPRANGE中） +是0x90000000_00001000，而其弱序非缓存直接映射虚拟地址（在XKPRANGE中）是0xA0000000_ +00001000。 + +Loongson与LoongArch的关系 +========================= + +LoongArch是一种RISC指令集架构（ISA），不同于现存的任何一种ISA，而Loongson（即龙 +芯）是一个处理器家族。龙芯包括三个系列：Loongson-1（龙芯1号）是32位处理器系列， +Loongson-2（龙芯2号）是低端64位处理器系列，而Loongson-3（龙芯3号）是高端64位处理 +器系列。旧的龙芯处理器基于MIPS架构，而新的龙芯处理器基于LoongArch架构。以龙芯3号 +为例：龙芯3A1000/3B1500/3A2000/3A3000/3A4000都是兼容MIPS的，而龙芯3A5000（以及将 +来的型号）都是基于LoongArch的。 + +.. _loongarch-references-zh_CN: + +参考文献 +======== + +Loongson官方网站（龙芯中科技术股份有限公司）： + + http://www.loongson.cn/ + +Loongson与LoongArch的开发者网站（软件与文档资源）： + + http://www.loongnix.cn/ + + https://github.com/loongson/ + + https://loongson.github.io/LoongArch-Documentation/ + +LoongArch指令集架构的文档： + + https://github.com/loongson/LoongArch-Documentation/releases/latest/download/LoongArch-Vol1-v1.00-CN.pdf （中文版） + + https://github.com/loongson/LoongArch-Documentation/releases/latest/download/LoongArch-Vol1-v1.00-EN.pdf （英文版） + +LoongArch的ELF psABI文档： + + https://github.com/loongson/LoongArch-Documentation/releases/latest/download/LoongArch-ELF-ABI-v1.00-CN.pdf （中文版） + + https://github.com/loongson/LoongArch-Documentation/releases/latest/download/LoongArch-ELF-ABI-v1.00-EN.pdf （英文版） + +Loongson与LoongArch的Linux内核源码仓库： + + https://git.kernel.org/pub/scm/linux/kernel/git/chenhuacai/linux-loongson.git diff --git a/Documentation/translations/zh_CN/loongarch/irq-chip-model.rst b/Documentation/translations/zh_CN/loongarch/irq-chip-model.rst new file mode 100644 index 000000000000..fb5d23b49ed5 --- /dev/null +++ b/Documentation/translations/zh_CN/loongarch/irq-chip-model.rst @@ -0,0 +1,157 @@ +.. SPDX-License-Identifier: GPL-2.0 + +.. include:: ../disclaimer-zh_CN.rst + +:Original: Documentation/loongarch/irq-chip-model.rst +:Translator: Huacai Chen <chenhuacai@loongson.cn> + +================================== +LoongArch的IRQ芯片模型（层级关系） +================================== + +目前，基于LoongArch的处理器（如龙芯3A5000）只能与LS7A芯片组配合工作。LoongArch计算机 +中的中断控制器（即IRQ芯片）包括CPUINTC（CPU Core Interrupt Controller）、LIOINTC（ +Legacy I/O Interrupt Controller）、EIOINTC（Extended I/O Interrupt Controller）、 +HTVECINTC（Hyper-Transport Vector Interrupt Controller）、PCH-PIC（LS7A芯片组的主中 +断控制器）、PCH-LPC（LS7A芯片组的LPC中断控制器）和PCH-MSI（MSI中断控制器）。 + +CPUINTC是一种CPU内部的每个核本地的中断控制器，LIOINTC/EIOINTC/HTVECINTC是CPU内部的 +全局中断控制器（每个芯片一个，所有核共享），而PCH-PIC/PCH-LPC/PCH-MSI是CPU外部的中 +断控制器（在配套芯片组里面）。这些中断控制器（或者说IRQ芯片）以一种层次树的组织形式 +级联在一起，一共有两种层级关系模型（传统IRQ模型和扩展IRQ模型）。 + +传统IRQ模型 +=========== + +在这种模型里面，IPI（Inter-Processor Interrupt）和CPU本地时钟中断直接发送到CPUINTC， +CPU串口（UARTs）中断发送到LIOINTC，而其他所有设备的中断则分别发送到所连接的PCH-PIC/ +PCH-LPC/PCH-MSI，然后被HTVECINTC统一收集，再发送到LIOINTC，最后到达CPUINTC:: + + +-----+ +---------+ +-------+ + | IPI | --> | CPUINTC | <-- | Timer | + +-----+ +---------+ +-------+ + ^ + | + +---------+ +-------+ + | LIOINTC | <-- | UARTs | + +---------+ +-------+ + ^ + | + +-----------+ + | HTVECINTC | + +-----------+ + ^ ^ + | | + +---------+ +---------+ + | PCH-PIC | | PCH-MSI | + +---------+ +---------+ + ^ ^ ^ + | | | + +---------+ +---------+ +---------+ + | PCH-LPC | | Devices | | Devices | + +---------+ +---------+ +---------+ + ^ + | + +---------+ + | Devices | + +---------+ + +扩展IRQ模型 +=========== + +在这种模型里面，IPI（Inter-Processor Interrupt）和CPU本地时钟中断直接发送到CPUINTC， +CPU串口（UARTs）中断发送到LIOINTC，而其他所有设备的中断则分别发送到所连接的PCH-PIC/ +PCH-LPC/PCH-MSI，然后被EIOINTC统一收集，再直接到达CPUINTC:: + + +-----+ +---------+ +-------+ + | IPI | --> | CPUINTC | <-- | Timer | + +-----+ +---------+ +-------+ + ^ ^ + | | + +---------+ +---------+ +-------+ + | EIOINTC | | LIOINTC | <-- | UARTs | + +---------+ +---------+ +-------+ + ^ ^ + | | + +---------+ +---------+ + | PCH-PIC | | PCH-MSI | + +---------+ +---------+ + ^ ^ ^ + | | | + +---------+ +---------+ +---------+ + | PCH-LPC | | Devices | | Devices | + +---------+ +---------+ +---------+ + ^ + | + +---------+ + | Devices | + +---------+ + +ACPI相关的定义 +============== + +CPUINTC:: + + ACPI_MADT_TYPE_CORE_PIC; + struct acpi_madt_core_pic; + enum acpi_madt_core_pic_version; + +LIOINTC:: + + ACPI_MADT_TYPE_LIO_PIC; + struct acpi_madt_lio_pic; + enum acpi_madt_lio_pic_version; + +EIOINTC:: + + ACPI_MADT_TYPE_EIO_PIC; + struct acpi_madt_eio_pic; + enum acpi_madt_eio_pic_version; + +HTVECINTC:: + + ACPI_MADT_TYPE_HT_PIC; + struct acpi_madt_ht_pic; + enum acpi_madt_ht_pic_version; + +PCH-PIC:: + + ACPI_MADT_TYPE_BIO_PIC; + struct acpi_madt_bio_pic; + enum acpi_madt_bio_pic_version; + +PCH-MSI:: + + ACPI_MADT_TYPE_MSI_PIC; + struct acpi_madt_msi_pic; + enum acpi_madt_msi_pic_version; + +PCH-LPC:: + + ACPI_MADT_TYPE_LPC_PIC; + struct acpi_madt_lpc_pic; + enum acpi_madt_lpc_pic_version; + +参考文献 +======== + +龙芯3A5000的文档： + + https://github.com/loongson/LoongArch-Documentation/releases/latest/download/Loongson-3A5000-usermanual-1.02-CN.pdf (中文版) + + https://github.com/loongson/LoongArch-Documentation/releases/latest/download/Loongson-3A5000-usermanual-1.02-EN.pdf (英文版) + +龙芯LS7A芯片组的文档： + + https://github.com/loongson/LoongArch-Documentation/releases/latest/download/Loongson-7A1000-usermanual-2.00-CN.pdf (中文版) + + https://github.com/loongson/LoongArch-Documentation/releases/latest/download/Loongson-7A1000-usermanual-2.00-EN.pdf (英文版) + +.. note:: + - CPUINTC：即《龙芯架构参考手册卷一》第7.4节所描述的CSR.ECFG/CSR.ESTAT寄存器及其 + 中断控制逻辑； + - LIOINTC：即《龙芯3A5000处理器使用手册》第11.1节所描述的“传统I/O中断”； + - EIOINTC：即《龙芯3A5000处理器使用手册》第11.2节所描述的“扩展I/O中断”； + - HTVECINTC：即《龙芯3A5000处理器使用手册》第14.3节所描述的“HyperTransport中断”； + - PCH-PIC/PCH-MSI：即《龙芯7A1000桥片用户手册》第5章所描述的“中断控制器”； + - PCH-LPC：即《龙芯7A1000桥片用户手册》第24.3节所描述的“LPC中断”。 diff --git a/Documentation/translations/zh_CN/mm/active_mm.rst b/Documentation/translations/zh_CN/mm/active_mm.rst new file mode 100644 index 000000000000..c2816f523bd7 --- /dev/null +++ b/Documentation/translations/zh_CN/mm/active_mm.rst @@ -0,0 +1,85 @@ +.. include:: ../disclaimer-zh_CN.rst + +:Original: Documentation/mm/active_mm.rst + +:翻译: + + 司延腾 Yanteng Si <siyanteng@loongson.cn> + +:校译: + + +========= +Active MM +========= + +这是一封linux之父回复开发者的一封邮件，所以翻译时我尽量保持邮件格式的完整。 + +:: + + List: linux-kernel + Subject: Re: active_mm + From: Linus Torvalds <torvalds () transmeta ! com> + Date: 1999-07-30 21:36:24 + + 因为我并不经常写解释，所以已经抄送到linux-kernel邮件列表，而当我做这些， + 且更多的人在阅读它们时，我觉得棒极了。 + + 1999年7月30日 星期五， David Mosberger 写道： + > + > 是否有一个简短的描述，说明task_struct中的 + > "mm" 和 "active_mm"应该如何使用？ (如果 + > 这个问题在邮件列表中讨论过，我表示歉意--我刚 + > 刚度假回来，有一段时间没能关注linux-kernel了）。 + + 基本上，新的设定是： + + - 我们有“真实地址空间”和“匿名地址空间”。区别在于，匿名地址空间根本不关心用 + 户级页表，所以当我们做上下文切换到匿名地址空间时，我们只是让以前的地址空间 + 处于活动状态。 + + 一个“匿名地址空间”的明显用途是任何不需要任何用户映射的线程--所有的内核线 + 程基本上都属于这一类，但即使是“真正的”线程也可以暂时说在一定时间内它们不 + 会对用户空间感兴趣，调度器不妨试着避免在切换VM状态上浪费时间。目前只有老 + 式的bdflush sync能做到这一点。 + + - “tsk->mm” 指向 “真实地址空间”。对于一个匿名进程来说，tsk->mm将是NULL， + 其逻辑原因是匿名进程实际上根本就 “没有” 真正的地址空间。 + + - 然而，我们显然需要跟踪我们为这样的匿名用户“偷用”了哪个地址空间。为此，我们 + 有 “tsk->active_mm”，它显示了当前活动的地址空间是什么。 + + 规则是，对于一个有真实地址空间的进程（即tsk->mm是 non-NULL），active_mm + 显然必须与真实的mm相同。 + + 对于一个匿名进程，tsk->mm == NULL，而tsk->active_mm是匿名进程运行时 + “借用”的mm。当匿名进程被调度走时，借用的地址空间被返回并清除。 + + 为了支持所有这些，“struct mm_struct”现在有两个计数器：一个是 “mm_users” + 计数器，即有多少 “真正的地址空间用户”，另一个是 “mm_count”计数器，即 “lazy” + 用户（即匿名用户）的数量，如果有任何真正的用户，则加1。 + + 通常情况下，至少有一个真正的用户，但也可能是真正的用户在另一个CPU上退出，而 + 一个lazy的用户仍在活动，所以你实际上得到的情况是，你有一个地址空间 **只** + 被lazy的用户使用。这通常是一个短暂的生命周期状态，因为一旦这个线程被安排给一 + 个真正的线程，这个 “僵尸” mm就会被释放，因为 “mm_count”变成了零。 + + 另外，一个新的规则是，**没有人** 再把 “init_mm” 作为一个真正的MM了。 + “init_mm”应该被认为只是一个 “没有其他上下文时的lazy上下文”，事实上，它主 + 要是在启动时使用，当时还没有真正的VM被创建。因此，用来检查的代码 + + if (current->mm == &init_mm) + + 一般来说，应该用 + + if (!current->mm) + + 取代上面的写法（这更有意义--测试基本上是 “我们是否有一个用户环境”，并且通常 + 由缺页异常处理程序和类似的东西来完成）。 + + 总之，我刚才在ftp.kernel.org上放了一个pre-patch-2.3.13-1，因为它稍微改 + 变了接口以适配alpha（谁会想到呢，但alpha体系结构上下文切换代码实际上最终是 + 最丑陋的之一--不像其他架构的MM和寄存器状态是分开的，alpha的PALcode将两者 + 连接起来，你需要同时切换两者）。 + + (文档来源 http://marc.info/?l=linux-kernel&m=93337278602211&w=2) diff --git a/Documentation/translations/zh_CN/mm/balance.rst b/Documentation/translations/zh_CN/mm/balance.rst new file mode 100644 index 000000000000..6fd79209c307 --- /dev/null +++ b/Documentation/translations/zh_CN/mm/balance.rst @@ -0,0 +1,81 @@ +.. include:: ../disclaimer-zh_CN.rst + +:Original: Documentation/mm/balance.rst + +:翻译: + + 司延腾 Yanteng Si <siyanteng@loongson.cn> + +:校译: + + +======== +内存平衡 +======== + +2000年1月开始，作者：Kanoj Sarcar <kanoj@sgi.com> + +对于 !__GFP_HIGH 和 !__GFP_KSWAPD_RECLAIM 以及非 __GFP_IO 的分配，需要进行 +内存平衡。 + +调用者避免回收的第一个原因是调用者由于持有自旋锁或处于中断环境中而无法睡眠。第二个 +原因可能是，调用者愿意在不产生页面回收开销的情况下分配失败。这可能发生在有0阶回退 +选项的机会主义高阶分配请求中。在这种情况下，调用者可能也希望避免唤醒kswapd。 + +__GFP_IO分配请求是为了防止文件系统死锁。 + +在没有非睡眠分配请求的情况下，做平衡似乎是有害的。页面回收可以被懒散地启动，也就是 +说，只有在需要的时候（也就是区域的空闲内存为0），而不是让它成为一个主动的过程。 + +也就是说，内核应该尝试从直接映射池中满足对直接映射页的请求，而不是回退到dma池中， +这样就可以保持dma池为dma请求（不管是不是原子的）所填充。类似的争论也适用于高内存 +和直接映射的页面。相反，如果有很多空闲的dma页，最好是通过从dma池中分配一个来满足 +常规的内存请求，而不是产生常规区域平衡的开销。 + +在2.2中，只有当空闲页总数低于总内存的1/64时，才会启动内存平衡/页面回收。如果dma +和常规内存的比例合适，即使dma区完全空了，也很可能不会进行平衡。2.2已经在不同内存 +大小的生产机器上运行，即使有这个问题存在，似乎也做得不错。在2.3中，由于HIGHMEM的 +存在，这个问题变得更加严重。 + +在2.3中，区域平衡可以用两种方式之一来完成：根据区域的大小（可能是低级区域的大小）， +我们可以在初始化阶段决定在平衡任何区域时应该争取多少空闲页。好的方面是，在平衡的时 +候，我们不需要看低级区的大小，坏的方面是，我们可能会因为忽略低级区可能较低的使用率 +而做过于频繁的平衡。另外，只要对分配程序稍作修改，就有可能将memclass()宏简化为一 +个简单的等式。 + +另一个可能的解决方案是，我们只在一个区 **和** 其所有低级区的空闲内存低于该区及其 +低级区总内存的1/64时进行平衡。这就解决了2.2的平衡问题，并尽可能地保持了与2.2行为 +的接近。另外，平衡算法在各种架构上的工作方式也是一样的，这些架构有不同数量和类型的 +内存区。如果我们想变得更花哨一点，我们可以在未来为不同区域的自由页面分配不同的权重。 + +请注意，如果普通区的大小与dma区相比是巨大的，那么在决定是否平衡普通区的时候，考虑 +空闲的dma页就变得不那么重要了。那么第一个解决方案就变得更有吸引力。 + +所附的补丁实现了第二个解决方案。它还 “修复”了两个问题：首先，在低内存条件下，kswapd +被唤醒，就像2.2中的非睡眠分配。第二，HIGHMEM区也被平衡了，以便给replace_with_highmem() +一个争取获得HIGHMEM页的机会，同时确保HIGHMEM分配不会落回普通区。这也确保了HIGHMEM +页不会被泄露（例如，在一个HIGHMEM页在交换缓存中但没有被任何人使用的情况下）。 + +kswapd还需要知道它应该平衡哪些区。kswapd主要是在无法进行平衡的情况下需要的，可能 +是因为所有的分配请求都来自中断上下文，而所有的进程上下文都在睡眠。对于2.3， +kswapd并不真正需要平衡高内存区，因为中断上下文并不请求高内存页。kswapd看zone +结构体中的zone_wake_kswapd字段来决定一个区是否需要平衡。 + +如果从进程内存和shm中偷取页面可以减轻该页面节点中任何区的内存压力，而该区的内存压力 +已经低于其水位，则会进行偷取。 + +watemark[WMARK_MIN/WMARK_LOW/WMARK_HIGH]/low_on_memory/zone_wake_kswapd： +这些是每个区的字段，用于确定一个区何时需要平衡。当页面数低于水位[WMARK_MIN]时， +hysteric 的字段low_on_memory被设置。这个字段会一直被设置，直到空闲页数变成水位 +[WMARK_HIGH]。当low_on_memory被设置时，页面分配请求将尝试释放该区域的一些页面（如果 +请求中设置了GFP_WAIT）。与此相反的是，决定唤醒kswapd以释放一些区的页。这个决定不是基于 +hysteresis 的，而是当空闲页的数量低于watermark[WMARK_LOW]时就会进行；在这种情况下， +zone_wake_kswapd也被设置。 + + +我所听到的（超棒的）想法： + +1. 动态经历应该影响平衡：可以跟踪一个区的失败请求的数量，并反馈到平衡方案中（jalvo@mbay.net）。 + +2. 实现一个类似于replace_with_highmem()的replace_with_regular()，以保留dma页面。 + (lkd@tantalophile.demon.co.uk) diff --git a/Documentation/translations/zh_CN/mm/damon/api.rst b/Documentation/translations/zh_CN/mm/damon/api.rst new file mode 100644 index 000000000000..5593a83c86bc --- /dev/null +++ b/Documentation/translations/zh_CN/mm/damon/api.rst @@ -0,0 +1,32 @@ +.. SPDX-License-Identifier: GPL-2.0 + +:Original: Documentation/mm/damon/api.rst + +:翻译: + + 司延腾 Yanteng Si <siyanteng@loongson.cn> + +:校译: + + +======= +API参考 +======= + +内核空间的程序可以使用下面的API来使用DAMON的每个功能。你所需要做的就是引用 ``damon.h`` ， +它位于源代码树的include/linux/。 + +结构体 +====== + +该API在以下内核代码中: + +include/linux/damon.h + + +函数 +==== + +该API在以下内核代码中: + +mm/damon/core.c diff --git a/Documentation/translations/zh_CN/mm/damon/design.rst b/Documentation/translations/zh_CN/mm/damon/design.rst new file mode 100644 index 000000000000..16e3db34a7dd --- /dev/null +++ b/Documentation/translations/zh_CN/mm/damon/design.rst @@ -0,0 +1,140 @@ +.. SPDX-License-Identifier: GPL-2.0 + +:Original: Documentation/mm/damon/design.rst + +:翻译: + + 司延腾 Yanteng Si <siyanteng@loongson.cn> + +:校译: + + +==== +设计 +==== + +可配置的层 +========== + +DAMON提供了数据访问监控功能，同时使其准确性和开销可控。基本的访问监控需要依赖于目标地址空间 +并为之优化的基元。另一方面，作为DAMON的核心，准确性和开销的权衡机制是在纯逻辑空间中。DAMON +将这两部分分离在不同的层中，并定义了它的接口，以允许各种低层次的基元实现与核心逻辑的配置。 + +由于这种分离的设计和可配置的接口，用户可以通过配置核心逻辑和适当的低级基元实现来扩展DAMON的 +任何地址空间。如果没有提供合适的，用户可以自己实现基元。 + +例如，物理内存、虚拟内存、交换空间、那些特定的进程、NUMA节点、文件和支持的内存设备将被支持。 +另外，如果某些架构或设备支持特殊的优化访问检查基元，这些基元将很容易被配置。 + + +特定地址空间基元的参考实现 +========================== + +基本访问监测的低级基元被定义为两部分。: + +1. 确定地址空间的监测目标地址范围 +2. 目标空间中特定地址范围的访问检查。 + +DAMON目前为物理和虚拟地址空间提供了基元的实现。下面两个小节描述了这些工作的方式。 + + +基于VMA的目标地址范围构造 +------------------------- + +这仅仅是针对虚拟地址空间基元的实现。对于物理地址空间，只是要求用户手动设置监控目标地址范围。 + +在进程的超级巨大的虚拟地址空间中，只有小部分被映射到物理内存并被访问。因此，跟踪未映射的地 +址区域只是一种浪费。然而，由于DAMON可以使用自适应区域调整机制来处理一定程度的噪声，所以严 +格来说，跟踪每一个映射并不是必须的，但在某些情况下甚至会产生很高的开销。也就是说，监测目标 +内部过于巨大的未映射区域应该被移除，以不占用自适应机制的时间。 + +出于这个原因，这个实现将复杂的映射转换为三个不同的区域，覆盖地址空间的每个映射区域。这三个 +区域之间的两个空隙是给定地址空间中两个最大的未映射区域。这两个最大的未映射区域是堆和最上面 +的mmap()区域之间的间隙，以及在大多数情况下最下面的mmap()区域和堆之间的间隙。因为这些间隙 +在通常的地址空间中是异常巨大的，排除这些间隙就足以做出合理的权衡。下面详细说明了这一点:: + + <heap> + <BIG UNMAPPED REGION 1> + <uppermost mmap()-ed region> + (small mmap()-ed regions and munmap()-ed regions) + <lowermost mmap()-ed region> + <BIG UNMAPPED REGION 2> + <stack> + + +基于PTE访问位的访问检查 +----------------------- + +物理和虚拟地址空间的实现都使用PTE Accessed-bit进行基本访问检查。唯一的区别在于从地址中 +找到相关的PTE访问位的方式。虚拟地址的实现是为该地址的目标任务查找页表，而物理地址的实现则 +是查找与该地址有映射关系的每一个页表。通过这种方式，实现者找到并清除下一个采样目标地址的位， +并检查该位是否在一个采样周期后再次设置。这可能会干扰其他使用访问位的内核子系统，即空闲页跟 +踪和回收逻辑。为了避免这种干扰，DAMON使其与空闲页面跟踪相互排斥，并使用 ``PG_idle`` 和 +``PG_young`` 页面标志来解决与回收逻辑的冲突，就像空闲页面跟踪那样。 + + +独立于地址空间的核心机制 +======================== + +下面四个部分分别描述了DAMON的核心机制和五个监测属性，即 ``采样间隔`` 、 ``聚集间隔`` 、 +``更新间隔`` 、 ``最小区域数`` 和 ``最大区域数`` 。 + + +访问频率监测 +------------ + +DAMON的输出显示了在给定的时间内哪些页面的访问频率是多少。访问频率的分辨率是通过设置 +``采样间隔`` 和 ``聚集间隔`` 来控制的。详细地说，DAMON检查每个 ``采样间隔`` 对每 +个页面的访问，并将结果汇总。换句话说，计算每个页面的访问次数。在每个 ``聚合间隔`` 过 +去后，DAMON调用先前由用户注册的回调函数，以便用户可以阅读聚合的结果，然后再清除这些结 +果。这可以用以下简单的伪代码来描述:: + + while monitoring_on: + for page in monitoring_target: + if accessed(page): + nr_accesses[page] += 1 + if time() % aggregation_interval == 0: + for callback in user_registered_callbacks: + callback(monitoring_target, nr_accesses) + for page in monitoring_target: + nr_accesses[page] = 0 + sleep(sampling interval) + +这种机制的监测开销将随着目标工作负载规模的增长而任意增加。 + + +基于区域的抽样调查 +------------------ + +为了避免开销的无限制增加，DAMON将假定具有相同访问频率的相邻页面归入一个区域。只要保持 +这个假设（一个区域内的页面具有相同的访问频率），该区域内就只需要检查一个页面。因此，对 +于每个 ``采样间隔`` ，DAMON在每个区域中随机挑选一个页面，等待一个 ``采样间隔`` ，检 +查该页面是否同时被访问，如果被访问则增加该区域的访问频率。因此，监测开销是可以通过设置 +区域的数量来控制的。DAMON允许用户设置最小和最大的区域数量来进行权衡。 + +然而，如果假设没有得到保证，这个方案就不能保持输出的质量。 + + +适应性区域调整 +-------------- + +即使最初的监测目标区域被很好地构建以满足假设（同一区域内的页面具有相似的访问频率），数 +据访问模式也会被动态地改变。这将导致监测质量下降。为了尽可能地保持假设，DAMON根据每个 +区域的访问频率自适应地进行合并和拆分。 + +对于每个 ``聚集区间`` ，它比较相邻区域的访问频率，如果频率差异较小，就合并这些区域。 +然后，在它报告并清除每个区域的聚合接入频率后，如果区域总数不超过用户指定的最大区域数， +它将每个区域拆分为两个或三个区域。 + +通过这种方式，DAMON提供了其最佳的质量和最小的开销，同时保持了用户为其权衡设定的界限。 + + +动态目标空间更新处理 +-------------------- + +监测目标地址范围可以动态改变。例如，虚拟内存可以动态地被映射和解映射。物理内存可以被 +热插拔。 + +由于在某些情况下变化可能相当频繁，DAMON允许监控操作检查动态变化，包括内存映射变化， +并仅在用户指定的时间间隔（ ``更新间隔`` ）中的每个时间段，将其应用于监控操作相关的 +数据结构，如抽象的监控目标内存区。
\ No newline at end of file diff --git a/Documentation/translations/zh_CN/mm/damon/faq.rst b/Documentation/translations/zh_CN/mm/damon/faq.rst new file mode 100644 index 000000000000..de4be417494a --- /dev/null +++ b/Documentation/translations/zh_CN/mm/damon/faq.rst @@ -0,0 +1,48 @@ +.. SPDX-License-Identifier: GPL-2.0 + +:Original: Documentation/mm/damon/faq.rst + +:翻译: + + 司延腾 Yanteng Si <siyanteng@loongson.cn> + +:校译: + + +======== +常见问题 +======== + +为什么是一个新的子系统，而不是扩展perf或其他用户空间工具？ +========================================================== + +首先，因为它需要尽可能的轻量级，以便可以在线使用，所以应该避免任何不必要的开销，如内核-用户 +空间的上下文切换成本。第二，DAMON的目标是被包括内核在内的其他程序所使用。因此，对特定工具 +（如perf）的依赖性是不可取的。这就是DAMON在内核空间实现的两个最大的原因。 + + +“闲置页面跟踪” 或 “perf mem” 可以替代DAMON吗？ +============================================== + +闲置页跟踪是物理地址空间访问检查的一个低层次的原始方法。“perf mem”也是类似的，尽管它可以 +使用采样来减少开销。另一方面，DAMON是一个更高层次的框架，用于监控各种地址空间。它专注于内 +存管理优化，并提供复杂的精度/开销处理机制。因此，“空闲页面跟踪” 和 “perf mem” 可以提供 +DAMON输出的一个子集，但不能替代DAMON。 + + +DAMON是否只支持虚拟内存？ +========================= + +不，DAMON的核心是独立于地址空间的。用户可以在DAMON核心上实现和配置特定地址空间的低级原始 +部分，包括监测目标区域的构造和实际的访问检查。通过这种方式，DAMON用户可以用任何访问检查技 +术来监测任何地址空间。 + +尽管如此，DAMON默认为虚拟内存和物理内存提供了基于vma/rmap跟踪和PTE访问位检查的地址空间 +相关功能的实现，以供参考和方便使用。 + + +我可以简单地监测页面的粒度吗？ +============================== + +是的，你可以通过设置 ``min_nr_regions`` 属性高于工作集大小除以页面大小的值来实现。 +因为监视目标区域的大小被强制为 ``>=page size`` ，所以区域分割不会产生任何影响。 diff --git a/Documentation/translations/zh_CN/mm/damon/index.rst b/Documentation/translations/zh_CN/mm/damon/index.rst new file mode 100644 index 000000000000..b03bf307204f --- /dev/null +++ b/Documentation/translations/zh_CN/mm/damon/index.rst @@ -0,0 +1,32 @@ +.. SPDX-License-Identifier: GPL-2.0 + +:Original: Documentation/mm/damon/index.rst + +:翻译: + + 司延腾 Yanteng Si <siyanteng@loongson.cn> + +:校译: + + +========================== +DAMON:数据访问监视器 +========================== + +DAMON是Linux内核的一个数据访问监控框架子系统。DAMON的核心机制使其成为 +（该核心机制详见(Documentation/translations/zh_CN/mm/damon/design.rst)） + + - *准确度* （监测输出对DRAM级别的内存管理足够有用；但可能不适合CPU Cache级别）， + - *轻量级* （监控开销低到可以在线应用），以及 + - *可扩展* （无论目标工作负载的大小，开销的上限值都在恒定范围内）。 + +因此，利用这个框架，内核的内存管理机制可以做出高级决策。会导致高数据访问监控开销的实 +验性内存管理优化工作可以再次进行。同时，在用户空间，有一些特殊工作负载的用户可以编写 +个性化的应用程序，以便更好地了解和优化他们的工作负载和系统。 + +.. toctree:: + :maxdepth: 2 + + faq + design + api diff --git a/Documentation/translations/zh_CN/mm/free_page_reporting.rst b/Documentation/translations/zh_CN/mm/free_page_reporting.rst new file mode 100644 index 000000000000..5bfd58014c94 --- /dev/null +++ b/Documentation/translations/zh_CN/mm/free_page_reporting.rst @@ -0,0 +1,38 @@ +.. include:: ../disclaimer-zh_CN.rst + +:Original: Documentation/mm/free_page_reporting.rst + +:翻译: + + 司延腾 Yanteng Si <siyanteng@loongson.cn> + +:校译: + +========== +空闲页报告 +========== + +空闲页报告是一个API，设备可以通过它来注册接收系统当前未使用的页面列表。这在虚拟 +化的情况下是很有用的，客户机能够使用这些数据来通知管理器它不再使用内存中的某些页 +面。 + +对于驱动，通常是气球驱动要使用这个功能，它将分配和初始化一个page_reporting_dev_info +结构体。它要填充的结构体中的字段是用于处理散点列表的 "report" 函数指针。它还必 +须保证每次调用该函数时能处理至少相当于PAGE_REPORTING_CAPACITY的散点列表条目。 +假设没有其他页面报告设备已经注册， 对page_reporting_register的调用将向报告框 +架注册页面报告接口。 + +一旦注册，页面报告API将开始向驱动报告成批的页面。API将在接口被注册后2秒开始报告 +页面，并在任何足够高的页面被释放之后2秒继续报告。 + +报告的页面将被存储在传递给报告函数的散列表中，最后一个条目的结束位被设置在条目 +nent-1中。 当页面被报告函数处理时，分配器将无法访问它们。一旦报告函数完成，这些 +页将被返回到它们所获得的自由区域。 + +在移除使用空闲页报告的驱动之前，有必要调用page_reporting_unregister，以移除 +目前被空闲页报告使用的page_reporting_dev_info结构体。这样做将阻止进一步的报 +告通过该接口发出。如果另一个驱动或同一驱动被注册，它就有可能恢复前一个驱动在报告 +空闲页方面的工作。 + + +Alexander Duyck, 2019年12月04日 diff --git a/Documentation/translations/zh_CN/mm/frontswap.rst b/Documentation/translations/zh_CN/mm/frontswap.rst new file mode 100644 index 000000000000..434975390b48 --- /dev/null +++ b/Documentation/translations/zh_CN/mm/frontswap.rst @@ -0,0 +1,196 @@ +:Original: Documentation/mm/frontswap.rst + +:翻译: + + 司延腾 Yanteng Si <siyanteng@loongson.cn> + +:校译: + +========= +Frontswap +========= + +Frontswap为交换页提供了一个 “transcendent memory” 的接口。在一些环境中，由 +于交换页被保存在RAM（或类似RAM的设备）中，而不是交换磁盘，因此可以获得巨大的性能 +节省（提高）。 + +.. _Transcendent memory in a nutshell: https://lwn.net/Articles/454795/ + +Frontswap之所以这么命名，是因为它可以被认为是与swap设备的“back”存储相反。存 +储器被认为是一个同步并发安全的面向页面的“伪RAM设备”，符合transcendent memory +（如Xen的“tmem”，或内核内压缩内存，又称“zcache”，或未来的类似RAM的设备）的要 +求；这个伪RAM设备不能被内核直接访问或寻址，其大小未知且可能随时间变化。驱动程序通过 +调用frontswap_register_ops将自己与frontswap链接起来，以适当地设置frontswap_ops +的功能，它提供的功能必须符合某些策略，如下所示: + +一个 “init” 将设备准备好接收与指定的交换设备编号（又称“类型”）相关的frontswap +交换页。一个 “store” 将把该页复制到transcendent memory，并与该页的类型和偏移 +量相关联。一个 “load” 将把该页，如果找到的话，从transcendent memory复制到内核 +内存，但不会从transcendent memory中删除该页。一个 “invalidate_page” 将从 +transcendent memory中删除该页，一个 “invalidate_area” 将删除所有与交换类型 +相关的页（例如，像swapoff）并通知 “device” 拒绝进一步存储该交换类型。 + +一旦一个页面被成功存储，在该页面上的匹配加载通常会成功。因此，当内核发现自己处于需 +要交换页面的情况时，它首先尝试使用frontswap。如果存储的结果是成功的，那么数据就已 +经成功的保存到了transcendent memory中，并且避免了磁盘写入，如果后来再读回数据， +也避免了磁盘读取。如果存储返回失败，transcendent memory已经拒绝了该数据，且该页 +可以像往常一样被写入交换空间。 + +请注意，如果一个页面被存储，而该页面已经存在于transcendent memory中（一个 “重复” +的存储），要么存储成功，数据被覆盖，要么存储失败，该页面被废止。这确保了旧的数据永远 +不会从frontswap中获得。 + +如果配置正确，对frontswap的监控是通过 `/sys/kernel/debug/frontswap` 目录下的 +debugfs完成的。frontswap的有效性可以通过以下方式测量（在所有交换设备中）: + +``failed_stores`` + 有多少次存储的尝试是失败的 + +``loads`` + 尝试了多少次加载（应该全部成功） + +``succ_stores`` + 有多少次存储的尝试是成功的 + +``invalidates`` + 尝试了多少次作废 + +后台实现可以提供额外的指标。 + +经常问到的问题 +============== + +* 价值在哪里? + +当一个工作负载开始交换时，性能就会下降。Frontswap通过提供一个干净的、动态的接口来 +读取和写入交换页到 “transcendent memory”，从而大大增加了许多这样的工作负载的性 +能，否则内核是无法直接寻址的。当数据被转换为不同的形式和大小（比如压缩）或者被秘密 +移动（对于一些类似RAM的设备来说，这可能对写平衡很有用）时，这个接口是理想的。交换 +页（和被驱逐的页面缓存页）是这种比RAM慢但比磁盘快得多的“伪RAM设备”的一大用途。 + +Frontswap对内核的影响相当小，为各种系统配置中更动态、更灵活的RAM利用提供了巨大的 +灵活性： + +在单一内核的情况下，又称“zcache”，页面被压缩并存储在本地内存中，从而增加了可以安 +全保存在RAM中的匿名页面总数。Zcache本质上是用压缩/解压缩的CPU周期换取更好的内存利 +用率。Benchmarks测试显示，当内存压力较低时，几乎没有影响，而在高内存压力下的一些 +工作负载上，则有明显的性能改善（25%以上）。 + +“RAMster” 在zcache的基础上增加了对集群系统的 “peer-to-peer” transcendent memory +的支持。Frontswap页面像zcache一样被本地压缩，但随后被“remotified” 到另一个系 +统的RAM。这使得RAM可以根据需要动态地来回负载平衡，也就是说，当系统A超载时，它可以 +交换到系统B，反之亦然。RAMster也可以被配置成一个内存服务器，因此集群中的许多服务器 +可以根据需要动态地交换到配置有大量内存的单一服务器上......而不需要预先配置每个客户 +有多少内存可用 + +在虚拟情况下，虚拟化的全部意义在于统计地将物理资源在多个虚拟机的不同需求之间进行复 +用。对于RAM来说，这真的很难做到，而且在不改变内核的情况下，要做好这一点的努力基本上 +是失败的（除了一些广为人知的特殊情况下的工作负载）。具体来说，Xen Transcendent Memory +后端允许管理器拥有的RAM “fallow”，不仅可以在多个虚拟机之间进行“time-shared”， +而且页面可以被压缩和重复利用，以优化RAM的利用率。当客户操作系统被诱导交出未充分利用 +的RAM时（如 “selfballooning”），突然出现的意外内存压力可能会导致交换；frontswap +允许这些页面被交换到管理器RAM中或从管理器RAM中交换（如果整体主机系统内存条件允许）， +从而减轻计划外交换可能带来的可怕的性能影响。 + +一个KVM的实现正在进行中，并且已经被RFC'ed到lkml。而且，利用frontswap，对NVM作为 +内存扩展技术的调查也在进行中。 + +* 当然，在某些情况下可能有性能上的优势，但frontswap的空间/时间开销是多少？ + +如果 CONFIG_FRONTSWAP 被禁用，每个 frontswap 钩子都会编译成空，唯一的开销是每 +个 swapon'ed swap 设备的几个额外字节。如果 CONFIG_FRONTSWAP 被启用，但没有 +frontswap的 “backend” 寄存器，每读或写一个交换页就会有一个额外的全局变量，而不 +是零。如果 CONFIG_FRONTSWAP 被启用，并且有一个frontswap的backend寄存器，并且 +后端每次 “store” 请求都失败（即尽管声称可能，但没有提供内存），CPU 的开销仍然可以 +忽略不计 - 因为每次frontswap失败都是在交换页写到磁盘之前，系统很可能是 I/O 绑定 +的，无论如何使用一小部分的 CPU 都是不相关的。 + +至于空间，如果CONFIG_FRONTSWAP被启用，并且有一个frontswap的backend注册，那么 +每个交换设备的每个交换页都会被分配一个比特。这是在内核已经为每个交换设备的每个交换 +页分配的8位（在2.6.34之前是16位）上增加的。(Hugh Dickins观察到，frontswap可能 +会偷取现有的8个比特，但是我们以后再来担心这个小的优化问题)。对于标准的4K页面大小的 +非常大的交换盘（这很罕见），这是每32GB交换盘1MB开销。 + +当交换页存储在transcendent memory中而不是写到磁盘上时，有一个副作用，即这可能会 +产生更多的内存压力，有可能超过其他的优点。一个backend，比如zcache，必须实现策略 +来仔细（但动态地）管理内存限制，以确保这种情况不会发生。 + +* 好吧，那就用内核骇客能理解的术语来快速概述一下这个frontswap补丁的作用如何？ + +我们假设在内核初始化过程中，一个frontswap 的 “backend” 已经注册了；这个注册表 +明这个frontswap 的 “backend” 可以访问一些不被内核直接访问的“内存”。它到底提 +供了多少内存是完全动态和随机的。 + +每当一个交换设备被交换时，就会调用frontswap_init()，把交换设备的编号（又称“类 +型”）作为一个参数传给它。这就通知了frontswap，以期待 “store” 与该号码相关的交 +换页的尝试。 + +每当交换子系统准备将一个页面写入交换设备时（参见swap_writepage()），就会调用 +frontswap_store。Frontswap与frontswap backend协商，如果backend说它没有空 +间，frontswap_store返回-1，内核就会照常把页换到交换设备上。注意，来自frontswap +backend的响应对内核来说是不可预测的；它可能选择从不接受一个页面，可能接受每九个 +页面，也可能接受每一个页面。但是如果backend确实接受了一个页面，那么这个页面的数 +据已经被复制并与类型和偏移量相关联了，而且backend保证了数据的持久性。在这种情况 +下，frontswap在交换设备的“frontswap_map” 中设置了一个位，对应于交换设备上的 +页面偏移量，否则它就会将数据写入该设备。 + +当交换子系统需要交换一个页面时（swap_readpage()），它首先调用frontswap_load()， +检查frontswap_map，看这个页面是否早先被frontswap backend接受。如果是，该页 +的数据就会从frontswap后端填充，换入就完成了。如果不是，正常的交换代码将被执行， +以便从真正的交换设备上获得这一页的数据。 + +所以每次frontswap backend接受一个页面时，交换设备的读取和（可能）交换设备的写 +入都被 “frontswap backend store” 和（可能）“frontswap backend loads” +所取代，这可能会快得多。 + +* frontswap不能被配置为一个 “特殊的” 交换设备，它的优先级要高于任何真正的交换 + 设备（例如像zswap，或者可能是swap-over-nbd/NFS）？ + +首先，现有的交换子系统不允许有任何种类的交换层次结构。也许它可以被重写以适应层次 +结构，但这将需要相当大的改变。即使它被重写，现有的交换子系统也使用了块I/O层，它 +假定交换设备是固定大小的，其中的任何页面都是可线性寻址的。Frontswap几乎没有触 +及现有的交换子系统，而是围绕着块I/O子系统的限制，提供了大量的灵活性和动态性。 + +例如，frontswap backend对任何交换页的接受是完全不可预测的。这对frontswap backend +的定义至关重要，因为它赋予了backend完全动态的决定权。在zcache中，人们无法预 +先知道一个页面的可压缩性如何。可压缩性 “差” 的页面会被拒绝，而 “差” 本身也可 +以根据当前的内存限制动态地定义。 + +此外，frontswap是完全同步的，而真正的交换设备，根据定义，是异步的，并且使用 +块I/O。块I/O层不仅是不必要的，而且可能进行 “优化”，这对面向RAM的设备来说是 +不合适的，包括将一些页面的写入延迟相当长的时间。同步是必须的，以确保后端的动 +态性，并避免棘手的竞争条件，这将不必要地大大增加frontswap和/或块I/O子系统的 +复杂性。也就是说，只有最初的 “store” 和 “load” 操作是需要同步的。一个独立 +的异步线程可以自由地操作由frontswap存储的页面。例如，RAMster中的 “remotification” +线程使用标准的异步内核套接字，将压缩的frontswap页面移动到远程机器。同样， +KVM的客户方实现可以进行客户内压缩，并使用 “batched” hypercalls。 + +在虚拟化环境中，动态性允许管理程序（或主机操作系统）做“intelligent overcommit”。 +例如，它可以选择只接受页面，直到主机交换可能即将发生，然后强迫客户机做他们 +自己的交换。 + +transcendent memory规格的frontswap有一个坏处。因为任何 “store” 都可 +能失败，所以必须在一个真正的交换设备上有一个真正的插槽来交换页面。因此， +frontswap必须作为每个交换设备的 “影子” 来实现，它有可能容纳交换设备可能 +容纳的每一个页面，也有可能根本不容纳任何页面。这意味着frontswap不能包含比 +swap设备总数更多的页面。例如，如果在某些安装上没有配置交换设备，frontswap +就没有用。无交换设备的便携式设备仍然可以使用frontswap，但是这种设备的 +backend必须配置某种 “ghost” 交换设备，并确保它永远不会被使用。 + + +* 为什么会有这种关于 “重复存储” 的奇怪定义？如果一个页面以前被成功地存储过， + 难道它不能总是被成功地覆盖吗？ + +几乎总是可以的，不，有时不能。考虑一个例子，数据被压缩了，原来的4K页面被压 +缩到了1K。现在，有人试图用不可压缩的数据覆盖该页，因此会占用整个4K。但是 +backend没有更多的空间了。在这种情况下，这个存储必须被拒绝。每当frontswap +拒绝一个会覆盖的存储时，它也必须使旧的数据作废，并确保它不再被访问。因为交 +换子系统会把新的数据写到读交换设备上，这是确保一致性的正确做法。 + +* 为什么frontswap补丁会创建新的头文件swapfile.h？ + +frontswap代码依赖于一些swap子系统内部的数据结构，这些数据结构多年来一直 +在静态和全局之间来回移动。这似乎是一个合理的妥协：将它们定义为全局，但在一 +个新的包含文件中声明它们，该文件不被包含swap.h的大量源文件所包含。 + +Dan Magenheimer，最后更新于2012年4月9日 diff --git a/Documentation/translations/zh_CN/mm/highmem.rst b/Documentation/translations/zh_CN/mm/highmem.rst new file mode 100644 index 000000000000..f74800a6d9a7 --- /dev/null +++ b/Documentation/translations/zh_CN/mm/highmem.rst @@ -0,0 +1,137 @@ +.. include:: ../disclaimer-zh_CN.rst + +:Original: Documentation/mm/highmem.rst + +:翻译: + + 司延腾 Yanteng Si <siyanteng@loongson.cn> + +:校译: + +========== +高内存处理 +========== + +作者: Peter Zijlstra <a.p.zijlstra@chello.nl> + +.. contents:: :local: + +高内存是什么？ +============== + +当物理内存的大小接近或超过虚拟内存的最大大小时，就会使用高内存（highmem）。在这一点上，内 +核不可能在任何时候都保持所有可用的物理内存的映射。这意味着内核需要开始使用它想访问的物理内 +存的临时映射。 + +没有被永久映射覆盖的那部分（物理）内存就是我们所说的 "高内存"。对于这个边界的确切位置，有 +各种架构上的限制。 + +例如，在i386架构中，我们选择将内核映射到每个进程的虚拟空间，这样我们就不必为内核的进入/退 +出付出全部的TLB作废代价。这意味着可用的虚拟内存空间（i386上为4GiB）必须在用户和内核空间之 +间进行划分。 + +使用这种方法的架构的传统分配方式是3:1，3GiB用于用户空间，顶部的1GiB用于内核空间。:: + + +--------+ 0xffffffff + | Kernel | + +--------+ 0xc0000000 + | | + | User | + | | + +--------+ 0x00000000 + +这意味着内核在任何时候最多可以映射1GiB的物理内存，但是由于我们需要虚拟地址空间来做其他事 +情--包括访问其余物理内存的临时映射--实际的直接映射通常会更少（通常在~896MiB左右）。 + +其他有mm上下文标签的TLB的架构可以有独立的内核和用户映射。然而，一些硬件（如一些ARM）在使 +用mm上下文标签时，其虚拟空间有限。 + + +临时虚拟映射 +============ + +内核包含几种创建临时映射的方法。下面的列表按照使用的优先顺序显示了它们。 + +* kmap_local_page()。这个函数是用来要求短期映射的。它可以从任何上下文（包括中断）中调用， + 但是映射只能在获取它们的上下文中使用。 + + 在可行的情况下，这个函数应该比其他所有的函数优先使用。 + + 这些映射是线程本地和CPU本地的，这意味着映射只能从这个线程中访问，并且当映射处于活动状 + 态时，该线程与CPU绑定。即使线程被抢占了（因为抢占永远不会被函数禁用），CPU也不能通过 + CPU-hotplug从系统中拔出，直到映射被处理掉。 + + 在本地的kmap区域中采取pagefaults是有效的，除非获取本地映射的上下文由于其他原因不允许 + 这样做。 + + kmap_local_page()总是返回一个有效的虚拟地址，并且假定kunmap_local()不会失败。 + + 嵌套kmap_local_page()和kmap_atomic()映射在一定程度上是允许的（最多到KMAP_TYPE_NR）， + 但是它们的调用必须严格排序，因为映射的实现是基于堆栈的。关于如何管理嵌套映射的细节， + 请参见kmap_local_page() kdocs（包含在 "函数 "部分）。 + +* kmap_atomic(). 这允许对单个页面进行非常短的时间映射。由于映射被限制在发布它的CPU上， + 它表现得很好，但发布的任务因此被要求留在该CPU上直到它完成，以免其他任务取代它的映射。 + + kmap_atomic()也可以被中断上下文使用，因为它不睡眠，调用者也可能在调用kunmap_atomic() + 后才睡眠。 + + 内核中对kmap_atomic()的每次调用都会创建一个不可抢占的段，并禁用缺页异常。这可能是 + 未预期延迟的来源之一。因此用户应该选择kmap_local_page()而不是kmap_atomic()。 + + 假设k[un]map_atomic()不会失败。 + +* kmap()。这应该被用来对单个页面进行短时间的映射，对抢占或迁移没有限制。它会带来开销， + 因为映射空间是受限制的，并且受到全局锁的保护，以实现同步。当不再需要映射时，必须用 + kunmap()释放该页被映射的地址。 + + 映射变化必须广播到所有CPU（核）上，kmap()还需要在kmap的池被回绕（TLB项用光了，需要从第 + 一项复用）时进行全局TLB无效化，当映射空间被完全利用时，它可能会阻塞，直到有一个可用的 + 槽出现。因此，kmap()只能从可抢占的上下文中调用。 + + 如果一个映射必须持续相对较长的时间，上述所有的工作都是必要的，但是内核中大部分的 + 高内存映射都是短暂的，而且只在一个地方使用。这意味着在这种情况下，kmap()的成本大 + 多被浪费了。kmap()并不是为长期映射而设计的，但是它已经朝着这个方向发展了，在较新 + 的代码中强烈不鼓励使用它，前面的函数集应该是首选。 + + 在64位系统中，调用kmap_local_page()、kmap_atomic()和kmap()没有实际作用，因为64位 + 地址空间足以永久映射所有物理内存页面。 + +* vmap()。这可以用来将多个物理页长期映射到一个连续的虚拟空间。它需要全局同步来解除 + 映射。 + +临时映射的成本 +============== + +创建临时映射的代价可能相当高。体系架构必须操作内核的页表、数据TLB和/或MMU的寄存器。 + +如果CONFIG_HIGHMEM没有被设置，那么内核会尝试用一点计算来创建映射，将页面结构地址转换成 +指向页面内容的指针，而不是去捣鼓映射。在这种情况下，解映射操作可能是一个空操作。 + +如果CONFIG_MMU没有被设置，那么就不可能有临时映射和高内存。在这种情况下，也将使用计算方法。 + + +i386 PAE +======== + +在某些情况下，i386 架构将允许你在 32 位机器上安装多达 64GiB 的内存。但这有一些后果: + +* Linux需要为系统中的每个页面建立一个页帧结构，而且页帧需要驻在永久映射中，这意味着： + +* 你最多可以有896M/sizeof(struct page)页帧；由于页结构体是32字节的，所以最终会有 + 112G的页；然而，内核需要在内存中存储更多的页帧...... + +* PAE使你的页表变大--这使系统变慢，因为更多的数据需要在TLB填充等方面被访问。一个好处 + 是，PAE有更多的PTE位，可以提供像NX和PAT这样的高级功能。 + +一般的建议是，你不要在32位机器上使用超过8GiB的空间--尽管更多的空间可能对你和你的工作 +量有用，但你几乎是靠你自己--不要指望内核开发者真的会很关心事情的进展情况。 + +函数 +==== + +该API在以下内核代码中: + +include/linux/highmem.h + +include/linux/highmem-internal.h diff --git a/Documentation/translations/zh_CN/mm/hmm.rst b/Documentation/translations/zh_CN/mm/hmm.rst new file mode 100644 index 000000000000..5024a8a15516 --- /dev/null +++ b/Documentation/translations/zh_CN/mm/hmm.rst @@ -0,0 +1,361 @@ +.. include:: ../disclaimer-zh_CN.rst + +:Original: Documentation/mm/hmm.rst + +:翻译: + + 司延腾 Yanteng Si <siyanteng@loongson.cn> + +:校译: + +================== +异构内存管理 (HMM) +================== + +提供基础设施和帮助程序以将非常规内存（设备内存，如板上 GPU 内存）集成到常规内核路径中，其 +基石是此类内存的专用struct page（请参阅本文档的第 5 至 7 节）。 + +HMM 还为 SVM（共享虚拟内存）提供了可选的帮助程序，即允许设备透明地访问与 CPU 一致的程序 +地址，这意味着 CPU 上的任何有效指针也是该设备的有效指针。这对于简化高级异构计算的使用变得 +必不可少，其中 GPU、DSP 或 FPGA 用于代表进程执行各种计算。 + +本文档分为以下部分：在第一部分中，我揭示了与使用特定于设备的内存分配器相关的问题。在第二 +部分中，我揭示了许多平台固有的硬件限制。第三部分概述了 HMM 设计。第四部分解释了 CPU 页 +表镜像的工作原理以及 HMM 在这种情况下的目的。第五部分处理内核中如何表示设备内存。最后， +最后一节介绍了一个新的迁移助手，它允许利用设备 DMA 引擎。 + +.. contents:: :local: + +使用特定于设备的内存分配器的问题 +================================ + +具有大量板载内存（几 GB）的设备（如 GPU）历来通过专用驱动程序特定 API 管理其内存。这会 +造成设备驱动程序分配和管理的内存与常规应用程序内存（私有匿名、共享内存或常规文件支持内存） +之间的隔断。从这里开始，我将把这个方面称为分割的地址空间。我使用共享地址空间来指代相反的情况： +即，设备可以透明地使用任何应用程序内存区域。 + +分割的地址空间的发生是因为设备只能访问通过设备特定 API 分配的内存。这意味着从设备的角度来 +看，程序中的所有内存对象并不平等，这使得依赖于广泛的库的大型程序变得复杂。 + +具体来说，这意味着想要利用像 GPU 这样的设备的代码需要在通用分配的内存（malloc、mmap +私有、mmap 共享）和通过设备驱动程序 API 分配的内存之间复制对象（这仍然以 mmap 结束， +但是是设备文件）。 + +对于平面数据集（数组、网格、图像……），这并不难实现，但对于复杂数据集（列表、树……）， +很难做到正确。复制一个复杂的数据集需要重新映射其每个元素之间的所有指针关系。这很容易出错， +而且由于数据集和地址的重复，程序更难调试。 + +分割地址空间也意味着库不能透明地使用它们从核心程序或另一个库中获得的数据，因此每个库可能 +不得不使用设备特定的内存分配器来重复其输入数据集。大型项目会因此受到影响，并因为各种内存 +拷贝而浪费资源。 + +复制每个库的API以接受每个设备特定分配器分配的内存作为输入或输出，并不是一个可行的选择。 +这将导致库入口点的组合爆炸。 + +最后，随着高级语言结构（在 C++ 中，当然也在其他语言中）的进步，编译器现在有可能在没有程 +序员干预的情况下利用 GPU 和其他设备。某些编译器识别的模式仅适用于共享地址空间。对所有 +其他模式，使用共享地址空间也更合理。 + + +I/O 总线、设备内存特性 +====================== + +由于一些限制，I/O 总线削弱了共享地址空间。大多数 I/O 总线只允许从设备到主内存的基本 +内存访问；甚至缓存一致性通常是可选的。从 CPU 访问设备内存甚至更加有限。通常情况下，它 +不是缓存一致的。 + +如果我们只考虑 PCIE 总线，那么设备可以访问主内存（通常通过 IOMMU）并与 CPU 缓存一 +致。但是，它只允许设备对主存储器进行一组有限的原子操作。这在另一个方向上更糟：CPU +只能访问有限范围的设备内存，而不能对其执行原子操作。因此，从内核的角度来看，设备内存不 +能被视为与常规内存等同。 + +另一个严重的因素是带宽有限（约 32GBytes/s，PCIE 4.0 和 16 通道）。这比最快的 GPU +内存 (1 TBytes/s) 慢 33 倍。最后一个限制是延迟。从设备访问主内存的延迟比设备访问自 +己的内存时高一个数量级。 + +一些平台正在开发新的 I/O 总线或对 PCIE 的添加/修改以解决其中一些限制 +（OpenCAPI、CCIX）。它们主要允许 CPU 和设备之间的双向缓存一致性，并允许架构支持的所 +有原子操作。遗憾的是，并非所有平台都遵循这一趋势，并且一些主要架构没有针对这些问题的硬 +件解决方案。 + +因此，为了使共享地址空间有意义，我们不仅必须允许设备访问任何内存，而且还必须允许任何内 +存在设备使用时迁移到设备内存（在迁移时阻止 CPU 访问）。 + + +共享地址空间和迁移 +================== + +HMM 打算提供两个主要功能。第一个是通过复制cpu页表到设备页表中来共享地址空间，因此对 +于进程地址空间中的任何有效主内存地址，相同的地址指向相同的物理内存。 + +为了实现这一点，HMM 提供了一组帮助程序来填充设备页表，同时跟踪 CPU 页表更新。设备页表 +更新不像 CPU 页表更新那么容易。要更新设备页表，您必须分配一个缓冲区（或使用预先分配的 +缓冲区池）并在其中写入 GPU 特定命令以执行更新（取消映射、缓存失效和刷新等）。这不能通 +过所有设备的通用代码来完成。因此，为什么HMM提供了帮助器，在把硬件的具体细节留给设备驱 +动程序的同时，把一切可以考虑的因素都考虑进去了。 + +HMM 提供的第二种机制是一种新的 ZONE_DEVICE 内存，它允许为设备内存的每个页面分配一个 +struct page。这些页面很特殊，因为 CPU 无法映射它们。然而，它们允许使用现有的迁移机 +制将主内存迁移到设备内存，从 CPU 的角度来看，一切看起来都像是换出到磁盘的页面。使用 +struct page可以与现有的 mm 机制进行最简单、最干净的集成。再次，HMM 仅提供帮助程序， +首先为设备内存热插拔新的 ZONE_DEVICE 内存，然后执行迁移。迁移内容和时间的策略决定留 +给设备驱动程序。 + +请注意，任何 CPU 对设备页面的访问都会触发缺页异常并迁移回主内存。例如，当支持给定CPU +地址 A 的页面从主内存页面迁移到设备页面时，对地址 A 的任何 CPU 访问都会触发缺页异常 +并启动向主内存的迁移。 + +凭借这两个特性，HMM 不仅允许设备镜像进程地址空间并保持 CPU 和设备页表同步，而且还通 +过迁移设备正在使用的数据集部分来利用设备内存。 + + +地址空间镜像实现和API +===================== + +地址空间镜像的主要目标是允许将一定范围的 CPU 页表复制到一个设备页表中；HMM 有助于 +保持两者同步。想要镜像进程地址空间的设备驱动程序必须从注册 mmu_interval_notifier +开始:: + + int mmu_interval_notifier_insert(struct mmu_interval_notifier *interval_sub, + struct mm_struct *mm, unsigned long start, + unsigned long length, + const struct mmu_interval_notifier_ops *ops); + +在 ops->invalidate() 回调期间，设备驱动程序必须对范围执行更新操作（将范围标记为只 +读，或完全取消映射等）。设备必须在驱动程序回调返回之前完成更新。 + +当设备驱动程序想要填充一个虚拟地址范围时，它可以使用:: + + int hmm_range_fault(struct hmm_range *range); + +如果请求写访问，它将在丢失或只读条目上触发缺页异常（见下文）。缺页异常使用通用的 mm 缺 +页异常代码路径，就像 CPU 缺页异常一样。 + +这两个函数都将 CPU 页表条目复制到它们的 pfns 数组参数中。该数组中的每个条目对应于虚拟 +范围中的一个地址。HMM 提供了一组标志来帮助驱动程序识别特殊的 CPU 页表项。 + +在 sync_cpu_device_pagetables() 回调中锁定是驱动程序必须尊重的最重要的方面，以保 +持事物正确同步。使用模式是:: + + int driver_populate_range(...) + { + struct hmm_range range; + ... + + range.notifier = &interval_sub; + range.start = ...; + range.end = ...; + range.hmm_pfns = ...; + + if (!mmget_not_zero(interval_sub->notifier.mm)) + return -EFAULT; + + again: + range.notifier_seq = mmu_interval_read_begin(&interval_sub); + mmap_read_lock(mm); + ret = hmm_range_fault(&range); + if (ret) { + mmap_read_unlock(mm); + if (ret == -EBUSY) + goto again; + return ret; + } + mmap_read_unlock(mm); + + take_lock(driver->update); + if (mmu_interval_read_retry(&ni, range.notifier_seq) { + release_lock(driver->update); + goto again; + } + + /* Use pfns array content to update device page table, + * under the update lock */ + + release_lock(driver->update); + return 0; + } + +driver->update 锁与驱动程序在其 invalidate() 回调中使用的锁相同。该锁必须在调用 +mmu_interval_read_retry() 之前保持，以避免与并发 CPU 页表更新发生任何竞争。 + +利用 default_flags 和 pfn_flags_mask +==================================== + +hmm_range 结构有 2 个字段，default_flags 和 pfn_flags_mask，它们指定整个范围 +的故障或快照策略，而不必为 pfns 数组中的每个条目设置它们。 + +例如，如果设备驱动程序需要至少具有读取权限的范围的页面，它会设置:: + + range->default_flags = HMM_PFN_REQ_FAULT; + range->pfn_flags_mask = 0; + +并如上所述调用 hmm_range_fault()。这将填充至少具有读取权限的范围内的所有页面。 + +现在假设驱动程序想要做同样的事情，除了它想要拥有写权限的范围内的一页。现在驱动程序设 +置:: + + range->default_flags = HMM_PFN_REQ_FAULT; + range->pfn_flags_mask = HMM_PFN_REQ_WRITE; + range->pfns[index_of_write] = HMM_PFN_REQ_WRITE; + +有了这个，HMM 将在至少读取（即有效）的所有页面中异常，并且对于地址 +== range->start + (index_of_write << PAGE_SHIFT) 它将异常写入权限，即，如果 +CPU pte 没有设置写权限，那么HMM将调用handle_mm_fault()。 + +hmm_range_fault 完成后，标志位被设置为页表的当前状态，即 HMM_PFN_VALID | 如果页 +面可写，将设置 HMM_PFN_WRITE。 + + +从核心内核的角度表示和管理设备内存 +================================== + +尝试了几种不同的设计来支持设备内存。第一个使用特定于设备的数据结构来保存有关迁移内存 +的信息，HMM 将自身挂接到 mm 代码的各个位置，以处理对设备内存支持的地址的任何访问。 +事实证明，这最终复制了 struct page 的大部分字段，并且还需要更新许多内核代码路径才 +能理解这种新的内存类型。 + +大多数内核代码路径从不尝试访问页面后面的内存，而只关心struct page的内容。正因为如此， +HMM 切换到直接使用 struct page 用于设备内存，这使得大多数内核代码路径不知道差异。 +我们只需要确保没有人试图从 CPU 端映射这些页面。 + +移入和移出设备内存 +================== + +由于 CPU 无法直接访问设备内存，因此设备驱动程序必须使用硬件 DMA 或设备特定的加载/存 +储指令来迁移数据。migrate_vma_setup()、migrate_vma_pages() 和 +migrate_vma_finalize() 函数旨在使驱动程序更易于编写并集中跨驱动程序的通用代码。 + +在将页面迁移到设备私有内存之前，需要创建特殊的设备私有 ``struct page`` 。这些将用 +作特殊的“交换”页表条目，以便 CPU 进程在尝试访问已迁移到设备专用内存的页面时会发生异常。 + +这些可以通过以下方式分配和释放:: + + struct resource *res; + struct dev_pagemap pagemap; + + res = request_free_mem_region(&iomem_resource, /* number of bytes */, + "name of driver resource"); + pagemap.type = MEMORY_DEVICE_PRIVATE; + pagemap.range.start = res->start; + pagemap.range.end = res->end; + pagemap.nr_range = 1; + pagemap.ops = &device_devmem_ops; + memremap_pages(&pagemap, numa_node_id()); + + memunmap_pages(&pagemap); + release_mem_region(pagemap.range.start, range_len(&pagemap.range)); + +还有devm_request_free_mem_region(), devm_memremap_pages(), +devm_memunmap_pages() 和 devm_release_mem_region() 当资源可以绑定到 ``struct device``. + +整体迁移步骤类似于在系统内存中迁移 NUMA 页面(see :ref:`Page migration <page_migration>`) ， +但这些步骤分为设备驱动程序特定代码和共享公共代码: + +1. ``mmap_read_lock()`` + + 设备驱动程序必须将 ``struct vm_area_struct`` 传递给migrate_vma_setup()， + 因此需要在迁移期间保留 mmap_read_lock() 或 mmap_write_lock()。 + +2. ``migrate_vma_setup(struct migrate_vma *args)`` + + 设备驱动初始化了 ``struct migrate_vma`` 的字段，并将该指针传递给 + migrate_vma_setup()。``args->flags`` 字段是用来过滤哪些源页面应该被迁移。 + 例如，设置 ``MIGRATE_VMA_SELECT_SYSTEM`` 将只迁移系统内存，设置 + ``MIGRATE_VMA_SELECT_DEVICE_PRIVATE`` 将只迁移驻留在设备私有内存中的页 + 面。如果后者被设置， ``args->pgmap_owner`` 字段被用来识别驱动所拥有的设备 + 私有页。这就避免了试图迁移驻留在其他设备中的设备私有页。目前，只有匿名的私有VMA + 范围可以被迁移到系统内存和设备私有内存。 + + migrate_vma_setup()所做的第一步是用 ``mmu_notifier_invalidate_range_start()`` + 和 ``mmu_notifier_invalidate_range_end()`` 调用来遍历设备周围的页表，使 + 其他设备的MMU无效，以便在 ``args->src`` 数组中填写要迁移的PFN。 + ``invalidate_range_start()`` 回调传递给一个``struct mmu_notifier_range`` ， + 其 ``event`` 字段设置为MMU_NOTIFY_MIGRATE， ``owner`` 字段设置为传递给 + migrate_vma_setup()的 ``args->pgmap_owner`` 字段。这允许设备驱动跳过无 + 效化回调，只无效化那些实际正在迁移的设备私有MMU映射。这一点将在下一节详细解释。 + + + 在遍历页表时，一个 ``pte_none()`` 或 ``is_zero_pfn()`` 条目导致一个有效 + 的 “zero” PFN 存储在 ``args->src`` 阵列中。这让驱动分配设备私有内存并清 + 除它，而不是复制一个零页。到系统内存或设备私有结构页的有效PTE条目将被 + ``lock_page()``锁定，与LRU隔离（如果系统内存和设备私有页不在LRU上），从进 + 程中取消映射，并插入一个特殊的迁移PTE来代替原来的PTE。 migrate_vma_setup() + 还清除了 ``args->dst`` 数组。 + +3. 设备驱动程序分配目标页面并将源页面复制到目标页面。 + + 驱动程序检查每个 ``src`` 条目以查看该 ``MIGRATE_PFN_MIGRATE`` 位是否已 + 设置并跳过未迁移的条目。设备驱动程序还可以通过不填充页面的 ``dst`` 数组来选 + 择跳过页面迁移。 + + 然后，驱动程序分配一个设备私有 struct page 或一个系统内存页，用 ``lock_page()`` + 锁定该页，并将 ``dst`` 数组条目填入:: + + dst[i] = migrate_pfn(page_to_pfn(dpage)); + + 现在驱动程序知道这个页面正在被迁移，它可以使设备私有 MMU 映射无效并将设备私有 + 内存复制到系统内存或另一个设备私有页面。由于核心 Linux 内核会处理 CPU 页表失 + 效，因此设备驱动程序只需使其自己的 MMU 映射失效。 + + 驱动程序可以使用 ``migrate_pfn_to_page(src[i])`` 来获取源设备的 + ``struct page`` 面，并将源页面复制到目标设备上，如果指针为 ``NULL`` ，意 + 味着源页面没有被填充到系统内存中，则清除目标设备的私有内存。 + +4. ``migrate_vma_pages()`` + + 这一步是实际“提交”迁移的地方。 + + 如果源页是 ``pte_none()`` 或 ``is_zero_pfn()`` 页，这时新分配的页会被插 + 入到CPU的页表中。如果一个CPU线程在同一页面上发生异常，这可能会失败。然而，页 + 表被锁定，只有一个新页会被插入。如果它失去了竞争，设备驱动将看到 + ``MIGRATE_PFN_MIGRATE`` 位被清除。 + + 如果源页被锁定、隔离等，源 ``struct page`` 信息现在被复制到目标 + ``struct page`` ，最终完成CPU端的迁移。 + +5. 设备驱动为仍在迁移的页面更新设备MMU页表，回滚未迁移的页面。 + + 如果 ``src`` 条目仍然有 ``MIGRATE_PFN_MIGRATE`` 位被设置，设备驱动可以 + 更新设备MMU，如果 ``MIGRATE_PFN_WRITE`` 位被设置，则设置写启用位。 + +6. ``migrate_vma_finalize()`` + + 这一步用新页的页表项替换特殊的迁移页表项，并释放对源和目的 ``struct page`` + 的引用。 + +7. ``mmap_read_unlock()`` + + 现在可以释放锁了。 + +独占访问存储器 +============== + +一些设备具有诸如原子PTE位的功能，可以用来实现对系统内存的原子访问。为了支持对一 +个共享的虚拟内存页的原子操作，这样的设备需要对该页的访问是排他的，而不是来自CPU +的任何用户空间访问。 ``make_device_exclusive_range()`` 函数可以用来使一 +个内存范围不能从用户空间访问。 + +这将用特殊的交换条目替换给定范围内的所有页的映射。任何试图访问交换条目的行为都会 +导致一个异常，该异常会通过用原始映射替换该条目而得到恢复。驱动程序会被通知映射已 +经被MMU通知器改变，之后它将不再有对该页的独占访问。独占访问被保证持续到驱动程序 +放弃页面锁和页面引用为止，这时页面上的任何CPU异常都可以按所述进行。 + +内存 cgroup (memcg) 和 rss 统计 +=============================== + +目前，设备内存被视为 rss 计数器中的任何常规页面（如果设备页面用于匿名，则为匿名， +如果设备页面用于文件支持页面，则为文件，如果设备页面用于共享内存，则为 shmem）。 +这是为了保持现有应用程序的故意选择，这些应用程序可能在不知情的情况下开始使用设备 +内存，运行不受影响。 + +一个缺点是 OOM 杀手可能会杀死使用大量设备内存而不是大量常规系统内存的应用程序， +因此不会释放太多系统内存。在决定以不同方式计算设备内存之前，我们希望收集更多关 +于应用程序和系统在存在设备内存的情况下在内存压力下如何反应的实际经验。 + +对内存 cgroup 做出了相同的决定。设备内存页面根据相同的内存 cgroup 计算，常规 +页面将被计算在内。这确实简化了进出设备内存的迁移。这也意味着从设备内存迁移回常规 +内存不会失败，因为它会超过内存 cgroup 限制。一旦我们对设备内存的使用方式及其对 +内存资源控制的影响有了更多的了解，我们可能会在后面重新考虑这个选择。 + +请注意，设备内存永远不能由设备驱动程序或通过 GUP 固定，因此此类内存在进程退出时 +总是被释放的。或者在共享内存或文件支持内存的情况下，当删除最后一个引用时。 diff --git a/Documentation/translations/zh_CN/mm/hugetlbfs_reserv.rst b/Documentation/translations/zh_CN/mm/hugetlbfs_reserv.rst new file mode 100644 index 000000000000..752e5696cd47 --- /dev/null +++ b/Documentation/translations/zh_CN/mm/hugetlbfs_reserv.rst @@ -0,0 +1,436 @@ +.. include:: ../disclaimer-zh_CN.rst + +:Original: Documentation/mm/hugetlbfs_reserv.rst + +:翻译: + + 司延腾 Yanteng Si <siyanteng@loongson.cn> + +:校译: + +============== +Hugetlbfs 预留 +============== + +概述 +==== + +:ref:`hugetlbpage` 中描述的巨页通常是预先分配给应用程序使用的。如果VMA指 +示要使用巨页，这些巨页会在缺页异常时被实例化到任务的地址空间。如果在缺页异常 +时没有巨页存在，任务就会被发送一个SIGBUS，并经常不高兴地死去。在加入巨页支 +持后不久，人们决定，在mmap()时检测巨页的短缺情况会更好。这个想法是，如果 +没有足够的巨页来覆盖映射，mmap()将失败。这首先是在mmap()时在代码中做一个 +简单的检查，以确定是否有足够的空闲巨页来覆盖映射。就像内核中的大多数东西一 +样，代码随着时间的推移而不断发展。然而，基本的想法是在mmap()时 “预留” +巨页，以确保巨页可以用于该映射中的缺页异常。下面的描述试图描述在v4.10内核 +中是如何进行巨页预留处理的。 + + +读者 +==== +这个描述主要是针对正在修改hugetlbfs代码的内核开发者。 + + +数据结构 +======== + +resv_huge_pages + 这是一个全局的（per-hstate）预留的巨页的计数。预留的巨页只对预留它们的任 + 务可用。因此，一般可用的巨页的数量被计算为(``free_huge_pages - resv_huge_pages``)。 +Reserve Map + 预留映射由以下结构体描述:: + + struct resv_map { + struct kref refs; + spinlock_t lock; + struct list_head regions; + long adds_in_progress; + struct list_head region_cache; + long region_cache_count; + }; + + 系统中每个巨页映射都有一个预留映射。resv_map中的regions列表描述了映射中的 + 区域。一个区域被描述为:: + + struct file_region { + struct list_head link; + long from; + long to; + }; + + file_region结构体的 ‘from’ 和 ‘to’ 字段是进入映射的巨页索引。根据映射的类型，在 + reserv_map 中的一个区域可能表示该范围存在预留，或预留不存在。 +Flags for MAP_PRIVATE Reservations + 这些被存储在预留的映射指针的底部。 + + ``#define HPAGE_RESV_OWNER (1UL << 0)`` + 表示该任务是与该映射相关的预留的所有者。 + ``#define HPAGE_RESV_UNMAPPED (1UL << 1)`` + 表示最初映射此范围（并创建储备）的任务由于COW失败而从该任务（子任务）中取消映 + 射了一个页面。 +Page Flags + PagePrivate页面标志是用来指示在释放巨页时必须恢复巨页的预留。更多细节将在 + “释放巨页” 一节中讨论。 + + +预留映射位置（私有或共享） +========================== + +一个巨页映射或段要么是私有的，要么是共享的。如果是私有的，它通常只对一个地址空间 +（任务）可用。如果是共享的，它可以被映射到多个地址空间（任务）。对于这两种类型的映射， +预留映射的位置和语义是明显不同的。位置的差异是： + +- 对于私有映射，预留映射挂在VMA结构体上。具体来说，就是vma->vm_private_data。这个保 + 留映射是在创建映射（mmap(MAP_PRIVATE)）时创建的。 +- 对于共享映射，预留映射挂在inode上。具体来说，就是inode->i_mapping->private_data。 + 由于共享映射总是由hugetlbfs文件系统中的文件支持，hugetlbfs代码确保每个节点包含一个预 + 留映射。因此，预留映射在创建节点时被分配。 + + +创建预留 +======== +当创建一个巨大的有页面支持的共享内存段（shmget(SHM_HUGETLB)）或通过mmap(MAP_HUGETLB) +创建一个映射时，就会创建预留。这些操作会导致对函数hugetlb_reserve_pages()的调用:: + + int hugetlb_reserve_pages(struct inode *inode, + long from, long to, + struct vm_area_struct *vma, + vm_flags_t vm_flags) + +hugetlb_reserve_pages()做的第一件事是检查在调用shmget()或mmap()时是否指定了NORESERVE +标志。如果指定了NORESERVE，那么这个函数立即返回，因为不需要预留。 + +参数'from'和'to'是映射或基础文件的巨页索引。对于shmget()，'from'总是0，'to'对应于段/映射 +的长度。对于mmap()，offset参数可以用来指定进入底层文件的偏移量。在这种情况下，'from'和'to' +参数已经被这个偏移量所调整。 + +PRIVATE和SHARED映射之间的一个很大的区别是预留在预留映射中的表示方式。 + +- 对于共享映射，预留映射中的条目表示对应页面的预留存在或曾经存在。当预留被消耗时，预留映射不被 + 修改。 +- 对于私有映射，预留映射中没有条目表示相应页面存在预留。随着预留被消耗，条目被添加到预留映射中。 + 因此，预留映射也可用于确定哪些预留已被消耗。 + +对于私有映射，hugetlb_reserve_pages()创建预留映射并将其挂在VMA结构体上。此外， +HPAGE_RESV_OWNER标志被设置，以表明该VMA拥有预留。 + +预留映射被查阅以确定当前映射/段需要多少巨页预留。对于私有映射，这始终是一个值（to - from）。 +然而，对于共享映射来说，一些预留可能已经存在于(to - from)的范围内。关于如何实现这一点的细节， +请参见 :ref:`预留映射的修改 <resv_map_modifications>` 一节。 + +该映射可能与一个子池（subpool）相关联。如果是这样，将查询子池以确保有足够的空间用于映射。子池 +有可能已经预留了可用于映射的预留空间。更多细节请参见 :ref: `子池预留 <sub_pool_resv>` +一节。 + +在咨询了预留映射和子池之后，就知道了需要的新预留数量。hugetlb_acct_memory()函数被调用以检查 +并获取所要求的预留数量。hugetlb_acct_memory()调用到可能分配和调整剩余页数的函数。然而，在这 +些函数中，代码只是检查以确保有足够的空闲的巨页来容纳预留。如果有的话，全局预留计数resv_huge_pages +会被调整，如下所示:: + + if (resv_needed <= (resv_huge_pages - free_huge_pages)) + resv_huge_pages += resv_needed; + +注意，在检查和调整这些计数器时，全局锁hugetlb_lock会被预留。 + +如果有足够的空闲的巨页，并且全局计数resv_huge_pages被调整，那么与映射相关的预留映射被修改以 +反映预留。在共享映射的情况下，将存在一个file_region，包括'from'-'to'范围。对于私有映射， +不对预留映射进行修改，因为没有条目表示存在预留。 + +如果hugetlb_reserve_pages()成功，全局预留数和与映射相关的预留映射将根据需要被修改，以确保 +在'from'-'to'范围内存在预留。 + +消耗预留/分配一个巨页 +=========================== + +当与预留相关的巨页在相应的映射中被分配和实例化时，预留就被消耗了。该分配是在函数alloc_huge_page() +中进行的:: + + struct page *alloc_huge_page(struct vm_area_struct *vma, + unsigned long addr, int avoid_reserve) + +alloc_huge_page被传递给一个VMA指针和一个虚拟地址，因此它可以查阅预留映射以确定是否存在预留。 +此外，alloc_huge_page需要一个参数avoid_reserve，该参数表示即使看起来已经为指定的地址预留了 +预留，也不应该使用预留。avoid_reserve参数最常被用于写时拷贝和页面迁移的情况下，即现有页面的额 +外拷贝被分配。 + + +调用辅助函数vma_needs_reservation()来确定是否存在对映射(vma)中地址的预留。关于这个函数的详 +细内容，请参见 :ref:`预留映射帮助函数 <resv_map_helpers>` 一节。从 +vma_needs_reservation()返回的值通常为0或1。如果该地址存在预留，则为0，如果不存在预留，则为1。 +如果不存在预留，并且有一个与映射相关联的子池，则查询子池以确定它是否包含预留。如果子池包含预留， +则可将其中一个用于该分配。然而，在任何情况下，avoid_reserve参数都会优先考虑为分配使用预留。在 +确定预留是否存在并可用于分配后，调用dequeue_huge_page_vma()函数。这个函数需要两个与预留有关 +的参数： + +- avoid_reserve，这是传递给alloc_huge_page()的同一个值/参数。 +- chg，尽管这个参数的类型是long，但只有0或1的值被传递给dequeue_huge_page_vma。如果该值为0， + 则表明存在预留（关于可能的问题，请参见 “预留和内存策略” 一节）。如果值 + 为1，则表示不存在预留，如果可能的话，必须从全局空闲池中取出该页。 + +与VMA的内存策略相关的空闲列表被搜索到一个空闲页。如果找到了一个页面，当该页面从空闲列表中移除时， +free_huge_pages的值被递减。如果有一个与该页相关的预留，将进行以下调整:: + + SetPagePrivate(page); /* 表示分配这个页面消耗了一个预留， + * 如果遇到错误，以至于必须释放这个页面，预留将被 + * 恢复。 */ + resv_huge_pages--; /* 减少全局预留计数 */ + +注意，如果找不到满足VMA内存策略的巨页，将尝试使用伙伴分配器分配一个。这就带来了超出预留范围 +的剩余巨页和超额分配的问题。即使分配了一个多余的页面，也会进行与上面一样的基于预留的调整: +SetPagePrivate(page) 和 resv_huge_pages--. + +在获得一个新的巨页后，(page)->private被设置为与该页面相关的子池的值，如果它存在的话。当页 +面被释放时，这将被用于子池的计数。 + +然后调用函数vma_commit_reservation()，根据预留的消耗情况调整预留映射。一般来说，这涉及 +到确保页面在区域映射的file_region结构体中被表示。对于预留存在的共享映射，预留映射中的条目 +已经存在，所以不做任何改变。然而，如果共享映射中没有预留，或者这是一个私有映射，则必须创建一 +个新的条目。 + +注意，如果找不到满足VMA内存策略的巨页，将尝试使用伙伴分配器分配一个。这就带来了超出预留范围 +的剩余巨页和过度分配的问题。即使分配了一个多余的页面，也会进行与上面一样的基于预留的调整。 +SetPagePrivate(page)和resv_huge_pages-。 + +在获得一个新的巨页后，(page)->private被设置为与该页面相关的子池的值，如果它存在的话。当页 +面被释放时，这将被用于子池的计数。 + +然后调用函数vma_commit_reservation()，根据预留的消耗情况调整预留映射。一般来说，这涉及 +到确保页面在区域映射的file_region结构体中被表示。对于预留存在的共享映射，预留映射中的条目 +已经存在，所以不做任何改变。然而，如果共享映射中没有预留，或者这是一个私有映射，则必须创建 +一个新的条目。 + +在alloc_huge_page()开始调用vma_needs_reservation()和页面分配后调用 +vma_commit_reservation()之间，预留映射有可能被改变。如果hugetlb_reserve_pages在共 +享映射中为同一页面被调用，这将是可能的。在这种情况下，预留计数和子池空闲页计数会有一个偏差。 +这种罕见的情况可以通过比较vma_needs_reservation和vma_commit_reservation的返回值来 +识别。如果检测到这种竞争，子池和全局预留计数将被调整以进行补偿。关于这些函数的更多信息，请 +参见 :ref:`预留映射帮助函数 <resv_map_helpers>` 一节。 + + +实例化巨页 +========== + +在巨页分配之后，页面通常被添加到分配任务的页表中。在此之前，共享映射中的页面被添加到页面缓 +存中，私有映射中的页面被添加到匿名反向映射中。在这两种情况下，PagePrivate标志被清除。因此， +当一个已经实例化的巨页被释放时，不会对全局预留计数（resv_huge_pages）进行调整。 + + +释放巨页 +======== + +巨页释放是由函数free_huge_page()执行的。这个函数是hugetlbfs复合页的析构器。因此，它只传 +递一个指向页面结构体的指针。当一个巨页被释放时，可能需要进行预留计算。如果该页与包含保 +留的子池相关联，或者该页在错误路径上被释放，必须恢复全局预留计数，就会出现这种情况。 + +page->private字段指向与该页相关的任何子池。如果PagePrivate标志被设置，它表明全局预留计数 +应该被调整（关于如何设置这些标志的信息，请参见 +:ref: `消耗预留/分配一个巨页 <consume_resv>` ）。 + + +该函数首先调用hugepage_subpool_put_pages()来处理该页。如果这个函数返回一个0的值（不等于 +传递的1的值），它表明预留与子池相关联，这个新释放的页面必须被用来保持子池预留的数量超过最小值。 +因此，在这种情况下，全局resv_huge_pages计数器被递增。 + +如果页面中设置了PagePrivate标志，那么全局resv_huge_pages计数器将永远被递增。 + +子池预留 +======== + +有一个结构体hstate与每个巨页尺寸相关联。hstate跟踪所有指定大小的巨页。一个子池代表一 +个hstate中的页面子集，它与一个已挂载的hugetlbfs文件系统相关 + +当一个hugetlbfs文件系统被挂载时，可以指定min_size选项，它表示文件系统所需的最小的巨页数量。 +如果指定了这个选项，与min_size相对应的巨页的数量将被预留给文件系统使用。这个数字在结构体 +hugepage_subpool的min_hpages字段中被跟踪。在挂载时，hugetlb_acct_memory(min_hpages) +被调用以预留指定数量的巨页。如果它们不能被预留，挂载就会失败。 + +当从子池中获取或释放页面时，会调用hugepage_subpool_get/put_pages()函数。 +hugepage_subpool_get/put_pages被传递给巨页数量，以此来调整子池的 “已用页面” 计数 +（get为下降，put为上升）。通常情况下，如果子池中没有足够的页面，它们会返回与传递的相同的值或 +一个错误。 + +然而，如果预留与子池相关联，可能会返回一个小于传递值的返回值。这个返回值表示必须进行的额外全局 +池调整的数量。例如，假设一个子池包含3个预留的巨页，有人要求5个。与子池相关的3个预留页可以用来 +满足部分请求。但是，必须从全局池中获得2个页面。为了向调用者转达这一信息，将返回值2。然后，调用 +者要负责从全局池中获取另外两个页面。 + + +COW和预留 +========== + +由于共享映射都指向并使用相同的底层页面，COW最大的预留问题是私有映射。在这种情况下，两个任务可 +以指向同一个先前分配的页面。一个任务试图写到该页，所以必须分配一个新的页，以便每个任务都指向它 +自己的页。 + +当该页最初被分配时，该页的预留被消耗了。当由于COW而试图分配一个新的页面时，有可能没有空闲的巨 +页，分配会失败。 + +当最初创建私有映射时，通过设置所有者的预留映射指针中的HPAGE_RESV_OWNER位来标记映射的所有者。 +由于所有者创建了映射，所有者拥有与映射相关的所有预留。因此，当一个写异常发生并且没有可用的页面 +时，对预留的所有者和非所有者采取不同的行动。 + +在发生异常的任务不是所有者的情况下，异常将失败，该任务通常会收到一个SIGBUS。 + +如果所有者是发生异常的任务，我们希望它能够成功，因为它拥有原始的预留。为了达到这个目的，该页被 +从非所有者任务中解映射出来。这样一来，唯一的引用就是来自拥有者的任务。此外，HPAGE_RESV_UNMAPPED +位被设置在非拥有任务的预留映射指针中。如果非拥有者任务后来在一个不存在的页面上发生异常，它可能 +会收到一个SIGBUS。但是，映射/预留的原始拥有者的行为将与预期一致。 + +预留映射的修改 +============== + +以下低级函数用于对预留映射进行修改。通常情况下，这些函数不会被直接调用。而是调用一个预留映射辅 +助函数，该函数调用这些低级函数中的一个。这些低级函数在源代码（mm/hugetlb.c）中得到了相当好的 +记录。这些函数是:: + + long region_chg(struct resv_map *resv, long f, long t); + long region_add(struct resv_map *resv, long f, long t); + void region_abort(struct resv_map *resv, long f, long t); + long region_count(struct resv_map *resv, long f, long t); + +在预留映射上的操作通常涉及两个操作: + +1) region_chg()被调用来检查预留映射，并确定在指定的范围[f, t]内有多少页目前没有被代表。 + + 调用代码执行全局检查和分配，以确定是否有足够的巨页使操作成功。 + +2) + a) 如果操作能够成功，regi_add()将被调用，以实际修改先前传递给regi_chg()的相同范围 + [f, t]的预留映射。 + b) 如果操作不能成功，region_abort被调用，在相同的范围[f, t]内中止操作。 + +注意，这是一个两步的过程， region_add()和 region_abort()在事先调用 region_chg()后保证 +成功。 region_chg()负责预先分配任何必要的数据结构以确保后续操作（特别是 region_add()）的 +成功。 + +如上所述，region_chg()确定该范围内当前没有在映射中表示的页面的数量。region_add()返回添加 +到映射中的范围内的页数。在大多数情况下， region_add() 的返回值与 region_chg() 的返回值相 +同。然而，在共享映射的情况下，有可能在调用 region_chg() 和 region_add() 之间对预留映射进 +行更改。在这种情况下，regi_add()的返回值将与regi_chg()的返回值不符。在这种情况下，全局计数 +和子池计数很可能是不正确的，需要调整。检查这种情况并进行适当的调整是调用者的责任。 + +函数region_del()被调用以从预留映射中移除区域。 +它通常在以下情况下被调用: + +- 当hugetlbfs文件系统中的一个文件被删除时，该节点将被释放，预留映射也被释放。在释放预留映射 + 之前，所有单独的file_region结构体必须被释放。在这种情况下，region_del的范围是[0, LONG_MAX]。 +- 当一个hugetlbfs文件正在被截断时。在这种情况下，所有在新文件大小之后分配的页面必须被释放。 + 此外，预留映射中任何超过新文件大小的file_region条目必须被删除。在这种情况下，region_del + 的范围是[new_end_of_file, LONG_MAX]。 +- 当在一个hugetlbfs文件中打洞时。在这种情况下，巨页被一次次从文件的中间移除。当这些页被移除 + 时，region_del()被调用以从预留映射中移除相应的条目。在这种情况下，region_del被传递的范 + 围是[page_idx, page_idx + 1]。 + +在任何情况下，region_del()都会返回从预留映射中删除的页面数量。在非常罕见的情况下，region_del() +会失败。这只能发生在打洞的情况下，即它必须分割一个现有的file_region条目，而不能分配一个新的 +结构体。在这种错误情况下，region_del()将返回-ENOMEM。这里的问题是，预留映射将显示对该页有 +预留。然而，子池和全局预留计数将不反映该预留。为了处理这种情况，调用函数hugetlb_fix_reserve_counts() +来调整计数器，使其与不能被删除的预留映射条目相对应。 + +region_count()在解除私有巨页映射时被调用。在私有映射中，预留映射中没有条目表明存在一个预留。 +因此，通过计算预留映射中的条目数，我们知道有多少预留被消耗了，有多少预留是未完成的 +（Outstanding = (end - start) - region_count（resv, start, end））。由于映射正在消 +失，子池和全局预留计数被未完成的预留数量所减去。 + +预留映射帮助函数 +================ + +有几个辅助函数可以查询和修改预留映射。这些函数只对特定的巨页的预留感兴趣，所以它们只是传入一个 +地址而不是一个范围。此外，它们还传入相关的VMA。从VMA中，可以确定映射的类型（私有或共享）和预留 +映射的位置（inode或VMA）。这些函数只是调用 “预留映射的修改” 一节中描述的基础函数。然而， +它们确实考虑到了私有和共享映射的预留映射条目的 “相反” 含义，并向调用者隐藏了这个细节:: + + long vma_needs_reservation(struct hstate *h, + struct vm_area_struct *vma, + unsigned long addr) + +该函数为指定的页面调用 region_chg()。如果不存在预留，则返回1。如果存在预留，则返回0:: + + long vma_commit_reservation(struct hstate *h, + struct vm_area_struct *vma, + unsigned long addr) + +这将调用 region_add()，用于指定的页面。与region_chg和region_add的情况一样，该函数应在 +先前调用的vma_needs_reservation后调用。它将为该页添加一个预留条目。如果预留被添加，它将 +返回1，如果没有则返回0。返回值应与之前调用vma_needs_reservation的返回值进行比较。如果出 +现意外的差异，说明在两次调用之间修改了预留映射:: + + void vma_end_reservation(struct hstate *h, + struct vm_area_struct *vma, + unsigned long addr) + +这将调用指定页面的 region_abort()。与region_chg和region_abort的情况一样，该函数应在 +先前调用的vma_needs_reservation后被调用。它将中止/结束正在进行的预留添加操作:: + + long vma_add_reservation(struct hstate *h, + struct vm_area_struct *vma, + unsigned long addr) + +这是一个特殊的包装函数，有助于在错误路径上清理预留。它只从repare_reserve_on_error()函数 +中调用。该函数与vma_needs_reservation一起使用，试图将一个预留添加到预留映射中。它考虑到 +了私有和共享映射的不同预留映射语义。因此，region_add被调用用于共享映射（因为映射中的条目表 +示预留），而region_del被调用用于私有映射（因为映射中没有条目表示预留）。关于在错误路径上需 +要做什么的更多信息，请参见 “错误路径中的预留清理” 。 + + +错误路径中的预留清理 +==================== + +正如在:ref:`预留映射帮助函数<resv_map_helpers>` 一节中提到的，预留的修改分两步进行。首 +先，在分配页面之前调用vma_needs_reservation。如果分配成功，则调用vma_commit_reservation。 +如果不是，则调用vma_end_reservation。全局和子池的预留计数根据操作的成功或失败进行调整， +一切都很好。 + +此外，在一个巨页被实例化后，PagePrivate标志被清空，这样，当页面最终被释放时，计数是 +正确的。 + +然而，有几种情况是，在一个巨页被分配后，但在它被实例化之前，就遇到了错误。在这种情况下， +页面分配已经消耗了预留，并进行了适当的子池、预留映射和全局计数调整。如果页面在这个时候被释放 +（在实例化和清除PagePrivate之前），那么free_huge_page将增加全局预留计数。然而，预留映射 +显示报留被消耗了。这种不一致的状态将导致预留的巨页的 “泄漏” 。全局预留计数将比它原本的要高， +并阻止分配一个预先分配的页面。 + +函数 restore_reserve_on_error() 试图处理这种情况。它有相当完善的文档。这个函数的目的 +是将预留映射恢复到页面分配前的状态。通过这种方式，预留映射的状态将与页面释放后的全局预留计 +数相对应。 + +函数restore_reserve_on_error本身在试图恢复预留映射条目时可能会遇到错误。在这种情况下， +它将简单地清除该页的PagePrivate标志。这样一来，当页面被释放时，全局预留计数将不会被递增。 +然而，预留映射将继续看起来像预留被消耗了一样。一个页面仍然可以被分配到该地址，但它不会像最 +初设想的那样使用一个预留页。 + +有一些代码（最明显的是userfaultfd）不能调用restore_reserve_on_error。在这种情况下， +它简单地修改了PagePrivate，以便在释放巨页时不会泄露预留。 + + +预留和内存策略 +============== +当git第一次被用来管理Linux代码时，每个节点的巨页列表就存在于hstate结构中。预留的概念是 +在一段时间后加入的。当预留被添加时，没有尝试将内存策略考虑在内。虽然cpusets与内存策略不 +完全相同，但hugetlb_acct_memory中的这个注释总结了预留和cpusets/内存策略之间的相互作 +用:: + + + /* + * 当cpuset被配置时，它打破了严格的hugetlb页面预留，因为计数是在一个全局变量上完 + * 成的。在有cpuset的情况下，这样的预留完全是垃圾，因为预留没有根据当前cpuset的 + * 页面可用性来检查。在任务所在的cpuset中缺乏空闲的htlb页面时，应用程序仍然有可能 + * 被内核OOM'ed。试图用cpuset来执行严格的计数几乎是不可能的（或者说太难看了），因 + * 为cpuset太不稳定了，任务或内存节点可以在cpuset之间动态移动。与cpuset共享 + * hugetlb映射的语义变化是不可取的。然而，为了预留一些语义，我们退回到检查当前空闲 + * 页的可用性，作为一种最好的尝试，希望能将cpuset改变语义的影响降到最低。 + */ + +添加巨页预留是为了防止在缺页异常时出现意外的页面分配失败（OOM）。然而，如果一个应用 +程序使用cpusets或内存策略，就不能保证在所需的节点上有巨页可用。即使有足够数量的全局 +预留，也是如此。 + +Hugetlbfs回归测试 +================= + +最完整的hugetlb测试集在libhugetlbfs仓库。如果你修改了任何hugetlb相关的代码，请使用 +libhugetlbfs测试套件来检查回归情况。此外，如果你添加了任何新的hugetlb功能，请在 +libhugetlbfs中添加适当的测试。 + +-- +Mike Kravetz，2017年4月7日 diff --git a/Documentation/translations/zh_CN/mm/hwpoison.rst b/Documentation/translations/zh_CN/mm/hwpoison.rst new file mode 100644 index 000000000000..310862edc937 --- /dev/null +++ b/Documentation/translations/zh_CN/mm/hwpoison.rst @@ -0,0 +1,166 @@ + +:Original: Documentation/mm/hwpoison.rst + +:翻译: + + 司延腾 Yanteng Si <siyanteng@loongson.cn> + +:校译: + + +======== +hwpoison +======== + +什么是hwpoison? +=============== + + +即将推出的英特尔CPU支持从一些内存错误中恢复（ ``MCA恢复`` ）。这需要操作系统宣布 +一个页面"poisoned"，杀死与之相关的进程，并避免在未来使用它。 + +这个补丁包在虚拟机中实现了必要的(编程)框架。 + +引用概述中的评论:: + + 高级机器的检查与处理。处理方法是损坏的页面被硬件报告，通常是由于2位ECC内 + 存或高速缓存故障。 + + 这主要是针对在后台检测到的损坏的页面。当当前的CPU试图访问它时，当前运行的进程 + 可以直接被杀死。因为还没有访问损坏的页面, 如果错误由于某种原因不能被处理，就可 + 以安全地忽略它. 而不是用另外一个机器检查去处理它。 + + 处理不同状态的页面缓存页。这里棘手的部分是，相对于其他虚拟内存用户， 我们可以异 + 步访问任何页面。因为内存故障可能随时随地发生，可能违反了他们的一些假设。这就是 + 为什么这段代码必须非常小心。一般来说，它试图使用正常的锁规则，如获得标准锁，即使 + 这意味着错误处理可能需要很长的时间。 + + 这里的一些操作有点低效，并且具有非线性的算法复杂性，因为数据结构没有针对这种情 + 况进行优化。特别是从vma到进程的映射就是这种情况。由于这种情况大概率是罕见的，所 + 以我们希望我们可以摆脱这种情况。 + +该代码由mm/memory-failure.c中的高级处理程序、一个新的页面poison位和虚拟机中的 +各种检查组成，用来处理poison的页面。 + +现在主要目标是KVM客户机，但它适用于所有类型的应用程序。支持KVM需要最近的qemu-kvm +版本。 + +对于KVM的使用，需要一个新的信号类型，这样KVM就可以用适当的地址将机器检查注入到客户 +机中。这在理论上也允许其他应用程序处理内存故障。我们的期望是，所有的应用程序都不要这 +样做，但一些非常专业的应用程序可能会这样做。 + +故障恢复模式 +============ + +有两种（实际上是三种）模式的内存故障恢复可以在。 + +vm.memory_failure_recovery sysctl 置零: + 所有的内存故障都会导致panic。请不要尝试恢复。 + +早期处理 + (可以在全局和每个进程中控制) 一旦检测到错误，立即向应用程序发送SIGBUS这允许 + 应用程序以温和的方式处理内存错误（例如，放弃受影响的对象） 这是KVM qemu使用的 + 模式。 + +推迟处理 + 当应用程序运行到损坏的页面时，发送SIGBUS。这对不知道内存错误的应用程序来说是 + 最好的，默认情况下注意一些页面总是被当作late kill处理。 + +用户控制 +======== + +vm.memory_failure_recovery + 参阅 sysctl.txt + +vm.memory_failure_early_kill + 全局启用early kill + +PR_MCE_KILL + 设置early/late kill mode/revert 到系统默认值。 + + arg1: PR_MCE_KILL_CLEAR: + 恢复到系统默认值 + arg1: PR_MCE_KILL_SET: + arg2定义了线程特定模式 + + PR_MCE_KILL_EARLY: + Early kill + PR_MCE_KILL_LATE: + Late kill + PR_MCE_KILL_DEFAULT + 使用系统全局默认值 + + 注意，如果你想有一个专门的线程代表进程处理SIGBUS(BUS_MCEERR_AO)，你应该在 + 指定线程上调用prctl(PR_MCE_KILL_EARLY)。否则，SIGBUS将被发送到主线程。 + +PR_MCE_KILL_GET + 返回当前模式 + +测试 +==== + +* madvise(MADV_HWPOISON, ....) (as root) - 在测试过程中Poison一个页面 + +* 通过debugfs ``/sys/kernel/debug/hwpoison/`` hwpoison-inject模块 + + corrupt-pfn + 在PFN处注入hwpoison故障，并echoed到这个文件。这做了一些早期过滤，以避 + 免在测试套件中损坏非预期页面。 + unpoison-pfn + 在PFN的Software-unpoison页面对应到这个文件。这样，一个页面可以再次被 + 复用。这只对Linux注入的故障起作用，对真正的内存故障不起作用。 + + 注意这些注入接口并不稳定，可能会在不同的内核版本中发生变化 + + corrupt-filter-dev-major, corrupt-filter-dev-minor + 只处理与块设备major/minor定义的文件系统相关的页面的内存故障。-1U是通 + 配符值。这应该只用于人工注入的测试。 + + corrupt-filter-memcg + 限制注入到memgroup拥有的页面。由memcg的inode号指定。 + + Example:: + + mkdir /sys/fs/cgroup/mem/hwpoison + + usemem -m 100 -s 1000 & + echo `jobs -p` > /sys/fs/cgroup/mem/hwpoison/tasks + + memcg_ino=$(ls -id /sys/fs/cgroup/mem/hwpoison | cut -f1 -d' ') + echo $memcg_ino > /debug/hwpoison/corrupt-filter-memcg + + page-types -p `pidof init` --hwpoison # shall do nothing + page-types -p `pidof usemem` --hwpoison # poison its pages + + corrupt-filter-flags-mask, corrupt-filter-flags-value + 当指定时，只有在((page_flags & mask) == value)的情况下才会poison页面。 + 这允许对许多种类的页面进行压力测试。page_flags与/proc/kpageflags中的相 + 同。这些标志位在include/linux/kernel-page-flags.h中定义，并在 + Documentation/admin-guide/mm/pagemap.rst中记录。 + +* 架构特定的MCE注入器 + + x86 有 mce-inject, mce-test + + 在mce-test中的一些便携式hwpoison测试程序，见下文。 + +引用 +==== + +http://halobates.de/mce-lc09-2.pdf + 09年LinuxCon的概述演讲 + +git://git.kernel.org/pub/scm/utils/cpu/mce/mce-test.git + 测试套件（在tsrc中的hwpoison特定可移植测试）。 + +git://git.kernel.org/pub/scm/utils/cpu/mce/mce-inject.git + x86特定的注入器 + + +限制 +==== +- 不是所有的页面类型都被支持，而且永远不会。大多数内核内部对象不能被恢 + 复，目前只有LRU页。 + +--- +Andi Kleen, 2009年10月 diff --git a/Documentation/translations/zh_CN/mm/index.rst b/Documentation/translations/zh_CN/mm/index.rst new file mode 100644 index 000000000000..2f53e37b8049 --- /dev/null +++ b/Documentation/translations/zh_CN/mm/index.rst @@ -0,0 +1,69 @@ +.. include:: ../disclaimer-zh_CN.rst + +:Original: Documentation/mm/index.rst + +:翻译: + + 司延腾 Yanteng Si <siyanteng@loongson.cn> + +:校译: + +================= +Linux内存管理文档 +================= + +这是一份关于了解Linux的内存管理子系统的指南。如果你正在寻找关于简单分配内存的 +建议，请参阅内存分配指南 +(Documentation/translations/zh_CN/core-api/memory-allocation.rst)。 +关于控制和调整的指南，请看管理指南 +(Documentation/translations/zh_CN/admin-guide/mm/index.rst)。 + + +.. toctree:: + :maxdepth: 1 + + highmem + +该处剩余文档待原始文档有内容后翻译。 + + +遗留文档 +======== + +这是一个关于Linux内存管理（MM）子系统内部的旧文档的集合，其中有不同层次的细节， +包括注释和邮件列表的回复，用于阐述数据结构和算法的描述。它应该被很好地整合到上述 +结构化的文档中，如果它已经完成了它的使命，可以删除。 + +.. toctree:: + :maxdepth: 1 + + active_mm + balance + damon/index + free_page_reporting + ksm + frontswap + hmm + hwpoison + hugetlbfs_reserv + memory-model + mmu_notifier + numa + overcommit-accounting + page_frags + page_migration + page_owner + page_table_check + remap_file_pages + split_page_table_lock + vmalloced-kernel-stacks + z3fold + zsmalloc + +TODOLIST: +* arch_pgtable_helpers +* free_page_reporting +* hugetlbfs_reserv +* slub +* transhuge +* unevictable-lru diff --git a/Documentation/translations/zh_CN/mm/ksm.rst b/Documentation/translations/zh_CN/mm/ksm.rst new file mode 100644 index 000000000000..f0f458753d0c --- /dev/null +++ b/Documentation/translations/zh_CN/mm/ksm.rst @@ -0,0 +1,70 @@ +.. include:: ../disclaimer-zh_CN.rst + +:Original: Documentation/mm/ksm.rst + +:翻译: + + 徐鑫 xu xin <xu.xin16@zte.com.cn> + +============ +内核同页合并 +============ + +KSM 是一种节省内存的数据去重功能，由CONFIG_KSM=y启用，并在2.6.32版本时被添加 +到Linux内核。详见 ``mm/ksm.c`` 的实现，以及http://lwn.net/Articles/306704和 +https://lwn.net/Articles/330589 + +KSM的用户空间的接口在Documentation/translations/zh_CN/admin-guide/mm/ksm.rst +文档中有描述。 + +设计 +==== + +概述 +---- + +概述内容请见mm/ksm.c文档中的“DOC: Overview” + +逆映射 +------ +KSM维护着稳定树中的KSM页的逆映射信息。 + +当KSM页面的共享数小于 ``max_page_sharing`` 的虚拟内存区域(VMAs)时，则代表了 +KSM页的稳定树其中的节点指向了一个ksm_rmap_item结构体类型的列表。同时，这个KSM页 +的 ``page->mapping`` 指向了该稳定树节点。 + +如果共享数超过了阈值，KSM将给稳定树添加第二个维度。稳定树就变成链接一个或多 +个稳定树"副本"的"链"。每个副本都保留KSM页的逆映射信息，其中 ``page->mapping`` +指向该"副本"。 + +每个链以及链接到该链中的所有"副本"强制不变的是，它们代表了相同的写保护内存 +内容，尽管任中一个"副本"是由同一片内存区的不同的KSM复制页所指向的。 + +这样一来，相比与无限的逆映射链表，稳定树的查找计算复杂性不受影响。但在稳定树 +本身中不能有重复的KSM页面内容仍然是强制要求。 + +由 ``max_page_sharing`` 强制决定的数据去重限制是必要的，以此来避免虚拟内存 +rmap链表变得过大。rmap的遍历具有O(N)的复杂度，其中N是共享页面的rmap_项（即 +虚拟映射）的数量，而这个共享页面的节点数量又被 ``max_page_sharing`` 所限制。 +因此，这有效地将线性O(N)计算复杂度从rmap遍历中分散到不同的KSM页面上。ksmd进 +程在稳定节点"链"上的遍历也是O(N)，但这个N是稳定树"副本"的数量，而不是rmap项 +的数量，因此它对ksmd性能没有显著影响。实际上，最佳稳定树"副本"的候选节点将 +保留在"副本"列表的开头。 + +``max_page_sharing`` 的值设置得高了会促使更快的内存合并（因为将有更少的稳定 +树副本排队进入稳定节点chain->hlist）和更高的数据去重系数，但代价是在交换、压 +缩、NUMA平衡和页面迁移过程中可能导致KSM页的最大rmap遍历速度较慢。 + +``stable_node_dups/stable_node_chains`` 的比值还受 ``max_page_sharing`` 调控 +的影响，高比值可能意味着稳定节点dup中存在碎片，这可以通过在ksmd中引入碎片算 +法来解决，该算法将rmap项从一个稳定节点dup重定位到另一个稳定节点dup，以便释放 +那些仅包含极少rmap项的稳定节点"dup"，但这可能会增加ksmd进程的CPU使用率，并可 +能会减慢应用程序在KSM页面上的只读计算。 + +KSM会定期扫描稳定节点"链"中链接的所有稳定树"副本"，以便删减过时了的稳定节点。 +这种扫描的频率由 ``stable_node_chains_prune_millisecs`` 这个sysfs 接口定义。 + +参考 +==== +内核代码请见mm/ksm.c。 +涉及的函数(mm_slot ksm_scan stable_node rmap_item)。 diff --git a/Documentation/translations/zh_CN/mm/memory-model.rst b/Documentation/translations/zh_CN/mm/memory-model.rst new file mode 100644 index 000000000000..77ec149a970c --- /dev/null +++ b/Documentation/translations/zh_CN/mm/memory-model.rst @@ -0,0 +1,135 @@ +.. SPDX-License-Identifier: GPL-2.0 + +:Original: Documentation/mm/memory-model.rst + +:翻译: + + 司延腾 Yanteng Si <siyanteng@loongson.cn> + +:校译: + + +============ +物理内存模型 +============ + +系统中的物理内存可以用不同的方式进行寻址。最简单的情况是，物理内存从地址0开 +始，跨越一个连续的范围，直到最大的地址。然而，这个范围可能包含CPU无法访问的 +小孔隙。那么，在完全不同的地址可能有几个连续的范围。而且，别忘了NUMA，即不 +同的内存库连接到不同的CPU。 + +Linux使用两种内存模型中的一种对这种多样性进行抽象。FLATMEM和SPARSEM。每 +个架构都定义了它所支持的内存模型，默认的内存模型是什么，以及是否有可能手动 +覆盖该默认值。 + +所有的内存模型都使用排列在一个或多个数组中的 `struct page` 来跟踪物理页 +帧的状态。 + +无论选择哪种内存模型，物理页框号（PFN）和相应的 `struct page` 之间都存 +在一对一的映射关系。 + +每个内存模型都定义了 :c:func:`pfn_to_page` 和 :c:func:`page_to_pfn` +帮助函数，允许从PFN到 `struct page` 的转换，反之亦然。 + +FLATMEM +======= + +最简单的内存模型是FLATMEM。这个模型适用于非NUMA系统的连续或大部分连续的 +物理内存。 + +在FLATMEM内存模型中，有一个全局的 `mem_map` 数组来映射整个物理内存。对 +于大多数架构，孔隙在 `mem_map` 数组中都有条目。与孔洞相对应的 `struct page` +对象从未被完全初始化。 + +为了分配 `mem_map` 数组，架构特定的设置代码应该调用free_area_init()函数。 +然而，在调用memblock_free_all()函数之前，映射数组是不能使用的，该函数 +将所有的内存交给页分配器。 + +一个架构可能会释放 `mem_map` 数组中不包括实际物理页的部分。在这种情况下，特 +定架构的 :c:func:`pfn_valid` 实现应该考虑到 `mem_map` 中的孔隙。 + +使用FLATMEM，PFN和 `struct page` 之间的转换是直接的。 `PFN - ARCH_PFN_OFFSET` +是 `mem_map` 数组的一个索引。 + +`ARCH_PFN_OFFSET` 定义了物理内存起始地址不同于0的系统的第一个页框号。 + +SPARSEMEM +========= + +SPARSEMEM是Linux中最通用的内存模型，它是唯一支持若干高级功能的内存模型， +如物理内存的热插拔、非易失性内存设备的替代内存图和较大系统的内存图的延迟 +初始化。 + +SPARSEMEM模型将物理内存显示为一个部分的集合。一个区段用mem_section结构 +体表示，它包含 `section_mem_map` ，从逻辑上讲，它是一个指向 `struct page` +阵列的指针。然而，它被存储在一些其他的magic中，以帮助分区管理。区段的大小 +和最大区段数是使用 `SECTION_SIZE_BITS` 和 `MAX_PHYSMEM_BITS` 常量 +来指定的，这两个常量是由每个支持SPARSEMEM的架构定义的。 `MAX_PHYSMEM_BITS` +是一个架构所支持的物理地址的实际宽度，而 `SECTION_SIZE_BITS` 是一个任 +意的值。 + +最大的段数表示为 `NR_MEM_SECTIONS` ，定义为 + +.. math:: + + NR\_MEM\_SECTIONS = 2 ^ {(MAX\_PHYSMEM\_BITS - SECTION\_SIZE\_BITS)} + +`mem_section` 对象被安排在一个叫做 `mem_sections` 的二维数组中。这个数组的 +大小和位置取决于 `CONFIG_SPARSEM_EXTREME` 和可能的最大段数: + +* 当 `CONFIG_SPARSEMEM_EXTREME` 被禁用时， `mem_sections` 数组是静态的，有 + `NR_MEM_SECTIONS` 行。每一行持有一个 `mem_section` 对象。 +* 当 `CONFIG_SPARSEMEM_EXTREME` 被启用时， `mem_sections` 数组被动态分配。 + 每一行包含价值 `PAGE_SIZE` 的 `mem_section` 对象，行数的计算是为了适应所有的 + 内存区。 + +架构设置代码应该调用sparse_init()来初始化内存区和内存映射。 + +通过SPARSEMEM，有两种可能的方式将PFN转换为相应的 `struct page` --"classic sparse"和 + "sparse vmemmap"。选择是在构建时进行的，它由 `CONFIG_SPARSEMEM_VMEMMAP` 的 + 值决定。 + +Classic sparse在page->flags中编码了一个页面的段号，并使用PFN的高位来访问映射该页 +框的段。在一个区段内，PFN是指向页数组的索引。 + +Sparse vmemmapvmemmap使用虚拟映射的内存映射来优化pfn_to_page和page_to_pfn操 +作。有一个全局的 `struct page *vmemmap` 指针，指向一个虚拟连续的 `struct page` +对象阵列。PFN是该数组的一个索引，`struct page` 从 `vmemmap` 的偏移量是该页的PFN。 + +为了使用vmemmap，一个架构必须保留一个虚拟地址的范围，以映射包含内存映射的物理页，并 +确保 `vmemmap`指向该范围。此外，架构应该实现 :c:func:`vmemmap_populate` 方法， +它将分配物理内存并为虚拟内存映射创建页表。如果一个架构对vmemmap映射没有任何特殊要求， +它可以使用通用内存管理提供的默认 :c:func:`vmemmap_populate_basepages`。 + +虚拟映射的内存映射允许将持久性内存设备的 `struct page` 对象存储在这些设备上预先分 +配的存储中。这种存储用vmem_altmap结构表示，最终通过一长串的函数调用传递给 +vmemmap_populate()。vmemmap_populate()实现可以使用 `vmem_altmap` 和 +:c:func:`vmemmap_alloc_block_buf` 助手来分配持久性内存设备上的内存映射。 + +ZONE_DEVICE +=========== +`ZONE_DEVICE` 设施建立在 `SPARSEM_VMEMMAP` 之上，为设备驱动识别的物理地址范 +围提供 `struct page` `mem_map` 服务。 `ZONE_DEVICE` 的 "设备" 方面与以下 +事实有关：这些地址范围的页面对象从未被在线标记过，而且必须对设备进行引用，而不仅仅 +是页面，以保持内存被“锁定”以便使用。 `ZONE_DEVICE` ，通过 :c:func:`devm_memremap_pages` ， +为给定的pfns范围执行足够的内存热插拔来开启 :c:func:`pfn_to_page`， +:c:func:`page_to_pfn`, ，和 :c:func:`get_user_pages` 服务。由于页面引 +用计数永远不会低于1，所以页面永远不会被追踪为空闲内存，页面的 `struct list_head lru` +空间被重新利用，用于向映射该内存的主机设备/驱动程序进行反向引用。 + +虽然 `SPARSEMEM` 将内存作为一个区段的集合，可以选择收集并合成内存块，但 +`ZONE_DEVICE` 用户需要更小的颗粒度来填充 `mem_map` 。鉴于 `ZONE_DEVICE` +内存从未被在线标记，因此它的内存范围从未通过sysfs内存热插拔api暴露在内存块边界 +上。这个实现依赖于这种缺乏用户接口的约束，允许子段大小的内存范围被指定给 +:c:func:`arch_add_memory` ，即内存热插拔的上半部分。子段支持允许2MB作为 +:c:func:`devm_memremap_pages` 的跨架构通用对齐颗粒度。 + +`ZONE_DEVICE` 的用户是: + +* pmem: 通过DAX映射将平台持久性内存作为直接I/O目标使用。 + +* hmm: 用 `->page_fault()` 和 `->page_free()` 事件回调扩展 `ZONE_DEVICE` ， + 以允许设备驱动程序协调与设备内存相关的内存管理事件，通常是GPU内存。参见Documentation/mm/hmm.rst。 + +* p2pdma: 创建 `struct page` 对象，允许PCI/E拓扑结构中的peer设备协调它们之间的 + 直接DMA操作，即绕过主机内存。 diff --git a/Documentation/translations/zh_CN/mm/mmu_notifier.rst b/Documentation/translations/zh_CN/mm/mmu_notifier.rst new file mode 100644 index 000000000000..ce3664d1a410 --- /dev/null +++ b/Documentation/translations/zh_CN/mm/mmu_notifier.rst @@ -0,0 +1,97 @@ +:Original: Documentation/mm/mmu_notifier.rst + +:翻译: + + 司延腾 Yanteng Si <siyanteng@loongson.cn> + +:校译: + + + +什么时候需要页表锁内通知？ +========================== + +当清除一个pte/pmd时，我们可以选择通过在页表锁下（通知版的\*_clear_flush调用 +mmu_notifier_invalidate_range）通知事件。但这种通知并不是在所有情况下都需要的。 + +对于二级TLB（非CPU TLB），如IOMMU TLB或设备TLB（当设备使用类似ATS/PASID的东西让 +IOMMU走CPU页表来访问进程的虚拟地址空间）。只有两种情况需要在清除pte/pmd时在持有页 +表锁的同时通知这些二级TLB： + + A) 在mmu_notifier_invalidate_range_end()之前，支持页的地址被释放。 + B) 一个页表项被更新以指向一个新的页面（COW，零页上的写异常，__replace_page()，...）。 + +情况A很明显，你不想冒风险让设备写到一个现在可能被一些完全不同的任务使用的页面。 + +情况B更加微妙。为了正确起见，它需要按照以下序列发生: + + - 上页表锁 + - 清除页表项并通知 ([pmd/pte]p_huge_clear_flush_notify()) + - 设置页表项以指向新页 + +如果在设置新的pte/pmd值之前，清除页表项之后没有进行通知，那么你就会破坏设备的C11或 +C++11等内存模型。 + +考虑以下情况（设备使用类似于ATS/PASID的功能）。 + +两个地址addrA和addrB，这样|addrA - addrB| >= PAGE_SIZE，我们假设它们是COW的 +写保护（B的其他情况也适用）。 + +:: + + [Time N] -------------------------------------------------------------------- + CPU-thread-0 {尝试写到addrA} + CPU-thread-1 {尝试写到addrB} + CPU-thread-2 {} + CPU-thread-3 {} + DEV-thread-0 {读取addrA并填充设备TLB} + DEV-thread-2 {读取addrB并填充设备TLB} + [Time N+1] ------------------------------------------------------------------ + CPU-thread-0 {COW_step0: {mmu_notifier_invalidate_range_start(addrA)}} + CPU-thread-1 {COW_step0: {mmu_notifier_invalidate_range_start(addrB)}} + CPU-thread-2 {} + CPU-thread-3 {} + DEV-thread-0 {} + DEV-thread-2 {} + [Time N+2] ------------------------------------------------------------------ + CPU-thread-0 {COW_step1: {更新页表以指向addrA的新页}} + CPU-thread-1 {COW_step1: {更新页表以指向addrB的新页}} + CPU-thread-2 {} + CPU-thread-3 {} + DEV-thread-0 {} + DEV-thread-2 {} + [Time N+3] ------------------------------------------------------------------ + CPU-thread-0 {preempted} + CPU-thread-1 {preempted} + CPU-thread-2 {写入addrA，这是对新页面的写入} + CPU-thread-3 {} + DEV-thread-0 {} + DEV-thread-2 {} + [Time N+3] ------------------------------------------------------------------ + CPU-thread-0 {preempted} + CPU-thread-1 {preempted} + CPU-thread-2 {} + CPU-thread-3 {写入addrB，这是一个写入新页的过程} + DEV-thread-0 {} + DEV-thread-2 {} + [Time N+4] ------------------------------------------------------------------ + CPU-thread-0 {preempted} + CPU-thread-1 {COW_step3: {mmu_notifier_invalidate_range_end(addrB)}} + CPU-thread-2 {} + CPU-thread-3 {} + DEV-thread-0 {} + DEV-thread-2 {} + [Time N+5] ------------------------------------------------------------------ + CPU-thread-0 {preempted} + CPU-thread-1 {} + CPU-thread-2 {} + CPU-thread-3 {} + DEV-thread-0 {从旧页中读取addrA} + DEV-thread-2 {从新页面读取addrB} + +所以在这里，因为在N+2的时候，清空页表项没有和通知一起作废二级TLB，设备在看到addrA的新值之前 +就看到了addrB的新值。这就破坏了设备的总内存序。 + +当改变一个pte的写保护或指向一个新的具有相同内容的写保护页（KSM）时，将mmu_notifier_invalidate_range +调用延迟到页表锁外的mmu_notifier_invalidate_range_end()是可以的。即使做页表更新的线程 +在释放页表锁后但在调用mmu_notifier_invalidate_range_end()前被抢占，也是如此。 diff --git a/Documentation/translations/zh_CN/mm/numa.rst b/Documentation/translations/zh_CN/mm/numa.rst new file mode 100644 index 000000000000..b15cfeeb6dfb --- /dev/null +++ b/Documentation/translations/zh_CN/mm/numa.rst @@ -0,0 +1,101 @@ +:Original: Documentation/mm/numa.rst + +:翻译: + + 司延腾 Yanteng Si <siyanteng@loongson.cn> + +:校译: + + +始于1999年11月，作者： <kanoj@sgi.com> + +========================== +何为非统一内存访问(NUMA)？ +========================== + +这个问题可以从几个视角来回答：硬件观点和Linux软件视角。 + +从硬件角度看，NUMA系统是一个由多个组件或装配组成的计算机平台，每个组件可能包含0个或更多的CPU、 +本地内存和/或IO总线。为了简洁起见，并将这些物理组件/装配的硬件视角与软件抽象区分开来，我们在 +本文中称这些组件/装配为“单元”。 + +每个“单元”都可以看作是系统的一个SMP[对称多处理器]子集——尽管独立的SMP系统所需的一些组件可能 +不会在任何给定的单元上填充。NUMA系统的单元通过某种系统互连连接在一起——例如，交叉开关或点对点 +链接是NUMA系统互连的常见类型。这两种类型的互连都可以聚合起来，以创建NUMA平台，其中的单元与其 +他单元有多个距离。 + +对于Linux，感兴趣的NUMA平台主要是所谓的缓存相干NUMA--简称ccNUMA系统系统。在ccNUMA系统中， +所有的内存都是可见的，并且可以从连接到任何单元的任何CPU中访问，缓存一致性是由处理器缓存和/或 +系统互连在硬件中处理。 + +内存访问时间和有效的内存带宽取决于包含CPU的单元或进行内存访问的IO总线距离包含目标内存的单元 +有多远。例如，连接到同一单元的CPU对内存的访问将比访问其他远程单元的内存经历更快的访问时间和 +更高的带宽。 NUMA平台可以在任何给定单元上访问多种远程距离的（其他）单元。 + +平台供应商建立NUMA系统并不只是为了让软件开发人员的生活变得有趣。相反，这种架构是提供可扩展 +内存带宽的一种手段。然而，为了实现可扩展的内存带宽，系统和应用软件必须安排大部分的内存引用 +[cache misses]到“本地”内存——同一单元的内存，如果有的话——或者到最近的有内存的单元。 + +这就自然而然有了Linux软件对NUMA系统的视角: + +Linux将系统的硬件资源划分为多个软件抽象，称为“节点”。Linux将节点映射到硬件平台的物理单元 +上，对一些架构的细节进行了抽象。与物理单元一样，软件节点可能包含0或更多的CPU、内存和/或IO +总线。同样，对“较近”节点的内存访问——映射到较近单元的节点——通常会比对较远单元的访问经历更快 +的访问时间和更高的有效带宽。 + +对于一些架构，如x86，Linux将“隐藏”任何代表没有内存连接的物理单元的节点，并将连接到该单元 +的任何CPU重新分配到代表有内存的单元的节点上。因此，在这些架构上，我们不能假设Linux将所有 +的CPU与一个给定的节点相关联，会看到相同的本地内存访问时间和带宽。 + +此外，对于某些架构，同样以x86为例，Linux支持对额外节点的仿真。对于NUMA仿真，Linux会将现 +有的节点或者非NUMA平台的系统内存分割成多个节点。每个模拟的节点将管理底层单元物理内存的一部 +分。NUMA仿真对于在非NUMA平台上测试NUMA内核和应用功能是非常有用的，当与cpusets一起使用时， +可以作为一种内存资源管理机制。[见 Documentation/admin-guide/cgroup-v1/cpusets.rst] + +对于每个有内存的节点，Linux构建了一个独立的内存管理子系统，有自己的空闲页列表、使用中页列表、 +使用统计和锁来调解访问。此外，Linux为每个内存区[DMA、DMA32、NORMAL、HIGH_MEMORY、MOVABLE +中的一个或多个]构建了一个有序的“区列表”。zonelist指定了当一个选定的区/节点不能满足分配请求 +时要访问的区/节点。当一个区没有可用的内存来满足请求时，这种情况被称为“overflow 溢出”或 +“fallback 回退”。 + +由于一些节点包含多个包含不同类型内存的区，Linux必须决定是否对区列表进行排序，使分配回退到不同 +节点上的相同区类型，或同一节点上的不同区类型。这是一个重要的考虑因素，因为有些区，如DMA或DMA32， +代表了相对稀缺的资源。Linux选择了一个默认的Node ordered zonelist。这意味着在使用按NUMA距 +离排序的远程节点之前，它会尝试回退到同一节点的其他分区。 + +默认情况下，Linux会尝试从执行请求的CPU被分配到的节点中满足内存分配请求。具体来说，Linux将试 +图从请求来源的节点的适当分区列表中的第一个节点进行分配。这被称为“本地分配”。如果“本地”节点不能 +满足请求，内核将检查所选分区列表中其他节点的区域，寻找列表中第一个能满足请求的区域。 + +本地分配将倾向于保持对分配的内存的后续访问 “本地”的底层物理资源和系统互连——只要内核代表其分配 +一些内存的任务后来不从该内存迁移。Linux调度器知道平台的NUMA拓扑结构——体现在“调度域”数据结构 +中[见 Documentation/scheduler/sched-domains.rst]——并且调度器试图尽量减少任务迁移到遥 +远的调度域中。然而，调度器并没有直接考虑到任务的NUMA足迹。因此，在充分不平衡的情况下，任务可 +以在节点之间迁移，远离其初始节点和内核数据结构。 + +系统管理员和应用程序设计者可以使用各种CPU亲和命令行接口，如taskset(1)和numactl(1)，以及程 +序接口，如sched_setaffinity(2)，来限制任务的迁移，以改善NUMA定位。此外，人们可以使用 +Linux NUMA内存策略修改内核的默认本地分配行为。 [见 +:ref:`Documentation/admin-guide/mm/numa_memory_policy.rst <numa_memory_policy>`]. + +系统管理员可以使用控制组和CPUsets限制非特权用户在调度或NUMA命令和功能中可以指定的CPU和节点 +的内存。 [见 Documentation/admin-guide/cgroup-v1/cpusets.rst] + +在不隐藏无内存节点的架构上，Linux会在分区列表中只包括有内存的区域[节点]。这意味着对于一个无 +内存的节点，“本地内存节点”——CPU节点的分区列表中的第一个区域的节点——将不是节点本身。相反，它 +将是内核在建立分区列表时选择的离它最近的有内存的节点。所以，默认情况下，本地分配将由内核提供 +最近的可用内存来完成。这是同一机制的结果，该机制允许这种分配在一个包含内存的节点溢出时回退到 +其他附近的节点。 + +一些内核分配不希望或不能容忍这种分配回退行为。相反，他们想确保他们从指定的节点获得内存，或者 +得到通知说该节点没有空闲内存。例如，当一个子系统分配每个CPU的内存资源时，通常是这种情况。 + +一个典型的分配模式是使用内核的numa_node_id()或CPU_to_node()函数获得“当前CPU”所在节点的 +节点ID，然后只从返回的节点ID请求内存。当这样的分配失败时，请求的子系统可以恢复到它自己的回退 +路径。板块内核内存分配器就是这样的一个例子。或者，子系统可以选择在分配失败时禁用或不启用自己。 +内核分析子系统就是这样的一个例子。 + +如果架构支持——不隐藏无内存节点，那么连接到无内存节点的CPU将总是产生回退路径的开销，或者一些 +子系统如果试图完全从无内存的节点分配内存，将无法初始化。为了透明地支持这种架构，内核子系统可 +以使用numa_mem_id()或cpu_to_mem()函数来定位调用或指定CPU的“本地内存节点”。同样，这是同 +一个节点，默认的本地页分配将从这个节点开始尝试。 diff --git a/Documentation/translations/zh_CN/mm/overcommit-accounting.rst b/Documentation/translations/zh_CN/mm/overcommit-accounting.rst new file mode 100644 index 000000000000..d8452d8b7fbb --- /dev/null +++ b/Documentation/translations/zh_CN/mm/overcommit-accounting.rst @@ -0,0 +1,86 @@ +:Original: Documentation/mm/overcommit-accounting.rst + +:翻译: + + 司延腾 Yanteng Si <siyanteng@loongson.cn> + +:校译: + + + +============== +超量使用审计 +============== + +Linux内核支持下列超量使用处理模式 + +0 + 启发式超量使用处理。拒绝明显的地址空间超量使用。用于一个典型的系统。 + 它确保严重的疯狂分配失败，同时允许超量使用以减少swap的使用。在这种模式下， + 允许root分配稍多的内存。这是默认的。 +1 + 总是超量使用。适用于一些科学应用。经典的例子是使用稀疏数组的代码，只是依赖 + 几乎完全由零页组成的虚拟内存 + +2 + 不超量使用。系统提交的总地址空间不允许超过swap+一个可配置的物理RAM的数量 + （默认为50%）。根据你使用的数量，在大多数情况下，这意味着一个进程在访问页面时 + 不会被杀死，但会在内存分配上收到相应的错误。 + + 对于那些想保证他们的内存分配在未来可用而又不需要初始化每一个页面的应用程序来说 + 是很有用的。 + +超量使用策略是通过sysctl `vm.overcommit_memory` 设置的。 + +可以通过 `vm.overcommit_ratio` （百分比）或 `vm.overcommit_kbytes` （绝对值） +来设置超限数量。这些只有在 `vm.overcommit_memory` 被设置为2时才有效果。 + +在 ``/proc/meminfo`` 中可以分别以CommitLimit和Committed_AS的形式查看当前 +的超量使用和提交量。 + +陷阱 +==== + +C语言的堆栈增长是一个隐含的mremap。如果你想得到绝对的保证，并在接近边缘的地方运行， +你 **必须** 为你认为你需要的最大尺寸的堆栈进行mmap。对于典型的堆栈使用来说，这并 +不重要，但如果你真的非常关心的话，这就是一个值得关注的案例。 + + +在模式2中，MAP_NORESERVE标志被忽略。 + + +它是如何工作的 +============== + +超量使用是基于以下规则 + +对于文件映射 + | SHARED or READ-only - 0 cost (该文件是映射而不是交换) + | PRIVATE WRITABLE - 每个实例的映射大小 + +对于匿名或者 ``/dev/zero`` 映射 + | SHARED - 映射的大小 + | PRIVATE READ-only - 0 cost (但作用不大) + | PRIVATE WRITABLE - 每个实例的映射大小 + +额外的计数 + | 通过mmap制作可写副本的页面 + | 从同一池中提取的shmfs内存 + +状态 +==== + +* 我们核算mmap内存映射 +* 我们核算mprotect在提交中的变化 +* 我们核算mremap的大小变化 +* 我们的审计 brk +* 审计munmap +* 我们在/proc中报告commit 状态 +* 核对并检查分叉的情况 +* 审查堆栈处理/执行中的构建 +* 叙述SHMfs的情况 +* 实现实际限制的执行 + +待续 +==== +* ptrace 页计数（这很难）。 diff --git a/Documentation/translations/zh_CN/mm/page_frags.rst b/Documentation/translations/zh_CN/mm/page_frags.rst new file mode 100644 index 000000000000..20bd3fafdc8c --- /dev/null +++ b/Documentation/translations/zh_CN/mm/page_frags.rst @@ -0,0 +1,38 @@ +:Original: Documentation/mm/page_frags.rst + +:翻译: + + 司延腾 Yanteng Si <siyanteng@loongson.cn> + +:校译: + + +======== +页面片段 +======== + +一个页面片段是一个任意长度的任意偏移的内存区域，它位于一个0或更高阶的复合页面中。 +该页中的多个碎片在该页的引用计数器中被单独计算。 + +page_frag函数，page_frag_alloc和page_frag_free，为页面片段提供了一个简单 +的分配框架。这被网络堆栈和网络设备驱动使用，以提供一个内存的支持区域，作为 +sk_buff->head使用，或者用于skb_shared_info的 “frags” 部分。 + +为了使用页面片段API，需要一个支持页面片段的缓冲区。这为碎片分配提供了一个中心点， +并允许多个调用使用一个缓存的页面。这样做的好处是可以避免对get_page的多次调用， +这在分配时开销可能会很大。然而，由于这种缓存的性质，要求任何对缓存的调用都要受到每 +个CPU的限制，或者每个CPU的限制，并在执行碎片分配时强制禁止中断。 + +网络堆栈在每个CPU使用两个独立的缓存来处理碎片分配。netdev_alloc_cache被使用 +netdev_alloc_frag和__netdev_alloc_skb调用的调用者使用。napi_alloc_cache +被调用__napi_alloc_frag和__napi_alloc_skb的调用者使用。这两个调用的主要区别是 +它们可能被调用的环境。“netdev” 前缀的函数可以在任何上下文中使用，因为这些函数 +将禁用中断，而 ”napi“ 前缀的函数只可以在softirq上下文中使用。 + +许多网络设备驱动程序使用类似的方法来分配页面片段，但页面片段是在环或描述符级别上 +缓存的。为了实现这些情况，有必要提供一种拆解页面缓存的通用方法。出于这个原因， +__page_frag_cache_drain被实现了。它允许通过一次调用从一个页面释放多个引用。 +这样做的好处是，它允许清理被添加到一个页面的多个引用，以避免每次分配都调用 +get_page。 + +Alexander Duyck，2016年11月29日。 diff --git a/Documentation/translations/zh_CN/mm/page_migration.rst b/Documentation/translations/zh_CN/mm/page_migration.rst new file mode 100644 index 000000000000..076081dc1635 --- /dev/null +++ b/Documentation/translations/zh_CN/mm/page_migration.rst @@ -0,0 +1,228 @@ +.. include:: ../disclaimer-zh_CN.rst + +:Original: Documentation/mm/page_migration.rst + +:翻译: + + 司延腾 Yanteng Si <siyanteng@loongson.cn> + +:校译: + +======== +页面迁移 +======== + +页面迁移允许在进程运行时在NUMA系统的节点之间移动页面的物理位置。这意味着进程所看到的虚拟地 +址并没有改变。然而，系统会重新安排这些页面的物理位置。 + +也可以参见 :ref: `<异构内存管理 (HMM)>` 以了解将页面迁移到设备私有内存或从设备私有内存中迁移。 + +页面迁移的主要目的是通过将页面移到访问该内存的进程所运行的处理器附近来减少内存访问的延迟。 + +页面迁移允许进程通过MF_MOVE和MF_MOVE_ALL选项手动重新定位其页面所在的节点，同时通过 +mbind()设置一个新的内存策略。一个进程的页面也可以通过sys_migrate_pages()函数调用从另 +一个进程重新定位。migrate_pages()函数调用接收两组节点，并将一个进程位于旧节点上的页面移 +动到目标节点上。页面迁移功能由Andi Kleen的numactl包提供(需要0.9.3以上的版本，其仓库 +地址https://github.com/numactl/numactl.git)。numactl提供了libnuma，它为页面迁移 +提供了与其他NUMA功能类似的接口。执行 cat ``/proc/<pid>/numa_maps`` 允许轻松查看进 +程的页面位置。参见proc(5)手册中的numa_maps文档。 + +如果调度程序将一个进程重新安置到一个遥远的节点上的处理器，手动迁移是很有用的。批量调度程序 +或管理员可以检测到这种情况，并将进程的页面移到新处理器附近。内核本身只提供手动的页迁移支持。 +自动的页面迁移可以通过用户空间的进程移动页面来实现。一个特殊的函数调用 "move_pages" 允许 +在一个进程中移动单个页面。例如，NUMA分析器可以获得一个显示频繁的节点外访问的日志，并可以使 +用这个结果将页面移动到更有利的位置。 + +较大型的设备通常使用cpusets将系统分割成若干个节点。Paul Jackson为cpusets配备了当任务被 +转移到另一个cpuset时移动页面的能力(见:ref:`CPUSETS <cpusets>`)。Cpusets允许进程定 +位的自动化。如果一个任务被移到一个新的cpuset上，那么它的所有页面也会随之移动，这样进程的 +性能就不会急剧下降。如果cpuset允许的内存节点发生变化，cpuset中的进程页也会被移动。 + +页面迁移允许为所有迁移技术保留一组节点中页面的相对位置，这将保留生成的特定内存分配模式即使 +进程已被迁移。为了保留内存延迟，这一点是必要的。迁移后的进程将以类似的性能运行。 + +页面迁移分几个步骤进行。首先为那些试图从内核中使用migrate_pages()的进程做一个高层次的 +描述（对于用户空间的使用，可以参考上面提到的Andi Kleen的numactl包），然后对低水平的细 +节工作做一个低水平描述。 + +在内核中使用 migrate_pages() +============================ + +1. 从LRU中移除页面。 + + 要迁移的页面列表是通过扫描页面并把它们移到列表中来生成的。这是通过调用 isolate_lru_page() + 来完成的。调用isolate_lru_page()增加了对该页的引用，这样在页面迁移发生时它就不会 + 消失。它还可以防止交换器或其他扫描器遇到该页。 + + +2. 我们需要有一个new_page_t类型的函数，可以传递给migrate_pages()。这个函数应该计算 + 出如何在给定的旧页面中分配正确的新页面。 + +3. migrate_pages()函数被调用，它试图进行迁移。它将调用该函数为每个被考虑迁移的页面分 + 配新的页面。 + +migrate_pages()如何工作 +======================= + +migrate_pages()对它的页面列表进行了多次处理。如果当时对一个页面的所有引用都可以被移除， +那么这个页面就会被移动。该页已经通过isolate_lru_page()从LRU中移除，并且refcount被 +增加，以便在页面迁移发生时不释放该页。 + +步骤: + +1. 锁定要迁移的页面。 + +2. 确保回写已经完成。 + +3. 锁定我们要迁移到的新页面。锁定它是为了在迁移过程中立即阻止对这个（尚未更新的）页面的 + 访问。 + +4. 所有对该页的页表引用都被转换为迁移条目。这就减少了一个页面的mapcount。如果产生的 + mapcount不是零，那么我们就不迁移该页。所有试图访问该页的用户空间进程现在将等待页 + 面锁或者等待迁移页表项被移除。 + +5. i_pages的锁被持有。这将导致所有试图通过映射访问该页的进程在自旋锁上阻塞。 + +6. 检查该页的Refcount，如果还有引用，我们就退出。否则，我们知道我们是唯一引用这个页 + 面的人。 + +7. 检查基数树，如果它不包含指向这个页面的指针，那么我们就退出，因为其他人修改了基数树。 + +8. 新的页面要用旧的页面的一些设置进行预处理，这样访问新的页面就会发现一个具有正确设置 + 的页面。 + +9. 基数树被改变以指向新的页面。 + +10. 旧页的引用计数被删除，因为地址空间的引用已经消失。对新页的引用被建立，因为新页被 + 地址空间引用。 + +11. i_pages锁被放弃。这样一来，在映射中的查找又变得可能了。进程将从在锁上自旋到在 + 被锁的新页上睡眠。 + +12. 页面内容被复制到新的页面上。 + +13. 剩余的页面标志被复制到新的页面上。 + +14. 旧的页面标志被清除，以表明该页面不再提供任何信息。 + +15. 新页面上的回写队列被触发了。 + +16. 如果迁移条目被插入到页表中，那么就用真正的ptes替换它们。这样做将使那些尚未等待页 + 锁的用户空间进程能够访问。 + +17. 页面锁从新旧页面上被撤销。等待页锁的进程将重做他们的缺页异常，并将到达新的页面。 + +18. 新的页面被移到LRU中，可以被交换器等再次扫描。 + +非LRU页面迁移 +============= + +尽管迁移最初的目的是为了减少NUMA的内存访问延迟，但压缩也使用迁移来创建高阶页面。 + +目前实现的问题是，它被设计为只迁移*LRU*页。然而，有一些潜在的非LRU页面可以在驱动中 +被迁移，例如，zsmalloc，virtio-balloon页面。 + +对于virtio-balloon页面，迁移代码路径的某些部分已经被钩住，并添加了virtio-balloon +的特定函数来拦截迁移逻辑。这对一个驱动来说太特殊了，所以其他想让自己的页面可移动的驱 +动就必须在迁移路径中添加自己的特定钩子。 + +为了克服这个问题，VM支持非LRU页面迁移，它为非LRU可移动页面提供了通用函数，而在迁移 +路径中没有特定的驱动程序钩子。 + +如果一个驱动程序想让它的页面可移动，它应该定义三个函数，这些函数是 +struct address_space_operations的函数指针。 + +1. ``bool (*isolate_page) (struct page *page, isolate_mode_t mode);`` + + VM对驱动的isolate_page()函数的期望是，如果驱动成功隔离了该页，则返回*true*。 + 返回true后，VM会将该页标记为PG_isolated，这样多个CPU的并发隔离就会跳过该 + 页进行隔离。如果驱动程序不能隔离该页，它应该返回*false*。 + + 一旦页面被成功隔离，VM就会使用page.lru字段，因此驱动程序不应期望保留这些字段的值。 + +2. ``int (*migratepage) (struct address_space *mapping,`` +| ``struct page *newpage, struct page *oldpage, enum migrate_mode);`` + + 隔离后，虚拟机用隔离的页面调用驱动的migratepage()。migratepage()的功能是将旧页 + 的内容移动到新页，并设置struct page newpage的字段。请记住，如果你成功迁移了旧页 + 并返回MIGRATEPAGE_SUCCESS，你应该通过page_lock下的__ClearPageMovable()向虚 + 拟机表明旧页不再可移动。如果驱动暂时不能迁移该页，驱动可以返回-EAGAIN。在-EAGAIN + 时，VM会在短时间内重试页面迁移，因为VM将-EAGAIN理解为 "临时迁移失败"。在返回除 + -EAGAIN以外的任何错误时，VM将放弃页面迁移而不重试。 + + 在migratepage()函数中，驱动程序不应该接触page.lru字段。 + +3. ``void (*putback_page)(struct page *);`` + + 如果在隔离页上迁移失败，VM应该将隔离页返回给驱动，因此VM用隔离页调用驱动的 + putback_page()。在这个函数中，驱动应该把隔离页放回自己的数据结构中。 + +非LRU可移动页标志 + + 有两个页面标志用于支持非LRU可移动页面。 + + * PG_movable + + 驱动应该使用下面的函数来使页面在page_lock下可移动。:: + + void __SetPageMovable(struct page *page, struct address_space *mapping) + + 它需要address_space的参数来注册将被VM调用的migration family函数。确切地说， + PG_movable不是struct page的一个真正的标志。相反，VM复用了page->mapping的低 + 位来表示它:: + + #define PAGE_MAPPING_MOVABLE 0x2 + page->mapping = page->mapping | PAGE_MAPPING_MOVABLE; + + 所以驱动不应该直接访问page->mapping。相反，驱动应该使用page_mapping()，它可 + 以在页面锁下屏蔽掉page->mapping的低2位，从而获得正确的struct address_space。 + + 对于非LRU可移动页面的测试，VM支持__PageMovable()函数。然而，它并不能保证识别 + 非LRU可移动页面，因为page->mapping字段与struct page中的其他变量是统一的。如 + 果驱动程序在被虚拟机隔离后释放了页面，尽管page->mapping设置了PAGE_MAPPING_MOVABLE， + 但它并没有一个稳定的值（看看__ClearPageMovable）。但是__PageMovable()在页 + 面被隔离后，无论页面是LRU还是非LRU可移动的，调用它开销都很低，因为LRU页面在 + page->mapping中不可能有PAGE_MAPPING_MOVABLE设置。在用pfn扫描中的lock_page() + 进行更大开销的检查来选择受害者之前，它也很适合只是瞥一眼来测试非LRU可移动的页面。 + + 为了保证非LRU的可移动页面，VM提供了PageMovable()函数。与__PageMovable()不 + 同，PageMovable()在lock_page()下验证page->mapping和 + mapping->a_ops->isolate_page。lock_page()可以防止突然破坏page->mapping。 + + 使用__SetPageMovable()的驱动应该在释放页面之前通过page_lock()下的 + __ClearMovablePage()清除该标志。 + + * PG_isolated + + 为了防止几个CPU同时进行隔离，VM在lock_page()下将隔离的页面标记为PG_isolated。 + 因此，如果一个CPU遇到PG_isolated非LRU可移动页面，它可以跳过它。驱动程序不需要 + 操作这个标志，因为VM会自动设置/清除它。请记住，如果驱动程序看到PG_isolated页， + 这意味着该页已经被VM隔离，所以它不应该碰page.lru字段。PG_isolated标志与 + PG_reclaim标志是同义的，所以驱动程序不应该为自己的目的使用PG_isolated。 + +监测迁移 +======== + +以下事件（计数器）可用于监控页面迁移。 + +1. PGMIGRATE_SUCCESS: 正常的页面迁移成功。每个计数器意味着一个页面被迁移了。如果该 + 页是一个非THP和非hugetlb页，那么这个计数器会增加1。如果该页面是一个THP或hugetlb + 页面，那么这个计数器会随着THP或hugetlb子页面的数量而增加。例如，迁移一个有4KB大小 + 的基础页（子页）的2MB THP，将导致这个计数器增加512。 + +2. PGMIGRATE_FAIL: 正常的页面迁移失败。与上面PGMIGRATE_SUCCESS的计数规则相同：如 + 果是THP或hugetlb，这个计数将被子页的数量增加。 + +3. THP_MIGRATION_SUCCESS: 一个THP被迁移而没有被分割。 + +4. THP_MIGRATION_FAIL: 一个THP不能被迁移，也不能被分割。 + +5. THP_MIGRATION_SPLIT: 一个THP被迁移了，但不是这样的：首先，这个THP必须被分割。 + 在拆分之后，对它的子页面进行了迁移重试。 + +THP_MIGRATION_* 事件也会更新相应的PGMIGRATE_SUCCESS或PGMIGRATE_FAIL事件。 +例如，一个THP迁移失败将导致THP_MIGRATION_FAIL和PGMIGRATE_FAIL增加。 + +Christoph Lameter，2006年5月8日。 + +Minchan Kim，2016年3月28日。 diff --git a/Documentation/translations/zh_CN/mm/page_owner.rst b/Documentation/translations/zh_CN/mm/page_owner.rst new file mode 100644 index 000000000000..21a6a0837d42 --- /dev/null +++ b/Documentation/translations/zh_CN/mm/page_owner.rst @@ -0,0 +1,181 @@ +:Original: Documentation/mm/page_owner.rst + +:翻译: + + 司延腾 Yanteng Si <siyanteng@loongson.cn> + +:校译: + + +================================ +page owner: 跟踪谁分配的每个页面 +================================ + +概述 +==== + +page owner是用来追踪谁分配的每一个页面。它可以用来调试内存泄漏或找到内存占用者。 +当分配发生时，有关分配的信息，如调用堆栈和页面的顺序被存储到每个页面的特定存储中。 +当我们需要了解所有页面的状态时，我们可以获得并分析这些信息。 + +尽管我们已经有了追踪页面分配/释放的tracepoint，但用它来分析谁分配的每个页面是 +相当复杂的。我们需要扩大跟踪缓冲区，以防止在用户空间程序启动前出现重叠。而且，启 +动的程序会不断地将跟踪缓冲区转出，供以后分析，这将会改变系统的行为，会产生更多的 +可能性，而不是仅仅保留在内存中，所以不利于调试。 + +页面所有者也可以用于各种目的。例如，可以通过每个页面的gfp标志信息获得精确的碎片 +统计。如果启用了page owner，它就已经实现并激活了。我们非常欢迎其他用途。 + +page owner在默认情况下是禁用的。所以，如果你想使用它，你需要在你的启动cmdline +中加入"page_owner=on"。如果内核是用page owner构建的，并且由于没有启用启动 +选项而在运行时禁用page owner，那么运行时的开销是很小的。如果在运行时禁用，它不 +需要内存来存储所有者信息，所以没有运行时内存开销。而且，页面所有者在页面分配器的 +热路径中只插入了两个不可能的分支，如果不启用，那么分配就会像没有页面所有者的内核 +一样进行。这两个不可能的分支应该不会影响到分配的性能，特别是在静态键跳转标签修补 +功能可用的情况下。以下是由于这个功能而导致的内核代码大小的变化。 + +- 没有page owner:: + + text data bss dec hex filename + 48392 2333 644 51369 c8a9 mm/page_alloc.o + +- 有page owner:: + + text data bss dec hex filename + 48800 2445 644 51889 cab1 mm/page_alloc.o + 6662 108 29 6799 1a8f mm/page_owner.o + 1025 8 8 1041 411 mm/page_ext.o + +虽然总共增加了8KB的代码，但page_alloc.o增加了520字节，其中不到一半是在hotpath +中。构建带有page owner的内核，并在需要时打开它，将是调试内核内存问题的最佳选择。 + +有一个问题是由实现细节引起的。页所有者将信息存储到struct page扩展的内存中。这 +个内存的初始化时间比稀疏内存系统中的页面分配器启动的时间要晚一些，所以，在初始化 +之前，许多页面可以被分配，但它们没有所有者信息。为了解决这个问题，这些早期分配的 +页面在初始化阶段被调查并标记为分配。虽然这并不意味着它们有正确的所有者信息，但至 +少，我们可以更准确地判断该页是否被分配。在2GB内存的x86-64虚拟机上，有13343 +个早期分配的页面被捕捉和标记，尽管它们大部分是由结构页扩展功能分配的。总之，在这 +之后，没有任何页面处于未追踪状态。 + +使用方法 +======== + +1) 构建用户空间的帮助:: + + cd tools/vm + make page_owner_sort + +2) 启用page owner: 添加 "page_owner=on" 到 boot cmdline. + +3) 做你想调试的工作。 + +4) 分析来自页面所有者的信息:: + + cat /sys/kernel/debug/page_owner > page_owner_full.txt + ./page_owner_sort page_owner_full.txt sorted_page_owner.txt + + ``page_owner_full.txt`` 的一般输出情况如下:: + + Page allocated via order XXX, ... + PFN XXX ... + // 栈详情 + + Page allocated via order XXX, ... + PFN XXX ... + // 栈详情 + 默认情况下，它将以一个给定的pfn开始，做完整的pfn转储，且page_owner支持fseek。 + + FILE *fp = fopen("/sys/kernel/debug/page_owner", "r"); + fseek(fp, pfn_start, SEEK_SET); + + ``page_owner_sort`` 工具忽略了 ``PFN`` 行，将剩余的行放在buf中，使用regexp提 + 取页序值，计算buf的次数和页数，最后根据参数进行排序。 + + 在 ``sorted_page_owner.txt`` 中可以看到关于谁分配了每个页面的结果。一般输出:: + + XXX times, XXX pages: + Page allocated via order XXX, ... + // Detailed stack + + 默认情况下， ``page_owner_sort`` 是根据buf的时间来排序的。如果你想 + 按buf的页数排序，请使用-m参数。详细的参数是: + + 基本函数:: + + 排序: + -a 按内存分配时间排序 + -m 按总内存排序 + -p 按pid排序。 + -P 按tgid排序。 + -n 按任务命令名称排序。 + -r 按内存释放时间排序。 + -s 按堆栈跟踪排序。 + -t 按时间排序（默认）。 + --sort <order> 指定排序顺序。排序的语法是[+|-]key[,[+|-]key[,...]]。从 + **标准格式指定器**那一节选择一个键。"+"是可选的，因为默认的方向是数字或 + 词法的增加。允许混合使用缩写和完整格式的键。 + + 例子: + ./page_owner_sort <input> <output> --sort=n,+pid,-tgid + ./page_owner_sort <input> <output> --sort=at + + 其它函数:: + + 剔除: + --cull <rules> + 指定剔除规则。剔除的语法是key[,key[,...]]。从**标准格式指定器** + 部分选择一个多字母键。 + <rules>是一个以逗号分隔的列表形式的单一参数，它提供了一种指定单个剔除规则的 + 方法。 识别的关键字在下面的**标准格式指定器**部分有描述。<规则>可以通过键的 + 序列k1,k2,...来指定，在下面的标准排序键部分有描述。允许混合使用简写和完整形 + 式的键。 + + Examples: + ./page_owner_sort <input> <output> --cull=stacktrace + ./page_owner_sort <input> <output> --cull=st,pid,name + ./page_owner_sort <input> <output> --cull=n,f + + 过滤: + -f 过滤掉内存已被释放的块的信息。 + + 选择: + --pid <pidlist> 按pid选择。这将选择进程ID号出现在<pidlist>中的块。 + --tgid <tgidlist> 按tgid选择。这将选择其线程组ID号出现在<tgidlist> + 中的块。 + --name <cmdlist> 按任务命令名称选择。这将选择其任务命令名称出现在 + <cmdlist>中的区块。 + + <pidlist>, <tgidlist>, <cmdlist>是以逗号分隔的列表形式的单个参数， + 它提供了一种指定单个选择规则的方法。 + + + 例子: + ./page_owner_sort <input> <output> --pid=1 + ./page_owner_sort <input> <output> --tgid=1,2,3 + ./page_owner_sort <input> <output> --name name1,name2 + +标准格式指定器 +============== +:: + + --sort的选项: + + 短键 长键 描述 + p pid 进程ID + tg tgid 线程组ID + n name 任务命令名称 + st stacktrace 页面分配的堆栈跟踪 + T txt 块的全文 + ft free_ts 页面释放时的时间戳 + at alloc_ts 页面被分配时的时间戳 + ator allocator 页面的内存分配器 + + --curl的选项: + + 短键 长键 描述 + p pid 进程ID + tg tgid 线程组ID + n name 任务命令名称 + f free 该页是否已经释放 + st stacktrace 页面分配的堆栈跟踪 + ator allocator 页面的内存分配器 diff --git a/Documentation/translations/zh_CN/mm/page_table_check.rst b/Documentation/translations/zh_CN/mm/page_table_check.rst new file mode 100644 index 000000000000..e8077310a76c --- /dev/null +++ b/Documentation/translations/zh_CN/mm/page_table_check.rst @@ -0,0 +1,56 @@ +.. SPDX-License-Identifier: GPL-2.0 + +:Original: Documentation/mm/page_table_check.rst + +:翻译: + + 司延腾 Yanteng Si <siyanteng@loongson.cn> + +:校译: + + +======== +页表检查 +======== + +概述 +==== + +页表检查允许通过确保防止某些类型的内存损坏来强化内核。 + +当新的页面可以从用户空间访问时，页表检查通过将它们的页表项（PTEs PMD等）添加到页表中来执行额外 +的验证。 + +在检测到损坏的情况下，内核会被崩溃。页表检查有一个小的性能和内存开销。因此，它在默认情况下是禁用 +的，但是在额外的加固超过性能成本的系统上，可以选择启用。另外，由于页表检查是同步的，它可以帮助调 +试双映射内存损坏问题，在错误的映射发生时崩溃内核，而不是在内存损坏错误发生后内核崩溃。 + +双重映射检测逻辑 +================ + ++-------------------+-------------------+-------------------+------------------+ +| Current Mapping | New mapping | Permissions | Rule | ++===================+===================+===================+==================+ +| Anonymous | Anonymous | Read | Allow | ++-------------------+-------------------+-------------------+------------------+ +| Anonymous | Anonymous | Read / Write | Prohibit | ++-------------------+-------------------+-------------------+------------------+ +| Anonymous | Named | Any | Prohibit | ++-------------------+-------------------+-------------------+------------------+ +| Named | Anonymous | Any | Prohibit | ++-------------------+-------------------+-------------------+------------------+ +| Named | Named | Any | Allow | ++-------------------+-------------------+-------------------+------------------+ + +启用页表检查 +============ + +用以下方法构建内核: + +- PAGE_TABLE_CHECK=y + 注意，它只能在ARCH_SUPPORTS_PAGE_TABLE_CHECK可用的平台上启用。 + +- 使用 "page_table_check=on" 内核参数启动。 + +可以选择用PAGE_TABLE_CHECK_ENFORCED来构建内核，以便在没有额外的内核参数的情况下获得页表 +支持。 diff --git a/Documentation/translations/zh_CN/mm/remap_file_pages.rst b/Documentation/translations/zh_CN/mm/remap_file_pages.rst new file mode 100644 index 000000000000..31e0c54dc36f --- /dev/null +++ b/Documentation/translations/zh_CN/mm/remap_file_pages.rst @@ -0,0 +1,32 @@ +:Original: Documentation/mm/remap_file_pages.rst + +:翻译: + + 司延腾 Yanteng Si <siyanteng@loongson.cn> + +:校译: + + +============================== +remap_file_pages()系统调用 +============================== + +remap_file_pages()系统调用被用来创建一个非线性映射，也就是说，在这个映射中， +文件的页面被无序映射到内存中。使用remap_file_pages()比重复调用mmap(2)的好 +处是，前者不需要内核创建额外的VMA（虚拟内存区）数据结构。 + +支持非线性映射需要在内核虚拟内存子系统中编写大量的non-trivial的代码，包括热 +路径。另外，为了使非线性映射工作，内核需要一种方法来区分正常的页表项和带有文件 +偏移的项（pte_file）。内核为达到这个目的在PTE中保留了标志。PTE标志是稀缺资 +源，特别是在某些CPU架构上。如果能腾出这个标志用于其他用途就更好了。 + +幸运的是，在生活中并没有很多remap_file_pages()的用户。只知道有一个企业的RDBMS +实现在32位系统上使用这个系统调用来映射比32位虚拟地址空间线性尺寸更大的文件。 +由于64位系统的广泛使用，这种使用情况已经不重要了。 + +syscall被废弃了，现在用一个模拟来代替它。仿真会创建新的VMA，而不是非线性映射。 +对于remap_file_pages()的少数用户来说，它的工作速度会变慢，但ABI被保留了。 + +仿真的一个副作用（除了性能之外）是，由于额外的VMA，用户可以更容易达到 +vm.max_map_count的限制。关于限制的更多细节，请参见DEFAULT_MAX_MAP_COUNT +的注释。 diff --git a/Documentation/translations/zh_CN/mm/split_page_table_lock.rst b/Documentation/translations/zh_CN/mm/split_page_table_lock.rst new file mode 100644 index 000000000000..4fb7aa666037 --- /dev/null +++ b/Documentation/translations/zh_CN/mm/split_page_table_lock.rst @@ -0,0 +1,96 @@ +:Original: Documentation/mm/split_page_table_lock.rst + +:翻译: + + 司延腾 Yanteng Si <siyanteng@loongson.cn> + +:校译: + + +================================= +分页表锁（split page table lock） +================================= + +最初，mm->page_table_lock spinlock保护了mm_struct的所有页表。但是这种方 +法导致了多线程应用程序的缺页异常可扩展性差，因为对锁的争夺很激烈。为了提高可扩 +展性，我们引入了分页表锁。 + +有了分页表锁，我们就有了单独的每张表锁来顺序化对表的访问。目前，我们对PTE和 +PMD表使用分页锁。对高层表的访问由mm->page_table_lock保护。 + +有一些辅助工具来锁定/解锁一个表和其他访问器函数: + + - pte_offset_map_lock() + 映射pte并获取PTE表锁，返回所取锁的指针； + - pte_unmap_unlock() + 解锁和解映射PTE表； + - pte_alloc_map_lock() + 如果需要的话，分配PTE表并获取锁，如果分配失败，返回已获取的锁的指针 + 或NULL； + - pte_lockptr() + 返回指向PTE表锁的指针； + - pmd_lock() + 取得PMD表锁，返回所取锁的指针。 + - pmd_lockptr() + 返回指向PMD表锁的指针； + +如果CONFIG_SPLIT_PTLOCK_CPUS（通常为4）小于或等于NR_CPUS，则在编译 +时启用PTE表的分页表锁。如果分页锁被禁用，所有的表都由mm->page_table_lock +来保护。 + +如果PMD表启用了分页锁，并且架构支持它，那么PMD表的分页锁就会被启用（见 +下文）。 + +Hugetlb 和分页表锁 +================== + +Hugetlb可以支持多种页面大小。我们只对PMD级别使用分页锁，但不对PUD使用。 + +Hugetlb特定的辅助函数: + + - huge_pte_lock() + 对PMD_SIZE页面采取pmd分割锁，否则mm->page_table_lock； + - huge_pte_lockptr() + 返回指向表锁的指针。 + +架构对分页表锁的支持 +==================== + +没有必要特别启用PTE分页表锁：所有需要的东西都由pgtable_pte_page_ctor() +和pgtable_pte_page_dtor()完成，它们必须在PTE表分配/释放时被调用。 + +确保架构不使用slab分配器来分配页表：slab使用page->slab_cache来分配其页 +面。这个区域与page->ptl共享存储。 + +PMD分页锁只有在你有两个以上的页表级别时才有意义。 + +启用PMD分页锁需要在PMD表分配时调用pgtable_pmd_page_ctor()，在释放时调 +用pgtable_pmd_page_dtor()。 + +分配通常发生在pmd_alloc_one()中，释放发生在pmd_free()和pmd_free_tlb() +中，但要确保覆盖所有的PMD表分配/释放路径：即X86_PAE在pgd_alloc()中预先 +分配一些PMD。 + +一切就绪后，你可以设置CONFIG_ARCH_ENABLE_SPLIT_PMD_PTLOCK。 + +注意：pgtable_pte_page_ctor()和pgtable_pmd_page_ctor()可能失败--必 +须正确处理。 + +page->ptl +========= + +page->ptl用于访问分割页表锁，其中'page'是包含该表的页面struct page。它 +与page->private（以及union中的其他几个字段）共享存储。 + +为了避免增加struct page的大小并获得最佳性能，我们使用了一个技巧: + + - 如果spinlock_t适合于long，我们使用page->ptr作为spinlock，这样我们 + 就可以避免间接访问并节省一个缓存行。 + - 如果spinlock_t的大小大于long的大小，我们使用page->ptl作为spinlock_t + 的指针并动态分配它。这允许在启用DEBUG_SPINLOCK或DEBUG_LOCK_ALLOC的 + 情况下使用分页锁，但由于间接访问而多花了一个缓存行。 + +PTE表的spinlock_t分配在pgtable_pte_page_ctor()中，PMD表的spinlock_t +分配在pgtable_pmd_page_ctor()中。 + +请不要直接访问page->ptl - -使用适当的辅助函数。 diff --git a/Documentation/translations/zh_CN/mm/vmalloced-kernel-stacks.rst b/Documentation/translations/zh_CN/mm/vmalloced-kernel-stacks.rst new file mode 100644 index 000000000000..d02a23f7f07e --- /dev/null +++ b/Documentation/translations/zh_CN/mm/vmalloced-kernel-stacks.rst @@ -0,0 +1,133 @@ +.. SPDX-License-Identifier: GPL-2.0 +.. include:: ../disclaimer-zh_CN.rst + +:Original: Documentation/mm/vmalloced-kernel-stacks.rst + +:翻译: + + 司延腾 Yanteng Si <siyanteng@loongson.cn> + +:校译: + +==================== +支持虚拟映射的内核栈 +==================== + +:作者: Shuah Khan <skhan@linuxfoundation.org> + +.. contents:: :local: + +概览 +---- + +这是介绍 `虚拟映射内核栈功能 <https://lwn.net/Articles/694348/>` 的代码 +和原始补丁系列的信息汇总。 + +简介 +---- + +内核堆栈溢出通常难以调试，并使内核容易被（恶意）利用。问题可能在稍后的时间出现，使其难以 +隔离和究其根本原因。 + +带有保护页的虚拟映射内核堆栈如果溢出，会被立即捕获，而不会放任其导致难以诊断的损 +坏。 + +HAVE_ARCH_VMAP_STACK和VMAP_STACK配置选项能够支持带有保护页的虚拟映射堆栈。 +当堆栈溢出时，这个特性会引发可靠的异常。溢出后堆栈跟踪的可用性以及对溢出本身的 +响应取决于架构。 + +.. note:: + 截至本文撰写时， arm64, powerpc, riscv, s390, um, 和 x86 支持VMAP_STACK。 + +HAVE_ARCH_VMAP_STACK +-------------------- + +能够支持虚拟映射内核栈的架构应该启用这个bool配置选项。要求是: + +- vmalloc空间必须大到足以容纳许多内核堆栈。这可能排除了许多32位架构。 +- vmalloc空间的堆栈需要可靠地工作。例如，如果vmap页表是按需创建的，当堆栈指向 + 具有未填充页表的虚拟地址时，这种机制需要工作，或者架构代码（switch_to()和 + switch_mm()，很可能）需要确保堆栈的页表项在可能未填充的堆栈上运行之前已经填 + 充。 +- 如果堆栈溢出到一个保护页，就应该发生一些合理的事情。“合理”的定义是灵活的，但 + 在没有记录任何东西的情况下立即重启是不友好的。 + +VMAP_STACK +---------- + +VMAP_STACK bool配置选项在启用时分配虚拟映射的任务栈。这个选项依赖于 +HAVE_ARCH_VMAP_STACK。 + +- 如果你想使用带有保护页的虚拟映射的内核堆栈，请启用该选项。这将导致内核栈溢出 + 被立即捕获，而不是难以诊断的损坏。 + +.. note:: + + 使用KASAN的这个功能需要架构支持用真实的影子内存来支持虚拟映射，并且 + 必须启用KASAN_VMALLOC。 + +.. note:: + + 启用VMAP_STACK时，无法在堆栈分配的数据上运行DMA。 + +内核配置选项和依赖性不断变化。请参考最新的代码库: + +`Kconfig <https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/arch/Kconfig>` + +分配方法 +-------- + +当一个新的内核线程被创建时，线程堆栈是由页级分配器分配的虚拟连续的内存页组成。这 +些页面被映射到有PAGE_KERNEL保护的连续的内核虚拟空间。 + +alloc_thread_stack_node()调用__vmalloc_node_range()来分配带有PAGE_KERNEL +保护的栈。 + +- 分配的堆栈被缓存起来，以后会被新的线程重用，所以在分配/释放堆栈给任务时，要手动 + 进行memcg核算。因此，__vmalloc_node_range被调用时没有__GFP_ACCOUNT。 +- vm_struct被缓存起来，以便能够找到在中断上下文中启动的空闲线程。 free_thread_stack() + 可以在中断上下文中调用。 +- 在arm64上，所有VMAP的堆栈都需要有相同的对齐方式，以确保VMAP的堆栈溢出检测正常 + 工作。架构特定的vmap堆栈分配器照顾到了这个细节。 +- 这并不涉及中断堆栈--参考原始补丁 + +线程栈分配是由clone()、fork()、vfork()、kernel_thread()通过kernel_clone() +启动的。留点提示在这，以便搜索代码库，了解线程栈何时以及如何分配。 + +大量的代码是在: +`kernel/fork.c <https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/kernel/fork.c>`. + +task_struct中的stack_vm_area指针可以跟踪虚拟分配的堆栈，一个非空的stack_vm_area +指针可以表明虚拟映射的内核堆栈已经启用。 + +:: + + struct vm_struct *stack_vm_area; + +堆栈溢出处理 +------------ + +前守护页和后守护页有助于检测堆栈溢出。当堆栈溢出到守护页时，处理程序必须小心不要再 +次溢出堆栈。当处理程序被调用时，很可能只留下很少的堆栈空间。 + +在x86上，这是通过处理表明内核堆栈溢出的双异常堆栈的缺页异常来实现的。 + +用守护页测试VMAP分配 +-------------------- + +我们如何确保VMAP_STACK在分配时确实有前守护页和后守护页的保护？下面的 lkdtm 测试 +可以帮助检测任何回归。 + +:: + + void lkdtm_STACK_GUARD_PAGE_LEADING() + void lkdtm_STACK_GUARD_PAGE_TRAILING() + +结论 +---- + +- vmalloced堆栈的percpu缓存似乎比高阶堆栈分配要快一些，至少在缓存命中时是这样。 +- THREAD_INFO_IN_TASK完全摆脱了arch-specific thread_info，并简单地将 + thread_info（仅包含标志）和'int cpu'嵌入task_struct中。 +- 一旦任务死亡，线程栈就可以被释放（无需等待RCU），然后，如果使用vmapped栈，就 + 可以将整个栈缓存起来，以便在同一cpu上重复使用。 diff --git a/Documentation/translations/zh_CN/mm/z3fold.rst b/Documentation/translations/zh_CN/mm/z3fold.rst new file mode 100644 index 000000000000..9569a6d88270 --- /dev/null +++ b/Documentation/translations/zh_CN/mm/z3fold.rst @@ -0,0 +1,31 @@ +:Original: Documentation/mm/z3fold.rst + +:翻译: + + 司延腾 Yanteng Si <siyanteng@loongson.cn> + +:校译: + + +====== +z3fold +====== + +z3fold是一个专门用于存储压缩页的分配器。它被设计为每个物理页最多可以存储三个压缩页。 +它是zbud的衍生物，允许更高的压缩率，保持其前辈的简单性和确定性。 + +z3fold和zbud的主要区别是: + +* 与zbud不同的是，z3fold允许最大的PAGE_SIZE分配。 +* z3fold在其页面中最多可以容纳3个压缩页面 +* z3fold本身没有输出任何API，因此打算通过zpool的API来使用 + +为了保持确定性和简单性，z3fold，就像zbud一样，总是在每页存储一个整数的压缩页，但是 +它最多可以存储3页，不像zbud最多可以存储2页。因此压缩率达到2.7倍左右，而zbud的压缩 +率是1.7倍左右。 + +不像zbud（但也像zsmalloc），z3fold_alloc()那样不返回一个可重复引用的指针。相反，它 +返回一个无符号长句柄，它编码了被分配对象的实际位置。 + +保持有效的压缩率接近于zsmalloc，z3fold不依赖于MMU的启用，并提供更可预测的回收行 +为，这使得它更适合于小型和反应迅速的系统。 diff --git a/Documentation/translations/zh_CN/mm/zsmalloc.rst b/Documentation/translations/zh_CN/mm/zsmalloc.rst new file mode 100644 index 000000000000..4c8c9b1006a9 --- /dev/null +++ b/Documentation/translations/zh_CN/mm/zsmalloc.rst @@ -0,0 +1,78 @@ +:Original: Documentation/mm/zsmalloc.rst + +:翻译: + + 司延腾 Yanteng Si <siyanteng@loongson.cn> + +:校译: + +======== +zsmalloc +======== + +这个分配器是为与zram一起使用而设计的。因此，该分配器应该在低内存条件下工作良好。特别是， +它从未尝试过higher order页面的分配，这在内存压力下很可能会失败。另一方面，如果我们只 +是使用单（0-order）页，它将遭受非常高的碎片化 - 任何大小为PAGE_SIZE/2或更大的对象将 +占据整个页面。这是其前身（xvmalloc）的主要问题之一。 + +为了克服这些问题，zsmalloc分配了一堆0-order页面，并使用各种"struct page"字段将它 +们链接起来。这些链接的页面作为一个单一的higher order页面，即一个对象可以跨越0-order +页面的边界。代码将这些链接的页面作为一个实体，称为zspage。 + +为了简单起见，zsmalloc只能分配大小不超过PAGE_SIZE的对象，因为这满足了所有当前用户的 +要求（在最坏的情况下，页面是不可压缩的，因此以"原样"即未压缩的形式存储）。对于大于这 +个大小的分配请求，会返回失败（见zs_malloc）。 + +此外，zs_malloc()并不返回一个可重复引用的指针。相反，它返回一个不透明的句柄（无符号 +长），它编码了被分配对象的实际位置。这种间接性的原因是zsmalloc并不保持zspages的永久 +映射，因为这在32位系统上会导致问题，因为内核空间映射的VA区域非常小。因此，在使用分配 +的内存之前，对象必须使用zs_map_object()进行映射以获得一个可用的指针，随后使用 +zs_unmap_object()解除映射。 + +stat +==== + +通过CONFIG_ZSMALLOC_STAT，我们可以通过 ``/sys/kernel/debug/zsmalloc/<user name>`` +看到zsmalloc内部信息。下面是一个统计输出的例子。:: + + # cat /sys/kernel/debug/zsmalloc/zram0/classes + + class size almost_full almost_empty obj_allocated obj_used pages_used pages_per_zspage + ... + ... + 9 176 0 1 186 129 8 4 + 10 192 1 0 2880 2872 135 3 + 11 208 0 1 819 795 42 2 + 12 224 0 1 219 159 12 4 + ... + ... + + +class + 索引 +size + zspage存储对象大小 +almost_empty + ZS_ALMOST_EMPTY zspage的数量（见下文）。 +almost_full + ZS_ALMOST_FULL zspage的数量(见下图) +obj_allocated + 已分配对象的数量 +obj_used + 分配给用户的对象的数量 +pages_used + 为该类分配的页数 +pages_per_zspage + 组成一个zspage的0-order页面的数量 + +当n <= N / f时，我们将一个zspage分配给ZS_ALMOST_EMPTYfullness组，其中 + +* n = 已分配对象的数量 +* N = zspage可以存储的对象总数 +* f = fullness_threshold_frac(即，目前是4个) + +同样地，我们将zspage分配给: + +* ZS_ALMOST_FULL when n > N / f +* ZS_EMPTY when n == 0 +* ZS_FULL when n == N diff --git a/Documentation/translations/zh_CN/oops-tracing.txt b/Documentation/translations/zh_CN/oops-tracing.txt deleted file mode 100644 index c5f3bda7abcb..000000000000 --- a/Documentation/translations/zh_CN/oops-tracing.txt +++ /dev/null @@ -1,212 +0,0 @@ -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 <leoyang.li@nxp.com> - 王聪 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/admin-guide/kdump/kdump.rst）， -使用在Documentation/admin-guide/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/peci/index.rst b/Documentation/translations/zh_CN/peci/index.rst new file mode 100644 index 000000000000..4f6694c828fa --- /dev/null +++ b/Documentation/translations/zh_CN/peci/index.rst @@ -0,0 +1,26 @@ +.. SPDX-License-Identifier: GPL-2.0-only +.. include:: ../disclaimer-zh_CN.rst + +:Original: Documentation/peci/index.rst + +:翻译: + + 司延腾 Yanteng Si <siyanteng@loongson.cn> + +:校译: + +================= +Linux PECI 子系统 +================= + +.. toctree:: + + + peci + +.. only:: subproject and html + + Indices + ======= + + * :ref:`genindex` diff --git a/Documentation/translations/zh_CN/peci/peci.rst b/Documentation/translations/zh_CN/peci/peci.rst new file mode 100644 index 000000000000..a3b4f99b994c --- /dev/null +++ b/Documentation/translations/zh_CN/peci/peci.rst @@ -0,0 +1,54 @@ +.. SPDX-License-Identifier: GPL-2.0-only +.. include:: ../disclaimer-zh_CN.rst + +:Original: Documentation/peci/peci.rst + +:翻译: + + 司延腾 Yanteng Si <siyanteng@loongson.cn> + +:校译: + +==== +概述 +==== + +平台环境控制接口（PECI）是英特尔处理器和管理控制器（如底板管理控制器，BMC） +之间的一个通信接口。PECI提供的服务允许管理控制器通过访问各种寄存器来配置、监 +控和调试平台。它定义了一个专门的命令协议，管理控制器作为PECI的发起者，处理器 +作为PECI的响应者。PECI可以用于基于单处理器和多处理器的系统中。 + +注意：英特尔PECI规范没有作为专门的文件发布，而是作为英特尔CPU的外部设计规范 +（EDS）的一部分。外部设计规范通常是不公开的。 + +PECI 线 +--------- + +PECI线接口使用单线进行自锁和数据传输。它不需要任何额外的控制线--物理层是一个 +自锁的单线总线信号，每一个比特都从接近零伏的空闲状态开始驱动、上升边缘。驱动高 +电平信号的持续时间可以确定位值是逻辑 “0” 还是逻辑 “1”。PECI线还包括与每个信 +息建立的可变数据速率。 + +对于PECI线，每个处理器包将在一个定义的范围内利用唯一的、固定的地址，该地址应 +该与处理器插座ID有固定的关系--如果其中一个处理器被移除，它不会影响其余处理器 +的地址。 + +PECI子系统代码内嵌文档 +------------------------ + +该API在以下内核代码中: + +include/linux/peci.h + +drivers/peci/internal.h + +drivers/peci/core.c + +drivers/peci/request.c + +PECI CPU 驱动 API +------------------- + +该API在以下内核代码中: + +drivers/peci/cpu.c diff --git a/Documentation/translations/zh_CN/power/energy-model.rst b/Documentation/translations/zh_CN/power/energy-model.rst new file mode 100644 index 000000000000..c7da1b6aefee --- /dev/null +++ b/Documentation/translations/zh_CN/power/energy-model.rst @@ -0,0 +1,190 @@ +.. SPDX-License-Identifier: GPL-2.0 +.. include:: ../disclaimer-zh_CN.rst + +:Original: Documentation/power/energy-model.rst + +:翻译: + + 唐艺舟 Tang Yizhou <tangyeechou@gmail.com> + +============ +设备能量模型 +============ + +1. 概述 +------- + +能量模型（EM）框架是一种驱动程序与内核子系统之间的接口。其中驱动程序了解不同 +性能层级的设备所消耗的功率，而内核子系统愿意使用该信息做出能量感知决策。 + +设备所消耗的功率的信息来源在不同的平台上可能有很大的不同。这些功率成本在某些 +情况下可以使用设备树数据来估算。在其它情况下，固件会更清楚。或者，用户空间可能 +是最清楚的。以此类推。为了避免每一个客户端子系统对每一种可能的信息源自己重新 +实现支持，EM框架作为一个抽象层介入，它在内核中对功率成本表的格式进行标准化， +因此能够避免多余的工作。 + +功率值可以用毫瓦或“抽象刻度”表示。多个子系统可能使用EM，由系统集成商来检查 +功率值刻度类型的要求是否满足。可以在能量感知调度器的文档中找到一个例子 +Documentation/scheduler/sched-energy.rst。对于一些子系统，比如热能或 +powercap，用“抽象刻度”描述功率值可能会导致问题。这些子系统对过去使用的功率的 +估算值更感兴趣，因此可能需要真实的毫瓦。这些要求的一个例子可以在智能功率分配 +Documentation/driver-api/thermal/power_allocator.rst文档中找到。 + +内核子系统可能（基于EM内部标志位）实现了对EM注册设备是否具有不一致刻度的自动 +检查。要记住的重要事情是，当功率值以“抽象刻度”表示时，从中推导以毫焦耳为单位 +的真实能量消耗是不可能的。 + +下图描述了一个驱动的例子（这里是针对Arm的，但该方法适用于任何体系结构），它 +向EM框架提供了功率成本，感兴趣的客户端可从中读取数据:: + + +---------------+ +-----------------+ +---------------+ + | Thermal (IPA) | | Scheduler (EAS) | | Other | + +---------------+ +-----------------+ +---------------+ + | | em_cpu_energy() | + | | em_cpu_get() | + +---------+ | +---------+ + | | | + v v v + +---------------------+ + | Energy Model | + | Framework | + +---------------------+ + ^ ^ ^ + | | | em_dev_register_perf_domain() + +----------+ | +---------+ + | | | + +---------------+ +---------------+ +--------------+ + | cpufreq-dt | | arm_scmi | | Other | + +---------------+ +---------------+ +--------------+ + ^ ^ ^ + | | | + +--------------+ +---------------+ +--------------+ + | Device Tree | | Firmware | | ? | + +--------------+ +---------------+ +--------------+ + +对于CPU设备，EM框架管理着系统中每个“性能域”的功率成本表。一个性能域是一组 +性能一起伸缩的CPU。性能域通常与CPUFreq策略具有1对1映射。一个性能域中的 +所有CPU要求具有相同的微架构。不同性能域中的CPU可以有不同的微架构。 + + +2. 核心API +---------- + +2.1 配置选项 +^^^^^^^^^^^^ + +必须使能CONFIG_ENERGY_MODEL才能使用EM框架。 + + +2.2 性能域的注册 +^^^^^^^^^^^^^^^^ + +“高级”EM的注册 +~~~~~~~~~~~~~~~~ + +“高级”EM因它允许驱动提供更精确的功率模型而得名。它并不受限于框架中的一些已 +实现的数学公式（就像“简单”EM那样）。它可以更好地反映每个性能状态的实际功率 +测量。因此，在EM静态功率（漏电流功率）是重要的情况下，应该首选这种注册方式。 + +驱动程序应通过以下API将性能域注册到EM框架中:: + + int em_dev_register_perf_domain(struct device *dev, unsigned int nr_states, + struct em_data_callback *cb, cpumask_t *cpus, bool milliwatts); + +驱动程序必须提供一个回调函数，为每个性能状态返回<频率,功率>元组。驱动程序 +提供的回调函数可以自由地从任何相关位置（DT、固件......）以及以任何被认为是 +必要的方式获取数据。只有对于CPU设备，驱动程序必须使用cpumask指定性能域的CPU。 +对于CPU以外的其他设备，最后一个参数必须被设置为NULL。 + +最后一个参数“milliwatts”（毫瓦）设置成正确的值是很重要的，使用EM的内核 +子系统可能会依赖这个标志来检查所有的EM设备是否使用相同的刻度。如果有不同的 +刻度，这些子系统可能决定：返回警告/错误，停止工作或崩溃（panic）。 + +关于实现这个回调函数的驱动程序的例子，参见第3节。或者在第2.4节阅读这个API +的更多文档。 + + +“简单”EM的注册 +~~~~~~~~~~~~~~~~ + +“简单”EM是用框架的辅助函数cpufreq_register_em_with_opp()注册的。它实现了 +一个和以下数学公式紧密相关的功率模型:: + + Power = C * V^2 * f + +使用这种方法注册的EM可能无法正确反映真实设备的物理特性，例如当静态功率 +（漏电流功率）很重要时。 + + +2.3 访问性能域 +^^^^^^^^^^^^^^ + +有两个API函数提供对能量模型的访问。em_cpu_get()以CPU id为参数，em_pd_get() +以设备指针为参数。使用哪个接口取决于子系统，但对于CPU设备来说，这两个函数都返 +回相同的性能域。 + +对CPU的能量模型感兴趣的子系统可以通过em_cpu_get() API检索它。在创建性能域时 +分配一次能量模型表，它保存在内存中不被修改。 + +一个性能域所消耗的能量可以使用em_cpu_energy() API来估算。该估算假定CPU设备 +使用的CPUfreq监管器是schedutil。当前该计算不能提供给其它类型的设备。 + +关于上述API的更多细节可以在 ``<linux/energy_model.h>`` 或第2.4节中找到。 + + +2.4 API的细节描述 +^^^^^^^^^^^^^^^^^ +参见 include/linux/energy_model.h 和 kernel/power/energy_model.c 的kernel doc。 + +3. 驱动示例 +----------- + +CPUFreq框架支持专用的回调函数，用于为指定的CPU（们）注册EM： +cpufreq_driver::register_em()。这个回调必须为每个特定的驱动程序正确实现， +因为框架会在设置过程中适时地调用它。本节提供了一个简单的例子，展示CPUFreq驱动 +在能量模型框架中使用（假的）“foo”协议注册性能域。该驱动实现了一个est_power() +函数提供给EM框架:: + + -> drivers/cpufreq/foo_cpufreq.c + + 01 static int est_power(unsigned long *mW, unsigned long *KHz, + 02 struct device *dev) + 03 { + 04 long freq, power; + 05 + 06 /* 使用“foo”协议设置频率上限 */ + 07 freq = foo_get_freq_ceil(dev, *KHz); + 08 if (freq < 0); + 09 return freq; + 10 + 11 /* 估算相关频率下设备的功率成本 */ + 12 power = foo_estimate_power(dev, freq); + 13 if (power < 0); + 14 return power; + 15 + 16 /* 将这些值返回给EM框架 */ + 17 *mW = power; + 18 *KHz = freq; + 19 + 20 return 0; + 21 } + 22 + 23 static void foo_cpufreq_register_em(struct cpufreq_policy *policy) + 24 { + 25 struct em_data_callback em_cb = EM_DATA_CB(est_power); + 26 struct device *cpu_dev; + 27 int nr_opp; + 28 + 29 cpu_dev = get_cpu_device(cpumask_first(policy->cpus)); + 30 + 31 /* 查找该策略支持的OPP数量 */ + 32 nr_opp = foo_get_nr_opp(policy); + 33 + 34 /* 并注册新的性能域 */ + 35 em_dev_register_perf_domain(cpu_dev, nr_opp, &em_cb, policy->cpus, + 36 true); + 37 } + 38 + 39 static struct cpufreq_driver foo_cpufreq_driver = { + 40 .register_em = foo_cpufreq_register_em, + 41 }; diff --git a/Documentation/translations/zh_CN/power/index.rst b/Documentation/translations/zh_CN/power/index.rst new file mode 100644 index 000000000000..bc54983ba515 --- /dev/null +++ b/Documentation/translations/zh_CN/power/index.rst @@ -0,0 +1,56 @@ +.. SPDX-License-Identifier: GPL-2.0 +.. include:: ../disclaimer-zh_CN.rst + +:Original: Documentation/power/index.rst + +:翻译: + + 唐艺舟 Tang Yizhou <tangyeechou@gmail.com> + +======== +电源管理 +======== + +.. toctree:: + :maxdepth: 1 + + energy-model + opp + +TODOList: + + * apm-acpi + * basic-pm-debugging + * charger-manager + * drivers-testing + * freezing-of-tasks + * pci + * pm_qos_interface + * power_supply_class + * runtime_pm + * s2ram + * suspend-and-cpuhotplug + * suspend-and-interrupts + * swsusp-and-swap-files + * swsusp-dmcrypt + * swsusp + * video + * tricks + + * userland-swsusp + + * powercap/powercap + * powercap/dtpm + + * regulator/consumer + * regulator/design + * regulator/machine + * regulator/overview + * regulator/regulator + +.. only:: subproject and html + + Indices + ======= + + * :ref:`genindex` diff --git a/Documentation/translations/zh_CN/power/opp.rst b/Documentation/translations/zh_CN/power/opp.rst new file mode 100644 index 000000000000..8d6e3f6f6202 --- /dev/null +++ b/Documentation/translations/zh_CN/power/opp.rst @@ -0,0 +1,341 @@ +.. SPDX-License-Identifier: GPL-2.0 +.. include:: ../disclaimer-zh_CN.rst + +:Original: Documentation/power/opp.rst + +:翻译: + + 唐艺舟 Tang Yizhou <tangyeechou@gmail.com> + +====================== +操作性能值（OPP）库 +====================== + +(C) 2009-2010 Nishanth Menon <nm@ti.com>, 德州仪器公司 + +.. 目录 + + 1. 简介 + 2. OPP链表初始注册 + 3. OPP搜索函数 + 4. OPP可用性控制函数 + 5. OPP数据检索函数 + 6. 数据结构 + +1. 简介 +======= + +1.1 何为操作性能值（OPP）？ +------------------------------ + +当今复杂的单片系统（SoC）由多个子模块组成，这些子模块会联合工作。在一个执行不同用例 +的操作系统中，并不是SoC中的所有模块都需要一直以最高频率工作。为了促成这一点，SoC中 +的子模块被分组为不同域，允许一些域以较低的电压和频率运行，而其它域则以较高的“电压/ +频率对”运行。 + +设备按域支持的由频率电压对组成的离散的元组的集合，被称为操作性能值（组），或OPPs。 + +举例来说： + +让我们考虑一个支持下述频率、电压值的内存保护单元（MPU）设备： +{300MHz，最低电压为1V}, {800MHz，最低电压为1.2V}, {1GHz，最低电压为1.3V} + +我们能将它们表示为3个OPP，如下述{Hz, uV}元组（译注：频率的单位是赫兹，电压的单位是 +微伏）。 + +- {300000000, 1000000} +- {800000000, 1200000} +- {1000000000, 1300000} + +1.2 操作性能值库 +---------------- + +OPP库提供了一组辅助函数来组织和查询OPP信息。该库位于drivers/opp/目录下，其头文件 +位于include/linux/pm_opp.h中。OPP库可以通过开启CONFIG_PM_OPP来启用。某些SoC， +如德州仪器的OMAP框架允许在不需要cpufreq的情况下可选地在某一OPP下启动。 + +OPP库的典型用法如下:: + + （用户） -> 注册一个默认的OPP集合 -> （库） + （SoC框架） -> 在必要的情况下，对某些OPP进行修改 -> OPP layer + -> 搜索/检索信息的查询 -> + +OPP层期望每个域由一个唯一的设备指针来表示。SoC框架在OPP层为每个设备注册了一组初始 +OPP。这个链表的长度被期望是一个最优化的小数字，通常每个设备大约5个。初始链表包含了 +一个OPP集合，这个集合被期望能在系统中安全使能。 + +关于OPP可用性的说明 +^^^^^^^^^^^^^^^^^^^ + +随着系统的运行，SoC框架可能会基于各种外部因素选择让某些OPP在每个设备上可用或不可用， +示例：温度管理或其它异常场景中，SoC框架可能会选择禁用一个较高频率的OPP以安全地继续 +运行，直到该OPP被重新启用（如果可能）。 + +OPP库在它的实现中达成了这个概念。以下操作函数只能对可用的OPP使用： +dev_pm_opp_find_freq_{ceil, floor}, dev_pm_opp_get_voltage, +dev_pm_opp_get_freq, dev_pm_opp_get_opp_count。 + +dev_pm_opp_find_freq_exact是用来查找OPP指针的，该指针可被用在dev_pm_opp_enable/ +disable函数，使一个OPP在被需要时变为可用。 + +警告：如果对一个设备调用dev_pm_opp_enable/disable函数，OPP库的用户应该使用 +dev_pm_opp_get_opp_count来刷新OPP的可用性计数。触发这些的具体机制，或者对有依赖的 +子系统（比如cpufreq）的通知机制，都是由使用OPP库的SoC特定框架酌情处理的。在这些操作 +中，同样需要注意刷新cpufreq表。 + +2. OPP链表初始注册 +================== +SoC的实现会迭代调用dev_pm_opp_add函数来增加每个设备的OPP。预期SoC框架将以最优的 +方式注册OPP条目 - 典型的数字范围小于5。通过注册OPP生成的OPP链表，在整个设备运行过程 +中由OPP库维护。SoC框架随后可以使用dev_pm_opp_enable / disable函数动态地 +控制OPP的可用性。 + +dev_pm_opp_add + 为设备指针所指向的特定域添加一个新的OPP。OPP是用频率和电压定义的。一旦完成 + 添加，OPP被认为是可用的，可以用dev_pm_opp_enable/disable函数来控制其可用性。 + OPP库内部用dev_pm_opp结构体存储并管理这些信息。这个函数可以被SoC框架根据SoC + 的使用环境的需求来定义一个最优链表。 + + 警告： + 不要在中断上下文使用这个函数。 + + 示例:: + + soc_pm_init() + { + /* 做一些事情 */ + r = dev_pm_opp_add(mpu_dev, 1000000, 900000); + if (!r) { + pr_err("%s: unable to register mpu opp(%d)\n", r); + goto no_cpufreq; + } + /* 做一些和cpufreq相关的事情 */ + no_cpufreq: + /* 做剩余的事情 */ + } + +3. OPP搜索函数 +============== +cpufreq等高层框架对频率进行操作，为了将频率映射到相应的OPP，OPP库提供了便利的函数 +来搜索OPP库内部管理的OPP链表。这些搜索函数如果找到匹配的OPP，将返回指向该OPP的指针， +否则返回错误。这些错误预计由标准的错误检查，如IS_ERR()来处理，并由调用者采取适当的 +行动。 + +这些函数的调用者应在使用完OPP后调用dev_pm_opp_put()。否则，OPP的内存将永远不会 +被释放，并导致内存泄露。 + +dev_pm_opp_find_freq_exact + 根据 *精确的* 频率和可用性来搜索OPP。这个函数对默认不可用的OPP特别有用。 + 例子：在SoC框架检测到更高频率可用的情况下，它可以使用这个函数在调用 + dev_pm_opp_enable之前找到OPP:: + + opp = dev_pm_opp_find_freq_exact(dev, 1000000000, false); + dev_pm_opp_put(opp); + /* 不要操作指针.. 只是做有效性检查.. */ + if (IS_ERR(opp)) { + pr_err("frequency not disabled!\n"); + /* 触发合适的操作.. */ + } else { + dev_pm_opp_enable(dev,1000000000); + } + + 注意： + 这是唯一一个可以搜索不可用OPP的函数。 + +dev_pm_opp_find_freq_floor + 搜索一个 *最多* 提供指定频率的可用OPP。这个函数在搜索较小的匹配或按频率 + 递减的顺序操作OPP信息时很有用。 + 例子：要找的一个设备的最高OPP:: + + freq = ULONG_MAX; + opp = dev_pm_opp_find_freq_floor(dev, &freq); + dev_pm_opp_put(opp); + +dev_pm_opp_find_freq_ceil + 搜索一个 *最少* 提供指定频率的可用OPP。这个函数在搜索较大的匹配或按频率 + 递增的顺序操作OPP信息时很有用。 + 例1：找到一个设备最小的OPP:: + + freq = 0; + opp = dev_pm_opp_find_freq_ceil(dev, &freq); + dev_pm_opp_put(opp); + + 例: 一个SoC的cpufreq_driver->target的简易实现:: + + soc_cpufreq_target(..) + { + /* 做策略检查等操作 */ + /* 找到和请求最接近的频率 */ + opp = dev_pm_opp_find_freq_ceil(dev, &freq); + dev_pm_opp_put(opp); + if (!IS_ERR(opp)) + soc_switch_to_freq_voltage(freq); + else + /* 当不能满足请求时，要做的事 */ + /* 做其它事 */ + } + +4. OPP可用性控制函数 +==================== +在OPP库中注册的默认OPP链表也许无法满足所有可能的场景。OPP库提供了一套函数来修改 +OPP链表中的某个OPP的可用性。这使得SoC框架能够精细地动态控制哪一组OPP是可用于操作 +的。设计这些函数的目的是在诸如考虑温度时 *暂时地* 删除某个OPP（例如，在温度下降 +之前不要使用某OPP）。 + +警告： + 不要在中断上下文使用这些函数。 + +dev_pm_opp_enable + 使一个OPP可用于操作。 + 例子：假设1GHz的OPP只有在SoC温度低于某个阈值时才可用。SoC框架的实现可能 + 会选择做以下事情:: + + if (cur_temp < temp_low_thresh) { + /* 若1GHz未使能，则使能 */ + opp = dev_pm_opp_find_freq_exact(dev, 1000000000, false); + dev_pm_opp_put(opp); + /* 仅仅是错误检查 */ + if (!IS_ERR(opp)) + ret = dev_pm_opp_enable(dev, 1000000000); + else + goto try_something_else; + } + +dev_pm_opp_disable + 使一个OPP不可用于操作。 + 例子：假设1GHz的OPP只有在SoC温度高于某个阈值时才可用。SoC框架的实现可能 + 会选择做以下事情:: + + if (cur_temp > temp_high_thresh) { + /* 若1GHz已使能，则关闭 */ + opp = dev_pm_opp_find_freq_exact(dev, 1000000000, true); + dev_pm_opp_put(opp); + /* 仅仅是错误检查 */ + if (!IS_ERR(opp)) + ret = dev_pm_opp_disable(dev, 1000000000); + else + goto try_something_else; + } + +5. OPP数据检索函数 +================== +由于OPP库对OPP信息进行了抽象化处理，因此需要一组函数来从dev_pm_opp结构体中提取 +信息。一旦使用搜索函数检索到一个OPP指针，以下函数就可以被SoC框架用来检索OPP层 +内部描述的信息。 + +dev_pm_opp_get_voltage + 检索OPP指针描述的电压。 + 例子: 当cpufreq切换到到不同频率时，SoC框架需要用稳压器框架将OPP描述 + 的电压设置到提供电压的电源管理芯片中:: + + soc_switch_to_freq_voltage(freq) + { + /* 做一些事情 */ + opp = dev_pm_opp_find_freq_ceil(dev, &freq); + v = dev_pm_opp_get_voltage(opp); + dev_pm_opp_put(opp); + if (v) + regulator_set_voltage(.., v); + /* 做其它事 */ + } + +dev_pm_opp_get_freq + 检索OPP指针描述的频率。 + 例子：比方说，SoC框架使用了几个辅助函数，通过这些函数，我们可以将OPP + 指针传入，而不是传入额外的参数，用来处理一系列数据参数:: + + soc_cpufreq_target(..) + { + /* 做一些事情.. */ + max_freq = ULONG_MAX; + max_opp = dev_pm_opp_find_freq_floor(dev,&max_freq); + requested_opp = dev_pm_opp_find_freq_ceil(dev,&freq); + if (!IS_ERR(max_opp) && !IS_ERR(requested_opp)) + r = soc_test_validity(max_opp, requested_opp); + dev_pm_opp_put(max_opp); + dev_pm_opp_put(requested_opp); + /* 做其它事 */ + } + soc_test_validity(..) + { + if(dev_pm_opp_get_voltage(max_opp) < dev_pm_opp_get_voltage(requested_opp)) + return -EINVAL; + if(dev_pm_opp_get_freq(max_opp) < dev_pm_opp_get_freq(requested_opp)) + return -EINVAL; + /* 做一些事情.. */ + } + +dev_pm_opp_get_opp_count + 检索某个设备可用的OPP数量。 + 例子：假设SoC中的一个协处理器需要知道某个表中的可用频率，主处理器可以 + 按如下方式发出通知:: + + soc_notify_coproc_available_frequencies() + { + /* 做一些事情 */ + num_available = dev_pm_opp_get_opp_count(dev); + speeds = kzalloc(sizeof(u32) * num_available, GFP_KERNEL); + /* 按升序填充表 */ + freq = 0; + while (!IS_ERR(opp = dev_pm_opp_find_freq_ceil(dev, &freq))) { + speeds[i] = freq; + freq++; + i++; + dev_pm_opp_put(opp); + } + + soc_notify_coproc(AVAILABLE_FREQs, speeds, num_available); + /* 做其它事 */ + } + +6. 数据结构 +=========== +通常，一个SoC包含多个可变电压域。每个域由一个设备指针描述。和OPP之间的关系可以 +按以下方式描述:: + + SoC + |- device 1 + | |- opp 1 (availability, freq, voltage) + | |- opp 2 .. + ... ... + | `- opp n .. + |- device 2 + ... + `- device m + +OPP库维护着一个内部链表，SoC框架使用上文描述的各个函数来填充和访问。然而，描述 +真实OPP和域的结构体是OPP库自身的内部组成，以允许合适的抽象在不同系统中得到复用。 + +struct dev_pm_opp + OPP库的内部数据结构，用于表示一个OPP。除了频率、电压、可用性信息外， + 它还包含OPP库运行所需的内部统计信息。指向这个结构体的指针被提供给 + 用户（比如SoC框架）使用，在与OPP层的交互中作为OPP的标识符。 + + 警告： + 结构体dev_pm_opp的指针不应该由用户解析或修改。一个实例的默认值由 + dev_pm_opp_add填充，但OPP的可用性由dev_pm_opp_enable/disable函数 + 修改。 + +struct device + 这用于向OPP层标识一个域。设备的性质和它的实现是由OPP库的用户决定的， + 如SoC框架。 + +总体来说，以一个简化的视角看，对数据结构的操作可以描述为下面各图:: + + 初始化 / 修改: + +-----+ /- dev_pm_opp_enable + dev_pm_opp_add --> | opp | <------- + | +-----+ \- dev_pm_opp_disable + \-------> domain_info(device) + + 搜索函数: + /-- dev_pm_opp_find_freq_ceil ---\ +-----+ + domain_info<---- dev_pm_opp_find_freq_exact -----> | opp | + \-- dev_pm_opp_find_freq_floor ---/ +-----+ + + 检索函数: + +-----+ /- dev_pm_opp_get_voltage + | opp | <--- + +-----+ \- dev_pm_opp_get_freq + + domain_info <- dev_pm_opp_get_opp_count diff --git a/Documentation/translations/zh_CN/process/5.Posting.rst b/Documentation/translations/zh_CN/process/5.Posting.rst index 4ee7de13f373..6a469e1c7deb 100644 --- a/Documentation/translations/zh_CN/process/5.Posting.rst +++ b/Documentation/translations/zh_CN/process/5.Posting.rst @@ -19,8 +19,7 @@ 内核开发社区已经发展出一套用于发布补丁的约定和过程；遵循这些约定和过程将使 参与其中的每个人的生活更加轻松。本文档试图描述这些约定的部分细节；更多信息 也可在以下文档中找到 -:ref:`Documentation/translations/zh_CN/process/submitting-patches.rst <cn_submittingpatches>`， -:ref:`Documentation/translations/zh_CN/process/submitting-drivers.rst <cn_submittingdrivers>` +:ref:`Documentation/translations/zh_CN/process/submitting-patches.rst <cn_submittingpatches>` 和 :ref:`Documentation/translations/zh_CN/process/submit-checklist.rst <cn_submitchecklist>`。 何时寄送 diff --git a/Documentation/translations/zh_CN/process/8.Conclusion.rst b/Documentation/translations/zh_CN/process/8.Conclusion.rst index 4707f0101964..643b88af97bb 100644 --- a/Documentation/translations/zh_CN/process/8.Conclusion.rst +++ b/Documentation/translations/zh_CN/process/8.Conclusion.rst @@ -19,7 +19,6 @@ :ref:`Documentation/translations/zh_CN/process/howto.rst <cn_process_howto>` 文件是一个重要的起点； :ref:`Documentation/translations/zh_CN/process/submitting-patches.rst <cn_submittingpatches>` -和 :ref:`Documentation/translations/zh_CN/process/submitting-drivers.rst <cn_submittingdrivers>` 也是所有内核开发人员都应该阅读的内容。许多内部内核API都是使用kerneldoc机制 记录的；“make htmldocs”或“make pdfdocs”可用于以HTML或PDF格式生成这些文档 （尽管某些发行版提供的tex版本会遇到内部限制，无法正确处理文档）。 diff --git a/Documentation/translations/zh_CN/process/coding-style.rst b/Documentation/translations/zh_CN/process/coding-style.rst index 638d714bec83..fa28ef0a7fee 100644 --- a/Documentation/translations/zh_CN/process/coding-style.rst +++ b/Documentation/translations/zh_CN/process/coding-style.rst @@ -1,21 +1,23 @@ .. include:: ../disclaimer-zh_CN.rst -:Original: :ref:`Documentation/process/coding-style.rst <codingstyle>` +:Original: Documentation/process/coding-style.rst .. _cn_codingstyle: -译者:: +:译者: + - 张乐 Zhang Le <r0bertz@gentoo.org> + - Andy Deng <theandy.deng@gmail.com> + - 吴想成 <bobwxc@email.cn> - 中文版维护者： 张乐 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> +:校译: + - 王聪 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 内核的首选代码风格。代码风格是因人而异的， 而且我不愿意把自己的观点强加给任何人，但这就像我去做任何事情都必须遵循的原则 @@ -29,7 +31,7 @@ Linux 内核代码风格 1) 缩进 --------------- +------- 制表符是 8 个字符，所以缩进也是 8 个字符。有些异端运动试图将缩进变为 4 (甚至 2！) 字符深，这几乎相当于尝试将圆周率的值定义为 3。 @@ -73,6 +75,22 @@ Linux 内核代码风格 if (condition) do_this; do_something_everytime; +不要使用逗号来避免使用大括号： + +.. code-block:: c + + if (condition) + do_this(), do_that(); + +使用大括号包裹多语句： + +.. code-block:: c + + if (condition) { + do_this(); + do_that(); + } + 也不要在一行里放多个赋值语句。内核代码风格超级简单。就是避免可能导致别人误读 的表达式。 @@ -83,20 +101,25 @@ Linux 内核代码风格 2) 把长的行和字符串打散 ------------------------------- +----------------------- 代码风格的意义就在于使用平常使用的工具来维持代码的可读性和可维护性。 每一行的长度的限制是 80 列，我们强烈建议您遵守这个惯例。 长于 80 列的语句要打散成有意义的片段。除非超过 80 列能显著增加可读性，并且不 -会隐藏信息。子片段要明显短于母片段，并明显靠右。这同样适用于有着很长参数列表 -的函数头。然而，绝对不要打散对用户可见的字符串，例如 printk 信息，因为这样就 +会隐藏信息。 + +子片段要明显短于母片段，并明显靠右。一种非常常用的样式是将子体与函数左括号对齐。 + +这同样适用于有着很长参数列表的函数头。 + +然而，绝对不要打散对用户可见的字符串，例如 printk 信息，因为这样就 很难对它们 grep。 3) 大括号和空格的放置 ------------------------------- +--------------------- C 语言风格中另外一个常见问题是大括号的放置。和缩进大小不同，选择或弃用某种放 置策略并没有多少技术上的原因，不过首选的方式，就像 Kernighan 和 Ritchie 展示 @@ -132,12 +155,12 @@ C 语言风格中另外一个常见问题是大括号的放置。和缩进大小 body of function } -全世界的异端可能会抱怨这个不一致性是... 呃... 不一致的，不过所有思维健全的人 +全世界的异端可能会抱怨这个不一致性是……呃……不一致，不过所有思维健全的人 都知道 (a) K&R 是 **正确的** 并且 (b) K&R 是正确的。此外，不管怎样函数都是特 殊的 (C 函数是不能嵌套的)。 注意结束大括号独自占据一行，除非它后面跟着同一个语句的剩余部分，也就是 do 语 -句中的 "while" 或者 if 语句中的 "else"，像这样： +句中的 ``while`` 或者 if 语句中的 ``else`` ，像这样： .. code-block:: c @@ -191,7 +214,7 @@ C 语言风格中另外一个常见问题是大括号的放置。和缩进大小 } 3.1) 空格 -******************** +********* Linux 内核的空格使用方式 (主要) 取决于它是用于函数还是关键字。(大多数) 关键字 后要加一个空格。值得注意的例外是 sizeof, typeof, alignof 和 __attribute__，这 @@ -254,7 +277,7 @@ Linux 内核的空格使用方式 (主要) 取决于它是用于函数还是关 4) 命名 ------------------------------- +------- C 是一个简朴的语言，你的命名也应该这样。和 Modula-2 和 Pascal 程序员不同， C 程序员不使用类似 ThisVariableIsATemporaryCounter 这样华丽的名字。C 程序员会 @@ -275,11 +298,31 @@ C 程序员不使用类似 ThisVariableIsATemporaryCounter 这样华丽的名字 可能的话。类似的， ``tmp`` 可以用来称呼任意类型的临时变量。 如果你怕混淆了你的本地变量名，你就遇到另一个问题了，叫做函数增长荷尔蒙失衡综 -合症。请看第六章 (函数)。 +合征。请看第六章 (函数)。 +对于符号名称和文档，避免引入新的“master/slave”（或独立于“master”的“slave”） +和“blacklist/whitelist”。 + +“master/slave”推荐替换为： + '{primary,main} / {secondary,replica,subordinate}' + '{initiator,requester} / {target,responder}' + '{controller,host} / {device,worker,proxy}' + 'leader/follower' + 'director/performer' + +“blacklist/whitelist”推荐替换为： + 'denylist/allowlist' + 'blocklist/passlist' + +引入新用法的例外情况是：维护用户空间ABI/API，或更新现有（截至2020年）硬件或 +协议规范的代码时要求这些术语。对于新规范，尽可能将术语的规范用法转换为内核 +编码标准。 + +.. warning:: + 以上主从、黑白名单规则不适用于中文文档，请勿更改中文术语！ 5) Typedef ------------ +---------- 不要使用类似 ``vps_t`` 之类的东西。 @@ -308,7 +351,7 @@ C 程序员不使用类似 ThisVariableIsATemporaryCounter 这样华丽的名字 .. note:: - 不透明性和 "访问函数" 本身是不好的。我们使用 pte_t 等类型的原因在于真 + 不透明性和“访问函数”本身是不好的。我们使用 pte_t 等类型的原因在于真 的是完全没有任何共用的可访问信息。 (b) 清楚的整数类型，如此，这层抽象就可以 **帮助** 消除到底是 ``int`` 还是 @@ -353,7 +396,7 @@ C 程序员不使用类似 ThisVariableIsATemporaryCounter 这样华丽的名字 6) 函数 ------------------------------- +------- 函数应该简短而漂亮，并且只完成一件事情。函数应该可以一屏或者两屏显示完 (我们 都知道 ISO/ANSI 屏幕大小是 80x24)，只做一件事情，而且把它做好。 @@ -383,12 +426,46 @@ C 程序员不使用类似 ThisVariableIsATemporaryCounter 这样华丽的名字 } EXPORT_SYMBOL(system_is_up); -在函数原型中，包含函数名和它们的数据类型。虽然 C 语言里没有这样的要求，在 +6.1) 函数原型 +************* + +在函数原型中包含参数名和它们的数据类型。虽然 C 语言里没有这样的要求，但在 Linux 里这是提倡的做法，因为这样可以很简单的给读者提供更多的有价值的信息。 +不要在函数声明里使用 ``extern`` 关键字，因为这会导致代码行变长，并且不是严格 +必需的。 + +写函数原型时，请保持 `元素顺序规则 <https://lore.kernel.org/mm-commits/CAHk-=wiOCLRny5aifWNhr621kYrJwhfURsa0vFPeUEm8mF0ufg@mail.gmail.com/>`_ 。 +例如下列函数声明:: + + __init void * __must_check action(enum magic value, size_t size, u8 count, + char *fmt, ...) __printf(4, 5) __malloc; + +推荐的函数原型元素顺序是： + +- 储存类型（下方的 ``static __always_inline`` ，注意 ``__always_inline`` + 技术上来讲是个属性但被当做 ``inline`` ） +- 储存类型属性（上方的 ``__init`` ——即节声明，但也像 ``__cold`` ） +- 返回类型（上方的 ``void *`` ） +- 返回类型属性（上方的 ``__must_check`` ） +- 函数名（上方的 ``action`` ） +- 函数参数（上方的 ``(enum magic value, size_t size, u8 count, char *fmt, ...)`` ， + 注意必须写上参数名） +- 函数参数属性（上方的 ``__printf(4, 5)`` ） +- 函数行为属性（上方的 ``__malloc`` ） + +请注意，对于函数 **定义** （即实际函数体），编译器不允许在函数参数之后添加函 +数参数属性。在这种情况下，它们应该跟随存储类型属性（例如，与上面的 **声明** +示例相比，请注意下面的 ``__printf(4, 5)`` 的位置发生了变化）:: + + static __always_inline __init __printf(4, 5) void * __must_check action(enum magic value, + size_t size, u8 count, char *fmt, ...) __malloc + { + ... + } 7) 集中的函数退出途径 ------------------------------- +--------------------- 虽然被某些人声称已经过时，但是 goto 语句的等价物还是经常被编译器所使用，具体 形式是无条件跳转指令。 @@ -432,7 +509,7 @@ Linux 里这是提倡的做法，因为这样可以很简单的给读者提供 return result; } -一个需要注意的常见错误是 ``一个 err 错误`` ，就像这样： +一个需要注意的常见错误是 ``单 err 错误`` ，就像这样： .. code-block:: c @@ -456,19 +533,19 @@ Linux 里这是提倡的做法，因为这样可以很简单的给读者提供 8) 注释 ------------------------------- +------- 注释是好的，不过有过度注释的危险。永远不要在注释里解释你的代码是如何运作的： 更好的做法是让别人一看你的代码就可以明白，解释写的很差的代码是浪费时间。 -一般的，你想要你的注释告诉别人你的代码做了什么，而不是怎么做的。也请你不要把 +一般来说你用注释告诉别人你的代码做了什么，而不是怎么做的。也请你不要把 注释放在一个函数体内部：如果函数复杂到你需要独立的注释其中的一部分，你很可能 需要回到第六章看一看。你可以做一些小注释来注明或警告某些很聪明 (或者槽糕) 的 做法，但不要加太多。你应该做的，是把注释放在函数的头部，告诉人们它做了什么， 也可以加上它做这些事情的原因。 -当注释内核 API 函数时，请使用 kernel-doc 格式。请看 -Documentation/doc-guide/ 和 scripts/kernel-doc 以获得详细信息。 +当注释内核 API 函数时，请使用 kernel-doc 格式。详见 +Documentation/translations/zh_CN/doc-guide/index.rst 和 scripts/kernel-doc 。 长 (多行) 注释的首选风格是： @@ -500,17 +577,18 @@ Documentation/doc-guide/ 和 scripts/kernel-doc 以获得详细信息。 9) 你已经把事情弄糟了 ------------------------------- +--------------------- -这没什么，我们都是这样。可能你的使用了很长时间 Unix 的朋友已经告诉你 +这没什么，我们都是这样。可能你长期使用 Unix 的朋友已经告诉你 ``GNU emacs`` 能自动帮你格式化 C 源代码，而且你也注意到了，确实是这样，不过它 所使用的默认值和我们想要的相去甚远 (实际上，甚至比随机打的还要差——无数个猴子 -在 GNU emacs 里打字永远不会创造出一个好程序) (译注：Infinite Monkey Theorem) +在 GNU emacs 里打字永远不会创造出一个好程序) +*(译注：Infinite Monkey Theorem)* 所以你要么放弃 GNU emacs，要么改变它让它使用更合理的设定。要采用后一个方案， 你可以把下面这段粘贴到你的 .emacs 文件里。 -.. code-block:: none +.. code-block:: elisp (defun c-lineup-arglist-tabs-only (ignored) "Line up argument lists by tabs, not spaces" @@ -529,7 +607,7 @@ Documentation/doc-guide/ 和 scripts/kernel-doc 以获得详细信息。 (c-offsets-alist . ( (arglist-close . c-lineup-arglist-tabs-only) (arglist-cont-nonempty . - (c-lineup-gcc-asm-reg c-lineup-arglist-tabs-only)) + (c-lineup-gcc-asm-reg c-lineup-arglist-tabs-only)) (arglist-intro . +) (brace-list-intro . +) (c . c-lineup-C-comments) @@ -573,9 +651,14 @@ Documentation/doc-guide/ 和 scripts/kernel-doc 以获得详细信息。 ``indent`` 有很多选项，特别是重新格式化注释的时候，你可能需要看一下它的手册。 不过记住： ``indent`` 不能修正坏的编程习惯。 +请注意，您还可以使用 ``clang-format`` 工具帮助您处理这些规则，快速自动重新格 +式化部分代码，并审阅整个文件以发现代码风格错误、打字错误和可能的改进。它还可 +以方便地排序 ``#include`` ，对齐变量/宏，重排文本和其他类似任务。 +详见 Documentation/process/clang-format.rst 。 + 10) Kconfig 配置文件 ------------------------------- +-------------------- 对于遍布源码树的所有 Kconfig* 配置文件来说，它们缩进方式有所不同。紧挨着 ``config`` 定义的行，用一个制表符缩进，然而 help 信息的缩进则额外增加 2 个空 @@ -598,11 +681,11 @@ Documentation/doc-guide/ 和 scripts/kernel-doc 以获得详细信息。 depends on ADFS_FS ... -要查看配置文件的完整文档，请看 Documentation/kbuild/kconfig-language.rst。 +要查看配置文件的完整文档，请看 Documentation/kbuild/kconfig-language.rst 。 11) 数据结构 ------------------------------- +------------ 如果一个数据结构，在创建和销毁它的单线执行环境之外可见，那么它必须要有一个引 用计数器。内核里没有垃圾收集 (并且内核之外的垃圾收集慢且效率低下)，这意味着你 @@ -626,7 +709,7 @@ mm_count)，和文件系统 (``struct super_block``: s_count 和 s_active) 中 12) 宏，枚举和RTL ------------------------------- +----------------- 用于定义常量的宏的名字及枚举里的标签需要大写。 @@ -638,7 +721,7 @@ mm_count)，和文件系统 (``struct super_block``: s_count 和 s_active) 中 宏的名字请用大写字母，不过形如函数的宏的名字可以用小写字母。 -一般的，如果能写成内联函数就不要写成像函数的宏。 +通常如果能写成内联函数就不要写成像函数的宏。 含有多个语句的宏应该被包含在一个 do-while 代码块里： @@ -696,18 +779,18 @@ mm_count)，和文件系统 (``struct super_block``: s_count 和 s_active) 中 (ret); \ }) -ret 是本地变量的通用名字 - __foo_ret 更不容易与一个已存在的变量冲突。 +ret 是本地变量的通用名字—— __foo_ret 更不容易与一个已存在的变量冲突。 cpp 手册对宏的讲解很详细。gcc internals 手册也详细讲解了 RTL，内核里的汇编语 言经常用到它。 13) 打印内核消息 ------------------------------- +---------------- -内核开发者应该是受过良好教育的。请一定注意内核信息的拼写，以给人以好的印象。 +内核开发者应该看起来有文化。请一定注意内核信息的拼写，以给人良好的印象。 不要用不规范的单词比如 ``dont``，而要用 ``do not`` 或者 ``don't`` 。保证这些信 -息简单明了,无歧义。 +息简单明了、无歧义。 内核信息不必以英文句号结束。 @@ -724,17 +807,18 @@ dev_info() 等等。对于那些不和某个特定设备相关连的信息，<li 或设定了 CONFIG_DYNAMIC_DEBUG。实际这同样是为了 dev_dbg()，一个相关约定是在一 个已经开启了 DEBUG 时，使用 VERBOSE_DEBUG 来添加 dev_vdbg()。 -许多子系统拥有 Kconfig 调试选项来开启 -DDEBUG 在对应的 Makefile 里面；在其他 +许多子系统拥有 Kconfig 调试选项来开启对应 Makefile 里面的 -DDEBUG；在其他 情况下，特殊文件使用 #define DEBUG。当一条调试信息需要被无条件打印时，例如， 如果已经包含一个调试相关的 #ifdef 条件，printk(KERN_DEBUG ...) 就可被使用。 14) 分配内存 ------------------------------- +------------ 内核提供了下面的一般用途的内存分配函数： kmalloc(), kzalloc(), kmalloc_array(), kcalloc(), vmalloc() 和 vzalloc()。 -请参考 API 文档以获取有关它们的详细信息。 +请参考 API 文档以获取有关它们的详细信息： +Documentation/translations/zh_CN/core-api/memory-allocation.rst 。 传递结构体大小的首选形式是这样的： @@ -761,11 +845,13 @@ kmalloc(), kzalloc(), kmalloc_array(), kcalloc(), vmalloc() 和 vzalloc()。 p = kcalloc(n, sizeof(...), ...); -两种形式检查分配大小 n * sizeof(...) 的溢出，如果溢出返回 NULL。 +两种形式都会检查分配 n * sizeof(...) 大小时内存的溢出，如果溢出返回 NULL。 +在没有 __GFP_NOWARN 的情况下使用时，这些通用分配函数都会在失败时发起堆栈转储， +因此当返回NULL时，没有必要发出额外的失败消息。 15) 内联弊病 ------------------------------- +------------ 有一个常见的误解是 ``内联`` 是 gcc 提供的可以让代码运行更快的一个选项。虽然使 用内联函数有时候是恰当的 (比如作为一种替代宏的方式，请看第十二章)，不过很多情 @@ -786,7 +872,7 @@ inline gcc 也可以自动使其内联。而且其他用户可能会要求移除 16) 函数返回值及命名 ------------------------------- +-------------------- 函数可以返回多种不同类型的值，最常见的一种是表明函数执行成功或者失败的值。这样 的一个值可以表示为一个错误代码整数 (-Exxx＝失败，0＝成功) 或者一个 ``成功`` @@ -797,7 +883,7 @@ inline gcc 也可以自动使其内联。而且其他用户可能会要求移除 产生这种 bug，请遵循下面的惯例:: 如果函数的名字是一个动作或者强制性的命令，那么这个函数应该返回错误代 - 码整数。如果是一个判断，那么函数应该返回一个 "成功" 布尔值。 + 码整数。如果是一个判断，那么函数应该返回一个“成功”布尔值。 比如， ``add work`` 是一个命令，所以 add_work() 在成功时返回 0，在失败时返回 -EBUSY。类似的，因为 ``PCI device present`` 是一个判断，所以 pci_dev_present() @@ -806,13 +892,35 @@ inline gcc 也可以自动使其内联。而且其他用户可能会要求移除 所有 EXPORTed 函数都必须遵守这个惯例，所有的公共函数也都应该如此。私有 (static) 函数不需要如此，但是我们也推荐这样做。 -返回值是实际计算结果而不是计算是否成功的标志的函数不受此惯例的限制。一般的， +返回值是实际计算结果而不是计算是否成功的标志的函数不受此惯例的限制。通常 他们通过返回一些正常值范围之外的结果来表示出错。典型的例子是返回指针的函数， 他们使用 NULL 或者 ERR_PTR 机制来报告错误。 +17) 使用布尔类型 +---------------- + +Linux内核布尔（bool）类型是C99 _Bool类型的别名。布尔值只能为0或1，而对布尔的 +隐式或显式转换将自动将值转换为true或false。在使用布尔类型时 **不需要** 构造， +它会消除一类错误。 + +使用布尔值时，应使用true和false定义，而不是1和0。 -17) 不要重新发明内核宏 ------------------------------- +布尔函数返回类型和堆栈变量总是可以在适当的时候使用。鼓励使用布尔来提高可读性， +并且布尔值在存储时通常比“int”更好。 + +如果缓存行布局或值的大小很重要，请不要使用布尔，因为其大小和对齐方式根据编译 +的体系结构而不同。针对对齐和大小进行优化的结构体不应使用布尔。 + +如果一个结构体有多个true/false值，请考虑将它们合并为具有1比特成员的位域，或使 +用适当的固定宽度类型，如u8。 + +类似地，对于函数参数，多个true/false值可以合并为单个按位的“标志”参数，如果调 +用点具有裸true/false常量，“标志”参数通常是更具可读性的替代方法。 + +总之，在结构体和参数中有限地使用布尔可以提高可读性。 + +18) 不要重新发明内核宏 +---------------------- 头文件 include/linux/kernel.h 包含了一些宏，你应该使用它们，而不要自己写一些 它们的变种。比如，如果你需要计算一个数组的长度，使用这个宏 @@ -832,11 +940,11 @@ inline gcc 也可以自动使其内联。而且其他用户可能会要求移除 在你的代码里自己重新定义。 -18) 编辑器模式行和其他需要罗嗦的事情 --------------------------------------------------- +19) 编辑器模式行和其他需要罗嗦的事情 +------------------------------------ 有一些编辑器可以解释嵌入在源文件里的由一些特殊标记标明的配置信息。比如，emacs -能够解释被标记成这样的行： +能够解析被标记成这样的行： .. code-block:: c @@ -852,7 +960,7 @@ inline gcc 也可以自动使其内联。而且其他用户可能会要求移除 End: */ -Vim 能够解释这样的标记： +Vim 能够解析这样的标记： .. code-block:: c @@ -863,8 +971,8 @@ Vim 能够解释这样的标记： 的模式，或者使用其他可以产生正确的缩进的巧妙方法。 -19) 内联汇编 ------------------------------- +20) 内联汇编 +------------ 在特定架构的代码中，你可能需要内联汇编与 CPU 和平台相关功能连接。需要这么做时 就不要犹豫。然而，当 C 可以完成工作时，不要平白无故地使用内联汇编。在可能的情 @@ -880,8 +988,8 @@ Vim 能够解释这样的标记： 移除了。你不必总是这样做，尽管，这不必要的举动会限制优化。 在写一个包含多条指令的单个内联汇编语句时，把每条指令用引号分割而且各占一行， -除了最后一条指令外，在每个指令结尾加上 \n\t，让汇编输出时可以正确地缩进下一条 -指令： +除了最后一条指令外，在每个指令结尾加上 ``\n\t`` ，让汇编输出时可以正确地缩进 +下一条指令： .. code-block:: c @@ -890,10 +998,10 @@ Vim 能够解释这样的标记： : /* outputs */ : /* inputs */ : /* clobbers */); -20) 条件编译 ------------------------------- +21) 条件编译 +------------ -只要可能，就不要在 .c 文件里面使用预处理条件 (#if, #ifdef)；这样做让代码更难 +只要可能，就不要在 .c 文件里面使用预处理条件 (#if, #ifdef)；这样做会让代码更难 阅读并且更难去跟踪逻辑。替代方案是，在头文件中用预处理条件提供给那些 .c 文件 使用，再给 #else 提供一个空桩 (no-op stub) 版本，然后在 .c 文件内无条件地调用 那些 (定义在头文件内的) 函数。这样做，编译器会避免为桩函数 (stub) 的调用生成 @@ -904,8 +1012,8 @@ Vim 能够解释这样的标记： 条件到这个辅助函数内。 如果你有一个在特定配置中，可能变成未使用的函数或变量，编译器会警告它定义了但 -未使用，把它标记为 __maybe_unused 而不是将它包含在一个预处理条件中。(然而，如 -果一个函数或变量总是未使用，就直接删除它。) +未使用，请把它标记为 __maybe_unused 而不是将它包含在一个预处理条件中。(然而， +如果一个函数或变量总是未使用，就直接删除它。) 在代码中，尽可能地使用 IS_ENABLED 宏来转化某个 Kconfig 标记为 C 的布尔 表达式，并在一般的 C 条件中使用它： @@ -931,23 +1039,45 @@ Vim 能够解释这样的标记： #endif /* CONFIG_SOMETHING */ -附录 I) 参考 -------------------- +附录 I) 参考资料 +---------------- -The C Programming Language, 第二版 +The C Programming Language, 2nd Edition 作者：Brian W. Kernighan 和 Denni M. Ritchie. Prentice Hall, Inc., 1988. -ISBN 0-13-110362-8 (软皮), 0-13-110370-9 (硬皮). +ISBN 0-13-110362-8 (平装), 0-13-110370-9 (精装). + +.. note:: + + 《C程序设计语言（第2版）》 + 作者：[美] Brian W. Kernighan / [美] Dennis M. Ritchie + 译者：徐宝文 / 李志 / 尤晋元（审校） + 出版社：机械工业出版社，2019 + ISBN：9787111617945 The Practice of Programming 作者：Brian W. Kernighan 和 Rob Pike. Addison-Wesley, Inc., 1999. ISBN 0-201-61586-X. +.. note:: + + 《程序设计实践》 + 作者：[美] Brian W. Kernighan / [美] Rob Pike + 出版社：机械工业出版社，2005 + ISBN：9787111091578 + + 《程序设计实践》 + 作者：[美] Brian W. Kernighan / Rob Pike + 译者：裘宗燕 + 出版社：机械工业出版社，2000 + ISBN：9787111075738 + GNU 手册 - 遵循 K&R 标准和此文本 - cpp, gcc, gcc internals and indent, 都可以从 https://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： +内核文档 Documentation/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/process/email-clients.rst b/Documentation/translations/zh_CN/process/email-clients.rst index 102023651118..34d51cdadc7b 100644 --- a/Documentation/translations/zh_CN/process/email-clients.rst +++ b/Documentation/translations/zh_CN/process/email-clients.rst @@ -1,17 +1,20 @@ -.. _cn_email_clients: +.. SPDX-License-Identifier: GPL-2.0-or-later .. include:: ../disclaimer-zh_CN.rst -:Original: :ref:`Documentation/process/email-clients.rst <email_clients>` +.. _cn_email_clients: -译者:: +:Original: Documentation/process/email-clients.rst - 中文版维护者： 贾威威 Harry Wei <harryxiyou@gmail.com> - 中文版翻译者： 贾威威 Harry Wei <harryxiyou@gmail.com> - 时奎亮 Alex Shi <alex.shi@linux.alibaba.com> - 中文版校译者： Yinglin Luan <synmyth@gmail.com> - Xiaochen Wang <wangxiaochen0@gmail.com> - yaxinsn <yaxinsn@163.com> +:译者: + - 贾威威 Harry Wei <harryxiyou@gmail.com> + - 时奎亮 Alex Shi <alexs@kernel.org> + - 吴想成 Wu XiangCheng <bobwxc@email.cn> + +:校译: + - Yinglin Luan <synmyth@gmail.com> + - Xiaochen Wang <wangxiaochen0@gmail.com> + - yaxinsn <yaxinsn@163.com> Linux邮件客户端配置信息 ======================= @@ -27,12 +30,17 @@ Git 改日志。如果工作正常，再将补丁发送到相应的邮件列表。 -普通配置 +通用配置 -------- + Linux内核补丁是通过邮件被提交的，最好把补丁作为邮件体的内嵌文本。有些维护者 接收附件，但是附件的内容格式应该是"text/plain"。然而，附件一般是不赞成的， 因为这会使补丁的引用部分在评论过程中变的很困难。 +同时也强烈建议在补丁或其他邮件的正文中使用纯文本格式。https://useplaintext.email +有助于了解如何配置你喜欢的邮件客户端，并在您还没有首选的情况下列出一些推荐的 +客户端。 + 用来发送Linux内核补丁的邮件客户端在发送补丁时应该处于文本的原始状态。例如， 他们不能改变或者删除制表符或者空格，甚至是在每一行的开头或者结尾。 @@ -40,17 +48,17 @@ Linux内核补丁是通过邮件被提交的，最好把补丁作为邮件体的 不要让你的邮件客户端进行自动换行。这样也会破坏你的补丁。 -邮件客户端不能改变文本的字符集编码方式。要发送的补丁只能是ASCII或者UTF-8编码方式， -如果你使用UTF-8编码方式发送邮件，那么你将会避免一些可能发生的字符集问题。 +邮件客户端不能改变文本的字符集编码方式。要发送的补丁只能是ASCII或者UTF-8编码 +方式，如果你使用UTF-8编码方式发送邮件，那么你将会避免一些可能发生的字符集问题。 -邮件客户端应该形成并且保持 References: 或者 In-Reply-To: 标题，那么 -邮件话题就不会中断。 +邮件客户端应该生成并且保持“References:”或者“In-Reply-To:”邮件头，这样邮件会话 +就不会中断。 -复制粘帖(或者剪贴粘帖)通常不能用于补丁，因为制表符会转换为空格。使用xclipboard, xclip -或者xcutsel也许可以，但是最好测试一下或者避免使用复制粘帖。 +复制粘帖(或者剪贴粘帖)通常不能用于补丁，因为制表符会转换为空格。使用xclipboard, +xclip或者xcutsel也许可以，但是最好测试一下或者避免使用复制粘帖。 -不要在使用PGP/GPG署名的邮件中包含补丁。这样会使得很多脚本不能读取和适用于你的补丁。 -（这个问题应该是可以修复的） +不要在使用PGP/GPG签名的邮件中包含补丁。这样会使得很多脚本不能读取和适用于你的 +补丁。（这个问题应该是可以修复的） 在给内核邮件列表发送补丁之前，给自己发送一个补丁是个不错的主意，保存接收到的 邮件，将补丁用'patch'命令打上，如果成功了，再给内核邮件列表发送。 @@ -58,98 +66,133 @@ Linux内核补丁是通过邮件被提交的，最好把补丁作为邮件体的 一些邮件客户端提示 ------------------ + 这里给出一些详细的MUA配置提示，可以用于给Linux内核发送补丁。这些并不意味是 所有的软件包配置总结。 说明： -TUI = 以文本为基础的用户接口 -GUI = 图形界面用户接口 + +- TUI = 以文本为基础的用户接口 +- GUI = 图形界面用户接口 Alpine (TUI) -~~~~~~~~~~~~ +************ 配置选项： -在"Sending Preferences"部分： -- "Do Not Send Flowed Text"必须开启 -- "Strip Whitespace Before Sending"必须关闭 +在 :menuselection:`Sending Preferences` 菜单： + +- :menuselection:`Do Not Send Flowed Text` 必须开启 +- :menuselection:`Strip Whitespace Before Sending` 必须关闭 + +当写邮件时，光标应该放在补丁会出现的地方，然后按下 :kbd:`CTRL-R` 组合键，使指 +定的补丁文件嵌入到邮件中。 + +Claws Mail (GUI) +**************** + +可以用，有人用它成功地发过补丁。 -当写邮件时，光标应该放在补丁会出现的地方，然后按下CTRL-R组合键，使指定的 -补丁文件嵌入到邮件中。 +用 :menuselection:`Message-->Insert File` (:kbd:`CTRL-I`) 或外置编辑器插入补丁。 + +若要在Claws编辑窗口重修改插入的补丁，需关闭 +:menuselection:`Configuration-->Preferences-->Compose-->Wrapping` +的 `Auto wrapping` 。 Evolution (GUI) -~~~~~~~~~~~~~~~ +*************** -一些开发者成功的使用它发送补丁 +一些开发者成功的使用它发送补丁。 -当选择邮件选项：Preformat - 从Format->Heading->Preformatted (Ctrl-7)或者工具栏 +撰写邮件时： +从 :menuselection:`格式-->段落样式-->预格式化` (:kbd:`CTRL-7`) +或工具栏选择 :menuselection:`预格式化` ； 然后使用： - Insert->Text File... (Alt-n x)插入补丁文件。 +:menuselection:`插入-->文本文件...` (:kbd:`ALT-N x`) 插入补丁文件。 -你还可以"diff -Nru old.c new.c | xclip"，选择Preformat，然后使用中间键进行粘帖。 +你还可以 ``diff -Nru old.c new.c | xclip`` ，选择 :menuselection:`预格式化` ， +然后使用鼠标中键进行粘帖。 Kmail (GUI) -~~~~~~~~~~~ +*********** 一些开发者成功的使用它发送补丁。 -默认设置不为HTML格式是合适的；不要启用它。 +默认撰写设置禁用HTML格式是合适的；不要启用它。 -当书写一封邮件的时候，在选项下面不要选择自动换行。唯一的缺点就是你在邮件中输入的任何文本 -都不会被自动换行，因此你必须在发送补丁之前手动换行。最简单的方法就是启用自动换行来书写邮件， -然后把它保存为草稿。一旦你在草稿中再次打开它，它已经全部自动换行了，那么你的邮件虽然没有 -选择自动换行，但是还不会失去已有的自动换行。 +当书写一封邮件的时候，在选项下面不要选择自动换行。唯一的缺点就是你在邮件中输 +入的任何文本都不会被自动换行，因此你必须在发送补丁之前手动换行。最简单的方法 +就是启用自动换行来书写邮件，然后把它保存为草稿。一旦你在草稿中再次打开它，它 +已经全部自动换行了，那么你的邮件虽然没有选择自动换行，但是还不会失去已有的自 +动换行。 -在邮件的底部，插入补丁之前，放上常用的补丁定界符：三个连字号(---)。 +在邮件的底部，插入补丁之前，放上常用的补丁定界符：三个连字符(``---``)。 -然后在"Message"菜单条目，选择插入文件，接着选取你的补丁文件。还有一个额外的选项，你可以 -通过它配置你的邮件建立工具栏菜单，还可以带上"insert file"图标。 +然后在 :menuselection:`信件` 菜单，选择 :menuselection:`插入文本文件` ，接 +着选取你的补丁文件。还有一个额外的选项，你可以通过它配置你的创建新邮件工具栏， +加上 :menuselection:`插入文本文件` 图标。 -你可以安全地通过GPG标记附件，但是内嵌补丁最好不要使用GPG标记它们。作为内嵌文本的签发补丁， -当从GPG中提取7位编码时会使他们变的更加复杂。 +将编辑器窗口拉到足够宽避免折行。对于KMail 1.13.5 (KDE 4.5.4)，它会在发送邮件 +时对编辑器窗口中显示折行的地方自动换行。在选项菜单中取消自动换行仍不能解决。 +因此，如果你的补丁中有非常长的行，必须在发送之前把编辑器窗口拉得非常宽。 +参见：https://bugs.kde.org/show_bug.cgi?id=174034 -如果你非要以附件的形式发送补丁，那么就右键点击附件，然后选中属性，突出"Suggest automatic -display"，这样内嵌附件更容易让读者看到。 +你可以安全地用GPG签名附件，但是内嵌补丁最好不要使用GPG签名它们。作为内嵌文本 +插入的签名补丁将使其难以从7-bit编码中提取。 -当你要保存将要发送的内嵌文本补丁，你可以从消息列表窗格选择包含补丁的邮件，然后右击选择 -"save as"。你可以使用一个没有更改的包含补丁的邮件，如果它是以正确的形式组成。当你正真在它 -自己的窗口之下察看，那时没有选项可以保存邮件--已经有一个这样的bug被汇报到了kmail的bugzilla -并且希望这将会被处理。邮件是以只针对某个用户可读写的权限被保存的，所以如果你想把邮件复制到其他地方， -你不得不把他们的权限改为组或者整体可读。 +如果你非要以附件的形式发送补丁，那么就右键点击附件，然后选择 +:menuselection:`属性` ，打开 :menuselection:`建议自动显示` ，使附件内联更容 +易让读者看到。 + +当你要保存将要发送的内嵌文本补丁，你可以从消息列表窗格选择包含补丁的邮件，然 +后右键选择 :menuselection:`另存为` 。如果整个电子邮件的组成正确，您可直接将 +其作为补丁使用。电子邮件以当前用户可读写权限保存，因此您必须 ``chmod`` ，以 +使其在复制到别处时用户组和其他人可读。 Lotus Notes (GUI) -~~~~~~~~~~~~~~~~~ +***************** 不要使用它。 +IBM Verse (Web GUI) +******************* + +同上条。 + Mutt (TUI) -~~~~~~~~~~ +********** + +很多Linux开发人员使用mutt客户端，这证明它肯定工作得非常漂亮。 -很多Linux开发人员使用mutt客户端，所以证明它肯定工作的非常漂亮。 +Mutt不自带编辑器，所以不管你使用什么编辑器，不自动断行就行。大多数编辑器都有 +:menuselection:`插入文件` 选项，它可以在不改变文件内容的情况下插入文件。 -Mutt不自带编辑器，所以不管你使用什么编辑器都不应该带有自动断行。大多数编辑器都带有 -一个"insert file"选项，它可以通过不改变文件内容的方式插入文件。 +用 ``vim`` 作为mutt的编辑器:: -'vim'作为mutt的编辑器： set editor="vi" - 如果使用xclip，敲入以下命令 +如果使用xclip，敲入以下命令:: + :set paste - 按中键之前或者shift-insert或者使用 + +然后再按中键或者shift-insert或者使用:: + :r filename -如果想要把补丁作为内嵌文本。 -(a)ttach工作的很好，不带有"set paste"。 +把补丁插入为内嵌文本。 +在未设置 ``set paste`` 时(a)ttach工作的很好。 你可以通过 ``git format-patch`` 生成补丁，然后用 Mutt发送它们:: - $ mutt -H 0001-some-bug-fix.patch + $ mutt -H 0001-some-bug-fix.patch 配置选项： + 它应该以默认设置的形式工作。 -然而，把"send_charset"设置为"us-ascii::utf-8"也是一个不错的主意。 +然而，把 ``send_charset`` 设置一下也是一个不错的主意:: + + set send_charset="us-ascii:utf-8" Mutt 是高度可配置的。 这里是个使用mutt通过 Gmail 发送的补丁的最小配置:: @@ -178,71 +221,107 @@ Mutt 是高度可配置的。 这里是个使用mutt通过 Gmail 发送的补丁 set from = "username@gmail.com" set use_from = yes -Mutt文档含有更多信息: +Mutt文档含有更多信息： - http://dev.mutt.org/trac/wiki/UseCases/Gmail + https://gitlab.com/muttmua/mutt/-/wikis/UseCases/Gmail - http://dev.mutt.org/doc/manual.html + http://www.mutt.org/doc/manual/ Pine (TUI) -~~~~~~~~~~ +********** Pine过去有一些空格删减问题，但是这些现在应该都被修复了。 -如果可以，请使用alpine(pine的继承者) +如果可以，请使用alpine（pine的继承者）。 配置选项： -- 最近的版本需要消除流程文本 -- "no-strip-whitespace-before-send"选项也是需要的。 + +- 最近的版本需要 ``quell-flowed-text`` +- ``no-strip-whitespace-before-send`` 选项也是需要的。 Sylpheed (GUI) -~~~~~~~~~~~~~~ +************** - 内嵌文本可以很好的工作（或者使用附件）。 - 允许使用外部的编辑器。 -- 对于目录较多时非常慢。 +- 收件箱较多时非常慢。 - 如果通过non-SSL连接，无法使用TLS SMTP授权。 -- 在组成窗口中有一个很有用的ruler bar。 -- 给地址本中添加地址就不会正确的了解显示名。 +- 撰写窗口的标尺很有用。 +- 将地址添加到通讯簿时无法正确理解显示的名称。 Thunderbird (GUI) -~~~~~~~~~~~~~~~~~ +***************** + +Thunderbird是Outlook的克隆版本，它很容易损坏文本，但也有一些方法强制修正。 + +在完成修改后（包括安装扩展），您需要重新启动Thunderbird。 + +- 允许使用外部编辑器： + + 使用Thunderbird发补丁最简单的方法是使用扩展来打开您最喜欢的外部编辑器。 + + 下面是一些能够做到这一点的扩展样例。 + + - “External Editor Revived” + + https://github.com/Frederick888/external-editor-revived + + https://addons.thunderbird.net/en-GB/thunderbird/addon/external-editor-revived/ + + 它需要安装“本地消息主机（native messaging host）”。 + 参见以下文档: + https://github.com/Frederick888/external-editor-revived/wiki + + - “External Editor” + + https://github.com/exteditor/exteditor + + 下载并安装此扩展，然后打开 :menuselection:`新建消息` 窗口, 用 + :menuselection:`查看-->工具栏-->自定义...` 给它增加一个按钮，直接点击此 + 按钮即可使用外置编辑器。 + + 请注意，“External Editor”要求你的编辑器不能fork，换句话说，编辑器必须在 + 关闭前不返回。你可能需要传递额外的参数或修改编辑器设置。最值得注意的是， + 如果您使用的是gvim，那么您必须将 :menuselection:`external editor` 设置的 + 编辑器字段设置为 ``/usr/bin/gvim --nofork"`` （假设可执行文件在 + ``/usr/bin`` ），以传递 ``-f`` 参数。如果您正在使用其他编辑器，请阅读其 + 手册了解如何处理。 -默认情况下，thunderbird很容易损坏文本，但是还有一些方法可以强制它变得更好。 +若要修正内部编辑器，请执行以下操作： -- 在用户帐号设置里，组成和寻址，不要选择"Compose messages in HTML format"。 +- 修改你的Thunderbird设置，不要使用 ``format=flowed`` ！ + 回到主窗口，按照 + :menuselection:`主菜单-->首选项-->常规-->配置编辑器...` + 打开Thunderbird的配置编辑器。 -- 编辑你的Thunderbird配置设置来使它不要拆行使用：user_pref("mailnews.wraplength", 0); + - 将 ``mailnews.send_plaintext_flowed`` 设为 ``false`` -- 编辑你的Thunderbird配置设置，使它不要使用"format=flowed"格式：user_pref("mailnews. - send_plaintext_flowed", false); + - 将 ``mailnews.wraplength`` 从 ``72`` 改为 ``0`` -- 你需要使Thunderbird变为预先格式方式： - 如果默认情况下你书写的是HTML格式，那不是很难。仅仅从标题栏的下拉框中选择"Preformat"格式。 - 如果默认情况下你书写的是文本格式，你不得把它改为HTML格式（仅仅作为一次性的）来书写新的消息， - 然后强制使它回到文本格式，否则它就会拆行。要实现它，在写信的图标上使用shift键来使它变为HTML - 格式，然后标题栏的下拉框中选择"Preformat"格式。 +- 不要写HTML邮件！ + 回到主窗口，打开 + :menuselection:`主菜单-->账户设置-->你的@邮件.地址-->通讯录/编写&地址簿` ， + 关掉 ``以HTML格式编写消息`` 。 -- 允许使用外部的编辑器： - 针对Thunderbird打补丁最简单的方法就是使用一个"external editor"扩展，然后使用你最喜欢的 - $EDITOR来读取或者合并补丁到文本中。要实现它，可以下载并且安装这个扩展，然后添加一个使用它的 - 按键View->Toolbars->Customize...最后当你书写信息的时候仅仅点击它就可以了。 +- 只用纯文本格式查看邮件！ + 回到主窗口， :menuselection:`主菜单-->查看-->消息体为-->纯文本` ！ TkRat (GUI) -~~~~~~~~~~~ +*********** 可以使用它。使用"Insert file..."或者外部的编辑器。 Gmail (Web GUI) -~~~~~~~~~~~~~~~ +*************** 不要使用它发送补丁。 Gmail网页客户端自动地把制表符转换为空格。 -虽然制表符转换为空格问题可以被外部编辑器解决，同时它还会使用回车换行把每行拆分为78个字符。 +虽然制表符转换为空格问题可以被外部编辑器解决，但它同时还会使用回车换行把每行 +拆分为78个字符。 -另一个问题是Gmail还会把任何不是ASCII的字符的信息改为base64编码。它把东西变的像欧洲人的名字。 +另一个问题是Gmail还会把任何含有非ASCII的字符的消息改用base64编码，如欧洲人的 +名字。 - ### diff --git a/Documentation/translations/zh_CN/process/embargoed-hardware-issues.rst b/Documentation/translations/zh_CN/process/embargoed-hardware-issues.rst index 88273ebe7823..cf5f1fca3d92 100644 --- a/Documentation/translations/zh_CN/process/embargoed-hardware-issues.rst +++ b/Documentation/translations/zh_CN/process/embargoed-hardware-issues.rst @@ -174,7 +174,7 @@ CVE分配 ============= ======================================================== ARM - AMD Tom Lendacky <tom.lendacky@amd.com> + AMD Tom Lendacky <thomas.lendacky@amd.com> IBM Intel Tony Luck <tony.luck@intel.com> Qualcomm Trilok Soni <tsoni@codeaurora.org> diff --git a/Documentation/translations/zh_CN/process/howto.rst b/Documentation/translations/zh_CN/process/howto.rst index 2903d7161bc8..888978a62db3 100644 --- a/Documentation/translations/zh_CN/process/howto.rst +++ b/Documentation/translations/zh_CN/process/howto.rst @@ -45,7 +45,7 @@ Linux内核大部分是由C语言写成的，一些体系结构相关的代码 - "C: A Reference Manual" by Harbison and Steele [Prentice Hall] 《C语言参考手册（原书第5版）》（邱仲潘 等译）[机械工业出版社] -Linux内核使用GNU C和GNU工具链开发。虽然它遵循ISO C89标准，但也用到了一些 +Linux内核使用GNU C和GNU工具链开发。虽然它遵循ISO C11标准，但也用到了一些 标准中没有定义的扩展。内核是自给自足的C环境，不依赖于标准C库的支持，所以 并不支持C标准中的部分定义。比如long long类型的大数除法和浮点运算就不允许 使用。有时候确实很难弄清楚内核对工具链的要求和它所使用的扩展，不幸的是目 @@ -96,7 +96,6 @@ Linux内核代码中包含有大量的文档。这些文档对于学习如何与 的代码。 :ref:`Documentation/translations/zh_CN/process/submitting-patches.rst <cn_submittingpatches>` - :ref:`Documentation/process/submitting-drivers.rst <submittingdrivers>` 这两份文档明确描述如何创建和发送补丁，其中包括（但不仅限于)： - 邮件内容 @@ -252,7 +251,7 @@ Linux-next 集成测试树 在将子系统树的更新合并到主线树之前，需要对它们进行集成测试。为此，存在一个 特殊的测试存储库，其中几乎每天都会提取所有子系统树： - https://git.kernel.org/？p=linux/kernel/git/next/linux-next.git + https://git.kernel.org/?p=linux/kernel/git/next/linux-next.git 通过这种方式，Linux-next 对下一个合并阶段将进入主线内核的内容给出了一个概要 展望。非常欢冒险的测试者运行测试Linux-next。 @@ -307,7 +306,7 @@ bugzilla.kernel.org是Linux内核开发者们用来跟踪内核Bug的网站。 网上很多地方都有这个邮件列表的存档(archive)。可以使用搜索引擎来找到这些 存档。比如： - http://dir.gmane.org/gmane.linux.kernel + https://lore.kernel.org/lkml/ 在发信之前，我们强烈建议你先在存档中搜索你想要讨论的问题。很多已经被详细 讨论过的问题只在邮件列表的存档中可以找到。 diff --git a/Documentation/translations/zh_CN/process/index.rst b/Documentation/translations/zh_CN/process/index.rst index 39e9c88fbaa6..a1a35f88f4ae 100644 --- a/Documentation/translations/zh_CN/process/index.rst +++ b/Documentation/translations/zh_CN/process/index.rst @@ -10,6 +10,7 @@ .. _cn_process_index: +======================== 与Linux 内核社区一起工作 ======================== @@ -40,7 +41,6 @@ .. toctree:: :maxdepth: 1 - submitting-drivers submit-checklist stable-api-nonsense stable-kernel-rules diff --git a/Documentation/translations/zh_CN/process/magic-number.rst b/Documentation/translations/zh_CN/process/magic-number.rst index 42f0635ca70a..0617ce125e12 100644 --- a/Documentation/translations/zh_CN/process/magic-number.rst +++ b/Documentation/translations/zh_CN/process/magic-number.rst @@ -58,87 +58,17 @@ Linux 魔术数 魔术数名 数字 结构 文件 ===================== ================ ======================== ========================================== 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`` -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`` -PTY_MAGIC 0x5001 ``drivers/char/pty.c`` -PPP_MAGIC 0x5002 ppp ``include/linux/if_pppvar.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`` -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`` -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`` -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`` -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 ``fs/coda/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/process/programming-language.rst b/Documentation/translations/zh_CN/process/programming-language.rst index 2a47a1d2ec20..fabdc338dbfb 100644 --- a/Documentation/translations/zh_CN/process/programming-language.rst +++ b/Documentation/translations/zh_CN/process/programming-language.rst @@ -9,8 +9,7 @@ ============ 内核是用C语言 :ref:`c-language <cn_c-language>` 编写的。更准确地说，内核通常是用 :ref:`gcc <cn_gcc>` -在 ``-std=gnu89`` :ref:`gcc-c-dialect-options <cn_gcc-c-dialect-options>` 下编译的：ISO C90的 GNU 方言（ -包括一些C99特性） +在 ``-std=gnu11`` :ref:`gcc-c-dialect-options <cn_gcc-c-dialect-options>` 下编译的：ISO C11的 GNU 方言 这种方言包含对语言 :ref:`gnu-extensions <cn_gnu-extensions>` 的许多扩展，当然，它们许多都在内核中使用。 diff --git a/Documentation/translations/zh_CN/process/submit-checklist.rst b/Documentation/translations/zh_CN/process/submit-checklist.rst index a64858d321fc..3d6ee21c74ae 100644 --- a/Documentation/translations/zh_CN/process/submit-checklist.rst +++ b/Documentation/translations/zh_CN/process/submit-checklist.rst @@ -1,105 +1,111 @@ .. include:: ../disclaimer-zh_CN.rst -:Original: :ref:`Documentation/process/submit-checklist.rst <submitchecklist>` -:Translator: Alex Shi <alex.shi@linux.alibaba.com> +:Original: Documentation/process/submit-checklist.rst +:Translator: + - Alex Shi <alexs@kernel.org> + - Wu XiangCheng <bobwxc@email.cn> .. _cn_submitchecklist: -Linux内核补丁提交清单 -~~~~~~~~~~~~~~~~~~~~~ +Linux内核补丁提交检查单 +~~~~~~~~~~~~~~~~~~~~~~~ 如果开发人员希望看到他们的内核补丁提交更快地被接受，那么他们应该做一些基本 的事情。 -这些都是在 -:ref:`Documentation/translations/zh_CN/process/submitting-patches.rst <cn_submittingpatches>` +这些都是在 Documentation/translations/zh_CN/process/submitting-patches.rst 和其他有关提交Linux内核补丁的文档中提供的。 -1) 如果使用工具，则包括定义/声明该工具的文件。不要依赖于其他头文件拉入您使用 +1) 如果使用工具，则包括定义/声明该工具的文件。不要依赖其他头文件来引入您使用 的头文件。 2) 干净的编译： - a) 使用适用或修改的 ``CONFIG`` 选项 ``=y``、``=m`` 和 ``=n`` 。没有GCC + a) 使用合适的 ``CONFIG`` 选项 ``=y``、``=m`` 和 ``=n`` 。没有 ``gcc`` 警告/错误，没有链接器警告/错误。 - b) 通过allnoconfig、allmodconfig + b) 通过 ``allnoconfig`` 、 ``allmodconfig`` c) 使用 ``O=builddir`` 时可以成功编译 -3) 通过使用本地交叉编译工具或其他一些构建场在多个CPU体系结构上构建。 + d) 任何 Doucmentation/ 下的变更都能成功构建且不引入新警告/错误。 + 用 ``make htmldocs`` 或 ``make pdfdocs`` 检验构建情况并修复问题。 + +3) 通过使用本地交叉编译工具或其他一些构建设施在多个CPU体系结构上构建。 4) PPC64是一种很好的交叉编译检查体系结构，因为它倾向于对64位的数使用无符号 长整型。 -5) 如下所述 :ref:`Documentation/translations/zh_CN/process/coding-style.rst <cn_codingstyle>`. - 检查您的补丁是否为常规样式。在提交（ ``scripts/check patch.pl`` ）之前， - 使用补丁样式检查器检查是否有轻微的冲突。您应该能够处理您的补丁中存在的所有 +5) 按 Documentation/translations/zh_CN/process/coding-style.rst 所述检查您的 + 补丁是否为常规样式。在提交之前使用补丁样式检查器 ``scripts/checkpatch.pl`` + 检查是否有轻微的冲突。您应该能够处理您的补丁中存在的所有 违规行为。 -6) 任何新的或修改过的 ``CONFIG`` 选项都不会弄脏配置菜单，并默认为关闭，除非 - 它们符合 ``Documentation/kbuild/kconfig-language.rst`` 中记录的异常条件, - 菜单属性：默认值. +6) 任何新的或修改过的 ``CONFIG`` 选项都不应搞乱配置菜单，并默认为关闭，除非 + 它们符合 ``Documentation/kbuild/kconfig-language.rst`` 菜单属性：默认值中 + 记录的例外条件。 7) 所有新的 ``kconfig`` 选项都有帮助文本。 8) 已仔细审查了相关的 ``Kconfig`` 组合。这很难用测试来纠正——脑力在这里是有 回报的。 -9) 用 sparse 检查干净。 +9) 通过 sparse 清查。 + （参见 Documentation/translations/zh_CN/dev-tools/sparse.rst ） 10) 使用 ``make checkstack`` 和 ``make namespacecheck`` 并修复他们发现的任何 问题。 .. note:: - ``checkstack`` 并没有明确指出问题，但是任何一个在堆栈上使用超过512 + ``checkstack`` 并不会明确指出问题，但是任何一个在堆栈上使用超过512 字节的函数都可以进行更改。 -11) 包括 :ref:`kernel-doc <kernel_doc>` 内核文档以记录全局内核API。（静态函数 - 不需要，但也可以。）使用 ``make htmldocs`` 或 ``make pdfdocs`` 检查 - :ref:`kernel-doc <kernel_doc>` 并修复任何问题。 +11) 包括 :ref:`kernel-doc <kernel_doc_zh>` 内核文档以记录全局内核API。（静态 + 函数不需要，但也可以。）使用 ``make htmldocs`` 或 ``make pdfdocs`` 检查 + :ref:`kernel-doc <kernel_doc_zh>` 并修复任何问题。 -12) 通过以下选项同时启用的测试 ``CONFIG_PREEMPT``, ``CONFIG_DEBUG_PREEMPT``, +12) 通过以下选项同时启用的测试： ``CONFIG_PREEMPT``, ``CONFIG_DEBUG_PREEMPT``, ``CONFIG_DEBUG_SLAB``, ``CONFIG_DEBUG_PAGEALLOC``, ``CONFIG_DEBUG_MUTEXES``, ``CONFIG_DEBUG_SPINLOCK``, ``CONFIG_DEBUG_ATOMIC_SLEEP``, - ``CONFIG_PROVE_RCU`` and ``CONFIG_DEBUG_OBJECTS_RCU_HEAD`` - -13) 已经过构建和运行时测试，包括有或没有 ``CONFIG_SMP``, ``CONFIG_PREEMPT``. + ``CONFIG_PROVE_RCU`` 和 ``CONFIG_DEBUG_OBJECTS_RCU_HEAD`` 。 -14) 如果补丁程序影响IO/磁盘等：使用或不使用 ``CONFIG_LBDAF`` 进行测试。 +13) 在 ``CONFIG_SMP``, ``CONFIG_PREEMPT`` 开启和关闭的情况下都进行构建和运行 + 时测试。 -15) 所有代码路径都已在启用所有lockdep功能的情况下运行。 +14) 所有代码路径都已在启用所有死锁检测（lockdep）功能的情况下运行。 -16) 所有新的/proc条目都记录在 ``Documentation/`` +15) 所有新的 ``/proc`` 条目都记录在 ``Documentation/`` -17) 所有新的内核引导参数都记录在 +16) 所有新的内核引导参数都记录在 Documentation/admin-guide/kernel-parameters.rst 中。 -18) 所有新的模块参数都记录在 ``MODULE_PARM_DESC()`` +17) 所有新的模块参数都记录在 ``MODULE_PARM_DESC()`` -19) 所有新的用户空间接口都记录在 ``Documentation/ABI/`` 中。有关详细信息， +18) 所有新的用户空间接口都记录在 ``Documentation/ABI/`` 中。有关详细信息， 请参阅 ``Documentation/ABI/README`` 。更改用户空间接口的补丁应该抄送 linux-api@vger.kernel.org。 -20) 已通过至少注入slab和page分配失败进行检查。请参阅 ``Documentation/fault-injection/`` +19) 已通过至少注入slab和page分配失败进行检查。请参阅 ``Documentation/fault-injection/`` 。 如果新代码是实质性的，那么添加子系统特定的故障注入可能是合适的。 -21) 新添加的代码已经用 ``gcc -W`` 编译（使用 ``make EXTRA-CFLAGS=-W`` ）。这 +20) 新添加的代码已经用 ``gcc -W`` 编译（使用 ``make EXTRA-CFLAGS=-W`` ）。这 将产生大量噪声，但对于查找诸如“警告：有符号和无符号之间的比较”之类的错误 很有用。 -22) 在它被合并到-mm补丁集中之后进行测试，以确保它仍然与所有其他排队的补丁以 +21) 在它被合并到-mm补丁集中之后进行测试，以确保它仍然与所有其他排队的补丁以 及VM、VFS和其他子系统中的各种更改一起工作。 -23) 所有内存屏障例如 ``barrier()``, ``rmb()``, ``wmb()`` 都需要源代码中的注 +22) 所有内存屏障（例如 ``barrier()``, ``rmb()``, ``wmb()`` ）都需要源代码注 释来解释它们正在执行的操作及其原因的逻辑。 -24) 如果补丁添加了任何ioctl，那么也要更新 ``Documentation/userspace-api/ioctl/ioctl-number.rst`` +23) 如果补丁添加了任何ioctl，那么也要更新 + ``Documentation/userspace-api/ioctl/ioctl-number.rst`` 。 -25) 如果修改后的源代码依赖或使用与以下 ``Kconfig`` 符号相关的任何内核API或 +24) 如果修改后的源代码依赖或使用与以下 ``Kconfig`` 符号相关的任何内核API或 功能，则在禁用相关 ``Kconfig`` 符号和/或 ``=m`` （如果该选项可用）的情况 下测试以下多个构建[并非所有这些都同时存在，只是它们的各种/随机组合]： - ``CONFIG_SMP``, ``CONFIG_SYSFS``, ``CONFIG_PROC_FS``, ``CONFIG_INPUT``, ``CONFIG_PCI``, ``CONFIG_BLOCK``, ``CONFIG_PM``, ``CONFIG_MAGIC_SYSRQ``, - ``CONFIG_NET``, ``CONFIG_INET=n`` (但是后者伴随 ``CONFIG_NET=y``). + ``CONFIG_SMP``, ``CONFIG_SYSFS``, ``CONFIG_PROC_FS``, ``CONFIG_INPUT``, + ``CONFIG_PCI``, ``CONFIG_BLOCK``, ``CONFIG_PM``, ``CONFIG_MAGIC_SYSRQ``, + ``CONFIG_NET``, ``CONFIG_INET=n`` （但是最后一个需要 ``CONFIG_NET=y`` ）。 diff --git a/Documentation/translations/zh_CN/process/submitting-drivers.rst b/Documentation/translations/zh_CN/process/submitting-drivers.rst deleted file mode 100644 index 98341e7cd812..000000000000 --- a/Documentation/translations/zh_CN/process/submitting-drivers.rst +++ /dev/null @@ -1,160 +0,0 @@ -.. _cn_submittingdrivers: - -.. include:: ../disclaimer-zh_CN.rst - -:Original: :ref:`Documentation/process/submitting-drivers.rst - <submittingdrivers>` - -如果想评论或更新本文的内容，请直接联系原文档的维护者。如果你使用英文 -交流有困难的话，也可以向中文版维护者求助。如果本翻译更新不及时或者翻 -译存在问题，请联系中文版维护者:: - - 中文版维护者： 李阳 Li Yang <leoyang.li@nxp.com> - 中文版翻译者： 李阳 Li Yang <leoyang.li@nxp.com> - 中文版校译者： 陈琦 Maggie Chen <chenqi@beyondsoft.com> - 王聪 Wang Cong <xiyou.wangcong@gmail.com> - 张巍 Zhang Wei <wezhang@outlook.com> - -如何向 Linux 内核提交驱动程序 -============================= - -这篇文档将会解释如何向不同的内核源码树提交设备驱动程序。请注意，如果你感 -兴趣的是显卡驱动程序，你也许应该访问 XFree86 项目(https://www.xfree86.org/) -和／或 X.org 项目 (https://x.org)。 - -另请参阅 Documentation/translations/zh_CN/process/submitting-patches.rst 文档。 - - -分配设备号 ----------- - -块设备和字符设备的主设备号与从设备号是由 Linux 命名编号分配权威 LANANA（ -现在是 Torben Mathiasen）负责分配。申请的网址是 https://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.rst。有关驱动程序电 - 源管理问题相对全面的概述，请参阅 - 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 版内核）： - https://lwn.net/Kernel/LDD3/ （免费版） - -LWN.net: - 每周内核开发活动摘要 - https://lwn.net/ - - 2.6 版中 API 的变更： - - https://lwn.net/Articles/2.6-kernel-api/ - - 将旧版内核的驱动程序移植到 2.6 版： - - https://lwn.net/Articles/driver-porting/ - -内核新手(KernelNewbies): - 为新的内核开发者提供文档和帮助 - https://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): - https://kernelnewbies.org/KernelJanitors diff --git a/Documentation/translations/zh_CN/process/submitting-patches.rst b/Documentation/translations/zh_CN/process/submitting-patches.rst index a9570165582a..f8978f02057c 100644 --- a/Documentation/translations/zh_CN/process/submitting-patches.rst +++ b/Documentation/translations/zh_CN/process/submitting-patches.rst @@ -1,144 +1,92 @@ -.. _cn_submittingpatches: +.. SPDX-License-Identifier: GPL-2.0-or-later .. include:: ../disclaimer-zh_CN.rst -:Original: :ref:`Documentation/process/submitting-patches.rst <submittingpatches>` +.. _cn_submittingpatches: + +:Original: Documentation/process/submitting-patches.rst -译者:: +:译者: + - 钟宇 TripleX Chung <xxx.phy@gmail.com> + - 时奎亮 Alex Shi <alexs@kernel.org> + - 吴想成 Wu XiangCheng <bobwxc@email.cn> - 中文版维护者： 钟宇 TripleX Chung <xxx.phy@gmail.com> - 中文版翻译者： 钟宇 TripleX Chung <xxx.phy@gmail.com> - 时奎亮 Alex Shi <alex.shi@linux.alibaba.com> - 中文版校译者： 李阳 Li Yang <leoyang.li@nxp.com> - 王聪 Wang Cong <xiyou.wangcong@gmail.com> +:校译: + - 李阳 Li Yang <leoyang.li@nxp.com> + - 王聪 Wang Cong <xiyou.wangcong@gmail.com> -如何让你的改动进入内核 -====================== +提交补丁：如何让你的改动进入内核 +================================ 对于想要将改动提交到 Linux 内核的个人或者公司来说，如果不熟悉“规矩”， -提交的流程会让人畏惧。本文档收集了一系列建议，这些建议可以大大的提高你 +提交的流程会让人畏惧。本文档包含了一系列建议，可以大大提高你 的改动被接受的机会. -以下文档含有大量简洁的建议， 具体请见： -:ref:`Documentation/process <development_process_main>` -同样，:ref:`Documentation/translations/zh_CN/process/submit-checklist.rst <cn_submitchecklist>` -给出在提交代码前需要检查的项目的列表。如果你在提交一个驱动程序，那么 -同时阅读一下: -:ref:`Documentation/process/submitting-drivers.rst <submittingdrivers>` +本文档以较为简洁的行文给出了大量建议。关于内核开发流程如何进行的详细信息， +参见： Documentation/translations/zh_CN/process/development-process.rst 。 +Documentation/translations/zh_CN/process/submit-checklist.rst 给出了一系列 +提交补丁之前要检查的事项。设备树相关的补丁，请参阅 +Documentation/devicetree/bindings/submitting-patches.rst 。 -其中许多步骤描述了Git版本控制系统的默认行为；如果您使用Git来准备补丁， -您将发现它为您完成的大部分机械工作，尽管您仍然需要准备和记录一组合理的 -补丁。一般来说，使用git将使您作为内核开发人员的生活更轻松。 +本文档假设您正在使用 ``git`` 准备你的补丁。如果您不熟悉 ``git`` ，最好学习 +如何使用它，这将使您作为内核开发人员的生活变得更加轻松。 +部分子系统和维护人员的树有一些关于其工作流程和要求的额外信息，请参阅 +Documentation/process/maintainer-handbooks.rst 。 -0) 获取当前源码树 ------------------ +获取当前源码树 +-------------- -如果您没有一个可以使用当前内核源代码的存储库，请使用git获取一个。您将要 -从主线存储库开始，它可以通过以下方式获取:: +如果您手头没有当前内核源代码的存储库，请使用 ``git`` 获取一份。您需要先获取 +主线存储库，它可以通过以下命令拉取:: - git clone git://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git + git clone git://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git -但是，请注意，您可能不希望直接针对主线树进行开发。大多数子系统维护人员运 +但是，请注意，您可能不想直接针对主线树进行开发。大多数子系统维护人员运 行自己的树，并希望看到针对这些树准备的补丁。请参见MAINTAINERS文件中子系 -统的 **T:** 项以查找该树，或者简单地询问维护者该树是否未在其中列出。 - -仍然可以通过tarballs下载内核版本（如下一节所述），但这是进行内核开发的 -一种困难的方式。 - -1) "diff -up" -------------- - -使用 "diff -up" 或者 "diff -uprN" 来创建补丁。 - -所有内核的改动，都是以补丁的形式呈现的，补丁由 diff(1) 生成。创建补丁的 -时候，要确认它是以 "unified diff" 格式创建的，这种格式由 diff(1) 的 '-u' -参数生成。而且，请使用 '-p' 参数，那样会显示每个改动所在的C函数，使得 -产生的补丁容易读得多。补丁应该基于内核源代码树的根目录，而不是里边的任 -何子目录。 - -为一个单独的文件创建补丁，一般来说这样做就够了:: - - SRCTREE=linux - MYFILE=drivers/net/mydriver.c +统的 **T:** 项以查找该树，或者直接询问维护者该树是否未在其中列出。 - cd $SRCTREE - cp $MYFILE $MYFILE.orig - vi $MYFILE # make your change - cd .. - diff -up $SRCTREE/$MYFILE{.orig,} > /tmp/patch +.. _zh_describe_changes: -为多个文件创建补丁，你可以解开一个没有修改过的内核源代码树，然后和你自 -己的代码树之间做 diff 。例如:: - - MYSRC=/devel/linux - - tar xvfz linux-3.19.tar.gz - mv linux-3.19 linux-3.19-vanilla - diff -uprN -X linux-3.19-vanilla/Documentation/dontdiff \ - linux-3.19-vanilla $MYSRC > /tmp/patch - -"dontdiff" 是内核在编译的时候产生的文件的列表，列表中的文件在 diff(1) -产生的补丁里会被跳过。 - -确定你的补丁里没有包含任何不属于这次补丁提交的额外文件。记得在用diff(1) -生成补丁之后，审阅一次补丁，以确保准确。 - -如果你的改动很散乱，你应该研究一下如何将补丁分割成独立的部分，将改动分 -割成一系列合乎逻辑的步骤。这样更容易让其他内核开发者审核，如果你想你的 -补丁被接受，这是很重要的。请参阅： -:ref:`cn_split_changes` - -如果你用 ``git`` , ``git rebase -i`` 可以帮助你这一点。如果你不用 ``git``, -``quilt`` <https://savannah.nongnu.org/projects/quilt> 另外一个流行的选择。 - -.. _cn_describe_changes: - -2) 描述你的改动 ---------------- +描述你的改动 +------------ 描述你的问题。无论您的补丁是一行错误修复还是5000行新功能，都必须有一个潜在 -的问题激励您完成这项工作。让审稿人相信有一个问题值得解决，让他们读完第一段 -是有意义的。 +的问题激励您完成这项工作。说服审阅者相信有一个问题值得解决，让他们读完第一段 +后就能明白这一点。 描述用户可见的影响。直接崩溃和锁定是相当有说服力的，但并不是所有的错误都那么 -明目张胆。即使在代码审查期间发现了这个问题，也要描述一下您认为它可能对用户产 +明目张胆。即使在代码审阅期间发现了这个问题，也要描述一下您认为它可能对用户产 生的影响。请记住，大多数Linux安装运行的内核来自二级稳定树或特定于供应商/产品 的树，只从上游精选特定的补丁，因此请包含任何可以帮助您将更改定位到下游的内容： 触发的场景、DMESG的摘录、崩溃描述、性能回归、延迟尖峰、锁定等。 -量化优化和权衡。如果您声称在性能、内存消耗、堆栈占用空间或二进制大小方面有所 -改进，请包括支持它们的数字。但也要描述不明显的成本。优化通常不是免费的，而是 -在CPU、内存和可读性之间进行权衡；或者，探索性的工作，在不同的工作负载之间进 +质量优化和权衡。如果您声称在性能、内存消耗、堆栈占用空间或二进制大小方面有所 +改进，请包括支持它们的数据。但也要描述不明显的成本。优化通常不是零成本的，而是 +在CPU、内存和可读性之间进行权衡；或者，做探索性的工作，在不同的工作负载之间进 行权衡。请描述优化的预期缺点，以便审阅者可以权衡成本和收益。 -一旦问题建立起来，就要详细地描述一下您实际在做什么。对于审阅者来说，用简单的 -英语描述代码的变化是很重要的，以验证代码的行为是否符合您的意愿。 +提出问题之后，就要详细地描述一下您实际在做的技术细节。对于审阅者来说，用简练的 +英语描述代码的变化是很重要的，以验证代码的行为是否符合您的意图。 -如果您将补丁描述写在一个表单中，这个表单可以很容易地作为“提交日志”放入Linux -的源代码管理系统git中，那么维护人员将非常感谢您。见 :ref:`cn_explicit_in_reply_to`. +如果您将补丁描述写成“标准格式”，可以很容易地作为“提交日志”放入Linux的源代 +码管理系统 ``git`` 中，那么维护人员将非常感谢您。 +参见 :ref:`zh_the_canonical_patch_format` 。 每个补丁只解决一个问题。如果你的描述开始变长，这就表明你可能需要拆分你的补丁。 -请见 :ref:`cn_split_changes` +请见 :ref:`zh_split_changes` 。 -提交或重新提交修补程序或修补程序系列时，请包括完整的修补程序说明和理由。不要 +提交或重新提交补丁或补丁系列时，请包括完整的补丁说明和理由。不要 只说这是补丁（系列）的第几版。不要期望子系统维护人员引用更早的补丁版本或引用 URL来查找补丁描述并将其放入补丁中。也就是说，补丁（系列）及其描述应该是独立的。 -这对维护人员和审查人员都有好处。一些评审者可能甚至没有收到补丁的早期版本。 +这对维护人员和审阅者都有好处。一些审阅者可能甚至没有收到补丁的早期版本。 -描述你在命令语气中的变化，例如“make xyzzy do frotz”而不是“[This patch]make +用祈使句描述你的变更，例如“make xyzzy do frotz”而不是“[This patch]make xyzzy do frotz”或“[I]changed xyzzy to do frotz”，就好像你在命令代码库改变 它的行为一样。 -如果修补程序修复了一个记录的bug条目，请按编号和URL引用该bug条目。如果补丁来 -自邮件列表讨论，请给出邮件列表存档的URL；使用带有 ``Message-ID`` 的 -https://lore.kernel.org/ 重定向，以确保链接不会过时。 - -但是，在没有外部资源的情况下，尽量让你的解释可理解。除了提供邮件列表存档或 -bug的URL之外，还要总结需要提交补丁的相关讨论要点。 - -如果您想要引用一个特定的提交，不要只引用提交的 SHA-1 ID。还请包括提交的一行 +如果您想要引用一个特定的提交，不要只引用提交的SHA-1 ID。还请包括提交的一行 摘要，以便于审阅者了解它是关于什么的。例如:: Commit e21d2170f36602ae2708 ("video: remove unnecessary @@ -146,82 +94,104 @@ bug的URL之外，还要总结需要提交补丁的相关讨论要点。 platform_set_drvdata(), but left the variable "dev" unused, delete it. -您还应该确保至少使用前12位 SHA-1 ID. 内核存储库包含*许多*对象，使与较短的ID +您还应该确保至少使用前12位SHA-1 ID。内核存储库包含 *许多* 对象，使较短的ID 发生冲突的可能性很大。记住，即使现在不会与您的六个字符ID发生冲突，这种情况 -可能五年后改变。 +也可能在五年后改变。 + +如果该变更的相关讨论或背景信息可以在网上查阅，请加上“Link:”标签指向它。例如 +你的补丁修复了一个缺陷，需要添加一个带有URL的标签指向邮件列表存档或缺陷跟踪器 +的相关报告；如果该补丁是由一些早先邮件列表讨论或网络上的记录引起的，请指向它。 + +当链接到邮件列表存档时，请首选lore.kernel.org邮件存档服务。用邮件中的 +``Message-ID`` 头（去掉尖括号）可以创建链接URL。例如:: + + Link: https://lore.kernel.org/r/30th.anniversary.repost@klaava.Helsinki.FI/ + +请检查该链接以确保可用且指向正确的邮件。 -如果修补程序修复了特定提交中的错误，例如，使用 ``git bisct`` ，请使用带有前 -12个字符SHA-1 ID 的"Fixes:"标记和单行摘要。为了简化不要将标记拆分为多个， -行、标记不受分析脚本“75列换行”规则的限制。例如:: +不过，在没有外部资源的情况下，也要尽量让你的解释可理解。除了提供邮件列表存档或 +缺陷的URL之外，还要需要总结该补丁的相关讨论要点。 - Fixes: 54a4f0239f2e ("KVM: MMU: make kvm_mmu_zap_page() return the number of pages it actually freed") +如果补丁修复了特定提交中的错误，例如使用 ``git bisct`` 发现了一个问题，请使用 +带有前12个字符SHA-1 ID的“Fixes:”标签和单行摘要。为了简化解析脚本，不要将该 +标签拆分为多行，标签不受“75列换行”规则的限制。例如:: -下列 ``git config`` 设置可以添加让 ``git log``, ``git show`` 漂亮的显示格式:: + Fixes: 54a4f0239f2e ("KVM: MMU: make kvm_mmu_zap_page() return the number of pages it actually freed") + +下列 ``git config`` 设置可以让 ``git log``, ``git show`` 增加上述风格的显示格式:: [core] abbrev = 12 [pretty] fixes = Fixes: %h (\"%s\") -.. _cn_split_changes: +使用示例:: + + $ git log -1 --pretty=fixes 54a4f0239f2e + Fixes: 54a4f0239f2e ("KVM: MMU: make kvm_mmu_zap_page() return the number of pages it actually freed") -3) 拆分你的改动 ---------------- +.. _zh_split_changes: -将每个逻辑更改分隔成一个单独的补丁。 +拆分你的改动 +------------ + +将每个 **逻辑更改** 拆分成一个单独的补丁。 例如，如果你的改动里同时有bug修正和性能优化，那么把这些改动拆分到两个或 -者更多的补丁文件中。如果你的改动包含对API的修改，并且修改了驱动程序来适 -应这些新的API，那么把这些修改分成两个补丁。 +者更多的补丁文件中。如果你的改动包含对API的修改，并且增加了一个使用该新API +的驱动，那么把这些修改分成两个补丁。 另一方面，如果你将一个单独的改动做成多个补丁文件，那么将它们合并成一个 单独的补丁文件。这样一个逻辑上单独的改动只被包含在一个补丁文件里。 -如果有一个补丁依赖另外一个补丁来完成它的改动，那没问题。简单的在你的补 -丁描述里指出“这个补丁依赖某补丁”就好了。 +需要记住的一点是，每个补丁的更改都应易于理解，以便审阅者验证。每个补丁都应该 +对其价值进行阐述。 + +如果有一个补丁依赖另外一个补丁来完成它的改动，那没问题。直接在你的补 +丁描述里指出 **“这个补丁依赖某补丁”** 就好了。 -在将您的更改划分为一系列补丁时，要特别注意确保内核在系列中的每个补丁之后 -都能正常构建和运行。使用 ``git bisect`` 来追踪问题的开发者可能会在任何时 -候分割你的补丁系列；如果你在中间引入错误，他们不会感谢你。 +在将您的更改划分为一系列补丁时，要特别注意确保内核在应用系列中的每个补丁之后 +都能正常构建和运行。使用 ``git bisect`` 来追踪问题的开发者可能会在任何地方分 +割你的补丁系列；如果你在中间引入错误，他们不会感谢你。 -如果你不能将补丁浓缩成更少的文件，那么每次大约发送出15个，然后等待审查 +如果你不能将补丁系列浓缩得更小，那么每次大约发送出15个补丁，然后等待审阅 和集成。 -4) 检查你的更改风格 -------------------- +检查你的更改风格 +---------------- -检查您的补丁是否存在基本样式冲突，详细信息可在 -:ref:`Documentation/translations/zh_CN/process/coding-style.rst <cn_codingstyle>` -中找到。如果不这样做，只会浪费审稿人的时间，并且会导致你的补丁被拒绝，甚至 +检查您的补丁是否违反了基本样式规定，详细信息参见 +Documentation/translations/zh_CN/process/coding-style.rst +中找到。如果不这样做，只会浪费审阅者的时间，并且会导致你的补丁被拒绝，甚至 可能没有被阅读。 一个重要的例外是在将代码从一个文件移动到另一个文件时——在这种情况下，您不应 该在移动代码的同一个补丁中修改移动的代码。这清楚地描述了移动代码和您的更改 -的行为。这大大有助于审查实际差异，并允许工具更好地跟踪代码本身的历史。 +的行为。这大大有助于审阅实际差异，并允许工具更好地跟踪代码本身的历史。 在提交之前，使用补丁样式检查程序检查补丁（scripts/check patch.pl）。不过， 请注意，样式检查程序应该被视为一个指南，而不是作为人类判断的替代品。如果您 -的代码看起来更好，但有违规行为，那么最好不要使用它。 +的代码看起来更好，但有违规行为，那么最好别管它。 检查者报告三个级别： - ERROR：很可能出错的事情 - - WARNING：需要仔细审查的事项 + - WARNING：需要仔细审阅的事项 - CHECK：需要思考的事情 您应该能够判断您的补丁中存在的所有违规行为。 -5) 选择补丁收件人 ------------------ +选择补丁收件人 +-------------- -您应该总是在任何补丁上复制相应的子系统维护人员，以获得他们维护的代码；查看 +您应该总是知会任何补丁相应代码的子系统维护人员；查看 维护人员文件和源代码修订历史记录，以了解这些维护人员是谁。脚本 -scripts/get_Maintainer.pl在这个步骤中非常有用。如果您找不到正在工作的子系统 +scripts/get_maintainer.pl在这个步骤中非常有用。如果您找不到正在工作的子系统 的维护人员，那么Andrew Morton（akpm@linux-foundation.org）将充当最后的维护 人员。 -您通常还应该选择至少一个邮件列表来接收补丁集的。linux-kernel@vger.kernel.org -作为最后一个解决办法的列表，但是这个列表上的体积已经引起了许多开发人员的拒绝。 +您通常还应该选择至少一个邮件列表来接收补丁集的副本。linux-kernel@vger.kernel.org +是所有补丁的默认列表，但是这个列表的流量已经导致了许多开发人员不再看它。 在MAINTAINERS文件中查找子系统特定的列表；您的补丁可能会在那里得到更多的关注。 不过，请不要发送垃圾邮件到无关的列表。 @@ -231,189 +201,170 @@ http://vger.kernel.org/vger-lists.html 上找到它们的列表。不过，也 不要一次发送超过15个补丁到vger邮件列表！！！！ -Linus Torvalds 是决定改动能否进入 Linux 内核的最终裁决者。他的 e-mail -地址是 <torvalds@linux-foundation.org> 。他收到的 e-mail 很多，所以一般 -的说，最好别给他发 e-mail。 - -如果您有修复可利用安全漏洞的补丁，请将该补丁发送到 security@kernel.org。对于 -严重的bug，可以考虑短期暂停以允许分销商向用户发布补丁；在这种情况下，显然不应 -将补丁发送到任何公共列表。 +Linus Torvalds是决定改动能否进入 Linux 内核的最终裁决者。他的邮件地址是 +torvalds@linux-foundation.org 。他收到的邮件很多，所以一般来说最好 **别** +给他发邮件。 -修复已发布内核中严重错误的补丁程序应该指向稳定版维护人员，方法是放这样的一行:: +如果您有修复可利用安全漏洞的补丁，请将该补丁发送到 security@kernel.org 。对于 +严重的bug，可以考虑短期禁令以允许分销商（有时间）向用户发布补丁；在这种情况下， +显然不应将补丁发送到任何公共列表。 +参见 Documentation/translations/zh_CN/admin-guide/security-bugs.rst 。 - Cc: stable@vger.kernel.org +修复已发布内核中严重错误的补丁程序应该抄送给稳定版维护人员，方法是把以下列行 +放进补丁的签准区（注意，不是电子邮件收件人）:: -进入补丁的签准区（注意，不是电子邮件收件人）。除了这个文件之外，您还应该阅读 -:ref:`Documentation/process/stable-kernel-rules.rst <stable_kernel_rules>` + Cc: stable@vger.kernel.org -但是，请注意，一些子系统维护人员希望得出他们自己的结论，即哪些补丁应该被放到 -稳定的树上。尤其是网络维护人员，不希望看到单个开发人员在补丁中添加像上面这样 -的行。 +除了本文件之外，您还应该阅读 +Documentation/translations/zh_CN/process/stable-kernel-rules.rst 。 -如果更改影响到用户和内核接口，请向手册页维护人员（如维护人员文件中所列）发送 +如果更改影响到用户侧内核接口，请向手册页维护人员（如维护人员文件中所列）发送 手册页补丁，或至少发送更改通知，以便一些信息进入手册页。还应将用户空间API -更改复制到 linux-api@vger.kernel.org。 +更改抄送到 linux-api@vger.kernel.org 。 -6) 没有 MIME 编码，没有链接，没有压缩，没有附件，只有纯文本 ------------------------------------------------------------ +不要MIME编码，不要链接，不要压缩，不要附件，只要纯文本 +------------------------------------------------------ Linus 和其他的内核开发者需要阅读和评论你提交的改动。对于内核开发者来说 -，可以“引用”你的改动很重要，使用一般的 e-mail 工具，他们就可以在你的 +，可以“引用”你的改动很重要，使用一般的邮件工具，他们就可以在你的 代码的任何位置添加评论。 -因为这个原因，所有的提交的补丁都是 e-mail 中“内嵌”的。 +因为这个原因，所有的提交的补丁都是邮件中“内嵌”的。最简单（和推荐）的方法就 +是使用 ``git send-email`` 。https://git-send-email.io 有 ``git send-email`` +的交互式教程。 + +如果你选择不用 ``git send-email`` ： .. warning:: - 如果你使用剪切-粘贴你的补丁，小心你的编辑器的自动换行功能破坏你的补丁 -不要将补丁作为 MIME 编码的附件，不管是否压缩。很多流行的 e-mail 软件不 -是任何时候都将 MIME 编码的附件当作纯文本发送的，这会使得别人无法在你的 -代码中加评论。另外，MIME 编码的附件会让 Linus 多花一点时间来处理，这就 -降低了你的改动被接受的可能性。 + 如果你使用剪切-粘贴你的补丁，小心你的编辑器的自动换行功能破坏你的补丁 -例外：如果你的邮递员弄坏了补丁，那么有人可能会要求你使用mime重新发送补丁 +不要将补丁作为MIME编码的附件，不管是否压缩。很多流行的邮件软件不 +是任何时候都将MIME编码的附件当作纯文本发送的，这会使得别人无法在你的 +代码中加评论。另外，MIME编码的附件会让Linus多花一点时间来处理，这就 +降低了你的改动被接受的可能性。 -请参阅 :ref:`Documentation/translations/zh_CN/process/email-clients.rst <cn_email_clients>` -以获取有关配置电子邮件客户端以使其不受影响地发送修补程序的提示。 +例外：如果你的邮路损坏了补丁，那么有人可能会要求你使用MIME重新发送补丁。 -7) e-mail 的大小 ----------------- +请参阅 Documentation/translations/zh_CN/process/email-clients.rst +以获取有关配置电子邮件客户端以使其不受影响地发送补丁的提示。 -大的改动对邮件列表不合适，对某些维护者也不合适。如果你的补丁，在不压缩 -的情况下，超过了300kB，那么你最好将补丁放在一个能通过 internet 访问的服 -务器上，然后用指向你的补丁的 URL 替代。但是请注意，如果您的补丁超过了 -300kb，那么它几乎肯定需要被破坏。 +回复审阅意见 +------------ -8）回复评审意见 ---------------- +你的补丁几乎肯定会得到审阅者对补丁改进方法的评论（以回复邮件的形式）。您必须 +对这些评论作出回应；让补丁被忽略的一个好办法就是忽略审阅者的意见。直接回复邮 +件来回应意见即可。不会导致代码更改的意见或问题几乎肯定会带来注释或变更日志的 +改变，以便下一个审阅者更好地了解正在发生的事情。 -你的补丁几乎肯定会得到评审者对补丁改进方法的评论。您必须对这些评论作出 -回应；让补丁被忽略的一个好办法就是忽略审阅者的意见。不会导致代码更改的 -意见或问题几乎肯定会带来注释或变更日志的改变，以便下一个评审者更好地了解 -正在发生的事情。 +一定要告诉审阅者你在做什么改变，并感谢他们的时间。代码审阅是一个累人且耗时的 +过程，审阅者有时会变得暴躁。即使在这种情况下，也要礼貌地回应并解决他们指出的 +问题。当发送下一版时，在封面邮件或独立补丁里加上 ``patch changelog`` 说明与 +前一版本的不同之处（参见 :ref:`zh_the_canonical_patch_format` ）。 -一定要告诉审稿人你在做什么改变，并感谢他们的时间。代码审查是一个累人且 -耗时的过程，审查人员有时会变得暴躁。即使在这种情况下，也要礼貌地回应并 -解决他们指出的问题。 +.. _zh_resend_reminders: -9）不要泄气或不耐烦 -------------------- +不要泄气或不耐烦 +---------------- -提交更改后，请耐心等待。审阅者是忙碌的人，可能无法立即访问您的修补程序。 +提交更改后，请耐心等待。审阅者是大忙人，可能无法立即审阅您的补丁。 -曾几何时，补丁曾在没有评论的情况下消失在空白中，但开发过程比现在更加顺利。 +曾几何时，补丁曾在没收到评论的情况下消失在虚空中，但现在开发过程应该更加顺利了。 您应该在一周左右的时间内收到评论；如果没有收到评论，请确保您已将补丁发送 -到正确的位置。在重新提交或联系审阅者之前至少等待一周-在诸如合并窗口之类的 +到正确的位置。在重新提交或联系审阅者之前至少等待一周——在诸如合并窗口之类的 繁忙时间可能更长。 -10）主题中包含 PATCH --------------------- +在等了几个星期后，用带RESEND的主题重发补丁也是可以的:: -由于到linus和linux内核的电子邮件流量很高，通常会在主题行前面加上[PATCH] -前缀. 这使Linus和其他内核开发人员更容易将补丁与其他电子邮件讨论区分开。 + [PATCH Vx RESEND] sub/sys: Condensed patch summary -11）签署你的作品-开发者原始认证 -------------------------------- +当你发布补丁（系列）修改版的时候，不要加上“RESEND”——“RESEND”只适用于重 +新提交之前未经修改的补丁（系列）。 -为了加强对谁做了何事的追踪，尤其是对那些透过好几层的维护者的补丁，我们 -建议在发送出去的补丁上加一个 “sign-off” 的过程。 +主题中包含 PATCH +---------------- -"sign-off" 是在补丁的注释的最后的简单的一行文字，认证你编写了它或者其他 +由于到Linus和linux-kernel的电子邮件流量很高，通常会在主题行前面加上[PATCH] +前缀。这使Linus和其他内核开发人员更容易将补丁与其他电子邮件讨论区分开。 + +``git send-email`` 会自动为你加上。 + +签署你的作品——开发者来源认证 +------------------------------ + +为了加强对谁做了何事的追踪，尤其是对那些透过好几层维护者才最终到达的补丁，我 +们在通过邮件发送的补丁上引入了“签署（sign-off）”流程。 + +“签署”是在补丁注释最后的一行简单文字，认证你编写了它或者其他 人有权力将它作为开放源代码的补丁传递。规则很简单：如果你能认证如下信息: -开发者来源证书 1.1 +开发者来源认证 1.1 ^^^^^^^^^^^^^^^^^^ 对于本项目的贡献，我认证如下信息： - （a）这些贡献是完全或者部分的由我创建，我有权利以文件中指出 + (a) 这些贡献是完全或者部分的由我创建，我有权利以文件中指出 的开放源代码许可证提交它；或者 - （b）这些贡献基于以前的工作，据我所知，这些以前的工作受恰当的开放 - 源代码许可证保护，而且，根据许可证，我有权提交修改后的贡献， + + (b) 这些贡献基于以前的工作，据我所知，这些以前的工作受恰当的开放 + 源代码许可证保护，而且，根据文件中指出的许可证，我有权提交修改后的贡献， 无论是完全还是部分由我创造，这些贡献都使用同一个开放源代码许可证 - （除非我被允许用其它的许可证），正如文件中指出的；或者 - （c）这些贡献由认证（a），（b）或者（c）的人直接提供给我，而 + （除非我被允许用其它的许可证）；或者 + + (c) 这些贡献由认证（a），（b）或者（c）的人直接提供给我，而 且我没有修改它。 - （d）我理解并同意这个项目和贡献是公开的，贡献的记录（包括我 - 一起提交的个人记录，包括 sign-off ）被永久维护并且可以和这个项目 + + (d) 我理解并同意这个项目和贡献是公开的，贡献的记录（包括我 + 一起提交的个人记录，包括sign-off）被永久维护并且可以和这个项目 或者开放源代码的许可证同步地再发行。 那么加入这样一行:: - Signed-off-by: Random J Developer <random@developer.example.org> - -使用你的真名（抱歉，不能使用假名或者匿名。） - -有人在最后加上标签。现在这些东西会被忽略，但是你可以这样做，来标记公司 -内部的过程，或者只是指出关于 sign-off 的一些特殊细节。 - -如果您是子系统或分支维护人员，有时需要稍微修改收到的补丁，以便合并它们， -因为树和提交者中的代码不完全相同。如果你严格遵守规则（c），你应该要求提交者 -重新发布，但这完全是在浪费时间和精力。规则（b）允许您调整代码，但是更改一个 -提交者的代码并让他认可您的错误是非常不礼貌的。要解决此问题，建议在最后一个 -由签名行和您的行之间添加一行，指示更改的性质。虽然这并不是强制性的，但似乎 -在描述前加上您的邮件和/或姓名（全部用方括号括起来），这足以让人注意到您对最 -后一分钟的更改负有责任。例如:: - - 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> - -如果您维护一个稳定的分支机构，同时希望对作者进行致谢、跟踪更改、合并修复并 -保护提交者不受投诉，那么这种做法尤其有用。请注意，在任何情况下都不能更改作者 -的ID（From 头），因为它是出现在更改日志中的标识。 - -对回合（back-porters）的特别说明：在提交消息的顶部（主题行之后）插入一个补丁 -的起源指示似乎是一种常见且有用的实践，以便于跟踪。例如，下面是我们在3.x稳定 -版本中看到的内容:: - - Date: Tue Oct 7 07:26:38 2014 -0400 - - libata: Un-break ATA blacklist - - commit 1c40279960bcd7d52dbdf1d466b20d24b99176c8 upstream. - -还有， 这里是一个旧版内核中的一个回合补丁:: + Signed-off-by: Random J Developer <random@developer.example.org> - Date: Tue May 13 22:12:27 2008 +0200 +使用你的真名（抱歉，不能使用假名或者匿名。）如果使用 ``git commit -s`` 的话 +将会自动完成。撤销也应当包含“Signed-off-by”， ``git revert -s`` 会帮你搞定。 - wireless, airo: waitbusy() won't delay +有些人会在最后加上额外的标签。现在这些东西会被忽略，但是你可以这样做，来标记 +公司内部的过程，或者只是指出关于签署的一些特殊细节。 - [backport of 2.6 commit b7acbdfbd1f277c1eb23f344f899cfa4cd0bf36a] +作者签署之后的任何其他签署（Signed-off-by:'s）均来自处理和传递补丁的人员，但 +未参与其开发。签署链应当反映补丁传播到维护者并最终传播到Linus所经过的 **真实** +路径，首个签署指明单个作者的主要作者身份。 -12）何时使用Acked-by:，CC:，和Co-Developed by: ----------------------------------------------- +何时使用Acked-by:，CC:，和Co-Developed by: +------------------------------------------ -Singed-off-by: 标记表示签名者参与了补丁的开发，或者他/她在补丁的传递路径中。 +Singed-off-by: 标签表示签名者参与了补丁的开发，或者他/她在补丁的传递路径中。 -如果一个人没有直接参与补丁的准备或处理，但希望表示并记录他们对补丁的批准， -那么他们可以要求在补丁的变更日志中添加一个 Acked-by: +如果一个人没有直接参与补丁的准备或处理，但希望表示并记录他们对补丁的批准/赞成， +那么他们可以要求在补丁的变更日志中添加一个Acked-by:。 -Acked-by：通常由受影响代码的维护者使用，当该维护者既没有贡献也没有转发补丁时。 +Acked-by: 通常由受影响代码的维护者使用，当该维护者既没有贡献也没有转发补丁时。 -Acked-by: 不像签字人那样正式。这是一个记录，确认人至少审查了补丁，并表示接受。 -因此，补丁合并有时会手动将Acker的“Yep，looks good to me”转换为 Acked-By：（但 +Acked-by: 不像签署那样正式。这是一个记录，确认人至少审阅了补丁，并表示接受。 +因此，补丁合并有时会手动将Acker的“Yep，looks good to me”转换为 Acked-By:（但 请注意，通常最好要求一个明确的Ack）。 Acked-by：不一定表示对整个补丁的确认。例如，如果一个补丁影响多个子系统，并且 -有一个：来自一个子系统维护者，那么这通常表示只确认影响维护者代码的部分。这里 -应该仔细判断。如有疑问，应参考邮件列表档案中的原始讨论。 +有一个来自某个子系统维护者的Acked-By:，那么这通常表示只确认影响维护者代码的部 +分。这里应该仔细判断。如有疑问，应参考邮件列表存档中的原始讨论。 -如果某人有机会对补丁进行评论，但没有提供此类评论，您可以选择在补丁中添加 ``Cc:`` -这是唯一一个标签，它可以在没有被它命名的人显式操作的情况下添加，但它应该表明 -这个人是在补丁上抄送的。讨论中包含了潜在利益相关方。 +如果某人本应有机会对补丁进行评论，但没有提供此类评论，您可以选择在补丁中添加 +``Cc:`` 这是唯一可以在没有被该人明确同意的情况下添加的标签——但它应该表明 +这个人是在补丁上抄送的。此标签记录了讨论中包含的潜在利益相关方。 Co-developed-by: 声明补丁是由多个开发人员共同创建的；当几个人在一个补丁上工 -作时，它用于将属性赋予共同作者（除了 From: 所赋予的作者之外）。因为 -Co-developed-by: 表示作者身份，所以每个共同开发人：必须紧跟在相关合作作者的 -签名之后。标准的签核程序要求：标记的签核顺序应尽可能反映补丁的时间历史，而不 -管作者是通过 From ：还是由 Co-developed-by: 共同开发的。值得注意的是，最后一 -个签字人：必须始终是提交补丁的开发人员。 +作时，它用于给出共同作者（除了From:所给出的作者之外）。因为Co-developed-by: +表示作者身份，所以每个Co-developed-by:必须紧跟在相关合作作者的签署之后。标准 +签署程序要求Singed-off-by:标签的顺序应尽可能反映补丁的时间历史，无论作者是通 +过From:还是Co-developed-by:表明。值得注意的是，最后一个Singed-off-by:必须是 +提交补丁的开发人员。 -注意，当作者也是电子邮件标题“发件人：”行中列出的人时，“From: ” 标记是可选的。 +注意，如果From:作者也是电子邮件标题的From:行中列出的人，则From:标签是可选的。 -作者提交的补丁程序示例:: +被From:作者提交的补丁示例:: <changelog> @@ -423,7 +374,7 @@ Co-developed-by: 表示作者身份，所以每个共同开发人：必须紧跟 Signed-off-by: Second Co-Author <second@coauthor.example.org> Signed-off-by: From Author <from@author.example.org> -合作开发者提交的补丁示例:: +被合作开发者提交的补丁示例:: From: From Author <from@author.example.org> @@ -436,76 +387,85 @@ Co-developed-by: 表示作者身份，所以每个共同开发人：必须紧跟 Signed-off-by: Submitting Co-Author <sub@coauthor.example.org> -13）使用报告人：、测试人：、审核人：、建议人：、修复人： --------------------------------------------------------- +使用Reported-by:、Tested-by:、Reviewed-by:、Suggested-by:和Fixes: +----------------------------------------------------------------- Reported-by: 给那些发现错误并报告错误的人致谢，它希望激励他们在将来再次帮助 -我们。请注意，如果bug是以私有方式报告的，那么在使用Reported-by标记之前，请 -先请求权限。 +我们。请注意，如果bug是以私有方式报告的，那么在使用Reported-by标签之前，请 +先请求许可。此标签是为Bug设计的；请不要将其用于感谢功能请求。 -Tested-by: 标记表示补丁已由指定的人（在某些环境中）成功测试。这个标签通知 -维护人员已经执行了一些测试，为将来的补丁提供了一种定位测试人员的方法，并确 -保测试人员的信誉。 +Tested-by: 标签表示补丁已由指定的人（在某些环境中）成功测试。这个标签通知 +维护人员已经执行了一些测试，为将来的补丁提供了一种定位测试人员的方法，并彰显测试人员的功劳。 -Reviewed-by：相反，根据审查人的声明，表明该补丁已被审查并被认为是可接受的： +Reviewed-by：根据审阅者的监督声明，表明该补丁已被审阅并被认为是可接受的： -审查人的监督声明 +审阅者的监督声明 ^^^^^^^^^^^^^^^^ -通过提供我的 Reviewed-by，我声明： +通过提供我的Reviewed-by:标签，我声明： - (a) 我已经对这个补丁进行了一次技术审查，以评估它是否适合被包含到 + (a) 我已经对这个补丁进行了一次技术审阅，以评估它是否适合被包含到 主线内核中。 (b) 与补丁相关的任何问题、顾虑或问题都已反馈给提交者。我对提交者对 我的评论的回应感到满意。 - (c) 虽然这一提交可能会改进一些东西，但我相信，此时，（1）对内核 + (c) 虽然这一提交可能仍可被改进，但我相信，此时，（1）对内核 进行了有价值的修改，（2）没有包含争论中涉及的已知问题。 - (d) 虽然我已经审查了补丁并认为它是健全的，但我不会（除非另有明确 - 说明）作出任何保证或保证它将在任何给定情况下实现其规定的目的 + (d) 虽然我已经审阅了补丁并认为它是健全的，但我不会（除非另有明确 + 说明）作出任何保证或担保它会在任何给定情况下实现其规定的目的 或正常运行。 -Reviewed-by 是一种观点声明，即补丁是对内核的适当修改，没有任何遗留的严重技术 -问题。任何感兴趣的审阅者（完成工作的人）都可以为一个补丁提供一个 Review-by -标签。此标签用于向审阅者提供致谢，并通知维护者已在修补程序上完成的审阅程度。 -Reviewed-by: 当由已知了解主题区域并执行彻底检查的审阅者提供时，通常会增加 +Reviewed-by是一种观点声明，即补丁是对内核的适当修改，没有任何遗留的严重技术 +问题。任何感兴趣的审阅者（完成工作的人）都可以为一个补丁提供一个Reviewed-by +标签。此标签用于向审阅者提供致谢，并通知维护者补丁的审阅进度。 +当Reviewed-by:标签由已知了解主题区域并执行彻底检查的审阅者提供时，通常会增加 补丁进入内核的可能性。 +一旦从测试人员或审阅者的“Tested-by”和“Reviewed-by”标签出现在邮件列表中， +作者应在发送下一个版本时将其添加到适用的补丁中。但是，如果补丁在以下版本中发 +生了实质性更改，这些标签可能不再适用，因此应该删除。通常，在补丁更改日志中 +（在 ``---`` 分隔符之后）应该提到删除某人的测试者或审阅者标签。 + Suggested-by: 表示补丁的想法是由指定的人提出的，并确保将此想法归功于指定的 人。请注意，未经许可，不得添加此标签，特别是如果该想法未在公共论坛上发布。 -这就是说，如果我们勤快地致谢我们的创意者，他们很有希望在未来得到鼓舞，再次 +也就是说，如果我们勤快地致谢创意提供者，他们将受到鼓舞，很有希望在未来再次 帮助我们。 -Fixes: 指示补丁在以前的提交中修复了一个问题。它可以很容易地确定错误的来源， -这有助于检查错误修复。这个标记还帮助稳定内核团队确定应该接收修复的稳定内核 -版本。这是指示补丁修复的错误的首选方法。请参阅 :ref:`cn_describe_changes` -描述您的更改以了解更多详细信息。 +Fixes: 指示补丁修复了之前提交的一个问题。它可以便于确定错误的来源，这有助于 +检查错误修复。这个标签还帮助稳定内核团队确定应该接收修复的稳定内核版本。这是 +指示补丁修复的错误的首选方法。请参阅 :ref:`zh_describe_changes` 了解更多信息。 -.. _cn_the_canonical_patch_format: +.. note:: -12）标准补丁格式 ----------------- + 附加Fixes:标签不会改变稳定内核规则流程，也不改变所有稳定版补丁抄送 + stable@vger.kernel.org的要求。有关更多信息，请阅读 + Documentation/translations/zh_CN/process/stable-kernel-rules.rst 。 + +.. _zh_the_canonical_patch_format: + +标准补丁格式 +------------ 本节描述如何格式化补丁本身。请注意，如果您的补丁存储在 ``Git`` 存储库中，则 -可以使用 ``git format-patch`` 进行正确的补丁格式设置。但是，这些工具无法创建 +可以使用 ``git format-patch`` 进行正确的补丁格式化。但是，这些工具无法创建 必要的文本，因此请务必阅读下面的说明。 -标准的补丁，标题行是:: +标准的补丁标题行是:: Subject: [PATCH 001/123] 子系统:一句话概述 -标准补丁的信体存在如下部分： +标准补丁的信体包含如下部分： - - 一个 "from" 行指出补丁作者。后跟空行（仅当发送修补程序的人不是作者时才需要）。 + - 一个 ``from`` 行指出补丁作者。后跟空行（仅当发送补丁的人不是作者时才需要）。 - - 解释的正文，行以75列包装，这将被复制到永久变更日志来描述这个补丁。 + - 说明文字，每行最长75列，这将被复制到永久变更日志来描述这个补丁。 - 一个空行 - - 上面描述的“Signed-off-by” 行，也将出现在更改日志中。 + - 上述的 ``Signed-off-by:`` 行，也将出现在更改日志中。 - 只包含 ``---`` 的标记线。 @@ -513,29 +473,29 @@ Fixes: 指示补丁在以前的提交中修复了一个问题。它可以很容 - 实际补丁（ ``diff`` 输出）。 -标题行的格式，使得对标题行按字母序排序非常的容易 - 很多 e-mail 客户端都 -可以支持 - 因为序列号是用零填充的，所以按数字排序和按字母排序是一样的。 +标题行的格式，使得对标题行按字母序排序非常的容易——很多邮件客户端都 +可以支持——因为序列号是用零填充的，所以按数字排序和按字母排序是一样的。 -e-mail 标题中的“子系统”标识哪个内核子系统将被打补丁。 +邮件标题中的“子系统”标识哪个内核子系统将被打补丁。 -e-mail 标题中的“一句话概述”扼要的描述 e-mail 中的补丁。“一句话概述” +邮件标题中的“一句话概述”扼要的描述邮件中的补丁。“一句话概述” 不应该是一个文件名。对于一个补丁系列（“补丁系列”指一系列的多个相关补 丁），不要对每个补丁都使用同样的“一句话概述”。 -记住 e-mail 的“一句话概述”会成为该补丁的全局唯一标识。它会蔓延到 git +记住邮件的“一句话概述”会成为该补丁的全局唯一标识。它会进入 ``git`` 的改动记录里。然后“一句话概述”会被用在开发者的讨论里，用来指代这个补 -丁。用户将希望通过 google 来搜索"一句话概述"来找到那些讨论这个补丁的文 +丁。用户将希望通过搜索引擎搜索“一句话概述”来找到那些讨论这个补丁的文 章。当人们在两三个月后使用诸如 ``gitk`` 或 ``git log --oneline`` 之类 的工具查看数千个补丁时，也会很快看到它。 出于这些原因，概述必须不超过70-75个字符，并且必须描述补丁的更改以及为 -什么需要补丁。既要简洁又要描述性很有挑战性，但写得好的概述应该这样做。 +什么需要补丁。既要简洁又要描述性很有挑战性，但写得好的概述应该这样。 概述的前缀可以用方括号括起来：“Subject: [PATCH <tag>...] <概述>”。标记 不被视为概述的一部分，而是描述应该如何处理补丁。如果补丁的多个版本已发 -送出来以响应评审（即“v1，v2，v3”）或“rfc”，以指示评审请求，那么通用标记 -可能包括版本描述符。如果一个补丁系列中有四个补丁，那么各个补丁可以这样 -编号：1/4、2/4、3/4、4/4。这可以确保开发人员了解补丁应用的顺序，并且他们 +送出来以响应评审（即“v1，v2，v3”）则必须包含版本号，或包含“RFC”以指示 +评审请求。如果一个补丁系列中有四个补丁，那么各个补丁可以这样编号：1/4、2/4、 +3/4、4/4。这可以确保开发人员了解补丁应用的顺序，且 已经查看或应用了补丁系列中的所有补丁。 一些标题的例子:: @@ -543,95 +503,134 @@ e-mail 标题中的“一句话概述”扼要的描述 e-mail 中的补丁。 Subject: [patch 2/5] ext2: improve scalability of bitmap searching Subject: [PATCHv2 001/207] x86: fix eflags tracking -"From" 行是信体里的最上面一行，具有如下格式： +``From`` 行是信体里的最上面一行，具有如下格式:: + From: Patch Author <author@example.com> -"From" 行指明在永久改动日志里，谁会被确认为作者。如果没有 "From" 行，那 -么邮件头里的 "From: " 行会被用来决定改动日志中的作者。 +``From`` 行指明在永久改动日志里，谁会被确认为作者。如果没有 ``From`` 行，那 +么邮件头里的 ``From:`` 行会被用来决定改动日志中的作者。 -说明的主题将会被提交到永久的源代码改动日志里，因此对那些早已经不记得和 -这个补丁相关的讨论细节的有能力的读者来说，是有意义的。包括补丁程序定位 -错误的（内核日志消息、OOPS消息等）症状，对于搜索提交日志以寻找适用补丁的人 -尤其有用。如果一个补丁修复了一个编译失败，那么可能不需要包含所有编译失败； +说明文字将会被提交到永久的源代码改动日志里，因此应针对那些早已经不记得和这 +个补丁相关的讨论细节的读者。包括补丁处理的故障症状（内核日志消息、oops消息 +等），这对于可能正在搜索提交日志以查找适用补丁的人特别有用。文本应该写得如 +此详细，以便在数周、数月甚至数年后阅读时，能够为读者提供所需的细节信息，以 +掌握创建补丁的 **原因** 。 + +如果一个补丁修复了一个编译失败，那么可能不需要包含 *所有* 编译失败； 只要足够让搜索补丁的人能够找到它就行了。与概述一样，既要简洁又要描述性。 -"---" 标记行对于补丁处理工具要找到哪里是改动日志信息的结束，是不可缺少 +``---`` 标记行对于补丁处理工具要找到哪里是改动日志信息的结束，是不可缺少 的。 -对于 "---" 标记之后的额外注解，一个好的用途就是用来写 diffstat，用来显 -示修改了什么文件和每个文件都增加和删除了多少行。diffstat 对于比较大的补 -丁特别有用。其余那些只是和时刻或者开发者相关的注解，不合适放到永久的改 -动日志里的，也应该放这里。 -使用 diffstat的选项 "-p 1 -w 70" 这样文件名就会从内核源代码树的目录开始 +对于 ``---`` 标记之后的额外注解，一个好的用途就是用来写 ``diffstat`` ，用来显 +示修改了什么文件和每个文件都增加和删除了多少行。 ``diffstat`` 对于比较大的补 +丁特别有用。 +使用 ``diffstat`` 的选项 ``-p 1 -w 70`` 这样文件名就会从内核源代码树的目录开始 ，不会占用太宽的空间（很容易适合80列的宽度，也许会有一些缩进。） +（ ``git`` 默认会生成合适的diffstat。） + +其余那些只适用于当时或者与维护者相关的注解，不合适放到永久的改动日志里的，也 +应该放这里。较好的例子就是 ``补丁更改记录`` ，记录了v1和v2版本补丁之间的差异。 + +请将此信息放在将变更日志与补丁的其余部分分隔开的 ``---`` 行 **之后** 。版本 +信息不是提交到git树的变更日志的一部分。只是供审阅人员使用的附加信息。如果将 +其放置在提交标记上方，则需要手动交互才能将其删除。如果它位于分隔线以下，则在 +应用补丁时会自动剥离:: + + <commit message> + ... + Signed-off-by: Author <author@mail> + --- + V2 -> V3: Removed redundant helper function + V1 -> V2: Cleaned up coding style and addressed review comments -在后面的参考资料中能看到适当的补丁格式的更多细节。 + path/to/file | 5+++-- + ... -.. _cn_explicit_in_reply_to: +在后面的参考资料中能看到正确补丁格式的更多细节。 -15) 明确回复邮件头(In-Reply-To) -------------------------------- +.. _zh_backtraces: -手动添加回复补丁的的标题头(In-Reply_To:) 是有帮助的（例如，使用 ``git send-email`` ） -将补丁与以前的相关讨论关联起来，例如，将bug修复程序链接到电子邮件和bug报告。 +提交消息中的回溯（Backtraces） +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +回溯有助于记录导致问题的调用链。然而，并非所有回溯都有帮助。例如，早期引导调 +用链是独特而明显的。而逐字复制完整的dmesg输出则会增加时间戳、模块列表、寄存 +器和堆栈转储等分散注意力的信息。 + +因此，最有用的回溯应该从转储中提取相关信息，以更容易集中在真实问题上。下面是 +一个剪裁良好的回溯示例:: + + unchecked MSR access error: WRMSR to 0xd51 (tried to write 0x0000000000000064) + at rIP: 0xffffffffae059994 (native_write_msr+0x4/0x20) + Call Trace: + mba_wrmsr + update_domains + rdtgroup_mkdir + +.. _zh_explicit_in_reply_to: + +明确回复邮件头（In-Reply-To） +----------------------------- + +手动添加回复补丁的的邮件头（In-Reply_To:）是有用的（例如，使用 ``git send-email`` ）， +可以将补丁与以前的相关讨论关联起来，例如，将bug补丁链接到电子邮件和bug报告。 但是，对于多补丁系列，最好避免在回复时使用链接到该系列的旧版本。这样， -补丁的多个版本就不会成为电子邮件客户端中无法管理的引用序列。如果链接有用， +补丁的多个版本就不会成为电子邮件客户端中无法管理的引用树。如果链接有用， 可以使用 https://lore.kernel.org/ 重定向器（例如，在封面电子邮件文本中） 链接到补丁系列的早期版本。 -16) 发送git pull请求 --------------------- - -如果您有一系列补丁，那么让维护人员通过git pull操作将它们直接拉入子系统存储 -库可能是最方便的。但是，请注意，从开发人员那里获取补丁比从邮件列表中获取补 -丁需要更高的信任度。因此，许多子系统维护人员不愿意接受请求，特别是来自新的 -未知开发人员的请求。如果有疑问，您可以在封面邮件中使用pull 请求作为补丁系列 -正常发布的一个选项，让维护人员可以选择使用其中之一。 - -pull 请求的主题行中应该有[Git Pull]。请求本身应该在一行中包含存储库名称和 -感兴趣的分支；它应该看起来像:: +给出基础树信息 +-------------- - Please pull from +当其他开发人员收到您的补丁并开始审阅时，知道应该将您的工作放到代码树历史记录 +中的什么位置通常很有用。这对于自动化持续集成流水（CI）特别有用，这些流水线试 +图运行一系列测试，以便在维护人员开始审阅之前确定提交的质量。 - git://jdelvare.pck.nerim.net/jdelvare-2.6 i2c-for-linus +如果您使用 ``git format-patch`` 生成补丁，则可以通过 ``--base`` 标志在提交中 +自动包含基础树信息。使用此选项最简单、最方便的方法是配合主题分支:: - to get these changes: + $ git checkout -t -b my-topical-branch master + Branch 'my-topical-branch' set up to track local branch 'master'. + Switched to a new branch 'my-topical-branch' + [perform your edits and commits] -pull 请求还应该包含一条整体消息，说明请求中将包含什么，一个补丁本身的 ``Git shortlog`` -以及一个显示补丁系列整体效果的 ``diffstat`` 。当然，将所有这些信息收集在一起 -的最简单方法是让 ``git`` 使用 ``git request-pull`` 命令为您完成这些工作。 + $ git format-patch --base=auto --cover-letter -o outgoing/ master + outgoing/0000-cover-letter.patch + outgoing/0001-First-Commit.patch + outgoing/... -一些维护人员（包括Linus）希望看到来自已签名提交的请求；这增加了他们对你的 -请求信心。特别是，在没有签名标签的情况下，Linus 不会从像 Github 这样的公共 -托管站点拉请求。 +当你编辑 ``outgoing/0000-cover-letter.patch`` 时，您会注意到在它的最底部有一 +行 ``base-commit:`` 尾注，它为审阅者和CI工具提供了足够的信息以正确执行 +``git am`` 而不必担心冲突:: -创建此类签名的第一步是生成一个 GNRPG 密钥，并由一个或多个核心内核开发人员对 -其进行签名。这一步对新开发人员来说可能很困难，但没有办法绕过它。参加会议是 -找到可以签署您的密钥的开发人员的好方法。 + $ git checkout -b patch-review [base-commit-id] + Switched to a new branch 'patch-review' + $ git am patches.mbox + Applying: First Commit + Applying: ... -一旦您在Git 中准备了一个您希望有人拉的补丁系列，就用 ``git tag -s`` 创建一 -个签名标记。这将创建一个新标记，标识该系列中的最后一次提交，并包含用您的私 -钥创建的签名。您还可以将changelog样式的消息添加到标记中；这是一个描述拉请求 -整体效果的理想位置。 +有关此选项的更多信息，请参阅 ``man git-format-patch`` 。 -如果维护人员将要从中提取的树不是您正在使用的存储库，请不要忘记将已签名的标记 -显式推送到公共树。 +.. note:: -生成拉请求时，请使用已签名的标记作为目标。这样的命令可以实现:: + ``--base`` 功能是在2.9.0版git中引入的。 - git request-pull master git://my.public.tree/linux.git my-signed-tag +如果您不使用git格式化补丁，仍然可以包含相同的 ``base-commit`` 尾注，以指示您 +的工作所基于的树的提交哈希。你应该在封面邮件或系列的第一个补丁中添加它，它应 +该放在 ``---`` 行的下面或所有其他内容之后，即只在你的电子邮件签名之前。 参考文献 -------- -Andrew Morton, "The perfect patch" (tpp). +Andrew Morton，“完美的补丁”（tpp） <https://www.ozlabs.org/~akpm/stuff/tpp.txt> -Jeff Garzik, "Linux kernel patch submission format". +Jeff Garzik，“Linux内核补丁提交格式” <https://web.archive.org/web/20180829112450/http://linux.yyz.us/patch-format.html> -Greg Kroah-Hartman, "How to piss off a kernel subsystem maintainer". +Greg Kroah-Hartman，“如何惹恼内核子系统维护人员” <http://www.kroah.com/log/linux/maintainer.html> <http://www.kroah.com/log/linux/maintainer-02.html> @@ -644,16 +643,15 @@ Greg Kroah-Hartman, "How to piss off a kernel subsystem maintainer". <http://www.kroah.com/log/linux/maintainer-06.html> -NO!!!! No more huge patch bombs to linux-kernel@vger.kernel.org people! +不！！！别再发巨型补丁炸弹给linux-kernel@vger.kernel.org的人们了！ <https://lore.kernel.org/r/20050711.125305.08322243.davem@davemloft.net> -Kernel Documentation/process/coding-style.rst: - :ref:`Documentation/translations/zh_CN/process/coding-style.rst <cn_codingstyle>` +内核 Documentation/translations/zh_CN/process/coding-style.rst -Linus Torvalds's mail on the canonical patch format: +Linus Torvalds关于标准补丁格式的邮件 <https://lore.kernel.org/r/Pine.LNX.4.58.0504071023190.28951@ppc970.osdl.org> -Andi Kleen, "On submitting kernel patches" - Some strategies to get difficult or controversial changes in. +Andi Kleen，“提交补丁之路” + 一些帮助合入困难或有争议的变更的策略。 http://halobates.de/on-submitting-patches.pdf diff --git a/Documentation/translations/zh_CN/riscv/index.rst b/Documentation/translations/zh_CN/riscv/index.rst index bbf5d7b3777a..131e405aa857 100644 --- a/Documentation/translations/zh_CN/riscv/index.rst +++ b/Documentation/translations/zh_CN/riscv/index.rst @@ -18,7 +18,7 @@ RISC-V 体系结构 :maxdepth: 1 boot-image-header - pmu + vm-layout patch-acceptance diff --git a/Documentation/translations/zh_CN/riscv/pmu.rst b/Documentation/translations/zh_CN/riscv/pmu.rst deleted file mode 100644 index 7ec801026c4d..000000000000 --- a/Documentation/translations/zh_CN/riscv/pmu.rst +++ /dev/null @@ -1,235 +0,0 @@ -.. include:: ../disclaimer-zh_CN.rst - -:Original: Documentation/riscv/pmu.rst - -:翻译: - - 司延腾 Yanteng Si <siyanteng@loongson.cn> - -.. _cn_riscv_pmu: - -======================== -RISC-V平台上对PMUs的支持 -======================== - -Alan Kao <alankao@andestech.com>, Mar 2018 - -简介 ------------- - -截止本文撰写时，在The RISC-V ISA Privileged Version 1.10中提到的 perf_event -相关特性如下: -（详情请查阅手册） - -* [m|s]counteren -* mcycle[h], cycle[h] -* minstret[h], instret[h] -* mhpeventx, mhpcounterx[h] - -仅有以上这些功能，移植perf需要做很多工作，究其原因是缺少以下通用架构的性能 -监测特性: - -* 启用/停用计数器 - 在我们这里，计数器一直在自由运行。 -* 计数器溢出引起的中断 - 规范中没有这种功能。 -* 中断指示器 - 不可能所有的计数器都有很多的中断端口，所以需要一个中断指示器让软件来判断 - 哪个计数器刚好溢出。 -* 写入计数器 - 由于内核不能修改计数器，所以会有一个SBI来支持这个功能[1]。 另外，一些厂商 - 考虑实现M-S-U型号机器的硬件扩展来直接写入计数器。 - -这篇文档旨在为开发者提供一个在内核中支持PMU的简要指南。下面的章节简要解释了 -perf' 机制和待办事项。 - -你可以在这里查看以前的讨论[1][2]。 另外，查看附录中的相关内核结构体可能会有 -帮助。 - - -1. 初始化 ---------- - -*riscv_pmu* 是一个类型为 *struct riscv_pmu* 的全局指针，它包含了根据perf内部 -约定的各种方法和PMU-specific参数。人们应该声明这样的实例来代表PMU。 默认情况 -下， *riscv_pmu* 指向一个常量结构体 *riscv_base_pmu* ，它对基准QEMU模型有非常 -基础的支持。 - - -然后他/她可以将实例的指针分配给 *riscv_pmu* ，这样就可以利用已经实现的最小逻 -辑，或者创建他/她自己的 *riscv_init_platform_pmu* 实现。 - -换句话说，现有的 *riscv_base_pmu* 源只是提供了一个参考实现。 开发者可以灵活地 -决定多少部分可用，在最极端的情况下，他们可以根据自己的需要定制每一个函数。 - - -2. Event Initialization ------------------------ - -当用户启动perf命令来监控一些事件时，首先会被用户空间的perf工具解释为多个 -*perf_event_open* 系统调用，然后进一步调用上一步分配的 *event_init* 成员函数 -的主体。 在 *riscv_base_pmu* 的情况下，就是 *riscv_event_init* 。 - -该功能的主要目的是将用户提供的事件翻译成映射图，从而可以直接对HW-related的控 -制寄存器或计数器进行操作。该翻译基于 *riscv_pmu* 中提供的映射和方法。 - -注意，有些功能也可以在这个阶段完成: - -(1) 中断设置，这个在下一节说； -(2) 特限级设置(仅用户空间、仅内核空间、两者都有)； -(3) 析构函数设置。 通常应用 *riscv_destroy_event* 即可； -(4) 对非采样事件的调整，这将被函数应用，如 *perf_adjust_period* ，通常如下:: - - if (!is_sampling_event(event)) { - hwc->sample_period = x86_pmu.max_period; - hwc->last_period = hwc->sample_period; - local64_set(&hwc->period_left, hwc->sample_period); - } - - -在 *riscv_base_pmu* 的情况下，目前只提供了（3）。 - - -3. 中断 -------- - -3.1. 中断初始化 - -这种情况经常出现在 *event_init* 方案的开头。通常情况下，这应该是一个代码段，如:: - - int x86_reserve_hardware(void) - { - int err = 0; - - if (!atomic_inc_not_zero(&pmc_refcount)) { - mutex_lock(&pmc_reserve_mutex); - if (atomic_read(&pmc_refcount) == 0) { - if (!reserve_pmc_hardware()) - err = -EBUSY; - else - reserve_ds_buffers(); - } - if (!err) - atomic_inc(&pmc_refcount); - mutex_unlock(&pmc_reserve_mutex); - } - - return err; - } - -而神奇的是 *reserve_pmc_hardware* ，它通常做原子操作，使实现的IRQ可以从某个全局函 -数指针访问。 而 *release_pmc_hardware* 的作用正好相反，它用在上一节提到的事件分配 -器中。 - - (注：从所有架构的实现来看，*reserve/release* 对总是IRQ设置，所以 *pmc_hardware* - 似乎有些误导。 它并不处理事件和物理计数器之间的绑定，这一点将在下一节介绍。) - -3.2. IRQ结构体 - -基本上，一个IRQ运行以下伪代码:: - - for each hardware counter that triggered this overflow - - get the event of this counter - - // following two steps are defined as *read()*, - // check the section Reading/Writing Counters for details. - count the delta value since previous interrupt - update the event->count (# event occurs) by adding delta, and - event->hw.period_left by subtracting delta - - if the event overflows - sample data - set the counter appropriately for the next overflow - - if the event overflows again - too frequently, throttle this event - fi - fi - - end for - - 然而截至目前，没有一个RISC-V的实现为perf设计了中断，所以具体的实现要在未来完成。 - -4. Reading/Writing 计数 ------------------------ - -它们看似差不多，但perf对待它们的态度却截然不同。 对于读，在 *struct pmu* 中有一个 -*read* 接口，但它的作用不仅仅是读。 根据上下文，*read* 函数不仅要读取计数器的内容 -（event->count），还要更新左周期到下一个中断（event->hw.period_left）。 - - 但 perf 的核心不需要直接写计数器。 写计数器隐藏在以下两点的抽象化之后， - 1） *pmu->start* ，从字面上看就是开始计数，所以必须把计数器设置成一个合适的值，以 - 便下一次中断； - 2）在IRQ里面，应该把计数器设置成同样的合理值。 - -在RISC-V中，读操作不是问题，但写操作就需要费些力气了，因为S模式不允许写计数器。 - - -5. add()/del()/start()/stop() ------------------------------ - -基本思想: add()/del() 向PMU添加/删除事件，start()/stop() 启动/停止PMU中某个事件 -的计数器。 所有这些函数都使用相同的参数: *struct perf_event *event* 和 *int flag* 。 - -把 perf 看作一个状态机，那么你会发现这些函数作为这些状态之间的状态转换过程。 -定义了三种状态（event->hw.state）: - -* PERF_HES_STOPPED: 计数停止 -* PERF_HES_UPTODATE: event->count是最新的 -* PERF_HES_ARCH: 依赖于体系结构的用法，。。。我们现在并不需要它。 - -这些状态转换的正常流程如下: - -* 用户启动一个 perf 事件，导致调用 *event_init* 。 -* 当被上下文切换进来的时候，*add* 会被 perf core 调用，并带有一个标志 PERF_EF_START， - 也就是说事件被添加后应该被启动。 在这个阶段，如果有的话，一般事件会被绑定到一个物 - 理计数器上。当状态变为PERF_HES_STOPPED和PERF_HES_UPTODATE，因为现在已经停止了, - （软件）事件计数不需要更新。 - - - 然后调用 *start* ，并启用计数器。 - 通过PERF_EF_RELOAD标志，它向计数器写入一个适当的值（详细情况请参考上一节）。 - 如果标志不包含PERF_EF_RELOAD，则不会写入任何内容。 - 现在状态被重置为none，因为它既没有停止也没有更新（计数已经开始）。 - -*当被上下文切换出来时被调用。 然后，它检查出PMU中的所有事件，并调用 *stop* 来更新它们 - 的计数。 - - - *stop* 被 *del* 和perf核心调用，标志为PERF_EF_UPDATE，它经常以相同的逻辑和 *read* - 共用同一个子程序。 - 状态又一次变为PERF_HES_STOPPED和PERF_HES_UPTODATE。 - - - 这两对程序的生命周期: *add* 和 *del* 在任务切换时被反复调用；*start* 和 *stop* 在 - perf核心需要快速停止和启动时也会被调用，比如在调整中断周期时。 - -目前的实现已经足够了，将来可以很容易地扩展到功能。 - -A. 相关结构体 -------------- - -* struct pmu: include/linux/perf_event.h -* struct riscv_pmu: arch/riscv/include/asm/perf_event.h - - 两个结构体都被设计为只读。 - - *struct pmu* 定义了一些函数指针接口，它们大多以 *struct perf_event* 作为主参数，根据 - perf的内部状态机处理perf事件（详情请查看kernel/events/core.c）。 - - *struct riscv_pmu* 定义了PMU的具体参数。 命名遵循所有其它架构的惯例。 - -* struct perf_event: include/linux/perf_event.h -* struct hw_perf_event - - 表示 perf 事件的通用结构体，以及硬件相关的细节。 - -* struct riscv_hw_events: arch/riscv/include/asm/perf_event.h - - 保存事件状态的结构有两个固定成员。 - 事件的数量和事件的数组。 - -参考文献 --------- - -[1] https://github.com/riscv/riscv-linux/pull/124 - -[2] https://groups.google.com/a/groups.riscv.org/forum/#!topic/sw-dev/f19TmCNP6yA diff --git a/Documentation/translations/zh_CN/riscv/vm-layout.rst b/Documentation/translations/zh_CN/riscv/vm-layout.rst new file mode 100644 index 000000000000..91884e2dfff8 --- /dev/null +++ b/Documentation/translations/zh_CN/riscv/vm-layout.rst @@ -0,0 +1,104 @@ +.. SPDX-License-Identifier: GPL-2.0 +.. include:: ../disclaimer-zh_CN.rst + +:Original: Documentation/riscv/vm-layout.rst + +:翻译: + + 司延腾 Yanteng Si <siyanteng@loongson.cn> + Binbin Zhou <zhoubinbin@loongson.cn> + +============================ +RISC-V Linux上的虚拟内存布局 +============================ + +:作者: Alexandre Ghiti <alex@ghiti.fr> +:日期: 12 February 2021 + +这份文件描述了RISC-V Linux内核使用的虚拟内存布局。 + +32位 RISC-V Linux 内核 +====================== + +RISC-V Linux Kernel SV32 +------------------------ + +TODO + +64位 RISC-V Linux 内核 +====================== + +RISC-V特权架构文档指出，64位地址 "必须使第63-48位值都等于第47位，否则将发生缺页异常。"：这将虚 +拟地址空间分成两半，中间有一个非常大的洞，下半部分是用户空间所在的地方，上半部分是RISC-V Linux +内核所在的地方。 + +RISC-V Linux Kernel SV39 +------------------------ + +:: + + ======================================================================================================================== + 开始地址 | 偏移 | 结束地址 | 大小 | 虚拟内存区域描述 + ======================================================================================================================== + | | | | + 0000000000000000 | 0 | 0000003fffffffff | 256 GB | 用户空间虚拟内存，每个内存管理器不同 + __________________|____________|__________________|_________|___________________________________________________________ + | | | | + 0000004000000000 | +256 GB | ffffffbfffffffff | ~16M TB | ... 巨大的、几乎64位宽的直到内核映射的-256GB地方 + | | | | 开始偏移的非经典虚拟内存地址空洞。 + | | | | + __________________|____________|__________________|_________|___________________________________________________________ + | + | 内核空间的虚拟内存，在所有进程之间共享: + ____________________________________________________________|___________________________________________________________ + | | | | + ffffffc6fee00000 | -228 GB | ffffffc6feffffff | 2 MB | fixmap + ffffffc6ff000000 | -228 GB | ffffffc6ffffffff | 16 MB | PCI io + ffffffc700000000 | -228 GB | ffffffc7ffffffff | 4 GB | vmemmap + ffffffc800000000 | -224 GB | ffffffd7ffffffff | 64 GB | vmalloc/ioremap space + ffffffd800000000 | -160 GB | fffffff6ffffffff | 124 GB | 直接映射所有物理内存 + fffffff700000000 | -36 GB | fffffffeffffffff | 32 GB | kasan + __________________|____________|__________________|_________|____________________________________________________________ + | + | + ____________________________________________________________|____________________________________________________________ + | | | | + ffffffff00000000 | -4 GB | ffffffff7fffffff | 2 GB | modules, BPF + ffffffff80000000 | -2 GB | ffffffffffffffff | 2 GB | kernel + __________________|____________|__________________|_________|____________________________________________________________ + + +RISC-V Linux Kernel SV48 +------------------------ + +:: + + ======================================================================================================================== + 开始地址 | 偏移 | 结束地址 | 大小 | 虚拟内存区域描述 + ======================================================================================================================== + | | | | + 0000000000000000 | 0 | 00007fffffffffff | 128 TB | 用户空间虚拟内存，每个内存管理器不同 + __________________|____________|__________________|_________|___________________________________________________________ + | | | | + 0000800000000000 | +128 TB | ffff7fffffffffff | ~16M TB | ... 巨大的、几乎64位宽的直到内核映射的-128TB地方 + | | | | 开始偏移的非经典虚拟内存地址空洞。 + | | | | + __________________|____________|__________________|_________|___________________________________________________________ + | + | 内核空间的虚拟内存，在所有进程之间共享: + ____________________________________________________________|___________________________________________________________ + | | | | + ffff8d7ffee00000 | -114.5 TB | ffff8d7ffeffffff | 2 MB | fixmap + ffff8d7fff000000 | -114.5 TB | ffff8d7fffffffff | 16 MB | PCI io + ffff8d8000000000 | -114.5 TB | ffff8f7fffffffff | 2 TB | vmemmap + ffff8f8000000000 | -112.5 TB | ffffaf7fffffffff | 32 TB | vmalloc/ioremap space + ffffaf8000000000 | -80.5 TB | ffffef7fffffffff | 64 TB | 直接映射所有物理内存 + ffffef8000000000 | -16.5 TB | fffffffeffffffff | 16.5 TB | kasan + __________________|____________|__________________|_________|____________________________________________________________ + | + | 从此处开始，与39-bit布局相同： + ____________________________________________________________|____________________________________________________________ + | | | | + ffffffff00000000 | -4 GB | ffffffff7fffffff | 2 GB | modules, BPF + ffffffff80000000 | -2 GB | ffffffffffffffff | 2 GB | kernel + __________________|____________|__________________|_________|____________________________________________________________ diff --git a/Documentation/translations/zh_CN/scheduler/index.rst b/Documentation/translations/zh_CN/scheduler/index.rst index f8f8f35d53c7..a8eaa7325f54 100644 --- a/Documentation/translations/zh_CN/scheduler/index.rst +++ b/Documentation/translations/zh_CN/scheduler/index.rst @@ -5,6 +5,7 @@ :翻译: 司延腾 Yanteng Si <siyanteng@loongson.cn> + 唐艺舟 Tang Yizhou <tangyeechou@gmail.com> :校译: @@ -23,16 +24,16 @@ Linux调度器 sched-design-CFS sched-domains sched-capacity - + sched-energy + schedutil + sched-nice-design + sched-stats + sched-debug TODOList: - sched-bwc sched-deadline - sched-energy - sched-nice-design sched-rt-group - sched-stats text_files diff --git a/Documentation/translations/zh_CN/scheduler/sched-debug.rst b/Documentation/translations/zh_CN/scheduler/sched-debug.rst new file mode 100644 index 000000000000..5e17740c2bf3 --- /dev/null +++ b/Documentation/translations/zh_CN/scheduler/sched-debug.rst @@ -0,0 +1,51 @@ +.. SPDX-License-Identifier: GPL-2.0 +.. include:: ../disclaimer-zh_CN.rst + +:Original: Documentation/scheduler/sched-debug.rst + +:翻译: + + 唐艺舟 Tang Yizhou <tangyeechou@gmail.com> + +============= +调度器debugfs +============= + +用配置项CONFIG_SCHED_DEBUG=y启动内核后，将可以访问/sys/kernel/debug/sched +下的调度器专用调试文件。其中一些文件描述如下。 + +numa_balancing +============== + +`numa_balancing` 目录用来存放控制非统一内存访问（NUMA）平衡特性的相关文件。 +如果该特性导致系统负载太高，那么可以通过 `scan_period_min_ms, scan_delay_ms, +scan_period_max_ms, scan_size_mb` 文件控制NUMA缺页的内核采样速率。 + + +scan_period_min_ms, scan_delay_ms, scan_period_max_ms, scan_size_mb +------------------------------------------------------------------- + +自动NUMA平衡会扫描任务地址空间，检测页面是否被正确放置，或者数据是否应该被 +迁移到任务正在运行的本地内存结点，此时需解映射页面。每个“扫描延迟”（scan delay） +时间之后，任务扫描其地址空间中下一批“扫描大小”（scan size）个页面。若抵达 +内存地址空间末尾，扫描器将从头开始重新扫描。 + +结合来看，“扫描延迟”和“扫描大小”决定扫描速率。当“扫描延迟”减小时，扫描速率 +增加。“扫描延迟”和每个任务的扫描速率都是自适应的，且依赖历史行为。如果页面被 +正确放置，那么扫描延迟就会增加；否则扫描延迟就会减少。“扫描大小”不是自适应的， +“扫描大小”越大，扫描速率越高。 + +更高的扫描速率会产生更高的系统开销，因为必须捕获缺页异常，并且潜在地必须迁移 +数据。然而，当扫描速率越高，若工作负载模式发生变化，任务的内存将越快地迁移到 +本地结点，由于远程内存访问而产生的性能影响将降到最低。下面这些文件控制扫描延迟 +的阈值和被扫描的页面数量。 + +``scan_period_min_ms`` 是扫描一个任务虚拟内存的最小时间，单位是毫秒。它有效地 +控制了每个任务的最大扫描速率。 + +``scan_delay_ms`` 是一个任务初始化创建（fork）时，第一次使用的“扫描延迟”。 + +``scan_period_max_ms`` 是扫描一个任务虚拟内存的最大时间，单位是毫秒。它有效地 +控制了每个任务的最小扫描速率。 + +``scan_size_mb`` 是一次特定的扫描中，要扫描多少兆字节（MB）对应的页面数。 diff --git a/Documentation/translations/zh_CN/scheduler/sched-design-CFS.rst b/Documentation/translations/zh_CN/scheduler/sched-design-CFS.rst index 26b0f36f793d..3076402406c4 100644 --- a/Documentation/translations/zh_CN/scheduler/sched-design-CFS.rst +++ b/Documentation/translations/zh_CN/scheduler/sched-design-CFS.rst @@ -80,7 +80,7 @@ p->se.vruntime。一旦p->se.vruntime变得足够大，其它的任务将成为 CFS使用纳秒粒度的计时，不依赖于任何jiffies或HZ的细节。因此CFS并不像之前的调度器那样 有“时间片”的概念，也没有任何启发式的设计。唯一可调的参数（你需要打开CONFIG_SCHED_DEBUG）是： - /proc/sys/kernel/sched_min_granularity_ns + /sys/kernel/debug/sched/min_granularity_ns 它可以用来将调度器从“桌面”模式（也就是低时延）调节为“服务器”（也就是高批处理）模式。 它的默认设置是适合桌面的工作负载。SCHED_BATCH也被CFS调度器模块处理。 diff --git a/Documentation/translations/zh_CN/scheduler/sched-energy.rst b/Documentation/translations/zh_CN/scheduler/sched-energy.rst new file mode 100644 index 000000000000..fdbf6cfeea93 --- /dev/null +++ b/Documentation/translations/zh_CN/scheduler/sched-energy.rst @@ -0,0 +1,351 @@ +.. SPDX-License-Identifier: GPL-2.0 +.. include:: ../disclaimer-zh_CN.rst + +:Original: Documentation/scheduler/sched-energy.rst + +:翻译: + + 唐艺舟 Tang Yizhou <tangyeechou@gmail.com> + +============ +能量感知调度 +============ + +1. 简介 +------- + +能量感知调度（EAS）使调度器有能力预测其决策对CPU所消耗的能量的影响。EAS依靠 +一个能量模型（EM）来为每个任务选择一个节能的CPU，同时最小化对吞吐率的影响。 +本文档致力于介绍介绍EAS是如何工作的，它背后的主要设计决策是什么，以及使其运行 +所需的条件细节。 + +在进一步阅读之前，请注意，在撰写本文时:: + + /!\ EAS不支持对称CPU拓扑的平台 /!\ + +EAS只在异构CPU拓扑结构（如Arm大小核，big.LITTLE）上运行。因为在这种情况下， +通过调度来节约能量的潜力是最大的。 + +EAS实际使用的EM不是由调度器维护的，而是一个专门的框架。关于这个框架的细节和 +它提供的内容，请参考其文档（见Documentation/power/energy-model.rst）。 + + +2. 背景和术语 +------------- + +从一开始就说清楚定义: + - 能量 = [焦耳] （比如供电设备上的电池提供的资源） + - 功率 = 能量/时间 = [焦耳/秒] = [瓦特] + + EAS的目标是最小化能量消耗，同时仍能将工作完成。也就是说，我们要最大化:: + + 性能 [指令数/秒] + ---------------- + 功率 [瓦特] + +它等效于最小化:: + + 能量 [焦耳] + ----------- + 指令数 + +同时仍然获得“良好”的性能。当前调度器只考虑性能目标，因此该式子本质上是一个 +可选的优化目标，它同时考虑了两个目标：能量效率和性能。 + +引入EM的想法是为了让调度器评估其决策的影响，而不是盲目地应用可能仅在部分 +平台有正面效果的节能技术。同时，EM必须尽可能的简单，以最小化调度器的时延 +影响。 + +简而言之，EAS改变了CFS任务分配给CPU的方式。当调度器决定一个任务应该在哪里 +运行时（在唤醒期间），EM被用来在不损害系统吞吐率的情况下，从几个较好的候选 +CPU中挑选一个经预测能量消耗最优的CPU。EAS的预测依赖于对平台拓扑结构特定元素 +的了解，包括CPU的“算力”，以及它们各自的能量成本。 + + +3. 拓扑信息 +----------- + +EAS（以及调度器的剩余部分）使用“算力”的概念来区分不同计算吞吐率的CPU。一个 +CPU的“算力”代表了它在最高频率下运行时能完成的工作量，且这个值是相对系统中 +算力最大的CPU而言的。算力值被归一化为1024以内，并且可与由实体负载跟踪 +（PELT）机制算出的利用率信号做对比。由于有算力值和利用率值，EAS能够估计一个 +任务/CPU有多大/有多忙，并在评估性能与能量时将其考虑在内。CPU算力由特定体系 +结构实现的arch_scale_cpu_capacity()回调函数提供。 + +EAS使用的其余平台信息是直接从能量模型（EM）框架中读取的。一个平台的EM是一张 +表，表中每项代表系统中一个“性能域”的功率成本。（若要了解更多关于性能域的细节， +见Documentation/power/energy-model.rst） + +当调度域被建立或重新建立时，调度器管理对拓扑代码中EM对象的引用。对于每个根域 +（rd），调度器维护一个与当前rd->span相交的所有性能域的单向链表。链表中的每个 +节点都包含一个指向EM框架所提供的结构体em_perf_domain的指针。 + +链表被附加在根域上，以应对独占的cpuset的配置。由于独占的cpuset的边界不一定与 +性能域的边界一致，不同根域的链表可能包含重复的元素。 + +示例1 + 让我们考虑一个有12个CPU的平台，分成3个性能域，（pd0，pd4和pd8），按以下 + 方式组织:: + + CPUs: 0 1 2 3 4 5 6 7 8 9 10 11 + PDs: |--pd0--|--pd4--|---pd8---| + RDs: |----rd1----|-----rd2-----| + + 现在，考虑用户空间决定将系统分成两个独占的cpusets，因此创建了两个独立的根域， + 每个根域包含6个CPU。这两个根域在上图中被表示为rd1和rd2。由于pd4与rd1和rd2 + 都有交集，它将同时出现于附加在这两个根域的“->pd”链表中: + + * rd1->pd: pd0 -> pd4 + * rd2->pd: pd4 -> pd8 + + 请注意，调度器将为pd4创建两个重复的链表节点（每个链表中各一个）。然而这 + 两个节点持有指向同一个EM框架的共享数据结构的指针。 + +由于对这些链表的访问可能与热插拔及其它事件并发发生，因此它们受RCU锁保护，就像 +被调度器操控的拓扑结构体中剩下字段一样。 + +EAS同样维护了一个静态键（sched_energy_present），当至少有一个根域满足EAS +启动的所有条件时，这个键就会被启动。在第6节中总结了这些条件。 + + +4. 能量感知任务放置 +------------------- + +EAS覆盖了CFS的任务唤醒平衡代码。在唤醒平衡时，它使用平台的EM和PELT信号来选择节能 +的目标CPU。当EAS被启用时，select_task_rq_fair()调用find_energy_efficient_cpu() +来做任务放置决定。这个函数寻找在每个性能域中寻找具有最高剩余算力（CPU算力 - CPU +利用率）的CPU，因为它能让我们保持最低的频率。然后，该函数检查将任务放在新CPU相较 +依然放在之前活动的prev_cpu是否可以节省能量。 + +如果唤醒的任务被迁移，find_energy_efficient_cpu()使用compute_energy()来估算 +系统将消耗多少能量。compute_energy()检查各CPU当前的利用率情况，并尝试调整来 +“模拟”任务迁移。EM框架提供了API em_pd_energy()计算每个性能域在给定的利用率条件 +下的预期能量消耗。 + +下面详细介绍一个优化能量消耗的任务放置决策的例子。 + +示例2 + 让我们考虑一个有两个独立性能域的（伪）平台，每个性能域含有2个CPU。CPU0和CPU1 + 是小核，CPU2和CPU3是大核。 + + 调度器必须决定将任务P放在哪个CPU上，这个任务的util_avg = 200（平均利用率）， + prev_cpu = 0（上一次运行在CPU0）。 + + 目前CPU的利用率情况如下图所示。CPU 0-3的util_avg分别为400、100、600和500。 + 每个性能域有三个操作性能值（OPP）。与每个OPP相关的CPU算力和功率成本列在能量 + 模型表中。P的util_avg在图中显示为"PP":: + + CPU util. + 1024 - - - - - - - Energy Model + +-----------+-------------+ + | Little | Big | + 768 ============= +-----+-----+------+------+ + | Cap | Pwr | Cap | Pwr | + +-----+-----+------+------+ + 512 =========== - ##- - - - - | 170 | 50 | 512 | 400 | + ## ## | 341 | 150 | 768 | 800 | + 341 -PP - - - - ## ## | 512 | 300 | 1024 | 1700 | + PP ## ## +-----+-----+------+------+ + 170 -## - - - - ## ## + ## ## ## ## + ------------ ------------- + CPU0 CPU1 CPU2 CPU3 + + Current OPP: ===== Other OPP: - - - util_avg (100 each): ## + + + find_energy_efficient_cpu()将首先在两个性能域中寻找具有最大剩余算力的CPU。 + 在这个例子中是CPU1和CPU3。然后，它将估算，当P被放在它们中的任意一个时，系统的 + 能耗，并检查这样做是否会比把P放在CPU0上节省一些能量。EAS假定OPPs遵循利用率 + （这与CPUFreq监管器schedutil的行为一致。关于这个问题的更多细节，见第6节）。 + + **情况1. P被迁移到CPU1**:: + + 1024 - - - - - - - + + Energy calculation: + 768 ============= * CPU0: 200 / 341 * 150 = 88 + * CPU1: 300 / 341 * 150 = 131 + * CPU2: 600 / 768 * 800 = 625 + 512 - - - - - - - ##- - - - - * CPU3: 500 / 768 * 800 = 520 + ## ## => total_energy = 1364 + 341 =========== ## ## + PP ## ## + 170 -## - - PP- ## ## + ## ## ## ## + ------------ ------------- + CPU0 CPU1 CPU2 CPU3 + + + **情况2. P被迁移到CPU3**:: + + 1024 - - - - - - - + + Energy calculation: + 768 ============= * CPU0: 200 / 341 * 150 = 88 + * CPU1: 100 / 341 * 150 = 43 + PP * CPU2: 600 / 768 * 800 = 625 + 512 - - - - - - - ##- - -PP - * CPU3: 700 / 768 * 800 = 729 + ## ## => total_energy = 1485 + 341 =========== ## ## + ## ## + 170 -## - - - - ## ## + ## ## ## ## + ------------ ------------- + CPU0 CPU1 CPU2 CPU3 + + **情况3. P依旧留在prev_cpu/CPU0**:: + + 1024 - - - - - - - + + Energy calculation: + 768 ============= * CPU0: 400 / 512 * 300 = 234 + * CPU1: 100 / 512 * 300 = 58 + * CPU2: 600 / 768 * 800 = 625 + 512 =========== - ##- - - - - * CPU3: 500 / 768 * 800 = 520 + ## ## => total_energy = 1437 + 341 -PP - - - - ## ## + PP ## ## + 170 -## - - - - ## ## + ## ## ## ## + ------------ ------------- + CPU0 CPU1 CPU2 CPU3 + + 从这些计算结果来看，情况1的总能量最低。所以从节约能量的角度看，CPU1是最佳候选 + 者。 + +大核通常比小核更耗电，因此主要在任务不适合在小核运行时使用。然而，小核并不总是比 +大核节能。举例来说，对于某些系统，小核的高OPP可能比大核的低OPP能量消耗更高。因此， +如果小核在某一特定时间点刚好有足够的利用率，在此刻被唤醒的小任务放在大核执行可能 +会更节能，尽管它在小核上运行也是合适的。 + +即使在大核所有OPP都不如小核OPP节能的情况下，在某些特定条件下，令小任务运行在大核 +上依然可能节能。事实上，将一个任务放在一个小核上可能导致整个性能域的OPP提高，这将 +增加已经在该性能域运行的任务的能量成本。如果唤醒的任务被放在一个大核上，它的执行 +成本可能比放在小核上更高，但这不会影响小核上的其它任务，这些任务将继续以较低的OPP +运行。因此，当考虑CPU消耗的总能量时，在大核上运行一个任务的额外成本可能小于为所有 +其它运行在小核的任务提高OPP的成本。 + +上面的例子几乎不可能以一种通用的方式得到正确的结果；同时，对于所有平台，在不知道 +系统所有CPU每个不同OPP的运行成本时，也无法得到正确的结果。得益于基于EM的设计， +EAS应该能够正确处理这些问题而不会引发太多麻烦。然而，为了确保对高利用率场景的 +吞吐率造成的影响最小化，EAS同样实现了另外一种叫“过度利用率”的机制。 + + +5. 过度利用率 +------------- + +从一般的角度来看，EAS能提供最大帮助的是那些涉及低、中CPU利用率的使用场景。每当CPU +密集型的长任务运行，它们将需要所有的可用CPU算力，调度器将没有什么办法来节省能量同时 +又不损害吞吐率。为了避免EAS损害性能，一旦CPU被使用的算力超过80%，它将被标记为“过度 +利用”。只要根域中没有CPU是过度利用状态，负载均衡被禁用，而EAS将覆盖唤醒平衡代码。 +EAS很可能将负载放置在系统中能量效率最高的CPU而不是其它CPU上，只要不损害吞吐率。 +因此，负载均衡器被禁用以防止它打破EAS发现的节能任务放置。当系统未处于过度利用状态时， +这样做是安全的，因为低于80%的临界点意味着： + + a. 所有的CPU都有一些空闲时间，所以EAS使用的利用率信号很可能准确地代表各种任务 + 的“大小”。 + b. 所有任务，不管它们的nice值是多大，都应该被提供了足够多的CPU算力。 + c. 既然有多余的算力，那么所有的任务都必须定期阻塞/休眠，在唤醒时进行平衡就足够 + 了。 + +只要一个CPU利用率超过80%的临界点，上述三个假设中至少有一个是不正确的。在这种情况下， +整个根域的“过度利用”标志被设置，EAS被禁用，负载均衡器被重新启用。通过这样做，调度器 +又回到了在CPU密集的条件下基于负载的算法做负载均衡。这更好地尊重了任务的nice值。 + +由于过度利用率的概念在很大程度上依赖于检测系统中是否有一些空闲时间，所以必须考虑 +（比CFS）更高优先级的调度类（以及中断）“窃取”的CPU算力。像这样，对过度使用率的检测 +不仅要考虑CFS任务使用的算力，还需要考虑其它调度类和中断。 + + +6. EAS的依赖和要求 +------------------ + +能量感知调度依赖系统的CPU具有特定的硬件属性，以及内核中的其它特性被启用。本节列出 +了这些依赖，并对如何满足这些依赖提供了提示。 + + +6.1 - 非对称CPU拓扑 +^^^^^^^^^^^^^^^^^^^ + + +如简介所提，目前只有非对称CPU拓扑结构的平台支持EAS。通过在运行时查询 +SD_ASYM_CPUCAPACITY_FULL标志位是否在创建调度域时已设置来检查这一要求是否满足。 + +参阅Documentation/scheduler/sched-capacity.rst以了解在sched_domain层次结构 +中设置此标志位所需满足的要求。 + +请注意，EAS并非从根本上与SMP不兼容，但在SMP平台上还没有观察到明显的节能。这一 +限制可以在将来进行修改，如果被证明不是这样的话。 + + +6.2 - 当前的能量模型 +^^^^^^^^^^^^^^^^^^^^ + +EAS使用一个平台的EM来估算调度决策对能量的影响。因此，你的平台必须向EM框架提供 +能量成本表，以启动EAS。要做到这一点，请参阅文档 +Documentation/power/energy-model.rst中的独立EM框架部分。 + +另请注意，调度域需要在EM注册后重建，以便启动EAS。 + +EAS使用EM对能量使用率进行预测决策，因此它在检查任务放置的可能选项时更加注重 +差异。对于EAS来说，EM的功率值是以毫瓦还是以“抽象刻度”为单位表示并不重要。 + + + +6.3 - 能量模型复杂度 +^^^^^^^^^^^^^^^^^^^^ + +任务唤醒路径是时延敏感的。当一个平台的EM太复杂（太多CPU，太多性能域，太多状态 +等），在唤醒路径中使用它的成本就会升高到不可接受。能量感知唤醒算法的复杂度为： + + C = Nd * (Nc + Ns) + +其中：Nd是性能域的数量；Nc是CPU的数量；Ns是OPP的总数（例如：对于两个性能域， +每个域有4个OPP，则Ns = 8）。 + +当调度域建立时，复杂性检查是在根域上进行的。如果一个根域的复杂度C恰好高于完全 +主观设定的EM_MAX_COMPLEXITY阈值（在本文写作时，是2048），则EAS不会在此根域 +启动。 + +如果你的平台的能量模型的复杂度太高，EAS无法在这个根域上使用，但你真的想用， +那么你就只剩下两个可能的选择： + + 1. 将你的系统拆分成分离的、较小的、使用独占cpuset的根域，并在每个根域局部 + 启用EAS。这个方案的好处是开箱即用，但缺点是无法在根域之间实现负载均衡， + 这可能会导致总体系统负载不均衡。 + 2. 提交补丁以降低EAS唤醒算法的复杂度，从而使其能够在合理的时间内处理更大 + 的EM。 + + +6.4 - Schedutil监管器 +^^^^^^^^^^^^^^^^^^^^^ + +EAS试图预测CPU在不久的将来会在哪个OPP下运行，以估算它们的能量消耗。为了做到 +这一点，它假定CPU的OPP跟随CPU利用率变化而变化。 + +尽管在实践中很难对这一假设的准确性提供硬性保证（因为，举例来说硬件可能不会做 +它被要求做的事情），相对于其他CPUFreq监管器，schedutil至少_请求_使用利用率 +信号计算的频率。因此，与EAS一起使用的唯一合理的监管器是schedutil，因为它是 +唯一一个在频率请求和能量预测之间提供某种程度的一致性的监管器。 + +不支持将EAS与schedutil之外的任何其它监管器一起使用。 + + +6.5 刻度不变性使用率信号 +^^^^^^^^^^^^^^^^^^^^^^^^ + +为了对不同的CPU和所有的性能状态做出准确的预测，EAS需要频率不变的和CPU不变的 +PELT信号。这些信号可以通过每个体系结构定义的arch_scale{cpu,freq}_capacity() +回调函数获取。 + +不支持在没有实现这两个回调函数的平台上使用EAS。 + + +6.6 多线程（SMT） +^^^^^^^^^^^^^^^^^ + +当前实现的EAS是不感知SMT的，因此无法利用多线程硬件节约能量。EAS认为线程是独立的 +CPU，这实际上对性能和能量消耗都是不利的。 + +不支持在SMT上使用EAS。 diff --git a/Documentation/translations/zh_CN/scheduler/sched-nice-design.rst b/Documentation/translations/zh_CN/scheduler/sched-nice-design.rst new file mode 100644 index 000000000000..9107f0c0b979 --- /dev/null +++ b/Documentation/translations/zh_CN/scheduler/sched-nice-design.rst @@ -0,0 +1,99 @@ +.. SPDX-License-Identifier: GPL-2.0 +.. include:: ../disclaimer-zh_CN.rst + +:Original: Documentation/scheduler/sched-nice-design.rst + +:翻译: + + 唐艺舟 Tang Yizhou <tangyeechou@gmail.com> + +===================== +调度器nice值设计 +===================== + +本文档解释了新的Linux调度器中修改和精简后的nice级别的实现思路。 + +Linux的nice级别总是非常脆弱，人们持续不断地缠着我们，让nice +19的任务占用 +更少的CPU时间。 + +不幸的是，在旧的调度器中，这不是那么容易实现的（否则我们早就做到了），因为对 +nice级别的支持在历史上是与时间片长度耦合的，而时间片单位是由HZ滴答驱动的， +所以最小的时间片是1/HZ。 + +在O(1)调度器中（2003年），我们改变了负的nice级别，使它们比2.4内核更强 +（人们对这一变化很满意），而且我们还故意校正了线性时间片准则，使得nice +19 +的级别 _正好_ 是1 jiffy。为了让大家更好地理解它，时间片的图会是这样的（质量 +不佳的ASCII艺术提醒！）:: + + + A + \ | [timeslice length] + \ | + \ | + \ | + \ | + \|___100msecs + |^ . _ + | ^ . _ + | ^ . _ + -*----------------------------------*-----> [nice level] + -20 | +19 + | + | + +因此，如果有人真的想renice任务，相较线性规则，+19会给出更大的效果（改变 +ABI来扩展优先级的解决方案在早期就被放弃了）。 + +这种方法在一定程度上奏效了一段时间，但后来HZ=1000时，它导致1 jiffy为 +1ms，这意味着0.1%的CPU使用率，我们认为这有点过度。过度 _不是_ 因为它表示 +的CPU使用率过小，而是因为它引发了过于频繁（每毫秒1次）的重新调度（因此会 +破坏缓存，等等。请记住，硬件更弱、cache更小是很久以前的事了，当时人们在 +nice +19级别运行数量颇多的应用程序）。 + +因此，对于HZ=1000，我们将nice +19改为5毫秒，因为这感觉像是正确的最小 +粒度——这相当于5%的CPU利用率。但nice +19的根本的HZ敏感属性依然保持不变， +我们没有收到过关于nice +19在CPU利用率方面太 _弱_ 的任何抱怨，我们只收到 +过它（依然）太 _强_ 的抱怨 :-)。 + +总结一下：我们一直想让nice各级别一致性更强，但在HZ和jiffies的限制下，以及 +nice级别与时间片、调度粒度耦合是令人讨厌的设计，这一目标并不真正可行。 + +第二个关于Linux nice级别支持的抱怨是（不那么频繁，但仍然定期发生），它 +在原点周围的不对称性（你可以在上面的图片中看到），或者更准确地说：事实上 +nice级别的行为取决于 _绝对的_ nice级别，而nice应用程序接口本身从根本上 +说是“相对”的： + + int nice(int inc); + + asmlinkage long sys_nice(int increment) + +（第一个是glibc的应用程序接口，第二个是syscall的应用程序接口） +注意，“inc”是相对当前nice级别而言的，类似bash的“nice”命令等工具是这个 +相对性应用程序接口的镜像。 + +在旧的调度器中，举例来说，如果你以nice +1启动一个任务，并以nice +2启动 +另一个任务，这两个任务的CPU分配将取决于父外壳程序的nice级别——如果它是 +nice -10，那么CPU的分配不同于+5或+10。 + +第三个关于Linux nice级别支持的抱怨是，负数nice级别“不够有力”，以很多人 +不得不诉诸于实时调度优先级来运行音频（和其它多媒体）应用程序，比如 +SCHED_FIFO。但这也造成了其它问题：SCHED_FIFO未被证明是免于饥饿的，一个 +有问题的SCHED_FIFO应用程序也会锁住运行良好的系统。 + +v2.6.23版内核的新调度器解决了这三种类型的抱怨： + +为了解决第一个抱怨（nice级别不够“有力”），调度器与“时间片”、HZ的概念 +解耦（调度粒度被处理成一个和nice级别独立的概念），因此有可能实现更好、 +更一致的nice +19支持：在新的调度器中，nice +19的任务得到一个HZ无关的 +1.5%CPU使用率，而不是旧版调度器中3%-5%-9%的可变范围。 + +为了解决第二个抱怨（nice各级别不一致），新调度器令调用nice(1)对各任务的 +CPU利用率有相同的影响，无论其绝对nice级别如何。所以在新调度器上，运行一个 +nice +10和一个nice +11的任务会与运行一个nice -5和一个nice -4的任务的 +CPU利用率分割是相同的（一个会得到55%的CPU，另一个会得到45%）。这是为什么 +nice级别被改为“乘法”（或指数）——这样的话，不管你从哪个级别开始，“相对” +结果将总是一样的。 + +第三个抱怨（负数nice级别不够“有力”，并迫使音频应用程序在更危险的 +SCHED_FIFO调度策略下运行）几乎被新的调度器自动解决了：更强的负数级别 +具有重新校正nice级别动态范围的自动化副作用。 diff --git a/Documentation/translations/zh_CN/scheduler/sched-stats.rst b/Documentation/translations/zh_CN/scheduler/sched-stats.rst new file mode 100644 index 000000000000..c5e0be663837 --- /dev/null +++ b/Documentation/translations/zh_CN/scheduler/sched-stats.rst @@ -0,0 +1,156 @@ +.. SPDX-License-Identifier: GPL-2.0 +.. include:: ../disclaimer-zh_CN.rst + +:Original: Documentation/scheduler/sched-stats.rst + +:翻译: + + 唐艺舟 Tang Yizhou <tangyeechou@gmail.com> + +============== +调度器统计数据 +============== + +第15版schedstats去掉了sched_yield的一些计数器：yld_exp_empty，yld_act_empty +和yld_both_empty。在其它方面和第14版完全相同。 + +第14版schedstats包括对sched_domains（译注：调度域）的支持，该特性进入内核 +主线2.6.20，不过这一版schedstats与2.6.13-2.6.19内核的版本12的统计数据是完全 +相同的（内核未发布第13版）。有些计数器按每个运行队列统计是更有意义的，其它则 +按每个调度域统计是更有意义的。注意，调度域（以及它们的附属信息）仅在开启 +CONFIG_SMP的机器上是相关的和可用的。 + +在第14版schedstat中，每个被列出的CPU至少会有一级域统计数据，且很可能有一个 +以上的域。在这个实现中，域没有特别的名字，但是编号最高的域通常在机器上所有的 +CPU上仲裁平衡，而domain0是最紧密聚焦的域，有时仅在一对CPU之间进行平衡。此时， +没有任何体系结构需要3层以上的域。域统计数据中的第一个字段是一个位图，表明哪些 +CPU受该域的影响。 + +这些字段是计数器，而且只能递增。使用这些字段的程序将需要从基线观测开始，然后在 +后续每一个观测中计算出计数器的变化。一个能以这种方式处理其中很多字段的perl脚本 +可见 + + http://eaglet.pdxhosts.com/rick/linux/schedstat/ + +请注意，任何这样的脚本都必须是特定于版本的，改变版本的主要原因是输出格式的变化。 +对于那些希望编写自己的脚本的人，可以参考这里描述的各个字段。 + +CPU统计数据 +----------- +cpu<N> 1 2 3 4 5 6 7 8 9 + +第一个字段是sched_yield()的统计数据： + + 1) sched_yield()被调用了#次 + +接下来的三个是schedule()的统计数据： + + 2) 这个字段是一个过时的数组过期计数，在O(1)调度器中使用。为了ABI兼容性， + 我们保留了它，但它总是被设置为0。 + 3) schedule()被调用了#次 + 4) 调用schedule()导致处理器变为空闲了#次 + +接下来的两个是try_to_wake_up()的统计数据： + + 5) try_to_wake_up()被调用了#次 + 6) 调用try_to_wake_up()导致本地CPU被唤醒了#次 + +接下来的三个统计数据描述了调度延迟： + + 7) 本处理器运行任务的总时间，单位是纳秒 + 8) 本处理器任务等待运行的时间，单位是纳秒 + 9) 本CPU运行了#个时间片 + +域统计数据 +---------- + +对于每个被描述的CPU，和它相关的每一个调度域均会产生下面一行数据（注意，如果 +CONFIG_SMP没有被定义，那么*没有*调度域被使用，这些行不会出现在输出中）。 + +domain<N> <cpumask> 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 + +第一个字段是一个位掩码，表明该域在操作哪些CPU。 + +接下来的24个字段是load_balance()函数的各个统计数据，按空闲类型分组（空闲， +繁忙，新空闲）： + + + 1) 当CPU空闲时，load_balance()在这个调度域中被调用了#次 + 2) 当CPU空闲时，load_balance()在这个调度域中被调用，但是发现负载无需 + 均衡#次 + 3) 当CPU空闲时，load_balance()在这个调度域中被调用，试图迁移1个或更多 + 任务且失败了#次 + 4) 当CPU空闲时，load_balance()在这个调度域中被调用，发现不均衡（如果有） + #次 + 5) 当CPU空闲时，pull_task()在这个调度域中被调用#次 + 6) 当CPU空闲时，尽管目标任务是热缓存状态，pull_task()依然被调用#次 + 7) 当CPU空闲时，load_balance()在这个调度域中被调用，未能找到更繁忙的 + 队列#次 + 8) 当CPU空闲时，在调度域中找到了更繁忙的队列，但未找到更繁忙的调度组 + #次 + 9) 当CPU繁忙时，load_balance()在这个调度域中被调用了#次 + 10) 当CPU繁忙时，load_balance()在这个调度域中被调用，但是发现负载无需 + 均衡#次 + 11) 当CPU繁忙时，load_balance()在这个调度域中被调用，试图迁移1个或更多 + 任务且失败了#次 + 12) 当CPU繁忙时，load_balance()在这个调度域中被调用，发现不均衡（如果有） + #次 + 13) 当CPU繁忙时，pull_task()在这个调度域中被调用#次 + 14) 当CPU繁忙时，尽管目标任务是热缓存状态，pull_task()依然被调用#次 + 15) 当CPU繁忙时，load_balance()在这个调度域中被调用，未能找到更繁忙的 + 队列#次 + 16) 当CPU繁忙时，在调度域中找到了更繁忙的队列，但未找到更繁忙的调度组 + #次 + 17) 当CPU新空闲时，load_balance()在这个调度域中被调用了#次 + 18) 当CPU新空闲时，load_balance()在这个调度域中被调用，但是发现负载无需 + 均衡#次 + 19) 当CPU新空闲时，load_balance()在这个调度域中被调用，试图迁移1个或更多 + 任务且失败了#次 + 20) 当CPU新空闲时，load_balance()在这个调度域中被调用，发现不均衡（如果有） + #次 + 21) 当CPU新空闲时，pull_task()在这个调度域中被调用#次 + 22) 当CPU新空闲时，尽管目标任务是热缓存状态，pull_task()依然被调用#次 + 23) 当CPU新空闲时，load_balance()在这个调度域中被调用，未能找到更繁忙的 + 队列#次 + 24) 当CPU新空闲时，在调度域中找到了更繁忙的队列，但未找到更繁忙的调度组 + #次 + +接下来的3个字段是active_load_balance()函数的各个统计数据： + + 25) active_load_balance()被调用了#次 + 26) active_load_balance()被调用，试图迁移1个或更多任务且失败了#次 + 27) active_load_balance()被调用，成功迁移了#次任务 + +接下来的3个字段是sched_balance_exec()函数的各个统计数据： + + 28) sbe_cnt不再被使用 + 29) sbe_balanced不再被使用 + 30) sbe_pushed不再被使用 + +接下来的3个字段是sched_balance_fork()函数的各个统计数据： + + 31) sbf_cnt不再被使用 + 32) sbf_balanced不再被使用 + 33) sbf_pushed不再被使用 + +接下来的3个字段是try_to_wake_up()函数的各个统计数据： + + 34) 在这个调度域中调用try_to_wake_up()唤醒任务时，任务在调度域中一个 + 和上次运行不同的新CPU上运行了#次 + 35) 在这个调度域中调用try_to_wake_up()唤醒任务时，任务被迁移到发生唤醒 + 的CPU次数为#，因为该任务在原CPU是冷缓存状态 + 36) 在这个调度域中调用try_to_wake_up()唤醒任务时，引发被动负载均衡#次 + +/proc/<pid>/schedstat +--------------------- +schedstats还添加了一个新的/proc/<pid>/schedstat文件，来提供一些进程级的 +相同信息。这个文件中，有三个字段与该进程相关： + + 1) 在CPU上运行花费的时间(单位是纳秒) + 2) 在运行队列上等待的时间(单位是纳秒) + 3) 在CPU上运行了#个时间片 + +可以很容易地编写一个程序，利用这些额外的字段来报告一个特定的进程或一组进程在 +调度器策略下的表现如何。这样的程序的一个简单版本可在下面的链接找到 + + http://eaglet.pdxhosts.com/rick/linux/schedstat/v12/latency.c diff --git a/Documentation/translations/zh_CN/scheduler/schedutil.rst b/Documentation/translations/zh_CN/scheduler/schedutil.rst new file mode 100644 index 000000000000..d1ea68007520 --- /dev/null +++ b/Documentation/translations/zh_CN/scheduler/schedutil.rst @@ -0,0 +1,165 @@ +.. SPDX-License-Identifier: GPL-2.0 +.. include:: ../disclaimer-zh_CN.rst + +:Original: Documentation/scheduler/schedutil.rst + +:翻译: + + 唐艺舟 Tang Yizhou <tangyeechou@gmail.com> + +========= +Schedutil +========= + +.. note:: + + 本文所有内容都假设频率和工作算力之间存在线性关系。我们知道这是有瑕疵的， + 但这是最可行的近似处理。 + +PELT（实体负载跟踪，Per Entity Load Tracking） +============================================== + +通过PELT，我们跟踪了各种调度器实体的一些指标，从单个任务到任务组分片到CPU +运行队列。我们使用指数加权移动平均数（Exponentially Weighted Moving Average， +EWMA）作为其基础，每个周期（1024us）都会衰减，衰减速率满足y^32 = 0.5。 +也就是说，最近的32ms贡献负载的一半，而历史上的其它时间则贡献另一半。 + +具体而言： + + ewma_sum(u) := u_0 + u_1*y + u_2*y^2 + ... + + ewma(u) = ewma_sum(u) / ewma_sum(1) + +由于这本质上是一个无限几何级数的累加，结果是可组合的，即ewma(A) + ewma(B) = ewma(A+B)。 +这个属性是关键，因为它提供了在任务迁移时重新组合平均数的能力。 + +请注意，阻塞态的任务仍然对累加值（任务组分片和CPU运行队列）有贡献，这反映了 +它们在恢复运行后的预期贡献。 + +利用这一点，我们跟踪2个关键指标：“运行”和“可运行”。“运行”反映了一个调度实体 +在CPU上花费的时间，而“可运行”反映了一个调度实体在运行队列中花费的时间。当只有 +一个任务时，这两个指标是相同的，但一旦出现对CPU的争用，“运行”将减少以反映每个 +任务在CPU上花费的时间，而“可运行”将增加以反映争用的激烈程度。 + +更多细节见：kernel/sched/pelt.c + + +频率 / CPU不变性 +================ + +因为CPU频率在1GHz时利用率为50%和CPU频率在2GHz时利用率为50%是不一样的，同样 +在小核上运行时利用率为50%和在大核上运行时利用率为50%是不一样的，我们允许架构 +以两个比率来伸缩时间差，其中一个是动态电压频率升降（Dynamic Voltage and +Frequency Scaling，DVFS）比率，另一个是微架构比率。 + +对于简单的DVFS架构（软件有完全控制能力），我们可以很容易地计算该比率为:: + + f_cur + r_dvfs := ----- + f_max + +对于由硬件控制DVFS的更多动态系统，我们使用硬件计数器（Intel APERF/MPERF， +ARMv8.4-AMU）来计算这一比率。具体到Intel，我们使用:: + + APERF + f_cur := ----- * P0 + MPERF + + 4C-turbo; 如果可用并且使能了turbo + f_max := { 1C-turbo; 如果使能了turbo + P0; 其它情况 + + f_cur + r_dvfs := min( 1, ----- ) + f_max + +我们选择4C turbo而不是1C turbo，以使其更持久性略微更强。 + +r_cpu被定义为当前CPU的最高性能水平与系统中任何其它CPU的最高性能水平的比率。 + + r_tot = r_dvfs * r_cpu + +其结果是，上述“运行”和“可运行”的指标变成DVFS无关和CPU型号无关了。也就是说， +我们可以在CPU之间转移和比较它们。 + +更多细节见: + + - kernel/sched/pelt.h:update_rq_clock_pelt() + - arch/x86/kernel/smpboot.c:"APERF/MPERF frequency ratio computation." + - Documentation/translations/zh_CN/scheduler/sched-capacity.rst:"1. CPU Capacity + 2. Task utilization" + + +UTIL_EST / UTIL_EST_FASTUP +========================== + +由于周期性任务的平均数在睡眠时会衰减，而在运行时其预期利用率会和睡眠前相同， +因此它们在再次运行后会面临（DVFS）的上涨。 + +为了缓解这个问题，（一个默认使能的编译选项）UTIL_EST驱动一个无限脉冲响应 +（Infinite Impulse Response，IIR）的EWMA，“运行”值在出队时是最高的。 +另一个默认使能的编译选项UTIL_EST_FASTUP修改了IIR滤波器，使其允许立即增加， +仅在利用率下降时衰减。 + +进一步，运行队列的（可运行任务的）利用率之和由下式计算： + + util_est := \Sum_t max( t_running, t_util_est_ewma ) + +更多细节见: kernel/sched/fair.c:util_est_dequeue() + + +UCLAMP +====== + +可以在每个CFS或RT任务上设置有效的u_min和u_max clamp值（译注：clamp可以理解 +为类似滤波器的能力，它定义了有效取值范围的最大值和最小值）；运行队列为所有正在 +运行的任务保持这些clamp的最大聚合值。 + +更多细节见: include/uapi/linux/sched/types.h + + +Schedutil / DVFS +================ + +每当调度器的负载跟踪被更新时（任务唤醒、任务迁移、时间流逝），我们都会调用 +schedutil来更新硬件DVFS状态。 + +其基础是CPU运行队列的“运行”指标，根据上面的内容，它是CPU的频率不变的利用率 +估计值。由此我们计算出一个期望的频率，如下:: + + max( running, util_est ); 如果使能UTIL_EST + u_cfs := { running; 其它情况 + + clamp( u_cfs + u_rt, u_min, u_max ); 如果使能UCLAMP_TASK + u_clamp := { u_cfs + u_rt; 其它情况 + + u := u_clamp + u_irq + u_dl; [估计值。更多细节见源代码] + + f_des := min( f_max, 1.25 u * f_max ) + +关于IO-wait的说明：当发生更新是因为任务从IO完成中唤醒时，我们提升上面的“u”。 + +然后，这个频率被用来选择一个P-state或OPP，或者直接混入一个发给硬件的CPPC式 +请求。 + +关于截止期限调度器的说明: 截止期限任务（偶发任务模型）使我们能够计算出满足 +工作负荷所需的硬f_min值。 + +因为这些回调函数是直接来自调度器的，所以DVFS的硬件交互应该是“快速”和非阻塞的。 +在硬件交互缓慢和昂贵的时候，schedutil支持DVFS请求限速，不过会降低效率。 + +更多信息见: kernel/sched/cpufreq_schedutil.c + + +注意 +==== + + - 在低负载场景下，DVFS是最相关的，“运行”的值将密切反映利用率。 + + - 在负载饱和的场景下，任务迁移会导致一些瞬时性的使用率下降。假设我们有一个 + CPU，有4个任务占用导致其饱和，接下来我们将一个任务迁移到另一个空闲CPU上， + 旧的CPU的“运行”值将为0.75，而新的CPU将获得0.25。这是不可避免的，而且随着 + 时间流逝将自动修正。另注，由于没有空闲时间，我们还能保证f_max值吗？ + + - 上述大部分内容是关于避免DVFS下滑，以及独立的DVFS域发生负载迁移时不得不 + 重新学习/提升频率。 + diff --git a/Documentation/translations/zh_TW/index.rst b/Documentation/translations/zh_TW/index.rst index f56f78ba7860..e97d7d578751 100644 --- a/Documentation/translations/zh_TW/index.rst +++ b/Documentation/translations/zh_TW/index.rst @@ -5,7 +5,7 @@ \renewcommand\thesection* \renewcommand\thesubsection* \kerneldocCJKon - \kerneldocBeginTC + \kerneldocBeginTC{ .. _linux_doc_zh_tw: @@ -128,7 +128,7 @@ TODOList: * security/index * sound/index * crypto/index -* vm/index +* mm/index * bpf/index * usb/index * PCI/index @@ -174,4 +174,4 @@ TODOList: .. raw:: latex - \kerneldocEndTC + }\kerneldocEndTC diff --git a/Documentation/translations/zh_TW/oops-tracing.txt b/Documentation/translations/zh_TW/oops-tracing.txt deleted file mode 100644 index be8e59f2abaf..000000000000 --- a/Documentation/translations/zh_TW/oops-tracing.txt +++ /dev/null @@ -1,212 +0,0 @@ -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. - -Traditional Chinese maintainer: Hu Haowen <src.res@email.cn> ---------------------------------------------------------------------- -Documentation/admin-guide/bug-hunting.rst 的繁體中文版翻譯 - -如果想評論或更新本文的內容，請直接聯繫原文檔的維護者。如果你使用英文 -交流有困難的話，也可以向繁體中文版維護者求助。如果本翻譯更新不及時或 -者翻譯存在問題，請聯繫繁體中文版維護者。 - -繁體中文版維護者： 胡皓文 Hu Haowen <src.res@email.cn> -繁體中文版翻譯者： 胡皓文 Hu Haowen <src.res@email.cn> -繁體中文版校譯者： 胡皓文 Hu Haowen <src.res@email.cn> - -以下爲正文 ---------------------------------------------------------------------- - -注意： 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/admin-guide/kdump/kdump.rst）， -使用在Documentation/admin-guide/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_TW/process/5.Posting.rst b/Documentation/translations/zh_TW/process/5.Posting.rst index 5578bca403e6..280a8832ecc0 100644 --- a/Documentation/translations/zh_TW/process/5.Posting.rst +++ b/Documentation/translations/zh_TW/process/5.Posting.rst @@ -22,8 +22,7 @@ 內核開發社區已經發展出一套用於發布補丁的約定和過程；遵循這些約定和過程將使 參與其中的每個人的生活更加輕鬆。本文檔試圖描述這些約定的部分細節；更多信息 也可在以下文檔中找到 -:ref:`Documentation/translations/zh_TW/process/submitting-patches.rst <tw_submittingpatches>`， -:ref:`Documentation/translations/zh_TW/process/submitting-drivers.rst <tw_submittingdrivers>` +:ref:`Documentation/translations/zh_TW/process/submitting-patches.rst <tw_submittingpatches>` 和 :ref:`Documentation/translations/zh_TW/process/submit-checklist.rst <tw_submitchecklist>`。 何時郵寄 diff --git a/Documentation/translations/zh_TW/process/8.Conclusion.rst b/Documentation/translations/zh_TW/process/8.Conclusion.rst index 7572b17667d9..044fcc118bef 100644 --- a/Documentation/translations/zh_TW/process/8.Conclusion.rst +++ b/Documentation/translations/zh_TW/process/8.Conclusion.rst @@ -22,7 +22,6 @@ :ref:`Documentation/translations/zh_TW/process/howto.rst <tw_process_howto>` 文件是一個重要的起點； :ref:`Documentation/translations/zh_TW/process/submitting-patches.rst <tw_submittingpatches>` -和 :ref:`Documentation/translations/zh_TW/process/submitting-drivers.rst <tw_submittingdrivers>` 也是所有內核開發人員都應該閱讀的內容。許多內部內核API都是使用kerneldoc機制 記錄的；「make htmldocs」或「make pdfdocs」可用於以HTML或PDF格式生成這些文檔 （儘管某些發行版提供的tex版本會遇到內部限制，無法正確處理文檔）。 diff --git a/Documentation/translations/zh_TW/process/embargoed-hardware-issues.rst b/Documentation/translations/zh_TW/process/embargoed-hardware-issues.rst index 6c76fc96131a..fbde3e26eda5 100644 --- a/Documentation/translations/zh_TW/process/embargoed-hardware-issues.rst +++ b/Documentation/translations/zh_TW/process/embargoed-hardware-issues.rst @@ -177,7 +177,7 @@ CVE分配 ============= ======================================================== ARM - AMD Tom Lendacky <tom.lendacky@amd.com> + AMD Tom Lendacky <thomas.lendacky@amd.com> IBM Intel Tony Luck <tony.luck@intel.com> Qualcomm Trilok Soni <tsoni@codeaurora.org> diff --git a/Documentation/translations/zh_TW/process/howto.rst b/Documentation/translations/zh_TW/process/howto.rst index 2043691b92e3..8fb8edcaee66 100644 --- a/Documentation/translations/zh_TW/process/howto.rst +++ b/Documentation/translations/zh_TW/process/howto.rst @@ -48,7 +48,7 @@ Linux內核大部分是由C語言寫成的，一些體系結構相關的代碼 - "C: A Reference Manual" by Harbison and Steele [Prentice Hall] 《C語言參考手冊（原書第5版）》（邱仲潘 等譯）[機械工業出版社] -Linux內核使用GNU C和GNU工具鏈開發。雖然它遵循ISO C89標準，但也用到了一些 +Linux內核使用GNU C和GNU工具鏈開發。雖然它遵循ISO C11標準，但也用到了一些 標準中沒有定義的擴展。內核是自給自足的C環境，不依賴於標準C庫的支持，所以 並不支持C標準中的部分定義。比如long long類型的大數除法和浮點運算就不允許 使用。有時候確實很難弄清楚內核對工具鏈的要求和它所使用的擴展，不幸的是目 @@ -99,7 +99,6 @@ Linux內核代碼中包含有大量的文檔。這些文檔對於學習如何與 的代碼。 :ref:`Documentation/translations/zh_TW/process/submitting-patches.rst <tw_submittingpatches>` - :ref:`Documentation/process/submitting-drivers.rst <submittingdrivers>` 這兩份文檔明確描述如何創建和發送補丁，其中包括（但不僅限於)： - 郵件內容 @@ -310,7 +309,7 @@ bugzilla.kernel.org是Linux內核開發者們用來跟蹤內核Bug的網站。 網上很多地方都有這個郵件列表的存檔(archive)。可以使用搜尋引擎來找到這些 存檔。比如： - http://dir.gmane.org/gmane.linux.kernel + https://lore.kernel.org/lkml/ 在發信之前，我們強烈建議你先在存檔中搜索你想要討論的問題。很多已經被詳細 討論過的問題只在郵件列表的存檔中可以找到。 diff --git a/Documentation/translations/zh_TW/process/index.rst b/Documentation/translations/zh_TW/process/index.rst index ec7ad14bfd13..c5c59b4fd595 100644 --- a/Documentation/translations/zh_TW/process/index.rst +++ b/Documentation/translations/zh_TW/process/index.rst @@ -43,7 +43,6 @@ .. toctree:: :maxdepth: 1 - submitting-drivers submit-checklist stable-api-nonsense stable-kernel-rules diff --git a/Documentation/translations/zh_TW/process/magic-number.rst b/Documentation/translations/zh_TW/process/magic-number.rst index ae321a9aaece..f3f7082e17c6 100644 --- a/Documentation/translations/zh_TW/process/magic-number.rst +++ b/Documentation/translations/zh_TW/process/magic-number.rst @@ -61,88 +61,17 @@ Linux 魔術數 魔術數名 數字 結構 文件 ===================== ================ ======================== ========================================== 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`` -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`` -PTY_MAGIC 0x5001 ``drivers/char/pty.c`` -PPP_MAGIC 0x5002 ppp ``include/linux/if_pppvar.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`` -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`` -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`` -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`` -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 ``fs/coda/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_TW/process/programming-language.rst b/Documentation/translations/zh_TW/process/programming-language.rst index 54e3699eadf8..144bdaf81a41 100644 --- a/Documentation/translations/zh_TW/process/programming-language.rst +++ b/Documentation/translations/zh_TW/process/programming-language.rst @@ -12,8 +12,7 @@ ============ 內核是用C語言 :ref:`c-language <tw_c-language>` 編寫的。更準確地說，內核通常是用 :ref:`gcc <tw_gcc>` -在 ``-std=gnu89`` :ref:`gcc-c-dialect-options <tw_gcc-c-dialect-options>` 下編譯的：ISO C90的 GNU 方言（ -包括一些C99特性） +在 ``-std=gnu11`` :ref:`gcc-c-dialect-options <tw_gcc-c-dialect-options>` 下編譯的：ISO C11的 GNU 方言 這種方言包含對語言 :ref:`gnu-extensions <tw_gnu-extensions>` 的許多擴展，當然，它們許多都在內核中使用。 diff --git a/Documentation/translations/zh_TW/process/submitting-drivers.rst b/Documentation/translations/zh_TW/process/submitting-drivers.rst deleted file mode 100644 index 2fdd742318ba..000000000000 --- a/Documentation/translations/zh_TW/process/submitting-drivers.rst +++ /dev/null @@ -1,164 +0,0 @@ -.. SPDX-License-Identifier: GPL-2.0 - -.. _tw_submittingdrivers: - -.. include:: ../disclaimer-zh_TW.rst - -:Original: :ref:`Documentation/process/submitting-drivers.rst - <submittingdrivers>` - -如果想評論或更新本文的內容，請直接聯繫原文檔的維護者。如果你使用英文 -交流有困難的話，也可以向中文版維護者求助。如果本翻譯更新不及時或者翻 -譯存在問題，請聯繫中文版維護者:: - - 中文版維護者： 李陽 Li Yang <leoyang.li@nxp.com> - 中文版翻譯者： 李陽 Li Yang <leoyang.li@nxp.com> - 中文版校譯者： 陳琦 Maggie Chen <chenqi@beyondsoft.com> - 王聰 Wang Cong <xiyou.wangcong@gmail.com> - 張巍 Zhang Wei <wezhang@outlook.com> - 胡皓文 Hu Haowen <src.res@email.cn> - -如何向 Linux 內核提交驅動程序 -============================= - -這篇文檔將會解釋如何向不同的內核源碼樹提交設備驅動程序。請注意，如果你感 -興趣的是顯卡驅動程序，你也許應該訪問 XFree86 項目(https://www.xfree86.org/) -和／或 X.org 項目 (https://x.org)。 - -另請參閱 Documentation/translations/zh_TW/process/submitting-patches.rst 文檔。 - - -分配設備號 ----------- - -塊設備和字符設備的主設備號與從設備號是由 Linux 命名編號分配權威 LANANA（ -現在是 Torben Mathiasen）負責分配。申請的網址是 https://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.rst。有關驅動程序電 - 源管理問題相對全面的概述，請參閱 - 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 版內核）： - https://lwn.net/Kernel/LDD3/ （免費版） - -LWN.net: - 每周內核開發活動摘要 - https://lwn.net/ - - 2.6 版中 API 的變更： - - https://lwn.net/Articles/2.6-kernel-api/ - - 將舊版內核的驅動程序移植到 2.6 版： - - https://lwn.net/Articles/driver-porting/ - -內核新手(KernelNewbies): - 爲新的內核開發者提供文檔和幫助 - https://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): - https://kernelnewbies.org/KernelJanitors - diff --git a/Documentation/translations/zh_TW/process/submitting-patches.rst b/Documentation/translations/zh_TW/process/submitting-patches.rst index c4fd48f5bd8b..3f77ef5d48a0 100644 --- a/Documentation/translations/zh_TW/process/submitting-patches.rst +++ b/Documentation/translations/zh_TW/process/submitting-patches.rst @@ -26,9 +26,7 @@ 以下文檔含有大量簡潔的建議， 具體請見： :ref:`Documentation/process <development_process_main>` 同樣，:ref:`Documentation/translations/zh_TW/process/submit-checklist.rst <tw_submitchecklist>` -給出在提交代碼前需要檢查的項目的列表。如果你在提交一個驅動程序，那麼 -同時閱讀一下: -:ref:`Documentation/process/submitting-drivers.rst <submittingdrivers>` +給出在提交代碼前需要檢查的項目的列表。 其中許多步驟描述了Git版本控制系統的默認行爲；如果您使用Git來準備補丁， 您將發現它爲您完成的大部分機械工作，儘管您仍然需要準備和記錄一組合理的 |