From ccbfdd795e36ca421b1c169343c1e9a886f515a7 Mon Sep 17 00:00:00 2001 From: Scott Rifenbark Date: Wed, 6 Sep 2017 14:52:41 -0700 Subject: kernel-dev: Added the host prep for kernel dev to the chapter. (From yocto-docs rev: 7343f1108808bb3be182af58325f9e3195ff4d8e) Signed-off-by: Scott Rifenbark Signed-off-by: Richard Purdie --- documentation/kernel-dev/kernel-dev-common.xml | 577 ++++++++++++++++++++++++- 1 file changed, 565 insertions(+), 12 deletions(-) (limited to 'documentation/kernel-dev/kernel-dev-common.xml') diff --git a/documentation/kernel-dev/kernel-dev-common.xml b/documentation/kernel-dev/kernel-dev-common.xml index de119c3e87..3af52eb352 100644 --- a/documentation/kernel-dev/kernel-dev-common.xml +++ b/documentation/kernel-dev/kernel-dev-common.xml @@ -3,20 +3,391 @@ [ %poky; ] > - Common Tasks - - This chapter presents several common tasks you perform when you - work with the Yocto Project Linux kernel. - These tasks include preparing a layer, modifying an existing recipe, - iterative development, working with your own sources, and incorporating - out-of-tree modules. - - The examples presented in this chapter work with the Yocto Project - 1.2.2 Release and forward. - - + + This chapter presents several common tasks you perform when you + work with the Yocto Project Linux kernel. + These tasks include preparing your host development system for + kernel development, preparing a layer, modifying an existing recipe, + patching the kernel, iterative development, working with your own sources, + and incorporating out-of-tree modules. + + The examples presented in this chapter work with the Yocto Project + 2.4 Release and forward. + + + +
+ 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 + + + Getting ready for traditional kernel development using the Yocto + Project involves many of the same steps as described in the + previous section. + However, you need to establish a local copy of the kernel source + since you will be editing these files. + + + + Follow these steps to prepare to update the kernel image using + traditional kernel development flow with the Yocto Project. + Completing this procedure leaves you ready to make modifications + to the kernel source as described in the + "Using Traditional Kernel Development to Patch the Kernel" + section: + + + Initialize the BitBake Environment: + Before you can do anything using BitBake, 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 + + + + Create a Local Copy of the Kernel Git + Repository: + 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. + + + + + + + At this point you have set up to start making modifications to + the kernel using traditional kernel development steps. + For a continued example, see the + "Using Traditional Kernel Development to Patch the Kernel" + section. + +
+
Creating and Preparing a Layer @@ -824,6 +1195,188 @@ NOTE: This stuff is how it would have been if a *.wic file was created
+
+ Using Traditional Kernel Development to Patch the Kernel + + + The steps in this procedure show you how you can patch the + kernel using traditional kernel development (i.e. not using + devtool and the extensible SDK as + described in the + "Using devtool to Patch the Kernel" + section). + + Before attempting this procedure, be sure you have performed + the steps to get ready for updating the kernel as described + in the + "Getting Ready for Traditional Kernel Development" + section. + + + + + Patching the kernel involves changing or adding configurations + to an existing kernel, changing or adding recipes to the kernel + that are needed to support specific hardware features, or even + altering the source code itself. + + You can also use the yocto-kernel script + found in the + Source Directory + under scripts to manage kernel patches + and configuration. + See the "Managing kernel Patches and Config Items with yocto-kernel" + section in the Yocto Project Board Support Packages (BSP) + Developer's Guide for more information. + + + + + This example creates a simple patch by adding some QEMU emulator + console output at boot time through printk + statements in the kernel's calibrate.c source + code file. + Applying the patch and booting the modified image causes the added + messages to appear on the emulator's console. + + The example is a continuation of the setup procedure found in + the + "Getting Ready for Traditional Kernel Development" + Section. + + + + + Also, for more information on patching the kernel, see the + "Applying Patches" + section. + + + Know What Branch is Checked Out In Your Local + Kernel Git Repository: + Prior to this step, you should have used Git to create a + local copy of the repository for your kernel. + Assuming you created the repository as directed in the + "Getting Ready for Traditional Kernel Development" + section, use the following commands to check out the + standard/base branch of the + Linux Yocto 4.9 kernel: + + $ cd ~/linux-yocto-4.9 + $ git checkout -b standard/base origin/standard/base + + + + Edit the Source Files + Follow these steps to make some simple changes to the source + files: + + + Change the working directory: + You need to locate the source files in the + local copy of the kernel Git repository: + Change to where the kernel source code is before making + your edits to the calibrate.c file: + + $ cd ~/linux-yocto-4.9/init + + + + Edit the source file: + Edit the calibrate.c file to have + the following changes: + + void calibrate_delay(void) + { + unsigned long lpj; + static bool printed; + int this_cpu = smp_processor_id(); + + printk("*************************************\n"); + printk("* *\n"); + printk("* HELLO YOCTO KERNEL *\n"); + printk("* *\n"); + printk("*************************************\n"); + + if (per_cpu(cpu_loops_per_jiffy, this_cpu)) { + . + . + . + + + + + + Stage and Commit Your Changes: + Use standard Git commands to stage and commit the changes + you just made: + + $ git add calibrate.c + $ git commit -m "calibrate.c - Added some printk statements" + + If you do not stage and commit your changes, the OpenEmbedded + Build System will not pick up the changes. + + + Update Your local.conf File to Point to Your Source Files: + In addition to your local.conf file + specifying to use "kernel-modules" and the "qemux86" machine, + it must also point to the updated kernel source files. + Add the following commands to your + local.conf: + + $ cd ~/poky/build/conf + Add the following: + + SRC_URI_pn-linux-yocto = "git:///$HOME/linux-yocto-4.9;protocol=file;name=machine;branch=standard/base; \ + git:///home/scottrif/yocto-kernel-cache;protocol=file;type=kmeta;name=meta;branch=yocto-4.9;destsuffix=${KMETA}" +SRCREV_meta_qemux86 = "${AUTOREV}" +SRCREV_machine_qemux86 = "${AUTOREV}" + + You must be sure to specify the correct branch and machine + types. + For this example, the branch is + standard/base and the machine is + "qemux86". + + + Build the Image: + With the source modified, staged, and committed, and + the local.conf file pointing to + the kernel files, you can now use BitBake to build the + image: + + $ cd ~/poky/build + $ bitbake core-image-minimal + + + + Boot the image: + Boot the modified image in the QEMU emulator + using this command. + When prompted to login to the QEMU console, use "root" + with no password: + + $ runqemu qemux86 + + + + Look for Your Changes: + As QEMU booted, you might have seen your changes rapidly + scroll by. + If not, use these commands to see your changes: + + # dmesg | less + + You should see the results of your + printk statements + as part of the output when you scroll down the + console window. + + + +
+
Using an Iterative Development Process -- cgit v1.2.3-54-g00ecf