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é :c:func:`in_irq()`
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:func:`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
630Procedure e convenzioni
631=======================
632
633Liste doppiamente concatenate ``include/linux/list.h``
634------------------------------------------------------
635
636Un tempo negli header del kernel c'erano tre gruppi di funzioni per
637le liste concatenate, ma questa è stata la vincente. Se non avete particolari
638necessità per una semplice lista concatenata, allora questa è una buona scelta.
639
640In particolare, :c:func:`list_for_each_entry()` è utile.
641
642Convenzione dei valori di ritorno
643---------------------------------
644
645Per codice chiamato in contesto utente, è molto comune sfidare le convenzioni
646C e ritornare 0 in caso di successo, ed un codice di errore negativo
647(eg. ``-EFAULT``) nei casi fallimentari. Questo potrebbe essere controintuitivo
648a prima vista, ma è abbastanza diffuso nel kernel.
649
650Utilizzate :c:func:`ERR_PTR()` (``include/linux/err.h``) per codificare
651un numero d'errore negativo in un puntatore, e :c:func:`IS_ERR()` e
652:c:func:`PTR_ERR()` per recuperarlo di nuovo: così si evita d'avere un
653puntatore dedicato per il numero d'errore. Da brividi, ma in senso positivo.
654
655Rompere la compilazione
656-----------------------
657
658Linus e gli altri sviluppatori a volte cambiano i nomi delle funzioni e
659delle strutture nei kernel in sviluppo; questo non è solo per tenere
660tutti sulle spine: questo riflette cambiamenti fondamentati (eg. la funzione
661non può più essere chiamata con le funzioni attive, o fa controlli aggiuntivi,
662o non fa più controlli che venivano fatti in precedenza). Solitamente a questo
663s'accompagna un'adeguata e completa nota sulla lista di discussone
664linux-kernel; cercate negli archivi.
665Solitamente eseguire una semplice sostituzione su tutto un file rendere
666le cose **peggiori**.
667
668Inizializzazione dei campi d'una struttura
669------------------------------------------
670
671Il metodo preferito per l'inizializzazione delle strutture è quello
672di utilizzare gli inizializzatori designati, come definiti nello
673standard ISO C99, eg::
674
675    static struct block_device_operations opt_fops = {
676            .open               = opt_open,
677            .release            = opt_release,
678            .ioctl              = opt_ioctl,
679            .check_media_change = opt_media_change,
680    };
681
682Questo rende più facile la ricerca con grep, e rende più chiaro quale campo
683viene impostato. Dovreste fare così perché si mostra meglio.
684
685Estensioni GNU
686--------------
687
688Le estensioni GNU sono esplicitamente permesse nel kernel Linux. Da notare
689che alcune delle più complesse non sono ben supportate, per via dello scarso
690sviluppo, ma le seguenti sono da considerarsi la norma (per maggiori dettagli,
691leggete la sezione "C Extensions" nella pagina info di GCC - Sì, davvero
692la pagina info, la pagina man è solo un breve riassunto delle cose nella
693pagina info).
694
695-  Funzioni inline
696
697-  Istruzioni in espressioni (ie. il costrutto ({ and }) ).
698
699-  Dichiarate attributi di una funzione / variabile / tipo
700   (__attribute__)
701
702-  typeof
703
704-  Array con lunghezza zero
705
706-  Macro varargs
707
708-  Aritmentica sui puntatori void
709
710-  Inizializzatori non costanti
711
712-  Istruzioni assembler (non al di fuori di 'arch/' e 'include/asm/')
713
714-  Nomi delle funzioni come stringhe (__func__).
715
716-  __builtin_constant_p()
717
718Siate sospettosi quando utilizzate long long nel kernel, il codice generato
719da gcc è orribile ed anche peggio: le divisioni e le moltiplicazioni non
720funzionano sulle piattaforme i386 perché le rispettive funzioni di runtime
721di GCC non sono incluse nell'ambiente del kernel.
722
723C++
724---
725
726Solitamente utilizzare il C++ nel kernel è una cattiva idea perché
727il kernel non fornisce il necessario ambiente di runtime e gli header file
728non sono stati verificati. Rimane comunque possibile, ma non consigliato.
729Se davvero volete usarlo, almeno evitate le eccezioni.
730
731NUMif
732-----
733
734Viene generalmente considerato più pulito l'uso delle macro negli header file
735(o all'inizio dei file .c) per astrarre funzioni piuttosto che utlizzare
736l'istruzione di pre-processore \`#if' all'interno del codice sorgente.
737
738Mettere le vostre cose nel kernel
739=================================
740
741Al fine d'avere le vostre cose in ordine per l'inclusione ufficiale, o
742anche per avere patch pulite, c'è del lavoro amministrativo da fare:
743
744-  Trovare di chi è lo stagno in cui state pisciando. Guardare in cima
745   ai file sorgenti, all'interno del file ``MAINTAINERS``, ed alla fine
746   di tutti nel file ``CREDITS``. Dovreste coordinarvi con queste persone
747   per evitare di duplicare gli sforzi, o provare qualcosa che è già stato
748   rigettato.
749
750   Assicuratevi di mettere il vostro nome ed indirizzo email in cima a
751   tutti i file che create o che mangeggiate significativamente. Questo è
752   il primo posto dove le persone guarderanno quando troveranno un baco,
753   o quando **loro** vorranno fare una modifica.
754
755-  Solitamente vorrete un'opzione di configurazione per la vostra modifica
756   al kernel. Modificate ``Kconfig`` nella cartella giusta. Il linguaggio
757   Config è facile con copia ed incolla, e c'è una completa documentazione
758   nel file ``Documentation/kbuild/kconfig-language.txt``.
759
760   Nella descrizione della vostra opzione, assicuratevi di parlare sia agli
761   utenti esperti sia agli utente che non sanno nulla del vostro lavoro.
762   Menzionate qui le incompatibilità ed i problemi. Chiaramente la
763   descrizione deve terminare con “if in doubt, say N” (se siete in dubbio,
764   dite N) (oppure, occasionalmente, \`Y'); questo è per le persone che non
765   hanno idea di che cosa voi stiate parlando.
766
767-  Modificate il file ``Makefile``: le variabili CONFIG sono esportate qui,
768   quindi potete solitamente aggiungere una riga come la seguete
769   "obj-$(CONFIG_xxx) += xxx.o". La sintassi è documentata nel file
770   ``Documentation/kbuild/makefiles.txt``.
771
772-  Aggiungete voi stessi in ``CREDITS`` se avete fatto qualcosa di notevole,
773   solitamente qualcosa che supera il singolo file (comunque il vostro nome
774   dovrebbe essere all'inizio dei file sorgenti). ``MAINTAINERS`` significa
775   che volete essere consultati quando vengono fatte delle modifiche ad un
776   sottosistema, e quando ci sono dei bachi; questo implica molto di più
777   di un semplice impegno su una parte del codice.
778
779-  Infine, non dimenticatevi di leggere
780   ``Documentation/process/submitting-patches.rst`` e possibilmente anche
781   ``Documentation/process/submitting-drivers.rst``.
782
783Trucchetti del kernel
784=====================
785
786Dopo una rapida occhiata al codice, questi sono i preferiti. Sentitevi liberi
787di aggiungerne altri.
788
789``arch/x86/include/asm/delay.h``::
790
791    #define ndelay(n) (__builtin_constant_p(n) ? \
792            ((n) > 20000 ? __bad_ndelay() : __const_udelay((n) * 5ul)) : \
793            __ndelay(n))
794
795
796``include/linux/fs.h``::
797
798    /*
799     * Kernel pointers have redundant information, so we can use a
800     * scheme where we can return either an error code or a dentry
801     * pointer with the same return value.
802     *
803     * This should be a per-architecture thing, to allow different
804     * error and pointer decisions.
805     */
806     #define ERR_PTR(err)    ((void *)((long)(err)))
807     #define PTR_ERR(ptr)    ((long)(ptr))
808     #define IS_ERR(ptr)     ((unsigned long)(ptr) > (unsigned long)(-1000))
809
810``arch/x86/include/asm/uaccess_32.h:``::
811
812    #define copy_to_user(to,from,n)                         \
813            (__builtin_constant_p(n) ?                      \
814             __constant_copy_to_user((to),(from),(n)) :     \
815             __generic_copy_to_user((to),(from),(n)))
816
817
818``arch/sparc/kernel/head.S:``::
819
820    /*
821     * Sun people can't spell worth damn. "compatability" indeed.
822     * At least we *know* we can't spell, and use a spell-checker.
823     */
824
825    /* Uh, actually Linus it is I who cannot spell. Too much murky
826     * Sparc assembly will do this to ya.
827     */
828    C_LABEL(cputypvar):
829            .asciz "compatibility"
830
831    /* Tested on SS-5, SS-10. Probably someone at Sun applied a spell-checker. */
832            .align 4
833    C_LABEL(cputypvar_sun4m):
834            .asciz "compatible"
835
836
837``arch/sparc/lib/checksum.S:``::
838
839            /* Sun, you just can't beat me, you just can't.  Stop trying,
840             * give up.  I'm serious, I am going to kick the living shit
841             * out of you, game over, lights out.
842             */
843
844
845Ringraziamenti
846==============
847
848Ringrazio Andi Kleen per le sue idee, le risposte alle mie domande,
849le correzioni dei miei errori, l'aggiunta di contenuti, eccetera.
850Philipp Rumpf per l'ortografia e per aver reso più chiaro il testo, e
851per alcuni eccellenti punti tutt'altro che ovvi. Werner Almesberger
852per avermi fornito un ottimo riassunto di :c:func:`disable_irq()`,
853e Jes Sorensen e Andrea Arcangeli per le precisazioni. Michael Elizabeth
854Chastain per aver verificato ed aggiunto la sezione configurazione.
855Telsa Gwynne per avermi insegnato DocBook.
856