kernel/linux.git/Documentation/kbuild, branch v6.12.80

kbuild: rust: add rustc-min-version support function

2025-06-27T10:11:40+00:00

commit ac954145e1ee3f72033161cbe4ac0b16b5354ae7 upstream. Introduce `rustc-min-version` support function that mimics `{gcc,clang}-min-version` ones, following commit 88b61e3bff93 ("Makefile.compiler: replace cc-ifversion with compiler-specific macros"). In addition, use it in the first use case we have in the kernel (which was done independently to minimize the changes needed for the fix). Signed-off-by: Miguel Ojeda Reviewed-by: Fiona Behrens Reviewed-by: Nicolas Schier Signed-off-by: Masahiro Yamada Signed-off-by: Miguel Ojeda Signed-off-by: Greg Kroah-Hartman

kbuild: doc: replace "gcc" in external module description

2024-09-23T18:07:21+00:00

Avoid "gcc" since it is not the only compiler supported by Kbuild. Signed-off-by: Masahiro Yamada Reviewed-by: Nicolas Schier

kbuild: doc: describe the -C option precisely for external module builds

2024-09-23T18:07:21+00:00

Building external modules is typically done using this command: $ make -C M= Here, refers to the output directory where the kernel was built, not the kernel source directory. When the kernel is built in the source tree, there is no ambiguity, as the output directory and the source directory are the same. If the kernel was built in a separate build directory, should be the kernel output directory. Otherwise, Kbuild cannot locate necessary build artifacts. This has been the method for building external modules against a pre-built kernel in a separate directory for over 20 years. [1] If you pass the kernel source directory to the -C option, you must also specify the kernel build directory using the O= option. This approach works as well, though it results in a slightly longer command: $ make -C O= M= Some people mistakenly believe that O= should specify a build directory for external modules when used together with M=. This commit adds more clarification to Documentation/kbuild/kbuild.rst. [1]: https://git.kernel.org/pub/scm/linux/kernel/git/history/history.git/commit/?id=e321b2ec2eb2993b3d0116e5163c78ad923e3c54 Signed-off-by: Masahiro Yamada Reviewed-by: Nicolas Schier

kbuild: doc: remove the description about shipped files

2024-09-23T18:07:21+00:00

The use of shipped files is discouraged in the upstream kernel these days. [1] Downstream Makefiles have the freedom to use shipped files or other options to handle binaries, but this should not be advertised in the upstream document. [1]: https://lore.kernel.org/all/CAHk-=wgSEi_ZrHdqr=20xv+d6dr5G895CbOAi8ok+7-CQUN=fQ@mail.gmail.com/ Signed-off-by: Masahiro Yamada Reviewed-by: Nicolas Schier

kbuild: doc: drop section numbering, use references in modules.rst

2024-09-23T18:07:21+00:00

Do similar to commit 1a4c1c9df72e ("docs/kbuild/makefiles: drop section numbering, use references"). Signed-off-by: Masahiro Yamada

kbuild: doc: throw out the local table of contents in modules.rst

2024-09-23T18:07:21+00:00

Do similar to commit 5e8f0ba38a4d ("docs/kbuild/makefiles: throw out the local table of contents"). Signed-off-by: Masahiro Yamada

kbuild: doc: remove outdated description of the limitation on -I usage

2024-09-23T18:07:21+00:00

Kbuild used to manipulate header search paths, enforcing the odd limitation of "no space after -I". Commit cdd750bfb1f7 ("kbuild: remove 'addtree' and 'flags' magic for header search paths") stopped doing that. This limitation no longer exists. Instead, you need to accurately specify the header search path. (In this case, $(src)/include) Signed-off-by: Masahiro Yamada Reviewed-by: Nicolas Schier

kbuild: doc: remove description about grepping CONFIG options

2024-09-23T18:07:20+00:00

This description was added 20 years ago [1]. It does not convey any useful information except for a feeling of nostalgia. [1]: https://git.kernel.org/pub/scm/linux/kernel/git/history/history.git/commit/?id=65e433436b5794ae056d22ddba60fe9194bba007 Signed-off-by: Masahiro Yamada Reviewed-by: Nicolas Schier

kbuild: doc: update the description about Kbuild/Makefile split

