%poky; ] >

Regardless of how you intend to make use of the Yocto Project, chances are you will work with the Linux kernel. This manual describes how to set up your build host to support kernel development, introduces the kernel development process, provides background information on the Yocto Linux kernel Metadata, describes common tasks you can perform using the kernel tools, and shows you how to use the kernel Metadata needed to work with the kernel inside the Yocto Project. Each Yocto Project release has a set of Yocto Linux kernel recipes, whose Git repositories you can view in the Yocto Source Repositories under the "Yocto Linux Kernel" heading. New recipes for the release track the latest Linux kernel upstream developments from and introduce newly-supported platforms. Previous recipes in the release are refreshed and supported for at least one additional Yocto Project release. As they align, these previous releases are updated to include the latest from the Long Term Support Initiative (LTSI) project. Also included is a Yocto Linux kernel development recipe (linux-yocto-dev.bb) should you want to work with the very latest in upstream Yocto Linux kernel development and kernel Metadata development. For more on Yocto Linux kernels, see the "Yocto Project Kernel Development and Maintenance section. The Yocto Project also provides a powerful set of kernel tools for managing Yocto Linux kernel sources and configuration data. You can use these tools to make a single configuration change, apply multiple patches, or work with your own kernel sources. In particular, the kernel tools allow you to generate configuration fragments that specify only what you must, and nothing more. Configuration fragments only need to contain the highest level visible CONFIG options as presented by the Yocto Linux kernel menuconfig system. Contrast this against a complete Yocto Linux kernel .config file, which includes all the automatically selected CONFIG options. This efficiency reduces your maintenance effort and allows you to further separate your configuration in ways that make sense for your project. A common split separates policy and hardware. For example, all your kernels might support the proc and sys filesystems, but only specific boards require sound, USB, or specific drivers. Specifying these configurations individually allows you to aggregate them together as needed, but maintains them in only one place. Similar logic applies to separating source changes. If you do not maintain your own kernel sources and need to make only minimal changes to the sources, the released recipes provide a vetted base upon which to layer your changes. Doing so allows you to benefit from the continual kernel integration and testing performed during development of the Yocto Project. If, instead, you have a very specific Linux kernel source tree and are unable to align with one of the official Yocto Linux kernel recipes, an alternative exists by which you can use the Yocto Project Linux kernel tools with your own kernel sources.

Before you can do any kernel development, you need to be sure your build host is set up to use the Yocto Project. For information on how to get set up, see the "Setting Up to Use the Yocto Project" section in the Yocto Project Development Manual. Part of preparing the system is creating a local Git repository of the Source Directory (poky) on your system. Follow the steps in the "Cloning the poky Repository" section in the Yocto Project Development Manual to set up your Source Directory. Be sure you check out the appropriate development branch or by tag to get the version of Yocto Project you want. See the "Checking Out by Branch in Poky" and "Checking Out by Tag in Poky" sections in the Yocto Project Development Manual for more information. Kernel development is best accomplished using devtool and not through traditional kernel workflow methods. The remainder of this section provides information for both scenarios.

