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