Skip to contentSkip to conversation

docs: kbuild: remove ISDN references in Makefile examples

PATCH In review Ethan Nelson-Moore 4 participants 5 messages Jun 13 – Jun 18

Subsystems (2)
lore
Share & tools
lore
#0 lore raw

PATCH 1/1 docs: kbuild: remove ISDN references in Makefile examples

Documentation/kbuild/makefiles.rst uses some extracts from now-removed ISDN code as examples. While they are harmless, they appeared in my checks for CONFIG_* symbols referenced but not defined in the kernel. Replace them with generic examples.

---
 Documentation/kbuild/makefiles.rst | 23 +++++++++--------------
 1 file changed, 9 insertions(+), 14 deletions(-)
Documentation/kbuild/makefiles.rst +9 -14
index 24a4708d26e8..dfac8c9611f4 100644
@@ -127,11 +127,8 @@ controllers are detected, and thus your disks are renumbered.
 
 Example::
 
-  #drivers/isdn/i4l/Makefile
-  # Makefile for the kernel ISDN subsystem and device drivers.
-  # Each configuration option enables a list of files.
-  obj-$(CONFIG_ISDN_I4L)         += isdn.o
-  obj-$(CONFIG_ISDN_PPP_BSDCOMP) += isdn_bsdcomp.o
+  obj-$(CONFIG_FOO) += foo.o
+  obj-$(CONFIG_BAR) += bar.o
 
 Loadable module goals - obj-m
 -----------------------------
@@ -145,10 +142,9 @@ simply adds the file to $(obj-m).
 
 Example::
 
-  #drivers/isdn/i4l/Makefile
-  obj-$(CONFIG_ISDN_PPP_BSDCOMP) += isdn_bsdcomp.o
+  obj-$(CONFIG_FOO) += foo.o
 
-Note: In this example $(CONFIG_ISDN_PPP_BSDCOMP) evaluates to "m"
+Note: In this example $(CONFIG_FOO) evaluates to "m".
 
 If a kernel module is built from several source files, you specify
 that you want to build a module in the same way as above; however,
@@ -158,13 +154,12 @@ variable.
 
 Example::
 
-  #drivers/isdn/i4l/Makefile
-  obj-$(CONFIG_ISDN_I4L) += isdn.o
-  isdn-y := isdn_net_lib.o isdn_v110.o isdn_common.o
+  obj-$(CONFIG_FOO) += foo.o
+  foo-y := foo_1.o foo_2.o foo_3.o
 
-In this example, the module name will be isdn.o. Kbuild will
-compile the objects listed in $(isdn-y) and then run
-``$(LD) -r`` on the list of these files to generate isdn.o.
+In this example, the module name will be foo.o. Kbuild will
+compile the objects listed in $(foo-y) and then run
+``$(LD) -r`` on the list of these files to generate foo.o.
 
 Due to kbuild recognizing $(<module_name>-y) for composite objects,
 you can use the value of a ``CONFIG_`` symbol to optionally include an
Signature · 1 line
2.43.0
#1 lore raw
Quoted 3 lines · Ethan Nelson-Moore

Documentation/kbuild/makefiles.rst uses some extracts from now-removed ISDN code as examples. While they are harmless, they appeared in my checks for CONFIG_* symbols referenced but not defined in the kernel.

Hi Ethan, are you using the kconfig-sym-check[1] that was recently merged? This dead symbol check should not have the false positives on documentation.

Though maybe your check also catches dead symbols in C, Rust, Makefiles?

[1]
https://lore.kernel.org/all/[email protected]/

- Julian Braha

#2 lore raw

Hi, Julian,

Quoted 3 lines · Julian Braha

Hi Ethan, are you using the kconfig-sym-check[1] that was recently merged? This dead symbol check should not have the false positives on documentation.

No, I'm not - I had heard about the Kconfirm project, but not about this similar tool. Thanks for letting me know,

Quoted 1 line

Though maybe your check also catches dead symbols in C, Rust, Makefiles?

Yes, it does; it has orthogonal functionality to kconfig-sym-check, which only operates within Kconfig files.
My script checks for CONFIG_* symbols that are referenced in code or documentation, but that are not defined in any Kconfig file. The decision to include documentation is intentional and has revealed several instances of outdated documentation.
It also filters out symbols that are defined in a Makefile or hardcoded with #define, and also attempts to filter out structs and enums (and typedefs thereof) named CONFIG_*, though I need to improve this further.
I will post it publicly once I have done so.

Ethan

#3 lore raw
In reply to Ethan Nelson-Moore
Quoted 4 lines · Ethan Nelson-Moore

