From 972dcfcdbfe75dcfeb777150c136576cf1a71e99 Mon Sep 17 00:00:00 2001 From: Tudor Florea Date: Fri, 9 Oct 2015 22:59:03 +0200 Subject: initial commit for Enea Linux 5.0 arm Signed-off-by: Tudor Florea --- documentation/kernel-dev/kernel-dev-common.xml | 915 +++++++++++++++++++++++++ 1 file changed, 915 insertions(+) create mode 100644 documentation/kernel-dev/kernel-dev-common.xml (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 new file mode 100644 index 0000000000..58cc98ddff --- /dev/null +++ b/documentation/kernel-dev/kernel-dev-common.xml @@ -0,0 +1,915 @@ + %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. + + + +
+ Creating and Preparing a Layer + + + If you are going to be modifying kernel recipes, it is recommended + that you create and prepare your own layer in which to do your + work. + Your layer contains its own + BitBake + append files + (.bbappend) and provides a convenient + mechanism to create your own recipe files + (.bb). + For details on how to create and work with layers, see the following + sections in the Yocto Project Development Manual: + + "Understanding and Creating Layers" for + general information on layers and how to create layers. + "Set Up Your Layer for the Build" for + specific instructions on setting up a layer for kernel + development. + + +
+ +
+ Modifying an Existing Recipe + + + In many cases, you can customize an existing linux-yocto recipe to + meet the needs of your project. + Each release of the Yocto Project provides a few Linux + kernel recipes from which you can choose. + These are located in the + Source Directory + in meta/recipes-kernel/linux. + + + + Modifying an existing recipe can consist of the following: + + Creating the append file + Applying patches + Changing the configuration + + + + + 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 + of the Yocto Project Development Manual for a detailed + example. + + +
+ Creating the Append File + + + You create this file in your custom layer. + You also name it accordingly based on the linux-yocto recipe + you are using. + For example, if you are modifying the + meta/recipes-kernel/linux/linux-yocto_3.4.bb + recipe, the append file will typically be located as follows + within your custom layer: + + your-layer/recipes-kernel/linux/linux-yocto_3.4.bbappend + + The append file should initially extend the + FILESPATH + search path by prepending the directory that contains your + files to the + FILESEXTRAPATHS + variable as follows: + + FILESEXTRAPATHS_prepend := "${THISDIR}/${PN}:" + + The path ${THISDIR}/${PN} + expands to "linux-yocto" in the current directory for this + example. + If you add any new files that modify the kernel recipe and you + have extended FILESPATH as + described above, you must place the files in your layer in the + following area: + + your-layer/recipes-kernel/linux/linux-yocto/ + + If you are working on a new machine Board Support Package + (BSP), be sure to refer to the + Yocto Project Board Support Package (BSP) Developer's Guide. + + +
+ +
+ Applying Patches + + + If you have a single patch or a small series of patches + that you want to apply to the Linux kernel source, you + can do so just as you would with any other recipe. + You first copy the patches to the path added to + FILESEXTRAPATHS + in your .bbappend file as described in + the previous section, and then reference them in + SRC_URI + statements. + + + + For example, you can apply a three-patch series by adding the + following lines to your linux-yocto .bbappend + file in your layer: + + SRC_URI += "file://0001-first-change.patch" + SRC_URI += "file://0002-first-change.patch" + SRC_URI += "file://0003-first-change.patch" + + The next time you run BitBake to build the Linux kernel, BitBake + detects the change in the recipe and fetches and applies the patches + before building the kernel. + + + + For a detailed example showing how to patch the kernel, see the + "Patching the Kernel" + section in the Yocto Project Development Manual. + +
+ +
+ Changing the Configuration + + + You can make wholesale or incremental changes to the Linux + kernel .config file by including a + defconfig and by specifying + configuration fragments in the + SRC_URI. + + + + If you have a final Linux kernel .config + file you want to use, copy it to a directory named + files, which must be in + your layer's recipes-kernel/linux + directory, and name the file "defconfig". + Then, add the following lines to your linux-yocto + .bbappend file in your layer: + + FILESEXTRAPATHS_prepend := "${THISDIR}/files:" + SRC_URI += "file://defconfig" + + The SRC_URI tells the build system how to + search for the file, while the + FILESEXTRAPATHS + extends the + FILESPATH + variable (search directories) to include the + files directory you created for the + configuration changes. + + + + The build system applies the configurations from the + .config file before applying any + subsequent configuration fragments. + The final kernel configuration is a combination of the + configurations in the .config file and + any configuration fragments you provide. + You need to realize that if you have any configuration + fragments, the build system applies these on top of and + after applying the existing .config + file configurations. + + + + Generally speaking, the preferred approach is to determine the + incremental change you want to make and add that as a + configuration fragment. + For example, if you want to add support for a basic serial + console, create a file named 8250.cfg in + the files directory with the following + content (without indentation): + + CONFIG_SERIAL_8250=y + CONFIG_SERIAL_8250_CONSOLE=y + CONFIG_SERIAL_8250_PCI=y + CONFIG_SERIAL_8250_NR_UARTS=4 + CONFIG_SERIAL_8250_RUNTIME_UARTS=4 + CONFIG_SERIAL_CORE=y + CONFIG_SERIAL_CORE_CONSOLE=y + + Next, include this configuration fragment and extend the + FILESPATH variable in your + .bbappend file: + + FILESEXTRAPATHS_prepend := "${THISDIR}/files:" + SRC_URI += "file://8250.cfg" + + The next time you run BitBake to build the Linux kernel, BitBake + detects the change in the recipe and fetches and applies the + new configuration before building the kernel. + + + + For a detailed example showing how to configure the kernel, + see the + "Configuring the Kernel" + section in the Yocto Project Development Manual. + +
+
+ +
+ Using an Iterative Development Process + + + If you do not have existing patches or configuration files, + you can iteratively generate them from within the BitBake build + environment as described within this section. + During an iterative workflow, running a previously completed BitBake + task causes BitBake to invalidate the tasks that follow the + completed task in the build sequence. + Invalidated tasks rebuild the next time you run the build using + BitBake. + + + + As you read this section, be sure to substitute the name + of your Linux kernel recipe for the term + "linux-yocto". + + +
+ "-dirty" String + + + + + If kernel images are being built with "-dirty" on the + end of the version string, this simply means that + modifications in the source directory have not been committed. + + $ git status + + + + + You can use the above Git command to report modified, + removed, or added files. + You should commit those changes to the tree regardless of + whether they will be saved, exported, or used. + Once you commit the changes, you need to rebuild the kernel. + + + + To force a pickup and commit of all such pending changes, + enter the following: + + $ git add . + $ git commit -s -a -m "getting rid of -dirty" + + + + + Next, rebuild the kernel. + +
+ +
+ Generating Configuration Files + + + You can manipulate the .config file + used to build a linux-yocto recipe with the + menuconfig command as follows: + + $ bitbake linux-yocto -c menuconfig + + This command starts the Linux kernel configuration tool, + which allows you to prepare a new + .config file for the build. + When you exit the tool, be sure to save your changes + at the prompt. + + + + The resulting .config file is + located in + ${WORKDIR} under the + linux-${MACHINE}-${KTYPE}-build directory. + You can use the entire .config file as the + defconfig file as described in the + "Changing the Configuration" section. + + + + A better method is to create a configuration fragment using the + differences between two configuration files: one previously + created and saved, and one freshly created using the + menuconfig tool. + + + + To create a configuration fragment using this method, follow + these steps: + + Complete a build at least through the kernel + configuration task as follows: + + $ bitbake linux-yocto -c kernel_configme -f + + Run the menuconfig + command: + + $ bitbake linux-yocto -c menuconfig + + Run the diffconfig + command to prepare a configuration fragment. + The resulting file fragment.cfg + will be placed in the + ${WORKDIR} directory: + + $ bitbake linux-yocto -c diffconfig + + + + + + The diffconfig command creates a file that is a + list of Linux kernel CONFIG_ assignments. + See the "Changing the Configuration" + section for information on how to use the output as a + configuration fragment. + + You can also use this method to create configuration + fragments for a BSP. + See the "BSP Descriptions" + section for more information. + + + + + The kernel tools also provide configuration validation. + You can use these tools to produce warnings for when a + requested configuration does not appear in the final + .config file or when you override a + policy configuration in a hardware configuration fragment. + Here is an example with some sample output of the command + that runs these tools: + + $ bitbake linux-yocto -c kernel_configcheck -f + + ... + + NOTE: validating kernel configuration + This BSP sets 3 invalid/obsolete kernel options. + These config options are not offered anywhere within this kernel. + The full list can be found in your kernel src dir at: + meta/cfg/standard/mybsp/invalid.cfg + + This BSP sets 21 kernel options that are possibly non-hardware related. + The full list can be found in your kernel src dir at: + meta/cfg/standard/mybsp/specified_non_hdw.cfg + + WARNING: There were 2 hardware options requested that do not + have a corresponding value present in the final ".config" file. + This probably means you are not't getting the config you wanted. + The full list can be found in your kernel src dir at: + meta/cfg/standard/mybsp/mismatch.cfg + + + + + The output describes the various problems that you can + encounter along with where to find the offending configuration + items. + You can use the information in the logs to adjust your + configuration files and then repeat the + kernel_configme and + kernel_configcheck commands until + they produce no warnings. + + + + For more information on how to use the + menuconfig tool, see the + "Using menuconfig" + section in the Yocto Project Development Manual. + +
+ +
+ Modifying Source Code + + + You can experiment with source code changes and create a + simple patch without leaving the BitBake environment. + To get started, be sure to complete a build at + least through the kernel configuration task: + + $ bitbake linux-yocto -c kernel_configme -f + + Taking this step ensures you have the sources prepared + and the configuration completed. + You can find the sources in the + ${WORKDIR}/linux directory. + + + + You can edit the sources as you would any other Linux source + tree. + However, keep in mind that you will lose changes if you + trigger the + do_fetch + task for the recipe. + You can avoid triggering this task by not using BitBake to + run the + cleanall, + cleansstate, + or forced + fetch + commands. + Also, do not modify the recipe itself while working + with temporary changes or BitBake might run the + fetch command depending on the + changes to the recipe. + + + + To test your temporary changes, instruct BitBake to run the + compile again. + The -f option forces the command to run + even though BitBake might think it has already done so: + + $ bitbake linux-yocto -c compile -f + + If the compile fails, you can update the sources and repeat + the compile. + Once compilation is successful, you can inspect and test + the resulting build (i.e. kernel, modules, and so forth) from + the Build Directory: + + ${WORKDIR}/linux-${MACHINE}-${KTYPE}-build + + Alternatively, you can run the deploy + command to place the kernel image in the + tmp/deploy/images directory: + + $ bitbake linux-yocto -c deploy + + And, of course, you can perform the remaining installation and + packaging steps by issuing: + + $ bitbake linux-yocto + + + + + For rapid iterative development, the edit-compile-repeat loop + described in this section is preferable to rebuilding the + entire recipe because the installation and packaging tasks + 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 + SRC_URI + statement as described in the + "Applying Patches" + section. + If you are not familiar with generating patches, refer to the + "Creating the Patch" + section in the Yocto Project Development Manual. + +
+
+ +
+ Working With Your Own Sources + + + If you cannot work with one of the Linux kernel + versions supported by existing linux-yocto recipes, you can + still make use of the Yocto Project Linux kernel tooling by + working with your own sources. + When you use your own sources, you will not be able to + leverage the existing kernel + Metadata and + stabilization work of the linux-yocto sources. + However, you will be able to manage your own Metadata in the same + format as the linux-yocto sources. + Maintaining format compatibility facilitates converging with + linux-yocto on a future, mutually-supported kernel version. + + + + To help you use your own sources, the Yocto Project provides a + linux-yocto custom recipe + (linux-yocto-custom.bb) that uses + kernel.org sources + and the Yocto Project Linux kernel tools for managing + kernel Metadata. + You can find this recipe in the + poky Git repository of the + Yocto Project Source Repository + at: + + poky/meta-skeleton/recipes-kernel/linux/linux-yocto-custom.bb + + + + + Here are some basic steps you can use to work with your own sources: + + Copy the linux-yocto-custom.bb + recipe to your layer and give it a meaningful name. + The name should include the version of the Linux kernel you + are using (e.g. linux-yocto-myproject_3.5.bb, + where "3.5" is the base version of the Linux kernel + with which you would be working). + In the same directory inside your layer, + create a matching directory + to store your patches and configuration files (e.g. + linux-yocto-myproject). + + Edit the following variables in your recipe + as appropriate for your project: + + SRC_URI: + The SRC_URI should be a Git + repository that uses one of the supported Git fetcher + protocols (i.e. file, + git, http, + and so forth). + The skeleton recipe provides an example + SRC_URI as a syntax reference. + + LINUX_VERSION: + The Linux kernel version you are using (e.g. + "3.4"). + LINUX_VERSION_EXTENSION: + The Linux kernel CONFIG_LOCALVERSION + that is compiled into the resulting kernel and visible + through the uname command. + + SRCREV: + The commit ID from which you want to build. + + PR: + Treat this variable the same as you would in any other + recipe. + Increment the variable to indicate to the OpenEmbedded + build system that the recipe has changed. + + PV: + The default PV assignment is + typically adequate. + It combines the LINUX_VERSION + with the Source Control Manager (SCM) revision + as derived from the + SRCPV + variable. + The combined results are a string with + the following form: + + 3.4.11+git1+68a635bf8dfb64b02263c1ac80c948647cc76d5f_1+218bd8d2022b9852c60d32f0d770931e3cf343e2 + + While lengthy, the extra verbosity in PV + helps ensure you are using the exact + sources from which you intend to build. + + COMPATIBLE_MACHINE: + A list of the machines supported by your new recipe. + This variable in the example recipe is set + by default to a regular expression that matches + only the empty string, "(^$)". + This default setting triggers an explicit build + failure. + You must change it to match a list of the machines + that your new recipe supports. + For example, to support the qemux86 + and qemux86-64 machines, use + the following form: + + COMPATIBLE_MACHINE = "qemux86|qemux86-64" + + + Provide further customizations to your recipe + as needed just as you would customize an existing + linux-yocto recipe. + See the "Modifying + an Existing Recipe" section for information. + + + +
+ +
+ Working with Out-of-Tree Modules + + + This section describes steps to build out-of-tree modules on + your target and describes how to incorporate out-of-tree modules + in the build. + + +
+ Building Out-of-Tree Modules on the Target + + + If you want to be able to build out-of-tree modules on + the target, there are some steps you need to take + on the target that is running your SDK image. + Briefly, the kernel-dev package + is installed by default on all + *.sdk images. + However, you need to create some scripts prior to + attempting to build the out-of-tree modules on the target + that is running that image. + + + + Prior to attempting to build the out-of-tree modules, + you need to be on the target as root and you need to + change to the /usr/src/kernel directory. + Next, make the scripts: + + # cd /usr/src/kernel + # make scripts + + Because all SDK image recipes include + dev-pkgs, the + kernel-dev packages will be installed + as part of the SDK image. + The SDK uses the scripts when building out-of-tree + modules. + Once you have switched to that directory and created the + scripts, you should be able to build your out-of-tree modules + on the target. + +
+ +
+ Incorporating Out-of-Tree Modules + + + While it is always preferable to work with sources integrated + into the Linux kernel sources, if you need an external kernel + module, the hello-mod.bb recipe is + available as a template from which you can create your + own out-of-tree Linux kernel module recipe. + + + + This template recipe is located in the + poky Git repository of the + Yocto Project Source Repository + at: + + poky/meta-skeleton/recipes-kernel/hello-mod/hello-mod_0.1.bb + + + + + To get started, copy this recipe to your layer and give it a + meaningful name (e.g. mymodule_1.0.bb). + In the same directory, create a new directory named + files where you can store any source files, + patches, or other files necessary for building + the module that do not come with the sources. + Finally, update the recipe as needed for the module. + Typically, you will need to set the following variables: + + DESCRIPTION + + LICENSE* + + SRC_URI + + PV + + + + + + Depending on the build system used by the module sources, + you might need to make some adjustments. + For example, a typical module Makefile + looks much like the one provided with the + hello-mod template: + + obj-m := hello.o + + SRC := $(shell pwd) + + all: + $(MAKE) -C $(KERNEL_SRC) M=$(SRC) + + modules_install: + $(MAKE) -C $(KERNEL_SRC) M=$(SRC) modules_install + ... + + + + + The important point to note here is the + KERNEL_SRC + variable. + The + module + class sets this variable and the + KERNEL_PATH + variable to + ${STAGING_KERNEL_DIR} + with the necessary Linux kernel build information to build + modules. + If your module Makefile uses a different + variable, you might want to override the + do_compile() + step, or create a patch to + the Makefile to work with the more typical + KERNEL_SRC or + KERNEL_PATH variables. + + + + After you have prepared your recipe, you will likely want to + include the module in your images. + To do this, see the documentation for the following variables in + the Yocto Project Reference Manual and set one of them + appropriately for your machine configuration file: + + MACHINE_ESSENTIAL_EXTRA_RDEPENDS + + MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS + + MACHINE_EXTRA_RDEPENDS + + MACHINE_EXTRA_RRECOMMENDS + + + + + + Modules are often not required for boot and can be excluded from + certain build configurations. + The following allows for the most flexibility: + + MACHINE_EXTRA_RRECOMMENDS += "kernel-module-mymodule" + + The value is derived by appending the module filename without + the .ko extension to the string + "kernel-module-". + + + + Because the variable is + RRECOMMENDS + and not a + RDEPENDS + variable, the build will not fail if this module is not + available to include in the image. + +
+
+ + +
+ Inspecting Changes and Commits + + + A common question when working with a kernel is: + "What changes have been applied to this tree?" + Rather than using "grep" across directories to see what has + changed, you can use Git to inspect or search the kernel tree. + Using Git is an efficient way to see what has changed in the tree. + + +
+ What Changed in a Kernel? + + + Following are a few examples that show how to use Git + commands to examine changes. + These examples are by no means the only way to see changes. + + In the following examples, unless you provide a commit + range, kernel.org history is blended + with Yocto Project kernel changes. + You can form ranges by using branch names from the + kernel tree as the upper and lower commit markers with + the Git commands. + You can see the branch names through the web interface + to the Yocto Project source repositories at + . + + To see a full range of the changes, use the + git whatchanged command and specify a + commit range for the branch + (<commit>..<commit>). + + + + Here is an example that looks at what has changed in the + emenlow branch of the + linux-yocto-3.4 kernel. + The lower commit range is the commit associated with the + standard/base branch, while + the upper commit range is the commit associated with the + standard/emenlow branch. + + $ git whatchanged origin/standard/base..origin/standard/emenlow + + + + + To see short, one line summaries of changes use the + git log command: + + $ git log --oneline origin/standard/base..origin/standard/emenlow + + + + + Use this command to see code differences for the changes: + + $ git diff origin/standard/base..origin/standard/emenlow + + + + + Use this command to see the commit log messages and the + text differences: + + $ git show origin/standard/base..origin/standard/emenlow + + + + + Use this command to create individual patches for + each change. + Here is an example that that creates patch files for each + commit and places them in your Documents + directory: + + $ git format-patch -o $HOME/Documents origin/standard/base..origin/standard/emenlow + + +
+ +
+ Showing a Particular Feature or Branch Change + + + Tags in the Yocto Project kernel tree divide changes for + significant features or branches. + The git show <tag> command shows + changes based on a tag. + Here is an example that shows systemtap + changes: + + $ git show systemtap + + You can use the + git branch --contains <tag> command + to show the branches that contain a particular feature. + This command shows the branches that contain the + systemtap feature: + + $ git branch --contains systemtap + + +
+
+ + -- cgit v1.2.3-54-g00ecf