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

:Original: :ref:`Documentation/process/7.AdvancedTopics.rst <development_advancedtopics>`
:Translator: Federico Vaga <federico.vaga@vaga.pv.it>

.. _it_development_advancedtopics:

Argomenti avanzati
==================

A questo punto, si spera, dovreste avere un'idea su come funziona il processo
di sviluppo.  Ma rimane comunque molto da imparare!  Questo capitolo copre
alcuni argomenti che potrebbero essere utili per gli sviluppatori che stanno
per diventare parte integrante del processo di sviluppo del kernel.

Gestire le modifiche con git
-----------------------------

L'uso di un sistema distribuito per il controllo delle versioni del kernel
ebbe iniziò nel 2002 quando Linux iniziò a provare il programma proprietario
BitKeeper.  Nonostante l'uso di BitKeeper fosse opinabile, di certo il suo
approccio alla gestione dei sorgenti non lo era.  Un sistema distribuito per
il controllo delle versioni accelerò immediatamente lo sviluppo del kernel.
Oggigiorno, ci sono diverse alternative libere a BitKeeper.  Per il meglio o il
peggio, il progetto del kernel ha deciso di usare git per gestire i sorgenti.

Gestire le modifiche con git può rendere la vita dello sviluppatore molto
più facile, specialmente quando il volume delle modifiche cresce.
Git ha anche i suoi lati taglienti che possono essere pericolosi; è uno
strumento giovane e potente che è ancora in fase di civilizzazione da parte
dei suoi sviluppatori.  Questo documento non ha lo scopo di insegnare l'uso
di git ai suoi lettori; ci sarebbe materiale a sufficienza per un lungo
documento al riguardo.  Invece, qui ci concentriamo in particolare su come
git è parte del processo di sviluppo del kernel.  Gli sviluppatori che
desiderassero diventare agili con git troveranno più informazioni ai
seguenti indirizzi:

	http://git-scm.com/

	http://www.kernel.org/pub/software/scm/git/docs/user-manual.html

e su varie guide che potrete trovare su internet.

La prima cosa da fare prima di usarlo per produrre patch che saranno
disponibili ad altri, è quella di leggere i siti qui sopra e di acquisire una
base solida su come funziona git.  Uno sviluppatore che sappia usare git
dovrebbe essere capace di ottenere una copia del repositorio principale,
esplorare la storia della revisione, registrare le modifiche, usare i rami,
eccetera.  Una certa comprensione degli strumenti git per riscrivere la storia
(come ``rebase``) è altrettanto utile.  Git ha i propri concetti e la propria
terminologia; un nuovo utente dovrebbe conoscere *refs*, *remote branch*,
*index*, *fast-forward merge*, *push* e *pull*, *detached head*, eccetera.
Il tutto potrebbe essere un po' intimidatorio visto da fuori, ma con un po'
di studio i concetti non saranno così difficili da capire.

Utilizzare git per produrre patch da sottomettere via email può essere
un buon esercizio da fare mentre si sta prendendo confidenza con lo strumento.

Quando sarete in grado di creare rami git che siano guardabili da altri,
vi servirà, ovviamente, un server dal quale sia possibile attingere le vostre
modifiche.  Se avete un server accessibile da Internet, configurarlo per
eseguire git-daemon è relativamente semplice .  Altrimenti, iniziano a
svilupparsi piattaforme che offrono spazi pubblici, e gratuiti (Github,
per esempio).  Gli sviluppatori permanenti possono ottenere un account
su kernel.org, ma non è proprio facile da ottenere; per maggiori informazioni
consultate la pagina web http://kernel.org/faq/.

In git è normale avere a che fare con tanti rami.  Ogni linea di sviluppo
può essere separata in "rami per argomenti" e gestiti indipendentemente.
In git i rami sono facilissimi, per cui non c'è motivo per non usarli
in libertà.  In ogni caso, non dovreste sviluppare su alcun ramo dal
quale altri potrebbero attingere.  I rami disponibili pubblicamente dovrebbero
essere creati con attenzione; integrate patch dai rami di sviluppo
solo quando sono complete e pronte ad essere consegnate - non prima.

Git offre alcuni strumenti che vi permettono di riscrivere la storia del
vostro sviluppo.  Una modifica errata (diciamo, una che rompe la bisezione,
oppure che ha un qualche tipo di baco evidente) può essere corretta sul posto
o fatta sparire completamente dalla storia.  Una serie di patch può essere
riscritta come se fosse stata scritta in cima al ramo principale di oggi,
anche se ci avete lavorato per mesi.  Le modifiche possono essere spostate
in modo trasparente da un ramo ad un altro.  E così via.  Un uso giudizioso
di git per revisionare la storia può aiutare nella creazione di una serie
di patch pulite e con meno problemi.

Un uso eccessivo può portare ad altri tipi di problemi, tuttavia, oltre
alla semplice ossessione per la creazione di una storia del progetto che sia
perfetta.  Riscrivere la storia riscriverà le patch contenute in quella
storia, trasformando un kernel verificato (si spera) in uno da verificare.
Ma, oltre a questo, gli sviluppatori non possono collaborare se non condividono
la stessa vista sulla storia del progetto; se riscrivete la storia dalla quale
altri sviluppatori hanno attinto per i loro repositori, renderete la loro vita
molto più difficile.  Quindi tenete conto di questa semplice regola generale:
la storia che avete esposto ad altri, generalmente, dovrebbe essere vista come
immutabile.

Dunque, una volta che il vostro insieme di patch è stato reso disponibile
pubblicamente non dovrebbe essere più sovrascritto.  Git tenterà di imporre
questa regola, e si rifiuterà di pubblicare nuove patch che non risultino
essere dirette discendenti di quelle pubblicate in precedenza (in altre parole,
patch che non condividono la stessa storia).  È possibile ignorare questo
controllo, e ci saranno momenti in cui sarà davvero necessario riscrivere
un ramo già pubblicato.  Un esempio è linux-next dove le patch vengono
spostate da un ramo all'altro al fine di evitare conflitti.  Ma questo tipo
d'azione dovrebbe essere un'eccezione.  Questo è uno dei motivi per cui lo
sviluppo dovrebbe avvenire in rami privati (che possono essere sovrascritti
quando lo si ritiene necessario) e reso pubblico solo quando è in uno stato
avanzato.

Man mano che il ramo principale (o altri rami su cui avete basato le
modifiche) avanza, diventa allettante l'idea di integrare tutte le patch
per rimanere sempre aggiornati.  Per un ramo privato, il *rebase* può essere
un modo semplice per rimanere aggiornati, ma questa non è un'opzione nel
momento in cui il vostro ramo è stato esposto al mondo intero.
*Merge* occasionali possono essere considerati di buon senso, ma quando
diventano troppo frequenti confondono inutilmente la storia.  La tecnica
suggerita in questi casi è quella di fare *merge* raramente, e più in generale
solo nei momenti di rilascio (per esempio gli -rc del ramo principale).
Se siete nervosi circa alcune patch in particolare, potete sempre fare
dei *merge* di test in un ramo privato.  In queste situazioni git "rerere"
può essere utile; questo strumento si ricorda come i conflitti di *merge*
furono risolti in passato cosicché non dovrete fare lo stesso lavoro due volte.

Una delle lamentele più grosse e ricorrenti sull'uso di strumenti come git
è il grande movimento di patch da un repositorio all'altro che rende
facile l'integrazione nel ramo principale di modifiche mediocri, il tutto
sotto il naso dei revisori.  Gli sviluppatori del kernel tendono ad essere
scontenti quando vedono succedere queste cose; preparare un ramo git con
patch che non hanno ricevuto alcuna revisione o completamente avulse, potrebbe
influire sulla vostra capacita di proporre, in futuro, l'integrazione dei
vostri rami.  Citando Linus

::

	Potete inviarmi le vostre patch, ma per far si che io integri una
	vostra modifica da git, devo sapere che voi sappiate cosa state
	facendo, e ho bisogno di fidarmi *senza* dover passare tutte
	le modifiche manualmente una per una.

