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

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