Linux kernel patch 제출 전 점검표

Patch 제출 전 확인할 항목

이 목록은 kernel patch를 더 빨리 accept받기 위해 developer가 확인해야 할 항목입니다. Patch 제출 문서의 요구 사항을 보완하며, 특히 `Documentation/translations/it_IT/process/submitting-patches.rst`와 함께 확인해야 합니다.

.. include:: ../disclaimer-ita.rst

:Original: :ref:`Documentation/process/submit-checklist.rst <submitchecklist>`
:Translator: Federico Vaga <[email protected]>

.. _it_submitchecklist:

============================================================================
Lista delle verifiche da fare prima di inviare una patch per il kernel Linux
============================================================================

Qui troverete una lista di cose che uno sviluppatore dovrebbe fare per
vedere le proprie patch accettate più rapidamente.

Tutti questi punti integrano la documentazione fornita riguardo alla
sottomissione delle patch, in particolare
:ref:`Documentation/translations/it_IT/process/submitting-patches.rst <it_submittingpatches>`.

Code 검토

• Kernel 기능을 사용한다면 그 기능을 선언하거나 정의하는 header file을 직접 `#include`합니다. 다른 header가 우연히 필요한 header를 포함하는 관계에 의존하지 않습니다.
• `Documentation/translations/it_IT/process/coding-style.rst`의 지침에 따라 patch의 coding style을 검사합니다.
• `barrier()`, `rmb()`, `wmb()` 같은 모든 synchronization barrier에는 무엇을 하고 왜 필요한지 logic을 설명하는 source comment를 붙입니다.

Revisiona il tuo codice
=======================

1) Se state usando delle funzionalità del kernel allora includete (#include)
   i file che le dichiarano/definiscono.  Non dipendente dal fatto che un file
   d'intestazione include anche quelli usati da voi.

2) Controllate lo stile del codice della vostra patch secondo le direttive
   scritte in :ref:`Documentation/translations/it_IT/process/coding-style.rst <it_codingstyle>`.

3) Tutte le barriere di sincronizzazione {per esempio, ``barrier()``,
   ``rmb()``, ``wmb()``} devono essere accompagnate da un commento nei
   sorgenti che ne spieghi la logica: cosa fanno e perché.

Kconfig 변경 검토

• 새로 만들거나 수정한 `CONFIG` option이 configuration menu를 어지럽히지 않는지 확인합니다. `Documentation/kbuild/kconfig-language.rst`의 'Menu entries: default values' 기준을 충족하지 않으면 기본값은 disable이어야 합니다.
• 모든 새 `Kconfig` option에 help message를 작성합니다.
• 주요 `Kconfig` configuration 조합을 기준으로 patch를 세심하게 검토합니다. 이를 test만으로 정확히 확인하기는 매우 어려우므로 충분한 사전 검토가 중요합니다.

Revisionate i cambiamenti a Kconfig
===================================

1) Le opzioni ``CONFIG``, nuove o modificate, non scombussolano il menu
   di configurazione e sono preimpostate come disabilitate a meno che non
   soddisfino i criteri descritti in ``Documentation/kbuild/kconfig-language.rst``
   alla punto "Voci di menu: valori predefiniti".

2) Tutte le nuove opzioni ``Kconfig`` hanno un messaggio di aiuto.

3) La patch è stata accuratamente revisionata rispetto alle più importanti
   configurazioni ``Kconfig``.  Questo è molto difficile da fare
   correttamente - un buono lavoro di testa sarà utile.

문서 제공

• Global kernel API는 `kernel-doc`으로 문서화합니다.
• 새 `/proc` entry는 모두 `Documentation/` 아래에 문서화합니다.
• 새 kernel boot parameter는 모두 `Documentation/admin-guide/kernel-parameters.rst`에 문서화합니다.
• 새 module parameter는 모두 `MODULE_PARM_DESC()`로 설명합니다.
• 새 userspace interface는 모두 `Documentation/ABI/`에 문서화합니다. 자세한 내용은 `Documentation/admin-guide/abi.rst` 또는 `Documentation/ABI/README`를 참고하고, userspace interface를 바꾸는 patch는 `[email protected]`에도 Cc합니다.
• Patch가 새 ioctl을 추가한다면 `Documentation/userspace-api/ioctl/ioctl-number.rst`도 갱신합니다.

