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