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