From ea256df2a8af386f5c8c7bc7744d6d790ab0a3f9 Mon Sep 17 00:00:00 2001 From: Scott Rifenbark Date: Wed, 30 Aug 2017 13:34:52 -0700 Subject: dev-manual, kernel-dev: Working kernel flow process using devtool A work-in-progress of an example that modifies the kernel using the devtool. The procedure is not complete yet as it does not run properly. (From yocto-docs rev: 462ba2e46f237c294f05805ad5044291a085975d) Signed-off-by: Scott Rifenbark Signed-off-by: Richard Purdie --- documentation/dev-manual/dev-manual-start.xml | 13 + documentation/kernel-dev/kernel-dev-common.xml | 742 +++++++++++++------------ documentation/kernel-dev/kernel-dev-intro.xml | 22 +- 3 files changed, 408 insertions(+), 369 deletions(-) (limited to 'documentation') diff --git a/documentation/dev-manual/dev-manual-start.xml b/documentation/dev-manual/dev-manual-start.xml index 94595756b8..aa03d85c56 100644 --- a/documentation/dev-manual/dev-manual-start.xml +++ b/documentation/dev-manual/dev-manual-start.xml @@ -123,6 +123,19 @@ section in the Yocto Project Reference Manual. + Once you have completed the previous steps, you are ready to + continue using a given development path on your native Linux + machine. + If you are going to use BitBake, see the + "Cloning the poky Repository" + section. + If you are going to use the Extensible SDK, see the + "Using the Extensible SDK" + Chapter in the Yocto Project Software Development Kit (SDK) + Developer's Guide. + If you are going to use Toaster, see the + "Setting Up and Using Toaster" + section in the Toaster User Manual. diff --git a/documentation/kernel-dev/kernel-dev-common.xml b/documentation/kernel-dev/kernel-dev-common.xml index cb50912ea4..14381afefc 100644 --- a/documentation/kernel-dev/kernel-dev-common.xml +++ b/documentation/kernel-dev/kernel-dev-common.xml @@ -45,6 +45,67 @@ information. + + + Following is a detailed example showing how to create a layer + without the aid of tools for building the kernel: + + + Create additional structure: + Create the additional layer structure: + + $ cd ~/poky/meta-mylayer + $ mkdir conf + $ mkdir recipes-kernel + $ mkdir recipes-kernel/linux + $ mkdir recipes-kernel/linux/linux-yocto + + The conf directory holds your configuration files, while the + recipes-kernel directory holds your append file and + your patch file. + + + Create the layer configuration file: + Move to the meta-mylayer/conf + directory and create the layer.conf + file as follows: + + # We have a conf and classes directory, add to BBPATH + BBPATH .= ":${LAYERDIR}" + + # We have recipes-* directories, add to BBFILES + BBFILES += "${LAYERDIR}/recipes-*/*/*.bb \ + ${LAYERDIR}/recipes-*/*/*.bbappend" + + BBFILE_COLLECTIONS += "mylayer" + BBFILE_PATTERN_mylayer = "^${LAYERDIR}/" + BBFILE_PRIORITY_mylayer = "5" + + Notice mylayer as part of the last three + statements. + + Create the kernel recipe append file: + Move to the meta-mylayer/recipes-kernel/linux directory and create + the linux-yocto_3.4.bbappend file as follows: + + FILESEXTRAPATHS_prepend := "${THISDIR}/${PN}:" + + SRC_URI += "file://0001-calibrate-Add-printk-example.patch" + + The FILESEXTRAPATHS + and SRC_URI + statements enable the OpenEmbedded build system to find the patch file. + For more information on using append files, see the + "Using .bbappend Files in Your Layer" + section in the Yocto Project Development Manual. + + + Put the patch file in your layer: + Move the 0001-calibrate-Add-printk-example.patch file to + the meta-mylayer/recipes-kernel/linux/linux-yocto + directory. + +
@@ -72,11 +133,9 @@ Before modifying an existing recipe, be sure that you have created a minimal, custom layer from which you can work. - See the "Creating and Preparing a Layer" - section for some general resources. - You can also see the - "Set Up Your Layer for the Build" - section for a detailed example. + See the + "Creating and Preparing a Layer" + section for information.
@@ -452,63 +511,51 @@
Using <filename>devtool</filename> to Patch the Kernel - - Some stuff here for the using devtool from the wiki. - This whole section is WIP. - - - If you are dealing with real hardware, you can flash the - new kernel image to a USB stick and boot the hardware to - see it run. - - - Checkout and modify the kernel source. - This is where you make your changes to the image. - - - Create a new image that uses the altered kernel. - - - If you are working with actual hardware, you can flash - the new image to a USB stick and use it to boot up the - hardware. - You can see your changes in action. - - + This procedure currently does not work. + It is WIP. + + + + The steps in this procedure show you how you can patch the + kernel using the extensible SDK and devtool. + + Before attempting this procedure, be sure you have performed + the steps to get ready for updating the kernel as described + in the + "Getting Ready to Develop Using devtool" + 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. + 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 use the yocto-kernel script + 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. + 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. + 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 builds an extensible SDK, which is then used to - build, using devtool, a clean image for the - default qemux86 machine in a - Source Directory - named poky. - In the example, the - Build Directory - is build and is located in the default - poky_sdk directory. + + The example is a continuation of the setup procedure found in + the + "Getting Ready to Develop using devtool" + Section. + @@ -517,159 +564,93 @@ section. -
- Set Up the Build Host - - - Prior to creating any actual patches for your kernel, you - need to prepare the build host. - This example builds an extensible SDK. - Follow these steps: - - - Set Up the Build Environment: - Be sure you are set up to use BitBake in a shell. - See the - "Setting Up the Development Host to Use the Yocto Project" - section in the Yocto Project Development Manual for information - on how to get a build host ready that is either a native - Linux machine or a machine that uses CROPS. - - - Clone the poky Repository: - You need to have a local copy of the Yocto Project - Source Directory - (i.e. a local poky repository). - See the - "Cloning the poky Repository" - and possibly the - "Checking Out by Branch in Poky" - and - "Checking Out by Tag in Poky" - sections all in the Yocto Project Development Manual for - information on how to clone the poky - repository and check out the appropriate branch for your work. - - - Initialize the Build Environment: - While in the root directory of the Source Directory (i.e. - poky), run the - &OE_INIT_FILE; - environment setup script to define the OpenEmbedded - build environment on your build host. - - $ source &OE_INIT_FILE; - - Among other things, the script creates the - Build Directory, - which is build in this case - and is located in the - Source Directory. - After the script runs, your current working directory - is set to the build directory. - - For information on running a memory-resident - BitBake, - see the - oe-init-build-env-memres - setup script. - - - - -
- -
- Create a Layer for your Changes - - - The first step is to create a layer so you can isolate your - changes to the kernel. - Rather than use the yocto-layer script - to create the layer, this example steps through the process - by hand. - If you want information on the script that creates a general - layer, see the - "Creating a General Layer Using the yocto-layer Script" - section in the Yocto Project Development Manual. - - - - These two commands create a directory you can use for your - layer: - - $ cd ~/poky - $ mkdir meta-mylayer - - Creating a directory that follows the Yocto Project layer naming - conventions sets up the layer for your changes. - The layer is where you place your configuration files, append - files, and patch files. - To learn more about creating a layer and filling it with the - files you need, see the - "Understanding and Creating Layers" - section in the Yocto Project Development Manual. - -
- -
- Finding the Kernel Source Code - - - Each time you build a kernel image, the kernel source code - is fetched and unpacked into the following directory: + + + Check Out the Kernel Source Files: + First you must use devtool to checkout + the kernel source code in its workspace. + Be sure you are in the terminal set up to do work + with the extensible SDK. + + See this + step + in the + "Getting Ready to Develop Using devtool" + section for more information. + + Use the following devtool command + to check out the code: - ${S}/linux + $ devtool modify linux-yocto + Loading cache: 100% |#######################################################################| Time: 0:00:00 + Loaded 1300 entries from dependency cache. + WARNING: No bb files matched BBFILE_PATTERN_my-kernel '^/home/scottrif/poky_sdk/layers/meta-my-kernel/' + WARNING: No bb files matched BBFILE_PATTERN_my-kernel '^/home/scottrif/poky_sdk/layers/meta-my-kernel/' + WARNING: No bb files matched BBFILE_PATTERN_my-kernel '^/home/scottrif/poky_sdk/layers/meta-my-kernel/' + + Summary: There was 1 WARNING message shown. + Loading cache: 100% |########################################################################| Time: 0:00:00 + Loaded 1300 entries from dependency cache. + WARNING: No bb files matched BBFILE_PATTERN_my-kernel '^/home/scottrif/poky_sdk/layers/meta-my-kernel/' + WARNING: No bb files matched BBFILE_PATTERN_my-kernel '^/home/scottrif/poky_sdk/layers/meta-my-kernel/' + WARNING: No bb files matched BBFILE_PATTERN_my-kernel '^/home/scottrif/poky_sdk/layers/meta-my-kernel/' + + Summary: There was 1 WARNING message shown. + NOTE: Executing RunQueue Tasks + NOTE: Executing do_fetch... + NOTE: Executing do_unpack... + NOTE: Tasks Summary: Attempted 2 tasks of which 0 didn't need to be rerun and all succeeded. + NOTE: Executing RunQueue Tasks + NOTE: Executing do_kernel_checkout... + NOTE: Tasks Summary: Attempted 3 tasks of which 2 didn't need to be rerun and all succeeded. + NOTE: Patching... + NOTE: Executing RunQueue Tasks + NOTE: Executing do_validate_branches... + NOTE: Executing do_kernel_metadata... + NOTE: Executing do_patch... + NOTE: Tasks Summary: Attempted 6 tasks of which 3 didn't need to be rerun and all succeeded. + NOTE: Generating kernel config + NOTE: Executing RunQueue Tasks + NOTE: Executing do_kernel_configme... + NOTE: Executing do_prepare_recipe_sysroot... + NOTE: Executing do_configure... + NOTE: Tasks Summary: Attempted 9 tasks of which 6 didn't need to be rerun and all succeeded. + NOTE: Copying kernel config to srctree + NOTE: Source tree extracted to /home/scottrif/poky_sdk/workspace/sources/linux-yocto + NOTE: Recipe linux-yocto now set up to build from /home/scottrif/poky_sdk/workspace/sources/linux-yocto - See the "Finding Temporary Source Code" - section in the Yocto Project Development Manual and the - S - variable for more information about where source is kept - during a build. - - - - For this example, we are going to patch the - init/calibrate.c file - by adding some simple console printk statements that we can - see when we boot the image using QEMU. - -
- -
- Creating the Patch - - - Two methods exist by which you can create the patch: - devtool - and - Quilt. - For kernel patches, the Git workflow is more appropriate. - This section assumes the Git workflow and shows the steps - specific to this example. + + During the checkout operation, a bug exists that could + cause errors such as the following to appear: + + ERROR: Taskhash mismatch 2c793438c2d9f8c3681fd5f7bc819efa versus + be3a89ce7c47178880ba7bf6293d7404 for + /path/to/esdk/layers/poky/meta/recipes-kernel/linux/linux-yocto_4.10.bb.do_unpack + + You can safely ignore these messages. + The source code is correctly checked out. + + + + Edit the Source Files + Follow these steps to make some simple changes to the source + files: Change the working directory: + In the previous step, the output noted where you can find + the source files (e.g. + ~/poky_sdk/workspace/sources/linux-yocto). Change to where the kernel source code is before making your edits to the calibrate.c file: - $ cd ~/poky/build/tmp/work/qemux86-poky-linux/linux-yocto-${PV}-${PR}/linux + $ cd ~/poky_sdk/workspace/sources/linux-yocto - Because you are working in an established Git repository, - you must be in this directory in order to commit your changes - and create the patch file. - The PV and - PR variables - represent the version and revision for the - linux-yocto recipe. - The PV variable includes the Git meta and machine - hashes, which make the directory name longer than you might - expect. - + Edit the source file: - Edit the init/calibrate.c file to have the - following changes: + Edit the init/calibrate.c file to have + the following changes: void calibrate_delay(void) { @@ -687,202 +668,239 @@ . . . - - Stage and commit your changes: - These Git commands display the modified file, stage it, and then - commit the file: - - $ git status - $ git add init/calibrate.c - $ git commit -m "calibrate: Add printk example" - - Generate the patch file: - This Git command creates the a patch file named - 0001-calibrate-Add-printk-example.patch - in the current directory. - - $ git format-patch -1 - -
- -
- Set Up Your Layer for the Build - - These steps get your layer set up for the build: + + + Build the Updated Kernel Source: + To build the updated kernel source, use + devtool: + + $ devtool build linux-yocto + Parsing recipes: 100% |####################################################################################| Time: 0:00:31 + Parsing of 831 .bb files complete (0 cached, 831 parsed). 1300 targets, 48 skipped, 0 masked, 0 errors. + WARNING: No bb files matched BBFILE_PATTERN_my-kernel '^/home/scottrif/poky_sdk/layers/meta-my-kernel/' + NOTE: There are 1 recipes to be removed from sysroot qemux86, removing... + NOTE: Resolving any missing task queue dependencies + Initialising tasks: 100% |#################################################################################| Time: 0:00:00 + Checking sstate mirror object availability: 100% |#########################################################| Time: 0:00:00 + NOTE: Executing SetScene Tasks + NOTE: Executing RunQueue Tasks + linux-yocto-4.10.17+git999-r0 do_compile: NOTE: linux-yocto: compiling from external source tree /home/scottrif/poky_sdk/workspace/sources/linux-yocto + NOTE: Tasks Summary: Attempted 471 tasks of which 454 didn't need to be rerun and all succeeded. + + Summary: There was 1 WARNING message shown. + + + + + Create the Image With the New Kernel: + Use the devtool build-image command + to create a new image that has the new kernel. + + If the image you originally created resulted in a Wic + file, you can use an alternate method to create the new + image with the updated kernel. + For an example, see the steps in the + TipsAndTricks/KernelDevelopmentWithEsdk + Wiki Page. + + + $ cd ~ + $ devtool build-image core-image-minimal + Loading cache: 100% |###########################################################################| Time: 0:00:00 + Loaded 1299 entries from dependency cache. + Parsing recipes: 100% |#########################################################################| Time: 0:00:00 + Parsing of 831 .bb files complete (830 cached, 1 parsed). 1300 targets, 48 skipped, 0 masked, 0 errors. + WARNING: No bb files matched BBFILE_PATTERN_my-kernel '^/home/scottrif/poky_sdk/layers/meta-my-kernel/' + WARNING: No bb files matched BBFILE_PATTERN_my-kernel '^/home/scottrif/poky_sdk/layers/meta-my-kernel/' + WARNING: No bb files matched BBFILE_PATTERN_my-kernel '^/home/scottrif/poky_sdk/layers/meta-my-kernel/' + + Summary: There was 1 WARNING message shown. + WARNING: Skipping recipe linux-yocto as it doesn't produce a package with the same name + WARNING: No recipes in workspace, building image core-image-minimal unmodified + Loading cache: 100% |###########################################################################| Time: 0:00:00 + Loaded 1299 entries from dependency cache. + Parsing recipes: 100% |#########################################################################| Time: 0:00:00 + Parsing of 831 .bb files complete (830 cached, 1 parsed). 1300 targets, 48 skipped, 0 masked, 0 errors. + WARNING: No bb files matched BBFILE_PATTERN_my-kernel '^/home/scottrif/poky_sdk/layers/meta-my-kernel/' + NOTE: Resolving any missing task queue dependencies + Initialising tasks: 100% |######################################################################| Time: 0:00:06 + Checking sstate mirror object availability: 100% |##############################################| Time: 0:00:00 + NOTE: Executing SetScene Tasks + NOTE: Executing RunQueue Tasks + NOTE: Tasks Summary: Attempted 2393 tasks of which 2375 didn't need to be rerun and all succeeded. + + Summary: There was 1 WARNING message shown. + NOTE: Successfully built core-image-minimal. You can find output files in /home/scottrif/poky_sdk/tmp/deploy/images/qemux86 + + + + Test the New Image: + For this example, you can run the new image using QEMU + to verify your changes: - Boot the image: + + Boot the image: Boot the modified image in the QEMU emulator using this command: $ runqemu qemux86 - - Verify the changes: - Log into the machine using root with no password and then - use the following shell command to scroll through the console's boot output. + + + + Verify the changes: + Log into the machine using root + with no password and then use the following shell + command to scroll through the console's boot output. # dmesg | less - You should see the results of your printk statements - as part of the output. + You should see the results of your + printk statements + as part of the output when you scroll down the + console window. + - -
+ + + Stage and commit your changes: + Within your eSDK terminal, change your working directory to + where you modified the calibrate.c + file and use these Git commands to stage and commit your + changes: + + $ cd ~/poky_sdk/workspace/sources/linux-yocto + $ git status + $ git add init/calibrate.c + $ git commit -m "calibrate: Add printk example" + + + + Export the Patches and Create a .bbappend: + To export your commits as patches and create a + .bbappend file, use the following + command in the terminal used to work with the extensible + SDK. + This example uses the previously established layer named + meta-my-kernel. + + See Step 3 of the + "Getting Ready to Develop using devtool" + section for information on setting up this layer. + + + $ devtool finish linux-yocto /path/to/meta-my-kernel + + Once the command finishes, the patches and the + .bbappend file are located in the + ~/meta-my-kernel/recipes-kernel/linux + directory. + + + Build the Image With Your Modified Kernel: + You can now build an image that includes your kernel + patches. + Execute the following command from your + Build Directory + in the terminal set up to run BitBake: + + $ cd ~/poky/build + $ bitbake core-image-minimal + + +
@@ -1174,7 +1192,7 @@ are very time consuming. - + Once you are satisfied with your source code modifications, you can make them permanent by generating patches and applying them to the @@ -1183,7 +1201,7 @@ "Applying Patches" section. If you are not familiar with generating patches, refer to the - "Creating the Patch" + "I need a linked section here for the patch stuff" section.
diff --git a/documentation/kernel-dev/kernel-dev-intro.xml b/documentation/kernel-dev/kernel-dev-intro.xml index a2644aaa13..ce8e0fcb6d 100644 --- a/documentation/kernel-dev/kernel-dev-intro.xml +++ b/documentation/kernel-dev/kernel-dev-intro.xml @@ -108,6 +108,16 @@ "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. + @@ -156,7 +166,7 @@ building for the QEMU emulator in 32-bit mode. However, if you are not, you need to set the MACHINE variable appropriately in - your local.conf file found in the + your conf/local.conf file found in the Build Directory (i.e. ~/poky/build in this example). @@ -208,6 +218,7 @@ 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 @@ -290,12 +301,9 @@ 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. - Use a command similar to the following command to flash - the image: - - $ sudo dd if=tmp/deploy/images/architecture/core-image-minimal-architecture.wic of=/dev/sdd bs=1MB - $ sync - + For an example that uses a Minnowboard, see the + TipsAndTricks/KernelDevelopmentWithEsdk + Wiki page. -- cgit v1.2.3-54-g00ecf