1 .. include:: ../disclaimer-ita.rst
3 :Original: :doc:`../../../core-api/symbol-namespaces`
4 :Translator: Federico Vaga <federico.vaga@vaga.pv.it>
6 ===========================
7 Spazio dei nomi dei simboli
8 ===========================
10 Questo documento descrive come usare lo spazio dei nomi dei simboli
11 per strutturare quello che viene esportato internamente al kernel
12 grazie alle macro della famiglia EXPORT_SYMBOL().
17 Lo spazio dei nomi dei simboli è stato introdotto come mezzo per strutturare
18 l'API esposta internamente al kernel. Permette ai manutentori di un
19 sottosistema di organizzare i simboli esportati in diversi spazi di
20 nomi. Questo meccanismo è utile per la documentazione (pensate ad
21 esempio allo spazio dei nomi SUBSYSTEM_DEBUG) così come per limitare
22 la disponibilità di un gruppo di simboli in altre parti del kernel. Ad
23 oggi, i moduli che usano simboli esportati da uno spazio di nomi
24 devono prima importare detto spazio. Altrimenti il kernel, a seconda
25 della configurazione, potrebbe rifiutare di caricare il modulo o
26 avvisare l'utente di un'importazione mancante.
28 2. Come definire uno spazio dei nomi dei simboli
29 ================================================
31 I simboli possono essere esportati in spazi dei nomi usando diversi
32 meccanismi. Tutti questi meccanismi cambiano il modo in cui
33 EXPORT_SYMBOL e simili vengono guidati verso la creazione di voci in ksymtab.
35 2.1 Usare le macro EXPORT_SYMBOL
36 ================================
38 In aggiunta alle macro EXPORT_SYMBOL() e EXPORT_SYMBOL_GPL(), che permettono
39 di esportare simboli del kernel nella rispettiva tabella, ci sono
40 varianti che permettono di esportare simboli all'interno di uno spazio dei
41 nomi: EXPORT_SYMBOL_NS() ed EXPORT_SYMBOL_NS_GPL(). Queste macro richiedono un
42 argomento aggiuntivo: lo spazio dei nomi.
43 Tenete presente che per via dell'espansione delle macro questo argomento deve
44 essere un simbolo di preprocessore. Per esempio per esportare il
45 simbolo ``usb_stor_suspend`` nello spazio dei nomi ``USB_STORAGE`` usate::
47 EXPORT_SYMBOL_NS(usb_stor_suspend, USB_STORAGE);
49 Di conseguenza, nella tabella dei simboli del kernel ci sarà una voce
50 rappresentata dalla struttura ``kernel_symbol`` che avrà il campo
51 ``namespace`` (spazio dei nomi) impostato. Un simbolo esportato senza uno spazio
52 dei nomi avrà questo campo impostato a ``NULL``. Non esiste uno spazio dei nomi
53 di base. Il programma ``modpost`` e il codice in kernel/module/main.c usano lo
54 spazio dei nomi, rispettivamente, durante la compilazione e durante il
55 caricamento di un modulo.
57 2.2 Usare il simbolo di preprocessore DEFAULT_SYMBOL_NAMESPACE
58 ==============================================================
60 Definire lo spazio dei nomi per tutti i simboli di un sottosistema può essere
61 logorante e di difficile manutenzione. Perciò è stato fornito un simbolo
62 di preprocessore di base (DEFAULT_SYMBOL_NAMESPACE), che, se impostato,
63 diventa lo spazio dei simboli di base per tutti gli usi di EXPORT_SYMBOL()
64 ed EXPORT_SYMBOL_GPL() che non specificano esplicitamente uno spazio dei nomi.
66 Ci sono molti modi per specificare questo simbolo di preprocessore e il loro
67 uso dipende dalle preferenze del manutentore di un sottosistema. La prima
68 possibilità è quella di definire il simbolo nel ``Makefile`` del sottosistema.
69 Per esempio per esportare tutti i simboli definiti in usb-common nello spazio
70 dei nomi USB_COMMON, si può aggiungere la seguente linea in
71 drivers/usb/common/Makefile::
73 ccflags-y += -DDEFAULT_SYMBOL_NAMESPACE=USB_COMMON
75 Questo cambierà tutte le macro EXPORT_SYMBOL() ed EXPORT_SYMBOL_GPL(). Invece,
76 un simbolo esportato con EXPORT_SYMBOL_NS() non verrà cambiato e il simbolo
77 verrà esportato nello spazio dei nomi indicato.
79 Una seconda possibilità è quella di definire il simbolo di preprocessore
80 direttamente nei file da compilare. L'esempio precedente diventerebbe::
82 #undef DEFAULT_SYMBOL_NAMESPACE
83 #define DEFAULT_SYMBOL_NAMESPACE USB_COMMON
85 Questo va messo prima di un qualsiasi uso di EXPORT_SYMBOL.
87 3. Come usare i simboli esportati attraverso uno spazio dei nomi
88 ================================================================
90 Per usare i simboli esportati da uno spazio dei nomi, i moduli del
91 kernel devono esplicitamente importare il relativo spazio dei nomi; altrimenti
92 il kernel potrebbe rifiutarsi di caricare il modulo. Il codice del
93 modulo deve usare la macro MODULE_IMPORT_NS per importare lo spazio
94 dei nomi che contiene i simboli desiderati. Per esempio un modulo che
95 usa il simbolo usb_stor_suspend deve importare lo spazio dei nomi
96 USB_STORAGE usando la seguente dichiarazione::
98 MODULE_IMPORT_NS(USB_STORAGE);
100 Questo creerà un'etichetta ``modinfo`` per ogni spazio dei nomi
101 importato. Un risvolto di questo fatto è che gli spazi dei
102 nomi importati da un modulo possono essere ispezionati tramite
105 $ modinfo drivers/usb/storage/ums-karma.ko
107 import_ns: USB_STORAGE
111 Si consiglia di posizionare la dichiarazione MODULE_IMPORT_NS() vicino
112 ai metadati del modulo come MODULE_AUTHOR() o MODULE_LICENSE(). Fate
113 riferimento alla sezione 5. per creare automaticamente le importazioni
116 4. Caricare moduli che usano simboli provenienti da spazi dei nomi
117 ==================================================================
119 Quando un modulo viene caricato (per esempio usando ``insmod``), il kernel
120 verificherà la disponibilità di ogni simbolo usato e se lo spazio dei nomi
121 che potrebbe contenerli è stato importato. Il comportamento di base del kernel
122 è di rifiutarsi di caricare quei moduli che non importano tutti gli spazi dei
123 nomi necessari. L'errore verrà annotato e il caricamento fallirà con l'errore
124 EINVAL. Per caricare i moduli che non soddisfano questo requisito esiste
125 un'opzione di configurazione: impostare
126 MODULE_ALLOW_MISSING_NAMESPACE_IMPORTS=y caricherà i moduli comunque ma
129 5. Creare automaticamente la dichiarazione MODULE_IMPORT_NS
130 ===========================================================
132 La mancanza di un'importazione può essere individuata facilmente al momento
133 della compilazione. Infatti, modpost emetterà un avviso se il modulo usa
134 un simbolo da uno spazio dei nomi che non è stato importato.
135 La dichiarazione MODULE_IMPORT_NS() viene solitamente aggiunta in un posto
136 ben definito (assieme agli altri metadati del modulo). Per facilitare
137 la vita di chi scrive moduli (e i manutentori di sottosistemi), esistono uno
138 script e un target make per correggere le importazioni mancanti. Questo può
143 Lo scenario tipico di chi scrive un modulo potrebbe essere::
145 - scrivere codice che dipende da un simbolo appartenente ad uno spazio
146 dei nomi non importato
148 - aver notato un avviso da modpost che parla di un'importazione
150 - eseguire ``make nsdeps`` per aggiungere import nel posto giusto
152 Per i manutentori di sottosistemi che vogliono aggiungere uno spazio dei nomi,
153 l'approccio è simile. Di nuovo, eseguendo ``make nsdeps`` aggiungerà le
154 importazioni mancanti nei moduli inclusi nel kernel::
156 - spostare o aggiungere simboli ad uno spazio dei nomi (per esempio
157 usando EXPORT_SYMBOL_NS())
158 - eseguire ``make`` (preferibilmente con allmodconfig per coprire tutti
160 - aver notato un avviso da modpost che parla di un'importazione
162 - eseguire ``make nsdeps`` per aggiungere import nel posto giusto
164 Potete anche eseguire nsdeps per moduli esterni. Solitamente si usa così::
166 $ make -C <path_to_kernel_src> M=$PWD nsdeps