summaryrefslogtreecommitdiff
path: root/Documentation
diff options
context:
space:
mode:
authorLinus Torvalds <torvalds@linux-foundation.org>2020-06-06 12:00:25 -0700
committerLinus Torvalds <torvalds@linux-foundation.org>2020-06-06 12:00:25 -0700
commitcff11abeca78aa782378401ca2800bd2194aa14e (patch)
treefef5d11fd49bc91e49116d9935fc7f23d340716f /Documentation
parent6f2dc3d335457d9c815be9f4fd3dc8eff92fcef7 (diff)
parent8dfb61dcbaceb19a5ded5e9c9dcf8d05acc32294 (diff)
Merge tag 'kbuild-v5.8' of git://git.kernel.org/pub/scm/linux/kernel/git/masahiroy/linux-kbuild
Pull Kbuild updates from Masahiro Yamada: - fix warnings in 'make clean' for ARCH=um, hexagon, h8300, unicore32 - ensure to rebuild all objects when the compiler is upgraded - exclude system headers from dependency tracking and fixdep processing - fix potential bit-size mismatch between the kernel and BPF user-mode helper - add the new syntax 'userprogs' to build user-space programs for the target architecture (the same arch as the kernel) - compile user-space sample code under samples/ for the target arch instead of the host arch - make headers_install fail if a CONFIG option is leaked to user-space - sanitize the output format of scripts/checkstack.pl - handle ARM 'push' instruction in scripts/checkstack.pl - error out before modpost if a module name conflict is found - error out when multiple directories are passed to M= because this feature is broken for a long time - add CONFIG_DEBUG_INFO_COMPRESSED to support compressed debug info - a lot of cleanups of modpost - dump vmlinux symbols out into vmlinux.symvers, and reuse it in the second pass of modpost - do not run the second pass of modpost if nothing in modules is updated - install modules.builtin(.modinfo) by 'make install' as well as by 'make modules_install' because it is useful even when CONFIG_MODULES=n - add new command line variables, GZIP, BZIP2, LZOP, LZMA, LZ4, and XZ to allow users to use alternatives such as pigz, pbzip2, etc. * tag 'kbuild-v5.8' of git://git.kernel.org/pub/scm/linux/kernel/git/masahiroy/linux-kbuild: (96 commits) kbuild: add variables for compression tools Makefile: install modules.builtin even if CONFIG_MODULES=n mksysmap: Fix the mismatch of '.L' symbols in System.map kbuild: doc: rename LDFLAGS to KBUILD_LDFLAGS modpost: change elf_info->size to size_t modpost: remove is_vmlinux() helper modpost: strip .o from modname before calling new_module() modpost: set have_vmlinux in new_module() modpost: remove mod->skip struct member modpost: add mod->is_vmlinux struct member modpost: remove is_vmlinux() call in check_for_{gpl_usage,unused}() modpost: remove mod->is_dot_o struct member modpost: move -d option in scripts/Makefile.modpost modpost: remove -s option modpost: remove get_next_text() and make {grab,release_}file static modpost: use read_text_file() and get_line() for reading text files modpost: avoid false-positive file open error modpost: fix potential mmap'ed file overrun in get_src_version() modpost: add read_text_file() and get_line() helpers modpost: do not call get_modinfo() for vmlinux(.o) ...
Diffstat (limited to 'Documentation')
-rw-r--r--Documentation/dontdiff1
-rw-r--r--Documentation/kbuild/makefiles.rst187
-rw-r--r--Documentation/kbuild/modules.rst12
3 files changed, 138 insertions, 62 deletions
diff --git a/Documentation/dontdiff b/Documentation/dontdiff
index 72fc2e9e2b63..ef9519c32c55 100644
--- a/Documentation/dontdiff
+++ b/Documentation/dontdiff
@@ -251,6 +251,7 @@ vmlinux-*
vmlinux.aout
vmlinux.bin.all
vmlinux.lds
+vmlinux.symvers
vmlinuz
voffset.h
vsyscall.lds
diff --git a/Documentation/kbuild/makefiles.rst b/Documentation/kbuild/makefiles.rst
index b80257a03830..6515ebc12b6f 100644
--- a/Documentation/kbuild/makefiles.rst
+++ b/Documentation/kbuild/makefiles.rst
@@ -29,31 +29,37 @@ This document describes the Linux kernel Makefiles.
--- 4.4 Controlling compiler options for host programs
--- 4.5 When host programs are actually built
- === 5 Kbuild clean infrastructure
-
- === 6 Architecture Makefiles
- --- 6.1 Set variables to tweak the build to the architecture
- --- 6.2 Add prerequisites to archheaders:
- --- 6.3 Add prerequisites to archprepare:
- --- 6.4 List directories to visit when descending
- --- 6.5 Architecture-specific boot images
- --- 6.6 Building non-kbuild targets
- --- 6.7 Commands useful for building a boot image
- --- 6.8 Custom kbuild commands
- --- 6.9 Preprocessing linker scripts
- --- 6.10 Generic header files
- --- 6.11 Post-link pass
-
- === 7 Kbuild syntax for exported headers
- --- 7.1 no-export-headers
- --- 7.2 generic-y
- --- 7.3 generated-y
- --- 7.4 mandatory-y
-
- === 8 Kbuild Variables
- === 9 Makefile language
- === 10 Credits
- === 11 TODO
+ === 5 Userspace Program support
+ --- 5.1 Simple Userspace Program
+ --- 5.2 Composite Userspace Programs
+ --- 5.3 Controlling compiler options for userspace programs
+ --- 5.4 When userspace programs are actually built
+
+ === 6 Kbuild clean infrastructure
+
+ === 7 Architecture Makefiles
+ --- 7.1 Set variables to tweak the build to the architecture
+ --- 7.2 Add prerequisites to archheaders:
+ --- 7.3 Add prerequisites to archprepare:
+ --- 7.4 List directories to visit when descending
+ --- 7.5 Architecture-specific boot images
+ --- 7.6 Building non-kbuild targets
+ --- 7.7 Commands useful for building a boot image
+ --- 7.8 Custom kbuild commands
+ --- 7.9 Preprocessing linker scripts
+ --- 7.10 Generic header files
+ --- 7.11 Post-link pass
+
+ === 8 Kbuild syntax for exported headers
+ --- 8.1 no-export-headers
+ --- 8.2 generic-y
+ --- 8.3 generated-y
+ --- 8.4 mandatory-y
+
+ === 9 Kbuild Variables
+ === 10 Makefile language
+ === 11 Credits
+ === 12 TODO
1 Overview
==========
@@ -732,7 +738,88 @@ Both possibilities are described in the following.
This will tell kbuild to build lxdialog even if not referenced in
any rule.
-5 Kbuild clean infrastructure
+5 Userspace Program support
+===========================
+
+Just like host programs, Kbuild also supports building userspace executables
+for the target architecture (i.e. the same architecture as you are building
+the kernel for).
+
+The syntax is quite similar. The difference is to use "userprogs" instead of
+"hostprogs".
+
+5.1 Simple Userspace Program
+----------------------------
+
+ The following line tells kbuild that the program bpf-direct shall be
+ built for the target architecture.
+
+ Example::
+
+ userprogs := bpf-direct
+
+ Kbuild assumes in the above example that bpf-direct is made from a
+ single C source file named bpf-direct.c located in the same directory
+ as the Makefile.
+
+5.2 Composite Userspace Programs
+--------------------------------
+
+ Userspace programs can be made up based on composite objects.
+ The syntax used to define composite objects for userspace programs is
+ similar to the syntax used for kernel objects.
+ $(<executable>-objs) lists all objects used to link the final
+ executable.
+
+ Example::
+
+ #samples/seccomp/Makefile
+ userprogs := bpf-fancy
+ bpf-fancy-objs := bpf-fancy.o bpf-helper.o
+
+ Objects with extension .o are compiled from the corresponding .c
+ files. In the above example, bpf-fancy.c is compiled to bpf-fancy.o
+ and bpf-helper.c is compiled to bpf-helper.o.
+
+ Finally, the two .o files are linked to the executable, bpf-fancy.
+ Note: The syntax <executable>-y is not permitted for userspace programs.
+
+5.3 Controlling compiler options for userspace programs
+-------------------------------------------------------
+
+ When compiling userspace programs, it is possible to set specific flags.
+ The programs will always be compiled utilising $(CC) passed
+ the options specified in $(KBUILD_USERCFLAGS).
+ To set flags that will take effect for all userspace programs created
+ in that Makefile, use the variable userccflags.
+
+ Example::
+
+ # samples/seccomp/Makefile
+ userccflags += -I usr/include
+
+ To set specific flags for a single file the following construction
+ is used:
+
+ Example::
+
+ bpf-helper-userccflags += -I user/include
+
+ It is also possible to specify additional options to the linker.
+
+ Example::
+
+ # net/bpfilter/Makefile
+ bpfilter_umh-userldflags += -static
+
+ When linking bpfilter_umh, it will be passed the extra option -static.
+
+5.4 When userspace programs are actually built
+----------------------------------------------
+
+ Same as "When host programs are actually built".
+
+6 Kbuild clean infrastructure
=============================
"make clean" deletes most generated files in the obj tree where the kernel
@@ -790,7 +877,7 @@ is not operational at that point.
Note 2: All directories listed in core-y, libs-y, drivers-y and net-y will
be visited during "make clean".
-6 Architecture Makefiles
+7 Architecture Makefiles
========================
The top level Makefile sets up the environment and does the preparation,
@@ -820,10 +907,10 @@ When kbuild executes, the following steps are followed (roughly):
- Preparing initrd images and the like
-6.1 Set variables to tweak the build to the architecture
+7.1 Set variables to tweak the build to the architecture
--------------------------------------------------------
- LDFLAGS
+ KBUILD_LDFLAGS
Generic $(LD) options
Flags used for all invocations of the linker.
@@ -832,7 +919,7 @@ When kbuild executes, the following steps are followed (roughly):
Example::
#arch/s390/Makefile
- LDFLAGS := -m elf_s390
+ KBUILD_LDFLAGS := -m elf_s390
Note: ldflags-y can be used to further customise
the flags used. See chapter 3.7.
@@ -967,7 +1054,7 @@ When kbuild executes, the following steps are followed (roughly):
KBUILD_VMLINUX_LIBS together specify all the object files used to
link vmlinux.
-6.2 Add prerequisites to archheaders
+7.2 Add prerequisites to archheaders
------------------------------------
The archheaders: rule is used to generate header files that
@@ -977,7 +1064,7 @@ When kbuild executes, the following steps are followed (roughly):
architecture itself.
-6.3 Add prerequisites to archprepare
+7.3 Add prerequisites to archprepare
------------------------------------
The archprepare: rule is used to list prerequisites that need to be
@@ -995,7 +1082,7 @@ When kbuild executes, the following steps are followed (roughly):
generating offset header files.
-6.4 List directories to visit when descending
+7.4 List directories to visit when descending
---------------------------------------------
An arch Makefile cooperates with the top Makefile to define variables
@@ -1030,7 +1117,7 @@ When kbuild executes, the following steps are followed (roughly):
drivers-$(CONFIG_OPROFILE) += arch/sparc64/oprofile/
-6.5 Architecture-specific boot images
+7.5 Architecture-specific boot images
-------------------------------------
An arch Makefile specifies goals that take the vmlinux file, compress
@@ -1085,7 +1172,7 @@ When kbuild executes, the following steps are followed (roughly):
When "make" is executed without arguments, bzImage will be built.
-6.6 Building non-kbuild targets
+7.6 Building non-kbuild targets
-------------------------------
extra-y
@@ -1108,7 +1195,7 @@ When kbuild executes, the following steps are followed (roughly):
In this example, extra-y is used to list object files that
shall be built, but shall not be linked as part of built-in.a.
-6.7 Commands useful for building a boot image
+7.7 Commands useful for building a boot image
---------------------------------------------
Kbuild provides a few macros that are useful when building a
@@ -1211,7 +1298,7 @@ When kbuild executes, the following steps are followed (roughly):
targets += $(dtb-y)
DTC_FLAGS ?= -p 1024
-6.8 Custom kbuild commands
+7.8 Custom kbuild commands
--------------------------
When kbuild is executing with KBUILD_VERBOSE=0, then only a shorthand
@@ -1241,7 +1328,7 @@ When kbuild executes, the following steps are followed (roughly):
will be displayed with "make KBUILD_VERBOSE=0".
-6.9 Preprocessing linker scripts
+7.9 Preprocessing linker scripts
--------------------------------
When the vmlinux image is built, the linker script
@@ -1274,7 +1361,7 @@ When kbuild executes, the following steps are followed (roughly):
The kbuild infrastructure for `*lds` files is used in several
architecture-specific files.
-6.10 Generic header files
+7.10 Generic header files
-------------------------
The directory include/asm-generic contains the header files
@@ -1283,7 +1370,7 @@ When kbuild executes, the following steps are followed (roughly):
to list the file in the Kbuild file.
See "7.2 generic-y" for further info on syntax etc.
-6.11 Post-link pass
+7.11 Post-link pass
-------------------
If the file arch/xxx/Makefile.postlink exists, this makefile
@@ -1299,7 +1386,7 @@ When kbuild executes, the following steps are followed (roughly):
For example, powerpc uses this to check relocation sanity of
the linked vmlinux file.
-7 Kbuild syntax for exported headers
+8 Kbuild syntax for exported headers
------------------------------------
The kernel includes a set of headers that is exported to userspace.
@@ -1319,14 +1406,14 @@ A Kbuild file may be defined under arch/<arch>/include/uapi/asm/ and
arch/<arch>/include/asm/ to list asm files coming from asm-generic.
See subsequent chapter for the syntax of the Kbuild file.
-7.1 no-export-headers
+8.1 no-export-headers
---------------------
no-export-headers is essentially used by include/uapi/linux/Kbuild to
avoid exporting specific headers (e.g. kvm.h) on architectures that do
not support it. It should be avoided as much as possible.
-7.2 generic-y
+8.2 generic-y
-------------
If an architecture uses a verbatim copy of a header from
@@ -1356,7 +1443,7 @@ See subsequent chapter for the syntax of the Kbuild file.
#include <asm-generic/termios.h>
-7.3 generated-y
+8.3 generated-y
---------------
If an architecture generates other header files alongside generic-y
@@ -1370,7 +1457,7 @@ See subsequent chapter for the syntax of the Kbuild file.
#arch/x86/include/asm/Kbuild
generated-y += syscalls_32.h
-7.4 mandatory-y
+8.4 mandatory-y
---------------
mandatory-y is essentially used by include/(uapi/)asm-generic/Kbuild
@@ -1380,7 +1467,7 @@ See subsequent chapter for the syntax of the Kbuild file.
in arch/$(ARCH)/include/(uapi/)/asm, Kbuild will automatically generate
a wrapper of the asm-generic one.
-8 Kbuild Variables
+9 Kbuild Variables
==================
The top Makefile exports the following variables:
@@ -1438,8 +1525,8 @@ The top Makefile exports the following variables:
command.
-9 Makefile language
-===================
+10 Makefile language
+====================
The kernel Makefiles are designed to be run with GNU Make. The Makefiles
use only the documented features of GNU Make, but they do use many
@@ -1458,7 +1545,7 @@ time the left-hand side is used.
There are some cases where "=" is appropriate. Usually, though, ":="
is the right choice.
-10 Credits
+11 Credits
==========
- Original version made by Michael Elizabeth Chastain, <mailto:mec@shout.net>
@@ -1466,7 +1553,7 @@ is the right choice.
- Updates by Sam Ravnborg <sam@ravnborg.org>
- Language QA by Jan Engelhardt <jengelh@gmx.de>
-11 TODO
+12 TODO
=======
- Describe how kbuild supports shipped files with _shipped.
diff --git a/Documentation/kbuild/modules.rst b/Documentation/kbuild/modules.rst
index e0b45a257f21..a45cccff467d 100644
--- a/Documentation/kbuild/modules.rst
+++ b/Documentation/kbuild/modules.rst
@@ -528,18 +528,6 @@ build.
will then do the expected and compile both modules with
full knowledge of symbols from either module.
- Use an extra Module.symvers file
- When an external module is built, a Module.symvers file
- is generated containing all exported symbols which are
- not defined in the kernel. To get access to symbols
- from bar.ko, copy the Module.symvers file from the
- compilation of bar.ko to the directory where foo.ko is
- built. During the module build, kbuild will read the
- Module.symvers file in the directory of the external
- module, and when the build is finished, a new
- Module.symvers file is created containing the sum of
- all symbols defined and not part of the kernel.
-
Use "make" variable KBUILD_EXTRA_SYMBOLS
If it is impractical to add a top-level kbuild file,
you can assign a space separated list