Fornite documentazione
======================

1) Includete :ref:`kernel-doc <kernel_doc>` per documentare API globali del
   kernel.

2) Tutti i nuovi elementi in ``/proc`` sono documentati in ``Documentation/``.

3) Tutti i nuovi parametri d'avvio del kernel sono documentati in
    ``Documentation/admin-guide/kernel-parameters.rst``.

4) Tutti i nuovi parametri dei moduli sono documentati con ``MODULE_PARM_DESC()``.

5) Tutte le nuove interfacce verso lo spazio utente sono documentate in
    ``Documentation/ABI/``.  Leggete Documentation/admin-guide/abi.rst
    (o ``Documentation/ABI/README``) per maggiori informazioni.
    Le patch che modificano le interfacce utente dovrebbero essere inviate
    in copia anche a [email protected].

6) Se la patch aggiunge nuove chiamate ioctl, allora aggiornate
    ``Documentation/userspace-api/ioctl/ioctl-number.rst``.

도구를 이용한 검사

• 제출 전에 style checker인 `script/checkpatch.pl`로 단순한 위반을 찾습니다. Patch에 남아 있는 모든 위반에는 타당한 이유를 제시할 수 있어야 합니다.
• Sparse로 code를 검사합니다.
• `make checkstack`을 실행하고 발견된 문제를 고칩니다. `checkstack`은 문제를 명시적으로 표시하지 않지만 stack을 512 byte보다 많이 사용하는 function은 수정 후보입니다.

Verificate il vostro codice con gli strumenti
=============================================

1) Prima dell'invio della patch, usate il verificatore di stile
   (``script/checkpatch.pl``) per scovare le violazioni più semplici.
   Dovreste essere in grado di giustificare tutte le violazioni rimanenti nella
   vostra patch.

2) Verificare il codice con sparse.


3) Usare ``make checkstack`` e correggere tutti i problemi rilevati. Da notare
   che ``checkstack`` non evidenzia esplicitamente i problemi, ma una funzione
   che usa più di 512 byte sullo stack è una buona candidata per una correzione.

Code build

• 관련 `CONFIG` option을 `=y`, `=m`, `=n`으로 각각 설정해 `gcc`와 linker warning 또는 error 없이 clean build합니다.
• `allnoconfig`와 `allmodconfig` build를 통과합니다.
• `O=builddir`을 사용하는 build에 성공합니다.
• `Documentation/` 변경은 `make htmldocs` 또는 `make pdfdocs`로 warning과 error 없이 build합니다.
• Cross-compilation tool 등을 사용해 여러 processor architecture에서 build합니다. `ppc64`는 64-bit quantity에 `unsigned long`을 사용하는 경향이 있어 cross-build 검사에 적합합니다.
• 새 code를 `gcc -W`, 즉 `make KCFLAGS=-W`로 compile합니다. Warning이 많이 나오지만 signed와 unsigned 비교 같은 bug를 찾는 데 유용합니다.
• 수정한 code가 관련 kernel interface나 기능에 의존한다면 `CONFIG_SMP`, `CONFIG_SYSFS`, `CONFIG_PROC_FS`, `CONFIG_INPUT`, `CONFIG_PCI`, `CONFIG_BLOCK`, `CONFIG_PM`, `CONFIG_MAGIC_SYSRQ`, `CONFIG_NET`, `CONFIG_INET=n` 조합을 disable하거나 가능한 경우 `=m`으로 바꾸어 여러 configuration에서 build합니다. 모든 option을 한 번에 바꾸지 말고 다양한 조합을 사용합니다.

Compilare il codice
===================

1) Compilazione pulita:

  a) con le opzioni ``CONFIG`` negli stati ``=y``, ``=m`` e ``=n``. Nessun
     avviso/errore di ``gcc`` e nessun avviso/errore dal linker.

  b) con ``allnoconfig``, ``allmodconfig``

  c) quando si usa ``O=builddir``

  d) Qualsiasi modifica in Documentation/ deve compilare con successo senza
     avvisi o errori. Usare ``make htmldocs`` o ``make pdfdocs`` per verificare
     e correggere i problemi