Follow these steps to prepare to update the kernel image using devtool. Completing this procedure leaves you with a clean kernel image and ready to make modifications as described in the "Using devtool to Patch the Kernel" section: Initialize the BitBake Environment: Before building an extensible SDK, you need to initialize the BitBake build environment by sourcing a build environment script (i.e. oe-init-build-env or oe-init-build-env-memres): $ cd ~/poky $ source oe-init-build-env The previous commands assume the Source Repositories (i.e. poky) have been cloned using Git and the local repository is named "poky". Prepare Your local.conf File: By default, the MACHINE variable is set to "qemux86", which is fine if you are building for the QEMU emulator in 32-bit mode. However, if you are not, you need to set the MACHINE variable appropriately in your conf/local.conf file found in the Build Directory (i.e. ~/poky/build in this example). Also, since you are preparing to work on the kernel image, you need to set the MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS variable to include kernel modules. This example uses the default "qemux86" for the MACHINE variable but needs to add the "kernel-modules": MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS += "kernel-modules" Create a Layer for Patches: You need to create a layer to hold patches created for the kernel image. You can use the yocto-layer command as follows: $ cd ~/poky $ yocto-layer create my-kernel -o ../meta-my-kernel Please enter the layer priority you'd like to use for the layer: [default: 6] Would you like to have an example recipe created? (y/n) [default: n] Would you like to have an example bbappend file created? (y/n) [default: n] New layer created in ../meta-my-kernel. Don't forget to add it to your BBLAYERS (for details see ../meta-my-kernel/README). Inform the BitBake Build Environment About Your Layer: As directed when you created your layer, you need to add the layer to the BBLAYERS variable in the bblayers.conf file as follows: $ cd ~/poky/build $ bitbake-layers add-layer ../../meta-my-kernel Build the Extensible SDK: Use BitBake to build the extensible SDK specifically for the Minnowboard: $ cd ~/poky/build $ bitbake core-image-minimal -c populate_sdk_ext Once the build finishes, you can find the SDK installer file (i.e. *.sh file) in the following directory: ~/poky/build/tmp/deploy/sdk For this example, the installer file is named poky-glibc-x86_64-core-image-minimal-i586-toolchain-ext-&DISTRO;.sh Install the Extensible SDK: Use the following command to install the SDK. For this example, install the SDK in the default ~/poky_sdk directory: $ cd ~/poky/build/tmp/deploy/sdk $ ./poky-glibc-x86_64-core-image-minimal-i586-toolchain-ext-&DISTRO;.sh Poky (Yocto Project Reference Distro) Extensible SDK installer version &DISTRO; ============================================================================ Enter target directory for SDK (default: ~/poky_sdk): You are about to install the SDK to "/home/scottrif/poky_sdk". Proceed[Y/n]? Y Extracting SDK......................................done Setting it up... Extracting buildtools... Preparing build system... Parsing recipes: 100% |#################################################################| Time: 0:00:52 Initializing tasks: 100% |############## ###############################################| Time: 0:00:04 Checking sstate mirror object availability: 100% |######################################| Time: 0:00:00 Parsing recipes: 100% |#################################################################| Time: 0:00:33 Initializing tasks: 100% |##############################################################| Time: 0:00:00 done SDK has been successfully set up and is ready to be used. Each time you wish to use the SDK in a new shell session, you need to source the environment setup script e.g. $ . /home/scottrif/poky_sdk/environment-setup-i586-poky-linux Set Up a New Terminal to Work With the Extensible SDK: You must set up a new terminal to work with the SDK. You cannot use the same BitBake shell used to build the installer. After opening a new shell, run the SDK environment setup script as directed by the output from installing the SDK: $ source ~/poky_sdk/environment-setup-i586-poky-linux "SDK environment now set up; additionally you may now run devtool to perform development tasks. Run devtool --help for further details. If you get a warning about attempting to use the extensible SDK in an environment set up to run BitBake, you did not use a new shell. Build the Clean Image: The final step in preparing to work on the kernel is to build an initial image using devtool in the new terminal you just set up and initialized for SDK work: $ devtool build-image Parsing recipes: 100% |##########################################| Time: 0:00:05 Parsing of 830 .bb files complete (0 cached, 830 parsed). 1299 targets, 47 skipped, 0 masked, 0 errors. WARNING: No packages to add, building image core-image-minimal unmodified Loading cache: 100% |############################################| Time: 0:00:00 Loaded 1299 entries from dependency cache. NOTE: Resolving any missing task queue dependencies Initializing tasks: 100% |#######################################| Time: 0:00:07 Checking sstate mirror object availability: 100% |###############| Time: 0:00:00 NOTE: Executing SetScene Tasks NOTE: Executing RunQueue Tasks NOTE: Tasks Summary: Attempted 2866 tasks of which 2604 didn't need to be rerun and all succeeded. NOTE: Successfully built core-image-minimal. You can find output files in /home/scottrif/poky_sdk/tmp/deploy/images/qemux86 If you were building for actual hardware and not for emulation, you could flash the image to a USB stick on /dev/sdd and boot your device. For an example that uses a Minnowboard, see the TipsAndTricks/KernelDevelopmentWithEsdk Wiki page. At this point you have set up to start making modifications to the kernel by using the extensible SDK. For a continued example, see the "Using devtool to Patch the Kernel" section.