Documentation/kbuild/makefiles.rst uses some extracts from now-removed ISDN code as examples. While they are harmless, they appeared in my checks for CONFIG_* symbols referenced but not defined in the kernel. Replace them with generic examples.

While I am fine with adjusting these examples to make it easier on tools such as yours, how does this solve your problem? CONFIG_FOO and CONFIG_BAR are still not defined anywhere. Are you adding exceptions for these symbols? I ask because I would like these to be a little more "kernel specific" if that makes sense.

Maybe it is not worth even checking Documentation/ for dead configurations at all since that is probably not going to be a bug very often but I guess it helps with cleaning up dead documentation?

Documentation/kbuild/makefiles.rst controllers are detected, and thus your disks are renumbered. · line 132

Quoted 13 lines
Documentation/kbuild/makefiles.rst +0 -3
index 7521cae7d56f..ec8de1c20834 100644
@@ -127,11 +127,8 @@ controllers are detected, and thus your disks are renumbered.
 
 Example::
 
-  #drivers/isdn/i4l/Makefile
-  # Makefile for the kernel ISDN subsystem and device drivers.
-  # Each configuration option enables a list of files.

I think I would keep these comment, it is still relevant (at least to me).

Documentation/kbuild/makefiles.rst controllers are detected, and thus your disks are renumbered. · line 131

Quoted 4 lines
Documentation/kbuild/makefiles.rst +2 -2
-  obj-$(CONFIG_ISDN_I4L)         += isdn.o
-  obj-$(CONFIG_ISDN_PPP_BSDCOMP) += isdn_bsdcomp.o
+  obj-$(CONFIG_FOO) += foo.o
+  obj-$(CONFIG_BAR) += bar.o

For instance, I think using a more descriptive symbol illustrates the example a little better.

  obj-$(CONFIG_DRIVER_ONE) += driver_one.o
  obj-$(CONFIG_DRIVER_TWO) += driver_two.o

Same thing for the other examples. I just don't find these variable names to be particularly good when illustrating actual real world examples as opposed to conceptual ones. Not sure if others feel the same way.

Signature · 2 lines
Cheers,
Nathan
maintainer
#4 lore raw
Quoted 41 lines · Nathan Chancellor
Quoted 4 lines · Ethan Nelson-Moore

Documentation/kbuild/makefiles.rst uses some extracts from now-removed ISDN code as examples. While they are harmless, they appeared in my checks for CONFIG_* symbols referenced but not defined in the kernel. Replace them with generic examples.

While I am fine with adjusting these examples to make it easier on tools such as yours, how does this solve your problem? CONFIG_FOO and CONFIG_BAR are still not defined anywhere. Are you adding exceptions for these symbols? I ask because I would like these to be a little more "kernel specific" if that makes sense.

Maybe it is not worth even checking Documentation/ for dead configurations at all since that is probably not going to be a bug very often but I guess it helps with cleaning up dead documentation?

Documentation/kbuild/makefiles.rst controllers are detected, and thus your disks are renumbered. · line 132

Quoted 13 lines
Documentation/kbuild/makefiles.rst +0 -3
index 7521cae7d56f..ec8de1c20834 100644
@@ -127,11 +127,8 @@ controllers are detected, and thus your disks are renumbered.
 
 Example::
 
-  #drivers/isdn/i4l/Makefile
-  # Makefile for the kernel ISDN subsystem and device drivers.
-  # Each configuration option enables a list of files.

I think I would keep these comment, it is still relevant (at least to me).

Documentation/kbuild/makefiles.rst controllers are detected, and thus your disks are renumbered. · line 131

Quoted 4 lines
Documentation/kbuild/makefiles.rst +2 -2
-  obj-$(CONFIG_ISDN_I4L)         += isdn.o
-  obj-$(CONFIG_ISDN_PPP_BSDCOMP) += isdn_bsdcomp.o
+  obj-$(CONFIG_FOO) += foo.o
+  obj-$(CONFIG_BAR) += bar.o

For instance, I think using a more descriptive symbol illustrates the example a little better.

Quoted 7 lines
  obj-$(CONFIG_DRIVER_ONE) += driver_one.o
  obj-$(CONFIG_DRIVER_TWO) += driver_two.o

Same thing for the other examples. I just don't find these variable names to be particularly good when illustrating actual real world examples as opposed to conceptual ones. Not sure if others feel the same way.

+1

I liked that the examples were taken from actual Linux kconfigs, so it was possible to look them up and check the context as well. So, yes, I think updating these is a good idea!

Kind regards,
Nicolas