Documentation: kbuild: Improve grammar

--- 3.3 Loadable module goals - obj-m

--- 3.3 Loadable module goals - obj-m

	$(obj-m) specify object files which are built as loadable

	$(obj-m) specifies object files which are built as loadable

	kernel modules.

	kernel modules.

	A module may be built from one source file or several source

	A module may be built from one source file or several source

	down in the ext2 directory.

	down in the ext2 directory.

	Kbuild only uses this information to decide that it needs to visit

	Kbuild only uses this information to decide that it needs to visit

	the directory, it is the Makefile in the subdirectory that

	the directory, it is the Makefile in the subdirectory that

	specifies what is modules and what is built-in.

	specifies what is modular and what is built-in.

	It is good practice to use a CONFIG_ variable when assigning directory

	It is good practice to use a CONFIG_ variable when assigning directory

	names. This allows kbuild to totally skip the directory if the

	names. This allows kbuild to totally skip the directory if the

	echoing information to user in a rule is often a good practice

	echoing information to user in a rule is often a good practice

	but when execution "make -s" one does not expect to see any output

	but when execution "make -s" one does not expect to see any output

	except for warnings/errors.

	except for warnings/errors.

	To support this kbuild define $(kecho) which will echo out the

	To support this kbuild defines $(kecho) which will echo out the

	text following $(kecho) to stdout except if "make -s" is used.

	text following $(kecho) to stdout except if "make -s" is used.

	Example:

	Example:

	The kernel may be built with several different versions of

	The kernel may be built with several different versions of

	$(CC), each supporting a unique set of features and options.

	$(CC), each supporting a unique set of features and options.

	kbuild provide basic support to check for valid options for $(CC).

	kbuild provides basic support to check for valid options for $(CC).

	$(CC) is usually the gcc compiler, but other alternatives are

	$(CC) is usually the gcc compiler, but other alternatives are

	available.

	available.

	Note: as-instr-option uses KBUILD_AFLAGS for $(AS) options

	Note: as-instr-option uses KBUILD_AFLAGS for $(AS) options

    cc-option

    cc-option

	cc-option is used to check if $(CC) supports a given option, and not

	cc-option is used to check if $(CC) supports a given option, and if

	supported to use an optional second option.

	not supported to use an optional second option.

	Example:

	Example:

		#arch/x86/Makefile

		#arch/x86/Makefile

			false ; \

			false ; \

		fi

		fi

	In this example for a specific GCC version the build will error out explaining

	In this example for a specific GCC version the build will error out

	to the user why it stops.

	explaining to the user why it stops.

    cc-cross-prefix

    cc-cross-prefix

	cc-cross-prefix is used to check if there exists a $(CC) in path with

	cc-cross-prefix is used to check if there exists a $(CC) in path with

	In the example above the executable is composed of the C++ file

	In the example above the executable is composed of the C++ file

	qconf.cc - identified by $(qconf-cxxobjs).

	qconf.cc - identified by $(qconf-cxxobjs).

	If qconf is composed by a mixture of .c and .cc files, then an

	If qconf is composed of a mixture of .c and .cc files, then an

	additional line can be used to identify this.

	additional line can be used to identify this.

	Example:

	Example:

		hostprogs-$(CONFIG_KALLSYMS) += kallsyms

		hostprogs-$(CONFIG_KALLSYMS) += kallsyms

	Kbuild knows about both 'y' for built-in and 'm' for module.

	Kbuild knows about both 'y' for built-in and 'm' for module.

	So if a config symbol evaluate to 'm', kbuild will still build

	So if a config symbol evaluates to 'm', kbuild will still build

	the binary. In other words, Kbuild handles hostprogs-m exactly

	the binary. In other words, Kbuild handles hostprogs-m exactly

	like hostprogs-y. But only hostprogs-y is recommended to be used

	like hostprogs-y. But only hostprogs-y is recommended to be used

	when no CONFIG symbols are involved.

	when no CONFIG symbols are involved.

		#drivers/pci/Makefile

		#drivers/pci/Makefile

		clean-files := devlist.h classlist.h

		clean-files := devlist.h classlist.h

When executing "make clean", the two files "devlist.h classlist.h" will

When executing "make clean", the two files "devlist.h classlist.h" will be

be deleted. Kbuild will assume files to be in same relative directory as the

deleted. Kbuild will assume files to be in the same relative directory as the

Makefile except if an absolute path is specified (path starting with '/').

Makefile except if an absolute path is specified (path starting with '/').

To delete a directory hierarchy use:

To delete a directory hierarchy use:

The above assignment instructs kbuild to descend down in the

The above assignment instructs kbuild to descend down in the

directory compressed/ when "make clean" is executed.

directory compressed/ when "make clean" is executed.

To support the clean infrastructure in the Makefiles that builds the

To support the clean infrastructure in the Makefiles that build the

final bootimage there is an optional target named archclean:

