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