(http://lwn.net/Articles/224135/).

Per evitare queste situazioni, assicuratevi che tutte le patch in un ramo
siano strettamente correlate al tema delle modifiche; un ramo "driver fixes"
non dovrebbe fare modifiche al codice principale per la gestione della memoria.
E, più importante ancora, non usate un repositorio git per tentare di
evitare il processo di revisione.  Pubblicate un sommario di quello che il
vostro ramo contiene sulle liste di discussione più opportune, e , quando
sarà il momento, richiedete che il vostro ramo venga integrato in linux-next.

Se e quando altri inizieranno ad inviarvi patch per essere incluse nel
vostro repositorio, non dovete dimenticare di revisionarle.  Inoltre
assicuratevi di mantenerne le informazioni di paternità; al riguardo git "am"
fa del suo meglio, ma potreste dover aggiungere una riga "From:" alla patch
nel caso in cui sia arrivata per vie traverse.

Quando richiedete l'integrazione, siate certi di fornire tutte le informazioni:
dov'è il vostro repositorio, quale ramo integrare, e quali cambiamenti si
otterranno dall'integrazione.  Il comando git request-pull può essere d'aiuto;
preparerà una richiesta nel modo in cui gli altri sviluppatori se l'aspettano,
e verificherà che vi siate ricordati di pubblicare quelle patch su un
server pubblico.

Revisionare le patch
--------------------

Alcuni lettori potrebbero avere obiezioni sulla presenza di questa sezione
negli "argomenti avanzati" sulla base che anche gli sviluppatori principianti
dovrebbero revisionare le patch.  É certamente vero che non c'è modo
migliore di imparare come programmare per il kernel che guardare il codice
pubblicato dagli altri.  In aggiunta, i revisori sono sempre troppo pochi;
guardando il codice potete apportare un significativo contributo all'intero
processo.

Revisionare il codice potrebbe risultare intimidatorio, specialmente per i
nuovi arrivati che potrebbero sentirsi un po' nervosi nel questionare
il codice - in pubblico - pubblicato da sviluppatori più esperti.  Perfino
il codice scritto dagli sviluppatori più esperti può essere migliorato.
Forse il suggerimento migliore per i revisori (tutti) è questo: formulate
i commenti come domande e non come critiche.  Chiedere "Come viene rilasciato
il *lock* in questo percorso?" funziona sempre molto meglio che
"qui la sincronizzazione è sbagliata".

Diversi sviluppatori revisioneranno il codice con diversi punti di vista.
Alcuni potrebbero concentrarsi principalmente sullo stile del codice e se
alcune linee hanno degli spazio bianchi di troppo.  Altri si chiederanno
se accettare una modifica interamente è una cosa positiva per il kernel
o no.  E altri ancora si focalizzeranno sui problemi di sincronizzazione,
l'uso eccessivo di *stack*, problemi di sicurezza, duplicazione del codice
in altri contesti, documentazione, effetti negativi sulle prestazioni, cambi
all'ABI dello spazio utente, eccetera.  Qualunque tipo di revisione è ben
accetta e di valore, se porta ad avere un codice migliore nel kernel.


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

:Original: :ref:`Documentation/process/8.Conclusion.rst <development_conclusion>`
:Translator: Alessia Mantegazza <amantegazza@vaga.pv.it>

.. _it_development_conclusion:

Per maggiori informazioni
=========================

Esistono numerose fonti di informazioni sullo sviluppo del kernel Linux
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>` è
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
distribuzioni hanno dei limiti interni e fallisce nel processare
appropriatamente i documenti).

Diversi siti web approfondiscono lo sviluppo del kernel ad ogni livello
di dettaglio.  Il vostro autore vorrebbe umilmente suggerirvi
http://lwn.net/ come fonte; usando l'indice 'kernel' su LWN troverete
molti argomenti specifici sul kernel:

	http://lwn.net/Kernel/Index/

Oltre a ciò, una risorsa valida per gli sviluppatori kernel è:

	http://kernelnewbies.org/

E, ovviamente, una fonte da non dimenticare è http://kernel.org/, il luogo
definitivo per le informazioni sui rilasci del kernel.

Ci sono numerosi libri sullo sviluppo del kernel:

	Linux Device Drivers, 3rd Edition (Jonathan Corbet, Alessandro
	Rubini, and Greg Kroah-Hartman).  In linea all'indirizzo
	http://lwn.net/Kernel/LDD3/.

	Linux Kernel Development (Robert Love).

	Understanding the Linux Kernel (Daniel Bovet and Marco Cesati).

Tutti questi libri soffrono di un errore comune: tendono a risultare in un
certo senso obsoleti dal momento che si trovano in libreria da diverso
tempo.  Comunque contengono informazioni abbastanza buone.

La documentazione per git la troverete su:

	http://www.kernel.org/pub/software/scm/git/docs/

	http://www.kernel.org/pub/software/scm/git/docs/user-manual.html

Conclusioni
===========

Congratulazioni a chiunque ce l'abbia fatta a terminare questo documento di
lungo-respiro.  Si spera che abbia fornito un'utile comprensione d'insieme
di come il kernel Linux viene sviluppato e di come potete partecipare a
tale processo.

Infine, quello che conta è partecipare.  Qualsiasi progetto software
open-source non è altro che la somma di quello che i suoi contributori
mettono al suo interno.  Il kernel Linux è cresciuto velocemente e bene
perché ha ricevuto il supporto di un impressionante gruppo di sviluppatori,
ognuno dei quali sta lavorando per renderlo migliore.  Il kernel è un esempio
importante di cosa può essere fatto quando migliaia di persone lavorano
insieme verso un obiettivo comune.

Il kernel può sempre beneficiare di una larga base di sviluppatori, tuttavia,
c'è sempre molto lavoro da fare.  Ma, cosa non meno importante, molti degli
altri partecipanti all'ecosistema Linux possono trarre beneficio attraverso
il contributo al kernel.  Inserire codice nel ramo principale è la chiave
per arrivare ad una qualità del codice più alta, bassa manutenzione e
bassi prezzi di distribuzione, alti livelli d'influenza sulla direzione
dello sviluppo del kernel, e molto altro.  È una situazione nella quale
tutti coloro che sono coinvolti vincono.  Mollate il vostro editor e
raggiungeteci; sarete più che benvenuti.

repo_name: angery/linux


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

:Original: :ref:`Documentation/process/adding-syscalls.rst <addsyscalls>`
:Translator: Federico Vaga <federico.vaga@vaga.pv.it>

.. _it_addsyscalls:

Aggiungere una nuova chiamata di sistema
========================================

Questo documento descrive quello che è necessario sapere per aggiungere
nuove chiamate di sistema al kernel Linux; questo è da considerarsi come
un'aggiunta ai soliti consigli su come proporre nuove modifiche
:ref:`Documentation/translations/it_IT/process/submitting-patches.rst <it_submittingpatches>`.

Alternative alle chiamate di sistema
------------------------------------

La prima considerazione da fare quando si aggiunge una nuova chiamata di
sistema è quella di valutare le alternative.  Nonostante le chiamate di sistema
siano il punto di interazione fra spazio utente e kernel più tradizionale ed
ovvio, esistono altre possibilità - scegliete quella che meglio si adatta alle
vostra interfaccia.

 - Se le operazioni coinvolte possono rassomigliare a quelle di un filesystem,
   allora potrebbe avere molto più senso la creazione di un nuovo filesystem o
   dispositivo.  Inoltre, questo rende più facile incapsulare la nuova
   funzionalità in un modulo kernel piuttosto che essere sviluppata nel cuore
   del kernel.

     - Se la nuova funzionalità prevede operazioni dove il kernel notifica
       lo spazio utente su un avvenimento, allora restituire un descrittore
       di file all'oggetto corrispondente permette allo spazio utente di
       utilizzare ``poll``/``select``/``epoll`` per ricevere quelle notifiche.
     - Tuttavia, le operazioni che non si sposano bene con operazioni tipo
       :manpage:`read(2)`/:manpage:`write(2)` dovrebbero essere implementate
       come chiamate :manpage:`ioctl(2)`, il che potrebbe portare ad un'API in
       un qualche modo opaca.

 - Se dovete esporre solo delle informazioni sul sistema, un nuovo nodo in
   sysfs (vedere ``Documentation/filesystems/sysfs.rst``) o
   in procfs potrebbe essere sufficiente.  Tuttavia, l'accesso a questi
   meccanismi richiede che il filesystem sia montato, il che potrebbe non
   essere sempre vero (per esempio, in ambienti come namespace/sandbox/chroot).
   Evitate d'aggiungere nuove API in debugfs perché questo non viene
   considerata un'interfaccia di 'produzione' verso lo spazio utente.
 - Se l'operazione è specifica ad un particolare file o descrittore, allora
   potrebbe essere appropriata l'aggiunta di un comando :manpage:`fcntl(2)`.
   Tuttavia, :manpage:`fcntl(2)` è una chiamata di sistema multiplatrice che
   nasconde una notevole complessità, quindi è ottima solo quando la nuova
   funzione assomiglia a quelle già esistenti in :manpage:`fcntl(2)`, oppure
   la nuova funzionalità è veramente semplice (per esempio, leggere/scrivere
   un semplice flag associato ad un descrittore di file).
 - Se l'operazione è specifica ad un particolare processo, allora
   potrebbe essere appropriata l'aggiunta di un comando :manpage:`prctl(2)`.
   Come per :manpage:`fcntl(2)`, questa chiamata di sistema è un complesso
   multiplatore quindi è meglio usarlo per cose molto simili a quelle esistenti
   nel comando ``prctl`` oppure per leggere/scrivere un semplice flag relativo
   al processo.

Progettare l'API: pianificare le estensioni
-------------------------------------------

Una nuova chiamata di sistema diventerà parte dell'API del kernel, e
dev'essere supportata per un periodo indefinito.  Per questo, è davvero
un'ottima idea quella di discutere apertamente l'interfaccia sulla lista
di discussione del kernel, ed è altrettanto importante pianificarne eventuali
estensioni future.

(Nella tabella delle chiamate di sistema sono disseminati esempi dove questo
non fu fatto, assieme ai corrispondenti aggiornamenti -
``eventfd``/``eventfd2``, ``dup2``/``dup3``, ``inotify_init``/``inotify_init1``,
``pipe``/``pipe2``, ``renameat``/``renameat2`` --quindi imparate dalla storia
del kernel e pianificate le estensioni fin dall'inizio)

Per semplici chiamate di sistema che accettano solo un paio di argomenti,
il modo migliore di permettere l'estensibilità è quello di includere un
argomento *flags* alla chiamata di sistema.  Per assicurarsi che i programmi
dello spazio utente possano usare in sicurezza *flags* con diverse versioni
del kernel, verificate se *flags* contiene un qualsiasi valore sconosciuto,
in qual caso rifiutate la chiamata di sistema (con ``EINVAL``)::

    if (flags & ~(THING_FLAG1 | THING_FLAG2 | THING_FLAG3))
        return -EINVAL;

(Se *flags* non viene ancora utilizzato, verificate che l'argomento sia zero)

Per chiamate di sistema più sofisticate che coinvolgono un numero più grande di
argomenti, il modo migliore è quello di incapsularne la maggior parte in una
struttura dati che verrà passata per puntatore.  Questa struttura potrà
funzionare con future estensioni includendo un campo *size*::

    struct xyzzy_params {
        u32 size; /* userspace sets p->size = sizeof(struct xyzzy_params) */
        u32 param_1;
        u64 param_2;
        u64 param_3;
    };

Fintanto che un qualsiasi campo nuovo, diciamo ``param_4``, è progettato per
offrire il comportamento precedente quando vale zero, allora questo permetterà
di gestire un conflitto di versione in entrambe le direzioni:

 - un vecchio kernel può gestire l'accesso di una versione moderna di un
   programma in spazio utente verificando che la memoria oltre la dimensione
   della struttura dati attesa sia zero (in pratica verificare che
   ``param_4 == 0``).
 - un nuovo kernel può gestire l'accesso di una versione vecchia di un
   programma in spazio utente estendendo la struttura dati con zeri (in pratica
   ``param_4 = 0``).

Vedere :manpage:`perf_event_open(2)` e la funzione ``perf_copy_attr()`` (in
``kernel/events/core.c``) per un esempio pratico di questo approccio.

Progettare l'API: altre considerazioni
--------------------------------------

Se la vostra nuova chiamata di sistema permette allo spazio utente di fare
riferimento ad un oggetto del kernel, allora questa dovrebbe usare un
descrittore di file per accesso all'oggetto - non inventatevi nuovi tipi di
accesso da spazio utente quando il kernel ha già dei meccanismi e una semantica
ben definita per utilizzare i descrittori di file.

Se la vostra nuova chiamata di sistema :manpage:`xyzzy(2)` ritorna un nuovo
descrittore di file, allora l'argomento *flags* dovrebbe includere un valore
equivalente a ``O_CLOEXEC`` per i nuovi descrittori.  Questo rende possibile,
nello spazio utente, la chiusura della finestra temporale fra le chiamate a
``xyzzy()`` e ``fcntl(fd, F_SETFD, FD_CLOEXEC)``, dove un inaspettato
``fork()`` o ``execve()`` potrebbe trasferire il descrittore al programma
eseguito (Comunque, resistete alla tentazione di riutilizzare il valore di
``O_CLOEXEC`` dato che è specifico dell'architettura e fa parte di una
enumerazione di flag ``O_*`` che è abbastanza ricca).

Se la vostra nuova chiamata di sistema ritorna un nuovo descrittore di file,
dovreste considerare che significato avrà l'uso delle chiamate di sistema
della famiglia di :manpage:`poll(2)`. Rendere un descrittore di file pronto
per la lettura o la scrittura è il tipico modo del kernel per notificare lo
spazio utente circa un evento associato all'oggetto del kernel.

Se la vostra nuova chiamata di sistema :manpage:`xyzzy(2)` ha un argomento
che è il percorso ad un file::

    int sys_xyzzy(const char __user *path, ..., unsigned int flags);

dovreste anche considerare se non sia più appropriata una versione
:manpage:`xyzzyat(2)`::

    int sys_xyzzyat(int dfd, const char __user *path, ..., unsigned int flags);

Questo permette più flessibilità su come lo spazio utente specificherà il file
in questione; in particolare, permette allo spazio utente di richiedere la
funzionalità su un descrittore di file già aperto utilizzando il *flag*
``AT_EMPTY_PATH``, in pratica otterremmo gratuitamente l'operazione
:manpage:`fxyzzy(3)`::

 - xyzzyat(AT_FDCWD, path, ..., 0) is equivalent to xyzzy(path,...)
 - xyzzyat(fd, "", ..., AT_EMPTY_PATH) is equivalent to fxyzzy(fd, ...)

(Per maggiori dettagli sulla logica delle chiamate \*at(), leggete la pagina
man :manpage:`openat(2)`; per un esempio di AT_EMPTY_PATH, leggere la pagina
man :manpage:`fstatat(2)`).

Se la vostra nuova chiamata di sistema :manpage:`xyzzy(2)` prevede un parametro
per descrivere uno scostamento all'interno di un file, usate ``loff_t`` come
tipo cosicché scostamenti a 64-bit potranno essere supportati anche su
architetture a 32-bit.

Se la vostra nuova chiamata di sistema :manpage:`xyzzy(2)` prevede l'uso di
funzioni riservate, allora dev'essere gestita da un opportuno bit di privilegio
(verificato con una chiamata a ``capable()``), come descritto nella pagina man
:manpage:`capabilities(7)`.  Scegliete un bit di privilegio già esistente per
gestire la funzionalità associata, ma evitate la combinazione di diverse
funzionalità vagamente collegate dietro lo stesso bit, in quanto va contro il
principio di *capabilities* di separare i poteri di root.  In particolare,
evitate di aggiungere nuovi usi al fin-troppo-generico privilegio
``CAP_SYS_ADMIN``.

Se la vostra nuova chiamata di sistema :manpage:`xyzzy(2)` manipola altri
processi oltre a quello chiamato, allora dovrebbe essere limitata (usando
la chiamata ``ptrace_may_access()``) di modo che solo un processo chiamante
con gli stessi permessi del processo in oggetto, o con i necessari privilegi,
possa manipolarlo.

Infine, state attenti che in alcune architetture non-x86 la vita delle chiamate
di sistema con argomenti a 64-bit viene semplificata se questi argomenti
ricadono in posizioni dispari (pratica, i parametri 1, 3, 5); questo permette
l'uso di coppie contigue di registri a 32-bit.  (Questo non conta se gli
argomenti sono parte di una struttura dati che viene passata per puntatore).

Proporre l'API
--------------

Al fine di rendere le nuove chiamate di sistema di facile revisione, è meglio
che dividiate le modifiche i pezzi separati.  Questi dovrebbero includere
almeno le seguenti voci in *commit* distinti (ognuno dei quali sarà descritto
più avanti):

 - l'essenza dell'implementazione della chiamata di sistema, con i prototipi,
   i numeri generici, le modifiche al Kconfig e l'implementazione *stub* di
   ripiego.
 - preparare la nuova chiamata di sistema per un'architettura specifica,
   solitamente x86 (ovvero tutti: x86_64, x86_32 e x32).
 - un programma di auto-verifica da mettere in ``tools/testing/selftests/``
   che mostri l'uso della chiamata di sistema.
 - una bozza di pagina man per la nuova chiamata di sistema. Può essere
   scritta nell'email di presentazione, oppure come modifica vera e propria
   al repositorio delle pagine man.

Le proposte di nuove chiamate di sistema, come ogni altro modifica all'API del
kernel, deve essere sottomessa alla lista di discussione
linux-api@vger.kernel.org.

Implementazione di chiamate di sistema generiche
------------------------------------------------

Il principale punto d'accesso alla vostra nuova chiamata di sistema
:manpage:`xyzzy(2)` verrà chiamato ``sys_xyzzy()``; ma, piuttosto che in modo
esplicito, lo aggiungerete tramite la macro ``SYSCALL_DEFINEn``. La 'n'
indica il numero di argomenti della chiamata di sistema; la macro ha come
argomento il nome della chiamata di sistema, seguito dalle coppie (tipo, nome)
per definire i suoi parametri.  L'uso di questa macro permette di avere
i metadati della nuova chiamata di sistema disponibili anche per altri
strumenti.

Il nuovo punto d'accesso necessita anche del suo prototipo di funzione in
``include/linux/syscalls.h``, marcato come asmlinkage di modo da abbinargli
il modo in cui quelle chiamate di sistema verranno invocate::

    asmlinkage long sys_xyzzy(...);

Alcune architetture (per esempio x86) hanno le loro specifiche tabelle di
chiamate di sistema (syscall), ma molte altre architetture condividono una
tabella comune di syscall. Aggiungete alla lista generica la vostra nuova
chiamata di sistema aggiungendo un nuovo elemento alla lista in
``include/uapi/asm-generic/unistd.h``::

    #define __NR_xyzzy 292
    __SYSCALL(__NR_xyzzy, sys_xyzzy)

Aggiornate anche il contatore __NR_syscalls di modo che sia coerente con
l'aggiunta della nuove chiamate di sistema; va notato che se più di una nuova
chiamata di sistema viene aggiunga nella stessa finestra di sviluppo, il numero
della vostra nuova syscall potrebbe essere aggiustato al fine di risolvere i
conflitti.

Il file ``kernel/sys_ni.c`` fornisce le implementazioni *stub* di ripiego che
ritornano ``-ENOSYS``.  Aggiungete la vostra nuova chiamata di sistema anche
qui::

    COND_SYSCALL(xyzzy);

La vostra nuova funzionalità del kernel, e la chiamata di sistema che la
controlla, dovrebbero essere opzionali. Quindi, aggiungete un'opzione
``CONFIG`` (solitamente in ``init/Kconfig``).  Come al solito per le nuove
opzioni ``CONFIG``:

 - Includete una descrizione della nuova funzionalità e della chiamata di
   sistema che la controlla.
 - Rendete l'opzione dipendente da EXPERT se dev'essere nascosta agli utenti
   normali.
 - Nel Makefile, rendere tutti i nuovi file sorgenti, che implementano la
   nuova funzionalità, dipendenti dall'opzione CONFIG (per esempio
   ``obj-$(CONFIG_XYZZY_SYSCALL) += xyzzy.o``).
 - Controllate due volte che sia possibile generare il kernel con la nuova
   opzione CONFIG disabilitata.

Per riassumere, vi serve un *commit* che includa:

 - un'opzione ``CONFIG``per la nuova funzione, normalmente in ``init/Kconfig``
 - ``SYSCALL_DEFINEn(xyzzy, ...)`` per il punto d'accesso
 - il corrispondente prototipo in ``include/linux/syscalls.h``
 - un elemento nella tabella generica in ``include/uapi/asm-generic/unistd.h``
 - *stub* di ripiego in ``kernel/sys_ni.c``

Implementazione delle chiamate di sistema x86
---------------------------------------------

Per collegare la vostra nuova chiamate di sistema alle piattaforme x86,
dovete aggiornate la tabella principale di syscall.  Assumendo che la vostra
nuova chiamata di sistema non sia particolarmente speciale (vedere sotto),
dovete aggiungere un elemento *common* (per x86_64 e x32) in
arch/x86/entry/syscalls/syscall_64.tbl::

    333   common   xyzzy     sys_xyzzy

e un elemento per *i386* ``arch/x86/entry/syscalls/syscall_32.tbl``::

    380   i386     xyzzy     sys_xyzzy

Ancora una volta, questi numeri potrebbero essere cambiati se generano
conflitti durante la finestra di integrazione.

Chiamate di sistema compatibili (generico)
------------------------------------------

Per molte chiamate di sistema, la stessa implementazione a 64-bit può essere
invocata anche quando il programma in spazio utente è a 32-bit; anche se la
chiamata di sistema include esplicitamente un puntatore, questo viene gestito
in modo trasparente.

Tuttavia, ci sono un paio di situazione dove diventa necessario avere un
livello di gestione della compatibilità per risolvere le differenze di
dimensioni fra 32-bit e 64-bit.

Il primo caso è quando un kernel a 64-bit supporta anche programmi in spazio
utente a 32-bit, perciò dovrà ispezionare aree della memoria (``__user``) che
potrebbero contenere valori a 32-bit o a 64-bit.  In particolar modo, questo
è necessario quando un argomento di una chiamata di sistema è:

 - un puntatore ad un puntatore
 - un puntatore ad una struttura dati contenente a sua volta un puntatore
   ( ad esempio ``struct iovec __user *``)
 - un puntatore ad un tipo intero di dimensione variabile (``time_t``,
   ``off_t``, ``long``, ...)
 - un puntatore ad una struttura dati contenente un tipo intero di dimensione
   variabile.

Il secondo caso che richiede un livello di gestione della compatibilità è
quando uno degli argomenti di una chiamata a sistema è esplicitamente un tipo
a 64-bit anche su architetture a 32-bit, per esempio ``loff_t`` o ``__u64``.
In questo caso, un valore che arriva ad un kernel a 64-bit da un'applicazione
a 32-bit verrà diviso in due valori a 32-bit che dovranno essere riassemblati
in questo livello di compatibilità.

(Da notare che non serve questo livello di compatibilità per argomenti che
sono puntatori ad un tipo esplicitamente a 64-bit; per esempio, in
:manpage:`splice(2)` l'argomento di tipo ``loff_t __user *`` non necessita
di una chiamata di sistema ``compat_``)

La versione compatibile della nostra chiamata di sistema si chiamerà
``compat_sys_xyzzy()``, e viene aggiunta utilizzando la macro
``COMPAT_SYSCALL_DEFINEn()`` (simile a SYSCALL_DEFINEn).  Questa versione
dell'implementazione è parte del kernel a 64-bit ma accetta parametri a 32-bit
che trasformerà secondo le necessità (tipicamente, la versione
``compat_sys_`` converte questi valori nello loro corrispondente a 64-bit e
può chiamare la versione ``sys_`` oppure invocare una funzione che implementa
le parti comuni).

Il punto d'accesso *compat* deve avere il corrispondente prototipo di funzione
in ``include/linux/compat.h``, marcato come asmlinkage di modo da abbinargli
il modo in cui quelle chiamate di sistema verranno invocate::

    asmlinkage long compat_sys_xyzzy(...);

Se la chiamata di sistema prevede una struttura dati organizzata in modo
diverso per sistemi a 32-bit e per quelli a 64-bit, diciamo
``struct xyzzy_args``, allora il file d'intestazione
``then the include/linux/compat.h`` deve includere la sua versione
*compatibile* (``struct compat_xyzzy_args``); ogni variabile con
dimensione variabile deve avere il proprio tipo ``compat_`` corrispondente
a quello in ``struct xyzzy_args``.  La funzione ``compat_sys_xyzzy()``
può usare la struttura ``compat_`` per analizzare gli argomenti ricevuti
da una chiamata a 32-bit.

Per esempio, se avete i seguenti campi::

    struct xyzzy_args {
        const char __user *ptr;
        __kernel_long_t varying_val;
        u64 fixed_val;
        /* ... */
    };

nella struttura ``struct xyzzy_args``, allora la struttura
``struct compat_xyzzy_args`` dovrebbe avere::

    struct compat_xyzzy_args {
        compat_uptr_t ptr;
        compat_long_t varying_val;
        u64 fixed_val;
        /* ... */
    };

La lista generica delle chiamate di sistema ha bisogno di essere
aggiustata al fine di permettere l'uso della versione *compatibile*;
la voce in ``include/uapi/asm-generic/unistd.h`` dovrebbero usare
``__SC_COMP`` piuttosto di ``__SYSCALL``::

    #define __NR_xyzzy 292
    __SC_COMP(__NR_xyzzy, sys_xyzzy, compat_sys_xyzzy)

Riassumendo, vi serve:

 - un ``COMPAT_SYSCALL_DEFINEn(xyzzy, ...)`` per il punto d'accesso
   *compatibile*
 - un prototipo in ``include/linux/compat.h``
 - (se necessario) una struttura di compatibilità a 32-bit in
   ``include/linux/compat.h``
 - una voce ``__SC_COMP``, e non ``__SYSCALL``, in
   ``include/uapi/asm-generic/unistd.h``

Compatibilità delle chiamate di sistema (x86)
---------------------------------------------

Per collegare una chiamata di sistema, su un'architettura x86, con la sua
versione *compatibile*, è necessario aggiustare la voce nella tabella
delle syscall.

Per prima cosa, la voce in ``arch/x86/entry/syscalls/syscall_32.tbl`` prende
un argomento aggiuntivo per indicare che un programma in spazio utente
a 32-bit, eseguito su un kernel a 64-bit, dovrebbe accedere tramite il punto
d'accesso compatibile::

    380   i386     xyzzy     sys_xyzzy    __ia32_compat_sys_xyzzy

Secondo, dovete capire cosa dovrebbe succedere alla nuova chiamata di sistema
per la versione dell'ABI x32.  Qui C'è una scelta da fare: gli argomenti
possono corrisponde alla versione a 64-bit o a quella a 32-bit.

Se c'è un puntatore ad un puntatore, la decisione è semplice: x32 è ILP32,
quindi gli argomenti dovrebbero corrispondere a quelli a 32-bit, e la voce in
``arch/x86/entry/syscalls/syscall_64.tbl`` sarà divisa cosicché i programmi
x32 eseguano la chiamata *compatibile*::

    333   64       xyzzy     sys_xyzzy
    ...
    555   x32      xyzzy     __x32_compat_sys_xyzzy

Se non ci sono puntatori, allora è preferibile riutilizzare la chiamata di
sistema a 64-bit per l'ABI x32 (e di conseguenza la voce in
arch/x86/entry/syscalls/syscall_64.tbl rimane immutata).

In ambo i casi, dovreste verificare che i tipi usati dagli argomenti
abbiano un'esatta corrispondenza da x32 (-mx32) al loro equivalente a
32-bit (-m32) o 64-bit (-m64).

Chiamate di sistema che ritornano altrove
-----------------------------------------

Nella maggior parte delle chiamate di sistema, al termine della loro
esecuzione, i programmi in spazio utente riprendono esattamente dal punto
in cui si erano interrotti -- quindi dall'istruzione successiva, con lo
stesso *stack* e con la maggior parte del registri com'erano stati
lasciati prima della chiamata di sistema, e anche con la stessa memoria
virtuale.

Tuttavia, alcune chiamata di sistema fanno le cose in modo differente.
Potrebbero ritornare ad un punto diverso (``rt_sigreturn``) o cambiare
la memoria in spazio utente (``fork``/``vfork``/``clone``) o perfino
l'architettura del programma (``execve``/``execveat``).

Per permettere tutto ciò, l'implementazione nel kernel di questo tipo di
chiamate di sistema potrebbero dover salvare e ripristinare registri
aggiuntivi nello *stack* del kernel, permettendo così un controllo completo
su dove e come l'esecuzione dovrà continuare dopo l'esecuzione della
chiamata di sistema.

Queste saranno specifiche per ogni architettura, ma tipicamente si definiscono
dei punti d'accesso in *assembly* per salvare/ripristinare i registri
aggiuntivi e quindi chiamare il vero punto d'accesso per la chiamata di
sistema.

Per l'architettura x86_64, questo è implementato come un punto d'accesso
``stub_xyzzy`` in ``arch/x86/entry/entry_64.S``, e la voce nella tabella
di syscall (``arch/x86/entry/syscalls/syscall_64.tbl``) verrà corretta di
conseguenza::

    333   common   xyzzy     stub_xyzzy

L'equivalente per programmi a 32-bit eseguiti su un kernel a 64-bit viene
normalmente chiamato ``stub32_xyzzy`` e implementato in
``arch/x86/entry/entry_64_compat.S`` con la corrispondente voce nella tabella
di syscall ``arch/x86/entry/syscalls/syscall_32.tbl`` corretta nel
seguente modo::

    380   i386     xyzzy     sys_xyzzy    stub32_xyzzy

Se una chiamata di sistema necessita di un livello di compatibilità (come
nella sezione precedente), allora la versione ``stub32_`` deve invocare
la versione ``compat_sys_`` piuttosto che quella nativa a 64-bit.  In aggiunta,
se l'implementazione dell'ABI x32 è diversa da quella x86_64, allora la sua
voce nella tabella di syscall dovrà chiamare uno *stub* che invoca la versione
``compat_sys_``,

Per completezza, sarebbe carino impostare una mappatura cosicché
*user-mode* Linux (UML) continui a funzionare -- la sua tabella di syscall
farà riferimento a stub_xyzzy, ma UML non include l'implementazione
in ``arch/x86/entry/entry_64.S`` (perché UML simula i registri eccetera).
Correggerlo è semplice, basta aggiungere una #define in
``arch/x86/um/sys_call_table_64.c``::

    #define stub_xyzzy sys_xyzzy

Altri dettagli
--------------

La maggior parte dei kernel tratta le chiamate di sistema allo stesso modo,
ma possono esserci rare eccezioni per le quali potrebbe essere necessario
l'aggiornamento della vostra chiamata di sistema.

Il sotto-sistema di controllo (*audit subsystem*) è uno di questi casi
speciali; esso include (per architettura) funzioni che classificano alcuni
tipi di chiamate di sistema -- in particolare apertura dei file
(``open``/``openat``), esecuzione dei programmi (``execve``/``exeveat``)
oppure multiplatori di socket (``socketcall``). Se la vostra nuova chiamata
di sistema è simile ad una di queste, allora il sistema di controllo dovrebbe
essere aggiornato.

Più in generale, se esiste una chiamata di sistema che è simile alla vostra,
vale la pena fare una ricerca con ``grep`` su tutto il kernel per la chiamata
di sistema esistente per verificare che non ci siano altri casi speciali.

Verifica
--------

Una nuova chiamata di sistema dev'essere, ovviamente, provata; è utile fornire
ai revisori un programma in spazio utente che mostri l'uso della chiamata di
sistema.  Un buon modo per combinare queste cose è quello di aggiungere un
semplice programma di auto-verifica in una nuova cartella in
``tools/testing/selftests/``.

Per una nuova chiamata di sistema, ovviamente, non ci sarà alcuna funzione
in libc e quindi il programma di verifica dovrà invocarla usando ``syscall()``;
inoltre, se la nuova chiamata di sistema prevede un nuova struttura dati
visibile in spazio utente, il file d'intestazione necessario dev'essere
installato al fine di compilare il programma.

Assicuratevi che il programma di auto-verifica possa essere eseguito
correttamente su tutte le architetture supportate.  Per esempio, verificate che
funzioni quando viene compilato per x86_64 (-m64), x86_32 (-m32) e x32 (-mx32).

Al fine di una più meticolosa ed estesa verifica della nuova funzionalità,
dovreste considerare l'aggiunta di nuove verifica al progetto 'Linux Test',
oppure al progetto xfstests per cambiamenti relativi al filesystem.

 - https://linux-test-project.github.io/
 - git://git.kernel.org/pub/scm/fs/xfs/xfstests-dev.git

Pagine man
----------

Tutte le nuove chiamate di sistema dovrebbero avere una pagina man completa,
idealmente usando i marcatori groff, ma anche il puro testo può andare.  Se
state usando groff, è utile che includiate nella email di presentazione una
versione già convertita in formato ASCII: semplificherà la vita dei revisori.

Le pagine man dovrebbero essere in copia-conoscenza verso
linux-man@vger.kernel.org
Per maggiori dettagli, leggere
https://www.kernel.org/doc/man-pages/patches.html

Non invocate chiamate di sistema dal kernel
-------------------------------------------

Le chiamate di sistema sono, come già detto prima, punti di interazione fra
lo spazio utente e il kernel.  Perciò, le chiamate di sistema come
``sys_xyzzy()`` o ``compat_sys_xyzzy()`` dovrebbero essere chiamate solo dallo
spazio utente attraverso la tabella syscall, ma non da nessun altro punto nel
kernel.  Se la nuova funzionalità è utile all'interno del kernel, per esempio
dev'essere condivisa fra una vecchia e una nuova chiamata di sistema o
dev'essere utilizzata da una chiamata di sistema e la sua variante compatibile,
allora dev'essere implementata come una funzione di supporto
(*helper function*) (per esempio ``ksys_xyzzy()``).  Questa funzione potrà
essere chiamata dallo *stub* (``sys_xyzzy()``), dalla variante compatibile
(``compat_sys_xyzzy()``), e/o da altri parti del kernel.

Sui sistemi x86 a 64-bit, a partire dalla versione v4.17 è un requisito
fondamentale quello di non invocare chiamate di sistema all'interno del kernel.
Esso usa una diversa convenzione per l'invocazione di chiamate di sistema dove
``struct pt_regs`` viene decodificata al volo in una funzione che racchiude
la chiamata di sistema la quale verrà eseguita successivamente.
Questo significa che verranno passati solo i parametri che sono davvero
necessari ad una specifica chiamata di sistema, invece che riempire ogni volta
6 registri del processore con contenuti presi dallo spazio utente (potrebbe
causare seri problemi nella sequenza di chiamate).

Inoltre, le regole su come i dati possano essere usati potrebbero differire
fra il kernel e l'utente.  Questo è un altro motivo per cui invocare
``sys_xyzzy()`` è generalmente una brutta idea.

Eccezioni a questa regola vengono accettate solo per funzioni d'architetture
che surclassano quelle generiche, per funzioni d'architettura di compatibilità,
o per altro codice in arch/

Riferimenti e fonti
-------------------

 - Articolo di Michael Kerris su LWN sull'uso dell'argomento flags nelle
   chiamate di sistema: https://lwn.net/Articles/585415/
 - Articolo di Michael Kerris su LWN su come gestire flag sconosciuti in
   una chiamata di sistema: https://lwn.net/Articles/588444/
 - Articolo di Jake Edge su LWN che descrive i limiti degli argomenti a 64-bit
   delle chiamate di sistema: https://lwn.net/Articles/311630/
 - Una coppia di articoli di David Drysdale che descrivono i dettagli del
   percorso implementativo di una chiamata di sistema per la versione v3.14:

    - https://lwn.net/Articles/604287/
    - https://lwn.net/Articles/604515/

 - Requisiti specifici alle architetture sono discussi nella pagina man
   :manpage:`syscall(2)` :
   http://man7.org/linux/man-pages/man2/syscall.2.html#NOTES
 - Collezione di email di Linux Torvalds sui problemi relativi a ``ioctl()``:
   http://yarchive.net/comp/linux/ioctl.html
 - "Come non inventare interfacce del kernel", Arnd Bergmann,
   http://www.ukuug.org/events/linux2007/2007/papers/Bergmann.pdf
 - Articolo di Michael Kerris su LWN sull'evitare nuovi usi di CAP_SYS_ADMIN:
   https://lwn.net/Articles/486306/
 - Raccomandazioni da Andrew Morton circa il fatto che tutte le informazioni
   su una nuova chiamata di sistema dovrebbero essere contenute nello stesso
   filone di discussione di email: https://lore.kernel.org/r/20140724144747.3041b208832bbdf9fbce5d96@linux-foundation.org
 - Raccomandazioni da Michael Kerrisk circa il fatto che le nuove chiamate di
   sistema dovrebbero avere una pagina man: https://lore.kernel.org/r/CAKgNAkgMA39AfoSoA5Pe1r9N+ZzfYQNvNPvcRN7tOvRb8+v06Q@mail.gmail.com
 - Consigli da Thomas Gleixner sul fatto che il collegamento all'architettura
   x86 dovrebbe avvenire in un *commit* differente:
   https://lore.kernel.org/r/alpine.DEB.2.11.1411191249560.3909@nanos
 - Consigli da Greg Kroah-Hartman circa la bontà d'avere una pagina man e un
   programma di auto-verifica per le nuove chiamate di sistema:
   https://lore.kernel.org/r/20140320025530.GA25469@kroah.com
 - Discussione di Michael Kerrisk sulle nuove chiamate di sistema contro
   le estensioni :manpage:`prctl(2)`: https://lore.kernel.org/r/CAHO5Pa3F2MjfTtfNxa8LbnkeeU8=YJ+9tDqxZpw7Gz59E-4AUg@mail.gmail.com
 - Consigli da Ingo Molnar che le chiamate di sistema con più argomenti
   dovrebbero incapsularli in una struttura che includa un argomento
   *size* per garantire l'estensibilità futura:
   https://lore.kernel.org/r/20150730083831.GA22182@gmail.com
 - Un certo numero di casi strani emersi dall'uso (riuso) dei flag O_*:

    - commit 75069f2b5bfb ("vfs: renumber FMODE_NONOTIFY and add to uniqueness
      check")
    - commit 12ed2e36c98a ("fanotify: FMODE_NONOTIFY and __O_SYNC in sparc
      conflict")
    - commit bb458c644a59 ("Safer ABI for O_TMPFILE")

 - Discussion from Matthew Wilcox about restrictions on 64-bit arguments:
   https://lore.kernel.org/r/20081212152929.GM26095@parisc-linux.org
 - Raccomandazioni da Greg Kroah-Hartman sul fatto che i flag sconosciuti dovrebbero
   essere controllati: https://lore.kernel.org/r/20140717193330.GB4703@kroah.com
 - Raccomandazioni da Linus Torvalds che le chiamate di sistema x32 dovrebbero
   favorire la compatibilità con le versioni a 64-bit piuttosto che quelle a 32-bit:
   https://lore.kernel.org/r/CA+55aFxfmwfB7jbbrXxa=K7VBYPfAvmu3XOkGrLbB1UFjX1+Ew@mail.gmail.com


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

:Original: :ref:`Documentation/process/applying-patches.rst <applying_patches>`
:Translator: Federico Vaga <federico.vaga@vaga.pv.it>

.. _it_applying_patches:

Applicare patch al kernel Linux
+++++++++++++++++++++++++++++++

.. note::

   Questo documento è obsoleto.  Nella maggior parte dei casi, piuttosto
   che usare ``patch`` manualmente, vorrete usare Git.  Per questo motivo
   il documento non verrà tradotto.


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

:Original: :ref:`Documentation/process/changes.rst <changes>`
:Translator: Federico Vaga <federico.vaga@vaga.pv.it>

.. _it_changes:

Requisiti minimi per compilare il kernel
++++++++++++++++++++++++++++++++++++++++

Introduzione
============

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,
Alessandro Sigala, e tanti altri nella rete).

Requisiti minimi correnti
*************************

Prima di pensare d'avere trovato un baco, aggiornate i seguenti programmi
**almeno** alla versione indicata!  Se non siete certi della versione che state
usando, il comando indicato dovrebbe dirvelo.

Questa lista presume che abbiate già un kernel Linux funzionante.  In aggiunta,
non tutti gli strumenti sono necessari ovunque; ovviamente, se non avete una
PC Card, per esempio, probabilmente non dovreste preoccuparvi di pcmciautils.

====================== =================  ========================================
        Programma       Versione minima       Comando per verificare la versione
====================== =================  ========================================
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
jfsutils               1.1.3              fsck.jfs -V
reiserfsprogs          3.6.3              reiserfsck -V
xfsprogs               2.6.0              xfs_db -V
squashfs-tools         4.0                mksquashfs -version
btrfs-progs            0.18               btrfsck
pcmciautils            004                pccardctl -V
quota-tools            3.09               quota -V
PPP                    2.4.0              pppd --version
nfs-utils              1.0.5              showmount --version
procps                 3.2.0              ps --version
udev                   081                udevd --version
grub                   0.93               grub --version || grub-install --version
mcelog                 0.6                mcelog --version
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

Compilazione del kernel
***********************

GCC
---

La versione necessaria di gcc potrebbe variare a seconda del tipo di CPU nel
vostro calcolatore.

Clang/LLVM (opzionale)
----------------------

L'ultima versione di clang e *LLVM utils* (secondo `releases.llvm.org
<https://releases.llvm.org>`_) sono supportati per la generazione del
kernel. Non garantiamo che anche i rilasci più vecchi funzionino, inoltre
potremmo rimuovere gli espedienti che abbiamo implementato per farli
funzionare. Per maggiori informazioni
:ref:`Building Linux with Clang/LLVM <kbuild_llvm>`.

Make
----

Per compilare il kernel vi servirà GNU make 3.81 o successivo.

Binutils
--------

Per generare il kernel è necessario avere Binutils 2.23 o superiore.

pkg-config
----------

Il sistema di compilazione, dalla versione 4.18, richiede pkg-config per
verificare l'esistenza degli strumenti kconfig e per determinare le
impostazioni da usare in 'make {g,x}config'.  Precedentemente pkg-config
veniva usato ma non verificato o documentato.

Flex
----

Dalla versione 4.16, il sistema di compilazione, durante l'esecuzione, genera
un analizzatore lessicale.  Questo richiede flex 2.5.35 o successivo.

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

Per compilare il kernel vi servirà perl 5 e i seguenti moduli ``Getopt::Long``,
``Getopt::Std``, ``File::Basename``, e ``File::Find``.

BC
--

Vi servirà bc per compilare i kernel dal 3.10 in poi.

OpenSSL
-------

Il programma OpenSSL e la libreria crypto vengono usati per la firma dei moduli
e la gestione dei certificati; sono usati per la creazione della chiave e
la generazione della firma.

Se la firma dei moduli è abilitata, allora vi servirà openssl per compilare il
kernel 3.7 e successivi.  Vi serviranno anche i pacchetti di sviluppo di
openssl per compilare il kernel 4.3 o successivi.

Strumenti di sistema
********************

Modifiche architetturali
------------------------

DevFS è stato reso obsoleto da udev
(http://www.kernel.org/pub/linux/utils/kernel/hotplug/)

Il supporto per UID a 32-bit è ora disponibile.  Divertitevi!

La documentazione delle funzioni in Linux è una fase di transizione
verso una documentazione integrata nei sorgenti stessi usando dei commenti
formattati in modo speciale e posizionati vicino alle funzioni che descrivono.
Al fine di arricchire la documentazione, questi commenti possono essere
combinati con i file ReST presenti in Documentation/; questi potranno
poi essere convertiti in formato PostScript, HTML, LaTex, ePUB o PDF.
Per convertire i documenti da ReST al formato che volete, avete bisogno di
Sphinx.

Util-linux
----------

Le versioni più recenti di util-linux: forniscono il supporto a ``fdisk`` per
dischi di grandi dimensioni; supportano le nuove opzioni di mount; riconoscono
più tipi di partizioni; hanno un fdformat che funziona con i kernel 2.4;
e altre chicche.  Probabilmente vorrete aggiornarlo.

Ksymoops
--------

Se l'impensabile succede e il kernel va in oops, potrebbe servirvi lo strumento
ksymoops per decodificarlo, ma nella maggior parte dei casi non vi servirà.
Generalmente è preferibile compilare il kernel con l'opzione ``CONFIG_KALLSYMS``
cosicché venga prodotto un output più leggibile che può essere usato così com'è
(produce anche un output migliore di ksymoops).  Se per qualche motivo il
vostro kernel non è stato compilato con ``CONFIG_KALLSYMS`` e non avete modo di
ricompilarlo e riprodurre l'oops con quell'opzione abilitata, allora potete
usare ksymoops per decodificare l'oops.

Mkinitrd
--------

I cambiamenti della struttura in ``/lib/modules`` necessita l'aggiornamento di
mkinitrd.

E2fsprogs
---------

L'ultima versione di ``e2fsprogs`` corregge diversi bachi in fsck e debugfs.
Ovviamente, aggiornarlo è una buona idea.

JFSutils
--------

Il pacchetto ``jfsutils`` contiene programmi per il file-system JFS.
Sono disponibili i seguenti strumenti:

- ``fsck.jfs`` - avvia la ripetizione del log delle transizioni, e verifica e
  ripara una partizione formattata secondo JFS

- ``mkfs.jfs`` - crea una partizione formattata secondo JFS

- sono disponibili altri strumenti per il file-system.

Reiserfsprogs
-------------

Il pacchetto reiserfsprogs dovrebbe essere usato con reiserfs-3.6.x (Linux
kernel 2.4.x).  Questo è un pacchetto combinato che contiene versioni
funzionanti di ``mkreiserfs``, ``resize_reiserfs``, ``debugreiserfs`` e
``reiserfsck``.  Questi programmi funzionano sulle piattaforme i386 e alpha.

Xfsprogs
--------

L'ultima versione di ``xfsprogs`` contiene, fra i tanti, i programmi
``mkfs.xfs``, ``xfs_db`` e ``xfs_repair`` per il file-system XFS.
Dipendono dell'architettura e qualsiasi versione dalla 2.0.0 in poi
dovrebbe funzionare correttamente con la versione corrente del codice
XFS nel kernel (sono raccomandate le versioni 2.6.0 o successive per via
di importanti miglioramenti).

PCMCIAutils
-----------

PCMCIAutils sostituisce ``pcmica-cs``.  Serve ad impostare correttamente i
connettori PCMCIA all'avvio del sistema e a caricare i moduli necessari per
i dispositivi a 16-bit se il kernel è stato modularizzato e il sottosistema
hotplug è in uso.

Quota-tools
-----------

Il supporto per uid e gid a 32 bit richiedono l'uso della versione 2 del
formato quota.  La versione 3.07 e successive di quota-tools supportano
questo formato.  Usate la versione raccomandata nella lista qui sopra o una
successiva.

Micro codice per Intel IA32
---------------------------

Per poter aggiornare il micro codice per Intel IA32, è stato aggiunto un
apposito driver; il driver è accessibile come un normale dispositivo a
caratteri (misc).  Se non state usando udev probabilmente sarà necessario
eseguire i seguenti comandi come root prima di poterlo aggiornare::

  mkdir /dev/cpu
  mknod /dev/cpu/microcode c 10 184
  chmod 0644 /dev/cpu/microcode

Probabilmente, vorrete anche il programma microcode_ctl da usare con questo
dispositivo.

udev
----

``udev`` è un programma in spazio utente il cui scopo è quello di popolare
dinamicamente la cartella ``/dev`` coi dispositivi effettivamente presenti.
``udev`` sostituisce le funzionalità base di devfs, consentendo comunque
nomi persistenti per i dispositivi.

FUSE
----

Serve libfuse 2.4.0 o successiva.  Il requisito minimo assoluto è 2.3.0 ma
le opzioni di mount ``direct_io`` e ``kernel_cache`` non funzioneranno.

Rete
****

Cambiamenti generali
--------------------

Se per quanto riguarda la configurazione di rete avete esigenze di un certo
livello dovreste prendere in considerazione l'uso degli strumenti in ip-route2.

Filtro dei pacchetti / NAT
--------------------------

Il codice per filtraggio dei pacchetti e il NAT fanno uso degli stessi
strumenti come nelle versioni del kernel antecedenti la 2.4.x (iptables).
Include ancora moduli di compatibilità per 2.2.x ipchains e 2.0.x ipdwadm.

PPP
---

Il driver per PPP è stato ristrutturato per supportare collegamenti multipli e
per funzionare su diversi livelli.  Se usate PPP, aggiornate pppd almeno alla
versione 2.4.0.

Se non usate udev, dovete avere un file /dev/ppp che può essere creato da root
col seguente comando::

  mknod /dev/ppp c 108 0

NFS-utils
---------

Nei kernel più antichi (2.4 e precedenti), il server NFS doveva essere
informato sui clienti ai quali si voleva fornire accesso via NFS.  Questa
informazione veniva passata al kernel quando un cliente montava un file-system
mediante ``mountd``, oppure usando ``exportfs`` all'avvio del sistema.
exportfs prende le informazioni circa i clienti attivi da ``/var/lib/nfs/rmtab``.

Questo approccio è piuttosto delicato perché dipende dalla correttezza di
rmtab, che non è facile da garantire, in particolare quando si cerca di
implementare un *failover*.  Anche quando il sistema funziona bene, ``rmtab``
ha il problema di accumulare vecchie voci inutilizzate.

Sui kernel più recenti il kernel ha la possibilità di informare mountd quando
arriva una richiesta da una macchina sconosciuta, e mountd può dare al kernel
le informazioni corrette per l'esportazione.  Questo rimuove la dipendenza con
``rmtab`` e significa che il kernel deve essere al corrente solo dei clienti
attivi.

Per attivare questa funzionalità, dovete eseguire il seguente comando prima di
usare exportfs o mountd::

  mount -t nfsd nfsd /proc/fs/nfsd

Dove possibile, raccomandiamo di proteggere tutti i servizi NFS dall'accesso
via internet mediante un firewall.

mcelog
------

Quando ``CONFIG_x86_MCE`` è attivo, il programma mcelog processa e registra
gli eventi *machine check*.  Gli eventi *machine check* sono errori riportati
dalla CPU.  Incoraggiamo l'analisi di questi errori.

Documentazione del kernel
*************************

Sphinx
------

Per i dettaglio sui requisiti di Sphinx, fate riferimento a :ref:`it_sphinx_install`
in :ref:`Documentation/translations/it_IT/doc-guide/sphinx.rst <it_sphinxdoc>`

Ottenere software aggiornato
============================

Compilazione del kernel
***********************

gcc
---

- <ftp://ftp.gnu.org/gnu/gcc/>

Clang/LLVM
----------

- :ref:`Getting LLVM <getting_llvm>`.

Make
----

- <ftp://ftp.gnu.org/gnu/make/>

Binutils
--------

- <https://www.kernel.org/pub/linux/devel/binutils/>

Flex
----

- <https://github.com/westes/flex/releases>

Bison
-----

- <ftp://ftp.gnu.org/gnu/bison/>

OpenSSL
-------

- <https://www.openssl.org/>

Strumenti di sistema
********************

Util-linux
----------

- <https://www.kernel.org/pub/linux/utils/util-linux/>

Kmod
----

- <https://www.kernel.org/pub/linux/utils/kernel/kmod/>
- <https://git.kernel.org/pub/scm/utils/kernel/kmod/kmod.git>

Ksymoops
--------

- <https://www.kernel.org/pub/linux/utils/kernel/ksymoops/v2.4/>

Mkinitrd
--------

- <https://code.launchpad.net/initrd-tools/main>

E2fsprogs
---------

- <https://www.kernel.org/pub/linux/kernel/people/tytso/e2fsprogs/>
- <https://git.kernel.org/pub/scm/fs/ext2/e2fsprogs.git/>

JFSutils
--------

- <http://jfs.sourceforge.net/>

Reiserfsprogs
-------------

- <https://git.kernel.org/pub/scm/linux/kernel/git/jeffm/reiserfsprogs.git/>

Xfsprogs
--------

- <https://git.kernel.org/pub/scm/fs/xfs/xfsprogs-dev.git>
- <https://www.kernel.org/pub/linux/utils/fs/xfs/xfsprogs/>

Pcmciautils
-----------

- <https://www.kernel.org/pub/linux/utils/kernel/pcmcia/>

Quota-tools
-----------

- <http://sourceforge.net/projects/linuxquota/>

Microcodice Intel P6
--------------------

- <https://downloadcenter.intel.com/>

udev
----

- <http://www.freedesktop.org/software/systemd/man/udev.html>

FUSE
----

- <https://github.com/libfuse/libfuse/releases>

mcelog
------

- <http://www.mcelog.org/>

cpio
----

- <https://www.gnu.org/software/cpio/>

Rete
****

PPP
---

- <https://download.samba.org/pub/ppp/>
- <https://git.ozlabs.org/?p=ppp.git>
- <https://github.com/paulusmack/ppp/>

NFS-utils
---------

- <http://sourceforge.net/project/showfiles.php?group_id=14>

Iptables
--------

- <https://netfilter.org/projects/iptables/index.html>

Ip-route2
---------

- <https://www.kernel.org/pub/linux/utils/net/iproute2/>

OProfile
--------

- <http://oprofile.sf.net/download/>

NFS-Utils
---------

- <http://nfs.sourceforge.net/>

Documentazione del kernel
*************************

Sphinx
------

- <http://www.sphinx-doc.org/>


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

:Original: :ref:`Documentation/process/clang-format.rst <clangformat>`
:Translator: Federico Vaga <federico.vaga@vaga.pv.it>

.. _it_clangformat:

clang-format
============
``clang-format`` è uno strumento per formattare codice C/C++/... secondo
un gruppo di regole ed euristiche. Come tutti gli strumenti, non è perfetto
e non copre tutti i singoli casi, ma è abbastanza buono per essere utile.

``clang-format`` può essere usato per diversi fini:

  - Per riformattare rapidamente un blocco di codice secondo lo stile del
    kernel. Particolarmente utile quando si sposta del codice e lo si
    allinea/ordina. Vedere it_clangformatreformat_.

  - Identificare errori di stile, refusi e possibili miglioramenti nei
    file che mantieni, le modifiche che revisioni, le differenze,
    eccetera. Vedere it_clangformatreview_.

  - Ti aiuta a seguire lo stile del codice, particolarmente utile per i
    nuovi arrivati o per coloro che lavorano allo stesso tempo su diversi
    progetti con stili di codifica differenti.

Il suo file di configurazione è ``.clang-format`` e si trova nella cartella
principale dei sorgenti del kernel. Le regole scritte in quel file tentano
di approssimare le lo stile di codifica del kernel. Si tenta anche di seguire
il più possibile
:ref:`Documentation/translations/it_IT/process/coding-style.rst <it_codingstyle>`.
Dato che non tutto il kernel segue lo stesso stile, potreste voler aggiustare
le regole di base per un particolare sottosistema o cartella. Per farlo,
potete sovrascriverle scrivendole in un altro file ``.clang-format`` in
una sottocartella.

Questo strumento è già stato incluso da molto tempo nelle distribuzioni
Linux più popolari. Cercate ``clang-format`` nel vostro repositorio.
Altrimenti, potete scaricare una versione pre-generata dei binari di LLVM/clang
oppure generarlo dai codici sorgenti:

    http://releases.llvm.org/download.html

Troverete più informazioni ai seguenti indirizzi:

    https://clang.llvm.org/docs/ClangFormat.html

    https://clang.llvm.org/docs/ClangFormatStyleOptions.html

.. _it_clangformatreview:

Revisionare lo stile di codifica per file e modifiche
-----------------------------------------------------

Eseguendo questo programma, potrete revisionare un intero sottosistema,
cartella o singoli file alla ricerca di errori di stile, refusi o
miglioramenti.

Per farlo, potete eseguire qualcosa del genere::

    # Make sure your working directory is clean!
    clang-format -i kernel/*.[ch]

E poi date un'occhiata a *git diff*.

Osservare le righe di questo diff è utile a migliorare/aggiustare
le opzioni di stile nel file di configurazione; così come per verificare
le nuove funzionalità/versioni di ``clang-format``.

``clang-format`` è in grado di leggere diversi diff unificati, quindi
potrete revisionare facilmente delle modifiche e *git diff*.
La documentazione si trova al seguente indirizzo:

    https://clang.llvm.org/docs/ClangFormat.html#script-for-patch-reformatting

Per evitare che ``clang-format`` formatti alcune parti di un file, potete
scrivere nel codice::

    int formatted_code;
    // clang-format off
        void    unformatted_code  ;
    // clang-format on
    void formatted_code_again;

Nonostante si attraente l'idea di utilizzarlo per mantenere un file
sempre in sintonia con ``clang-format``, specialmente per file nuovi o
se siete un manutentore, ricordatevi che altre persone potrebbero usare
una versione diversa di ``clang-format`` oppure non utilizzarlo del tutto.
Quindi, dovreste trattenervi dall'usare questi marcatori nel codice del
kernel; almeno finché non vediamo che ``clang-format`` è diventato largamente
utilizzato.

.. _it_clangformatreformat:

Riformattare blocchi di codice
------------------------------

Utilizzando dei plugin per il vostro editor, potete riformattare una
blocco (selezione) di codice con una singola combinazione di tasti.
Questo è particolarmente utile: quando si riorganizza il codice, per codice
complesso, macro multi-riga (e allineare le loro "barre"), eccetera.

Ricordatevi che potete sempre aggiustare le modifiche in quei casi dove
questo strumento non ha fatto un buon lavoro. Ma come prima approssimazione,
può essere davvero molto utile.

Questo programma si integra con molti dei più popolari editor. Alcuni di
essi come vim, emacs, BBEdit, Visaul Studio, lo supportano direttamente.
Al seguente indirizzo troverete le istruzioni:

    https://clang.llvm.org/docs/ClangFormat.html

Per Atom, Eclipse, Sublime Text, Visual Studio Code, XCode e altri editor
e IDEs dovreste essere in grado di trovare dei plugin pronti all'uso.

Per questo caso d'uso, considerate l'uso di un secondo ``.clang-format``
che potete personalizzare con le vostre opzioni.
Consultare it_clangformatextra_.

.. _it_clangformatmissing:

Cose non supportate
-------------------

``clang-format`` non ha il supporto per alcune cose che sono comuni nel
codice del kernel. Sono facili da ricordare; quindi, se lo usate
regolarmente, imparerete rapidamente a evitare/ignorare certi problemi.

In particolare, quelli più comuni che noterete sono:

  - Allineamento di ``#define`` su una singola riga, per esempio::

        #define TRACING_MAP_BITS_DEFAULT       11
        #define TRACING_MAP_BITS_MAX           17
        #define TRACING_MAP_BITS_MIN           7

    contro::

        #define TRACING_MAP_BITS_DEFAULT 11
        #define TRACING_MAP_BITS_MAX 17
        #define TRACING_MAP_BITS_MIN 7

  - Allineamento dei valori iniziali, per esempio::

        static const struct file_operations uprobe_events_ops = {
                .owner          = THIS_MODULE,
                .open           = probes_open,
                .read           = seq_read,
                .llseek         = seq_lseek,
                .release        = seq_release,
                .write          = probes_write,
        };

    contro::

        static const struct file_operations uprobe_events_ops = {
                .owner = THIS_MODULE,
                .open = probes_open,
                .read = seq_read,
                .llseek = seq_lseek,
                .release = seq_release,
                .write = probes_write,
        };

.. _it_clangformatextra:

Funzionalità e opzioni aggiuntive
---------------------------------

Al fine di minimizzare le differenze fra il codice attuale e l'output
del programma, alcune opzioni di stile e funzionalità non sono abilitate
nella configurazione base. In altre parole, lo scopo è di rendere le
differenze le più piccole possibili, permettendo la semplificazione
della revisione di file, differenze e modifiche.

In altri casi (per esempio un particolare sottosistema/cartella/file), lo
stile del kernel potrebbe essere diverso e abilitare alcune di queste
opzioni potrebbe dare risultati migliori.

Per esempio:

  - Allineare assegnamenti (``AlignConsecutiveAssignments``).

  - Allineare dichiarazioni (``AlignConsecutiveDeclarations``).

  - Riorganizzare il testo nei commenti (``ReflowComments``).

  - Ordinare gli ``#include`` (``SortIncludes``).

Piuttosto che per interi file, solitamente sono utili per la riformattazione
di singoli blocchi. In alternativa, potete creare un altro file
``.clang-format`` da utilizzare con il vostro editor/IDE.


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

:Original: :ref:`Documentation/process/code-of-conduct.rst <code_of_conduct>`

.. _it_code_of_conduct:

Accordo dei contributori sul codice di condotta
+++++++++++++++++++++++++++++++++++++++++++++++

.. warning::

    TODO ancora da tradurre