kbuild-(directory)

00-INDEX
    - this file: info on the kernel build process
kbuild.txt
    - developer information on kbuild
kconfig.txt
    - usage help for make *config
kconfig-language.txt
    - specification of Config Language, the language in Kconfig files
makefiles.txt
    - developer information for linux kernel makefiles
modules.txt
    - how to build modules and to install them

 

kbuild

Output files

modules.order
--------------------------------------------------
This file records the order in which modules appear in Makefiles. This
is used by modprobe to deterministically resolve aliases that match
multiple modules.

modules.builtin
--------------------------------------------------
This file lists all modules that are built into the kernel. This is used
by modprobe to not fail when trying to load something builtin.


Environment variables

KCPPFLAGS
--------------------------------------------------
Additional options to pass when preprocessing. The preprocessing options
will be used in all cases where kbuild does preprocessing including
building C files and assembler files.

KAFLAGS
--------------------------------------------------
Additional options to the assembler (for built-in and modules).

AFLAGS_MODULE
--------------------------------------------------
Additional module specific options to use for $(AS).

AFLAGS_KERNEL
--------------------------------------------------
Additional options for $(AS) when used for assembler
code for code that is compiled as built-in.

KCFLAGS
--------------------------------------------------
Additional options to the C compiler (for built-in and modules).

CFLAGS_KERNEL
--------------------------------------------------
Additional options for $(CC) when used to compile
code that is compiled as built-in.

CFLAGS_MODULE
--------------------------------------------------
Additional module specific options to use for $(CC).

LDFLAGS_MODULE
--------------------------------------------------
Additional options used for $(LD) when linking modules.

KBUILD_VERBOSE
--------------------------------------------------
Set the kbuild verbosity. Can be assigned same values as "V=...".
See make help for the full list.
Setting "V=..." takes precedence over KBUILD_VERBOSE.

KBUILD_EXTMOD
--------------------------------------------------
Set the directory to look for the kernel source when building external
modules.
The directory can be specified in several ways:
1) Use "M=..." on the command line
2) Environment variable KBUILD_EXTMOD
3) Environment variable SUBDIRS
The possibilities are listed in the order they take precedence.
Using "M=..." will always override the others.

KBUILD_OUTPUT
--------------------------------------------------
Specify the output directory when building the kernel.
The output directory can also be specified using "O=...".
Setting "O=..." takes precedence over KBUILD_OUTPUT.

KBUILD_DEBARCH
--------------------------------------------------
For the deb-pkg target, allows overriding the normal heuristics deployed by
deb-pkg. Normally deb-pkg attempts to guess the right architecture based on
the UTS_MACHINE variable, and on some architectures also the kernel config.
The value of KBUILD_DEBARCH is assumed (not checked) to be a valid Debian
architecture.

ARCH
--------------------------------------------------
Set ARCH to the architecture to be built.
In most cases the name of the architecture is the same as the
directory name found in the arch/ directory.
But some architectures such as x86 and sparc have aliases.
x86: i386 for 32 bit, x86_64 for 64 bit
sparc: sparc for 32 bit, sparc64 for 64 bit

CROSS_COMPILE
--------------------------------------------------
Specify an optional fixed part of the binutils filename.
CROSS_COMPILE can be a part of the filename or the full path.

CROSS_COMPILE is also used for ccache in some setups.

CF
--------------------------------------------------
Additional options for sparse.
CF is often used on the command-line like this:

    make CF=-Wbitwise C=2

INSTALL_PATH
--------------------------------------------------
INSTALL_PATH specifies where to place the updated kernel and system map
images. Default is /boot, but you can set it to other values.

INSTALLKERNEL
--------------------------------------------------
Install script called when using "make install".
The default name is "installkernel".

The script will be called with the following arguments:
    $1 - kernel version
    $2 - kernel image file
    $3 - kernel map file
    $4 - default install path (use root directory if blank)

The implementation of "make install" is architecture specific
and it may differ from the above.

INSTALLKERNEL is provided to enable the possibility to
specify a custom installer when cross compiling a kernel.

MODLIB
--------------------------------------------------
Specify where to install modules.
The default value is:

     $(INSTALL_MOD_PATH)/lib/modules/$(KERNELRELEASE)

The value can be overridden in which case the default value is ignored.

INSTALL_MOD_PATH
--------------------------------------------------
INSTALL_MOD_PATH specifies a prefix to MODLIB for module directory
relocations required by build roots.  This is not defined in the
makefile but the argument can be passed to make if needed.

INSTALL_MOD_STRIP
--------------------------------------------------
INSTALL_MOD_STRIP, if defined, will cause modules to be
stripped after they are installed.  If INSTALL_MOD_STRIP is '1', then
the default option --strip-debug will be used.  Otherwise,
INSTALL_MOD_STRIP value will be used as the options to the strip command.

INSTALL_FW_PATH
--------------------------------------------------
INSTALL_FW_PATH specifies where to install the firmware blobs.
The default value is:

    $(INSTALL_MOD_PATH)/lib/firmware

The value can be overridden in which case the default value is ignored.

INSTALL_HDR_PATH
--------------------------------------------------
INSTALL_HDR_PATH specifies where to install user space headers when
executing "make headers_*".
The default value is:

    $(objtree)/usr

$(objtree) is the directory where output files are saved.
The output directory is often set using "O=..." on the commandline.

The value can be overridden in which case the default value is ignored.

KBUILD_MODPOST_WARN
--------------------------------------------------
KBUILD_MODPOST_WARN can be set to avoid errors in case of undefined
symbols in the final module linking stage. It changes such errors
into warnings.

KBUILD_MODPOST_NOFINAL
--------------------------------------------------
KBUILD_MODPOST_NOFINAL can be set to skip the final link of modules.
This is solely useful to speed up test compiles.

KBUILD_EXTRA_SYMBOLS
--------------------------------------------------
For modules that use symbols from other modules.
See more details in modules.txt.

ALLSOURCE_ARCHS
--------------------------------------------------
For tags/TAGS/cscope targets, you can specify more than one arch
to be included in the databases, separated by blank space. E.g.:

    $ make ALLSOURCE_ARCHS="x86 mips arm" tags

To get all available archs you can also specify all. E.g.:

    $ make ALLSOURCE_ARCHS=all tags

KBUILD_ENABLE_EXTRA_GCC_CHECKS
--------------------------------------------------
If enabled over the make command line with "W=1", it turns on additional
gcc -W... options for more extensive build-time checking.

KBUILD_BUILD_TIMESTAMP
--------------------------------------------------
Setting this to a date string overrides the timestamp used in the
UTS_VERSION definition (uname -v in the running kernel). The value has to
be a string that can be passed to date -d. The default value
is the output of the date command at one point during build.

KBUILD_BUILD_USER, KBUILD_BUILD_HOST
--------------------------------------------------
These two variables allow to override the user@host string displayed during
boot and in /proc/version. The default value is the output of the commands
whoami and host, respectively.

 

kconfig

This file contains some assistance for using "make *config".

Use "make help" to list all of the possible configuration targets.

The xconfig ('qconf') and menuconfig ('mconf') programs also
have embedded help text.  Be sure to check it for navigation,
search, and other general help text.

======================================================================
General
--------------------------------------------------

New kernel releases often introduce new config symbols.  Often more
important, new kernel releases may rename config symbols.  When
this happens, using a previously working .config file and running
"make oldconfig" won't necessarily produce a working new kernel
for you, so you may find that you need to see what NEW kernel
symbols have been introduced.

To see a list of new config symbols when using "make oldconfig", use

    cp user/some/old.config .config
    yes "" | make oldconfig >conf.new

and the config program will list as (NEW) any new symbols that have
unknown values.  Of course, the .config file is also updated with
new (default) values, so you can use:

    grep "(NEW)" conf.new

to see the new config symbols or you can use diffconfig to see the
differences between the previous and new .config files:

    scripts/diffconfig .config.old .config | less

______________________________________________________________________
Environment variables for '*config'

KCONFIG_CONFIG
--------------------------------------------------
This environment variable can be used to specify a default kernel config
file name to override the default name of ".config".

KCONFIG_OVERWRITECONFIG
--------------------------------------------------
If you set KCONFIG_OVERWRITECONFIG in the environment, Kconfig will not
break symlinks when .config is a symlink to somewhere else.

______________________________________________________________________
Environment variables for '{allyes/allmod/allno/rand}config'

KCONFIG_ALLCONFIG
--------------------------------------------------
(partially based on lkml email from/by Rob Landley, re: miniconfig)
--------------------------------------------------
The allyesconfig/allmodconfig/allnoconfig/randconfig variants can
also use the environment variable KCONFIG_ALLCONFIG as a flag or a
filename that contains config symbols that the user requires to be
set to a specific value.  If KCONFIG_ALLCONFIG is used without a
filename, "make *config" checks for a file named
"all{yes/mod/no/def/random}.config" (corresponding to the *config command
that was used) for symbol values that are to be forced.  If this file
is not found, it checks for a file named "all.config" to contain forced
values.

This enables you to create "miniature" config (miniconfig) or custom
config files containing just the config symbols that you are interested
in.  Then the kernel config system generates the full .config file,
including symbols of your miniconfig file.

This 'KCONFIG_ALLCONFIG' file is a config file which contains
(usually a subset of all) preset config symbols.  These variable
settings are still subject to normal dependency checks.

Examples:
    KCONFIG_ALLCONFIG=custom-notebook.config make allnoconfig
or
    KCONFIG_ALLCONFIG=mini.config make allnoconfig
or
    make KCONFIG_ALLCONFIG=mini.config allnoconfig

These examples will disable most options (allnoconfig) but enable or
disable the options that are explicitly listed in the specified
mini-config files.

______________________________________________________________________
Environment variables for 'silentoldconfig'

KCONFIG_NOSILENTUPDATE
--------------------------------------------------
If this variable has a non-blank value, it prevents silent kernel
config updates (requires explicit updates).

KCONFIG_AUTOCONFIG
--------------------------------------------------
This environment variable can be set to specify the path & name of the
"auto.conf" file.  Its default value is "include/config/auto.conf".

KCONFIG_TRISTATE
--------------------------------------------------
This environment variable can be set to specify the path & name of the
"tristate.conf" file.  Its default value is "include/config/tristate.conf".

KCONFIG_AUTOHEADER
--------------------------------------------------
This environment variable can be set to specify the path & name of the
"autoconf.h" (header) file.
Its default value is "include/generated/autoconf.h".


======================================================================
menuconfig
--------------------------------------------------

SEARCHING for CONFIG symbols