final bootimage there is an optional target named archclean:

	Example:

	Example:

    KBUILD_AFLAGS_MODULE   Options for $(AS) when building modules

    KBUILD_AFLAGS_MODULE   Options for $(AS) when building modules

	$(KBUILD_AFLAGS_MODULE) is used to add arch specific options that

	$(KBUILD_AFLAGS_MODULE) is used to add arch-specific options that

	are used for $(AS).

	are used for $(AS).

	From commandline AFLAGS_MODULE shall be used (see kbuild.txt).

	From commandline AFLAGS_MODULE shall be used (see kbuild.txt).

    KBUILD_CFLAGS_MODULE   Options for $(CC) when building modules

    KBUILD_CFLAGS_MODULE   Options for $(CC) when building modules

	$(KBUILD_CFLAGS_MODULE) is used to add arch specific options that

	$(KBUILD_CFLAGS_MODULE) is used to add arch-specific options that

	are used for $(CC).

	are used for $(CC).

	From commandline CFLAGS_MODULE shall be used (see kbuild.txt).

	From commandline CFLAGS_MODULE shall be used (see kbuild.txt).

    KBUILD_LDFLAGS_MODULE   Options for $(LD) when linking modules

    KBUILD_LDFLAGS_MODULE   Options for $(LD) when linking modules

	$(KBUILD_LDFLAGS_MODULE) is used to add arch specific options

	$(KBUILD_LDFLAGS_MODULE) is used to add arch-specific options

	used when linking modules. This is often a linker script.

	used when linking modules. This is often a linker script.

	From commandline LDFLAGS_MODULE shall be used (see kbuild.txt).

	From commandline LDFLAGS_MODULE shall be used (see kbuild.txt).

    extra-y

    extra-y

	extra-y specify additional targets created in the current

	extra-y specifies additional targets created in the current

	directory, in addition to any targets specified by obj-*.

	directory, in addition to any targets specified by obj-*.

	Listing all targets in extra-y is required for two purposes:

	Listing all targets in extra-y is required for two purposes:

		2) delete target during make clean

		2) delete target during make clean

	The ": %: %.o" part of the prerequisite is a shorthand that

	The ": %: %.o" part of the prerequisite is a shorthand that

	free us from listing the setup.o and bootsect.o files.

	frees us from listing the setup.o and bootsect.o files.

	Note: It is a common mistake to forget the "targets :=" assignment,

	Note: It is a common mistake to forget the "targets :=" assignment,

	      resulting in the target file being recompiled for no

	      resulting in the target file being recompiled for no

	      obvious reason.

	      obvious reason.

	When building the *.lds target, kbuild uses the variables:

	When building the *.lds target, kbuild uses the variables:

	KBUILD_CPPFLAGS	: Set in top-level Makefile

	KBUILD_CPPFLAGS	: Set in top-level Makefile

	cppflags-y	: May be set in the kbuild makefile

	cppflags-y	: May be set in the kbuild makefile

	CPPFLAGS_$(@F)  : Target specific flags.

	CPPFLAGS_$(@F)  : Target-specific flags.

	                  Note that the full filename is used in this

	                  Note that the full filename is used in this

	                  assignment.

	                  assignment.

	The kbuild infrastructure for *lds file are used in several

	The kbuild infrastructure for *lds files is used in several

	architecture-specific files.

	architecture-specific files.

--- 6.10 Generic header files

--- 6.10 Generic header files

=== 7 Kbuild syntax for exported headers

=== 7 Kbuild syntax for exported headers

The kernel include a set of headers that is exported to userspace.

The kernel includes a set of headers that is exported to userspace.

Many headers can be exported as-is but other headers require a

Many headers can be exported as-is but other headers require a

minimal pre-processing before they are ready for user-space.

minimal pre-processing before they are ready for user-space.

The pre-processing does:

The pre-processing does:

- drop kernel specific annotations

- drop kernel-specific annotations

- drop include of compiler.h

- drop include of compiler.h

- drop all sections that are kernel internal (guarded by ifdef __KERNEL__)

- drop all sections that are kernel internal (guarded by ifdef __KERNEL__)

	--- 7.1 header-y

	--- 7.1 header-y

	header-y specify header files to be exported.

	header-y specifies header files to be exported.

		Example:

		Example:

			#include/linux/Kbuild

			#include/linux/Kbuild

	The convention is to list one file per line and

	The convention is to list one file per line and

	preferably in alphabetic order.

	preferably in alphabetic order.

	header-y also specify which subdirectories to visit.

	header-y also specifies which subdirectories to visit.

	A subdirectory is identified by a trailing '/' which

	A subdirectory is identified by a trailing '/' which

	can be seen in the example above for the usb subdirectory.

	can be seen in the example above for the usb subdirectory.

	--- 7.3 destination-y

	--- 7.3 destination-y

	When an architecture have a set of exported headers that needs to be

	When an architecture has a set of exported headers that needs to be

	exported to a different directory destination-y is used.

	exported to a different directory destination-y is used.

	destination-y specify the destination directory for all exported

	destination-y specifies the destination directory for all exported

	headers in the file where it is present.

	headers in the file where it is present.

		Example:

		Example:

    INSTALL_MOD_STRIP

    INSTALL_MOD_STRIP

	If this variable is specified, will cause modules to be stripped

	If this variable is specified, it will cause modules to be stripped

	after they are installed.  If INSTALL_MOD_STRIP is '1', then the

	after they are installed.  If INSTALL_MOD_STRIP is '1', then the

	default option --strip-debug will be used.  Otherwise,

	default option --strip-debug will be used.  Otherwise, the

	INSTALL_MOD_STRIP value will be used as the option(s) to the strip

	INSTALL_MOD_STRIP value will be used as the option(s) to the strip

	command.

	command.