For traditional kernel development using the Yocto Project, you need to establish a local copy of the kernel source. You can find Git repositories of supported Yocto Project kernels organized under "Yocto Linux Kernel" in the Yocto Project Source Repositories at . For simplicity, it is recommended that you create your copy of the kernel Git repository outside of the Source Directory, which is usually named poky. The following command shows how to create a local copy of the linux-yocto-4.9 kernel: $ git clone git://git.yoctoproject.org/linux-yocto-4.9 linux-yocto-4.9.git Cloning into 'linux-yocto-4.9.git'... remote: Counting objects: 5094108, done. remote: Compressing objects: 100% (765113/765113), done. remote: Total 5094108 (delta 4294009), reused 5088388 (delta 4288312) Receiving objects: 100% (5094108/5094108), 1.02 GiB | 7.82 MiB/s, done. Resolving deltas: 100% (4294009/4294009), done. Checking connectivity... done. Checking out files: 100% (56233/56233), done.

Kernel modification involves changing the Yocto Project kernel, which could involve changing configuration options as well as adding new kernel recipes. Configuration changes can be added in the form of configuration fragments, while recipe modification comes through the kernel's recipes-kernel area in a kernel layer you create. This section presents a high-level overview of the Yocto Project kernel modification workflow. You can find additional information here: The "Using devtool to Patch the Kernel" section. The "Configuring the Kernel" section in the Yocto Project Development Manual. This illustration and the following list summarizes the kernel modification general workflow. Set up Your Host Development System to Support Development Using the Yocto Project: See the "Setting Up to Use the Yocto Project" section in the Yocto Project Quick Start for options on how to get a build host ready to use the Yocto Project. Establish the Temporary Kernel Source Files: Temporary kernel source files are kept in the Build Directory created by the OpenEmbedded build system when you run BitBake. If you have never built the kernel in which you are interested, you need to run an initial build to establish local kernel source files. If you are building an image for the first time, you need to get the build environment ready by sourcing an environment setup script (i.e. oe-init-build-env or oe-init-build-env-memres). You also need to be sure two key configuration files (local.conf and bblayers.conf) are configured appropriately. The entire process for building an image is overviewed in the "Building Images" section of the Yocto Project Quick Start. You might want to reference this information. You can find more information on BitBake in the BitBake User Manual. The build process supports several types of images to satisfy different needs. See the "Images" chapter in the Yocto Project Reference Manual for information on supported images. Make Changes to the Kernel Source Code if applicable: Modifying the kernel does not always mean directly changing source files. However, if you have to do this, you make the changes to the files in the Build Directory. Make Kernel Configuration Changes if Applicable: If your situation calls for changing the kernel's configuration, you can use menuconfig, which allows you to interactively develop and test the configuration changes you are making to the kernel. Saving changes you make with menuconfig updates the kernel's .config file. Try to resist the temptation to directly edit an existing .config file, which is found in the Build Directory among the source code used for the build (e.g. see the workflow illustration in the "Kernel Modification Workflow" section). Doing so, can produce unexpected results when the OpenEmbedded build system regenerates the configuration file. Once you are satisfied with the configuration changes made using menuconfig and you have saved them, you can directly compare the resulting .config file against an existing original and gather those changes into a configuration fragment file to be referenced from within the kernel's .bbappend file. Additionally, if you are working in a BSP layer and need to modify the BSP's kernel's configuration, you can use the yocto-kernel script as well as menuconfig. The yocto-kernel script lets you interactively set up kernel configurations. Rebuild the Kernel Image With Your Changes: Rebuilding the kernel image applies your changes.

The remainder of this manual provides instructions for completing specific Linux kernel development tasks. These instructions assume you are comfortable working with BitBake recipes and basic open-source development tools. Understanding these concepts will facilitate the process of working with the kernel recipes. If you find you need some additional background, please be sure to review and understand the following documentation: Yocto Project Quick Start devtool workflow as described in the Yocto Project Software Development Kit (SDK) Developer's Guide. The "Understanding and Creating Layers" section in the Yocto Project Development Manual The "Kernel Modification Workflow" section. Finally, while this document focuses on the manual creation of recipes, patches, and configuration files, the Yocto Project Board Support Package (BSP) tools are available to automate this process with existing content and work well to create the initial framework and boilerplate code. For details on these tools, see the "Using the Yocto Project's BSP Tools" section in the Yocto Project Board Support Package (BSP) Developer's Guide.