Symbol namespace

Symbol namespace의 목적

이 문서는 이탈리아어 공통 면책 고지 `../disclaimer-ita.rst`를 포함하고 공식 원문 `Documentation/core-api/symbol-namespaces.rst`를 가리킵니다. `EXPORT_SYMBOL()` 계열 매크로로 커널 내부에 공개하는 항목을 symbol namespace로 구조화하는 방법을 설명합니다.

Symbol namespace는 커널 내부에 노출되는 API를 정리하기 위해 도입됐습니다. 하위 시스템 유지관리자는 export symbol을 여러 namespace로 분류해 책임 범위와 사용 목적을 드러낼 수 있습니다.

예를 들어 `SUBSYSTEM_DEBUG`처럼 디버그 전용 API를 별도 namespace로 묶으면 문서화가 쉬워지고, 다른 커널 영역에 특정 symbol 그룹이 무분별하게 노출되는 것도 제한할 수 있습니다.

namespace에서 export된 symbol을 쓰는 모듈은 먼저 해당 namespace를 import해야 합니다. import가 없으면 커널 설정에 따라 모듈 로드를 거부하거나 누락 경고를 냅니다.

.. include:: ../disclaimer-ita.rst

:Original: Documentation/core-api/symbol-namespaces.rst

===========================
Spazio dei nomi dei simboli
===========================

Questo documento descrive come usare lo spazio dei nomi dei simboli
per strutturare quello che viene esportato internamente al kernel
grazie alle macro della famiglia EXPORT_SYMBOL().

Introduzione
============

Lo spazio dei nomi dei simboli è stato introdotto come mezzo per strutturare
l'API esposta internamente al kernel. Permette ai manutentori di un
sottosistema di organizzare i simboli esportati in diversi spazi di
nomi. Questo meccanismo è utile per la documentazione (pensate ad
esempio allo spazio dei nomi SUBSYSTEM_DEBUG) così come per limitare
la disponibilità di un gruppo di simboli in altre parti del kernel. Ad
oggi, i moduli che usano simboli esportati da uno spazio di nomi
devono prima importare detto spazio. Altrimenti il kernel, a seconda
della configurazione, potrebbe rifiutare di caricare il modulo o
avvisare l'utente di un'importazione mancante.

EXPORT_SYMBOL_NS()로 명시적 export

Symbol을 namespace로 export하는 방법은 여러 가지지만, 모두 `EXPORT_SYMBOL` 계열이 `ksymtab` 항목을 만드는 방식에 namespace 정보를 추가한다는 공통점이 있습니다.

일반 `EXPORT_SYMBOL()`과 GPL 전용 `EXPORT_SYMBOL_GPL()` 외에 namespace 변형인 `EXPORT_SYMBOL_NS()`와 `EXPORT_SYMBOL_NS_GPL()`이 있습니다. 이 변형은 symbol 뒤에 namespace 인수를 하나 더 받습니다.

매크로 확장 방식 때문에 namespace 인수는 전처리기가 처리할 수 있는 symbol이어야 합니다. 예제는 `usb_stor_suspend`를 `USB_STORAGE` namespace로 export합니다.

simbolo ``usb_stor_suspend`` nello spazio dei nomi ``USB_STORAGE`` usate::

	EXPORT_SYMBOL_NS(usb_stor_suspend, "USB_STORAGE");

그 결과 커널 symbol table의 `kernel_symbol` 구조체 항목에 `namespace` 필드가 설정됩니다. namespace 없이 export한 symbol은 이 필드가 `NULL`이며, 암묵적인 기본 namespace가 존재하는 것은 아닙니다.

`modpost`는 빌드할 때 namespace 정보를 검사하고, `kernel/module/main.c`의 코드는 모듈을 로드할 때 이를 사용합니다.

Come definire uno spazio dei nomi dei simboli
=============================================

I simboli possono essere esportati in spazi dei nomi usando diversi
meccanismi.  Tutti questi meccanismi cambiano il modo in cui
EXPORT_SYMBOL e simili vengono guidati verso la creazione di voci in ksymtab.

Usare le macro EXPORT_SYMBOL
----------------------------