2) Compilare per diverse architetture di processore usando strumenti per la
   cross-compilazione o altri. Una buona architettura per la verifica della
   cross-compilazione è la ppc64 perché tende ad usare ``unsigned long`` per le
   quantità a 64-bit.

3) Il nuovo codice è stato compilato con ``gcc -W`` (usate
    ``make KCFLAGS=-W``).  Questo genererà molti avvisi, ma è ottimo
    per scovare bachi come  "warning: comparison between signed and unsigned".

4) Se il codice che avete modificato dipende o usa una qualsiasi interfaccia o
   funzionalità del kernel che è associata a uno dei seguenti simboli
   ``Kconfig``, allora verificate che il kernel compili con diverse
   configurazioni dove i simboli sono disabilitati e/o ``=m`` (se c'è la
   possibilità) [non tutti contemporaneamente, solo diverse combinazioni
   casuali]:

   ``CONFIG_SMP``, ``CONFIG_SYSFS``, ``CONFIG_PROC_FS``, ``CONFIG_INPUT``,
   ``CONFIG_PCI``, ``CONFIG_BLOCK``, ``CONFIG_PM``, ``CONFIG_MAGIC_SYSRQ``,
   ``CONFIG_NET``, ``CONFIG_INET=n`` (ma l'ultimo con ``CONFIG_NET=y``).

Code runtime test

• `CONFIG_PREEMPT`, `CONFIG_DEBUG_PREEMPT`, `CONFIG_DEBUG_SLAB`, `CONFIG_DEBUG_PAGEALLOC`, `CONFIG_DEBUG_MUTEXES`, `CONFIG_DEBUG_SPINLOCK`, `CONFIG_DEBUG_ATOMIC_SLEEP`, `CONFIG_PROVE_RCU`, `CONFIG_DEBUG_OBJECTS_RCU_HEAD`를 동시에 enable한 상태로 patch를 시험합니다.
• `CONFIG_SMP`와 `CONFIG_PREEMPT`를 각각 켠 경우와 끈 경우 모두 patch를 build하고 runtime test합니다.
• 모든 lockdep 기능을 enable하고 모든 code path를 시험합니다.
• Slab allocation과 page allocation에 failure injection을 적용해 patch를 시험합니다. `Documentation/fault-injection/`을 참고하고 새 code가 크다면 subsystem 전용 fault injection 추가도 고려합니다.
• 가장 최근 `linux-next` tag에서 시험해 queue의 다른 patch와 VM, VFS 및 다른 subsystem 변경을 함께 적용해도 동작하는지 확인합니다.

Verificate il vostro codice
===========================

1) La patch è stata verificata con le seguenti opzioni abilitate
   contemporaneamente: ``CONFIG_PREEMPT``, ``CONFIG_DEBUG_PREEMPT``,
   ``CONFIG_DEBUG_SLAB``, ``CONFIG_DEBUG_PAGEALLOC``, ``CONFIG_DEBUG_MUTEXES``,
   ``CONFIG_DEBUG_SPINLOCK``, ``CONFIG_DEBUG_ATOMIC_SLEEP``,
   ``CONFIG_PROVE_RCU`` e ``CONFIG_DEBUG_OBJECTS_RCU_HEAD``.

2) La patch è stata compilata e verificata in esecuzione con, e senza,
   le opzioni ``CONFIG_SMP`` e ``CONFIG_PREEMPT``.

3) Tutti i percorsi del codice sono stati verificati con tutte le funzionalità
   di lockdep abilitate.

4) La patch è stata verificata con l'iniezione di fallimenti in slab e
   nell'allocazione di pagine. Vedere ``Documentation/fault-injection/``.
   Se il nuovo codice è corposo, potrebbe essere opportuno aggiungere
   l'iniezione di fallimenti specifici per il sottosistema.

5) La patch è stata verificata sul tag più recente di linux-next per assicurarsi
   che funzioni assieme a tutte le altre patch in coda, assieme ai vari
   cambiamenti nei sottosistemi VM, VFS e altri.