====== Kernel Development ======

===== Selecting a Kernel =====

To use a different kernel than the default for the machine, set the kernel using ''PREFERRED_PROVIDER''.
This can either be set in ''local.conf'' for testing/development or in ''machine/<machine>.conf'' to set the default kernel for that machine.

<code>
PREFERRED_PROVIDER_virtual/kernel = "<kernel>"
</code>

Note the old kernel should be cleaned before switching to a new kernel.
Neglecting to do so may cause build errors.

<code>
bitbake virtual/kernel -c clean
</code>

===== Adding a Kernel as a Recipe =====

Poky provides a template [[ .:recipes | recipe ]] for kernels in its ''meta-skeleton'' [[ .:layer | layer ]].
The recipe can be found in ''poky/meta-skeleton/recipes-kernel/linux-yocto-custom.bb''.

Canonically, kernels [[ .:recipes | recipes ]] live in ''recipes-kernel/linux/'' and the [[ .:recipes | recipe ]] name starts with ''linux'', for example ''linux-yocto'' or ''linux-toradex''.

The kernel [[ .:recipes | recipe ]] - like any [[ .:recipes | recipe ]] - needs a [[ .:layer | layer ]] to live in.

Copy the template from meta-skeleton to your custom layer into ''recipes-kernel/linux/'' and rename it appropriately.

<code>
cd <layer dir>
mkdir -p recipes-kernel/linux
cp ../poky/meta-skeleton/recipes-kernel/linux/linux-yocto-custom.bb recipes-kernel/linux/linux-<name>.bb
</code>

==== Customizing the Recipe ====

Now the [[ .:recipes | recipe ]] needs to modified to build the kernel in question.
The key fields in need of modification are listed below:

<code>
SRC_URI = "<kernel source>"

LINUX_VERSION ?= "<kernel version>"
LINUX_VERSION_EXTENSION_append = "-custom"

SRCREV = "<commit hash or tag if git repo>"

COMPATIBLE_MACHINE = "<machine>"
</code>

  * ''SRC_URI'' needs to include the kernel source as well as any patches if needed
  * ''LINUX_VERSION'' needs to contain the kernel version, e.g. ''4.14''
  * ''LINUX_VERSION_EXTENSION_append'' can be used to the kernel name
  * ''SRCREV'' needs to contain the commit hash or tag if the kernel source is a git repository
  * ''COMPATIBLE_MACHINE'' needs to include all machines that this kernel is compatible with

The kernel can now be set as ''PREFERRED_PROVIDER_virtual/kernel''.

===== Working with the Kernel =====

Here are some common operations when dealing with the kernel:

^ command ^ description |
| bitbake virtual/kernel -c unpack | unpack kernel |
| bitbake virtual/kernel -c patch | apply patches (if any) |
| bitbake virtual/kernel -c compile | build kernel |
| bitbake virtual/kernel -c configure | configure kernel* |
| bitbake virtual/kernel -c menuconfig | menuconfig, like ''make menuconfig'' |
| bitbake virtual/kernel -c clean | clean kernel package, like ''make clean'' |
| bitbake virtual/kernel | build and install kernel package |

*: ''configure'' also extracts the kernel into ''tmp/work-shared/<machine>/kernel-source''.
This is convenient when needing to modify the kernel, for example to create patches.

Note that bitbake will also run all commands that need to be run to execute the specified command.
For example, ''compile'' will also cause ''unpack'' and ''patch'' to be run, since these need to happen before the build.