In aggiunta alle macro EXPORT_SYMBOL() e EXPORT_SYMBOL_GPL(), che permettono
di esportare simboli del kernel nella rispettiva tabella, ci sono
varianti che permettono di esportare simboli all'interno di uno spazio dei
nomi: EXPORT_SYMBOL_NS() ed EXPORT_SYMBOL_NS_GPL(). Queste macro richiedono un
argomento aggiuntivo: lo spazio dei nomi.
Tenete presente che per via dell'espansione delle macro questo argomento deve
essere un simbolo di preprocessore. Per esempio per esportare il
simbolo ``usb_stor_suspend`` nello spazio dei nomi ``USB_STORAGE`` usate::

	EXPORT_SYMBOL_NS(usb_stor_suspend, "USB_STORAGE");

Di conseguenza, nella tabella dei simboli del kernel ci sarà una voce
rappresentata dalla struttura ``kernel_symbol`` che avrà il campo
``namespace`` (spazio dei nomi) impostato. Un simbolo esportato senza uno spazio
dei nomi avrà questo campo impostato a ``NULL``. Non esiste uno spazio dei nomi
di base. Il programma ``modpost`` e il codice in kernel/module/main.c usano lo
spazio dei nomi, rispettivamente, durante la compilazione e durante il
caricamento di un modulo.

DEFAULT_SYMBOL_NAMESPACE 설정

하위 시스템의 모든 symbol마다 namespace를 반복해서 쓰면 번거롭고 유지하기 어렵습니다. `DEFAULT_SYMBOL_NAMESPACE` 전처리기 symbol은 명시적 namespace가 없는 `EXPORT_SYMBOL()`과 `EXPORT_SYMBOL_GPL()`에 기본값을 제공합니다.

설정 방법은 유지관리자 선호에 따라 다릅니다. 첫 방법은 하위 시스템 `Makefile`의 compiler flags에서 정의하는 것입니다. `usb-common`의 모든 일반 export를 `USB_COMMON`에 넣는 예는 다음과 같습니다.

possibilità è quella di definire il simbolo nel ``Makefile`` del sottosistema.
Per esempio per esportare tutti i simboli definiti in usb-common nello spazio
dei nomi USB_COMMON, si può aggiungere la seguente linea in
drivers/usb/common/Makefile::

	ccflags-y += -DDEFAULT_SYMBOL_NAMESPACE='"USB_COMMON"'

이 compiler flag는 해당 범위의 `EXPORT_SYMBOL()`과 `EXPORT_SYMBOL_GPL()`을 바꿉니다. 반면 `EXPORT_SYMBOL_NS()`로 namespace를 명시한 symbol은 영향을 받지 않고 지정한 namespace로 export됩니다.

두 번째 방법은 컴파일할 소스 파일에서 전처리기 symbol을 직접 정의하는 것입니다. 기존 정의를 `#undef`한 뒤 `USB_COMMON`으로 다시 정의합니다.

Una seconda possibilità è quella di definire il simbolo di preprocessore
direttamente nei file da compilare. L'esempio precedente diventerebbe::

	#undef  DEFAULT_SYMBOL_NAMESPACE
	#define DEFAULT_SYMBOL_NAMESPACE "USB_COMMON"

Questo va messo prima di un qualsiasi uso di EXPORT_SYMBOL.

이 정의는 파일 안의 어떤 `EXPORT_SYMBOL` 사용보다 먼저 나와야 합니다. 그렇지 않으면 앞선 export에는 기본 namespace가 적용되지 않습니다.

Usare il simbolo di preprocessore DEFAULT_SYMBOL_NAMESPACE
----------------------------------------------------------

Definire lo spazio dei nomi per tutti i simboli di un sottosistema può essere
logorante e di difficile manutenzione. Perciò è stato fornito un simbolo
di preprocessore di base (DEFAULT_SYMBOL_NAMESPACE), che, se impostato,
diventa lo spazio dei simboli di base per tutti gli usi di EXPORT_SYMBOL()
ed EXPORT_SYMBOL_GPL() che non specificano esplicitamente uno spazio dei nomi.

Ci sono molti modi per specificare questo simbolo di preprocessore e il loro
uso dipende dalle preferenze del manutentore di un sottosistema. La prima
possibilità è quella di definire il simbolo nel ``Makefile`` del sottosistema.
Per esempio per esportare tutti i simboli definiti in usb-common nello spazio
dei nomi USB_COMMON, si può aggiungere la seguente linea in
drivers/usb/common/Makefile::

	ccflags-y += -DDEFAULT_SYMBOL_NAMESPACE='"USB_COMMON"'

Questo cambierà tutte le macro EXPORT_SYMBOL() ed EXPORT_SYMBOL_GPL(). Invece,
un simbolo esportato con EXPORT_SYMBOL_NS() non verrà cambiato e il simbolo
verrà esportato nello spazio dei nomi indicato.

