Documentation/translations/it_IT/core-api/symbol-namespaces.rst

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