..
 # Copyright (c) 2025, Arm Limited.
 #
 # SPDX-License-Identifier: MIT

#######################
Build a Suitable Kernel
#######################

Fastpath will install on the SUT any kernel you provide to it and reboot into
that kernel. There are few requirements for the features that must be enabled in
the kernel, but it must have the required drivers to be able to boot the SUT
(either built-in or as modules, as appropriate), and it must be able to support
running Docker. Note that the arm64 defconfig does not support Docker.

A full kernel config can be used in place of defconfig when building the kernel.
This can be helpful if you need to reproduce the exact environment of a SUT or
have a known-good config you want to use. In some cases, such as with cloud VMs,
defconfig may be missing required options for the system to boot or operate
properly. If only a few additional options are needed, they can be added using a
config fragment instead.

For Arm's internal usage of Fastpath, we predominantly build kernels with
defconfig + the Kconfigs described in the `fastpath.frag
<https://gitlab.arm.com/tooling/fastpath/-/blob/main/kconfigs/fastpath.frag>`_
Kconfig fragment. This provides all the features required by Docker and all the
drivers for the various HW we run on internally. The fragment is provided as an
example only.

Fastpath requires a kernel image (see :ref:`user-guide/planschema:swprofile
object`), which may be compressed or uncompressed. If using modules, you will
also provide a tarball of the modules in the plan's swprofile section.

There are many ways to build the Linux kernel, but `tuxmake
<https://tuxmake.org>`_ is a convenient option for this case because it includes
all required tools in a container and outputs both the kernel image and the
modules in the required formats. Assuming your linux source code is at
``./linux``:

.. code-block:: shell

  tuxmake \
	--directory linux \
	--output-dir my-kernel \
	--target-arch arm64 \
	--kconfig defconfig
	--kconfig-add kconfigs/fastpath.frag \
	--runtime docker \
	--fail-fast \
	config kernel modules

On completion, ``my-kernel/Image.gz`` and ``my-kernel/modules.tar.xz`` provide
files that Fastpath requires.