Lines Matching +full:in +full:- +full:kernel
1 .. SPDX-License-Identifier: CC-BY-SA-2.0-UK
8 with the Yocto Project Linux kernel. These tasks include preparing your
9 host development system for kernel development, preparing a layer,
10 modifying an existing recipe, patching the kernel, configuring the
11 kernel, iterative development, working with your own sources, and
12 incorporating out-of-tree modules.
16 The examples presented in this chapter work with the Yocto Project
19 Preparing the Build Host to Work on the Kernel
22 Before you can do any kernel development, you need to be sure your build
24 set up, see the ":doc:`/dev-manual/start`" section in
27 :term:`Source Directory` (``poky``) on your system. Follow the steps in the
28 ":ref:`dev-manual/start:cloning the \`\`poky\`\` repository`"
29 section in the Yocto Project Development Tasks Manual to set up your
37 ":ref:`dev-manual/start:checking out by branch in poky`" and
38 ":ref:`dev-manual/start:checking out by tag in poky`"
39 sections in the Yocto Project Development Tasks Manual for more information.
41 Kernel development is best accomplished using
42 :ref:`devtool <sdk-manual/extensible:using \`\`devtool\`\` in your sdk workflow>`
43 and not through traditional kernel workflow methods. The remainder of
47 ------------------------------------------
49 Follow these steps to prepare to update the kernel image using
50 ``devtool``. Completing this procedure leaves you with a clean kernel
51 image and ready to make modifications as described in the
52 ":ref:`kernel-dev/common:using \`\`devtool\`\` to patch the kernel`"
57 the build environment script (i.e. :ref:`structure-core-script`)::
60 $ source oe-init-build-env
65 :ref:`overview-manual/development-environment:yocto project source repositories`
71 "qemux86-64", which is fine if you are building for the QEMU emulator
72 in 64-bit mode. However, if you are not, you need to set the
73 :term:`MACHINE` variable appropriately in your ``conf/local.conf`` file
74 found in the
76 ``poky/build`` in this example).
78 Also, since you are preparing to work on the kernel image, you need
81 variable to include kernel modules.
83 In this example we wish to build for qemux86 so we must set the
84 :term:`MACHINE` variable to "qemux86" and also add the "kernel-modules".
88 MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS += "kernel-modules"
91 patches created for the kernel image. You can use the
92 ``bitbake-layers create-layer`` command as follows::
95 $ bitbake-layers create-layer ../../meta-mylayer
97 Add your new layer with 'bitbake-layers add-layer ../../meta-mylayer'
104 ":ref:`dev-manual/common-tasks:understanding and creating layers`"
105 section in the Yocto Project Development Tasks Manual and the
106 ":ref:`bsp-guide/bsp:bsp layers`" section in the Yocto Project Board
108 use the ``bitbake-layers create-layer`` command to quickly set up a layer,
110 … ":ref:`dev-manual/common-tasks:creating a general layer using the \`\`bitbake-layers\`\` script`"
111 section in the Yocto Project Development Tasks Manual.
115 :term:`BBLAYERS` variable in the
119 $ bitbake-layers add-layer ../../meta-mylayer
127 $ bitbake core-image-minimal -c populate_sdk_ext
131 ``*.sh`` file) in the following directory::
136 ``poky-glibc-x86_64-core-image-minimal-i586-toolchain-ext-&DISTRO;.sh``.
139 the SDK. For this example, install the SDK in the default
143 $ ./poky-glibc-x86_64-core-image-minimal-i586-toolchain-ext-&DISTRO;.sh
159 …Each time you wish to use the SDK in a new shell session, you need to source the environment setup…
160 $ . /home/scottrif/poky_sdk/environment-setup-i586-poky-linux
170 $ source poky_sdk/environment-setup-i586-poky-linux
172 Run devtool --help for further details.
176 If you get a warning about attempting to use the extensible SDK in
179 8. *Build the Clean Image:* The final step in preparing to work on the
180 kernel is to build an initial image using ``devtool`` in the new
183 $ devtool build-image
186 WARNING: No packages to add, building image core-image-minimal unmodified
195 …NOTE: Successfully built core-image-minimal. You can find output files in /home/scottrif/poky_sdk/…
205 kernel by using the extensible SDK. For a continued example, see the
206 ":ref:`kernel-dev/common:using \`\`devtool\`\` to patch the kernel`"
209 Getting Ready for Traditional Kernel Development
210 ------------------------------------------------
212 Getting ready for traditional kernel development using the Yocto Project
213 involves many of the same steps as described in the previous section.
214 However, you need to establish a local copy of the kernel source since
217 Follow these steps to prepare to update the kernel image using
218 traditional kernel development flow with the Yocto Project. Completing
219 this procedure leaves you ready to make modifications to the kernel
220 source as described in the ":ref:`kernel-dev/common:using traditional kernel development to patch t…
226 :ref:`structure-core-script`).
230 ":ref:`dev-manual/start:checking out by branch in poky`"
231 section in the Yocto Project Development Tasks Manual.
238 $ source oe-init-build-env
243 :ref:`overview-manual/development-environment:yocto project source repositories`
249 "qemux86-64", which is fine if you are building for the QEMU emulator
250 in 64-bit mode. However, if you are not, you need to set the
251 :term:`MACHINE` variable appropriately in your ``conf/local.conf`` file
252 found in the
254 ``poky/build`` in this example).
256 Also, since you are preparing to work on the kernel image, you need
259 variable to include kernel modules.
261 In this example we wish to build for qemux86 so we must set the
262 :term:`MACHINE` variable to "qemux86" and also add the "kernel-modules".
266 MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS += "kernel-modules"
269 patches created for the kernel image. You can use the
270 ``bitbake-layers create-layer`` command as follows::
273 $ bitbake-layers create-layer ../../meta-mylayer
275 Add your new layer with 'bitbake-layers add-layer ../../meta-mylayer'
281 ":ref:`dev-manual/common-tasks:understanding and creating layers`"
282 section in the Yocto Project Development Tasks Manual and the
283 ":ref:`bsp-guide/bsp:bsp layers`" section in the Yocto Project Board
285 use the ``bitbake-layers create-layer`` command to quickly set up a layer,
287 … ":ref:`dev-manual/common-tasks:creating a general layer using the \`\`bitbake-layers\`\` script`"
288 section in the Yocto Project Development Tasks Manual.
292 :term:`BBLAYERS` variable in the
296 $ bitbake-layers add-layer ../../meta-mylayer
300 5. *Create a Local Copy of the Kernel Git Repository:* You can find Git
302 "Yocto Linux Kernel" in the Yocto Project Source Repositories at
306 kernel Git repository outside of the
308 usually named ``poky``. Also, be sure you are in the
312 ``linux-yocto-4.12`` kernel and be in the ``standard/base`` branch.
316 The ``linux-yocto-4.12`` kernel can be used with the Yocto Project 2.4
318 You cannot use the ``linux-yocto-4.12`` kernel with releases prior to
324 $ git clone git://git.yoctoproject.org/linux-yocto-4.12 --branch standard/base
325 Cloning into 'linux-yocto-4.12'...
333 6. *Create a Local Copy of the Kernel Cache Git Repository:* For
334 simplicity, it is recommended that you create your copy of the kernel
337 usually named ``poky``. Also, for this example, be sure you are in
338 the ``yocto-4.12`` branch.
341 ``yocto-kernel-cache`` and switch to the ``yocto-4.12`` branch::
344 $ git clone git://git.yoctoproject.org/yocto-kernel-cache --branch yocto-4.12
345 Cloning into 'yocto-kernel-cache'...
353 At this point, you are ready to start making modifications to the kernel
354 using traditional kernel development steps. For a continued example, see
355 the ":ref:`kernel-dev/common:using traditional kernel development to patch the kernel`"
361 If you are going to be modifying kernel recipes, it is recommended that
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
367 ":ref:`dev-manual/common-tasks:understanding and creating layers`"
368 section in the Yocto Project Development Tasks Manual.
373 to perform. One such tool is the ``bitbake-layers create-layer``
375 ":ref:`dev-manual/common-tasks:creating a general layer using the \`\`bitbake-layers\`\` script`"
376 section in the Yocto Project Development Tasks Manual for
379 To better understand the layer you create for kernel development, the
381 tools. These steps assume creation of a layer named ``mylayer`` in your
386 $ mkdir meta-mylayer
387 $ mkdir meta-mylayer/conf
388 $ mkdir meta-mylayer/recipes-kernel
389 $ mkdir meta-mylayer/recipes-kernel/linux
390 $ mkdir meta-mylayer/recipes-kernel/linux/linux-yocto
393 ``recipes-kernel`` directory holds your append file and eventual
397 ``meta-mylayer/conf`` directory and create the ``layer.conf`` file as
403 # We have recipes-* directories, add to BBFILES
404 BBFILES += "${LAYERDIR}/recipes-*/*/*.bb \
405 ${LAYERDIR}/recipes-*/*/*.bbappend"
413 3. *Create the Kernel Recipe Append File*: Move to the
414 ``meta-mylayer/recipes-kernel/linux`` directory and create the
415 kernel's append file. This example uses the ``linux-yocto-4.12``
416 kernel. Thus, the name of the append file is
417 ``linux-yocto_4.12.bbappend``::
421 SRC_URI:append = " file://patch-file-one.patch"
422 SRC_URI:append = " file://patch-file-two.patch"
423 SRC_URI:append = " file://patch-file-three.patch"
428 ":ref:`dev-manual/common-tasks:appending other layers metadata with your layer`"
429 section in the Yocto Project Development Tasks Manual.
434 In many cases, you can customize an existing linux-yocto recipe to meet
436 few Linux kernel recipes from which you can choose. These are located in
437 the :term:`Source Directory` in
438 ``meta/recipes-kernel/linux``.
442 - :ref:`kernel-dev/common:creating the append file`
444 - :ref:`kernel-dev/common:applying patches`
446 - :ref:`kernel-dev/common:changing the configuration`
450 ":ref:`kernel-dev/common:creating and preparing a layer`" section for
454 ------------------------
456 You create this file in your custom layer. You also name it accordingly
457 based on the linux-yocto recipe you are using. For example, if you are
458 modifying the ``meta/recipes-kernel/linux/linux-yocto_4.12.bb`` recipe,
462 .. code-block:: none
464 your-layer/recipes-kernel/linux/linux-yocto_4.12.bbappend
475 expands to "linux-yocto" in the current directory for this example. If
476 you add any new files that modify the kernel recipe and you have
477 extended :term:`FILESPATH` as described above, you must place the files in
478 your layer in the following area::
480 your-layer/recipes-kernel/linux/linux-yocto/
485 sure to refer to the :doc:`/bsp-guide/index`.
487 As an example, consider the following append file used by the BSPs in
488 ``meta-yocto-bsp``:
490 .. code-block:: none
492 meta-yocto-bsp/recipes-kernel/linux/linux-yocto_4.12.bbappend
495 strings in this example listing might be different than the actual
496 strings in the file from the ``meta-yocto-bsp`` layer upstream.
500 KBRANCH:genericx86-64 = "standard/base"
502 KMACHINE:genericx86 ?= "common-pc"
503 KMACHINE:genericx86-64 ?= "common-pc-64"
508 SRCREV_machine:genericx86-64 ?= "d09f2ce584d60ecb7890550c22a80c48b83c2e19"
514 COMPATIBLE_MACHINE:genericx86-64 = "genericx86-64"
519 LINUX_VERSION:genericx86-64 = "4.12.7"
530 machine name used by the Linux Yocto kernel. The file also uses the
532 ensure the build process uses the appropriate kernel branch.
536 variable could be used to enable features specific to the kernel. The
537 append file points to specific commits in the
539 the ``meta`` Git repository branches to identify the exact kernel needed
542 One thing missing in this particular BSP, which you will typically need
543 when developing a BSP, is the kernel configuration file (``.config``)
544 for your BSP. When developing a BSP, you probably have a kernel
545 configuration file or a set of kernel configuration files that, when
546 taken together, define the kernel configuration for your BSP. You can
547 accomplish this definition by putting the configurations in a file or a
549 kernel's append file and having the same name as the kernel's main
551 in the :term:`SRC_URI` statement in
554 For example, suppose you had some configuration options in a file called
556 named ``linux-yocto`` and then add a :term:`SRC_URI` statement such as the
558 the kernel, the configuration options are picked up and applied.
567 the following in your append file::
573 Another variable you can use in your kernel recipe append file is the
583 kernel repository, you could checkout the kernel's ``meta`` branch,
585 of the kernel. The result is that you directly add configuration
587 options will likely end up in that location anyway if the BSP gets
590 In general, however, the Yocto Project maintainers take care of
591 moving the :term:`SRC_URI`-specified configuration options to the
592 kernel's ``meta`` branch. Not only is it easier for BSP developers
593 not to have to put those configurations in the branch,
596 BSPs in the tree are typically using. This allows for promotion of
600 ----------------
603 apply to the Linux kernel source, you can do so just as you would with
605 :term:`FILESEXTRAPATHS` in
606 your ``.bbappend`` file as described in the previous section, and then
607 reference them in :term:`SRC_URI`
610 For example, you can apply a three-patch series by adding the following
611 lines to your linux-yocto ``.bbappend`` file in your layer::
613 SRC_URI += "file://0001-first-change.patch"
614 SRC_URI += "file://0002-second-change.patch"
615 SRC_URI += "file://0003-third-change.patch"
618 the Linux kernel, BitBake detects the change in the recipe and fetches
619 and applies the patches before building the kernel.
621 For a detailed example showing how to patch the kernel using
623 ":ref:`kernel-dev/common:using \`\`devtool\`\` to patch the kernel`"
625 ":ref:`kernel-dev/common:using traditional kernel development to patch the kernel`"
629 --------------------------
632 file used for the eventual Linux kernel configuration by including a
633 ``defconfig`` file and by specifying configuration fragments in the
637 If you have a complete, working Linux kernel ``.config`` file you want
639 appropriate ``${PN}`` directory in your layer's ``recipes-kernel/linux``
641 following lines to the linux-yocto ``.bbappend`` file in your layer::
654 :ref:`ref-tasks-savedefconfig`
656 non-default configuration values. You need to additionally set
658 in the linux-yocto ``.bbappend`` file in your layer::
666 final kernel configuration is a combination of the configurations in
675 console, create a file named ``8250.cfg`` in the ``${PN}`` directory
687 configuration fragment and extend the :term:`FILESPATH` variable in your
694 Linux kernel, BitBake detects the change in the recipe and fetches and
695 applies the new configuration before building the kernel.
697 For a detailed example showing how to configure the kernel, see the
698 ":ref:`kernel-dev/common:configuring the kernel`" section.
700 Using an "In-Tree" ``defconfig`` File
701 --------------------------------------
703 It might be desirable to have kernel configuration fragment support
704 through a ``defconfig`` file that is pulled from the kernel source tree
706 looks for ``defconfig`` files in the layer used for Metadata, which is
707 "out-of-tree", and then configures them using the following::
712 ``defconfig`` files in your layer but would rather allow users to use
713 the default configuration from the kernel tree and still be able to add
717 ``defconfig`` file that is "in-tree".
719 To specify an "in-tree" ``defconfig`` file, use the following statement
726 and provides the path to the "in-tree" ``defconfig`` file to be used for
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.
734 a kernel's ``linux-``\ `machine`\ ``.inc`` file). In other words, if the
735 build system detects a statement that identifies an "out-of-tree"
743 Using ``devtool`` to Patch the Kernel
746 The steps in this procedure show you how you can patch the kernel using
752 steps to get ready for updating the kernel as described in the
753 ":ref:`kernel-dev/common:getting ready to develop using \`\`devtool\`\``"
756 Patching the kernel involves changing or adding configurations to an
757 existing kernel, changing or adding recipes to the kernel that are
762 output at boot time through ``printk`` statements in the kernel's
765 console. The example is a continuation of the setup procedure found in
766 the ":ref:`kernel-dev/common:getting ready to develop using \`\`devtool\`\``" Section.
768 1. *Check Out the Kernel Source Files:* First you must use ``devtool``
769 to checkout the kernel source code in its workspace. Be sure you are
770 in the terminal set up to do work with the extensible SDK.
774 See this step in the
775 ":ref:`kernel-dev/common:getting ready to develop using \`\`devtool\`\``"
780 $ devtool modify linux-yocto
787 .. code-block:: none
791 … /path/to/esdk/layers/poky/meta/recipes-kernel/linux/linux-yocto_4.10.bb.do_unpack
800 1. *Change the working directory*: In the previous step, the output
802 ``poky_sdk/workspace/sources/linux-yocto``). Change to where the
803 kernel source code is before making your edits to the
806 $ cd poky_sdk/workspace/sources/linux-yocto
819 printk("* HELLO YOCTO KERNEL *\n");
828 3. *Build the Updated Kernel Source:* To build the updated kernel
831 $ devtool build linux-yocto
833 4. *Create the Image With the New Kernel:* Use the
834 ``devtool build-image`` command to create a new image that has the
835 new kernel.
839 If the image you originally created resulted in a Wic file, you
841 updated kernel. For an example, see the steps in the
848 $ devtool build-image core-image-minimal
853 1. *Boot the image*: Boot the modified image in the QEMU emulator
862 .. code-block:: none
874 $ cd poky_sdk/workspace/sources/linux-yocto
877 $ git commit -m "calibrate: Add printk example"
881 command in the terminal used to work with the extensible SDK. This
882 example uses the previously established layer named ``meta-mylayer``.
885 $ devtool finish linux-yocto ~/meta-mylayer
890 ":ref:`kernel-dev/common:getting ready to develop using \`\`devtool\`\``"
894 finishes, the patches and the ``.bbappend`` file are located in the
895 ``~/meta-mylayer/recipes-kernel/linux`` directory.
897 8. *Build the Image With Your Modified Kernel:* You can now build an
898 image that includes your kernel patches. Execute the following
900 :term:`Build Directory` in the terminal
904 $ bitbake core-image-minimal
906 Using Traditional Kernel Development to Patch the Kernel
909 The steps in this procedure show you how you can patch the kernel using
910 traditional kernel development (i.e. not using ``devtool`` and the
911 extensible SDK as described in the
912 ":ref:`kernel-dev/common:using \`\`devtool\`\` to patch the kernel`"
918 steps to get ready for updating the kernel as described in the
919 ":ref:`kernel-dev/common:getting ready for traditional kernel development`"
922 Patching the kernel involves changing or adding configurations to an
923 existing kernel, changing or adding recipes to the kernel that are
927 The example in this section creates a simple patch by adding some QEMU
928 emulator console output at boot time through ``printk`` statements in
929 the kernel's ``calibrate.c`` source code file. Applying the patch and
932 found in the
933 ":ref:`kernel-dev/common:getting ready for traditional kernel development`"
937 to create a local copy of the repository for your kernel. Assuming
938 you created the repository as directed in the
939 ":ref:`kernel-dev/common:getting ready for traditional kernel development`"
943 files in the local copy of the kernel Git repository. Change to
944 where the kernel source code is before making your edits to the
947 $ cd ~/linux-yocto-4.12/init
960 printk("* HELLO YOCTO KERNEL *\n");
973 $ git commit -m "calibrate.c - Added some printk statements"
979 3. *Update Your local.conf File to Point to Your Source Files:* In
981 "kernel-modules" and the "qemux86" machine, it must also point to the
982 updated kernel source files. Add
991 …SRC_URI:pn-linux-yocto = "git:///path-to/linux-yocto-4.12;protocol=file;name=machine;branch=standa…
992 …git:///path-to/yocto-kernel-cache;protocol=file;type=kmeta;name=meta;branch=yocto-4.12;destsuffix=…
998 Be sure to replace `path-to`
1004 committed, and the ``local.conf`` file pointing to the kernel files,
1008 $ bitbake core-image-minimal
1010 5. *Boot the image*: Boot the modified image in the QEMU emulator using
1021 .. code-block:: none
1030 correctly, you can generate a ``*.patch`` file in the kernel source
1033 $ cd ~/linux-yocto-4.12/init
1034 $ git format-patch -1
1035 0001-calibrate.c-Added-some-printk-statements.patch
1037 8. *Move the Patch File to Your Layer:* In order for subsequent builds
1038 to pick up patches, you need to move the patch file you created in
1039 the previous step to your layer ``meta-mylayer``. For this example,
1040 the layer created earlier is located in your home directory as
1041 ``meta-mylayer``. When the layer was created using the
1042 ``yocto-create`` script, no additional hierarchy was created to
1046 $ cd ~/meta-mylayer
1047 $ mkdir recipes-kernel
1048 $ mkdir recipes-kernel/linux
1049 $ mkdir recipes-kernel/linux/linux-yocto
1052 hierarchy in your layer, you can move the patch file using the
1055 …$ mv ~/linux-yocto-4.12/init/0001-calibrate.c-Added-some-printk-statements.patch ~/meta-mylayer/re…
1058 ``linux-yocto_4.12.bbappend`` file and insert statements that allow
1060 needs to be in your layer's ``recipes-kernel/linux`` directory and it
1061 must be named ``linux-yocto_4.12.bbappend`` and have the following
1065 SRC_URI:append = "file://0001-calibrate.c-Added-some-printk-statements.patch"
1071 ":ref:`kernel-dev/common:creating the append file`" and
1072 ":ref:`kernel-dev/common:applying patches`" sections. You can also see the
1073 ":ref:`dev-manual/common-tasks:appending other layers metadata with your layer`"
1074 section in the Yocto Project Development Tasks Manual.
1078 To build ``core-image-minimal`` again and see the effects of your patch,
1079 you can essentially eliminate the temporary source files saved in
1084 $ bitbake -c cleanall yocto-linux
1085 $ bitbake core-image-minimal -c cleanall
1086 $ bitbake core-image-minimal
1090 Configuring the Kernel
1093 Configuring the Yocto Project kernel consists of making sure the
1094 ``.config`` file has all the right information in it for the image you
1097 You can also save known configurations in a ``defconfig`` file that the
1098 build system can use for kernel configuration.
1102 ``.config`` file to create the leanest kernel configuration file
1105 For more information on kernel configuration, see the
1106 ":ref:`kernel-dev/common:changing the configuration`" section.
1109 ---------------------
1111 The easiest way to define kernel configurations is to set them through
1113 which to set kernel configurations. For general information on
1116 To use the ``menuconfig`` tool in the Yocto Project development
1119 - Because you launch ``menuconfig`` using BitBake, you must be sure to
1121 :ref:`structure-core-script` script found in
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::
1129 libncurses5-dev
1130 libtinfo-dev
1133 :ref:`ref-tasks-kernel_configme`
1135 Directory's top-level folder is ``poky``::
1138 $ source oe-init-build-env
1139 $ bitbake linux-yocto -c kernel_configme -f
1140 $ bitbake linux-yocto -c menuconfig
1144 kernel configuration parameters. After making your changes, simply exit
1152 ":ref:`kernel-dev/common:changing the configuration`",
1153 ":ref:`kernel-dev/common:using an "in-tree" \`\`defconfig\`\` file`",
1154 and ":ref:`kernel-dev/common:creating a \`\`defconfig\`\` file`"
1158 ``linux-yocto-4.12`` kernel.
1162 The OpenEmbedded build system recognizes this kernel as ``linux-yocto``
1163 through Metadata (e.g. :term:`PREFERRED_VERSION`\ ``_linux-yocto ?= "12.4%"``).
1166 selections to find the configuration settings in which you are
1168 "Symmetric Multi-Processing Support" option. Using the interface, you
1171 Multi-Processing Support" and enter "N" to clear the asterisk. When you
1176 kernel during the build. You can find and examine this file in the Build
1177 Directory in ``tmp/work/``. The actual ``.config`` is located in the
1178 area where the specific kernel is built. For example, if you were
1179 building a Linux Yocto kernel based on the ``linux-yocto-4.12`` kernel
1183 .. code-block:: none
1185 poky/build/tmp/work/qemux86-poky-linux/linux-yocto/4.12.12+gitAUTOINC+eda4d18...
1186 ...967-r0/linux-qemux86-standard-build/.config
1191 characters in the actual filename are omitted in order to make it
1192 more readable. Also, depending on the kernel you are using, the exact
1195 Within the ``.config`` file, you can see the kernel settings. For
1196 example, the following entry shows that symmetric multi-processor
1207 your base to create configuration fragments to permanently save in your
1208 kernel layer.
1216 ------------------------------
1218 A ``defconfig`` file in the context of the Yocto Project is often a
1220 from the kernel tree and moved into recipe space. You can use a
1221 ``defconfig`` file to retain a known set of kernel configurations from
1227 Out-of-the-box, the Yocto Project never ships a ``defconfig`` or ``.config``
1229 to configure the kernel.
1231 To create a ``defconfig``, start with a complete, working Linux kernel
1233 ``${``\ :term:`PN`\ ``}`` directory in
1234 your layer's ``recipes-kernel/linux`` directory, and rename the copied
1236 ``~/meta-mylayer/recipes-kernel/linux/linux-yocto/defconfig``). Then,
1237 add the following lines to the linux-yocto ``.bbappend`` file in your
1252 final kernel configuration is a combination of the configurations in
1258 For more information on configuring the kernel, see the
1259 ":ref:`kernel-dev/common:changing the configuration`" section.
1262 --------------------------------
1264 Configuration fragments are simply kernel options that appear in a file
1267 configurations from a ``defconfig`` file. Thus, the final kernel
1268 configuration is a combination of the configurations in the
1274 appear in the ``.config`` file, which is in the :term:`Build Directory`.
1279 example in the
1280 ":ref:`kernel-dev/common:using \`\`menuconfig\`\``"
1286 multi-processor support within the kernel::
1292 All configuration fragment files must use the ``.cfg`` extension in order
1303 1. *Complete a Build Through Kernel Configuration:* Complete a build at
1304 least through the kernel configuration task as follows::
1306 $ bitbake linux-yocto -c kernel_configme -f
1315 $ bitbake linux-yocto -c menuconfig
1319 ``fragment.cfg`` is placed in the
1323 $ bitbake linux-yocto -c diffconfig
1325 The ``diffconfig`` command creates a file that is a list of Linux kernel
1327 ":ref:`kernel-dev/common:changing the configuration`" section for additional
1333 BSP. See the ":ref:`kernel-dev/advanced:bsp descriptions`"
1337 files in an area pointed to by
1339 ``bblayers.conf`` file, which is located in your layer. The OpenEmbedded
1340 build system picks up the configuration and adds it to the kernel's
1342 options in a file called ``myconfig.cfg``. If you put that file inside a
1343 directory named ``linux-yocto`` that resides in the same directory as
1344 the kernel's append file within your layer and then add the following
1345 statements to the kernel's append file, those configuration options will
1346 be picked up and applied when the kernel is built::
1352 files and name them all in the :term:`SRC_URI` statement as well. For
1355 :term:`SRC_URI` statement like the following in your append file::
1362 ------------------------
1365 :ref:`ref-tasks-kernel_configcheck`
1368 $ bitbake linux-yocto -c kernel_configcheck -f
1371 requested configuration does not appear in the final ``.config`` file or
1372 when you override a policy configuration in a hardware configuration
1375 In order to run this task, you must have an existing ``.config`` file.
1376 See the ":ref:`kernel-dev/common:using \`\`menuconfig\`\``" section for
1381 .. code-block:: none
1394 WARNING: linux-yocto-4.12.12+gitAUTOINC+eda4d18ce4_16de014967-r0 do_kernel_configcheck:
1395 [kernel config]: specified values did not make it into the kernel's final configuration:
1397 ---------- CONFIG_X86_TSC -----------------
1399 …/home/scottrif/poky/build/tmp/work-shared/qemux86/kernel-source/.kernel-meta/configs/standard/bsp/…
1404 ---------- CONFIG_X86_BIGSMP -----------------
1406 …From: /home/scottrif/poky/build/tmp/work-shared/qemux86/kernel-source/.kernel-meta/configs/standar…
1407 …/home/scottrif/poky/build/tmp/work-shared/qemux86/kernel-source/.kernel-meta/configs/standard/defc…
1412 ---------- CONFIG_NR_CPUS -----------------
1414 …From: /home/scottrif/poky/build/tmp/work-shared/qemux86/kernel-source/.kernel-meta/configs/standar…
1415 …/home/scottrif/poky/build/tmp/work-shared/qemux86/kernel-source/.kernel-meta/configs/standard/bsp/…
1416 …/home/scottrif/poky/build/tmp/work-shared/qemux86/kernel-source/.kernel-meta/configs/standard/defc…
1421 ---------- CONFIG_SCHED_SMT -----------------
1423 …From: /home/scottrif/poky/build/tmp/work-shared/qemux86/kernel-source/.kernel-meta/configs/standar…
1424 …/home/scottrif/poky/build/tmp/work-shared/qemux86/kernel-source/.kernel-meta/configs/standard/defc…
1441 information in the logs to adjust your configuration files and then
1443 :ref:`ref-tasks-kernel_configme`
1445 :ref:`ref-tasks-kernel_configcheck`
1449 :ref:`kernel-dev/common:using \`\`menuconfig\`\`` section.
1451 Fine-Tuning the Kernel Configuration File
1452 -----------------------------------------
1455 possible by reading the output of the kernel configuration fragment
1459 As part of the kernel build process, the ``do_kernel_configcheck`` task
1460 runs. This task validates the kernel configuration by checking the final
1464 - Requested options that did not make the final ``.config`` file.
1466 - Configuration items that appear twice in the same configuration
1469 - Configuration items tagged as "required" that were overridden.
1471 - A board overrides a non-board specific option.
1473 - Listed options not valid for the kernel being processed. In other
1478 The :ref:`ref-tasks-kernel_configcheck` task can also optionally report if
1495 $ bitbake linux-yocto -c kernel_configme -f
1496 $ bitbake linux-yocto -c kernel_configcheck -f
1501 - Drop values that are redefined in the fragment but do not change
1504 - Analyze and potentially drop values from the ``.config`` file that
1507 - Analyze and potentially remove non-board specific options.
1509 - Remove repeated and invalid options.
1511 4. *Re-Run Configure and Check Tasks:* After you have worked through the
1512 output of the kernel configuration audit, you can re-run the
1515 them as described in the previous step.
1519 ``.config``, you can build the Linux Yocto kernel.
1526 output of the ``bitbake -e`` command. The output is long and is more
1527 easily managed in a text file, which allows for easy searches::
1529 $ bitbake -e virtual/kernel > some_text_file
1535 Working with a "Dirty" Kernel Version String
1538 If you build a kernel image and the version string has a "+" or a
1539 "-dirty" at the end, it means there are uncommitted modifications in the kernel's
1542 1. *Discover the Uncommitted Changes:* Go to the kernel's locally cloned
1548 2. *Commit the Changes:* You should commit those changes to the kernel
1553 $ git commit -s -a -m "getting rid of -dirty"
1555 3. *Rebuild the Kernel Image:* Once you commit the changes, rebuild the
1556 kernel.
1558 Depending on your particular kernel development workflow, the
1559 commands you use to rebuild the kernel might differ. For information
1560 on building the kernel image when using ``devtool``, see the
1561 ":ref:`kernel-dev/common:using \`\`devtool\`\` to patch the kernel`"
1563 information on building the kernel image when using Bitbake, see the
1564 ":ref:`kernel-dev/common:using traditional kernel development to patch the kernel`"
1570 If you cannot work with one of the Linux kernel versions supported by
1571 existing linux-yocto recipes, you can still make use of the Yocto
1572 Project Linux kernel tooling by working with your own sources. When you
1574 kernel :term:`Metadata` and stabilization
1575 work of the linux-yocto sources. However, you will be able to manage
1576 your own Metadata in the same format as the linux-yocto sources.
1577 Maintaining format compatibility facilitates converging with linux-yocto
1578 on a future, mutually-supported kernel version.
1581 linux-yocto custom recipe that uses ``kernel.org`` sources and
1582 the Yocto Project Linux kernel tools for managing kernel Metadata.
1583 You can find this recipe in the ``poky`` Git repository:
1584 :yocto_git:`meta-skeleton/recipes-kernel/linux/linux-yocto-custom.bb
1585 </poky/tree/meta-skeleton/recipes-kernel/linux/linux-yocto-custom.bb>`.
1589 1. *Create a Copy of the Kernel Recipe:* Copy the
1590 ``linux-yocto-custom.bb`` recipe to your layer and give it a
1592 Linux kernel you are using (e.g. ``linux-yocto-myproject_4.12.bb``,
1593 where "4.12" is the base version of the Linux kernel with which you
1596 2. *Create a Directory for Your Patches:* In the same directory inside
1598 configuration files (e.g. ``linux-yocto-myproject``).
1601 ``defconfig`` file or configuration fragment files in your layer.
1602 When you use the ``linux-yocto-custom.bb`` recipe, you must specify a
1609 resulting ``.config`` file to the ``files`` directory in your layer
1611 :term:`SRC_URI` variable in the
1614 Running the ``make defconfig`` command results in the default
1615 configuration for your architecture as defined by your kernel.
1618 particularly true for non-x86 architectures.
1620 To use non-x86 ``defconfig`` files, you need to be more specific and
1621 find one that matches your board (i.e. for arm, you look in
1625 4. *Edit the Recipe:* Edit the following variables in your recipe as
1628 - :term:`SRC_URI`: The
1636 - :term:`LINUX_VERSION`:
1637 The Linux kernel version you are using (e.g. "4.12").
1639 - :term:`LINUX_VERSION_EXTENSION`:
1640 The Linux kernel ``CONFIG_LOCALVERSION`` that is compiled into the
1641 resulting kernel and visible through the ``uname`` command.
1643 - :term:`SRCREV`: The commit ID
1646 - :term:`PR`: Treat this variable the
1647 same as you would in any other recipe. Increment the variable to
1651 - :term:`PV`: The default :term:`PV`
1660 While lengthy, the extra verbosity in :term:`PV` helps ensure you are
1663 - :term:`COMPATIBLE_MACHINE`:
1665 in the example recipe is set by default to a regular expression
1669 to support the ``qemux86`` and ``qemux86-64`` machines, use the
1672 COMPATIBLE_MACHINE = "qemux86|qemux86-64"
1676 linux-yocto recipe. See the
1677 ":ref:`ref-manual/devtool-reference:modifying an existing recipe`" section
1680 Working with Out-of-Tree Modules
1683 This section describes steps to build out-of-tree modules on your target
1684 and describes how to incorporate out-of-tree modules in the build.
1686 Building Out-of-Tree Modules on the Target
1687 ------------------------------------------
1690 include kernel modules as part of the normal build process, you might
1694 you should consider the benefits of using a proper cross-development
1697 If you want to be able to build out-of-tree modules on the target, there
1699 image. Briefly, the ``kernel-dev`` package is installed by default on
1700 all ``*.sdk`` images and the ``kernel-devsrc`` package is installed on
1702 prior to attempting to build the out-of-tree modules on the target that
1705 Prior to attempting to build the out-of-tree modules, you need to be on
1706 the target as root and you need to change to the ``/usr/src/kernel``
1709 .. code-block:: none
1711 # cd /usr/src/kernel
1714 Because all SDK image recipes include ``dev-pkgs``, the
1715 ``kernel-dev`` packages will be installed as part of the SDK image and
1716 the ``kernel-devsrc`` packages will be installed as part of applicable
1717 SDK images. The SDK uses the scripts when building out-of-tree modules.
1719 should be able to build your out-of-tree modules on the target.
1721 Incorporating Out-of-Tree Modules
1722 ---------------------------------
1725 Linux kernel sources, if you need an external kernel module, the
1726 ``hello-mod.bb`` recipe is available as a template from which you can
1727 create your own out-of-tree Linux kernel module recipe.
1729 This template recipe is located in the ``poky`` Git repository of the
1731 :yocto_git:`meta-skeleton/recipes-kernel/hello-mod/hello-mod_0.1.bb
1732 </poky/tree/meta-skeleton/recipes-kernel/hello-mod/hello-mod_0.1.bb>`.
1735 name (e.g. ``mymodule_1.0.bb``). In the same directory, create a new
1741 - :term:`DESCRIPTION`
1743 - :term:`LICENSE* <LICENSE>`
1745 - :term:`SRC_URI`
1747 - :term:`PV`
1751 looks much like the one provided with the ``hello-mod`` template::
1753 obj-m := hello.o
1758 $(MAKE) -C $(KERNEL_SRC) M=$(SRC)
1761 $(MAKE) -C $(KERNEL_SRC) M=$(SRC) modules_install
1765 :ref:`module <ref-classes-module>` class sets this variable and the
1767 ``${STAGING_KERNEL_DIR}`` with the necessary Linux kernel build
1770 :ref:`ref-tasks-compile` step, or
1775 module in your images. To do this, see the documentation for the
1776 following variables in the Yocto Project Reference Manual and set one of
1779 - :term:`MACHINE_ESSENTIAL_EXTRA_RDEPENDS`
1781 - :term:`MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS`
1783 - :term:`MACHINE_EXTRA_RDEPENDS`
1785 - :term:`MACHINE_EXTRA_RRECOMMENDS`
1790 MACHINE_EXTRA_RRECOMMENDS += "kernel-module-mymodule"
1794 to the string "kernel-module-".
1799 will not fail if this module is not available to include in the image.
1804 A common question when working with a kernel is: "What changes have been
1806 see what has changed, you can use Git to inspect or search the kernel
1807 tree. Using Git is an efficient way to see what has changed in the tree.
1809 What Changed in a Kernel?
1810 -------------------------
1818 In the following examples, unless you provide a commit range, ``kernel.org``
1819 history is blended with Yocto Project kernel changes. You can form
1820 ranges by using branch names from the kernel tree as the upper and
1828 Here is an example that looks at what has changed in the ``emenlow``
1829 branch of the ``linux-yocto-3.19`` kernel. The lower commit range is the
1839 $ git log --oneline origin/standard/base..origin/standard/emenlow
1852 in your ``Documents`` directory::
1854 $ git format-patch -o $HOME/Documents origin/standard/base..origin/standard/emenlow
1857 ---------------------------------------------
1859 Tags in the Yocto Project kernel tree divide changes for significant
1865 You can use the ``git branch --contains`` tag command to
1869 $ git branch --contains systemtap
1871 Adding Recipe-Space Kernel Features
1874 You can add kernel features in the
1875 :ref:`recipe-space <kernel-dev/advanced:recipe-space metadata>`
1877 variable and by specifying the feature's ``.scc`` file path in the
1881 build stops. Kernel features are the last elements processed for
1882 configuring and patching the kernel. Therefore, adding features in this
1887 You add a kernel feature by providing the feature as part of the
1889 ``.scc`` file, which is relative to the root of the kernel Metadata. The
1890 OpenEmbedded build system searches all forms of kernel Metadata on the
1891 :term:`SRC_URI` statement regardless of whether the Metadata is in the
1892 "kernel-cache", system kernel Metadata, or a recipe-space Metadata (i.e.
1893 part of the kernel recipe). See the
1894 ":ref:`kernel-dev/advanced:kernel metadata location`" section for
1899 ``.scc`` file along with all its subdirectories to the kernel feature
1901 single ``.scc`` file in the :term:`SRC_URI` statement to reference multiple
1902 kernel features.
1909 specify in the :term:`SRC_URI` statement.
1913 - You must add the directory of the ``.scc`` file to the
1914 fetcher's search path in the same manner as you would add a
1917 - You can create additional ``.scc`` files beneath the directory
1922 adding has a ``test.scc`` file in the following directory::
1926 +-linux-yocto
1928 +-test.cfg
1929 +-test.scc
1931 In this example, the
1932 ``linux-yocto`` directory has both the feature ``test.scc`` file and
1943 3. *Specify the Feature as a Kernel Feature:* Use the
1944 :term:`KERNEL_FEATURES` statement to specify the feature as a kernel
1950 system processes the kernel feature when it builds the kernel.