From e079a08c60744af54eed7b7f957d6c87b163f25e Mon Sep 17 00:00:00 2001 From: Masahiro Yamada Date: Wed, 29 Apr 2020 12:45:17 +0900 Subject: kbuild: doc: document the new syntax 'userprogs' Kbuild now supports the syntax 'userprogs' to compile userspace programs for the same architecture as the kernel. Insert the section '5 Userspace Program support' to explain it. I copy-pasted '4 Host Program support' and fixed it up. Signed-off-by: Masahiro Yamada Acked-by: Sam Ravnborg --- Documentation/kbuild/makefiles.rst | 183 +++++++++++++++++++++++++++---------- 1 file changed, 135 insertions(+), 48 deletions(-) (limited to 'Documentation') diff --git a/Documentation/kbuild/makefiles.rst b/Documentation/kbuild/makefiles.rst index b80257a03830..2a18aea7c043 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. + $(-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 -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,7 +907,7 @@ 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 @@ -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//include/uapi/asm/ and 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 -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, @@ -1466,7 +1553,7 @@ is the right choice. - Updates by Sam Ravnborg - Language QA by Jan Engelhardt -11 TODO +12 TODO ======= - Describe how kbuild supports shipped files with _shipped. -- cgit v1.2.3 From 9504bbe91efc163e4c46496ae790da60353b23b4 Mon Sep 17 00:00:00 2001 From: Masahiro Yamada Date: Thu, 21 May 2020 13:31:17 +0900 Subject: kbuild: doc: remove documentation about copying Module.symvers around This is a left-over of commit 39808e451fdf ("kbuild: do not read $(KBUILD_EXTMOD)/Module.symvers"). Kbuild no longer supports this way. Signed-off-by: Masahiro Yamada --- Documentation/kbuild/modules.rst | 12 ------------ 1 file changed, 12 deletions(-) (limited to 'Documentation') 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 -- cgit v1.2.3 From 269a535ca931b754a40dda3ab60514e68773c759 Mon Sep 17 00:00:00 2001 From: Masahiro Yamada Date: Mon, 1 Jun 2020 14:57:11 +0900 Subject: modpost: generate vmlinux.symvers and reuse it for the second modpost The full build runs modpost twice, first for vmlinux.o and second for modules. The first pass dumps all the vmlinux symbols into Module.symvers, but the second pass parses vmlinux again instead of reusing the dump file, presumably because it needs to avoid accumulating stale symbols. Loading symbol info from a dump file is faster than parsing an ELF object. Besides, modpost deals with various issues to parse vmlinux in the second pass. A solution is to make the first pass dumps symbols into a separate file, vmlinux.symvers. The second pass reads it, and parses module .o files. The merged symbol information is dumped into Module.symvers in the same way as before. This makes further modpost cleanups possible. Also, it fixes the problem of 'make vmlinux', which previously overwrote Module.symvers, throwing away module symbols. I slightly touched scripts/link-vmlinux.sh so that vmlinux is re-linked when you cross this commit. Otherwise, vmlinux.symvers would not be generated. Signed-off-by: Masahiro Yamada --- .gitignore | 1 + Documentation/dontdiff | 1 + Makefile | 2 +- scripts/Makefile.modpost | 7 ++++--- scripts/link-vmlinux.sh | 2 -- 5 files changed, 7 insertions(+), 6 deletions(-) (limited to 'Documentation') diff --git a/.gitignore b/.gitignore index 2258e906f01c..87b9dd8a163b 100644 --- a/.gitignore +++ b/.gitignore @@ -56,6 +56,7 @@ modules.order /linux /vmlinux /vmlinux.32 +/vmlinux.symvers /vmlinux-gdb.py /vmlinuz /System.map 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/Makefile b/Makefile index b0bbf8453b66..9768140f8d5a 100644 --- a/Makefile +++ b/Makefile @@ -1416,7 +1416,7 @@ endif # CONFIG_MODULES # make distclean Remove editor backup files, patch leftover files and the like # Directories & files removed with 'make clean' -CLEAN_FILES += include/ksym \ +CLEAN_FILES += include/ksym vmlinux.symvers \ modules.builtin modules.builtin.modinfo modules.nsdeps # Directories & files removed with 'make mrproper' diff --git a/scripts/Makefile.modpost b/scripts/Makefile.modpost index 79e850c8ce01..896c799911c5 100644 --- a/scripts/Makefile.modpost +++ b/scripts/Makefile.modpost @@ -55,10 +55,10 @@ ifdef MODPOST_VMLINUX quiet_cmd_modpost = MODPOST $@ cmd_modpost = $(MODPOST) $< -Module.symvers: vmlinux.o +vmlinux.symvers: vmlinux.o $(call cmd,modpost) -__modpost: Module.symvers +__modpost: vmlinux.symvers else @@ -66,7 +66,8 @@ MODPOST += -s \ $(if $(KBUILD_NSDEPS),-d $(MODULES_NSDEPS)) ifeq ($(KBUILD_EXTMOD),) -MODPOST += $(wildcard vmlinux) + +input-symdump := vmlinux.symvers output-symdump := Module.symvers else diff --git a/scripts/link-vmlinux.sh b/scripts/link-vmlinux.sh index d09ab4afbda4..d5af6be50b50 100755 --- a/scripts/link-vmlinux.sh +++ b/scripts/link-vmlinux.sh @@ -218,8 +218,6 @@ on_signals() } trap on_signals HUP INT QUIT TERM -# -# # Use "make V=1" to debug this script case "${KBUILD_VERBOSE}" in *1*) -- cgit v1.2.3 From c0901577e1dcc8d1c0fd1a11c8d571f650df845f Mon Sep 17 00:00:00 2001 From: Masahiro Yamada Date: Tue, 2 Jun 2020 02:03:28 +0900 Subject: kbuild: doc: rename LDFLAGS to KBUILD_LDFLAGS Commit d503ac531a52 ("kbuild: rename LDFLAGS to KBUILD_LDFLAGS") missed to update the documentation. Signed-off-by: Masahiro Yamada --- Documentation/kbuild/makefiles.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'Documentation') diff --git a/Documentation/kbuild/makefiles.rst b/Documentation/kbuild/makefiles.rst index 2a18aea7c043..6515ebc12b6f 100644 --- a/Documentation/kbuild/makefiles.rst +++ b/Documentation/kbuild/makefiles.rst @@ -910,7 +910,7 @@ When kbuild executes, the following steps are followed (roughly): 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. @@ -919,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. -- cgit v1.2.3