| <!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" |
| "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" |
| [<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] > |
| |
| <chapter id='kernel-dev-common'> |
| |
| <title>Common Tasks</title> |
| |
| <para> |
| 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. |
| <note> |
| The examples presented in this chapter work with the Yocto Project |
| 1.2.2 Release and forward. |
| </note> |
| </para> |
| |
| <section id='creating-and-preparing-a-layer'> |
| <title>Creating and Preparing a Layer</title> |
| |
| <para> |
| 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 |
| <ulink url='&YOCTO_DOCS_DEV_URL;#bitbake-term'>BitBake</ulink> |
| append files |
| (<filename>.bbappend</filename>) and provides a convenient |
| mechanism to create your own recipe files |
| (<filename>.bb</filename>). |
| For details on how to create and work with layers, see the following |
| sections in the Yocto Project Development Manual: |
| <itemizedlist> |
| <listitem><para>"<ulink url='&YOCTO_DOCS_DEV_URL;#understanding-and-creating-layers'>Understanding and Creating Layers</ulink>" for |
| general information on layers and how to create layers.</para></listitem> |
| <listitem><para>"<ulink url='&YOCTO_DOCS_DEV_URL;#set-up-your-layer-for-the-build'>Set Up Your Layer for the Build</ulink>" for |
| specific instructions on setting up a layer for kernel |
| development.</para></listitem> |
| </itemizedlist> |
| </para> |
| </section> |
| |
| <section id='modifying-an-existing-recipe'> |
| <title>Modifying an Existing Recipe</title> |
| |
| <para> |
| 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 |
| <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink> |
| in <filename>meta/recipes-kernel/linux</filename>. |
| </para> |
| |
| <para> |
| Modifying an existing recipe can consist of the following: |
| <itemizedlist> |
| <listitem><para>Creating the append file</para></listitem> |
| <listitem><para>Applying patches</para></listitem> |
| <listitem><para>Changing the configuration</para></listitem> |
| </itemizedlist> |
| </para> |
| |
| <para> |
| Before modifying an existing recipe, be sure that you have created |
| a minimal, custom layer from which you can work. |
| See the "<link linkend='creating-and-preparing-a-layer'>Creating and Preparing a Layer</link>" |
| section for some general resources. |
| You can also see the |
| "<ulink url='&YOCTO_DOCS_DEV_URL;#set-up-your-layer-for-the-build'>Set Up Your Layer for the Build</ulink>" section |
| of the Yocto Project Development Manual for a detailed |
| example. |
| </para> |
| |
| <section id='creating-the-append-file'> |
| <title>Creating the Append File</title> |
| |
| <para> |
| 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 |
| <filename>meta/recipes-kernel/linux/linux-yocto_3.19.bb</filename> |
| recipe, the append file will typically be located as follows |
| within your custom layer: |
| <literallayout class='monospaced'> |
| <replaceable>your-layer</replaceable>/recipes-kernel/linux/linux-yocto_3.19.bbappend |
| </literallayout> |
| The append file should initially extend the |
| <ulink url='&YOCTO_DOCS_REF_URL;#var-FILESPATH'><filename>FILESPATH</filename></ulink> |
| search path by prepending the directory that contains your |
| files to the |
| <ulink url='&YOCTO_DOCS_REF_URL;#var-FILESEXTRAPATHS'><filename>FILESEXTRAPATHS</filename></ulink> |
| variable as follows: |
| <literallayout class='monospaced'> |
| FILESEXTRAPATHS_prepend := "${THISDIR}/${PN}:" |
| </literallayout> |
| The path <filename>${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-THISDIR'><filename>THISDIR</filename></ulink><filename>}/${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-PN'><filename>PN</filename></ulink><filename>}</filename> |
| 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 <filename>FILESPATH</filename> as |
| described above, you must place the files in your layer in the |
| following area: |
| <literallayout class='monospaced'> |
| <replaceable>your-layer</replaceable>/recipes-kernel/linux/linux-yocto/ |
| </literallayout> |
| <note>If you are working on a new machine Board Support Package |
| (BSP), be sure to refer to the |
| <ulink url='&YOCTO_DOCS_BSP_URL;'>Yocto Project Board Support Package (BSP) Developer's Guide</ulink>. |
| </note> |
| </para> |
| </section> |
| |
| <section id='applying-patches'> |
| <title>Applying Patches</title> |
| |
| <para> |
| 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 |
| <ulink url='&YOCTO_DOCS_REF_URL;#var-FILESEXTRAPATHS'><filename>FILESEXTRAPATHS</filename></ulink> |
| in your <filename>.bbappend</filename> file as described in |
| the previous section, and then reference them in |
| <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink> |
| statements. |
| </para> |
| |
| <para> |
| For example, you can apply a three-patch series by adding the |
| following lines to your linux-yocto |
| <filename>.bbappend</filename> file in your layer: |
| <literallayout class='monospaced'> |
| SRC_URI += "file://0001-first-change.patch" |
| SRC_URI += "file://0002-second-change.patch" |
| SRC_URI += "file://0003-third-change.patch" |
| </literallayout> |
| 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. |
| </para> |
| |
| <para> |
| For a detailed example showing how to patch the kernel, see the |
| "<ulink url='&YOCTO_DOCS_DEV_URL;#patching-the-kernel'>Patching the Kernel</ulink>" |
| section in the Yocto Project Development Manual. |
| </para> |
| </section> |
| |
| <section id='changing-the-configuration'> |
| <title>Changing the Configuration</title> |
| |
| <para> |
| You can make wholesale or incremental changes to the final |
| <filename>.config</filename> file used for the eventual |
| Linux kernel configuration by including a |
| <filename>defconfig</filename> file and by specifying |
| configuration fragments in the |
| <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink> |
| to be applied to that file. |
| </para> |
| |
| <para> |
| If you have a complete, working Linux kernel |
| <filename>.config</filename> |
| file you want to use for the configuration, as before, copy |
| that file to the appropriate <filename>${PN}</filename> |
| directory in your layer's |
| <filename>recipes-kernel/linux</filename> directory, |
| and rename the copied file to "defconfig". |
| Then, add the following lines to the linux-yocto |
| <filename>.bbappend</filename> file in your layer: |
| <literallayout class='monospaced'> |
| FILESEXTRAPATHS_prepend := "${THISDIR}/${PN}:" |
| SRC_URI += "file://defconfig" |
| </literallayout> |
| The <filename>SRC_URI</filename> tells the build system how to |
| search for the file, while the |
| <ulink url='&YOCTO_DOCS_REF_URL;#var-FILESEXTRAPATHS'><filename>FILESEXTRAPATHS</filename></ulink> |
| extends the |
| <ulink url='&YOCTO_DOCS_REF_URL;#var-FILESPATH'><filename>FILESPATH</filename></ulink> |
| variable (search directories) to include the |
| <filename>${PN}</filename> directory you created to hold the |
| configuration changes. |
| </para> |
| |
| <note> |
| The build system applies the configurations from the |
| <filename>defconfig</filename> file before applying any |
| subsequent configuration fragments. |
| The final kernel configuration is a combination of the |
| configurations in the <filename>defconfig</filename> 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 <filename>defconfig</filename> |
| file configurations. |
| </note> |
| |
| <para> |
| 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 <filename>8250.cfg</filename> in |
| the <filename>${PN}</filename> directory with the following |
| content (without indentation): |
| <literallayout class='monospaced'> |
| 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 |
| </literallayout> |
| Next, include this configuration fragment and extend the |
| <filename>FILESPATH</filename> variable in your |
| <filename>.bbappend</filename> file: |
| <literallayout class='monospaced'> |
| FILESEXTRAPATHS_prepend := "${THISDIR}/${PN}:" |
| SRC_URI += "file://8250.cfg" |
| </literallayout> |
| 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. |
| </para> |
| |
| <para> |
| For a detailed example showing how to configure the kernel, |
| see the |
| "<ulink url='&YOCTO_DOCS_DEV_URL;#configuring-the-kernel'>Configuring the Kernel</ulink>" |
| section in the Yocto Project Development Manual. |
| </para> |
| </section> |
| |
| <section id='using-an-in-tree-defconfig-file'> |
| <title>Using an "In-Tree" <filename>defconfig</filename> File</title> |
| |
| <para> |
| It might be desirable to have kernel configuration fragment |
| support through a <filename>defconfig</filename> file that |
| is pulled from the kernel source tree for the configured |
| machine. |
| By default, the OpenEmbedded build system looks for |
| <filename>defconfig</filename> files in the layer used for |
| Metadata, which is "out-of-tree", and then configures them |
| using the following: |
| <literallayout class='monospaced'> |
| SRC_URI += "file://defconfig" |
| </literallayout> |
| If you do not want to maintain copies of |
| <filename>defconfig</filename> files in your layer but would |
| rather allow users to use the default configuration from the |
| kernel tree and still be able to add configuration fragments |
| to the |
| <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink> |
| through, for example, append files, you can direct the |
| OpenEmbedded build system to use a |
| <filename>defconfig</filename> file that is "in-tree". |
| </para> |
| |
| <para> |
| To specify an "in-tree" <filename>defconfig</filename> file, |
| edit the recipe that builds your kernel so that it has the |
| following command form: |
| <literallayout class='monospaced'> |
| KBUILD_DEFCONFIG_KMACHINE ?= <replaceable>defconfig_file</replaceable> |
| </literallayout> |
| You need to append the variable with |
| <ulink url='&YOCTO_DOCS_REF_URL;#var-KMACHINE'><filename>KMACHINE</filename></ulink> |
| and then supply the path to your "in-tree" |
| <filename>defconfig</filename> file. |
| </para> |
| |
| <para> |
| Aside from modifying your kernel recipe and providing your own |
| <filename>defconfig</filename> file, you need to be sure no |
| files or statements set <filename>SRC_URI</filename> to use a |
| <filename>defconfig</filename> other than your "in-tree" |
| file (e.g. a kernel's <filename>linux-</filename><replaceable>machine</replaceable><filename>.inc</filename> |
| file). |
| In other words, if the build system detects a statement |
| that identifies an "out-of-tree" |
| <filename>defconfig</filename> file, that statement |
| will override your |
| <filename>KBUILD_DEFCONFIG</filename> variable. |
| </para> |
| |
| <para> |
| See the |
| <ulink url='&YOCTO_DOCS_REF_URL;#var-KBUILD_DEFCONFIG'><filename>KBUILD_DEFCONFIG</filename></ulink> |
| variable description for more information. |
| </para> |
| </section> |
| </section> |
| |
| <section id='using-an-iterative-development-process'> |
| <title>Using an Iterative Development Process</title> |
| |
| <para> |
| 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. |
| </para> |
| |
| <para> |
| As you read this section, be sure to substitute the name |
| of your Linux kernel recipe for the term |
| "linux-yocto". |
| </para> |
| |
| <section id='tip-dirty-string'> |
| <title>"-dirty" String</title> |
| |
| <!-- |
| <para> |
| <emphasis>AR - Darren Hart:</emphasis> This section |
| originated from the old Yocto Project Kernel Architecture |
| and Use Manual. |
| It was decided we need to put it in this section here. |
| Darren needs to figure out where we want it and what part |
| of it we want (all, revision???) |
| </para> |
| --> |
| |
| <para> |
| 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. |
| <literallayout class='monospaced'> |
| $ git status |
| </literallayout> |
| </para> |
| |
| <para> |
| 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. |
| </para> |
| |
| <para> |
| To force a pickup and commit of all such pending changes, |
| enter the following: |
| <literallayout class='monospaced'> |
| $ git add . |
| $ git commit -s -a -m "getting rid of -dirty" |
| </literallayout> |
| </para> |
| |
| <para> |
| Next, rebuild the kernel. |
| </para> |
| </section> |
| |
| <section id='generating-configuration-files'> |
| <title>Generating Configuration Files</title> |
| |
| <para> |
| You can manipulate the <filename>.config</filename> file |
| used to build a linux-yocto recipe with the |
| <filename>menuconfig</filename> command as follows: |
| <literallayout class='monospaced'> |
| $ bitbake linux-yocto -c menuconfig |
| </literallayout> |
| This command starts the Linux kernel configuration tool, |
| which allows you to prepare a new |
| <filename>.config</filename> file for the build. |
| When you exit the tool, be sure to save your changes |
| at the prompt. |
| </para> |
| |
| <para> |
| The resulting <filename>.config</filename> file is |
| located in the build directory, |
| <filename>${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-B'><filename>B</filename></ulink><filename>}</filename>, |
| which expands to |
| <filename>${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-WORKDIR'><filename>WORKDIR</filename></ulink><filename>}</filename><filename>/linux-</filename><filename>${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-PACKAGE_ARCH'><filename>PACKAGE_ARCH</filename></ulink><filename>}-${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-LINUX_KERNEL_TYPE'><filename>LINUX_KERNEL_TYPE</filename></ulink><filename>}-build</filename>. |
| You can use the entire <filename>.config</filename> file as the |
| <filename>defconfig</filename> file as described in the |
| "<link linkend='changing-the-configuration'>Changing the Configuration</link>" section. |
| For more information on the <filename>.config</filename> file, |
| see the |
| "<ulink url='&YOCTO_DOCS_DEV_URL;#using-menuconfig'>Using <filename>menuconfig</filename></ulink>" |
| section in the Yocto Project Development Manual. |
| <note> |
| You can determine what a variable expands to by looking |
| at the output of the <filename>bitbake -e</filename> |
| command: |
| <literallayout class='monospaced'> |
| $ bitbake -e virtual/kernel |
| </literallayout> |
| Search the output for the variable in which you are |
| interested to see exactly how it is expanded and used. |
| </note> |
| </para> |
| |
| <para> |
| 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 |
| <filename>menuconfig</filename> tool. |
| </para> |
| |
| <para> |
| To create a configuration fragment using this method, follow |
| these steps: |
| <orderedlist> |
| <listitem><para>Complete a build at least through the kernel |
| configuration task as follows: |
| <literallayout class='monospaced'> |
| $ bitbake linux-yocto -c kernel_configme -f |
| </literallayout> |
| This step ensures that you will be creating a |
| <filename>.config</filename> file from a known state. |
| Because situations exist where your build state might |
| become unknown, it is best to run the previous |
| command prior to starting up |
| <filename>menuconfig</filename>. |
| </para></listitem> |
| <listitem><para>Run the <filename>menuconfig</filename> |
| command: |
| <literallayout class='monospaced'> |
| $ bitbake linux-yocto -c menuconfig |
| </literallayout></para></listitem> |
| <listitem><para>Run the <filename>diffconfig</filename> |
| command to prepare a configuration fragment. |
| The resulting file <filename>fragment.cfg</filename> |
| will be placed in the |
| <filename>${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-WORKDIR'><filename>WORKDIR</filename></ulink><filename>}</filename> directory: |
| <literallayout class='monospaced'> |
| $ bitbake linux-yocto -c diffconfig |
| </literallayout></para></listitem> |
| </orderedlist> |
| </para> |
| |
| <para> |
| The <filename>diffconfig</filename> command creates a file that is a |
| list of Linux kernel <filename>CONFIG_</filename> assignments. |
| See the "<link linkend='changing-the-configuration'>Changing the Configuration</link>" |
| section for information on how to use the output as a |
| configuration fragment. |
| <note> |
| You can also use this method to create configuration |
| fragments for a BSP. |
| See the "<link linkend='bsp-descriptions'>BSP Descriptions</link>" |
| section for more information. |
| </note> |
| </para> |
| |
| <para> |
| 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 |
| <filename>.config</filename> 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: |
| <literallayout class='monospaced'> |
| $ 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 getting the config you wanted. |
| The full list can be found in your kernel src dir at: |
| meta/cfg/standard/mybsp/mismatch.cfg |
| </literallayout> |
| </para> |
| |
| <para> |
| 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 |
| <filename>kernel_configme</filename> and |
| <filename>kernel_configcheck</filename> commands until |
| they produce no warnings. |
| </para> |
| |
| <para> |
| For more information on how to use the |
| <filename>menuconfig</filename> tool, see the |
| "<ulink url='&YOCTO_DOCS_DEV_URL;#using-menuconfig'>Using <filename>menuconfig</filename></ulink>" |
| section in the Yocto Project Development Manual. |
| </para> |
| </section> |
| |
| <section id='modifying-source-code'> |
| <title>Modifying Source Code</title> |
| |
| <para> |
| 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: |
| <literallayout class='monospaced'> |
| $ bitbake linux-yocto -c kernel_configme -f |
| </literallayout> |
| Taking this step ensures you have the sources prepared |
| and the configuration completed. |
| You can find the sources in the build directory within the |
| <filename>source/</filename> directory, which is a symlink |
| (i.e. <filename>${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-B'><filename>B</filename></ulink><filename>}/source</filename>). |
| The <filename>source/</filename> directory expands to |
| <filename>${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-WORKDIR'><filename>WORKDIR</filename></ulink><filename>}</filename><filename>/linux-</filename><filename>${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-PACKAGE_ARCH'><filename>PACKAGE_ARCH</filename></ulink><filename>}-${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-LINUX_KERNEL_TYPE'><filename>LINUX_KERNEL_TYPE</filename></ulink><filename>}-build/source</filename>. |
| The directory pointed to by the |
| <filename>source/</filename> symlink is also known as |
| <filename>${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-STAGING_KERNEL_DIR'><filename>STAGING_KERNEL_DIR</filename></ulink><filename>}</filename>. |
| </para> |
| |
| <para> |
| 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 |
| <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-fetch'><filename>do_fetch</filename></ulink> |
| task for the recipe. |
| You can avoid triggering this task by not using BitBake to |
| run the |
| <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-cleanall'><filename>cleanall</filename></ulink>, |
| <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-cleansstate'><filename>cleansstate</filename></ulink>, |
| or forced |
| <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-fetch'><filename>fetch</filename></ulink> |
| commands. |
| Also, do not modify the recipe itself while working |
| with temporary changes or BitBake might run the |
| <filename>fetch</filename> command depending on the |
| changes to the recipe. |
| </para> |
| |
| <para> |
| To test your temporary changes, instruct BitBake to run the |
| <filename>compile</filename> again. |
| The <filename>-f</filename> option forces the command to run |
| even though BitBake might think it has already done so: |
| <literallayout class='monospaced'> |
| $ bitbake linux-yocto -c compile -f |
| </literallayout> |
| If the compile fails, you can update the sources and repeat |
| the <filename>compile</filename>. |
| Once compilation is successful, you can inspect and test |
| the resulting build (i.e. kernel, modules, and so forth) from |
| the following build directory: |
| <literallayout class='monospaced'> |
| ${WORKDIR}/linux-${PACKAGE_ARCH}-${LINUX_KERNEL_TYPE}-build |
| </literallayout> |
| Alternatively, you can run the <filename>deploy</filename> |
| command to place the kernel image in the |
| <filename>tmp/deploy/images</filename> directory: |
| <literallayout class='monospaced'> |
| $ bitbake linux-yocto -c deploy |
| </literallayout> |
| And, of course, you can perform the remaining installation and |
| packaging steps by issuing: |
| <literallayout class='monospaced'> |
| $ bitbake linux-yocto |
| </literallayout> |
| </para> |
| |
| <para> |
| 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. |
| </para> |
| |
| <para> |
| Once you are satisfied with your source code modifications, |
| you can make them permanent by generating patches and |
| applying them to the |
| <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink> |
| statement as described in the |
| "<link linkend='applying-patches'>Applying Patches</link>" |
| section. |
| If you are not familiar with generating patches, refer to the |
| "<ulink url='&YOCTO_DOCS_DEV_URL;#creating-the-patch'>Creating the Patch</ulink>" |
| section in the Yocto Project Development Manual. |
| </para> |
| </section> |
| </section> |
| |
| <section id='working-with-your-own-sources'> |
| <title>Working With Your Own Sources</title> |
| |
| <para> |
| 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 |
| <ulink url='&YOCTO_DOCS_DEV_URL;#metadata'>Metadata</ulink> 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. |
| </para> |
| |
| <para> |
| To help you use your own sources, the Yocto Project provides a |
| linux-yocto custom recipe |
| (<filename>linux-yocto-custom.bb</filename>) that uses |
| <filename>kernel.org</filename> sources |
| and the Yocto Project Linux kernel tools for managing |
| kernel Metadata. |
| You can find this recipe in the |
| <filename>poky</filename> Git repository of the |
| Yocto Project <ulink url='&YOCTO_GIT_URL;'>Source Repository</ulink> |
| at: |
| <literallayout class="monospaced"> |
| poky/meta-skeleton/recipes-kernel/linux/linux-yocto-custom.bb |
| </literallayout> |
| </para> |
| |
| <para> |
| Here are some basic steps you can use to work with your own sources: |
| <orderedlist> |
| <listitem><para>Copy the <filename>linux-yocto-custom.bb</filename> |
| 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. |
| <filename>linux-yocto-myproject_3.19.bb</filename>, |
| where "3.19" is the base version of the Linux kernel |
| with which you would be working).</para></listitem> |
| <listitem><para>In the same directory inside your layer, |
| create a matching directory |
| to store your patches and configuration files (e.g. |
| <filename>linux-yocto-myproject</filename>). |
| </para></listitem> |
| <listitem><para>Make sure you have either a |
| <filename>defconfig</filename> file or configuration |
| fragment files. |
| When you use the <filename>linux-yocto-custom.bb</filename> |
| recipe, you must specify a configuration. |
| If you do not have a <filename>defconfig</filename> file, |
| you can run the following: |
| <literallayout class='monospaced'> |
| $ make defconfig |
| </literallayout> |
| After running the command, copy the resulting |
| <filename>.config</filename> to the |
| <filename>files</filename> directory as "defconfig" and |
| then add it to the |
| <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink> |
| variable in the recipe.</para> |
| <para>Running the <filename>make defconfig</filename> |
| command results in the default configuration for your |
| architecture as defined by your kernel. |
| However, no guarantee exists that this configuration is |
| valid for your use case, or that your board will even boot. |
| This is particularly true for non-x86 architectures. |
| To use non-x86 <filename>defconfig</filename> files, you |
| need to be more specific and find one that matches your |
| board (i.e. for arm, you look in |
| <filename>arch/arm/configs</filename> and use the one that |
| is the best starting point for your board). |
| </para></listitem> |
| <listitem><para>Edit the following variables in your recipe |
| as appropriate for your project: |
| <itemizedlist> |
| <listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink>: |
| The <filename>SRC_URI</filename> should specify |
| a Git repository that uses one of the supported Git |
| fetcher protocols (i.e. <filename>file</filename>, |
| <filename>git</filename>, <filename>http</filename>, |
| and so forth). |
| The <filename>SRC_URI</filename> variable should |
| also specify either a <filename>defconfig</filename> |
| file or some configuration fragment files. |
| The skeleton recipe provides an example |
| <filename>SRC_URI</filename> as a syntax reference. |
| </para></listitem> |
| <listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-LINUX_VERSION'><filename>LINUX_VERSION</filename></ulink>: |
| The Linux kernel version you are using (e.g. |
| "3.19").</para></listitem> |
| <listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-LINUX_VERSION_EXTENSION'><filename>LINUX_VERSION_EXTENSION</filename></ulink>: |
| The Linux kernel <filename>CONFIG_LOCALVERSION</filename> |
| that is compiled into the resulting kernel and visible |
| through the <filename>uname</filename> command. |
| </para></listitem> |
| <listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-SRCREV'><filename>SRCREV</filename></ulink>: |
| The commit ID from which you want to build. |
| </para></listitem> |
| <listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-PR'><filename>PR</filename></ulink>: |
| 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. |
| </para></listitem> |
| <listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-PV'><filename>PV</filename></ulink>: |
| The default <filename>PV</filename> assignment is |
| typically adequate. |
| It combines the <filename>LINUX_VERSION</filename> |
| with the Source Control Manager (SCM) revision |
| as derived from the |
| <ulink url='&YOCTO_DOCS_REF_URL;#var-SRCPV'><filename>SRCPV</filename></ulink> |
| variable. |
| The combined results are a string with |
| the following form: |
| <literallayout class='monospaced'> |
| 3.19.11+git1+68a635bf8dfb64b02263c1ac80c948647cc76d5f_1+218bd8d2022b9852c60d32f0d770931e3cf343e2 |
| </literallayout> |
| While lengthy, the extra verbosity in <filename>PV</filename> |
| helps ensure you are using the exact |
| sources from which you intend to build. |
| </para></listitem> |
| <listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-COMPATIBLE_MACHINE'><filename>COMPATIBLE_MACHINE</filename></ulink>: |
| 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 <filename>qemux86</filename> |
| and <filename>qemux86-64</filename> machines, use |
| the following form: |
| <literallayout class='monospaced'> |
| COMPATIBLE_MACHINE = "qemux86|qemux86-64" |
| </literallayout></para></listitem> |
| </itemizedlist></para></listitem> |
| <listitem><para>Provide further customizations to your recipe |
| as needed just as you would customize an existing |
| linux-yocto recipe. |
| See the "<link linkend='modifying-an-existing-recipe'>Modifying |
| an Existing Recipe</link>" section for information. |
| </para></listitem> |
| </orderedlist> |
| </para> |
| </section> |
| |
| <section id='working-with-out-of-tree-modules'> |
| <title>Working with Out-of-Tree Modules</title> |
| |
| <para> |
| 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. |
| </para> |
| |
| <section id='building-out-of-tree-modules-on-the-target'> |
| <title>Building Out-of-Tree Modules on the Target</title> |
| |
| <para> |
| While the traditional Yocto Project development model would be |
| to include kernel modules as part of the normal build |
| process, you might find it useful to build modules on the |
| target. |
| This could be the case if your target system is capable |
| and powerful enough to handle the necessary compilation. |
| Before deciding to build on your target, however, you should |
| consider the benefits of using a proper cross-development |
| environment from your build host. |
| </para> |
| |
| <para> |
| 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 <filename>kernel-dev</filename> package |
| is installed by default on all |
| <filename>*.sdk</filename> images and the |
| <filename>kernel-devsrc</filename> package is installed |
| on many of the <filename>*.sdk</filename> 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. |
| </para> |
| |
| <para> |
| 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 <filename>/usr/src/kernel</filename> directory. |
| Next, <filename>make</filename> the scripts: |
| <literallayout class='monospaced'> |
| # cd /usr/src/kernel |
| # make scripts |
| </literallayout> |
| Because all SDK image recipes include |
| <filename>dev-pkgs</filename>, the |
| <filename>kernel-dev</filename> packages will be installed |
| as part of the SDK image and the |
| <filename>kernel-devsrc</filename> packages will be installed |
| as part of applicable SDK images. |
| 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. |
| </para> |
| </section> |
| |
| <section id='incorporating-out-of-tree-modules'> |
| <title>Incorporating Out-of-Tree Modules</title> |
| |
| <para> |
| While it is always preferable to work with sources integrated |
| into the Linux kernel sources, if you need an external kernel |
| module, the <filename>hello-mod.bb</filename> recipe is |
| available as a template from which you can create your |
| own out-of-tree Linux kernel module recipe. |
| </para> |
| |
| <para> |
| This template recipe is located in the |
| <filename>poky</filename> Git repository of the |
| Yocto Project <ulink url='&YOCTO_GIT_URL;'>Source Repository</ulink> |
| at: |
| <literallayout class="monospaced"> |
| poky/meta-skeleton/recipes-kernel/hello-mod/hello-mod_0.1.bb |
| </literallayout> |
| </para> |
| |
| <para> |
| To get started, copy this recipe to your layer and give it a |
| meaningful name (e.g. <filename>mymodule_1.0.bb</filename>). |
| In the same directory, create a new directory named |
| <filename>files</filename> 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: |
| <itemizedlist> |
| <listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-DESCRIPTION'><filename>DESCRIPTION</filename></ulink> |
| </para></listitem> |
| <listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-LICENSE'><filename>LICENSE*</filename></ulink> |
| </para></listitem> |
| <listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink> |
| </para></listitem> |
| <listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-PV'><filename>PV</filename></ulink> |
| </para></listitem> |
| </itemizedlist> |
| </para> |
| |
| <para> |
| Depending on the build system used by the module sources, |
| you might need to make some adjustments. |
| For example, a typical module <filename>Makefile</filename> |
| looks much like the one provided with the |
| <filename>hello-mod</filename> template: |
| <literallayout class='monospaced'> |
| obj-m := hello.o |
| |
| SRC := $(shell pwd) |
| |
| all: |
| $(MAKE) -C $(KERNEL_SRC) M=$(SRC) |
| |
| modules_install: |
| $(MAKE) -C $(KERNEL_SRC) M=$(SRC) modules_install |
| ... |
| </literallayout> |
| </para> |
| |
| <para> |
| The important point to note here is the |
| <ulink url='&YOCTO_DOCS_REF_URL;#var-KERNEL_SRC'><filename>KERNEL_SRC</filename></ulink> |
| variable. |
| The |
| <ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-module'><filename>module</filename></ulink> |
| class sets this variable and the |
| <ulink url='&YOCTO_DOCS_REF_URL;#var-KERNEL_PATH'><filename>KERNEL_PATH</filename></ulink> |
| variable to |
| <filename>${<ulink url='&YOCTO_DOCS_REF_URL;#var-STAGING_KERNEL_DIR'><filename>STAGING_KERNEL_DIR</filename></ulink>}</filename> |
| with the necessary Linux kernel build information to build |
| modules. |
| If your module <filename>Makefile</filename> uses a different |
| variable, you might want to override the |
| <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-compile'><filename>do_compile()</filename></ulink> |
| step, or create a patch to |
| the <filename>Makefile</filename> to work with the more typical |
| <filename>KERNEL_SRC</filename> or |
| <filename>KERNEL_PATH</filename> variables. |
| </para> |
| |
| <para> |
| 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: |
| <itemizedlist> |
| <listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE_ESSENTIAL_EXTRA_RDEPENDS'><filename>MACHINE_ESSENTIAL_EXTRA_RDEPENDS</filename></ulink> |
| </para></listitem> |
| <listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS'><filename>MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS</filename></ulink> |
| </para></listitem> |
| <listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE_EXTRA_RDEPENDS'><filename>MACHINE_EXTRA_RDEPENDS</filename></ulink> |
| </para></listitem> |
| <listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE_EXTRA_RRECOMMENDS'><filename>MACHINE_EXTRA_RRECOMMENDS</filename></ulink> |
| </para></listitem> |
| </itemizedlist> |
| </para> |
| |
| <para> |
| Modules are often not required for boot and can be excluded from |
| certain build configurations. |
| The following allows for the most flexibility: |
| <literallayout class='monospaced'> |
| MACHINE_EXTRA_RRECOMMENDS += "kernel-module-mymodule" |
| </literallayout> |
| The value is derived by appending the module filename without |
| the <filename>.ko</filename> extension to the string |
| "kernel-module-". |
| </para> |
| |
| <para> |
| Because the variable is |
| <ulink url='&YOCTO_DOCS_REF_URL;#var-RRECOMMENDS'><filename>RRECOMMENDS</filename></ulink> |
| and not a |
| <ulink url='&YOCTO_DOCS_REF_URL;#var-RDEPENDS'><filename>RDEPENDS</filename></ulink> |
| variable, the build will not fail if this module is not |
| available to include in the image. |
| </para> |
| </section> |
| </section> |
| |
| |
| <section id='inspecting-changes-and-commits'> |
| <title>Inspecting Changes and Commits</title> |
| |
| <para> |
| 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. |
| </para> |
| |
| <section id='what-changed-in-a-kernel'> |
| <title>What Changed in a Kernel?</title> |
| |
| <para> |
| 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. |
| <note> |
| In the following examples, unless you provide a commit |
| range, <filename>kernel.org</filename> 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 |
| <ulink url='http://git.yoctoproject.org/cgit.cgi'></ulink>. |
| </note> |
| To see a full range of the changes, use the |
| <filename>git whatchanged</filename> command and specify a |
| commit range for the branch |
| (<replaceable>commit</replaceable><filename>..</filename><replaceable>commit</replaceable>). |
| </para> |
| |
| <para> |
| Here is an example that looks at what has changed in the |
| <filename>emenlow</filename> branch of the |
| <filename>linux-yocto-3.19</filename> kernel. |
| The lower commit range is the commit associated with the |
| <filename>standard/base</filename> branch, while |
| the upper commit range is the commit associated with the |
| <filename>standard/emenlow</filename> branch. |
| <literallayout class='monospaced'> |
| $ git whatchanged origin/standard/base..origin/standard/emenlow |
| </literallayout> |
| </para> |
| |
| <para> |
| To see short, one line summaries of changes use the |
| <filename>git log</filename> command: |
| <literallayout class='monospaced'> |
| $ git log --oneline origin/standard/base..origin/standard/emenlow |
| </literallayout> |
| </para> |
| |
| <para> |
| Use this command to see code differences for the changes: |
| <literallayout class='monospaced'> |
| $ git diff origin/standard/base..origin/standard/emenlow |
| </literallayout> |
| </para> |
| |
| <para> |
| Use this command to see the commit log messages and the |
| text differences: |
| <literallayout class='monospaced'> |
| $ git show origin/standard/base..origin/standard/emenlow |
| </literallayout> |
| </para> |
| |
| <para> |
| 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 <filename>Documents</filename> |
| directory: |
| <literallayout class='monospaced'> |
| $ git format-patch -o $HOME/Documents origin/standard/base..origin/standard/emenlow |
| </literallayout> |
| </para> |
| </section> |
| |
| <section id='showing-a-particular-feature-or-branch-change'> |
| <title>Showing a Particular Feature or Branch Change</title> |
| |
| <para> |
| Tags in the Yocto Project kernel tree divide changes for |
| significant features or branches. |
| The <filename>git show</filename> <replaceable>tag</replaceable> |
| command shows changes based on a tag. |
| Here is an example that shows <filename>systemtap</filename> |
| changes: |
| <literallayout class='monospaced'> |
| $ git show systemtap |
| </literallayout> |
| You can use the |
| <filename>git branch --contains</filename> <replaceable>tag</replaceable> |
| command to show the branches that contain a particular feature. |
| This command shows the branches that contain the |
| <filename>systemtap</filename> feature: |
| <literallayout class='monospaced'> |
| $ git branch --contains systemtap |
| </literallayout> |
| </para> |
| </section> |
| </section> |
| |
| <section id='adding-recipe-space-kernel-features'> |
| <title>Adding Recipe-Space Kernel Features</title> |
| |
| <para> |
| You can add kernel features in the |
| <link linkend='recipe-space-metadata'>recipe-space</link> by |
| using the |
| <ulink url='&YOCTO_DOCS_REF_URL;#var-KERNEL_FEATURES'><filename>KERNEL_FEATURES</filename></ulink> |
| variable and by specifying the feature's <filename>.scc</filename> |
| file path in the |
| <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink> |
| statement. |
| When you add features using this method, the OpenEmbedded build |
| system checks to be sure the features are present. |
| If the features are not present, the build stops. |
| Kernel features are the last elements processed for configuring |
| and patching the kernel. |
| Therefore, adding features in this manner is a way |
| to enforce specific features are present and enabled |
| without needing to do a full audit of any other layer's additions |
| to the <filename>SRC_URI</filename> statement. |
| </para> |
| |
| <para> |
| You add a kernel feature by providing the feature as part of the |
| <filename>KERNEL_FEATURES</filename> variable and by providing the |
| path to the feature's <filename>.scc</filename> file, which is |
| relative to the root of the kernel Metadata. |
| The OpenEmbedded build system searches all forms of kernel |
| Metadata on the <filename>SRC_URI</filename> statement regardless |
| of whether the Metadata is in the "kernel-cache", system kernel |
| Metadata, or a recipe-space Metadata. |
| See the |
| "<link linkend='kernel-metadata-location'>Kernel Metadata Location</link>" |
| section for additional information. |
| </para> |
| |
| <para> |
| When you specify the feature's <filename>.scc</filename> file |
| on the <filename>SRC_URI</filename> statement, the OpenEmbedded |
| build system adds the directory of that |
| <filename>.scc</filename> file along with all its subdirectories |
| to the kernel feature search path. |
| Because subdirectories are searched, you can reference a single |
| <filename>.scc</filename> file in the |
| <filename>SRC_URI</filename> statement to reference multiple kernel |
| features. |
| </para> |
| |
| <para> |
| Consider the following example that adds the "test.scc" feature |
| to the build. |
| <orderedlist> |
| <listitem><para> |
| Create a <filename>.scc</filename> file and locate it |
| just as you would any other patch file, |
| <filename>.cfg</filename> file, or fetcher item |
| you specify in the <filename>SRC_URI</filename> |
| statement. |
| <note><title>Notes</title> |
| <itemizedlist> |
| <listitem><para> |
| You must add the directory of the |
| <filename>.scc</filename> file to the fetcher's |
| search path in the same manner as you would |
| add a <filename>.patch</filename> file. |
| </para></listitem> |
| <listitem><para> |
| You can create additional |
| <filename>.scc</filename> files beneath the |
| directory that contains the file you are |
| adding. |
| All subdirectories are searched during the |
| build as potential feature directories. |
| </para></listitem> |
| </itemizedlist> |
| </note> |
| Continuing with the example, suppose the "test.scc" |
| feature you are adding has a |
| <filename>test.scc</filename> file in the following |
| directory: |
| <literallayout class='monospaced'> |
| <replaceable>my_recipe</replaceable> |
| | |
| +-linux-yocto |
| | |
| +-test.cfg |
| +-test.scc |
| </literallayout> |
| In this example, the <filename>linux-yocto</filename> |
| directory has both the feature |
| <filename>test.scc</filename> file and a similarly |
| named configuration fragment file |
| <filename>test.cfg</filename>. |
| </para></listitem> |
| <listitem><para> |
| Add the <filename>.scc</filename> file to the |
| recipe's <filename>SRC_URI</filename> statement: |
| <literallayout class='monospaced'> |
| SRC_URI_append = " file://test.scc" |
| </literallayout> |
| The leading space before the path is important as the |
| path is appended to the existing path. |
| </para></listitem> |
| <listitem><para> |
| Specify the feature as a kernel feature: |
| <literallayout class='monospaced'> |
| KERNEL_FEATURES_append = " test.scc" |
| </literallayout> |
| The OpenEmbedded build system processes the kernel feature |
| when it builds the kernel. |
| <note> |
| If other features are contained below "test.scc", |
| then their directories are relative to the directory |
| containing the <filename>test.scc</filename> file. |
| </note> |
| </para></listitem> |
| </orderedlist> |
| </para> |
| </section> |
| </chapter> |
| <!-- |
| vim: expandtab tw=80 ts=4 |
| --> |