Searching in menuconfig:

    The Search function searches for kernel configuration symbol
    names, so you have to know something close to what you are
    looking for.

    Example:
        /hotplug
        This lists all config symbols that contain "hotplug",
        e.g., HOTPLUG, HOTPLUG_CPU, MEMORY_HOTPLUG.

    For search help, enter / followed TAB-TAB-TAB (to highlight
    ) and Enter.  This will tell you that you can also use
    regular expressions (regexes) in the search string, so if you
    are not interested in MEMORY_HOTPLUG, you could try

        /^hotplug

______________________________________________________________________
User interface options for 'menuconfig'

MENUCONFIG_COLOR
--------------------------------------------------
It is possible to select different color themes using the variable
MENUCONFIG_COLOR.  To select a theme use:

    make MENUCONFIG_COLOR= menuconfig

Available themes are:
  mono       => selects colors suitable for monochrome displays
  blackbg    => selects a color scheme with black background
  classic    => theme with blue background. The classic look
  bluetitle  => a LCD friendly version of classic. (default)

MENUCONFIG_MODE
--------------------------------------------------
This mode shows all sub-menus in one large tree.

Example:
    make MENUCONFIG_MODE=single_menu menuconfig


======================================================================
xconfig
--------------------------------------------------

Searching in xconfig:

    The Search function searches for kernel configuration symbol
    names, so you have to know something close to what you are
    looking for.

    Example:
        Ctrl-F hotplug
    or
        Menu: File, Search, hotplug

    lists all config symbol entries that contain "hotplug" in
    the symbol name.  In this Search dialog, you may change the
    config setting for any of the entries that are not grayed out.
    You can also enter a different search string without having
    to return to the main menu.


======================================================================
gconfig
--------------------------------------------------

