From 8c4d9b145ba39fa31fd225e9051dd562260b6460 Mon Sep 17 00:00:00 2001 From: Masahiro Yamada Date: Sat, 28 Nov 2020 20:51:03 +0900 Subject: [PATCH] kbuild: doc: replace arch/$(ARCH)/ with arch/$(SRCARCH)/ Precisely speaking, the arch directory is specified by $(SRCARCH), not $(ARCH). In old days, $(ARCH) actually matched to the arch directory because 32-bit and 64-bit were supported as separate architectures. Most architectures (except arm/arm64) were unified like follows: arch/i386, arch/x86_64 -> arch/x86 arch/sh, arch/sh64 -> arch/sh arch/sparc, arch/sparc64 -> arch/sparc To not break the user interface, commit 6752ed90da03 ("Kbuild: allow arch/xxx to use a different source path") introduced SRCARCH to point to the arch directory, still allowing to pass in the former ARCH=i386 or ARCH=x86_64. Update the documents for preciseness, and add the explanation of SRCARCH. Signed-off-by: Masahiro Yamada Reviewed-by: Randy Dunlap --- Documentation/kbuild/makefiles.rst | 61 +++++++++++++++++------------- Documentation/kbuild/modules.rst | 2 +- 2 files changed, 35 insertions(+), 28 deletions(-) diff --git a/Documentation/kbuild/makefiles.rst b/Documentation/kbuild/makefiles.rst index a7b874097a91..896fe1612d55 100644 --- a/Documentation/kbuild/makefiles.rst +++ b/Documentation/kbuild/makefiles.rst @@ -67,11 +67,11 @@ This document describes the Linux kernel Makefiles. The Makefiles have five parts:: - Makefile the top Makefile. - .config the kernel configuration file. - arch/$(ARCH)/Makefile the arch Makefile. - scripts/Makefile.* common rules etc. for all kbuild Makefiles. - kbuild Makefiles exist in every subdirectory + Makefile the top Makefile. + .config the kernel configuration file. + arch/$(SRCARCH)/Makefile the arch Makefile. + scripts/Makefile.* common rules etc. for all kbuild Makefiles. + kbuild Makefiles exist in every subdirectory The top Makefile reads the .config file, which comes from the kernel configuration process. @@ -82,7 +82,7 @@ It builds these goals by recursively descending into the subdirectories of the kernel source tree. The list of subdirectories which are visited depends upon the kernel configuration. The top Makefile textually includes an arch Makefile -with the name arch/$(ARCH)/Makefile. The arch Makefile supplies +with the name arch/$(SRCARCH)/Makefile. The arch Makefile supplies architecture-specific information to the top Makefile. Each subdirectory has a kbuild Makefile which carries out the commands @@ -933,7 +933,7 @@ When "make clean" is executed, make will descend down in arch/x86/boot, and clean as usual. The Makefile located in arch/x86/boot/ may use the subdir- trick to descend further down. -Note 1: arch/$(ARCH)/Makefile cannot use "subdir-", because that file is +Note 1: arch/$(SRCARCH)/Makefile cannot use "subdir-", because that file is included in the top level makefile, and the kbuild infrastructure is not operational at that point. @@ -946,9 +946,9 @@ be visited during "make clean". The top level Makefile sets up the environment and does the preparation, before starting to descend down in the individual directories. The top level makefile contains the generic part, whereas -arch/$(ARCH)/Makefile contains what is required to set up kbuild +arch/$(SRCARCH)/Makefile contains what is required to set up kbuild for said architecture. -To do so, arch/$(ARCH)/Makefile sets up a number of variables and defines +To do so, arch/$(SRCARCH)/Makefile sets up a number of variables and defines a few targets. When kbuild executes, the following steps are followed (roughly): @@ -956,14 +956,14 @@ When kbuild executes, the following steps are followed (roughly): 1) Configuration of the kernel => produce .config 2) Store kernel version in include/linux/version.h 3) Updating all other prerequisites to the target prepare: - - Additional prerequisites are specified in arch/$(ARCH)/Makefile + - Additional prerequisites are specified in arch/$(SRCARCH)/Makefile 4) Recursively descend down in all directories listed in init-* core* drivers-* net-* libs-* and build all targets. - - The values of the above variables are expanded in arch/$(ARCH)/Makefile. + - The values of the above variables are expanded in arch/$(SRCARCH)/Makefile. 5) All object files are then linked and the resulting file vmlinux is located at the root of the obj tree. The very first objects linked are listed in head-y, assigned by - arch/$(ARCH)/Makefile. + arch/$(SRCARCH)/Makefile. 6) Finally, the architecture-specific part does any required post processing and builds the final bootimage. - This includes building boot records @@ -1169,7 +1169,7 @@ When kbuild executes, the following steps are followed (roughly): $(core-y), $(libs-y), $(drivers-y) and $(net-y). The top level Makefile defines values for all generic directories, - and arch/$(ARCH)/Makefile only adds architecture-specific + and arch/$(SRCARCH)/Makefile only adds architecture-specific directories. Example:: @@ -1189,15 +1189,15 @@ When kbuild executes, the following steps are followed (roughly): The actual goals are not standardized across architectures. It is common to locate any additional processing in a boot/ - directory below arch/$(ARCH)/. + directory below arch/$(SRCARCH)/. Kbuild does not provide any smart way to support building a - target specified in boot/. Therefore arch/$(ARCH)/Makefile shall + target specified in boot/. Therefore arch/$(SRCARCH)/Makefile shall call make manually to build a target in boot/. The recommended approach is to include shortcuts in - arch/$(ARCH)/Makefile, and use the full path when calling down - into the arch/$(ARCH)/boot/Makefile. + arch/$(SRCARCH)/Makefile, and use the full path when calling down + into the arch/$(SRCARCH)/boot/Makefile. Example:: @@ -1217,7 +1217,7 @@ When kbuild executes, the following steps are followed (roughly): #arch/x86/Makefile define archhelp - echo '* bzImage - Image (arch/$(ARCH)/boot/bzImage)' + echo '* bzImage - Compressed kernel image (arch/x86/boot/bzImage)' endif When make is executed without arguments, the first goal encountered @@ -1332,7 +1332,7 @@ When kbuild executes, the following steps are followed (roughly): objcopy Copy binary. Uses OBJCOPYFLAGS usually specified in - arch/$(ARCH)/Makefile. + arch/$(SRCARCH)/Makefile. OBJCOPYFLAGS_$@ may be used to set additional options. gzip @@ -1395,7 +1395,7 @@ When kbuild executes, the following steps are followed (roughly): -------------------------------- When the vmlinux image is built, the linker script - arch/$(ARCH)/kernel/vmlinux.lds is used. + arch/$(SRCARCH)/kernel/vmlinux.lds is used. The script is a preprocessed variant of the file vmlinux.lds.S located in the same directory. kbuild knows .lds files and includes a rule `*lds.S` -> `*lds`. @@ -1405,9 +1405,6 @@ When kbuild executes, the following steps are followed (roughly): #arch/x86/kernel/Makefile extra-y := vmlinux.lds - #Makefile - export CPPFLAGS_vmlinux.lds += -P -C -U$(ARCH) - The assignment to extra-y is used to tell kbuild to build the target vmlinux.lds. The assignment to $(CPPFLAGS_vmlinux.lds) tells kbuild to use the @@ -1481,7 +1478,7 @@ See subsequent chapter for the syntax of the Kbuild file. If an architecture uses a verbatim copy of a header from include/asm-generic then this is listed in the file - arch/$(ARCH)/include/asm/Kbuild like this: + arch/$(SRCARCH)/include/asm/Kbuild like this: Example:: @@ -1492,7 +1489,7 @@ See subsequent chapter for the syntax of the Kbuild file. During the prepare phase of the build a wrapper include file is generated in the directory:: - arch/$(ARCH)/include/generated/asm + arch/$(SRCARCH)/include/generated/asm When a header is exported where the architecture uses the generic header a similar wrapper is generated as part @@ -1527,8 +1524,8 @@ See subsequent chapter for the syntax of the Kbuild file. to define the minimum set of ASM headers that all architectures must have. This works like optional generic-y. If a mandatory header is missing - in arch/$(ARCH)/include/(uapi/)/asm, Kbuild will automatically generate - a wrapper of the asm-generic one. + in arch/$(SRCARCH)/include/(uapi/)/asm, Kbuild will automatically + generate a wrapper of the asm-generic one. 9 Kbuild Variables ================== @@ -1564,6 +1561,16 @@ The top Makefile exports the following variables: make ARCH=m68k ... + SRCARCH + This variable specifies the directory in arch/ to build. + + ARCH and SRCARCH may not necessarily match. A couple of arch + directories are biarch, that is, a single `arch/*/` directory supports + both 32-bit and 64-bit. + + For example, you can pass in ARCH=i386, ARCH=x86_64, or ARCH=x86. + For all of them, SRCARCH=x86 because arch/x86/ supports both i386 and + x86_64. INSTALL_PATH This variable defines a place for the arch Makefiles to install diff --git a/Documentation/kbuild/modules.rst b/Documentation/kbuild/modules.rst index 85ccc878895e..a1f3eb7a43e2 100644 --- a/Documentation/kbuild/modules.rst +++ b/Documentation/kbuild/modules.rst @@ -332,7 +332,7 @@ according to the following rule: There are two notable exceptions to this rule: larger subsystems have their own directory under include/, such as include/scsi; and architecture specific headers are located - under arch/$(ARCH)/include/. + under arch/$(SRCARCH)/include/. 4.1 Kernel Includes -------------------