documentation/kernel-dev/common.rst

8 with the Yocto Project Linux kernel. These tasks include preparing your
11 kernel, iterative development, working with your own sources, and
22 Before you can do any kernel development, you need to be sure your build
27 :term:`Source Directory` (``poky``) on your system. Follow the steps in the
29 section in the Yocto Project Development Tasks Manual to set up your
35    create your local branch by checking out a specific tag to get the
42 :ref:`devtool <sdk-manual/extensible:using \`\`devtool\`\` in your sdk workflow>`
69 2. *Prepare Your local.conf File:* By default, the
73    :term:`MACHINE` variable appropriately in your ``conf/local.conf`` file
97       Add your new layer with 'bitbake-layers add-layer ../../meta-mylayer'
113 4. *Inform the BitBake Build Environment About Your Layer:* As directed
114    when you created your layer, you need to add the layer to the
199    the image to a USB stick on ``/dev/sdd`` and boot your device. For an
247 2. *Prepare Your local.conf File:* By default, the
251    :term:`MACHINE` variable appropriately in your ``conf/local.conf`` file
275       Add your new layer with 'bitbake-layers add-layer ../../meta-mylayer'
290 4. *Inform the BitBake Build Environment About Your Layer:* As directed
291    when you created your layer, you need to add the layer to the
305    For simplicity, it is recommended that you create your copy of the
334    simplicity, it is recommended that you create your copy of the kernel
362 you create and prepare your own layer in which to do your work. Your
365 create your own recipe files (``.bb``) as well as store and use kernel
381 tools. These steps assume creation of a layer named ``mylayer`` in your
392    The ``conf`` directory holds your configuration files, while the
393    ``recipes-kernel`` directory holds your append file and eventual
428    ":ref:`dev-manual/common-tasks:appending other layers metadata with your layer`"
435 the needs of your project. Each release of the Yocto Project provides a
456 You create this file in your custom layer. You also name it accordingly
459 the append file will typically be located as follows within your custom
464    your-layer/recipes-kernel/linux/linux-yocto_4.12.bbappend
468 prepending the directory that contains your files to the
478 your layer in the following area::
480    your-layer/recipes-kernel/linux/linux-yocto/
544 for your BSP. When developing a BSP, you probably have a kernel
546 taken together, define the kernel configuration for your BSP. You can
548 set of files inside a directory located at the same level as your
567 the following in your append file::
573 Another variable you can use in your kernel recipe append file is the
584    make your changes, and then push the changes to the local bare clone
586    options to the ``meta`` branch for your BSP. The configuration
606 your ``.bbappend`` file as described in the previous section, and then
611 lines to your linux-yocto ``.bbappend`` file in your layer::
639 appropriate ``${PN}`` directory in your layer's ``recipes-kernel/linux``
641 following lines to the linux-yocto ``.bbappend`` file in your layer::
658 in the linux-yocto ``.bbappend`` file in your layer::
687 configuration fragment and extend the :term:`FILESPATH` variable in your
712 ``defconfig`` files in your layer but would rather allow users to use
731 Aside from modifying your kernel recipe and providing your own
733 :term:`SRC_URI` to use a ``defconfig`` other than your "in-tree" file (e.g.
736 ``defconfig`` file, that statement will override your
803       kernel source code is before making your edits to the
851    using QEMU to verify your changes:
867       the results of your ``printk`` statements as part of the output
870 6. *Stage and commit your changes*: Within your eSDK terminal, change
871    your working directory to where you modified the ``calibrate.c`` file
872    and use these Git commands to stage and commit your changes::
879 7. *Export the Patches and Create an Append File:* To export your
897 8. *Build the Image With Your Modified Kernel:* You can now build an
898    image that includes your kernel patches. Execute the following
899    command from your
937    to create a local copy of the repository for your kernel. Assuming
944       where the kernel source code is before making your edits to the
969 2. *Stage and Commit Your Changes:* Use standard Git commands to stage
976    stage and commit your changes, the OpenEmbedded Build System will not
979 3. *Update Your local.conf File to Point to Your Source Files:* In
980    addition to your ``local.conf`` file specifying to use
985    to the following to your ``local.conf``::
999       with the pathname to your local Git repositories. Also, you must
1003 4. *Build the Image:* With the source modified, your changes staged and
1017 6. *Look for Your Changes:* As QEMU booted, you might have seen your
1018    changes rapidly scroll by. If not, use these commands to see your
1025    You should see the results of your
1029 7. *Generate the Patch File:* Once you are sure that your patch works
1037 8. *Move the Patch File to Your Layer:* In order for subsequent builds
1039    the previous step to your layer ``meta-mylayer``. For this example,
1040    the layer created earlier is located in your home directory as
1044    additional structure to your layer using the following commands::
1052    hierarchy in your layer, you can move the patch file using the
1060    needs to be in your layer's ``recipes-kernel/linux`` directory and it
1073    ":ref:`dev-manual/common-tasks:appending other layers metadata with your layer`"
1078       To build ``core-image-minimal`` again and see the effects of your patch,
1096 fragments to make sure your ``.config`` file is just how you need it.
1101 configuration fragments, and how to interactively modify your
1120    set up your environment by running the
1124 -  You must be sure of the state of your build's configuration in the
1127 -  Your build host must have the following two packages installed::
1144 kernel configuration parameters. After making your changes, simply exit
1145 the tool and save your changes to create an updated version of the
1207 your base to create configuration fragments to permanently save in your
1234 your layer's ``recipes-kernel/linux`` directory, and rename the copied
1237 add the following lines to the linux-yocto ``.bbappend`` file in your
1310    your build state might become unknown, it is best to run this task
1336 Where do you put your configuration fragment files? You can place these
1338 :term:`SRC_URI` as directed by your
1339 ``bblayers.conf`` file, which is located in your layer. The OpenEmbedded
1344 the kernel's append file within your layer and then add the following
1355 :term:`SRC_URI` statement like the following in your append file::
1441 information in the logs to adjust your configuration files and then
1490    successfully. Use this configuration file as your baseline.
1514    results of your changes. If you have more issues, you can deal with
1558    Depending on your particular kernel development workflow, the
1567 Working With Your Own Sources
1572 Project Linux kernel tooling by working with your own sources. When you
1573 use your own sources, you will not be able to leverage the existing
1576 your own Metadata in the same format as the linux-yocto sources.
1580 To help you use your own sources, the Yocto Project provides a
1587 Here are some basic steps you can use to work with your own sources:
1590    ``linux-yocto-custom.bb`` recipe to your layer and give it a
1596 2. *Create a Directory for Your Patches:* In the same directory inside
1597    your layer, create a matching directory to store your patches and
1601    ``defconfig`` file or configuration fragment files in your layer.
1609    resulting ``.config`` file to the ``files`` directory in your layer
1615    configuration for your architecture as defined by your kernel.
1617    your use case, or that your board will even boot. This is
1621    find one that matches your board (i.e. for arm, you look in
1623    for your board).
1625 4. *Edit the Recipe:* Edit the following variables in your recipe as
1626    appropriate for your project:
1664       A list of the machines supported by your new recipe. This variable
1668       list of the machines that your new recipe supports. For example,
1674 5. *Customize Your Recipe as Needed:* Provide further customizations to
1675    your recipe as needed just as you would customize an existing
1683 This section describes steps to build out-of-tree modules on your target
1692 your target system is capable and powerful enough to handle the
1693 necessary compilation. Before deciding to build on your target, however,
1695 environment from your build host.
1698 are some steps you need to take on the target that is running your SDK
1719 should be able to build your out-of-tree modules on the target.
1727 create your own out-of-tree Linux kernel module recipe.
1734 To get started, copy this recipe to your layer and give it a meaningful
1768 information to build modules. If your module ``Makefile`` uses a
1774 After you have prepared your recipe, you will likely want to include the
1775 module in your images. To do this, see the documentation for the
1777 them appropriately for your machine configuration file:
1852 in your ``Documents`` directory::