Una seconda possibilità è quella di definire il simbolo di preprocessore
direttamente nei file da compilare. L'esempio precedente diventerebbe::

	#undef  DEFAULT_SYMBOL_NAMESPACE
	#define DEFAULT_SYMBOL_NAMESPACE "USB_COMMON"

Questo va messo prima di un qualsiasi uso di EXPORT_SYMBOL.

MODULE_IMPORT_NS()로 symbol 사용

namespace에서 export된 symbol을 사용하려는 커널 모듈은 관련 namespace를 명시적으로 import해야 합니다. 그렇지 않으면 커널이 모듈 로드를 거부할 수 있습니다.

모듈 소스는 `MODULE_IMPORT_NS()` 매크로로 필요한 namespace를 선언합니다. `usb_stor_suspend`를 사용하는 모듈은 `USB_STORAGE`를 다음과 같이 import합니다.

Per usare i simboli esportati da uno spazio dei nomi, i moduli del
kernel devono esplicitamente importare il relativo spazio dei nomi; altrimenti
il kernel potrebbe rifiutarsi di caricare il modulo. Il codice del
modulo deve usare la macro MODULE_IMPORT_NS per importare lo spazio
dei nomi che contiene i simboli desiderati. Per esempio un modulo che
usa il simbolo usb_stor_suspend deve importare lo spazio dei nomi
USB_STORAGE usando la seguente dichiarazione::

	MODULE_IMPORT_NS("USB_STORAGE");

각 import 선언은 모듈에 `modinfo` 태그를 만듭니다. 따라서 빌드된 `.ko` 파일이 import하는 namespace를 `modinfo` 명령으로 확인할 수 있습니다.

Questo creerà un'etichetta ``modinfo`` per ogni spazio dei nomi
importato. Un risvolto di questo fatto è che gli spazi dei
nomi importati da un modulo possono essere ispezionati tramite
modinfo::

	$ modinfo drivers/usb/storage/ums-karma.ko
	[...]
	import_ns:      USB_STORAGE
	[...]

`MODULE_IMPORT_NS()` 선언은 `MODULE_AUTHOR()`나 `MODULE_LICENSE()` 같은 다른 모듈 메타데이터 가까이에 두는 것이 권장됩니다.

Come usare i simboli esportati attraverso uno spazio dei nomi
=============================================================

Per usare i simboli esportati da uno spazio dei nomi, i moduli del
kernel devono esplicitamente importare il relativo spazio dei nomi; altrimenti
il kernel potrebbe rifiutarsi di caricare il modulo. Il codice del
modulo deve usare la macro MODULE_IMPORT_NS per importare lo spazio
dei nomi che contiene i simboli desiderati. Per esempio un modulo che
usa il simbolo usb_stor_suspend deve importare lo spazio dei nomi
USB_STORAGE usando la seguente dichiarazione::

	MODULE_IMPORT_NS("USB_STORAGE");

Questo creerà un'etichetta ``modinfo`` per ogni spazio dei nomi
importato. Un risvolto di questo fatto è che gli spazi dei
nomi importati da un modulo possono essere ispezionati tramite
modinfo::

	$ modinfo drivers/usb/storage/ums-karma.ko
	[...]
	import_ns:      USB_STORAGE
	[...]


Si consiglia di posizionare la dichiarazione MODULE_IMPORT_NS() vicino
ai metadati del modulo come MODULE_AUTHOR() o MODULE_LICENSE().

모듈 로드 시 누락 import 처리

`insmod` 등으로 모듈을 로드하면 커널은 사용한 각 symbol이 존재하는지와 그 symbol의 namespace를 import했는지 확인합니다.

기본 동작은 필요한 모든 namespace를 import하지 않은 모듈의 로드를 거부하는 것입니다. 오류를 로그에 남기고 모듈 로드는 `EINVAL`로 실패합니다.

`MODULE_ALLOW_MISSING_NAMESPACE_IMPORTS=y`로 설정하면 요구 사항을 충족하지 않은 모듈도 로드하지만 누락 경고를 냅니다. 이는 호환 완화 옵션이지 올바른 import 선언을 대체하는 권장 경로가 아닙니다.

Caricare moduli che usano simboli provenienti da spazi dei nomi
===============================================================

