diff --git a/documentation/kernel-dev/kernel-dev-intro.xml b/documentation/kernel-dev/kernel-dev-intro.xml index 17ff5c7877..2490087b7a 100644 --- a/documentation/kernel-dev/kernel-dev-intro.xml +++ b/documentation/kernel-dev/kernel-dev-intro.xml @@ -89,407 +89,6 @@ recipes, an alternative exists by which you can use the Yocto Project Linux kernel tools with your own kernel sources. - - -
- Preparing the Build Host to Work on the Kernel - - - 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. - - -
- Getting Ready to Develop using <filename>devtool</filename> - - - 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. - -
- -
- Getting Ready for Traditional Kernel Development - - - 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 Workflow - - - 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. - Warning - 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. - - - -
- -
- Other Resources The remainder of this manual provides instructions for completing @@ -536,6 +135,124 @@
+
+ Kernel Modification Workflow + + + 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. + The illustration and accompanying list provide general information + and references for further information. + + + + + + + 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. + + + Set Up Your Host Development System for Kernel Development: + It is recommended that you use devtool + and an extensible SDK for kernel development. + Alternatively, you can use traditional kernel development + methods with the Yocto Project. + Either way, there are steps you need to take to get the + development environment ready. + + Using devtool and the eSDK requires + that you have a clean build of the image and that you are + set up with the appropriate eSDK. + For more information, see the + "Getting Ready to Develop Using devtool" + section. + + Using traditional kernel development requires that you + have the kernel source available in an isolated local Git + repository. + For more information, see the + "Getting Ready for Traditional Kernel Development" + section. + + + 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 eSDK's Build Directory if you are using + devtool. + For more information, see the + "Using devtool to Patch the Kernel" + section. + + If you are using traditional kernel development, you + edit the source files in the kernel's local Git repository. + For more information, see the + "Using Traditional Kernel Development to Patch the Kernel" + section. + + + 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. + Warning + 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. + 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. + Depending on your target hardware, you can verify your changes + on actual hardware or perhaps QEMU. + + + +
+