Skip to contentSkip to conversation

doc: module: Two clearifications

PATCH Superseded Uwe Kleine-König 4 participants 14 messages Dec 4, 2024 – Dec 30, 2024

Subsystems (2)
Documentation Nsdeps

v1 of 2 Superseded Latest is v2 →

lore
Share & tools
lore

Uwe Kleine-König

author
#0 lore raw

cover doc: module: Two clearifications

Hello,

here come to fixes for the symbol namespace docs around DEFAULT_SYMBOL_NAMESPACE. The first updates the text to say that a namespace has to be a C-string. Before it claimed it should be a preprocessor symbol. I'm not sure how to understand it, but today it's wrong for sure.

Fixes a statement that Andy pointed out to be wrong in the docs while discussing the respective fix in drivers/i2c/busses/i2c-designware-*. (See
https://lore.kernel.org/linux-i2c/[email protected])

Uwe Kleine-König (2):
doc: module: Fix documented type of namespace
doc: module: DEFAULT_SYMBOL_NAMESPACE must be defined before #includes

 Documentation/core-api/symbol-namespaces.rst | 9 ++++-----
 1 file changed, 4 insertions(+), 5 deletions(-)

base-commit: ceb8bf2ceaa77fe222fe8fe32cb7789c9099ddf1

Signature · 1 line
2.45.2
author
#1 lore raw

PATCH 1/2 doc: module: Fix documented type of namespace

Since commit cdd30ebb1b9f ("module: Convert symbol namespace to string literal") the namespace has to be a string. Fix accordingly.

Signed-off-by Uwe Kleine-König <[email protected]>
---
 Documentation/core-api/symbol-namespaces.rst | 5 ++---
 1 file changed, 2 insertions(+), 3 deletions(-)
Documentation/core-api/symbol-namespaces.rst +2 -3
index 27a9cccc792c..a08a3448cbad 100644
@@ -41,9 +41,8 @@ entries.
 In addition to the macros EXPORT_SYMBOL() and EXPORT_SYMBOL_GPL(), that allow
 exporting of kernel symbols to the kernel symbol table, variants of these are
 available to export symbols into a certain namespace: EXPORT_SYMBOL_NS() and
-EXPORT_SYMBOL_NS_GPL(). They take one additional argument: the namespace.
-Please note that due to macro expansion that argument needs to be a
-preprocessor symbol. E.g. to export the symbol ``usb_stor_suspend`` into the
+EXPORT_SYMBOL_NS_GPL(). They take one additional argument: the namespace as a
+C-string. E.g. to export the symbol ``usb_stor_suspend`` into the
 namespace ``USB_STORAGE``, use::
 
 	EXPORT_SYMBOL_NS(usb_stor_suspend, "USB_STORAGE");
Signature · 1 line
2.45.2
#2 lore raw

Re: [PATCH 1/2] doc: module: Fix documented type of namespace

Quoted 2 lines · Uwe Kleine-König

Since commit cdd30ebb1b9f ("module: Convert symbol namespace to string literal") the namespace has to be a string. Fix accordingly.

Interesting. Using preprocessor symbols inherently restricted the namespace syntax to that of C identifiers.

Is it now okay to use any syntax for the namespaces from now on? Should the document have some recommendations for naming namespaces?

BR,
Jani.

Quoted 22 lines
Signed-off-by Uwe Kleine-König <[email protected]>
---
 Documentation/core-api/symbol-namespaces.rst | 5 ++---
 1 file changed, 2 insertions(+), 3 deletions(-)
Documentation/core-api/symbol-namespaces.rst +2 -3
index 27a9cccc792c..a08a3448cbad 100644
@@ -41,9 +41,8 @@ entries.
 In addition to the macros EXPORT_SYMBOL() and EXPORT_SYMBOL_GPL(), that allow
 exporting of kernel symbols to the kernel symbol table, variants of these are
 available to export symbols into a certain namespace: EXPORT_SYMBOL_NS() and
-EXPORT_SYMBOL_NS_GPL(). They take one additional argument: the namespace.
-Please note that due to macro expansion that argument needs to be a
-preprocessor symbol. E.g. to export the symbol ``usb_stor_suspend`` into the
+EXPORT_SYMBOL_NS_GPL(). They take one additional argument: the namespace as a
+C-string. E.g. to export the symbol ``usb_stor_suspend`` into the
 namespace ``USB_STORAGE``, use::
 
 	EXPORT_SYMBOL_NS(usb_stor_suspend, "USB_STORAGE");
Signature · 1 line
Jani Nikula, Intel
#3 lore raw

Re: [PATCH 1/2] doc: module: Fix documented type of namespace

Quoted 10 lines · Jani Nikula
Quoted 2 lines · Uwe Kleine-König

Since commit cdd30ebb1b9f ("module: Convert symbol namespace to string literal") the namespace has to be a string. Fix accordingly.

Interesting. Using preprocessor symbols inherently restricted the namespace syntax to that of C identifiers.

Is it now okay to use any syntax for the namespaces from now on? Should the document have some recommendations for naming namespaces?

I guess the answer is yes except for whitespaces.

The namespaces are recorded in the Module.symvers file,
which is also parsed by external programs like kmod.
Using whitespaces within namespaces may confuse the field separators. Otherwise, the namespace is a simple string matching as far as I can tell.

Signature · 2 lines
Best Regards
Masahiro Yamada
#4 lore raw

Re: [PATCH 1/2] doc: module: Fix documented type of namespace

In reply to Uwe Kleine-König

Documentation/core-api/symbol-namespaces.rst entries. · line 45

Quoted 11 lines · Uwe Kleine-König

Since commit cdd30ebb1b9f ("module: Convert symbol namespace to string literal") the namespace has to be a string. Fix accordingly.

In addition to the macros EXPORT_SYMBOL() and EXPORT_SYMBOL_GPL(), that allow exporting of kernel symbols to the kernel symbol table, variants of these are available to export symbols into a certain namespace: EXPORT_SYMBOL_NS() and

Documentation/core-api/symbol-namespaces.rst +2 -3
-EXPORT_SYMBOL_NS_GPL(). They take one additional argument: the namespace.
-Please note that due to macro expansion that argument needs to be a
-preprocessor symbol. E.g. to export the symbol ``usb_stor_suspend`` into the
+EXPORT_SYMBOL_NS_GPL(). They take one additional argument: the namespace as a
+C-string. E.g. to export the symbol ``usb_stor_suspend`` into the

But C-string is ambiguous. Is it now okay to use

static const char *p = "my constant C-string";

EXPORT_...(, p);

?

Quoted 1 line

namespace ``USB_STORAGE``, use::

Signature · 2 lines
With Best Regards,
Andy Shevchenko
author
#5 lore raw

Re: [PATCH 1/2] doc: module: Fix documented type of namespace

Quoted 15 lines · Andy Shevchenko

Documentation/core-api/symbol-namespaces.rst entries. · line 45

Quoted 11 lines · Uwe Kleine-König

Since commit cdd30ebb1b9f ("module: Convert symbol namespace to string literal") the namespace has to be a string. Fix accordingly.

In addition to the macros EXPORT_SYMBOL() and EXPORT_SYMBOL_GPL(), that allow exporting of kernel symbols to the kernel symbol table, variants of these are available to export symbols into a certain namespace: EXPORT_SYMBOL_NS() and

Documentation/core-api/symbol-namespaces.rst +2 -3
-EXPORT_SYMBOL_NS_GPL(). They take one additional argument: the namespace.
-Please note that due to macro expansion that argument needs to be a
-preprocessor symbol. E.g. to export the symbol ``usb_stor_suspend`` into the
+EXPORT_SYMBOL_NS_GPL(). They take one additional argument: the namespace as a
+C-string. E.g. to export the symbol ``usb_stor_suspend`` into the

But C-string is ambiguous. Is it now okay to use

Quoted 3 lines

static const char *p = "my constant C-string";

EXPORT_...(, p);

I didn't test that, but I guess that won't work. While you could argue that p isn't a C-string but a pointer, I agree that the wording isn't optimal.

So maybe make that:

... the namespace as a string constant.

?

Best regards
Uwe

#6 lore raw

Re: [PATCH 1/2] doc: module: Fix documented type of namespace

Quoted 20 lines · Uwe Kleine-König
Quoted 15 lines · Andy Shevchenko

Documentation/core-api/symbol-namespaces.rst entries. · line 45

Quoted 11 lines · Uwe Kleine-König

Since commit cdd30ebb1b9f ("module: Convert symbol namespace to string literal") the namespace has to be a string. Fix accordingly.

In addition to the macros EXPORT_SYMBOL() and EXPORT_SYMBOL_GPL(), that allow exporting of kernel symbols to the kernel symbol table, variants of these are available to export symbols into a certain namespace: EXPORT_SYMBOL_NS() and

Documentation/core-api/symbol-namespaces.rst +2 -3
-EXPORT_SYMBOL_NS_GPL(). They take one additional argument: the namespace.
-Please note that due to macro expansion that argument needs to be a
-preprocessor symbol. E.g. to export the symbol ``usb_stor_suspend`` into the
+EXPORT_SYMBOL_NS_GPL(). They take one additional argument: the namespace as a
+C-string. E.g. to export the symbol ``usb_stor_suspend`` into the

But C-string is ambiguous. Is it now okay to use

Quoted 3 lines

static const char *p = "my constant C-string";

EXPORT_...(, p);

Quoted 7 lines

I didn't test that, but I guess that won't work. While you could argue that p isn't a C-string but a pointer, I agree that the wording isn't optimal.

So maybe make that:

... the namespace as a string constant.

...a string literal.

?

Quoted 1 line

?

Signature · 2 lines
With Best Regards,
Andy Shevchenko
author
#7 lore raw

Re: [PATCH 1/2] doc: module: Fix documented type of namespace

Quoted 25 lines · Andy Shevchenko
Quoted 24 lines · Uwe Kleine-König
Quoted 15 lines · Andy Shevchenko

Documentation/core-api/symbol-namespaces.rst entries. · line 45

Quoted 11 lines · Uwe Kleine-König

Since commit cdd30ebb1b9f ("module: Convert symbol namespace to string literal") the namespace has to be a string. Fix accordingly.

In addition to the macros EXPORT_SYMBOL() and EXPORT_SYMBOL_GPL(), that allow exporting of kernel symbols to the kernel symbol table, variants of these are available to export symbols into a certain namespace: EXPORT_SYMBOL_NS() and

Documentation/core-api/symbol-namespaces.rst +2 -3
-EXPORT_SYMBOL_NS_GPL(). They take one additional argument: the namespace.
-Please note that due to macro expansion that argument needs to be a
-preprocessor symbol. E.g. to export the symbol ``usb_stor_suspend`` into the
+EXPORT_SYMBOL_NS_GPL(). They take one additional argument: the namespace as a
+C-string. E.g. to export the symbol ``usb_stor_suspend`` into the

But C-string is ambiguous. Is it now okay to use

Quoted 3 lines

static const char *p = "my constant C-string";

EXPORT_...(, p);

I didn't test that, but I guess that won't work. While you could argue that p isn't a C-string but a pointer, I agree that the wording isn't optimal.

Quoted 5 lines
Quoted 3 lines

So maybe make that:

... the namespace as a string constant.

...a string literal.

Gcc calls it "string constant":
https://www.gnu.org/software/gnu-c-manual/gnu-c-manual.html#String-Constants

My C book (https://www.amazon.de/dp/013089592X) also calls it "string constant".

So I tend to keep that name as it seems to be the official term.

Best regards
Uwe

#8 lore raw

Re: [PATCH 1/2] doc: module: Fix documented type of namespace

Quoted 4 lines · Uwe Kleine-König
Quoted 3 lines · Andy Shevchenko
Quoted 2 lines · Uwe Kleine-König
Quoted 1 line · Andy Shevchenko

On Wed, Dec 04, 2024 at 11:01:10AM +0100, Uwe Kleine-König wrote:

...

Quoted 2 lines
Quoted 2 lines
Quoted 2 lines
Quoted 2 lines
Quoted 2 lines

Since commit cdd30ebb1b9f ("module: Convert symbol namespace to string literal") the namespace has to be a string. Fix accordingly.

^^^ (1)

...

Quoted 11 lines
Quoted 3 lines
Quoted 1 line

... the namespace as a string constant.

...a string literal.

Gcc calls it "string constant":
https://www.gnu.org/software/gnu-c-manual/gnu-c-manual.html#String-Constants

My C book (https://www.amazon.de/dp/013089592X) also calls it "string constant".

So I tend to keep that name as it seems to be the official term.

Even though we should be more consistent with the de facto usages, no?

(see (1) above, for example).

Signature · 2 lines
With Best Regards,
Andy Shevchenko
#9 lore raw

Re: [PATCH 1/2] doc: module: Fix documented type of namespace

In reply to Uwe Kleine-König
Quoted 33 lines · Uwe Kleine-König
Quoted 25 lines · Andy Shevchenko
Quoted 24 lines · Uwe Kleine-König
Quoted 15 lines · Andy Shevchenko

Documentation/core-api/symbol-namespaces.rst entries. · line 45

Quoted 11 lines · Uwe Kleine-König

Since commit cdd30ebb1b9f ("module: Convert symbol namespace to string literal") the namespace has to be a string. Fix accordingly.

In addition to the macros EXPORT_SYMBOL() and EXPORT_SYMBOL_GPL(), that allow exporting of kernel symbols to the kernel symbol table, variants of these are available to export symbols into a certain namespace: EXPORT_SYMBOL_NS() and

Documentation/core-api/symbol-namespaces.rst +2 -3
-EXPORT_SYMBOL_NS_GPL(). They take one additional argument: the namespace.
-Please note that due to macro expansion that argument needs to be a
-preprocessor symbol. E.g. to export the symbol ``usb_stor_suspend`` into the
+EXPORT_SYMBOL_NS_GPL(). They take one additional argument: the namespace as a
+C-string. E.g. to export the symbol ``usb_stor_suspend`` into the

But C-string is ambiguous. Is it now okay to use

Quoted 3 lines

static const char *p = "my constant C-string";

EXPORT_...(, p);

I didn't test that, but I guess that won't work. While you could argue that p isn't a C-string but a pointer, I agree that the wording isn't optimal.

Quoted 5 lines
Quoted 3 lines

So maybe make that:

... the namespace as a string constant.

...a string literal.

Quoted 7 lines

Gcc calls it "string constant":
https://www.gnu.org/software/gnu-c-manual/gnu-c-manual.html#String-Constants

My C book (https://www.amazon.de/dp/013089592X) also calls it "string constant".

So I tend to keep that name as it seems to be the official term.

But, you do not call it a "C-string".

EXPORT_SYMBOL_NS() is expanded into assembly code.

See:
.asciz ns

So, will you send v2 with "string constant" or "string literal"? (I think either is fine.)

Signature · 2 lines
Best Regards
Masahiro Yamada
author
#10 lore raw

PATCH 2/2 doc: module: DEFAULT_SYMBOL_NAMESPACE must be defined before #includes

In reply to Uwe Kleine-König

The definition of EXPORT_SYMBOL et al depends on DEFAULT_SYMBOL_NAMESPACE. So DEFAULT_SYMBOL_NAMESPACE must already be available when <linux/export.h> is parsed.

Reported-by Andy Shevchenko <[email protected]>
Link https://lore.kernel.org/linux-i2c/[email protected]/ open here
Signed-off-by Uwe Kleine-König <[email protected]>
---
 Documentation/core-api/symbol-namespaces.rst | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)
Documentation/core-api/symbol-namespaces.rst +2 -2
index a08a3448cbad..d63e4245a9f5 100644
@@ -80,8 +80,8 @@ unit as preprocessor statement. The above example would then read::
 	#undef  DEFAULT_SYMBOL_NAMESPACE
 	#define DEFAULT_SYMBOL_NAMESPACE "USB_COMMON"
 
-within the corresponding compilation unit before any EXPORT_SYMBOL macro is
-used.
+within the corresponding compilation unit before the #include for
+<linux/export.h>.
 
 3. How to use Symbols exported in Namespaces
 ============================================
Signature · 1 line
2.45.2
#11 lore raw

Re: [PATCH 2/2] doc: module: DEFAULT_SYMBOL_NAMESPACE must be defined before #includes

Documentation/core-api/symbol-namespaces.rst unit as preprocessor statement. The above example would then read:: · line 84

Quoted 8 lines · Uwe Kleine-König

The definition of EXPORT_SYMBOL et al depends on DEFAULT_SYMBOL_NAMESPACE. So DEFAULT_SYMBOL_NAMESPACE must already be available when <linux/export.h> is parsed.

Documentation/core-api/symbol-namespaces.rst +2 -2
-within the corresponding compilation unit before any EXPORT_SYMBOL macro is
-used.
+within the corresponding compilation unit before the #include for
+<linux/export.h>.

And how do I know where it is included in the current state of affairs with the dependency hell in the kernel?

I suggest to reword it to something like "before any global inclusions", the best probably is to repeat the piece from pr_fmt() / dev_fmt() documentation (if any).

Signature · 2 lines
With Best Regards,
Andy Shevchenko
author
#12 lore raw

Re: [PATCH 2/2] doc: module: DEFAULT_SYMBOL_NAMESPACE must be defined before #includes

Hello Andy,

Quoted 13 lines · Andy Shevchenko

Documentation/core-api/symbol-namespaces.rst unit as preprocessor statement. The above example would then read:: · line 84

Quoted 8 lines · Uwe Kleine-König

The definition of EXPORT_SYMBOL et al depends on DEFAULT_SYMBOL_NAMESPACE. So DEFAULT_SYMBOL_NAMESPACE must already be available when <linux/export.h> is parsed.

Documentation/core-api/symbol-namespaces.rst +2 -2
-within the corresponding compilation unit before any EXPORT_SYMBOL macro is
-used.
+within the corresponding compilation unit before the #include for
+<linux/export.h>.

And how do I know where it is included in the current state of affairs with the dependency hell in the kernel?

Quoted 3 lines

I suggest to reword it to something like "before any global inclusions", the best probably is to repeat the piece from pr_fmt() / dev_fmt() documentation (if any).

Well, "before <linux/export.h>" is the accurate thing you have to ensure. "before any global inclusion" is the safe and easy thing to do to achieve that. Maybe:

	...
	within the corresponding compilation unit before the #include for
	<linux/export.h>. Typically it's placed before the first
	#include.

?

Best regards
Uwe

#13 lore raw

Re: [PATCH 2/2] doc: module: DEFAULT_SYMBOL_NAMESPACE must be defined before #includes

Quoted 20 lines · Uwe Kleine-König

Hello Andy,

Quoted 13 lines · Andy Shevchenko

Documentation/core-api/symbol-namespaces.rst unit as preprocessor statement. The above example would then read:: · line 84

Quoted 8 lines · Uwe Kleine-König

The definition of EXPORT_SYMBOL et al depends on DEFAULT_SYMBOL_NAMESPACE. So DEFAULT_SYMBOL_NAMESPACE must already be available when <linux/export.h> is parsed.

Documentation/core-api/symbol-namespaces.rst +2 -2
-within the corresponding compilation unit before any EXPORT_SYMBOL macro is
-used.
+within the corresponding compilation unit before the #include for
+<linux/export.h>.

And how do I know where it is included in the current state of affairs with the dependency hell in the kernel?

Quoted 3 lines

I suggest to reword it to something like "before any global inclusions", the best probably is to repeat the piece from pr_fmt() / dev_fmt() documentation (if any).

Quoted 8 lines

Well, "before <linux/export.h>" is the accurate thing you have to ensure. "before any global inclusion" is the safe and easy thing to do to achieve that. Maybe:

	...
	within the corresponding compilation unit before the #include for
	<linux/export.h>. Typically it's placed before the first
	#include.

The below is excerpt for pr_fmt():

---8>----
Besides being more concise than the equivalent printk() calls, they can use a common definition for the format string through the pr_fmt() macro. For instance, defining this at the top of a source file (before any ``#include`` directive)::

  #define pr_fmt(fmt) "%s:%s: " fmt, KBUILD_MODNAME, __func__

---8>----

Quoted 1 line

?

Signature · 2 lines
With Best Regards,
Andy Shevchenko