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