Quando un modulo viene caricato (per esempio usando ``insmod``), il kernel
verificherà la disponibilità di ogni simbolo usato e se lo spazio dei nomi
che potrebbe contenerli è stato importato. Il comportamento di base del kernel
è di rifiutarsi di caricare quei moduli che non importano tutti gli spazi dei
nomi necessari. L'errore verrà annotato e il caricamento fallirà con l'errore
EINVAL. Per caricare i moduli che non soddisfano questo requisito esiste
un'opzione di configurazione: impostare
MODULE_ALLOW_MISSING_NAMESPACE_IMPORTS=y caricherà i moduli comunque ma
emetterà un avviso.

make nsdeps 자동 보정

누락 namespace import는 빌드 때 쉽게 찾을 수 있습니다. 모듈이 import하지 않은 namespace의 symbol을 사용하면 `modpost`가 경고를 냅니다.

`MODULE_IMPORT_NS()`는 보통 모듈 메타데이터가 모인 정해진 위치에 추가됩니다. 모듈 작성자와 하위 시스템 유지관리자를 돕기 위해 누락 선언을 고치는 script와 make target이 제공됩니다.

Creare automaticamente la dichiarazione MODULE_IMPORT_NS
========================================================

La mancanza di un'importazione può essere individuata facilmente al momento
della compilazione. Infatti, modpost emetterà un avviso se il modulo usa
un simbolo da uno spazio dei nomi che non è stato importato.
La dichiarazione MODULE_IMPORT_NS() viene solitamente aggiunta in un posto
ben definito (assieme agli altri metadati del modulo). Per facilitare
la vita di chi scrive moduli (e i manutentori di sottosistemi), esistono uno
script e un target make per correggere le importazioni mancanti. Questo può
essere fatto con::

	$ make nsdeps

일반적인 모듈 개발 흐름은 namespace import 없이 symbol을 사용하는 코드를 작성하고 `make`를 실행한 뒤, `modpost`의 누락 import 경고를 확인하고 `make nsdeps`로 적절한 위치에 선언을 추가하는 것입니다.

하위 시스템 유지관리자가 새 namespace를 도입할 때도 흐름은 같습니다. `EXPORT_SYMBOL_NS()` 등으로 symbol을 새 namespace로 이동하거나 추가하고, 가능하면 `allmodconfig`로 모든 커널 모듈을 포함해 빌드한 뒤 `modpost` 경고를 확인하고 `make nsdeps`를 실행합니다.

외부 모듈에도 `nsdeps`를 실행할 수 있습니다. 커널 소스 경로를 `-C`로, 현재 외부 모듈 디렉터리를 `M=$PWD`로 지정합니다.

Potete anche eseguire nsdeps per moduli esterni. Solitamente si usa così::

       $ make -C <path_to_kernel_src> M=$PWD nsdeps

Creare automaticamente la dichiarazione MODULE_IMPORT_NS
========================================================

La mancanza di un'importazione può essere individuata facilmente al momento
della compilazione. Infatti, modpost emetterà un avviso se il modulo usa
un simbolo da uno spazio dei nomi che non è stato importato.
La dichiarazione MODULE_IMPORT_NS() viene solitamente aggiunta in un posto
ben definito (assieme agli altri metadati del modulo). Per facilitare
la vita di chi scrive moduli (e i manutentori di sottosistemi), esistono uno
script e un target make per correggere le importazioni mancanti. Questo può
essere fatto con::

	$ make nsdeps

Lo scenario tipico di chi scrive un modulo potrebbe essere::

	- scrivere codice che dipende da un simbolo appartenente ad uno spazio
	  dei nomi non importato
	- eseguire ``make``
	- aver notato un avviso da modpost che parla di un'importazione
	  mancante
	- eseguire ``make nsdeps`` per aggiungere import nel posto giusto

Per i manutentori di sottosistemi che vogliono aggiungere uno spazio dei nomi,
l'approccio è simile. Di nuovo, eseguendo ``make nsdeps`` aggiungerà le
importazioni mancanti nei moduli inclusi nel kernel::

	- spostare o aggiungere simboli ad uno spazio dei nomi (per esempio
	  usando EXPORT_SYMBOL_NS())
	- eseguire ``make`` (preferibilmente con allmodconfig per coprire tutti
	  i moduli del kernel)
	- aver notato un avviso da modpost che parla di un'importazione
	  mancante
	- eseguire ``make nsdeps`` per aggiungere import nel posto giusto

Potete anche eseguire nsdeps per moduli esterni. Solitamente si usa così::

       $ make -C <path_to_kernel_src> M=$PWD nsdeps