147 lines
5.8 KiB
Plaintext
147 lines
5.8 KiB
Plaintext
Introduction
|
|
------------
|
|
|
|
There are cases where it is useful to shard (break apart) the kernel source
|
|
into separate directories, yet still create a single kernel image from the
|
|
combination of all of those directories. These separate directories could then
|
|
be distributed separately, or on different timescales. One example is during
|
|
development of support for a new piece of hardware, where there is often a
|
|
desire to defer release of software support until the hardware is released,
|
|
while still releasing modifications to the base kernel. This document
|
|
describes the "kernel overlays" feature, which supports this requirement.
|
|
|
|
High-level Description
|
|
----------------------
|
|
|
|
The kernel's build system can be explicitly told about so-called overlay source
|
|
trees. A list of overlays will be provided each time the build system is
|
|
invoked using the KERNEL_OVERLAYS environment variable, or a list of possible
|
|
overlays may be embedded into the top-level Makefile. The kernel build process
|
|
will automatically process source contained in these overlays along with the
|
|
base kernel source. This will be handled entirely by the core kernel build
|
|
process, so that no Kconfig file or Makefile will need to reference any
|
|
overlay.
|
|
|
|
The kernel source tree will be considered to be the union of the main kernel
|
|
source tree and all overlays. Any file access will search or combine files from
|
|
all overlays as appropriate. A consequence of this concept is that no overlay
|
|
should contain the same filename as any other overlay, except for Kconfig
|
|
files and Makefiles, which are explicitly handled as described below.
|
|
|
|
Kconfig Details
|
|
---------------
|
|
|
|
When the kernel configuration utility parses any Kconfig file, it will
|
|
automatically include equivalent files in each overlay. The algorithm will be
|
|
approximately:
|
|
|
|
def parse_file(filename):
|
|
parse_file_imp(${srctree}/Kconfig)
|
|
for each overlay in overlays:
|
|
parse_file_imp(${srctree.${overlay}}/Kconfig)
|
|
|
|
Thus, any Kconfig options defined in overlay Kconfig files will be placed into
|
|
the Kconfig menu structure in the same location as (immediately following) any
|
|
options defined in the base kernel's Kconfig file. The choice_append and
|
|
menu_append Kconfig statements also allow appending to existing menus in some
|
|
cases.
|
|
|
|
Makefile Details
|
|
----------------
|
|
|
|
When the kernel build system reads any Makefile, it will automatically include
|
|
equivalent files in each overlay. The algorithm will be approximately:
|
|
|
|
def include_makefile(filename):
|
|
include ${srctree}/filename
|
|
for each overlay in overlays:
|
|
include ${srctree.${overlay}}/Makefile
|
|
|
|
Thus, any assignments to obj-y will be considered part of the same Makefile as
|
|
the base kernel's Makefile, and hence end up in the same built-in.o.
|
|
|
|
Referencing Other Overlays
|
|
--------------------------
|
|
|
|
Overlays may depend on each-other. Dependency order should be well-defined and
|
|
non-cyclic; the base kernel and all overlays should form a Directed Acyclic
|
|
Graph. For example, an overlay that adds support for all released $vendor
|
|
CPUs could rely on the base kernel. An overlay that adds support for an as yet
|
|
unreleased CPU from the same vendor could rely on both the base vendor, and
|
|
the aforementioned $vendor overlay. One use-case is one overlay implementing
|
|
public functions, and prototyping those functions in a header file, and
|
|
another overlay needing to use those functions, and hence needing to include
|
|
header files from the first overlay.
|
|
|
|
Overlays should not hard-code the path (even relative) to other overlays. The
|
|
build system provides variables to allow overlays to be referenced by name.
|
|
Each overlay is assumed to be identified by a unique name. It is also assumed
|
|
that each overlay is stored in a directory with that name as the last
|
|
component. Given that, just as ${srctree} contains the path of the base kernel,
|
|
then ${srctree.${overlay_name}} contains the path of the given named overlay.
|
|
|
|
Examples
|
|
--------
|
|
|
|
Add a new source file to an existing directory
|
|
----------------------------------------------
|
|
|
|
In the overlay, write a Kconfig and Makefile that contain any new Kconfig
|
|
config statement that is required, and standard Makefile content. No
|
|
boilerplate logic is required:
|
|
|
|
overlay/drivers/i2c/busses/Kconfig:
|
|
|
|
config I2C_FOO
|
|
tristate "FOO I2C"
|
|
|
|
overlay/drivers/i2c/busses/Makefile:
|
|
|
|
obj-$(CONFIG_I2C_FOO) += foo.o
|
|
|
|
Add a new directory into the source tree
|
|
----------------------------------------
|
|
|
|
Determine the parent directory that should reference the new directory's
|
|
Kconfig and Makefile files, as if you were to add the directory to the base
|
|
kernel. This is typically the physical parent directory of the new directory,
|
|
although in some cases, directories are referenced from other places instead.
|
|
This parent directory must already be linked into the Kconfig and Makefiles in
|
|
the base kernel, or in some earlier overlay.
|
|
|
|
Assume we wish to add drivers/foo/, and reference this from the existing Kconfig
|
|
and Makefile in drivers/.
|
|
|
|
In the overlay that contains the new directory, create or edit the chosen
|
|
parent directory's (drivers/) Kconfig file and Makefile to reference the new
|
|
directory as if it existed in the base kernel, without any boilerplate logic.
|
|
For example:
|
|
|
|
overlay/drivers/Kconfig:
|
|
|
|
source "drivers/foo/Kconfig"
|
|
|
|
overlay/drivers/Makefile:
|
|
|
|
obj-y += foo/
|
|
|
|
In the overlay that contains the new directory, create the content for the new
|
|
directory in exactly the same way that you would if the new directory were part
|
|
of the base kernel:
|
|
|
|
overlay/drivers/foo/Kconfig:
|
|
|
|
config FOO
|
|
bool "Description"
|
|
|
|
overlay/drivers/foo/Makefile:
|
|
|
|
# Just an example of $srctree.xxx usage; not required in all cases
|
|
ccflags-y += -I${srctree.other_overlay}/some/utility/lib/include
|
|
|
|
obj-$(CONFIG_FOO) += foo.o
|
|
|
|
overlay/drivers/foo/foo.c
|
|
|
|
Standard source code
|