1.. include:: ../disclaimer-ita.rst
2
3.. note:: Per leggere la documentazione originale in inglese:
4	  :ref:`Documentation/kernel-hacking/hacking.rst <kernel_hacking_hack>`
5
6:Original: :ref:`Documentation/kernel-hacking/hacking.rst <kernel_hacking_hack>`
7:Translator: Federico Vaga <federico.vaga@vaga.pv.it>
8
9.. _it_kernel_hacking_hack:
10
11=================================================
12L'inaffidabile guida all'hacking del kernel Linux
13=================================================
14
15:Author: Rusty Russell
16
17Introduzione
18============
19
20Benvenuto, gentile lettore, alla notevole ed inaffidabile guida all'hacking
21del kernel Linux ad opera di Rusty. Questo documento descrive le procedure
22più usate ed i concetti necessari per scrivere codice per il kernel: lo scopo
23è di fornire ai programmatori C più esperti un manuale di base per sviluppo.
24Eviterò dettagli implementativi: per questo abbiamo il codice,
25ed ignorerò intere parti di alcune procedure.
26
27Prima di leggere questa guida, sappiate che non ho mai voluto scriverla,
28essendo esageratamente sotto qualificato, ma ho sempre voluto leggere
29qualcosa di simile, e quindi questa era l'unica via. Spero che possa
30crescere e diventare un compendio di buone pratiche, punti di partenza
31e generiche informazioni.
32
33Gli attori
34==========
35
36In qualsiasi momento ognuna delle CPU di un sistema può essere:
37
38-  non associata ad alcun processo, servendo un'interruzione hardware;
39
40-  non associata ad alcun processo, servendo un softirq o tasklet;
41
42-  in esecuzione nello spazio kernel, associata ad un processo
43   (contesto utente);
44
45-  in esecuzione di un processo nello spazio utente;
46
47Esiste un ordine fra questi casi. Gli ultimi due possono avvicendarsi (preempt)
48l'un l'altro, ma a parte questo esiste una gerarchia rigida: ognuno di questi
49può avvicendarsi solo ad uno di quelli sottostanti. Per esempio, mentre un
50softirq è in esecuzione su d'una CPU, nessun altro softirq può avvicendarsi
51nell'esecuzione, ma un'interruzione hardware può. Ciò nonostante, le altre CPU
52del sistema operano indipendentemente.
53
54Più avanti vedremo alcuni modi in cui dal contesto utente è possibile bloccare
55le interruzioni, così da impedirne davvero il diritto di prelazione.
56
57Contesto utente
58---------------
59
60Ci si trova nel contesto utente quando si arriva da una chiamata di sistema
61od altre eccezioni: come nello spazio utente, altre procedure più importanti,
62o le interruzioni, possono far valere il proprio diritto di prelazione sul
63vostro processo. Potete sospendere l'esecuzione chiamando :c:func:`schedule()`.
64
65.. note::
66
67    Si è sempre in contesto utente quando un modulo viene caricato o rimosso,
68    e durante le operazioni nello strato dei dispositivi a blocchi
69    (*block layer*).
70
71Nel contesto utente, il puntatore ``current`` (il quale indica il processo al
72momento in esecuzione) è valido, e :c:func:`in_interrupt()`
73(``include/linux/preempt.h``) è falsa.
74
75.. warning::
76
77    Attenzione che se avete la prelazione o i softirq disabilitati (vedere
78    di seguito), :c:func:`in_interrupt()` ritornerà un falso positivo.
79
80Interruzioni hardware (Hard IRQs)
81---------------------------------
82
83Temporizzatori, schede di rete e tastiere sono esempi di vero hardware
84che possono produrre interruzioni in un qualsiasi momento. Il kernel esegue
85i gestori d'interruzione che prestano un servizio all'hardware. Il kernel
86garantisce che questi gestori non vengano mai interrotti: se una stessa
87interruzione arriva, questa verrà accodata (o scartata).
88Dato che durante la loro esecuzione le interruzioni vengono disabilitate,
89i gestori d'interruzioni devono essere veloci: spesso si limitano
90esclusivamente a notificare la presa in carico dell'interruzione,
91programmare una 'interruzione software' per l'esecuzione e quindi terminare.
92
93Potete dire d'essere in una interruzione hardware perché in_hardirq()
94ritorna vero.
95
96.. warning::
97
98    Attenzione, questa ritornerà un falso positivo se le interruzioni
99    sono disabilitate (vedere di seguito).
100
101Contesto d'interruzione software: softirq e tasklet
102---------------------------------------------------
103
104Quando una chiamata di sistema sta per tornare allo spazio utente,
105oppure un gestore d'interruzioni termina, qualsiasi 'interruzione software'
106marcata come pendente (solitamente da un'interruzione hardware) viene
107eseguita (``kernel/softirq.c``).
108
109La maggior parte del lavoro utile alla gestione di un'interruzione avviene qui.
110All'inizio della transizione ai sistemi multiprocessore, c'erano solo i
111cosiddetti 'bottom half' (BH), i quali non traevano alcun vantaggio da questi
112sistemi. Non appena abbandonammo i computer raffazzonati con fiammiferi e
113cicche, abbandonammo anche questa limitazione e migrammo alle interruzioni
114software 'softirqs'.
115
116Il file ``include/linux/interrupt.h`` elenca i differenti tipi di 'softirq'.
117Un tipo di softirq molto importante è il timer (``include/linux/timer.h``):
118potete programmarlo per far si che esegua funzioni dopo un determinato
119periodo di tempo.
120
121Dato che i softirq possono essere eseguiti simultaneamente su più di un
122processore, spesso diventa estenuante l'averci a che fare. Per questa ragione,
123i tasklet (``include/linux/interrupt.h``) vengo usati più di frequente:
124possono essere registrati dinamicamente (il che significa che potete averne
125quanti ne volete), e garantiscono che un qualsiasi tasklet verrà eseguito
126solo su un processore alla volta, sebbene diversi tasklet possono essere
127eseguiti simultaneamente.
128
129.. warning::
130
131    Il nome 'tasklet' è ingannevole: non hanno niente a che fare
132    con i 'processi' ('tasks').
133
134Potete determinate se siete in un softirq (o tasklet) utilizzando la
135macro :c:func:`in_softirq()` (``include/linux/preempt.h``).
136
137.. warning::
138
139    State attenti che questa macro ritornerà un falso positivo
140    se :ref:`botton half lock <it_local_bh_disable>` è bloccato.
141
142Alcune regole basilari
143======================
144
145Nessuna protezione della memoria
146    Se corrompete la memoria, che sia in contesto utente o d'interruzione,
147    la macchina si pianterà. Siete sicuri che quello che volete fare
148    non possa essere fatto nello spazio utente?
149
150Nessun numero in virgola mobile o MMX
151    Il contesto della FPU non è salvato; anche se siete in contesto utente
152    lo stato dell'FPU probabilmente non corrisponde a quello del processo
153    corrente: vi incasinerete con lo stato di qualche altro processo. Se
154    volete davvero usare la virgola mobile, allora dovrete salvare e recuperare
155    lo stato dell'FPU (ed evitare cambi di contesto). Generalmente è una
156    cattiva idea; usate l'aritmetica a virgola fissa.
157
158Un limite rigido dello stack
159    A seconda della configurazione del kernel lo stack è fra 3K e 6K per la
160    maggior parte delle architetture a 32-bit; è di 14K per la maggior
161    parte di quelle a 64-bit; e spesso è condiviso con le interruzioni,
162    per cui non si può usare.
163    Evitare profonde ricorsioni ad enormi array locali nello stack
164    (allocateli dinamicamente).
165
166Il kernel Linux è portabile
167    Quindi mantenetelo tale. Il vostro codice dovrebbe essere a 64-bit ed
168    indipendente dall'ordine dei byte (endianess) di un processore. Inoltre,
169    dovreste minimizzare il codice specifico per un processore; per esempio
170    il codice assembly dovrebbe essere incapsulato in modo pulito e minimizzato
171    per facilitarne la migrazione. Generalmente questo codice dovrebbe essere
172    limitato alla parte di kernel specifica per un'architettura.
173
174ioctl: non scrivere nuove chiamate di sistema
175=============================================
176
177Una chiamata di sistema, generalmente, è scritta così::
178
179    asmlinkage long sys_mycall(int arg)
180    {
181            return 0;
182    }
183
184Primo, nella maggior parte dei casi non volete creare nuove chiamate di
185sistema.
186Create un dispositivo a caratteri ed implementate l'appropriata chiamata ioctl.
187Questo meccanismo è molto più flessibile delle chiamate di sistema: esso non
188dev'essere dichiarato in tutte le architetture nei file
189``include/asm/unistd.h`` e ``arch/kernel/entry.S``; inoltre, è improbabile
190che questo venga accettato da Linus.
191
192Se tutto quello che il vostro codice fa è leggere o scrivere alcuni parametri,
193considerate l'implementazione di un'interfaccia :c:func:`sysfs()`.
194
195All'interno di una ioctl vi trovate nel contesto utente di un processo. Quando
196avviene un errore dovete ritornare un valore negativo di errno (consultate
197``include/uapi/asm-generic/errno-base.h``,
198``include/uapi/asm-generic/errno.h`` e ``include/linux/errno.h``), altrimenti
199ritornate 0.
200
201Dopo aver dormito dovreste verificare se ci sono stati dei segnali: il modo
202Unix/Linux di gestire un segnale è di uscire temporaneamente dalla chiamata
203di sistema con l'errore ``-ERESTARTSYS``. La chiamata di sistema ritornerà
204al contesto utente, eseguirà il gestore del segnale e poi la vostra chiamata
205di sistema riprenderà (a meno che l'utente non l'abbia disabilitata). Quindi,
206dovreste essere pronti per continuare l'esecuzione, per esempio nel mezzo
207della manipolazione di una struttura dati.
208
209::
210
211    if (signal_pending(current))
212            return -ERESTARTSYS;
213
214Se dovete eseguire dei calcoli molto lunghi: pensate allo spazio utente.
215Se **davvero** volete farlo nel kernel ricordatevi di verificare periodicamente
216se dovete *lasciare* il processore (ricordatevi che, per ogni processore, c'è
217un sistema multi-processo senza diritto di prelazione).
218Esempio::
219
220    cond_resched(); /* Will sleep */
221
222Una breve nota sulla progettazione delle interfacce: il motto dei sistemi
223UNIX è "fornite meccanismi e non politiche"
224
225La ricetta per uno stallo
226=========================
227
228Non è permesso invocare una procedura che potrebbe dormire, fanno eccezione
229i seguenti casi:
230
231-  Siete in un contesto utente.
232
233-  Non trattenete alcun spinlock.
234
235-  Avete abilitato le interruzioni (in realtà, Andy Kleen dice che
236   lo schedulatore le abiliterà per voi, ma probabilmente questo non è quello
237   che volete).
238
239Da tener presente che alcune funzioni potrebbero dormire implicitamente:
240le più comuni sono quelle per l'accesso allo spazio utente (\*_user) e
241quelle per l'allocazione della memoria senza l'opzione ``GFP_ATOMIC``
242
243Dovreste sempre compilare il kernel con l'opzione ``CONFIG_DEBUG_ATOMIC_SLEEP``
244attiva, questa vi avviserà se infrangete una di queste regole.
245Se **infrangete** le regole, allora potreste bloccare il vostro scatolotto.
246
247Veramente.
248
249Alcune delle procedure più comuni
250=================================
251
252:c:func:`printk()`
253------------------
254
255Definita in ``include/linux/printk.h``
256
257:c:func:`printk()` fornisce messaggi alla console, dmesg, e al demone syslog.
258Essa è utile per il debugging o per la notifica di errori; può essere
259utilizzata anche all'interno del contesto d'interruzione, ma usatela con
260cautela: una macchina che ha la propria console inondata da messaggi diventa
261inutilizzabile. La funzione utilizza un formato stringa quasi compatibile con
262la printf ANSI C, e la concatenazione di una stringa C come primo argomento
263per indicare la "priorità"::
264
265    printk(KERN_INFO "i = %u\n", i);
266
267Consultate ``include/linux/kern_levels.h`` per gli altri valori ``KERN_``;
268questi sono interpretati da syslog come livelli. Un caso speciale:
269per stampare un indirizzo IP usate::
270
271    __be32 ipaddress;
272    printk(KERN_INFO "my ip: %pI4\n", &ipaddress);
273
274
275:c:func:`printk()` utilizza un buffer interno di 1K e non s'accorge di
276eventuali sforamenti. Accertatevi che vi basti.
277
278.. note::
279
280    Saprete di essere un vero hacker del kernel quando inizierete a digitare
281    nei vostri programmi utenti le printf come se fossero printk :)
282
283.. note::
284
285    Un'altra nota a parte: la versione originale di Unix 6 aveva un commento
286    sopra alla funzione printf: "Printf non dovrebbe essere usata per il
287    chiacchiericcio". Dovreste seguire questo consiglio.
288
289:c:func:`copy_to_user()` / :c:func:`copy_from_user()` / :c:func:`get_user()` / :c:func:`put_user()`
290---------------------------------------------------------------------------------------------------
291
292Definite in ``include/linux/uaccess.h`` / ``asm/uaccess.h``
293
294**[DORMONO]**
295
296:c:func:`put_user()` e :c:func:`get_user()` sono usate per ricevere ed
297impostare singoli valori (come int, char, o long) da e verso lo spazio utente.
298Un puntatore nello spazio utente non dovrebbe mai essere dereferenziato: i dati
299dovrebbero essere copiati usando suddette procedure. Entrambe ritornano
300``-EFAULT`` oppure 0.
301
302:c:func:`copy_to_user()` e :c:func:`copy_from_user()` sono più generiche:
303esse copiano una quantità arbitraria di dati da e verso lo spazio utente.
304
305.. warning::
306
307    Al contrario di:c:func:`put_user()` e :c:func:`get_user()`, queste
308    funzioni ritornano la quantità di dati copiati (0 è comunque un successo).
309
310[Sì, questa interfaccia mi imbarazza. La battaglia torna in auge anno
311dopo anno. --RR]
312
313Le funzioni potrebbero dormire implicitamente. Queste non dovrebbero mai essere
314invocate fuori dal contesto utente (non ha senso), con le interruzioni
315disabilitate, o con uno spinlock trattenuto.
316
317:c:func:`kmalloc()`/:c:func:`kfree()`
318-------------------------------------
319
320Definite in ``include/linux/slab.h``
321
322**[POTREBBERO DORMIRE: LEGGI SOTTO]**
323
324Queste procedure sono utilizzate per la richiesta dinamica di un puntatore ad
325un pezzo di memoria allineato, esattamente come malloc e free nello spazio
326utente, ma :c:func:`kmalloc()` ha un argomento aggiuntivo per indicare alcune
327opzioni. Le opzioni più importanti sono:
328
329``GFP_KERNEL``
330    Potrebbe dormire per librarare della memoria. L'opzione fornisce il modo
331    più affidabile per allocare memoria, ma il suo uso è strettamente limitato
332    allo spazio utente.
333
334``GFP_ATOMIC``
335    Non dorme. Meno affidabile di ``GFP_KERNEL``, ma può essere usata in un
336    contesto d'interruzione. Dovreste avere **davvero** una buona strategia
337    per la gestione degli errori in caso di mancanza di memoria.
338
339``GFP_DMA``
340    Alloca memoria per il DMA sul bus ISA nello spazio d'indirizzamento
341    inferiore ai 16MB. Se non sapete cos'è allora non vi serve.
342    Molto inaffidabile.
343
344Se vedete un messaggio d'avviso per una funzione dormiente che viene chiamata
345da un contesto errato, allora probabilmente avete usato una funzione
346d'allocazione dormiente da un contesto d'interruzione senza ``GFP_ATOMIC``.
347Dovreste correggerlo. Sbrigatevi, non cincischiate.
348
349Se allocate almeno ``PAGE_SIZE``(``asm/page.h`` o ``asm/page_types.h``) byte,
350considerate l'uso di :c:func:`__get_free_pages()` (``include/linux/gfp.h``).
351Accetta un argomento che definisce l'ordine (0 per per la dimensione di una
352pagine, 1 per una doppia pagina, 2 per quattro pagine, eccetra) e le stesse
353opzioni d'allocazione viste precedentemente.
354
355Se state allocando un numero di byte notevolemnte superiore ad una pagina
356potete usare :c:func:`vmalloc()`. Essa allocherà memoria virtuale all'interno
357dello spazio kernel. Questo è un blocco di memoria fisica non contiguo, ma
358la MMU vi darà l'impressione che lo sia (quindi, sarà contiguo solo dal punto
359di vista dei processori, non dal punto di vista dei driver dei dispositivi
360esterni).
361Se per qualche strana ragione avete davvero bisogno di una grossa quantità di
362memoria fisica contigua, avete un problema: Linux non ha un buon supporto per
363questo caso d'uso perché, dopo un po' di tempo, la frammentazione della memoria
364rende l'operazione difficile. Il modo migliore per allocare un simile blocco
365all'inizio dell'avvio del sistema è attraverso la procedura
366:c:func:`alloc_bootmem()`.
367
368Prima di inventare la vostra cache per gli oggetti più usati, considerate
369l'uso di una cache slab disponibile in ``include/linux/slab.h``.
370
371:c:macro:`current`
372-------------------
373
374Definita in ``include/asm/current.h``
375
376Questa variabile globale (in realtà una macro) contiene un puntatore alla
377struttura del processo corrente, quindi è valido solo dal contesto utente.
378Per esempio, quando un processo esegue una chiamata di sistema, questo
379punterà alla struttura dati del processo chiamate.
380Nel contesto d'interruzione in suo valore **non è NULL**.
381
382:c:func:`mdelay()`/:c:func:`udelay()`
383-------------------------------------
384
385Definite in ``include/asm/delay.h`` / ``include/linux/delay.h``
386
387Le funzioni :c:func:`udelay()` e :c:func:`ndelay()` possono essere utilizzate
388per brevi pause. Non usate grandi valori perché rischiate d'avere un
389overflow - in questo contesto la funzione :c:func:`mdelay()` è utile,
390oppure considerate :c:func:`msleep()`.
391
392:c:func:`cpu_to_be32()`/:c:func:`be32_to_cpu()`/:c:func:`cpu_to_le32()`/:c:func:`le32_to_cpu()`
393-----------------------------------------------------------------------------------------------
394
395Definite in ``include/asm/byteorder.h``
396
397La famiglia di funzioni :c:func:`cpu_to_be32()` (dove "32" può essere
398sostituito da 64 o 16, e "be" con "le") forniscono un modo generico
399per fare conversioni sull'ordine dei byte (endianess): esse ritornano
400il valore convertito. Tutte le varianti supportano anche il processo inverso:
401:c:func:`be32_to_cpu()`, eccetera.
402
403Queste funzioni hanno principalmente due varianti: la variante per
404puntatori, come :c:func:`cpu_to_be32p()`, che prende un puntatore
405ad un tipo, e ritorna il valore convertito. L'altra variante per
406la famiglia di conversioni "in-situ", come :c:func:`cpu_to_be32s()`,
407che convertono il valore puntato da un puntatore, e ritornano void.
408
409:c:func:`local_irq_save()`/:c:func:`local_irq_restore()`
410--------------------------------------------------------
411
412Definite in ``include/linux/irqflags.h``
413
414Queste funzioni abilitano e disabilitano le interruzioni hardware
415sul processore locale. Entrambe sono rientranti; esse salvano lo stato
416precedente nel proprio argomento ``unsigned long flags``. Se sapete
417che le interruzioni sono abilite, potete semplicemente utilizzare
418:c:func:`local_irq_disable()` e :c:func:`local_irq_enable()`.
419
420.. _it_local_bh_disable:
421
422:c:func:`local_bh_disable()`/:c:func:`local_bh_enable()`
423--------------------------------------------------------
424
425Definite in ``include/linux/bottom_half.h``
426
427
428Queste funzioni abilitano e disabilitano le interruzioni software
429sul processore locale. Entrambe sono rientranti; se le interruzioni
430software erano già state disabilitate in precedenza, rimarranno
431disabilitate anche dopo aver invocato questa coppia di funzioni.
432Lo scopo è di prevenire l'esecuzione di softirq e tasklet sul processore
433attuale.
434
435:c:func:`smp_processor_id()`
436----------------------------
437
438Definita in ``include/linux/smp.h``
439
440:c:func:`get_cpu()` nega il diritto di prelazione (quindi non potete essere
441spostati su un altro processore all'improvviso) e ritorna il numero
442del processore attuale, fra 0 e ``NR_CPUS``. Da notare che non è detto
443che la numerazione dei processori sia continua. Quando avete terminato,
444ritornate allo stato precedente con :c:func:`put_cpu()`.
445
446Se sapete che non dovete essere interrotti da altri processi (per esempio,
447se siete in un contesto d'interruzione, o il diritto di prelazione
448è disabilitato) potete utilizzare smp_processor_id().
449
450
451``__init``/``__exit``/``__initdata``
452------------------------------------
453
454Definite in  ``include/linux/init.h``
455
456Dopo l'avvio, il kernel libera una sezione speciale; le funzioni marcate
457con ``__init`` e le strutture dati marcate con ``__initdata`` vengono
458eliminate dopo il completamento dell'avvio: in modo simile i moduli eliminano
459questa memoria dopo l'inizializzazione. ``__exit`` viene utilizzato per
460dichiarare che una funzione verrà utilizzata solo in fase di rimozione:
461la detta funzione verrà eliminata quando il file che la contiene non è
462compilato come modulo. Guardate l'header file per informazioni. Da notare che
463non ha senso avere una funzione marcata come ``__init`` e al tempo stesso
464esportata ai moduli utilizzando :c:func:`EXPORT_SYMBOL()` o
465:c:func:`EXPORT_SYMBOL_GPL()` - non funzionerà.
466
467
468:c:func:`__initcall()`/:c:func:`module_init()`
469----------------------------------------------
470
471Definite in  ``include/linux/init.h`` / ``include/linux/module.h``
472
473Molte parti del kernel funzionano bene come moduli (componenti del kernel
474caricabili dinamicamente). L'utilizzo delle macro :c:func:`module_init()`
475e :c:func:`module_exit()` semplifica la scrittura di codice che può funzionare
476sia come modulo, sia come parte del kernel, senza l'ausilio di #ifdef.
477
478La macro :c:func:`module_init()` definisce quale funzione dev'essere
479chiamata quando il modulo viene inserito (se il file è stato compilato come
480tale), o in fase di avvio : se il file non è stato compilato come modulo la
481macro :c:func:`module_init()` diventa equivalente a :c:func:`__initcall()`,
482la quale, tramite qualche magia del linker, s'assicura che la funzione venga
483chiamata durante l'avvio.
484
485La funzione può ritornare un numero d'errore negativo per scatenare un
486fallimento del caricamento (sfortunatamente, questo non ha effetto se il
487modulo è compilato come parte integrante del kernel). Questa funzione è chiamata
488in contesto utente con le interruzioni abilitate, quindi potrebbe dormire.
489
490
491:c:func:`module_exit()`
492-----------------------
493
494
495Definita in  ``include/linux/module.h``
496
497Questa macro definisce la funzione che dev'essere chiamata al momento della
498rimozione (o mai, nel caso in cui il file sia parte integrante del kernel).
499Essa verrà chiamata solo quando il contatore d'uso del modulo raggiunge lo
500zero. Questa funzione può anche dormire, ma non può fallire: tutto dev'essere
501ripulito prima che la funzione ritorni.
502
503Da notare che questa macro è opzionale: se non presente, il modulo non sarà
504removibile (a meno che non usiate 'rmmod -f' ).
505
506
507:c:func:`try_module_get()`/:c:func:`module_put()`
508-------------------------------------------------
509
510Definite in ``include/linux/module.h``
511
512Queste funzioni maneggiano il contatore d'uso del modulo per proteggerlo dalla
513rimozione (in aggiunta, un modulo non può essere rimosso se un altro modulo
514utilizzo uno dei sui simboli esportati: vedere di seguito). Prima di eseguire
515codice del modulo, dovreste chiamare :c:func:`try_module_get()` su quel modulo:
516se fallisce significa che il modulo è stato rimosso e dovete agire come se
517non fosse presente. Altrimenti, potete accedere al modulo in sicurezza, e
518chiamare :c:func:`module_put()` quando avete finito.
519
520La maggior parte delle strutture registrabili hanno un campo owner
521(proprietario), come nella struttura
522:c:type:`struct file_operations <file_operations>`.
523Impostate questo campo al valore della macro ``THIS_MODULE``.
524
525
526Code d'attesa ``include/linux/wait.h``
527======================================
528
529**[DORMONO]**
530
531Una coda d'attesa è usata per aspettare che qualcuno vi attivi quando una
532certa condizione s'avvera. Per evitare corse critiche, devono essere usate
533con cautela. Dichiarate una :c:type:`wait_queue_head_t`, e poi i processi
534che vogliono attendere il verificarsi di quella condizione dichiareranno
535una :c:type:`wait_queue_entry_t` facendo riferimento a loro stessi, poi
536metteranno questa in coda.
537
538Dichiarazione
539-------------
540
541Potere dichiarare una ``wait_queue_head_t`` utilizzando la macro
542:c:func:`DECLARE_WAIT_QUEUE_HEAD()` oppure utilizzando la procedura
543:c:func:`init_waitqueue_head()` nel vostro codice d'inizializzazione.
544
545Accodamento
546-----------
547
548Mettersi in una coda d'attesa è piuttosto complesso, perché dovete
549mettervi in coda prima di verificare la condizione. Esiste una macro
550a questo scopo: :c:func:`wait_event_interruptible()` (``include/linux/wait.h``).
551Il primo argomento è la testa della coda d'attesa, e il secondo è
552un'espressione che dev'essere valutata; la macro ritorna 0 quando questa
553espressione è vera, altrimenti ``-ERESTARTSYS`` se è stato ricevuto un segnale.
554La versione :c:func:`wait_event()` ignora i segnali.
555
556Svegliare una procedura in coda
557-------------------------------
558
559Chiamate :c:func:`wake_up()` (``include/linux/wait.h``); questa attiverà tutti
560i processi in coda. Ad eccezione se uno di questi è impostato come
561``TASK_EXCLUSIVE``, in questo caso i rimanenti non verranno svegliati.
562Nello stesso header file esistono altre varianti di questa funzione.
563
564Operazioni atomiche
565===================
566
567Certe operazioni sono garantite come atomiche su tutte le piattaforme.
568Il primo gruppo di operazioni utilizza :c:type:`atomic_t`
569(``include/asm/atomic.h``); questo contiene un intero con segno (minimo 32bit),
570e dovete utilizzare queste funzione per modificare o leggere variabili di tipo
571:c:type:`atomic_t`. :c:func:`atomic_read()` e :c:func:`atomic_set()` leggono ed
572impostano il contatore, :c:func:`atomic_add()`, :c:func:`atomic_sub()`,
573:c:func:`atomic_inc()`, :c:func:`atomic_dec()`, e
574:c:func:`atomic_dec_and_test()` (ritorna vero se raggiunge zero dopo essere
575stata decrementata).
576
577Sì. Ritorna vero (ovvero != 0) se la variabile atomica è zero.
578
579Da notare che queste funzioni sono più lente rispetto alla normale aritmetica,
580e quindi non dovrebbero essere usate a sproposito.
581
582Il secondo gruppo di operazioni atomiche sono definite in
583``include/linux/bitops.h`` ed agiscono sui bit d'una variabile di tipo
584``unsigned long``. Queste operazioni prendono come argomento un puntatore
585alla variabile, e un numero di bit dove 0 è quello meno significativo.
586:c:func:`set_bit()`, :c:func:`clear_bit()` e :c:func:`change_bit()`
587impostano, cancellano, ed invertono il bit indicato.
588:c:func:`test_and_set_bit()`, :c:func:`test_and_clear_bit()` e
589:c:func:`test_and_change_bit()` fanno la stessa cosa, ad eccezione che
590ritornano vero se il bit era impostato; queste sono particolarmente
591utili quando si vuole impostare atomicamente dei flag.
592
593Con queste operazioni è possibile utilizzare indici di bit che eccedono
594il valore ``BITS_PER_LONG``. Il comportamento è strano sulle piattaforme
595big-endian quindi è meglio evitarlo.
596
597Simboli
598=======
599
600All'interno del kernel, si seguono le normali regole del linker (ovvero,
601a meno che un simbolo non venga dichiarato con visibilita limitata ad un
602file con la parola chiave ``static``, esso può essere utilizzato in qualsiasi
603parte del kernel). Nonostante ciò, per i moduli, esiste una tabella dei
604simboli esportati che limita i punti di accesso al kernel. Anche i moduli
605possono esportare simboli.
606
607:c:func:`EXPORT_SYMBOL()`
608-------------------------
609
610Definita in ``include/linux/export.h``
611
612Questo è il classico metodo per esportare un simbolo: i moduli caricati
613dinamicamente potranno utilizzare normalmente il simbolo.
614
615:c:func:`EXPORT_SYMBOL_GPL()`
616-----------------------------
617
618Definita in ``include/linux/export.h``
619
620Essa è simile a :c:func:`EXPORT_SYMBOL()` ad eccezione del fatto che i
621simboli esportati con :c:func:`EXPORT_SYMBOL_GPL()` possono essere
622utilizzati solo dai moduli che hanno dichiarato una licenza compatibile
623con la GPL attraverso :c:func:`MODULE_LICENSE()`. Questo implica che la
624funzione esportata è considerata interna, e non una vera e propria interfaccia.
625Alcuni manutentori e sviluppatori potrebbero comunque richiedere
626:c:func:`EXPORT_SYMBOL_GPL()` quando si aggiungono nuove funzionalità o
627interfacce.
628
629:c:func:`EXPORT_SYMBOL_NS()`
630----------------------------
631
632Definita in ``include/linux/export.h``
633
634Questa è una variate di `EXPORT_SYMBOL()` che permette di specificare uno
635spazio dei nomi. Lo spazio dei nomi è documentato in
636Documentation/translations/it_IT/core-api/symbol-namespaces.rst.
637
638:c:func:`EXPORT_SYMBOL_NS_GPL()`
639--------------------------------
640
641Definita in ``include/linux/export.h``
642
643Questa è una variate di `EXPORT_SYMBOL_GPL()` che permette di specificare uno
644spazio dei nomi. Lo spazio dei nomi è documentato in
645Documentation/translations/it_IT/core-api/symbol-namespaces.rst.
646
647Procedure e convenzioni
648=======================
649
650Liste doppiamente concatenate ``include/linux/list.h``
651------------------------------------------------------
652
653Un tempo negli header del kernel c'erano tre gruppi di funzioni per
654le liste concatenate, ma questa è stata la vincente. Se non avete particolari
655necessità per una semplice lista concatenata, allora questa è una buona scelta.
656
657In particolare, :c:func:`list_for_each_entry()` è utile.
658
659Convenzione dei valori di ritorno
660---------------------------------
661
662Per codice chiamato in contesto utente, è molto comune sfidare le convenzioni
663C e ritornare 0 in caso di successo, ed un codice di errore negativo
664(eg. ``-EFAULT``) nei casi fallimentari. Questo potrebbe essere controintuitivo
665a prima vista, ma è abbastanza diffuso nel kernel.
666
667Utilizzate :c:func:`ERR_PTR()` (``include/linux/err.h``) per codificare
668un numero d'errore negativo in un puntatore, e :c:func:`IS_ERR()` e
669:c:func:`PTR_ERR()` per recuperarlo di nuovo: così si evita d'avere un
670puntatore dedicato per il numero d'errore. Da brividi, ma in senso positivo.
671
672Rompere la compilazione
673-----------------------
674
675Linus e gli altri sviluppatori a volte cambiano i nomi delle funzioni e
676delle strutture nei kernel in sviluppo; questo non è solo per tenere
677tutti sulle spine: questo riflette cambiamenti fondamentati (eg. la funzione
678non può più essere chiamata con le funzioni attive, o fa controlli aggiuntivi,
679o non fa più controlli che venivano fatti in precedenza). Solitamente a questo
680s'accompagna un'adeguata e completa nota sulla lista di discussone
681più adatta; cercate negli archivi. Solitamente eseguire una semplice
682sostituzione su tutto un file rendere le cose **peggiori**.
683
684Inizializzazione dei campi d'una struttura
685------------------------------------------
686
687Il metodo preferito per l'inizializzazione delle strutture è quello
688di utilizzare gli inizializzatori designati, come definiti nello
689standard ISO C99, eg::
690
691    static struct block_device_operations opt_fops = {
692            .open               = opt_open,
693            .release            = opt_release,
694            .ioctl              = opt_ioctl,
695            .check_media_change = opt_media_change,
696    };
697
698Questo rende più facile la ricerca con grep, e rende più chiaro quale campo
699viene impostato. Dovreste fare così perché si mostra meglio.
700
701Estensioni GNU
702--------------
703
704Le estensioni GNU sono esplicitamente permesse nel kernel Linux. Da notare
705che alcune delle più complesse non sono ben supportate, per via dello scarso
706sviluppo, ma le seguenti sono da considerarsi la norma (per maggiori dettagli,
707leggete la sezione "C Extensions" nella pagina info di GCC - Sì, davvero
708la pagina info, la pagina man è solo un breve riassunto delle cose nella
709pagina info).
710
711-  Funzioni inline
712
713-  Istruzioni in espressioni (ie. il costrutto ({ and }) ).
714
715-  Dichiarate attributi di una funzione / variabile / tipo
716   (__attribute__)
717
718-  typeof
719
720-  Array con lunghezza zero
721
722-  Macro varargs
723
724-  Aritmentica sui puntatori void
725
726-  Inizializzatori non costanti
727
728-  Istruzioni assembler (non al di fuori di 'arch/' e 'include/asm/')
729
730-  Nomi delle funzioni come stringhe (__func__).
731
732-  __builtin_constant_p()
733
734Siate sospettosi quando utilizzate long long nel kernel, il codice generato
735da gcc è orribile ed anche peggio: le divisioni e le moltiplicazioni non
736funzionano sulle piattaforme i386 perché le rispettive funzioni di runtime
737di GCC non sono incluse nell'ambiente del kernel.
738
739C++
740---
741
742Solitamente utilizzare il C++ nel kernel è una cattiva idea perché
743il kernel non fornisce il necessario ambiente di runtime e gli header file
744non sono stati verificati. Rimane comunque possibile, ma non consigliato.
745Se davvero volete usarlo, almeno evitate le eccezioni.
746
747NUMif
748-----
749
750Viene generalmente considerato più pulito l'uso delle macro negli header file
751(o all'inizio dei file .c) per astrarre funzioni piuttosto che utlizzare
752l'istruzione di pre-processore \`#if' all'interno del codice sorgente.
753
754Mettere le vostre cose nel kernel
755=================================
756
757Al fine d'avere le vostre cose in ordine per l'inclusione ufficiale, o
758anche per avere patch pulite, c'è del lavoro amministrativo da fare:
759
760-  Trovare chi è responsabile del codice che state modificando. Guardare in cima
761   ai file sorgenti, all'interno del file ``MAINTAINERS``, ed alla fine
762   di tutti nel file ``CREDITS``. Dovreste coordinarvi con queste persone
763   per evitare di duplicare gli sforzi, o provare qualcosa che è già stato
764   rigettato.
765
766   Assicuratevi di mettere il vostro nome ed indirizzo email in cima a
767   tutti i file che create o che maneggiate significativamente. Questo è
768   il primo posto dove le persone guarderanno quando troveranno un baco,
769   o quando **loro** vorranno fare una modifica.
770
771-  Solitamente vorrete un'opzione di configurazione per la vostra modifica
772   al kernel. Modificate ``Kconfig`` nella cartella giusta. Il linguaggio
773   Config è facile con copia ed incolla, e c'è una completa documentazione
774   nel file ``Documentation/kbuild/kconfig-language.rst``.
775
776   Nella descrizione della vostra opzione, assicuratevi di parlare sia agli
777   utenti esperti sia agli utente che non sanno nulla del vostro lavoro.
778   Menzionate qui le incompatibilità ed i problemi. Chiaramente la
779   descrizione deve terminare con “if in doubt, say N” (se siete in dubbio,
780   dite N) (oppure, occasionalmente, \`Y'); questo è per le persone che non
781   hanno idea di che cosa voi stiate parlando.
782
783-  Modificate il file ``Makefile``: le variabili CONFIG sono esportate qui,
784   quindi potete solitamente aggiungere una riga come la seguete
785   "obj-$(CONFIG_xxx) += xxx.o". La sintassi è documentata nel file
786   ``Documentation/kbuild/makefiles.rst``.
787
788-  Aggiungete voi stessi in ``CREDITS`` se credete di aver fatto qualcosa di
789   notevole, solitamente qualcosa che supera il singolo file (comunque il vostro
790   nome dovrebbe essere all'inizio dei file sorgenti). ``MAINTAINERS`` significa
791   che volete essere consultati quando vengono fatte delle modifiche ad un
792   sottosistema, e quando ci sono dei bachi; questo implica molto di più di un
793   semplice impegno su una parte del codice.
794
795-  Infine, non dimenticatevi di leggere
796   ``Documentation/process/submitting-patches.rst``.
797
798Trucchetti del kernel
799=====================
800
801Dopo una rapida occhiata al codice, questi sono i preferiti. Sentitevi liberi
802di aggiungerne altri.
803
804``arch/x86/include/asm/delay.h``::
805
806    #define ndelay(n) (__builtin_constant_p(n) ? \
807            ((n) > 20000 ? __bad_ndelay() : __const_udelay((n) * 5ul)) : \
808            __ndelay(n))
809
810
811``include/linux/fs.h``::
812
813    /*
814     * Kernel pointers have redundant information, so we can use a
815     * scheme where we can return either an error code or a dentry
816     * pointer with the same return value.
817     *
818     * This should be a per-architecture thing, to allow different
819     * error and pointer decisions.
820     */
821     #define ERR_PTR(err)    ((void *)((long)(err)))
822     #define PTR_ERR(ptr)    ((long)(ptr))
823     #define IS_ERR(ptr)     ((unsigned long)(ptr) > (unsigned long)(-1000))
824
825``arch/x86/include/asm/uaccess_32.h:``::
826
827    #define copy_to_user(to,from,n)                         \
828            (__builtin_constant_p(n) ?                      \
829             __constant_copy_to_user((to),(from),(n)) :     \
830             __generic_copy_to_user((to),(from),(n)))
831
832
833``arch/sparc/kernel/head.S:``::
834
835    /*
836     * Sun people can't spell worth damn. "compatability" indeed.
837     * At least we *know* we can't spell, and use a spell-checker.
838     */
839
840    /* Uh, actually Linus it is I who cannot spell. Too much murky
841     * Sparc assembly will do this to ya.
842     */
843    C_LABEL(cputypvar):
844            .asciz "compatibility"
845
846    /* Tested on SS-5, SS-10. Probably someone at Sun applied a spell-checker. */
847            .align 4
848    C_LABEL(cputypvar_sun4m):
849            .asciz "compatible"
850
851
852``arch/sparc/lib/checksum.S:``::
853
854            /* Sun, you just can't beat me, you just can't.  Stop trying,
855             * give up.  I'm serious, I am going to kick the living shit
856             * out of you, game over, lights out.
857             */
858
859
860Ringraziamenti
861==============
862
863Ringrazio Andi Kleen per le sue idee, le risposte alle mie domande,
864le correzioni dei miei errori, l'aggiunta di contenuti, eccetera.
865Philipp Rumpf per l'ortografia e per aver reso più chiaro il testo, e
866per alcuni eccellenti punti tutt'altro che ovvi. Werner Almesberger
867per avermi fornito un ottimo riassunto di :c:func:`disable_irq()`,
868e Jes Sorensen e Andrea Arcangeli per le precisazioni. Michael Elizabeth
869Chastain per aver verificato ed aggiunto la sezione configurazione.
870Telsa Gwynne per avermi insegnato DocBook.
871