2024-09-23T18:07:20+00:00

The phrase "In newer versions of the kernel" was added 14 years ago, by commit efdf02cf0651 ("Documentation/kbuild: major edit of modules.txt sections 1-4"). This feature is no longer new, so remove it and update the paragraph. Example 3 was written 20 years ago [1]. There is no need to note about backward compatibility with such an old build system. Remove Example 3 entirely. [1]: https://git.kernel.org/pub/scm/linux/kernel/git/history/history.git/commit/?id=65e433436b5794ae056d22ddba60fe9194bba007 Signed-off-by: Masahiro Yamada Reviewed-by: Nicolas Schier

kbuild: generate offset range data for builtin modules

2024-09-20T00:21:43+00:00

Create file module.builtin.ranges that can be used to find where built-in modules are located by their addresses. This will be useful for tracing tools to find what functions are for various built-in modules. The offset range data for builtin modules is generated using: - modules.builtin: associates object files with module names - vmlinux.map: provides load order of sections and offset of first member per section - vmlinux.o.map: provides offset of object file content per section - .*.cmd: build cmd file with KBUILD_MODFILE The generated data will look like: .text 00000000-00000000 = _text .text 0000baf0-0000cb10 amd_uncore .text 0009bd10-0009c8e0 iosf_mbi ... .text 00b9f080-00ba011a intel_skl_int3472_discrete .text 00ba0120-00ba03c0 intel_skl_int3472_discrete intel_skl_int3472_tps68470 .text 00ba03c0-00ba08d6 intel_skl_int3472_tps68470 ... .data 00000000-00000000 = _sdata .data 0000f020-0000f680 amd_uncore For each ELF section, it lists the offset of the first symbol. This can be used to determine the base address of the section at runtime. Next, it lists (in strict ascending order) offset ranges in that section that cover the symbols of one or more builtin modules. Multiple ranges can apply to a single module, and ranges can be shared between modules. The CONFIG_BUILTIN_MODULE_RANGES option controls whether offset range data is generated for kernel modules that are built into the kernel image. How it works: 1. The modules.builtin file is parsed to obtain a list of built-in module names and their associated object names (the .ko file that the module would be in if it were a loadable module, hereafter referred to as ). This object name can be used to identify objects in the kernel compile because any C or assembler code that ends up into a built-in module will have the option -DKBUILD_MODFILE= present in its build command, and those can be found in the ..cmd file in the kernel build tree. If an object is part of multiple modules, they will all be listed in the KBUILD_MODFILE option argument. This allows us to conclusively determine whether an object in the kernel build belong to any modules, and which. 2. The vmlinux.map is parsed next to determine the base address of each top level section so that all addresses into the section can be turned into offsets. This makes it possible to handle sections getting loaded at different addresses at system boot. We also determine an 'anchor' symbol at the beginning of each section to make it possible to calculate the true base address of a section at runtime (i.e. symbol address - symbol offset). We collect start addresses of sections that are included in the top level section. This is used when vmlinux is linked using vmlinux.o, because in that case, we need to look at the vmlinux.o linker map to know what object a symbol is found in. And finally, we process each symbol that is listed in vmlinux.map (or vmlinux.o.map) based on the following structure: vmlinux linked from vmlinux.a: vmlinux.map: -- might be same as top level section) -- built-in association known -- belongs to module(s) object belongs to ... vmlinux linked from vmlinux.o: vmlinux.map: -- might be same as top level section) vmlinux.o -- need to use vmlinux.o.map -- ignored ... vmlinux.o.map:

-- built-in association known -- belongs to module(s) object belongs to ... 3. As sections, objects, and symbols are processed, offset ranges are constructed in a straight-forward way: - If the symbol belongs to one or more built-in modules: - If we were working on the same module(s), extend the range to include this object - If we were working on another module(s), close that range, and start the new one - If the symbol does not belong to any built-in modules: - If we were working on a module(s) range, close that range Signed-off-by: Kris Van Hees Reviewed-by: Nick Alcock Reviewed-by: Alan Maguire Reviewed-by: Steven Rostedt (Google) Tested-by: Sam James Reviewed-by: Sami Tolvanen Tested-by: Sami Tolvanen Signed-off-by: Masahiro Yamada