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 13Introduzione 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 27Come 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 34Usare 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 56Usare 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 86Come 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(). 112 113Caricare moduli che usano simboli provenienti da spazi dei nomi 114=============================================================== 115 116Quando un modulo viene caricato (per esempio usando ``insmod``), il kernel 117verificherà la disponibilità di ogni simbolo usato e se lo spazio dei nomi 118che potrebbe contenerli è stato importato. Il comportamento di base del kernel 119è di rifiutarsi di caricare quei moduli che non importano tutti gli spazi dei 120nomi necessari. L'errore verrà annotato e il caricamento fallirà con l'errore 121EINVAL. Per caricare i moduli che non soddisfano questo requisito esiste 122un'opzione di configurazione: impostare 123MODULE_ALLOW_MISSING_NAMESPACE_IMPORTS=y caricherà i moduli comunque ma 124emetterà un avviso. 125 126Creare automaticamente la dichiarazione MODULE_IMPORT_NS 127======================================================== 128 129La mancanza di un'importazione può essere individuata facilmente al momento 130della compilazione. Infatti, modpost emetterà un avviso se il modulo usa 131un simbolo da uno spazio dei nomi che non è stato importato. 132La dichiarazione MODULE_IMPORT_NS() viene solitamente aggiunta in un posto 133ben definito (assieme agli altri metadati del modulo). Per facilitare 134la vita di chi scrive moduli (e i manutentori di sottosistemi), esistono uno 135script e un target make per correggere le importazioni mancanti. Questo può 136essere fatto con:: 137 138 $ make nsdeps 139 140Lo scenario tipico di chi scrive un modulo potrebbe essere:: 141 142 - scrivere codice che dipende da un simbolo appartenente ad uno spazio 143 dei nomi non importato 144 - eseguire ``make`` 145 - aver notato un avviso da modpost che parla di un'importazione 146 mancante 147 - eseguire ``make nsdeps`` per aggiungere import nel posto giusto 148 149Per i manutentori di sottosistemi che vogliono aggiungere uno spazio dei nomi, 150l'approccio è simile. Di nuovo, eseguendo ``make nsdeps`` aggiungerà le 151importazioni mancanti nei moduli inclusi nel kernel:: 152 153 - spostare o aggiungere simboli ad uno spazio dei nomi (per esempio 154 usando EXPORT_SYMBOL_NS()) 155 - eseguire ``make`` (preferibilmente con allmodconfig per coprire tutti 156 i moduli del kernel) 157 - aver notato un avviso da modpost che parla di un'importazione 158 mancante 159 - eseguire ``make nsdeps`` per aggiungere import nel posto giusto 160 161Potete anche eseguire nsdeps per moduli esterni. Solitamente si usa così:: 162 163 $ make -C <path_to_kernel_src> M=$PWD nsdeps 164