Searching in gconfig:

    None (gconfig isn't maintained as well as xconfig or menuconfig);
    however, gconfig does have a few more viewing choices than
    xconfig does.

###

 

kconfig-language

Introduction
------------

The configuration database is a collection of configuration options
organized in a tree structure:

    +- Code maturity level options
    |  +- Prompt for development and/or incomplete code/drivers
    +- General setup
    |  +- Networking support
    |  +- System V IPC
    |  +- BSD Process Accounting
    |  +- Sysctl support
    +- Loadable module support
    |  +- Enable loadable module support
    |     +- Set version information on all module symbols
    |     +- Kernel module loader
    +- ...

Every entry has its own dependencies. These dependencies are used
to determine the visibility of an entry. Any child entry is only
visible if its parent entry is also visible.

Menu entries
------------

Most entries define a config option; all other entries help to organize
them. A single configuration option is defined like this:

config MODVERSIONS
    bool "Set version information on all module symbols"
    depends on MODULES
    help
      Usually, modules have to be recompiled whenever you switch to a new
      kernel.  ...

Every line starts with a key word and can be followed by multiple
arguments.  "config" starts a new config entry. The following lines
define attributes for this config option. Attributes can be the type of
the config option, input prompt, dependencies, help text and default
values. A config option can be defined multiple times with the same
name, but every definition can have only a single input prompt and the
type must not conflict.

Menu attributes
---------------

A menu entry can have a number of attributes. Not all of them are
applicable everywhere (see syntax).

- type definition: "bool"/"tristate"/"string"/"hex"/"int"
  Every config option must have a type. There are only two basic types:
  tristate and string; the other types are based on these two. The type
  definition optionally accepts an input prompt, so these two examples
  are equivalent:

    bool "Networking support"
  and
    bool
    prompt "Networking support"

- input prompt: "prompt"  ["if" <expr>]
  Every menu entry can have at most one prompt, which is used to display
  to the user. Optionally dependencies only for this prompt can be added
  with "if".

- default value: "default" <expr> ["if" <expr>]
  A config option can have any number of default values. If multiple
  default values are visible, only the first defined one is active.
  Default values are not limited to the menu entry where they are
  defined. This means the default can be defined somewhere else or be
  overridden by an earlier definition.
  The default value is only assigned to the config symbol if no other
  value was set by the user (via the input prompt above). If an input
  prompt is visible the default value is presented to the user and can
  be overridden by him.
  Optionally, dependencies only for this default value can be added with
  "if".

- type definition + default value:
    "def_bool"/"def_tristate" <expr> ["if" <expr>]
  This is a shorthand notation for a type definition plus a value.
  Optionally dependencies for this default value can be added with "if".

- dependencies: "depends on" <expr>
  This defines a dependency for this menu entry. If multiple
  dependencies are defined, they are connected with '&&'. Dependencies
  are applied to all other options within this menu entry (which also
  accept an "if" expression), so these two examples are equivalent:

    bool "foo" if BAR
    default y if BAR
  and
    depends on BAR
    bool "foo"
    default y

- reverse dependencies: "select"  ["if" <expr>]
  While normal dependencies reduce the upper limit of a symbol (see
  below), reverse dependencies can be used to force a lower limit of
  another symbol. The value of the current menu symbol is used as the
  minimal value  can be set to. If  is selected multiple
  times, the limit is set to the largest selection.
  Reverse dependencies can only be used with boolean or tristate
  symbols.
  Note:
    select should be used with care. select will force
    a symbol to a value without visiting the dependencies.
    By abusing select you are able to select a symbol FOO even
    if FOO depends on BAR that is not set.
    In general use select only for non-visible symbols
    (no prompts anywhere) and for symbols with no dependencies.
    That will limit the usefulness but on the other hand avoid
    the illegal configurations all over.

- limiting menu display: "visible if" <expr>
  This attribute is only applicable to menu blocks, if the condition is
  false, the menu block is not displayed to the user (the symbols
  contained there can still be selected by other symbols, though). It is
  similar to a conditional "prompt" attribute for individual menu
  entries. Default value of "visible" is true.

- numerical ranges: "range"   ["if" <expr>]
  This allows to limit the range of possible input values for int
  and hex symbols. The user can only input a value which is larger than
  or equal to the first symbol and smaller than or equal to the second
  symbol.

- help text: "help" or "---help---"
  This defines a help text. The end of the help text is determined by
  the indentation level, this means it ends at the first line which has
  a smaller indentation than the first line of the help text.
  "---help---" and "help" do not differ in behaviour, "---help---" is
  used to help visually separate configuration logic from help within
  the file as an aid to developers.

- misc options: "option" [=]
  Various less common options can be defined via this option syntax,
  which can modify the behaviour of the menu entry and its config
  symbol. These options are currently possible:

  - "defconfig_list"
    This declares a list of default entries which can be used when
    looking for the default configuration (which is used when the main
    .config doesn't exists yet.)

  - "modules"
    This declares the symbol to be used as the MODULES symbol, which
    enables the third modular state for all config symbols.

  - "env"=
    This imports the environment variable into Kconfig. It behaves like
    a default, except that the value comes from the environment, this
    also means that the behaviour when mixing it with normal defaults is
    undefined at this point. The symbol is currently not exported back
    to the build environment (if this is desired, it can be done via
    another symbol).

Menu dependencies
-----------------

Dependencies define the visibility of a menu entry and can also reduce
the input range of tristate symbols. The tristate logic used in the
expressions uses one more state than normal boolean logic to express the
module state. Dependency expressions have the following syntax:

<expr> ::=                              (1)
            '='                 (2)
            '!='                (3)
           '(' <expr> ')'                       (4)
           '!' <expr>                           (5)
           <expr> '&&' <expr>                   (6)
           <expr> '||' <expr>                   (7)

Expressions are listed in decreasing order of precedence. 

(1) Convert the symbol into an expression. Boolean and tristate symbols
    are simply converted into the respective expression values. All
    other symbol types result in 'n'.
(2) If the values of both symbols are equal, it returns 'y',
    otherwise 'n'.
(3) If the values of both symbols are equal, it returns 'n',
    otherwise 'y'.
(4) Returns the value of the expression. Used to override precedence.
(5) Returns the result of (2-/expr/).
(6) Returns the result of min(/expr/, /expr/).
(7) Returns the result of max(/expr/, /expr/).

An expression can have a value of 'n', 'm' or 'y' (or 0, 1, 2
respectively for calculations). A menu entry becomes visible when its
expression evaluates to 'm' or 'y'.

There are two types of symbols: constant and non-constant symbols.
Non-constant symbols are the most common ones and are defined with the
'config' statement. Non-constant symbols consist entirely of alphanumeric
characters or underscores.
Constant symbols are only part of expressions. Constant symbols are
always surrounded by single or double quotes. Within the quote, any
other character is allowed and the quotes can be escaped using '\'.

Menu structure
--------------

The position of a menu entry in the tree is determined in two ways. First
it can be specified explicitly:

menu "Network device support"
    depends on NET

config NETDEVICES
    ...

endmenu

All entries within the "menu" ... "endmenu" block become a submenu of
"Network device support". All subentries inherit the dependencies from
the menu entry, e.g. this means the dependency "NET" is added to the
dependency list of the config option NETDEVICES.

The other way to generate the menu structure is done by analyzing the
dependencies. If a menu entry somehow depends on the previous entry, it
can be made a submenu of it. First, the previous (parent) symbol must
be part of the dependency list and then one of these two conditions
must be true:
- the child entry must become invisible, if the parent is set to 'n'
- the child entry must only be visible, if the parent is visible

config MODULES
    bool "Enable loadable module support"

config MODVERSIONS
    bool "Set version information on all module symbols"
    depends on MODULES

comment "module support disabled"
    depends on !MODULES

MODVERSIONS directly depends on MODULES, this means it's only visible if
MODULES is different from 'n'. The comment on the other hand is always
visible when MODULES is visible (the (empty) dependency of MODULES is
also part of the comment dependencies).


Kconfig syntax
--------------

The configuration file describes a series of menu entries, where every
line starts with a keyword (except help texts). The following keywords
end a menu entry:
- config
- menuconfig
- choice/endchoice
- comment
- menu/endmenu
- if/endif
- source
The first five also start the definition of a menu entry.

config:

    "config" 
    

This defines a config symbol  and accepts any of above
attributes as options.

menuconfig:
    "menuconfig" 
    

This is similar to the simple config entry above, but it also gives a
hint to front ends, that all suboptions should be displayed as a
separate list of options.

choices:

    "choice" [symbol]
    
    
    "endchoice"

This defines a choice group and accepts any of the above attributes as
options. A choice can only be of type bool or tristate, while a boolean
choice only allows a single config entry to be selected, a tristate
choice also allows any number of config entries to be set to 'm'. This
can be used if multiple drivers for a single hardware exists and only a
single driver can be compiled/loaded into the kernel, but all drivers
can be compiled as modules.
A choice accepts another option "optional", which allows to set the
choice to 'n' and no entry needs to be selected.
If no [symbol] is associated with a choice, then you can not have multiple
definitions of that choice. If a [symbol] is associated to the choice,
then you may define the same choice (ie. with the same entries) in another
place.

comment:

    "comment" 
    

This defines a comment which is displayed to the user during the
configuration process and is also echoed to the output files. The only
possible options are dependencies.

menu:

    "menu" 
    
    
    "endmenu"

This defines a menu block, see "Menu structure" above for more
information. The only possible options are dependencies and "visible"
attributes.

if:

    "if" <expr>
    <if block>
    "endif"

This defines an if block. The dependency expression <expr> is appended
to all enclosed menu entries.

source:

    "source" 

This reads the specified configuration file. This file is always parsed.

mainmenu:

    "mainmenu" 

This sets the config program's title bar if the config program chooses
to use it. It should be placed at the top of the configuration, before any
other statement.


Kconfig hints
-------------
This is a collection of Kconfig tips, most of which aren't obvious at
first glance and most of which have become idioms in several Kconfig
files.

Adding common features and make the usage configurable
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
It is a common idiom to implement a feature/functionality that are
relevant for some architectures but not all.
The recommended way to do so is to use a config variable named HAVE_*
that is defined in a common Kconfig file and selected by the relevant
architectures.
An example is the generic IOMAP functionality.

We would in lib/Kconfig see:

# Generic IOMAP is used to ...
config HAVE_GENERIC_IOMAP

config GENERIC_IOMAP
    depends on HAVE_GENERIC_IOMAP && FOO

And in lib/Makefile we would see:
obj-$(CONFIG_GENERIC_IOMAP) += iomap.o

For each architecture using the generic IOMAP functionality we would see:

config X86
    select ...
    select HAVE_GENERIC_IOMAP
    select ...

Note: we use the existing config option and avoid creating a new
config variable to select HAVE_GENERIC_IOMAP.

Note: the use of the internal config variable HAVE_GENERIC_IOMAP, it is
introduced to overcome the limitation of select which will force a
config option to 'y' no matter the dependencies.
The dependencies are moved to the symbol GENERIC_IOMAP and we avoid the
situation where select forces a symbol equals to 'y'.

Build as module only
~~~~~~~~~~~~~~~~~~~~
To restrict a component build to module-only, qualify its config symbol
with "depends on m".  E.g.:

config FOO
    depends on BAR && m

limits FOO to module (=m) or disabled (=n).

Kconfig symbol existence
~~~~~~~~~~~~~~~~~~~~~~~~
The following two methods produce the same kconfig symbol dependencies
but differ greatly in kconfig symbol existence (production) in the
generated config file.

case 1:

config FOO
    tristate "about foo"
    depends on BAR

vs. case 2:

if BAR
config FOO
    tristate "about foo"
endif

In case 1, the symbol FOO will always exist in the config file (given
no other dependencies).  In case 2, the symbol FOO will only exist in
the config file if BAR is enabled.

 

makefiles

Linux Kernel Makefiles

This document describes the Linux kernel Makefiles.

=== Table of Contents

    === 1 Overview
    === 2 Who does what
    === 3 The kbuild files
       --- 3.1 Goal definitions
       --- 3.2 Built-in object goals - obj-y
       --- 3.3 Loadable module goals - obj-m
       --- 3.4 Objects which export symbols
       --- 3.5 Library file goals - lib-y
       --- 3.6 Descending down in directories
       --- 3.7 Compilation flags
       --- 3.8 Command line dependency
       --- 3.9 Dependency tracking
       --- 3.10 Special Rules
       --- 3.11 $(CC) support functions
       --- 3.12 $(LD) support functions

    === 4 Host Program support
       --- 4.1 Simple Host Program
       --- 4.2 Composite Host Programs
       --- 4.3 Defining shared libraries
       --- 4.4 Using C++ for host programs
       --- 4.5 Controlling compiler options for host programs
       --- 4.6 When host programs are actually built
       --- 4.7 Using hostprogs-$(CONFIG_FOO)

    === 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

    === 7 Kbuild syntax for exported headers
        --- 7.1 header-y
        --- 7.2 objhdr-y
        --- 7.3 destination-y
        --- 7.4 generic-y

    === 8 Kbuild Variables
    === 9 Makefile language
    === 10 Credits
    === 11 TODO

=== 1 Overview

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    there are about 500 of these.

The top Makefile reads the .config file, which comes from the kernel
configuration process.

The top Makefile is responsible for building two major products: vmlinux
(the resident kernel image) and modules (any module files).
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
architecture-specific information to the top Makefile.

Each subdirectory has a kbuild Makefile which carries out the commands
passed down from above. The kbuild Makefile uses information from the
.config file to construct various file lists used by kbuild to build
any built-in or modular targets.

scripts/Makefile.* contains all the definitions/rules etc. that
are used to build the kernel based on the kbuild makefiles.


=== 2 Who does what

People have four different relationships with the kernel Makefiles.

*Users* are people who build kernels.  These people type commands such as
"make menuconfig" or "make".  They usually do not read or edit
any kernel Makefiles (or any other source files).

*Normal developers* are people who work on features such as device
drivers, file systems, and network protocols.  These people need to
maintain the kbuild Makefiles for the subsystem they are
working on.  In order to do this effectively, they need some overall
knowledge about the kernel Makefiles, plus detailed knowledge about the
public interface for kbuild.

*Arch developers* are people who work on an entire architecture, such
as sparc or ia64.  Arch developers need to know about the arch Makefile
as well as kbuild Makefiles.

*Kbuild developers* are people who work on the kernel build system itself.
These people need to know about all aspects of the kernel Makefiles.

This document is aimed towards normal developers and arch developers.


=== 3 The kbuild files

Most Makefiles within the kernel are kbuild Makefiles that use the
kbuild infrastructure. This chapter introduces the syntax used in the
kbuild makefiles.
The preferred name for the kbuild files are 'Makefile' but 'Kbuild' can
be used and if both a 'Makefile' and a 'Kbuild' file exists, then the 'Kbuild'
file will be used.

Section 3.1 "Goal definitions" is a quick intro, further chapters provide
more details, with real examples.

--- 3.1 Goal definitions

    Goal definitions are the main part (heart) of the kbuild Makefile.
    These lines define the files to be built, any special compilation
    options, and any subdirectories to be entered recursively.

    The most simple kbuild makefile contains one line:

    Example:
        obj-y += foo.o

    This tells kbuild that there is one object in that directory, named
    foo.o. foo.o will be built from foo.c or foo.S.

    If foo.o shall be built as a module, the variable obj-m is used.
    Therefore the following pattern is often used:

    Example:
        obj-$(CONFIG_FOO) += foo.o

    $(CONFIG_FOO) evaluates to either y (for built-in) or m (for module).
    If CONFIG_FOO is neither y nor m, then the file will not be compiled
    nor linked.

--- 3.2 Built-in object goals - obj-y

    The kbuild Makefile specifies object files for vmlinux
    in the $(obj-y) lists.  These lists depend on the kernel
    configuration.

    Kbuild compiles all the $(obj-y) files.  It then calls
    "$(LD) -r" to merge these files into one built-in.o file.
    built-in.o is later linked into vmlinux by the parent Makefile.

    The order of files in $(obj-y) is significant.  Duplicates in
    the lists are allowed: the first instance will be linked into
    built-in.o and succeeding instances will be ignored.

    Link order is significant, because certain functions
    (module_init() / __initcall) will be called during boot in the
    order they appear. So keep in mind that changing the link
    order may e.g. change the order in which your SCSI
    controllers are detected, and thus your disks are renumbered.

    Example:
        #drivers/isdn/i4l/Makefile
        # Makefile for the kernel ISDN subsystem and device drivers.
        # Each configuration option enables a list of files.
        obj-$(CONFIG_ISDN_I4L)         += isdn.o
        obj-$(CONFIG_ISDN_PPP_BSDCOMP) += isdn_bsdcomp.o

--- 3.3 Loadable module goals - obj-m

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

    A module may be built from one source file or several source
    files. In the case of one source file, the kbuild makefile
    simply adds the file to $(obj-m).

    Example:
        #drivers/isdn/i4l/Makefile
        obj-$(CONFIG_ISDN_PPP_BSDCOMP) += isdn_bsdcomp.o

    Note: In this example $(CONFIG_ISDN_PPP_BSDCOMP) evaluates to 'm'

    If a kernel module is built from several source files, you specify
    that you want to build a module in the same way as above; however,
    kbuild needs to know which object files you want to build your
    module from, so you have to tell it by setting a $(-y)
    variable.

    Example:
        #drivers/isdn/i4l/Makefile
        obj-$(CONFIG_ISDN_I4L) += isdn.o
        isdn-y := isdn_net_lib.o isdn_v110.o isdn_common.o

    In this example, the module name will be isdn.o. Kbuild will
    compile the objects listed in $(isdn-y) and then run
    "$(LD) -r" on the list of these files to generate isdn.o.

    Due to kbuild recognizing $(-y) for composite objects,
    you can use the value of a CONFIG_ symbol to optionally include an
    object file as part of a composite object.

    Example:
        #fs/ext2/Makefile
            obj-$(CONFIG_EXT2_FS) += ext2.o
        ext2-y := balloc.o dir.o file.o ialloc.o inode.o ioctl.o \
              namei.o super.o symlink.o
            ext2-$(CONFIG_EXT2_FS_XATTR) += xattr.o xattr_user.o \
                        xattr_trusted.o

    In this example, xattr.o, xattr_user.o and xattr_trusted.o are only
    part of the composite object ext2.o if $(CONFIG_EXT2_FS_XATTR)
    evaluates to 'y'.

    Note: Of course, when you are building objects into the kernel,
    the syntax above will also work. So, if you have CONFIG_EXT2_FS=y,
    kbuild will build an ext2.o file for you out of the individual
    parts and then link this into built-in.o, as you would expect.

--- 3.4 Objects which export symbols

    No special notation is required in the makefiles for
    modules exporting symbols.

--- 3.5 Library file goals - lib-y

    Objects listed with obj-* are used for modules, or
    combined in a built-in.o for that specific directory.
    There is also the possibility to list objects that will
    be included in a library, lib.a.
    All objects listed with lib-y are combined in a single
    library for that directory.
    Objects that are listed in obj-y and additionally listed in
    lib-y will not be included in the library, since they will
    be accessible anyway.
    For consistency, objects listed in lib-m will be included in lib.a.

    Note that the same kbuild makefile may list files to be built-in
    and to be part of a library. Therefore the same directory
    may contain both a built-in.o and a lib.a file.

    Example:
        #arch/x86/lib/Makefile
        lib-y    := delay.o

    This will create a library lib.a based on delay.o. For kbuild to
    actually recognize that there is a lib.a being built, the directory
    shall be listed in libs-y.
    See also "6.4 List directories to visit when descending".

    Use of lib-y is normally restricted to lib/ and arch/*/lib.

--- 3.6 Descending down in directories

    A Makefile is only responsible for building objects in its own
    directory. Files in subdirectories should be taken care of by
    Makefiles in these subdirs. The build system will automatically
    invoke make recursively in subdirectories, provided you let it know of
    them.

    To do so, obj-y and obj-m are used.
    ext2 lives in a separate directory, and the Makefile present in fs/
    tells kbuild to descend down using the following assignment.

    Example:
        #fs/Makefile
        obj-$(CONFIG_EXT2_FS) += ext2/

    If CONFIG_EXT2_FS is set to either 'y' (built-in) or 'm' (modular)
    the corresponding obj- variable will be set, and kbuild will descend
    down in the ext2 directory.
    Kbuild only uses this information to decide that it needs to visit
    the directory, it is the Makefile in the subdirectory that
    specifies what is modules and what is built-in.

    It is good practice to use a CONFIG_ variable when assigning directory
    names. This allows kbuild to totally skip the directory if the
    corresponding CONFIG_ option is neither 'y' nor 'm'.

--- 3.7 Compilation flags

    ccflags-y, asflags-y and ldflags-y
    These three flags apply only to the kbuild makefile in which they
    are assigned. They are used for all the normal cc, as and ld
    invocations happening during a recursive build.
    Note: Flags with the same behaviour were previously named:
    EXTRA_CFLAGS, EXTRA_AFLAGS and EXTRA_LDFLAGS.
    They are still supported but their usage is deprecated.

    ccflags-y specifies options for compiling with $(CC).

    Example:
        # drivers/acpi/Makefile
        ccflags-y := -Os
        ccflags-$(CONFIG_ACPI_DEBUG) += -DACPI_DEBUG_OUTPUT

    This variable is necessary because the top Makefile owns the
    variable $(KBUILD_CFLAGS) and uses it for compilation flags for the
    entire tree.

    asflags-y specifies options for assembling with $(AS).

    Example:
        #arch/sparc/kernel/Makefile
        asflags-y := -ansi

    ldflags-y specifies options for linking with $(LD).

    Example:
        #arch/cris/boot/compressed/Makefile
        ldflags-y += -T $(srctree)/$(src)/decompress_$(arch-y).lds

    subdir-ccflags-y, subdir-asflags-y
    The two flags listed above are similar to ccflags-y and asflags-y.
    The difference is that the subdir- variants have effect for the kbuild
    file where they are present and all subdirectories.
    Options specified using subdir-* are added to the commandline before
    the options specified using the non-subdir variants.

    Example:
        subdir-ccflags-y := -Werror

    CFLAGS_$@, AFLAGS_$@

    CFLAGS_$@ and AFLAGS_$@ only apply to commands in current
    kbuild makefile.

    $(CFLAGS_$@) specifies per-file options for $(CC).  The $@
    part has a literal value which specifies the file that it is for.

    Example:
        # drivers/scsi/Makefile
        CFLAGS_aha152x.o =   -DAHA152X_STAT -DAUTOCONF
        CFLAGS_gdth.o    = # -DDEBUG_GDTH=2 -D__SERIAL__ -D__COM2__ \
                     -DGDTH_STATISTICS

    These two lines specify compilation flags for aha152x.o and gdth.o.

    $(AFLAGS_$@) is a similar feature for source files in assembly
    languages.

    Example:
        # arch/arm/kernel/Makefile
        AFLAGS_head.o        := -DTEXT_OFFSET=$(TEXT_OFFSET)
        AFLAGS_crunch-bits.o := -Wa,-mcpu=ep9312
        AFLAGS_iwmmxt.o      := -Wa,-mcpu=iwmmxt


--- 3.9 Dependency tracking

    Kbuild tracks dependencies on the following:
    1) All prerequisite files (both *.c and *.h)
    2) CONFIG_ options used in all prerequisite files
    3) Command-line used to compile target

    Thus, if you change an option to $(CC) all affected files will
    be re-compiled.

--- 3.10 Special Rules

    Special rules are used when the kbuild infrastructure does
    not provide the required support. A typical example is
    header files generated during the build process.
    Another example are the architecture-specific Makefiles which
    need special rules to prepare boot images etc.

    Special rules are written as normal Make rules.
    Kbuild is not executing in the directory where the Makefile is
    located, so all special rules shall provide a relative
    path to prerequisite files and target files.

    Two variables are used when defining special rules:

    $(src)
    $(src) is a relative path which points to the directory
    where the Makefile is located. Always use $(src) when
    referring to files located in the src tree.

    $(obj)
    $(obj) is a relative path which points to the directory
    where the target is saved. Always use $(obj) when
    referring to generated files.

    Example:
        #drivers/scsi/Makefile
        $(obj)/53c8xx_d.h: $(src)/53c7,8xx.scr $(src)/script_asm.pl
            $(CPP) -DCHIP=810 - < $< | ... $(src)/script_asm.pl

    This is a special rule, following the normal syntax
    required by make.
    The target file depends on two prerequisite files. References
    to the target file are prefixed with $(obj), references
    to prerequisites are referenced with $(src) (because they are not
    generated files).

    $(kecho)
    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
    except for warnings/errors.
    To support this kbuild define $(kecho) which will echo out the
    text following $(kecho) to stdout except if "make -s" is used.

    Example:
        #arch/blackfin/boot/Makefile
        $(obj)/vmImage: $(obj)/vmlinux.gz
            $(call if_changed,uimage)
            @$(kecho) 'Kernel: $@ is ready'


--- 3.11 $(CC) support functions

    The kernel may be built with several different versions of
    $(CC), each supporting a unique set of features and options.
    kbuild provide basic support to check for valid options for $(CC).
    $(CC) is usually the gcc compiler, but other alternatives are
    available.

    as-option
    as-option is used to check if $(CC) -- when used to compile
    assembler (*.S) files -- supports the given option. An optional
    second option may be specified if the first option is not supported.

    Example:
        #arch/sh/Makefile
        cflags-y += $(call as-option,-Wa$(comma)-isa=$(isa-y),)

    In the above example, cflags-y will be assigned the option
    -Wa$(comma)-isa=$(isa-y) if it is supported by $(CC).
    The second argument is optional, and if supplied will be used
    if first argument is not supported.

    cc-ldoption
    cc-ldoption is used to check if $(CC) when used to link object files
    supports the given option.  An optional second option may be
    specified if first option are not supported.

    Example:
        #arch/x86/kernel/Makefile
        vsyscall-flags += $(call cc-ldoption, -Wl$(comma)--hash-style=sysv)

    In the above example, vsyscall-flags will be assigned the option
    -Wl$(comma)--hash-style=sysv if it is supported by $(CC).
    The second argument is optional, and if supplied will be used
    if first argument is not supported.

    as-instr
    as-instr checks if the assembler reports a specific instruction
    and then outputs either option1 or option2
    C escapes are supported in the test instruction
    Note: as-instr-option uses KBUILD_AFLAGS for $(AS) options

    cc-option
    cc-option is used to check if $(CC) supports a given option, and not
    supported to use an optional second option.

    Example:
        #arch/x86/Makefile
        cflags-y += $(call cc-option,-march=pentium-mmx,-march=i586)

    In the above example, cflags-y will be assigned the option
    -march=pentium-mmx if supported by $(CC), otherwise -march=i586.
    The second argument to cc-option is optional, and if omitted,
    cflags-y will be assigned no value if first option is not supported.
    Note: cc-option uses KBUILD_CFLAGS for $(CC) options

   cc-option-yn
    cc-option-yn is used to check if gcc supports a given option
    and return 'y' if supported, otherwise 'n'.

    Example:
        #arch/ppc/Makefile
        biarch := $(call cc-option-yn, -m32)
        aflags-$(biarch) += -a32
        cflags-$(biarch) += -m32

    In the above example, $(biarch) is set to y if $(CC) supports the -m32
    option. When $(biarch) equals 'y', the expanded variables $(aflags-y)
    and $(cflags-y) will be assigned the values -a32 and -m32,
    respectively.
    Note: cc-option-yn uses KBUILD_CFLAGS for $(CC) options

    cc-option-align
    gcc versions >= 3.0 changed the type of options used to specify
    alignment of functions, loops etc. $(cc-option-align), when used
    as prefix to the align options, will select the right prefix:
    gcc < 3.00
        cc-option-align = -malign
    gcc >= 3.00
        cc-option-align = -falign

    Example:
        KBUILD_CFLAGS += $(cc-option-align)-functions=4

    In the above example, the option -falign-functions=4 is used for
    gcc >= 3.00. For gcc < 3.00, -malign-functions=4 is used.
    Note: cc-option-align uses KBUILD_CFLAGS for $(CC) options

    cc-disable-warning
    cc-disable-warning checks if gcc supports a given warning and returns
    the commandline switch to disable it. This special function is needed,
    because gcc 4.4 and later accept any unknown -Wno-* option and only
    warn about it if there is another warning in the source file.

    Example:
        KBUILD_CFLAGS += $(call cc-disable-warning, unused-but-set-variable)

    In the above example, -Wno-unused-but-set-variable will be added to
    KBUILD_CFLAGS only if gcc really accepts it.

    cc-version
    cc-version returns a numerical version of the $(CC) compiler version.
    The format is  where both are two digits. So for example
    gcc 3.41 would return 0341.
    cc-version is useful when a specific $(CC) version is faulty in one
    area, for example -mregparm=3 was broken in some gcc versions
    even though the option was accepted by gcc.

    Example:
        #arch/x86/Makefile
        cflags-y += $(shell \
        if [ $(call cc-version) -ge 0300 ] ; then \
            echo "-mregparm=3"; fi ;)

    In the above example, -mregparm=3 is only used for gcc version greater
    than or equal to gcc 3.0.

    cc-ifversion
    cc-ifversion tests the version of $(CC) and equals last argument if
    version expression is true.

    Example:
        #fs/reiserfs/Makefile
        ccflags-y := $(call cc-ifversion, -lt, 0402, -O1)

    In this example, ccflags-y will be assigned the value -O1 if the
    $(CC) version is less than 4.2.
    cc-ifversion takes all the shell operators:
    -eq, -ne, -lt, -le, -gt, and -ge
    The third parameter may be a text as in this example, but it may also
    be an expanded variable or a macro.

    cc-fullversion
    cc-fullversion is useful when the exact version of gcc is needed.
    One typical use-case is when a specific GCC version is broken.
    cc-fullversion points out a more specific version than cc-version does.

    Example:
        #arch/powerpc/Makefile
        $(Q)if test "$(call cc-fullversion)" = "040200" ; then \
            echo -n '*** GCC-4.2.0 cannot compile the 64-bit powerpc ' ; \
            false ; \
        fi

    In this example for a specific GCC version the build will error out explaining
    to the user why it stops.

    cc-cross-prefix
    cc-cross-prefix is used to check if there exists a $(CC) in path with
    one of the listed prefixes. The first prefix where there exist a
    prefix$(CC) in the PATH is returned - and if no prefix$(CC) is found
    then nothing is returned.
    Additional prefixes are separated by a single space in the
    call of cc-cross-prefix.
    This functionality is useful for architecture Makefiles that try
    to set CROSS_COMPILE to well-known values but may have several
    values to select between.
    It is recommended only to try to set CROSS_COMPILE if it is a cross
    build (host arch is different from target arch). And if CROSS_COMPILE
    is already set then leave it with the old value.

    Example:
        #arch/m68k/Makefile
        ifneq ($(SUBARCH),$(ARCH))
                ifeq ($(CROSS_COMPILE),)
                       CROSS_COMPILE := $(call cc-cross-prefix, m68k-linux-gnu-)
            endif
        endif

--- 3.12 $(LD) support functions

    ld-option
    ld-option is used to check if $(LD) supports the supplied option.
    ld-option takes two options as arguments.
    The second argument is an optional option that can be used if the
    first option is not supported by $(LD).

    Example:
        #Makefile
        LDFLAGS_vmlinux += $(call really-ld-option, -X)


=== 4 Host Program support

Kbuild supports building executables on the host for use during the
compilation stage.
Two steps are required in order to use a host executable.

The first step is to tell kbuild that a host program exists. This is
done utilising the variable hostprogs-y.

The second step is to add an explicit dependency to the executable.
This can be done in two ways. Either add the dependency in a rule,
or utilise the variable $(always).
Both possibilities are described in the following.

--- 4.1 Simple Host Program

    In some cases there is a need to compile and run a program on the
    computer where the build is running.
    The following line tells kbuild that the program bin2hex shall be
    built on the build host.

    Example:
        hostprogs-y := bin2hex

    Kbuild assumes in the above example that bin2hex is made from a single
    c-source file named bin2hex.c located in the same directory as
    the Makefile.

--- 4.2 Composite Host Programs

    Host programs can be made up based on composite objects.
    The syntax used to define composite objects for host programs is
    similar to the syntax used for kernel objects.
    $(-objs) lists all objects used to link the final
    executable.

    Example:
        #scripts/lxdialog/Makefile
        hostprogs-y   := lxdialog
        lxdialog-objs := checklist.o lxdialog.o

    Objects with extension .o are compiled from the corresponding .c
    files. In the above example, checklist.c is compiled to checklist.o
    and lxdialog.c is compiled to lxdialog.o.
    Finally, the two .o files are linked to the executable, lxdialog.
    Note: The syntax -y is not permitted for host-programs.

--- 4.3 Defining shared libraries

    Objects with extension .so are considered shared libraries, and
    will be compiled as position independent objects.
    Kbuild provides support for shared libraries, but the usage
    shall be restricted.
    In the following example the libkconfig.so shared library is used
    to link the executable conf.

    Example:
        #scripts/kconfig/Makefile
        hostprogs-y     := conf
        conf-objs       := conf.o libkconfig.so
        libkconfig-objs := expr.o type.o

    Shared libraries always require a corresponding -objs line, and
    in the example above the shared library libkconfig is composed by
    the two objects expr.o and type.o.
    expr.o and type.o will be built as position independent code and
    linked as a shared library libkconfig.so. C++ is not supported for
    shared libraries.

--- 4.4 Using C++ for host programs

    kbuild offers support for host programs written in C++. This was
    introduced solely to support kconfig, and is not recommended
    for general use.

    Example:
        #scripts/kconfig/Makefile
        hostprogs-y   := qconf
        qconf-cxxobjs := qconf.o

    In the example above the executable is composed of the C++ file
    qconf.cc - identified by $(qconf-cxxobjs).

    If qconf is composed by a mixture of .c and .cc files, then an
    additional line can be used to identify this.

    Example:
        #scripts/kconfig/Makefile
        hostprogs-y   := qconf
        qconf-cxxobjs := qconf.o
        qconf-objs    := check.o

--- 4.5 Controlling compiler options for host programs

    When compiling host programs, it is possible to set specific flags.
    The programs will always be compiled utilising $(HOSTCC) passed
    the options specified in $(HOSTCFLAGS).
    To set flags that will take effect for all host programs created
    in that Makefile, use the variable HOST_EXTRACFLAGS.

    Example:
        #scripts/lxdialog/Makefile
        HOST_EXTRACFLAGS += -I/usr/include/ncurses

    To set specific flags for a single file the following construction
    is used:

    Example:
        #arch/ppc64/boot/Makefile
        HOSTCFLAGS_piggyback.o := -DKERNELBASE=$(KERNELBASE)

    It is also possible to specify additional options to the linker.

    Example:
        #scripts/kconfig/Makefile
        HOSTLOADLIBES_qconf := -L$(QTDIR)/lib

    When linking qconf, it will be passed the extra option
    "-L$(QTDIR)/lib".

--- 4.6 When host programs are actually built

    Kbuild will only build host-programs when they are referenced
    as a prerequisite.
    This is possible in two ways:

    (1) List the prerequisite explicitly in a special rule.

    Example:
        #drivers/pci/Makefile
        hostprogs-y := gen-devlist
        $(obj)/devlist.h: $(src)/pci.ids $(obj)/gen-devlist
            ( cd $(obj); ./gen-devlist ) < $<

    The target $(obj)/devlist.h will not be built before
    $(obj)/gen-devlist is updated. Note that references to
    the host programs in special rules must be prefixed with $(obj).

    (2) Use $(always)
    When there is no suitable special rule, and the host program
    shall be built when a makefile is entered, the $(always)
    variable shall be used.

    Example:
        #scripts/lxdialog/Makefile
        hostprogs-y   := lxdialog
        always        := $(hostprogs-y)

    This will tell kbuild to build lxdialog even if not referenced in
    any rule.

--- 4.7 Using hostprogs-$(CONFIG_FOO)

    A typical pattern in a Kbuild file looks like this:

    Example:
        #scripts/Makefile
        hostprogs-$(CONFIG_KALLSYMS) += kallsyms

    Kbuild knows about both 'y' for built-in and 'm' for module.
    So if a config symbol evaluate to 'm', kbuild will still build
    the binary. In other words, Kbuild handles hostprogs-m exactly
    like hostprogs-y. But only hostprogs-y is recommended to be used
    when no CONFIG symbols are involved.

=== 5 Kbuild clean infrastructure

"make clean" deletes most generated files in the obj tree where the kernel
is compiled. This includes generated files such as host programs.
Kbuild knows targets listed in $(hostprogs-y), $(hostprogs-m), $(always),
$(extra-y) and $(targets). They are all deleted during "make clean".
Files matching the patterns "*.[oas]", "*.ko", plus some additional files
generated by kbuild are deleted all over the kernel src tree when
"make clean" is executed.

Additional files can be specified in kbuild makefiles by use of $(clean-files).

    Example:
        #drivers/pci/Makefile
        clean-files := devlist.h classlist.h

When executing "make clean", the two files "devlist.h classlist.h" will
be deleted. Kbuild will assume files to be in same relative directory as the
Makefile except if an absolute path is specified (path starting with '/').

To delete a directory hierarchy use:

    Example:
        #scripts/package/Makefile
        clean-dirs := $(objtree)/debian/

This will delete the directory debian, including all subdirectories.
Kbuild will assume the directories to be in the same relative path as the
Makefile if no absolute path is specified (path does not start with '/').

To exclude certain files from make clean, use the $(no-clean-files) variable.
This is only a special case used in the top level Kbuild file:

    Example:
        #Kbuild
        no-clean-files := $(bounds-file) $(offsets-file)

Usually kbuild descends down in subdirectories due to "obj-* := dir/",
but in the architecture makefiles where the kbuild infrastructure
is not sufficient this sometimes needs to be explicit.

    Example:
        #arch/x86/boot/Makefile
        subdir- := compressed/

The above assignment instructs kbuild to descend down in the
directory compressed/ when "make clean" is executed.

To support the clean infrastructure in the Makefiles that builds the
final bootimage there is an optional target named archclean:

    Example:
        #arch/x86/Makefile
        archclean:
            $(Q)$(MAKE) $(clean)=arch/x86/boot

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
included in the top level makefile, and the kbuild infrastructure
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

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
for said architecture.
To do so, arch/$(ARCH)/Makefile sets up a number of variables and defines
a few targets.

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) Symlink include/asm to include/asm-$(ARCH)
4) Updating all other prerequisites to the target prepare:
   - Additional prerequisites are specified in arch/$(ARCH)/Makefile
5) 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.
6) 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.
7) Finally, the architecture-specific part does any required post processing
   and builds the final bootimage.
   - This includes building boot records
   - Preparing initrd images and the like


--- 6.1 Set variables to tweak the build to the architecture

    LDFLAGS        Generic $(LD) options

    Flags used for all invocations of the linker.
    Often specifying the emulation is sufficient.

    Example:
        #arch/s390/Makefile
        LDFLAGS         := -m elf_s390
    Note: ldflags-y can be used to further customise
    the flags used. See chapter 3.7.

    LDFLAGS_MODULE    Options for $(LD) when linking modules

    LDFLAGS_MODULE is used to set specific flags for $(LD) when
    linking the .ko files used for modules.
    Default is "-r", for relocatable output.

    LDFLAGS_vmlinux    Options for $(LD) when linking vmlinux

    LDFLAGS_vmlinux is used to specify additional flags to pass to
    the linker when linking the final vmlinux image.
    LDFLAGS_vmlinux uses the LDFLAGS_$@ support.

    Example:
        #arch/x86/Makefile
        LDFLAGS_vmlinux := -e stext

    OBJCOPYFLAGS    objcopy flags

    When $(call if_changed,objcopy) is used to translate a .o file,
    the flags specified in OBJCOPYFLAGS will be used.
    $(call if_changed,objcopy) is often used to generate raw binaries on
    vmlinux.

    Example:
        #arch/s390/Makefile
        OBJCOPYFLAGS := -O binary

        #arch/s390/boot/Makefile
        $(obj)/image: vmlinux FORCE
            $(call if_changed,objcopy)

    In this example, the binary $(obj)/image is a binary version of
    vmlinux. The usage of $(call if_changed,xxx) will be described later.

    KBUILD_AFLAGS        $(AS) assembler flags

    Default value - see top level Makefile
    Append or modify as required per architecture.

    Example:
        #arch/sparc64/Makefile
        KBUILD_AFLAGS += -m64 -mcpu=ultrasparc

    KBUILD_CFLAGS        $(CC) compiler flags

    Default value - see top level Makefile
    Append or modify as required per architecture.

    Often, the KBUILD_CFLAGS variable depends on the configuration.

    Example:
        #arch/x86/Makefile
        cflags-$(CONFIG_M386) += -march=i386
        KBUILD_CFLAGS += $(cflags-y)

    Many arch Makefiles dynamically run the target C compiler to
    probe supported options:

        #arch/x86/Makefile

        ...
        cflags-$(CONFIG_MPENTIUMII)     += $(call cc-option,\
                        -march=pentium2,-march=i686)
        ...
        # Disable unit-at-a-time mode ...
        KBUILD_CFLAGS += $(call cc-option,-fno-unit-at-a-time)
        ...


    The first example utilises the trick that a config option expands
    to 'y' when selected.

    KBUILD_AFLAGS_KERNEL    $(AS) options specific for built-in

    $(KBUILD_AFLAGS_KERNEL) contains extra C compiler flags used to compile
    resident kernel code.

    KBUILD_AFLAGS_MODULE   Options for $(AS) when building modules

    $(KBUILD_AFLAGS_MODULE) is used to add arch specific options that
    are used for $(AS).
    From commandline AFLAGS_MODULE shall be used (see kbuild.txt).

    KBUILD_CFLAGS_KERNEL    $(CC) options specific for built-in

    $(KBUILD_CFLAGS_KERNEL) contains extra C compiler flags used to compile
    resident kernel code.

    KBUILD_CFLAGS_MODULE   Options for $(CC) when building modules

    $(KBUILD_CFLAGS_MODULE) is used to add arch specific options that
    are used for $(CC).
    From commandline CFLAGS_MODULE shall be used (see kbuild.txt).

    KBUILD_LDFLAGS_MODULE   Options for $(LD) when linking modules

    $(KBUILD_LDFLAGS_MODULE) is used to add arch specific options
    used when linking modules. This is often a linker script.
    From commandline LDFLAGS_MODULE shall be used (see kbuild.txt).

    KBUILD_ARFLAGS   Options for $(AR) when creating archives

    $(KBUILD_ARFLAGS) set by the top level Makefile to "D" (deterministic
    mode) if this option is supported by $(AR).

--- 6.2 Add prerequisites to archheaders:

    The archheaders: rule is used to generate header files that
    may be installed into user space by "make header_install" or
    "make headers_install_all".  In order to support
    "make headers_install_all", this target has to be able to run
    on an unconfigured tree, or a tree configured for another
    architecture.

    It is run before "make archprepare" when run on the
    architecture itself.


--- 6.3 Add prerequisites to archprepare:

    The archprepare: rule is used to list prerequisites that need to be
    built before starting to descend down in the subdirectories.
    This is usually used for header files containing assembler constants.

        Example:
        #arch/arm/Makefile
        archprepare: maketools

    In this example, the file target maketools will be processed
    before descending down in the subdirectories.
    See also chapter XXX-TODO that describe how kbuild supports
    generating offset header files.


--- 6.4 List directories to visit when descending

    An arch Makefile cooperates with the top Makefile to define variables
    which specify how to build the vmlinux file.  Note that there is no
    corresponding arch-specific section for modules; the module-building
    machinery is all architecture-independent.


    head-y, init-y, core-y, libs-y, drivers-y, net-y

    $(head-y) lists objects to be linked first in vmlinux.
    $(libs-y) lists directories where a lib.a archive can be located.
    The rest list directories where a built-in.o object file can be
    located.

    $(init-y) objects will be located after $(head-y).
    Then the rest follows in this order:
    $(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 directories.

    Example:
        #arch/sparc64/Makefile
        core-y += arch/sparc64/kernel/
        libs-y += arch/sparc64/prom/ arch/sparc64/lib/
        drivers-$(CONFIG_OPROFILE)  += arch/sparc64/oprofile/


--- 6.5 Architecture-specific boot images

    An arch Makefile specifies goals that take the vmlinux file, compress
    it, wrap it in bootstrapping code, and copy the resulting files
    somewhere. This includes various kinds of installation commands.
    The actual goals are not standardized across architectures.

    It is common to locate any additional processing in a boot/
    directory below arch/$(ARCH)/.

    Kbuild does not provide any smart way to support building a
    target specified in boot/. Therefore arch/$(ARCH)/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.

    Example:
        #arch/x86/Makefile
        boot := arch/x86/boot
        bzImage: vmlinux
            $(Q)$(MAKE) $(build)=$(boot) $(boot)/$@

    "$(Q)$(MAKE) $(build)=" is the recommended way to invoke
    make in a subdirectory.

    There are no rules for naming architecture-specific targets,
    but executing "make help" will list all relevant targets.
    To support this, $(archhelp) must be defined.

    Example:
        #arch/x86/Makefile
        define archhelp
          echo  '* bzImage      - Image (arch/$(ARCH)/boot/bzImage)'
        endif

    When make is executed without arguments, the first goal encountered
    will be built. In the top level Makefile the first goal present
    is all:.
    An architecture shall always, per default, build a bootable image.
    In "make help", the default goal is highlighted with a '*'.
    Add a new prerequisite to all: to select a default goal different
    from vmlinux.

    Example:
        #arch/x86/Makefile
        all: bzImage

    When "make" is executed without arguments, bzImage will be built.

--- 6.6 Building non-kbuild targets

    extra-y

    extra-y specify additional targets created in the current
    directory, in addition to any targets specified by obj-*.

    Listing all targets in extra-y is required for two purposes:
    1) Enable kbuild to check changes in command lines
       - When $(call if_changed,xxx) is used
    2) kbuild knows what files to delete during "make clean"

    Example:
        #arch/x86/kernel/Makefile
        extra-y := head.o init_task.o

    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.o.


--- 6.7 Commands useful for building a boot image

    Kbuild provides a few macros that are useful when building a
    boot image.

    if_changed

    if_changed is the infrastructure used for the following commands.

    Usage:
        target: source(s) FORCE
            $(call if_changed,ld/objcopy/gzip)

    When the rule is evaluated, it is checked to see if any files
    need an update, or the command line has changed since the last
    invocation. The latter will force a rebuild if any options
    to the executable have changed.
    Any target that utilises if_changed must be listed in $(targets),
    otherwise the command line check will fail, and the target will
    always be built.
    Assignments to $(targets) are without $(obj)/ prefix.
    if_changed may be used in conjunction with custom commands as
    defined in 6.8 "Custom kbuild commands".

    Note: It is a typical mistake to forget the FORCE prerequisite.
    Another common pitfall is that whitespace is sometimes
    significant; for instance, the below will fail (note the extra space
    after the comma):
        target: source(s) FORCE
    #WRONG!#    $(call if_changed, ld/objcopy/gzip)

    ld
    Link target. Often, LDFLAGS_$@ is used to set specific options to ld.

    objcopy
    Copy binary. Uses OBJCOPYFLAGS usually specified in
    arch/$(ARCH)/Makefile.
    OBJCOPYFLAGS_$@ may be used to set additional options.

    gzip
    Compress target. Use maximum compression to compress target.

    Example:
        #arch/x86/boot/Makefile
        LDFLAGS_bootsect := -Ttext 0x0 -s --oformat binary
        LDFLAGS_setup    := -Ttext 0x0 -s --oformat binary -e begtext

        targets += setup setup.o bootsect bootsect.o
        $(obj)/setup $(obj)/bootsect: %: %.o FORCE
            $(call if_changed,ld)

    In this example, there are two possible targets, requiring different
    options to the linker. The linker options are specified using the
    LDFLAGS_$@ syntax - one for each potential target.
    $(targets) are assigned all potential targets, by which kbuild knows
    the targets and will:
        1) check for commandline changes
        2) delete target during make clean

    The ": %: %.o" part of the prerequisite is a shorthand that
    free us from listing the setup.o and bootsect.o files.
    Note: It is a common mistake to forget the "target :=" assignment,
          resulting in the target file being recompiled for no
          obvious reason.

    dtc
    Create flattend device tree blob object suitable for linking
    into vmlinux. Device tree blobs linked into vmlinux are placed
    in an init section in the image. Platform code *must* copy the
    blob to non-init memory prior to calling unflatten_device_tree().

    Example:
        #arch/x86/platform/ce4100/Makefile
        clean-files := *dtb.S

        DTC_FLAGS := -p 1024
        obj-y += foo.dtb.o

        $(obj)/%.dtb: $(src)/%.dts
            $(call cmd,dtc)

--- 6.8 Custom kbuild commands

    When kbuild is executing with KBUILD_VERBOSE=0, then only a shorthand
    of a command is normally displayed.
    To enable this behaviour for custom commands kbuild requires
    two variables to be set:
    quiet_cmd_    - what shall be echoed
          cmd_    - the command to execute

    Example:
        #
        quiet_cmd_image = BUILD   $@
              cmd_image = $(obj)/tools/build $(BUILDFLAGS) \
                                             $(obj)/vmlinux.bin > $@

        targets += bzImage
        $(obj)/bzImage: $(obj)/vmlinux.bin $(obj)/tools/build FORCE
            $(call if_changed,image)
            @echo 'Kernel: $@ is ready'

    When updating the $(obj)/bzImage target, the line

    BUILD    arch/x86/boot/bzImage

    will be displayed with "make KBUILD_VERBOSE=0".


--- 6.9 Preprocessing linker scripts

    When the vmlinux image is built, the linker script
    arch/$(ARCH)/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.

    Example:
        #arch/x86/kernel/Makefile
        always := vmlinux.lds

        #Makefile
        export CPPFLAGS_vmlinux.lds += -P -C -U$(ARCH)

    The assignment to $(always) is used to tell kbuild to build the
    target vmlinux.lds.
    The assignment to $(CPPFLAGS_vmlinux.lds) tells kbuild to use the
    specified options when building the target vmlinux.lds.

    When building the *.lds target, kbuild uses the variables:
    KBUILD_CPPFLAGS    : Set in top-level Makefile
    cppflags-y    : May be set in the kbuild makefile
    CPPFLAGS_$(@F)  : Target specific flags.
                      Note that the full filename is used in this
                      assignment.

    The kbuild infrastructure for *lds file are used in several
    architecture-specific files.

--- 6.10 Generic header files

    The directory include/asm-generic contains the header files
    that may be shared between individual architectures.
    The recommended approach how to use a generic header file is
    to list the file in the Kbuild file.
    See "7.4 generic-y" for further info on syntax etc.

=== 7 Kbuild syntax for exported headers

The kernel include a set of headers that is exported to userspace.
Many headers can be exported as-is but other headers require a
minimal pre-processing before they are ready for user-space.
The pre-processing does:
- drop kernel specific annotations
- drop include of compiler.h
- drop all sections that are kernel internal (guarded by ifdef __KERNEL__)

Each relevant directory contains a file name "Kbuild" which specifies the
headers to be exported.
See subsequent chapter for the syntax of the Kbuild file.

    --- 7.1 header-y

    header-y specify header files to be exported.

        Example:
            #include/linux/Kbuild
            header-y += usb/
            header-y += aio_abi.h

    The convention is to list one file per line and
    preferably in alphabetic order.

    header-y also specify which subdirectories to visit.
    A subdirectory is identified by a trailing '/' which
    can be seen in the example above for the usb subdirectory.

    Subdirectories are visited before their parent directories.

    --- 7.2 objhdr-y

    objhdr-y specifies generated files to be exported.
    Generated files are special as they need to be looked
    up in another directory when doing 'make O=...' builds.

        Example:
            #include/linux/Kbuild
            objhdr-y += version.h

    --- 7.3 destination-y

    When an architecture have a set of exported headers that needs to be
    exported to a different directory destination-y is used.
    destination-y specify the destination directory for all exported
    headers in the file where it is present.

        Example:
            #arch/xtensa/platforms/s6105/include/platform/Kbuild
            destination-y := include/linux

    In the example above all exported headers in the Kbuild file
    will be located in the directory "include/linux" when exported.

    --- 7.4 generic-y

    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:

        Example:
            #arch/x86/include/asm/Kbuild
            generic-y += termios.h
            generic-y += rtc.h

    During the prepare phase of the build a wrapper include
    file is generated in the directory:

        arch/$(ARCH)/include/generated/asm

    When a header is exported where the architecture uses
    the generic header a similar wrapper is generated as part
    of the set of exported headers in the directory:

        usr/include/asm

    The generated wrapper will in both cases look like the following:

        Example: termios.h
            #include 

=== 8 Kbuild Variables

The top Makefile exports the following variables:

    VERSION, PATCHLEVEL, SUBLEVEL, EXTRAVERSION

    These variables define the current kernel version.  A few arch
    Makefiles actually use these values directly; they should use
    $(KERNELRELEASE) instead.

    $(VERSION), $(PATCHLEVEL), and $(SUBLEVEL) define the basic
    three-part version number, such as "2", "4", and "0".  These three
    values are always numeric.

    $(EXTRAVERSION) defines an even tinier sublevel for pre-patches
    or additional patches.    It is usually some non-numeric string
    such as "-pre4", and is often blank.

    KERNELRELEASE

    $(KERNELRELEASE) is a single string such as "2.4.0-pre4", suitable
    for constructing installation directory names or showing in
    version strings.  Some arch Makefiles use it for this purpose.

    ARCH

    This variable defines the target architecture, such as "i386",
    "arm", or "sparc". Some kbuild Makefiles test $(ARCH) to
    determine which files to compile.

    By default, the top Makefile sets $(ARCH) to be the same as the
    host system architecture.  For a cross build, a user may
    override the value of $(ARCH) on the command line:

        make ARCH=m68k ...


    INSTALL_PATH

    This variable defines a place for the arch Makefiles to install
    the resident kernel image and System.map file.
    Use this for architecture-specific install targets.

    INSTALL_MOD_PATH, MODLIB

    $(INSTALL_MOD_PATH) specifies a prefix to $(MODLIB) for module
    installation.  This variable is not defined in the Makefile but
    may be passed in by the user if desired.

    $(MODLIB) specifies the directory for module installation.
    The top Makefile defines $(MODLIB) to
    $(INSTALL_MOD_PATH)/lib/modules/$(KERNELRELEASE).  The user may
    override this value on the command line if desired.

    INSTALL_MOD_STRIP

    If this variable is specified, will cause modules to be stripped
    after they are installed.  If INSTALL_MOD_STRIP is '1', then the
    default option --strip-debug will be used.  Otherwise,
    INSTALL_MOD_STRIP value will be used as the option(s) to the strip
    command.


=== 9 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
GNU extensions.

GNU Make supports elementary list-processing functions.  The kernel
Makefiles use a novel style of list building and manipulation with few
"if" statements.

GNU Make has two assignment operators, ":=" and "=".  ":=" performs
immediate evaluation of the right-hand side and stores an actual string
into the left-hand side.  "=" is like a formula definition; it stores the
right-hand side in an unevaluated form and then evaluates this form each
time the left-hand side is used.

There are some cases where "=" is appropriate.  Usually, though, ":="
is the right choice.

=== 10 Credits

Original version made by Michael Elizabeth Chastain, 
Updates by Kai Germaschewski 
Updates by Sam Ravnborg 
Language QA by Jan Engelhardt 

=== 11 TODO

- Describe how kbuild supports shipped files with _shipped.
- Generating offset header files.
- Add more variables to section 7?

 

modules

Building External Modules

This document describes how to build an out-of-tree kernel module.

=== Table of Contents

    === 1 Introduction
    === 2 How to Build External Modules
       --- 2.1 Command Syntax
       --- 2.2 Options
       --- 2.3 Targets
       --- 2.4 Building Separate Files
    === 3. Creating a Kbuild File for an External Module
       --- 3.1 Shared Makefile
       --- 3.2 Separate Kbuild file and Makefile
       --- 3.3 Binary Blobs
       --- 3.4 Building Multiple Modules
    === 4. Include Files
       --- 4.1 Kernel Includes
       --- 4.2 Single Subdirectory
       --- 4.3 Several Subdirectories
    === 5. Module Installation
       --- 5.1 INSTALL_MOD_PATH
       --- 5.2 INSTALL_MOD_DIR
    === 6. Module Versioning
       --- 6.1 Symbols From the Kernel (vmlinux + modules)
       --- 6.2 Symbols and External Modules
       --- 6.3 Symbols From Another External Module
    === 7. Tips & Tricks
       --- 7.1 Testing for CONFIG_FOO_BAR



=== 1. Introduction

"kbuild" is the build system used by the Linux kernel. Modules must use
kbuild to stay compatible with changes in the build infrastructure and
to pick up the right flags to "gcc." Functionality for building modules
both in-tree and out-of-tree is provided. The method for building
either is similar, and all modules are initially developed and built
out-of-tree.

Covered in this document is information aimed at developers interested
in building out-of-tree (or "external") modules. The author of an
external module should supply a makefile that hides most of the
complexity, so one only has to type "make" to build the module. This is
easily accomplished, and a complete example will be presented in
section 3.


=== 2. How to Build External Modules

To build external modules, you must have a prebuilt kernel available
that contains the configuration and header files used in the build.
Also, the kernel must have been built with modules enabled. If you are
using a distribution kernel, there will be a package for the kernel you
are running provided by your distribution.

An alternative is to use the "make" target "modules_prepare." This will
make sure the kernel contains the information required. The target
exists solely as a simple way to prepare a kernel source tree for
building external modules.

NOTE: "modules_prepare" will not build Module.symvers even if
CONFIG_MODVERSIONS is set; therefore, a full kernel build needs to be
executed to make module versioning work.

--- 2.1 Command Syntax

    The command to build an external module is:

        $ make -C  M=$PWD

    The kbuild system knows that an external module is being built
    due to the "M=" option given in the command.

    To build against the running kernel use:

        $ make -C /lib/modules/`uname -r`/build M=$PWD

    Then to install the module(s) just built, add the target
    "modules_install" to the command:

        $ make -C /lib/modules/`uname -r`/build M=$PWD modules_install

--- 2.2 Options

    ($KDIR refers to the path of the kernel source directory.)

    make -C $KDIR M=$PWD

    -C $KDIR
        The directory where the kernel source is located.
        "make" will actually change to the specified directory
        when executing and will change back when finished.

    M=$PWD
        Informs kbuild that an external module is being built.
        The value given to "M" is the absolute path of the
        directory where the external module (kbuild file) is
        located.

--- 2.3 Targets

    When building an external module, only a subset of the "make"
    targets are available.

    make -C $KDIR M=$PWD [target]

    The default will build the module(s) located in the current
    directory, so a target does not need to be specified. All
    output files will also be generated in this directory. No
    attempts are made to update the kernel source, and it is a
    precondition that a successful "make" has been executed for the
    kernel.

    modules
        The default target for external modules. It has the
        same functionality as if no target was specified. See
        description above.

    modules_install
        Install the external module(s). The default location is
        /lib/modules//extra/, but a prefix may
        be added with INSTALL_MOD_PATH (discussed in section 5).

    clean
        Remove all generated files in the module directory only.

    help
        List the available targets for external modules.

--- 2.4 Building Separate Files

    It is possible to build single files that are part of a module.
    This works equally well for the kernel, a module, and even for
    external modules.

    Example (The module foo.ko, consist of bar.o and baz.o):
        make -C $KDIR M=$PWD bar.lst
        make -C $KDIR M=$PWD baz.o
        make -C $KDIR M=$PWD foo.ko
        make -C $KDIR M=$PWD /


=== 3. Creating a Kbuild File for an External Module

In the last section we saw the command to build a module for the
running kernel. The module is not actually built, however, because a
build file is required. Contained in this file will be the name of
the module(s) being built, along with the list of requisite source
files. The file may be as simple as a single line:

    obj-m := .o

The kbuild system will build .o from .c,
and, after linking, will result in the kernel module .ko.
The above line can be put in either a "Kbuild" file or a "Makefile."
When the module is built from multiple sources, an additional line is
needed listing the files:

    -y := .o .o ...

NOTE: Further documentation describing the syntax used by kbuild is
located in Documentation/kbuild/makefiles.txt.

The examples below demonstrate how to create a build file for the
module 8123.ko, which is built from the following files:

    8123_if.c
    8123_if.h
    8123_pci.c
    8123_bin.o_shipped    <= Binary blob

--- 3.1 Shared Makefile

    An external module always includes a wrapper makefile that
    supports building the module using "make" with no arguments.
    This target is not used by kbuild; it is only for convenience.
    Additional functionality, such as test targets, can be included
    but should be filtered out from kbuild due to possible name
    clashes.

    Example 1:
        --> filename: Makefile
        ifneq ($(KERNELRELEASE),)
        # kbuild part of makefile
        obj-m  := 8123.o
        8123-y := 8123_if.o 8123_pci.o 8123_bin.o

        else
        # normal makefile
        KDIR ?= /lib/modules/`uname -r`/build

        default:
            $(MAKE) -C $(KDIR) M=$$PWD

        # Module specific targets
        genbin:
            echo "X" > 8123_bin.o_shipped

        endif

    The check for KERNELRELEASE is used to separate the two parts
    of the makefile. In the example, kbuild will only see the two
    assignments, whereas "make" will see everything except these
    two assignments. This is due to two passes made on the file:
    the first pass is by the "make" instance run on the command
    line; the second pass is by the kbuild system, which is
    initiated by the parameterized "make" in the default target.

--- 3.2 Separate Kbuild File and Makefile

    In newer versions of the kernel, kbuild will first look for a
    file named "Kbuild," and only if that is not found, will it
    then look for a makefile. Utilizing a "Kbuild" file allows us
    to split up the makefile from example 1 into two files:

    Example 2:
        --> filename: Kbuild
        obj-m  := 8123.o
        8123-y := 8123_if.o 8123_pci.o 8123_bin.o

        --> filename: Makefile
        KDIR ?= /lib/modules/`uname -r`/build

        default:
            $(MAKE) -C $(KDIR) M=$$PWD

        # Module specific targets
        genbin:
            echo "X" > 8123_bin.o_shipped

    The split in example 2 is questionable due to the simplicity of
    each file; however, some external modules use makefiles
    consisting of several hundred lines, and here it really pays
    off to separate the kbuild part from the rest.

    The next example shows a backward compatible version.

    Example 3:
        --> filename: Kbuild
        obj-m  := 8123.o
        8123-y := 8123_if.o 8123_pci.o 8123_bin.o

        --> filename: Makefile
        ifneq ($(KERNELRELEASE),)
        # kbuild part of makefile
        include Kbuild

        else
        # normal makefile
        KDIR ?= /lib/modules/`uname -r`/build

        default:
            $(MAKE) -C $(KDIR) M=$$PWD

        # Module specific targets
        genbin:
            echo "X" > 8123_bin.o_shipped

        endif

    Here the "Kbuild" file is included from the makefile. This
    allows an older version of kbuild, which only knows of
    makefiles, to be used when the "make" and kbuild parts are
    split into separate files.

--- 3.3 Binary Blobs

    Some external modules need to include an object file as a blob.
    kbuild has support for this, but requires the blob file to be
    named _shipped. When the kbuild rules kick in, a copy
    of _shipped is created with _shipped stripped off,
    giving us . This shortened filename can be used in
    the assignment to the module.

    Throughout this section, 8123_bin.o_shipped has been used to
    build the kernel module 8123.ko; it has been included as
    8123_bin.o.

        8123-y := 8123_if.o 8123_pci.o 8123_bin.o

    Although there is no distinction between the ordinary source
    files and the binary file, kbuild will pick up different rules
    when creating the object file for the module.

--- 3.4 Building Multiple Modules

    kbuild supports building multiple modules with a single build
    file. For example, if you wanted to build two modules, foo.ko
    and bar.ko, the kbuild lines would be:

        obj-m := foo.o bar.o
        foo-y := 
        bar-y := 

    It is that simple!


=== 4. Include Files

Within the kernel, header files are kept in standard locations
according to the following rule:

    * If the header file only describes the internal interface of a
      module, then the file is placed in the same directory as the
      source files.
    * If the header file describes an interface used by other parts
      of the kernel that are located in different directories, then
      the file is placed in include/linux/.

      NOTE: 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/.

--- 4.1 Kernel Includes

    To include a header file located under include/linux/, simply
    use:

        #include 

    kbuild will add options to "gcc" so the relevant directories
    are searched.

--- 4.2 Single Subdirectory

    External modules tend to place header files in a separate
    include/ directory where their source is located, although this
    is not the usual kernel style. To inform kbuild of the
    directory, use either ccflags-y or CFLAGS_.o.

    Using the example from section 3, if we moved 8123_if.h to a
    subdirectory named include, the resulting kbuild file would
    look like:

        --> filename: Kbuild
        obj-m := 8123.o

        ccflags-y := -Iinclude
        8123-y := 8123_if.o 8123_pci.o 8123_bin.o

    Note that in the assignment there is no space between -I and
    the path. This is a limitation of kbuild: there must be no
    space present.

--- 4.3 Several Subdirectories

    kbuild can handle files that are spread over several directories.
    Consider the following example:

    .
    |__ src
    |   |__ complex_main.c
    |   |__ hal
    |    |__ hardwareif.c
    |    |__ include
    |        |__ hardwareif.h
    |__ include
        |__ complex.h

    To build the module complex.ko, we then need the following
    kbuild file:

        --> filename: Kbuild
        obj-m := complex.o
        complex-y := src/complex_main.o
        complex-y += src/hal/hardwareif.o

        ccflags-y := -I$(src)/include
        ccflags-y += -I$(src)/src/hal/include

    As you can see, kbuild knows how to handle object files located
    in other directories. The trick is to specify the directory
    relative to the kbuild file's location. That being said, this
    is NOT recommended practice.

    For the header files, kbuild must be explicitly told where to
    look. When kbuild executes, the current directory is always the
    root of the kernel tree (the argument to "-C") and therefore an
    absolute path is needed. $(src) provides the absolute path by
    pointing to the directory where the currently executing kbuild
    file is located.


=== 5. Module Installation

Modules which are included in the kernel are installed in the
directory:

    /lib/modules/$(KERNELRELEASE)/kernel/

And external modules are installed in:

    /lib/modules/$(KERNELRELEASE)/extra/

--- 5.1 INSTALL_MOD_PATH

    Above are the default directories but as always some level of
    customization is possible. A prefix can be added to the
    installation path using the variable INSTALL_MOD_PATH:

        $ make INSTALL_MOD_PATH=/frodo modules_install
        => Install dir: /frodo/lib/modules/$(KERNELRELEASE)/kernel/

    INSTALL_MOD_PATH may be set as an ordinary shell variable or,
    as shown above, can be specified on the command line when
    calling "make." This has effect when installing both in-tree
    and out-of-tree modules.

--- 5.2 INSTALL_MOD_DIR

    External modules are by default installed to a directory under
    /lib/modules/$(KERNELRELEASE)/extra/, but you may wish to
    locate modules for a specific functionality in a separate
    directory. For this purpose, use INSTALL_MOD_DIR to specify an
    alternative name to "extra."

        $ make INSTALL_MOD_DIR=gandalf -C $KDIR \
               M=$PWD modules_install
        => Install dir: /lib/modules/$(KERNELRELEASE)/gandalf/


=== 6. Module Versioning

Module versioning is enabled by the CONFIG_MODVERSIONS tag, and is used
as a simple ABI consistency check. A CRC value of the full prototype
for an exported symbol is created. When a module is loaded/used, the
CRC values contained in the kernel are compared with similar values in
the module; if they are not equal, the kernel refuses to load the
module.

Module.symvers contains a list of all exported symbols from a kernel
build.

--- 6.1 Symbols From the Kernel (vmlinux + modules)

    During a kernel build, a file named Module.symvers will be
    generated. Module.symvers contains all exported symbols from
    the kernel and compiled modules. For each symbol, the
    corresponding CRC value is also stored.

    The syntax of the Module.symvers file is:
                           

        0x2d036834  scsi_remove_host   drivers/scsi/scsi_mod

    For a kernel build without CONFIG_MODVERSIONS enabled, the CRC
    would read 0x00000000.

    Module.symvers serves two purposes:
    1) It lists all exported symbols from vmlinux and all modules.
    2) It lists the CRC if CONFIG_MODVERSIONS is enabled.

--- 6.2 Symbols and External Modules

    When building an external module, the build system needs access
    to the symbols from the kernel to check if all external symbols
    are defined. This is done in the MODPOST step. modpost obtains
    the symbols by reading Module.symvers from the kernel source
    tree. If a Module.symvers file is present in the directory
    where the external module is being built, this file will be
    read too. During the MODPOST step, a new Module.symvers file
    will be written containing all exported symbols that were not
    defined in the kernel.

--- 6.3 Symbols From Another External Module

    Sometimes, an external module uses exported symbols from
    another external module. kbuild needs to have full knowledge of
    all symbols to avoid spitting out warnings about undefined
    symbols. Three solutions exist for this situation.

    NOTE: The method with a top-level kbuild file is recommended
    but may be impractical in certain situations.

    Use a top-level kbuild file
        If you have two modules, foo.ko and bar.ko, where
        foo.ko needs symbols from bar.ko, you can use a
        common top-level kbuild file so both modules are
        compiled in the same build. Consider the following
        directory layout:

        ./foo/ <= contains foo.ko
        ./bar/ <= contains bar.ko

        The top-level kbuild file would then look like:

        #./Kbuild (or ./Makefile):
            obj-y := foo/ bar/

        And executing

            $ make -C $KDIR M=$PWD

        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 copy Module.symvers from
        another module, you can assign a space separated list
        of files to KBUILD_EXTRA_SYMBOLS in your build file.
        These files will be loaded by modpost during the
        initialization of its symbol tables.


=== 7. Tips & Tricks

--- 7.1 Testing for CONFIG_FOO_BAR

    Modules often need to check for certain CONFIG_ options to
    decide if a specific feature is included in the module. In
    kbuild this is done by referencing the CONFIG_ variable
    directly.

        #fs/ext2/Makefile
        obj-$(CONFIG_EXT2_FS) += ext2.o

        ext2-y := balloc.o bitmap.o dir.o
        ext2-$(CONFIG_EXT2_FS_XATTR) += xattr.o

    External modules have traditionally used "grep" to check for
    specific CONFIG_ settings directly in .config. This usage is
    broken. As introduced before, external modules should use
    kbuild for building and can therefore use the same methods as
    in-tree modules when testing for CONFIG_ definitions.

 

转载于:https://www.cnblogs.com/tfanalysis/p/7476765.html