summaryrefslogtreecommitdiffstats
path: root/documentation/kernel-dev/kernel-dev-common.rst
diff options
context:
space:
mode:
Diffstat (limited to 'documentation/kernel-dev/kernel-dev-common.rst')
-rw-r--r--documentation/kernel-dev/kernel-dev-common.rst1728
1 files changed, 1728 insertions, 0 deletions
diff --git a/documentation/kernel-dev/kernel-dev-common.rst b/documentation/kernel-dev/kernel-dev-common.rst
new file mode 100644
index 0000000000..bf87edbdc4
--- /dev/null
+++ b/documentation/kernel-dev/kernel-dev-common.rst
@@ -0,0 +1,1728 @@
1************
2Common Tasks
3************
4
5This chapter presents several common tasks you perform when you work
6with the Yocto Project Linux kernel. These tasks include preparing your
7host development system for kernel development, preparing a layer,
8modifying an existing recipe, patching the kernel, configuring the
9kernel, iterative development, working with your own sources, and
10incorporating out-of-tree modules.
11
12.. note::
13
14 The examples presented in this chapter work with the Yocto Project
15 2.4 Release and forward.
16
17Preparing the Build Host to Work on the Kernel
18==============================================
19
20Before you can do any kernel development, you need to be sure your build
21host is set up to use the Yocto Project. For information on how to get
22set up, see the "`Preparing the Build
23Host <&YOCTO_DOCS_DEV_URL;#dev-preparing-the-build-host>`__" section in
24the Yocto Project Development Tasks Manual. Part of preparing the system
25is creating a local Git repository of the `Source
26Directory <&YOCTO_DOCS_REF_URL;#source-directory>`__ (``poky``) on your
27system. Follow the steps in the "`Cloning the ``poky``
28Repository <&YOCTO_DOCS_DEV_URL;#cloning-the-poky-repository>`__"
29section in the Yocto Project Development Tasks Manual to set up your
30Source Directory.
31
32.. note::
33
34 Be sure you check out the appropriate development branch or you
35 create your local branch by checking out a specific tag to get the
36 desired version of Yocto Project. See the "
37 Checking Out by Branch in Poky
38 " and "
39 Checking Out by Tag in Poky
40 " sections in the Yocto Project Development Tasks Manual for more
41 information.
42
43Kernel development is best accomplished using
44```devtool`` <&YOCTO_DOCS_SDK_URL;#using-devtool-in-your-sdk-workflow>`__
45and not through traditional kernel workflow methods. The remainder of
46this section provides information for both scenarios.
47
48Getting Ready to Develop Using ``devtool``
49------------------------------------------
50
51Follow these steps to prepare to update the kernel image using
52``devtool``. Completing this procedure leaves you with a clean kernel
53image and ready to make modifications as described in the "`Using
54``devtool`` to Patch the Kernel <#using-devtool-to-patch-the-kernel>`__"
55section:
56
571. *Initialize the BitBake Environment:* Before building an extensible
58 SDK, you need to initialize the BitBake build environment by sourcing
59 the build environment script (i.e.
60 ```oe-init-build-env`` <&YOCTO_DOCS_REF_URL;#structure-core-script>`__):
61 $ cd ~/poky $ source oe-init-build-env
62
63 .. note::
64
65 The previous commands assume the
66 Source Repositories
67 (i.e.
68 poky
69 ) have been cloned using Git and the local repository is named
70 "poky".
71
722. *Prepare Your ``local.conf`` File:* By default, the
73 ```MACHINE`` <&YOCTO_DOCS_REF_URL;#var-MACHINE>`__ variable is set to
74 "qemux86-64", which is fine if you are building for the QEMU emulator
75 in 64-bit mode. However, if you are not, you need to set the
76 ``MACHINE`` variable appropriately in your ``conf/local.conf`` file
77 found in the `Build
78 Directory <&YOCTO_DOCS_REF_URL;#build-directory>`__ (i.e.
79 ``~/poky/build`` in this example).
80
81 Also, since you are preparing to work on the kernel image, you need
82 to set the
83 ```MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS`` <&YOCTO_DOCS_REF_URL;#var-MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS>`__
84 variable to include kernel modules.
85
86 In this example we wish to build for qemux86 so we must set the
87 ``MACHINE`` variable to "qemux86" and also add the "kernel-modules".
88 As described we do this by appending to ``conf/local.conf``: MACHINE
89 = "qemux86" MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS += "kernel-modules"
90
913. *Create a Layer for Patches:* You need to create a layer to hold
92 patches created for the kernel image. You can use the
93 ``bitbake-layers create-layer`` command as follows: $ cd ~/poky/build
94 $ bitbake-layers create-layer ../../meta-mylayer NOTE: Starting
95 bitbake server... Add your new layer with 'bitbake-layers add-layer
96 ../../meta-mylayer' $
97
98 .. note::
99
100 For background information on working with common and BSP layers,
101 see the "
102 Understanding and Creating Layers
103 " section in the Yocto Project Development Tasks Manual and the "
104 BSP Layers
105 " section in the Yocto Project Board Support (BSP) Developer's
106 Guide, respectively. For information on how to use the
107 bitbake-layers create-layer
108 command to quickly set up a layer, see the "
109 Creating a General Layer Using the
110 bitbake-layers
111 Script
112 " section in the Yocto Project Development Tasks Manual.
113
1144. *Inform the BitBake Build Environment About Your Layer:* As directed
115 when you created your layer, you need to add the layer to the
116 ```BBLAYERS`` <&YOCTO_DOCS_REF_URL;#var-BBLAYERS>`__ variable in the
117 ``bblayers.conf`` file as follows: $ cd ~/poky/build $ bitbake-layers
118 add-layer ../../meta-mylayer NOTE: Starting bitbake server... $
119
1205. *Build the Extensible SDK:* Use BitBake to build the extensible SDK
121 specifically for use with images to be run using QEMU: $ cd
122 ~/poky/build $ bitbake core-image-minimal -c populate_sdk_ext Once
123 the build finishes, you can find the SDK installer file (i.e.
124 ``*.sh`` file) in the following directory:
125 ~/poky/build/tmp/deploy/sdk For this example, the installer file is
126 named
127 ``poky-glibc-x86_64-core-image-minimal-i586-toolchain-ext-DISTRO.sh``
128
1296. *Install the Extensible SDK:* Use the following command to install
130 the SDK. For this example, install the SDK in the default
131 ``~/poky_sdk`` directory: $ cd ~/poky/build/tmp/deploy/sdk $
132 ./poky-glibc-x86_64-core-image-minimal-i586-toolchain-ext-DISTRO.sh
133 Poky (Yocto Project Reference Distro) Extensible SDK installer
134 version DISTRO
135 ============================================================================
136 Enter target directory for SDK (default: ~/poky_sdk): You are about
137 to install the SDK to "/home/scottrif/poky_sdk". Proceed [Y/n]? Y
138 Extracting SDK......................................done Setting it
139 up... Extracting buildtools... Preparing build system... Parsing
140 recipes: 100%
141 \|#################################################################\|
142 Time: 0:00:52 Initializing tasks: 100% \|##############
143 ###############################################\| Time: 0:00:04
144 Checking sstate mirror object availability: 100%
145 \|######################################\| Time: 0:00:00 Parsing
146 recipes: 100%
147 \|#################################################################\|
148 Time: 0:00:33 Initializing tasks: 100%
149 \|##############################################################\|
150 Time: 0:00:00 done SDK has been successfully set up and is ready to
151 be used. Each time you wish to use the SDK in a new shell session,
152 you need to source the environment setup script e.g. $ .
153 /home/scottrif/poky_sdk/environment-setup-i586-poky-linux
154
1557. *Set Up a New Terminal to Work With the Extensible SDK:* You must set
156 up a new terminal to work with the SDK. You cannot use the same
157 BitBake shell used to build the installer.
158
159 After opening a new shell, run the SDK environment setup script as
160 directed by the output from installing the SDK: $ source
161 ~/poky_sdk/environment-setup-i586-poky-linux "SDK environment now set
162 up; additionally you may now run devtool to perform development
163 tasks. Run devtool --help for further details.
164
165 .. note::
166
167 If you get a warning about attempting to use the extensible SDK in
168 an environment set up to run BitBake, you did not use a new shell.
169
1708. *Build the Clean Image:* The final step in preparing to work on the
171 kernel is to build an initial image using ``devtool`` in the new
172 terminal you just set up and initialized for SDK work: $ devtool
173 build-image Parsing recipes: 100%
174 \|##########################################\| Time: 0:00:05 Parsing
175 of 830 .bb files complete (0 cached, 830 parsed). 1299 targets, 47
176 skipped, 0 masked, 0 errors. WARNING: No packages to add, building
177 image core-image-minimal unmodified Loading cache: 100%
178 \|############################################\| Time: 0:00:00 Loaded
179 1299 entries from dependency cache. NOTE: Resolving any missing task
180 queue dependencies Initializing tasks: 100%
181 \|#######################################\| Time: 0:00:07 Checking
182 sstate mirror object availability: 100% \|###############\| Time:
183 0:00:00 NOTE: Executing SetScene Tasks NOTE: Executing RunQueue Tasks
184 NOTE: Tasks Summary: Attempted 2866 tasks of which 2604 didn't need
185 to be rerun and all succeeded. NOTE: Successfully built
186 core-image-minimal. You can find output files in
187 /home/scottrif/poky_sdk/tmp/deploy/images/qemux86 If you were
188 building for actual hardware and not for emulation, you could flash
189 the image to a USB stick on ``/dev/sdd`` and boot your device. For an
190 example that uses a Minnowboard, see the
191 `TipsAndTricks/KernelDevelopmentWithEsdk <https://wiki.yoctoproject.org/wiki/TipsAndTricks/KernelDevelopmentWithEsdk>`__
192 Wiki page.
193
194At this point you have set up to start making modifications to the
195kernel by using the extensible SDK. For a continued example, see the
196"`Using ``devtool`` to Patch the
197Kernel <#using-devtool-to-patch-the-kernel>`__" section.
198
199Getting Ready for Traditional Kernel Development
200------------------------------------------------
201
202Getting ready for traditional kernel development using the Yocto Project
203involves many of the same steps as described in the previous section.
204However, you need to establish a local copy of the kernel source since
205you will be editing these files.
206
207Follow these steps to prepare to update the kernel image using
208traditional kernel development flow with the Yocto Project. Completing
209this procedure leaves you ready to make modifications to the kernel
210source as described in the "`Using Traditional Kernel Development to
211Patch the
212Kernel <#using-traditional-kernel-development-to-patch-the-kernel>`__"
213section:
214
2151. *Initialize the BitBake Environment:* Before you can do anything
216 using BitBake, you need to initialize the BitBake build environment
217 by sourcing the build environment script (i.e.
218 ```oe-init-build-env`` <&YOCTO_DOCS_REF_URL;#structure-core-script>`__).
219 Also, for this example, be sure that the local branch you have
220 checked out for ``poky`` is the Yocto Project DISTRO_NAME branch. If
221 you need to checkout out the DISTRO_NAME branch, see the "`Checking
222 out by Branch in
223 Poky <&YOCTO_DOCS_DEV_URL;#checking-out-by-branch-in-poky>`__"
224 section in the Yocto Project Development Tasks Manual. $ cd ~/poky $
225 git branch master \* DISTRO_NAME $ source oe-init-build-env
226
227 .. note::
228
229 The previous commands assume the
230 Source Repositories
231 (i.e.
232 poky
233 ) have been cloned using Git and the local repository is named
234 "poky".
235
2362. *Prepare Your ``local.conf`` File:* By default, the
237 ```MACHINE`` <&YOCTO_DOCS_REF_URL;#var-MACHINE>`__ variable is set to
238 "qemux86-64", which is fine if you are building for the QEMU emulator
239 in 64-bit mode. However, if you are not, you need to set the
240 ``MACHINE`` variable appropriately in your ``conf/local.conf`` file
241 found in the `Build
242 Directory <&YOCTO_DOCS_REF_URL;#build-directory>`__ (i.e.
243 ``~/poky/build`` in this example).
244
245 Also, since you are preparing to work on the kernel image, you need
246 to set the
247 ```MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS`` <&YOCTO_DOCS_REF_URL;#var-MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS>`__
248 variable to include kernel modules.
249
250 In this example we wish to build for qemux86 so we must set the
251 ``MACHINE`` variable to "qemux86" and also add the "kernel-modules".
252 As described we do this by appending to ``conf/local.conf``: MACHINE
253 = "qemux86" MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS += "kernel-modules"
254
2553. *Create a Layer for Patches:* You need to create a layer to hold
256 patches created for the kernel image. You can use the
257 ``bitbake-layers create-layer`` command as follows: $ cd ~/poky/build
258 $ bitbake-layers create-layer ../../meta-mylayer NOTE: Starting
259 bitbake server... Add your new layer with 'bitbake-layers add-layer
260 ../../meta-mylayer'
261
262 .. note::
263
264 For background information on working with common and BSP layers,
265 see the "
266 Understanding and Creating Layers
267 " section in the Yocto Project Development Tasks Manual and the "
268 BSP Layers
269 " section in the Yocto Project Board Support (BSP) Developer's
270 Guide, respectively. For information on how to use the
271 bitbake-layers create-layer
272 command to quickly set up a layer, see the "
273 Creating a General Layer Using the
274 bitbake-layers
275 Script
276 " section in the Yocto Project Development Tasks Manual.
277
2784. *Inform the BitBake Build Environment About Your Layer:* As directed
279 when you created your layer, you need to add the layer to the
280 ```BBLAYERS`` <&YOCTO_DOCS_REF_URL;#var-BBLAYERS>`__ variable in the
281 ``bblayers.conf`` file as follows: $ cd ~/poky/build $ bitbake-layers
282 add-layer ../../meta-mylayer NOTE: Starting bitbake server ... $
283
2845. *Create a Local Copy of the Kernel Git Repository:* You can find Git
285 repositories of supported Yocto Project kernels organized under
286 "Yocto Linux Kernel" in the Yocto Project Source Repositories at
287 ` <&YOCTO_GIT_URL;>`__.
288
289 For simplicity, it is recommended that you create your copy of the
290 kernel Git repository outside of the `Source
291 Directory <&YOCTO_DOCS_REF_URL;#source-directory>`__, which is
292 usually named ``poky``. Also, be sure you are in the
293 ``standard/base`` branch.
294
295 The following commands show how to create a local copy of the
296 ``linux-yocto-4.12`` kernel and be in the ``standard/base`` branch.
297
298 .. note::
299
300 The
301 linux-yocto-4.12
302 kernel can be used with the Yocto Project 2.4 release and forward.
303 You cannot use the
304 linux-yocto-4.12
305 kernel with releases prior to Yocto Project 2.4:
306
307 $ cd ~ $ git clone git://git.yoctoproject.org/linux-yocto-4.12
308 --branch standard/base Cloning into 'linux-yocto-4.12'... remote:
309 Counting objects: 6097195, done. remote: Compressing objects: 100%
310 (901026/901026), done. remote: Total 6097195 (delta 5152604), reused
311 6096847 (delta 5152256) Receiving objects: 100% (6097195/6097195),
312 1.24 GiB \| 7.81 MiB/s, done. Resolving deltas: 100%
313 (5152604/5152604), done. Checking connectivity... done. Checking out
314 files: 100% (59846/59846), done.
315
3166. *Create a Local Copy of the Kernel Cache Git Repository:* For
317 simplicity, it is recommended that you create your copy of the kernel
318 cache Git repository outside of the `Source
319 Directory <&YOCTO_DOCS_REF_URL;#source-directory>`__, which is
320 usually named ``poky``. Also, for this example, be sure you are in
321 the ``yocto-4.12`` branch.
322
323 The following commands show how to create a local copy of the
324 ``yocto-kernel-cache`` and be in the ``yocto-4.12`` branch: $ cd ~ $
325 git clone git://git.yoctoproject.org/yocto-kernel-cache --branch
326 yocto-4.12 Cloning into 'yocto-kernel-cache'... remote: Counting
327 objects: 22639, done. remote: Compressing objects: 100% (9761/9761),
328 done. remote: Total 22639 (delta 12400), reused 22586 (delta 12347)
329 Receiving objects: 100% (22639/22639), 22.34 MiB \| 6.27 MiB/s, done.
330 Resolving deltas: 100% (12400/12400), done. Checking connectivity...
331 done.
332
333At this point, you are ready to start making modifications to the kernel
334using traditional kernel development steps. For a continued example, see
335the "`Using Traditional Kernel Development to Patch the
336Kernel <#using-traditional-kernel-development-to-patch-the-kernel>`__"
337section.
338
339Creating and Preparing a Layer
340==============================
341
342If you are going to be modifying kernel recipes, it is recommended that
343you create and prepare your own layer in which to do your work. Your
344layer contains its own `BitBake <&YOCTO_DOCS_REF_URL;#bitbake-term>`__
345append files (``.bbappend``) and provides a convenient mechanism to
346create your own recipe files (``.bb``) as well as store and use kernel
347patch files. For background information on working with layers, see the
348"`Understanding and Creating
349Layers <&YOCTO_DOCS_DEV_URL;#understanding-and-creating-layers>`__"
350section in the Yocto Project Development Tasks Manual.
351
352.. note::
353
354 The Yocto Project comes with many tools that simplify tasks you need
355 to perform. One such tool is the
356 bitbake-layers create-layer
357 command, which simplifies creating a new layer. See the "
358 Creating a General Layer Using the
359 bitbake-layers
360 Script
361 " section in the Yocto Project Development Tasks Manual for
362 information on how to use this script to quick set up a new layer.
363
364To better understand the layer you create for kernel development, the
365following section describes how to create a layer without the aid of
366tools. These steps assume creation of a layer named ``mylayer`` in your
367home directory:
368
3691. *Create Structure*: Create the layer's structure: $ cd $HOME $ mkdir
370 meta-mylayer $ mkdir meta-mylayer/conf $ mkdir
371 meta-mylayer/recipes-kernel $ mkdir meta-mylayer/recipes-kernel/linux
372 $ mkdir meta-mylayer/recipes-kernel/linux/linux-yocto The ``conf``
373 directory holds your configuration files, while the
374 ``recipes-kernel`` directory holds your append file and eventual
375 patch files.
376
3772. *Create the Layer Configuration File*: Move to the
378 ``meta-mylayer/conf`` directory and create the ``layer.conf`` file as
379 follows: # We have a conf and classes directory, add to BBPATH BBPATH
380 .= ":${LAYERDIR}" # We have recipes-\* directories, add to BBFILES
381 BBFILES += "${LAYERDIR}/recipes-*/*/*.bb \\
382 ${LAYERDIR}/recipes-*/*/*.bbappend" BBFILE_COLLECTIONS += "mylayer"
383 BBFILE_PATTERN_mylayer = "^${LAYERDIR}/" BBFILE_PRIORITY_mylayer =
384 "5" Notice ``mylayer`` as part of the last three statements.
385
3863. *Create the Kernel Recipe Append File*: Move to the
387 ``meta-mylayer/recipes-kernel/linux`` directory and create the
388 kernel's append file. This example uses the ``linux-yocto-4.12``
389 kernel. Thus, the name of the append file is
390 ``linux-yocto_4.12.bbappend``: FILESEXTRAPATHS_prepend :=
391 "${THISDIR}/${PN}:" SRC_URI_append = " file://patch-file-one"
392 SRC_URI_append = " file://patch-file-two" SRC_URI_append = "
393 file://patch-file-three" The
394 ```FILESEXTRAPATHS`` <&YOCTO_DOCS_REF_URL;#var-FILESEXTRAPATHS>`__
395 and ```SRC_URI`` <&YOCTO_DOCS_REF_URL;#var-SRC_URI>`__ statements
396 enable the OpenEmbedded build system to find patch files. For more
397 information on using append files, see the "`Using .bbappend Files in
398 Your Layer <&YOCTO_DOCS_DEV_URL;#using-bbappend-files>`__" section in
399 the Yocto Project Development Tasks Manual.
400
401Modifying an Existing Recipe
402============================
403
404In many cases, you can customize an existing linux-yocto recipe to meet
405the needs of your project. Each release of the Yocto Project provides a
406few Linux kernel recipes from which you can choose. These are located in
407the `Source Directory <&YOCTO_DOCS_REF_URL;#source-directory>`__ in
408``meta/recipes-kernel/linux``.
409
410Modifying an existing recipe can consist of the following:
411
412- Creating the append file
413
414- Applying patches
415
416- Changing the configuration
417
418Before modifying an existing recipe, be sure that you have created a
419minimal, custom layer from which you can work. See the "`Creating and
420Preparing a Layer <#creating-and-preparing-a-layer>`__" section for
421information.
422
423Creating the Append File
424------------------------
425
426You create this file in your custom layer. You also name it accordingly
427based on the linux-yocto recipe you are using. For example, if you are
428modifying the ``meta/recipes-kernel/linux/linux-yocto_4.12.bb`` recipe,
429the append file will typically be located as follows within your custom
430layer: your-layer/recipes-kernel/linux/linux-yocto_4.12.bbappend The
431append file should initially extend the
432```FILESPATH`` <&YOCTO_DOCS_REF_URL;#var-FILESPATH>`__ search path by
433prepending the directory that contains your files to the
434```FILESEXTRAPATHS`` <&YOCTO_DOCS_REF_URL;#var-FILESEXTRAPATHS>`__
435variable as follows: FILESEXTRAPATHS_prepend := "${THISDIR}/${PN}:" The
436path
437``${``\ ```THISDIR`` <&YOCTO_DOCS_REF_URL;#var-THISDIR>`__\ ``}/${``\ ```PN`` <&YOCTO_DOCS_REF_URL;#var-PN>`__\ ``}``
438expands to "linux-yocto" in the current directory for this example. If
439you add any new files that modify the kernel recipe and you have
440extended ``FILESPATH`` as described above, you must place the files in
441your layer in the following area:
442your-layer/recipes-kernel/linux/linux-yocto/
443
444.. note::
445
446 If you are working on a new machine Board Support Package (BSP), be
447 sure to refer to the
448 Yocto Project Board Support Package (BSP) Developer's Guide
449 .
450
451As an example, consider the following append file used by the BSPs in
452``meta-yocto-bsp``:
453meta-yocto-bsp/recipes-kernel/linux/linux-yocto_4.12.bbappend The
454following listing shows the file. Be aware that the actual commit ID
455strings in this example listing might be different than the actual
456strings in the file from the ``meta-yocto-bsp`` layer upstream.
457KBRANCH_genericx86 = "standard/base" KBRANCH_genericx86-64 =
458"standard/base" KMACHINE_genericx86 ?= "common-pc"
459KMACHINE_genericx86-64 ?= "common-pc-64" KBRANCH_edgerouter =
460"standard/edgerouter" KBRANCH_beaglebone = "standard/beaglebone"
461SRCREV_machine_genericx86 ?= "d09f2ce584d60ecb7890550c22a80c48b83c2e19"
462SRCREV_machine_genericx86-64 ?=
463"d09f2ce584d60ecb7890550c22a80c48b83c2e19" SRCREV_machine_edgerouter ?=
464"b5c8cfda2dfe296410d51e131289fb09c69e1e7d" SRCREV_machine_beaglebone ?=
465"b5c8cfda2dfe296410d51e131289fb09c69e1e7d" COMPATIBLE_MACHINE_genericx86
466= "genericx86" COMPATIBLE_MACHINE_genericx86-64 = "genericx86-64"
467COMPATIBLE_MACHINE_edgerouter = "edgerouter"
468COMPATIBLE_MACHINE_beaglebone = "beaglebone" LINUX_VERSION_genericx86 =
469"4.12.7" LINUX_VERSION_genericx86-64 = "4.12.7" LINUX_VERSION_edgerouter
470= "4.12.10" LINUX_VERSION_beaglebone = "4.12.10" This append file
471contains statements used to support several BSPs that ship with the
472Yocto Project. The file defines machines using the
473```COMPATIBLE_MACHINE`` <&YOCTO_DOCS_REF_URL;#var-COMPATIBLE_MACHINE>`__
474variable and uses the
475```KMACHINE`` <&YOCTO_DOCS_REF_URL;#var-KMACHINE>`__ variable to ensure
476the machine name used by the OpenEmbedded build system maps to the
477machine name used by the Linux Yocto kernel. The file also uses the
478optional ```KBRANCH`` <&YOCTO_DOCS_REF_URL;#var-KBRANCH>`__ variable to
479ensure the build process uses the appropriate kernel branch.
480
481Although this particular example does not use it, the
482```KERNEL_FEATURES`` <&YOCTO_DOCS_REF_URL;#var-KERNEL_FEATURES>`__
483variable could be used to enable features specific to the kernel. The
484append file points to specific commits in the `Source
485Directory <&YOCTO_DOCS_REF_URL;#source-directory>`__ Git repository and
486the ``meta`` Git repository branches to identify the exact kernel needed
487to build the BSP.
488
489One thing missing in this particular BSP, which you will typically need
490when developing a BSP, is the kernel configuration file (``.config``)
491for your BSP. When developing a BSP, you probably have a kernel
492configuration file or a set of kernel configuration files that, when
493taken together, define the kernel configuration for your BSP. You can
494accomplish this definition by putting the configurations in a file or a
495set of files inside a directory located at the same level as your
496kernel's append file and having the same name as the kernel's main
497recipe file. With all these conditions met, simply reference those files
498in the ```SRC_URI`` <&YOCTO_DOCS_REF_URL;#var-SRC_URI>`__ statement in
499the append file.
500
501For example, suppose you had some configuration options in a file called
502``network_configs.cfg``. You can place that file inside a directory
503named ``linux-yocto`` and then add a ``SRC_URI`` statement such as the
504following to the append file. When the OpenEmbedded build system builds
505the kernel, the configuration options are picked up and applied. SRC_URI
506+= "file://network_configs.cfg"
507
508To group related configurations into multiple files, you perform a
509similar procedure. Here is an example that groups separate
510configurations specifically for Ethernet and graphics into their own
511files and adds the configurations by using a ``SRC_URI`` statement like
512the following in your append file: SRC_URI += "file://myconfig.cfg \\
513file://eth.cfg \\ file://gfx.cfg"
514
515Another variable you can use in your kernel recipe append file is the
516```FILESEXTRAPATHS`` <&YOCTO_DOCS_REF_URL;#var-FILESEXTRAPATHS>`__
517variable. When you use this statement, you are extending the locations
518used by the OpenEmbedded system to look for files and patches as the
519recipe is processed.
520
521.. note::
522
523 Other methods exist to accomplish grouping and defining configuration
524 options. For example, if you are working with a local clone of the
525 kernel repository, you could checkout the kernel's ``meta`` branch,
526 make your changes, and then push the changes to the local bare clone
527 of the kernel. The result is that you directly add configuration
528 options to the ``meta`` branch for your BSP. The configuration
529 options will likely end up in that location anyway if the BSP gets
530 added to the Yocto Project.
531
532 In general, however, the Yocto Project maintainers take care of
533 moving the ``SRC_URI``-specified configuration options to the
534 kernel's ``meta`` branch. Not only is it easier for BSP developers to
535 not have to worry about putting those configurations in the branch,
536 but having the maintainers do it allows them to apply 'global'
537 knowledge about the kinds of common configuration options multiple
538 BSPs in the tree are typically using. This allows for promotion of
539 common configurations into common features.
540
541Applying Patches
542----------------
543
544If you have a single patch or a small series of patches that you want to
545apply to the Linux kernel source, you can do so just as you would with
546any other recipe. You first copy the patches to the path added to
547```FILESEXTRAPATHS`` <&YOCTO_DOCS_REF_URL;#var-FILESEXTRAPATHS>`__ in
548your ``.bbappend`` file as described in the previous section, and then
549reference them in ```SRC_URI`` <&YOCTO_DOCS_REF_URL;#var-SRC_URI>`__
550statements.
551
552For example, you can apply a three-patch series by adding the following
553lines to your linux-yocto ``.bbappend`` file in your layer: SRC_URI +=
554"file://0001-first-change.patch" SRC_URI +=
555"file://0002-second-change.patch" SRC_URI +=
556"file://0003-third-change.patch" The next time you run BitBake to build
557the Linux kernel, BitBake detects the change in the recipe and fetches
558and applies the patches before building the kernel.
559
560For a detailed example showing how to patch the kernel using
561``devtool``, see the "`Using ``devtool`` to Patch the
562Kernel <#using-devtool-to-patch-the-kernel>`__" and "`Using Traditional
563Kernel Development to Patch the
564Kernel <#using-traditional-kernel-development-to-patch-the-kernel>`__"
565sections.
566
567Changing the Configuration
568--------------------------
569
570You can make wholesale or incremental changes to the final ``.config``
571file used for the eventual Linux kernel configuration by including a
572``defconfig`` file and by specifying configuration fragments in the
573```SRC_URI`` <&YOCTO_DOCS_REF_URL;#var-SRC_URI>`__ to be applied to that
574file.
575
576If you have a complete, working Linux kernel ``.config`` file you want
577to use for the configuration, as before, copy that file to the
578appropriate ``${PN}`` directory in your layer's ``recipes-kernel/linux``
579directory, and rename the copied file to "defconfig". Then, add the
580following lines to the linux-yocto ``.bbappend`` file in your layer:
581FILESEXTRAPATHS_prepend := "${THISDIR}/${PN}:" SRC_URI +=
582"file://defconfig" The ``SRC_URI`` tells the build system how to search
583for the file, while the
584```FILESEXTRAPATHS`` <&YOCTO_DOCS_REF_URL;#var-FILESEXTRAPATHS>`__
585extends the ```FILESPATH`` <&YOCTO_DOCS_REF_URL;#var-FILESPATH>`__
586variable (search directories) to include the ``${PN}`` directory you
587created to hold the configuration changes.
588
589.. note::
590
591 The build system applies the configurations from the
592 defconfig
593 file before applying any subsequent configuration fragments. The
594 final kernel configuration is a combination of the configurations in
595 the
596 defconfig
597 file and any configuration fragments you provide. You need to realize
598 that if you have any configuration fragments, the build system
599 applies these on top of and after applying the existing
600 defconfig
601 file configurations.
602
603Generally speaking, the preferred approach is to determine the
604incremental change you want to make and add that as a configuration
605fragment. For example, if you want to add support for a basic serial
606console, create a file named ``8250.cfg`` in the ``${PN}`` directory
607with the following content (without indentation): CONFIG_SERIAL_8250=y
608CONFIG_SERIAL_8250_CONSOLE=y CONFIG_SERIAL_8250_PCI=y
609CONFIG_SERIAL_8250_NR_UARTS=4 CONFIG_SERIAL_8250_RUNTIME_UARTS=4
610CONFIG_SERIAL_CORE=y CONFIG_SERIAL_CORE_CONSOLE=y Next, include this
611configuration fragment and extend the ``FILESPATH`` variable in your
612``.bbappend`` file: FILESEXTRAPATHS_prepend := "${THISDIR}/${PN}:"
613SRC_URI += "file://8250.cfg" The next time you run BitBake to build the
614Linux kernel, BitBake detects the change in the recipe and fetches and
615applies the new configuration before building the kernel.
616
617For a detailed example showing how to configure the kernel, see the
618"`Configuring the Kernel <#configuring-the-kernel>`__" section.
619
620Using an "In-Tree"  ``defconfig`` File
621--------------------------------------
622
623It might be desirable to have kernel configuration fragment support
624through a ``defconfig`` file that is pulled from the kernel source tree
625for the configured machine. By default, the OpenEmbedded build system
626looks for ``defconfig`` files in the layer used for Metadata, which is
627"out-of-tree", and then configures them using the following: SRC_URI +=
628"file://defconfig" If you do not want to maintain copies of
629``defconfig`` files in your layer but would rather allow users to use
630the default configuration from the kernel tree and still be able to add
631configuration fragments to the
632```SRC_URI`` <&YOCTO_DOCS_REF_URL;#var-SRC_URI>`__ through, for example,
633append files, you can direct the OpenEmbedded build system to use a
634``defconfig`` file that is "in-tree".
635
636To specify an "in-tree" ``defconfig`` file, use the following statement
637form: KBUILD_DEFCONFIG_KMACHINE ?= defconfig_file Here is an example
638that assigns the ``KBUILD_DEFCONFIG`` variable based on "raspberrypi2"
639and provides the path to the "in-tree" ``defconfig`` file to be used for
640a Raspberry Pi 2, which is based on the Broadcom 2708/2709 chipset:
641KBUILD_DEFCONFIG_raspberrypi2 ?= "bcm2709_defconfig"
642
643Aside from modifying your kernel recipe and providing your own
644``defconfig`` file, you need to be sure no files or statements set
645``SRC_URI`` to use a ``defconfig`` other than your "in-tree" file (e.g.
646a kernel's ``linux-``\ machine\ ``.inc`` file). In other words, if the
647build system detects a statement that identifies an "out-of-tree"
648``defconfig`` file, that statement will override your
649``KBUILD_DEFCONFIG`` variable.
650
651See the
652```KBUILD_DEFCONFIG`` <&YOCTO_DOCS_REF_URL;#var-KBUILD_DEFCONFIG>`__
653variable description for more information.
654
655Using ``devtool`` to Patch the Kernel
656=====================================
657
658The steps in this procedure show you how you can patch the kernel using
659the extensible SDK and ``devtool``.
660
661.. note::
662
663 Before attempting this procedure, be sure you have performed the
664 steps to get ready for updating the kernel as described in the "
665 Getting Ready to Develop Using
666 devtool
667 " section.
668
669Patching the kernel involves changing or adding configurations to an
670existing kernel, changing or adding recipes to the kernel that are
671needed to support specific hardware features, or even altering the
672source code itself.
673
674This example creates a simple patch by adding some QEMU emulator console
675output at boot time through ``printk`` statements in the kernel's
676``calibrate.c`` source code file. Applying the patch and booting the
677modified image causes the added messages to appear on the emulator's
678console. The example is a continuation of the setup procedure found in
679the "`Getting Ready to Develop Using
680``devtool`` <#getting-ready-to-develop-using-devtool>`__" Section.
681
6821. *Check Out the Kernel Source Files:* First you must use ``devtool``
683 to checkout the kernel source code in its workspace. Be sure you are
684 in the terminal set up to do work with the extensible SDK.
685
686 .. note::
687
688 See this
689 step
690 in the "
691 Getting Ready to Develop Using
692 devtool
693 " section for more information.
694
695 Use the following ``devtool`` command to check out the code: $
696 devtool modify linux-yocto
697
698 .. note::
699
700 During the checkout operation, a bug exists that could cause
701 errors such as the following to appear:
702 ::
703
704 ERROR: Taskhash mismatch 2c793438c2d9f8c3681fd5f7bc819efa versus
705 be3a89ce7c47178880ba7bf6293d7404 for
706 /path/to/esdk/layers/poky/meta/recipes-kernel/linux/linux-yocto_4.10.bb.do_unpack
707
708
709 You can safely ignore these messages. The source code is correctly
710 checked out.
711
7122. *Edit the Source Files* Follow these steps to make some simple
713 changes to the source files:
714
715 1. *Change the working directory*: In the previous step, the output
716 noted where you can find the source files (e.g.
717 ``~/poky_sdk/workspace/sources/linux-yocto``). Change to where the
718 kernel source code is before making your edits to the
719 ``calibrate.c`` file: $ cd
720 ~/poky_sdk/workspace/sources/linux-yocto
721
722 2. *Edit the source file*: Edit the ``init/calibrate.c`` file to have
723 the following changes: void calibrate_delay(void) { unsigned long
724 lpj; static bool printed; int this_cpu = smp_processor_id();
725 printk("*************************************\n"); printk("\*
726 \*\n"); printk("\* HELLO YOCTO KERNEL \*\n"); printk("\* \*\n");
727 printk("*************************************\n"); if
728 (per_cpu(cpu_loops_per_jiffy, this_cpu)) { . . .
729
7303. *Build the Updated Kernel Source:* To build the updated kernel
731 source, use ``devtool``: $ devtool build linux-yocto
732
7334. *Create the Image With the New Kernel:* Use the
734 ``devtool build-image`` command to create a new image that has the
735 new kernel.
736
737 .. note::
738
739 If the image you originally created resulted in a Wic file, you
740 can use an alternate method to create the new image with the
741 updated kernel. For an example, see the steps in the
742 TipsAndTricks/KernelDevelopmentWithEsdk
743 Wiki Page.
744
745 $ cd ~ $ devtool build-image core-image-minimal
746
7475. *Test the New Image:* For this example, you can run the new image
748 using QEMU to verify your changes:
749
750 1. *Boot the image*: Boot the modified image in the QEMU emulator
751 using this command: $ runqemu qemux86
752
753 2. *Verify the changes*: Log into the machine using ``root`` with no
754 password and then use the following shell command to scroll
755 through the console's boot output. # dmesg \| less You should see
756 the results of your ``printk`` statements as part of the output
757 when you scroll down the console window.
758
7596. *Stage and commit your changes*: Within your eSDK terminal, change
760 your working directory to where you modified the ``calibrate.c`` file
761 and use these Git commands to stage and commit your changes: $ cd
762 ~/poky_sdk/workspace/sources/linux-yocto $ git status $ git add
763 init/calibrate.c $ git commit -m "calibrate: Add printk example"
764
7657. *Export the Patches and Create an Append File:* To export your
766 commits as patches and create a ``.bbappend`` file, use the following
767 command in the terminal used to work with the extensible SDK. This
768 example uses the previously established layer named ``meta-mylayer``.
769
770 .. note::
771
772 See Step 3 of the "
773 Getting Ready to Develop Using devtool
774 " section for information on setting up this layer.
775
776 $ devtool finish linux-yocto ~/meta-mylayer Once the command
777 finishes, the patches and the ``.bbappend`` file are located in the
778 ``~/meta-mylayer/recipes-kernel/linux`` directory.
779
7808. *Build the Image With Your Modified Kernel:* You can now build an
781 image that includes your kernel patches. Execute the following
782 command from your `Build
783 Directory <&YOCTO_DOCS_REF_URL;#build-directory>`__ in the terminal
784 set up to run BitBake: $ cd ~/poky/build $ bitbake core-image-minimal
785
786Using Traditional Kernel Development to Patch the Kernel
787========================================================
788
789The steps in this procedure show you how you can patch the kernel using
790traditional kernel development (i.e. not using ``devtool`` and the
791extensible SDK as described in the "`Using ``devtool`` to Patch the
792Kernel <#using-devtool-to-patch-the-kernel>`__" section).
793
794.. note::
795
796 Before attempting this procedure, be sure you have performed the
797 steps to get ready for updating the kernel as described in the "
798 Getting Ready for Traditional Kernel Development
799 " section.
800
801Patching the kernel involves changing or adding configurations to an
802existing kernel, changing or adding recipes to the kernel that are
803needed to support specific hardware features, or even altering the
804source code itself.
805
806The example in this section creates a simple patch by adding some QEMU
807emulator console output at boot time through ``printk`` statements in
808the kernel's ``calibrate.c`` source code file. Applying the patch and
809booting the modified image causes the added messages to appear on the
810emulator's console. The example is a continuation of the setup procedure
811found in the "`Getting Ready for Traditional Kernel
812Development <#getting-ready-for-traditional-kernel-development>`__"
813Section.
814
8151. *Edit the Source Files* Prior to this step, you should have used Git
816 to create a local copy of the repository for your kernel. Assuming
817 you created the repository as directed in the "`Getting Ready for
818 Traditional Kernel
819 Development <#getting-ready-for-traditional-kernel-development>`__"
820 section, use the following commands to edit the ``calibrate.c`` file:
821
822 1. *Change the working directory*: You need to locate the source
823 files in the local copy of the kernel Git repository: Change to
824 where the kernel source code is before making your edits to the
825 ``calibrate.c`` file: $ cd ~/linux-yocto-4.12/init
826
827 2. *Edit the source file*: Edit the ``calibrate.c`` file to have the
828 following changes: void calibrate_delay(void) { unsigned long lpj;
829 static bool printed; int this_cpu = smp_processor_id();
830 printk("*************************************\n"); printk("\*
831 \*\n"); printk("\* HELLO YOCTO KERNEL \*\n"); printk("\* \*\n");
832 printk("*************************************\n"); if
833 (per_cpu(cpu_loops_per_jiffy, this_cpu)) { . . .
834
8352. *Stage and Commit Your Changes:* Use standard Git commands to stage
836 and commit the changes you just made: $ git add calibrate.c $ git
837 commit -m "calibrate.c - Added some printk statements" If you do not
838 stage and commit your changes, the OpenEmbedded Build System will not
839 pick up the changes.
840
8413. *Update Your ``local.conf`` File to Point to Your Source Files:* In
842 addition to your ``local.conf`` file specifying to use
843 "kernel-modules" and the "qemux86" machine, it must also point to the
844 updated kernel source files. Add
845 ```SRC_URI`` <&YOCTO_DOCS_REF_URL;#var-SRC_URI>`__ and
846 ```SRCREV`` <&YOCTO_DOCS_REF_URL;#var-SRCREV>`__ statements similar
847 to the following to your ``local.conf``: $ cd ~/poky/build/conf Add
848 the following to the ``local.conf``: SRC_URI_pn-linux-yocto =
849 "git:///path-to/linux-yocto-4.12;protocol=file;name=machine;branch=standard/base;
850 \\
851 git:///path-to/yocto-kernel-cache;protocol=file;type=kmeta;name=meta;branch=yocto-4.12;destsuffix=${KMETA}"
852 SRCREV_meta_qemux86 = "${AUTOREV}" SRCREV_machine_qemux86 =
853 "${AUTOREV}"
854
855 .. note::
856
857 Be sure to replace
858 path-to
859 with the pathname to your local Git repositories. Also, you must
860 be sure to specify the correct branch and machine types. For this
861 example, the branch is
862 standard/base
863 and the machine is "qemux86".
864
8654. *Build the Image:* With the source modified, your changes staged and
866 committed, and the ``local.conf`` file pointing to the kernel files,
867 you can now use BitBake to build the image: $ cd ~/poky/build $
868 bitbake core-image-minimal
869
8705. *Boot the image*: Boot the modified image in the QEMU emulator using
871 this command. When prompted to login to the QEMU console, use "root"
872 with no password: $ cd ~/poky/build $ runqemu qemux86
873
8746. *Look for Your Changes:* As QEMU booted, you might have seen your
875 changes rapidly scroll by. If not, use these commands to see your
876 changes: # dmesg \| less You should see the results of your
877 ``printk`` statements as part of the output when you scroll down the
878 console window.
879
8807. *Generate the Patch File:* Once you are sure that your patch works
881 correctly, you can generate a ``*.patch`` file in the kernel source
882 repository: $ cd ~/linux-yocto-4.12/init $ git format-patch -1
883 0001-calibrate.c-Added-some-printk-statements.patch
884
8858. *Move the Patch File to Your Layer:* In order for subsequent builds
886 to pick up patches, you need to move the patch file you created in
887 the previous step to your layer ``meta-mylayer``. For this example,
888 the layer created earlier is located in your home directory as
889 ``meta-mylayer``. When the layer was created using the
890 ``yocto-create`` script, no additional hierarchy was created to
891 support patches. Before moving the patch file, you need to add
892 additional structure to your layer using the following commands: $ cd
893 ~/meta-mylayer $ mkdir recipes-kernel $ mkdir recipes-kernel/linux $
894 mkdir recipes-kernel/linux/linux-yocto Once you have created this
895 hierarchy in your layer, you can move the patch file using the
896 following command: $ mv
897 ~/linux-yocto-4.12/init/0001-calibrate.c-Added-some-printk-statements.patch
898 ~/meta-mylayer/recipes-kernel/linux/linux-yocto
899
9009. *Create the Append File:* Finally, you need to create the
901 ``linux-yocto_4.12.bbappend`` file and insert statements that allow
902 the OpenEmbedded build system to find the patch. The append file
903 needs to be in your layer's ``recipes-kernel/linux`` directory and it
904 must be named ``linux-yocto_4.12.bbappend`` and have the following
905 contents: FILESEXTRAPATHS_prepend := "${THISDIR}/${PN}:"
906 SRC_URI_append = "
907 file://0001-calibrate.c-Added-some-printk-statements.patch" The
908 ```FILESEXTRAPATHS`` <&YOCTO_DOCS_REF_URL;#var-FILESEXTRAPATHS>`__
909 and ```SRC_URI`` <&YOCTO_DOCS_REF_URL;#var-SRC_URI>`__ statements
910 enable the OpenEmbedded build system to find the patch file.
911
912 For more information on append files and patches, see the "`Creating
913 the Append File <#creating-the-append-file>`__" and "`Applying
914 Patches <#applying-patches>`__" sections. You can also see the
915 "`Using .bbappend Files in Your
916 Layer" <&YOCTO_DOCS_DEV_URL;#using-bbappend-files>`__" section in the
917 Yocto Project Development Tasks Manual.
918
919 .. note::
920
921 To build
922 core-image-minimal
923 again and see the effects of your patch, you can essentially
924 eliminate the temporary source files saved in
925 poky/build/tmp/work/...
926 and residual effects of the build by entering the following
927 sequence of commands:
928 ::
929
930 $ cd ~/poky/build
931 $ bitbake -c cleanall yocto-linux
932 $ bitbake core-image-minimal -c cleanall
933 $ bitbake core-image-minimal
934 $ runqemu qemux86
935
936
937Configuring the Kernel
938======================
939
940Configuring the Yocto Project kernel consists of making sure the
941``.config`` file has all the right information in it for the image you
942are building. You can use the ``menuconfig`` tool and configuration
943fragments to make sure your ``.config`` file is just how you need it.
944You can also save known configurations in a ``defconfig`` file that the
945build system can use for kernel configuration.
946
947This section describes how to use ``menuconfig``, create and use
948configuration fragments, and how to interactively modify your
949``.config`` file to create the leanest kernel configuration file
950possible.
951
952For more information on kernel configuration, see the "`Changing the
953Configuration <#changing-the-configuration>`__" section.
954
955Using  ``menuconfig``
956---------------------
957
958The easiest way to define kernel configurations is to set them through
959the ``menuconfig`` tool. This tool provides an interactive method with
960which to set kernel configurations. For general information on
961``menuconfig``, see ` <http://en.wikipedia.org/wiki/Menuconfig>`__.
962
963To use the ``menuconfig`` tool in the Yocto Project development
964environment, you must do the following:
965
966- Because you launch ``menuconfig`` using BitBake, you must be sure to
967 set up your environment by running the
968 ````` <&YOCTO_DOCS_REF_URL;#structure-core-script>`__ script found in
969 the `Build Directory <&YOCTO_DOCS_REF_URL;#build-directory>`__.
970
971- You must be sure of the state of your build's configuration in the
972 `Source Directory <&YOCTO_DOCS_REF_URL;#source-directory>`__.
973
974- Your build host must have the following two packages installed:
975 libncurses5-dev libtinfo-dev
976
977The following commands initialize the BitBake environment, run the
978```do_kernel_configme`` <&YOCTO_DOCS_REF_URL;#ref-tasks-kernel_configme>`__
979task, and launch ``menuconfig``. These commands assume the Source
980Directory's top-level folder is ``~/poky``: $ cd poky $ source
981oe-init-build-env $ bitbake linux-yocto -c kernel_configme -f $ bitbake
982linux-yocto -c menuconfig Once ``menuconfig`` comes up, its standard
983interface allows you to interactively examine and configure all the
984kernel configuration parameters. After making your changes, simply exit
985the tool and save your changes to create an updated version of the
986``.config`` configuration file.
987
988.. note::
989
990 You can use the entire
991 .config
992 file as the
993 defconfig
994 file. For information on
995 defconfig
996 files, see the "
997 Changing the Configuration
998 ", "
999 Using an In-Tree
1000 defconfig
1001 File
1002 , and "
1003 Creating a
1004 defconfig
1005 File
1006 " sections.
1007
1008Consider an example that configures the "CONFIG_SMP" setting for the
1009``linux-yocto-4.12`` kernel.
1010
1011.. note::
1012
1013 The OpenEmbedded build system recognizes this kernel as
1014 linux-yocto
1015 through Metadata (e.g.
1016 PREFERRED_VERSION
1017 \_linux-yocto ?= "12.4%"
1018 ).
1019
1020Once ``menuconfig`` launches, use the interface to navigate through the
1021selections to find the configuration settings in which you are
1022interested. For this example, you deselect "CONFIG_SMP" by clearing the
1023"Symmetric Multi-Processing Support" option. Using the interface, you
1024can find the option under "Processor Type and Features". To deselect
1025"CONFIG_SMP", use the arrow keys to highlight "Symmetric
1026Multi-Processing Support" and enter "N" to clear the asterisk. When you
1027are finished, exit out and save the change.
1028
1029Saving the selections updates the ``.config`` configuration file. This
1030is the file that the OpenEmbedded build system uses to configure the
1031kernel during the build. You can find and examine this file in the Build
1032Directory in ``tmp/work/``. The actual ``.config`` is located in the
1033area where the specific kernel is built. For example, if you were
1034building a Linux Yocto kernel based on the ``linux-yocto-4.12`` kernel
1035and you were building a QEMU image targeted for ``x86`` architecture,
1036the ``.config`` file would be:
1037poky/build/tmp/work/qemux86-poky-linux/linux-yocto/4.12.12+gitAUTOINC+eda4d18...
1038...967-r0/linux-qemux86-standard-build/.config
1039
1040.. note::
1041
1042 The previous example directory is artificially split and many of the
1043 characters in the actual filename are omitted in order to make it
1044 more readable. Also, depending on the kernel you are using, the exact
1045 pathname might differ.
1046
1047Within the ``.config`` file, you can see the kernel settings. For
1048example, the following entry shows that symmetric multi-processor
1049support is not set: # CONFIG_SMP is not set
1050
1051A good method to isolate changed configurations is to use a combination
1052of the ``menuconfig`` tool and simple shell commands. Before changing
1053configurations with ``menuconfig``, copy the existing ``.config`` and
1054rename it to something else, use ``menuconfig`` to make as many changes
1055as you want and save them, then compare the renamed configuration file
1056against the newly created file. You can use the resulting differences as
1057your base to create configuration fragments to permanently save in your
1058kernel layer.
1059
1060.. note::
1061
1062 Be sure to make a copy of the
1063 .config
1064 file and do not just rename it. The build system needs an existing
1065 .config
1066 file from which to work.
1067
1068Creating a  ``defconfig`` File
1069------------------------------
1070
1071A ``defconfig`` file in the context of the Yocto Project is often a
1072``.config`` file that is copied from a build or a ``defconfig`` taken
1073from the kernel tree and moved into recipe space. You can use a
1074``defconfig`` file to retain a known set of kernel configurations from
1075which the OpenEmbedded build system can draw to create the final
1076``.config`` file.
1077
1078.. note::
1079
1080 Out-of-the-box, the Yocto Project never ships a
1081 defconfig
1082 or
1083 .config
1084 file. The OpenEmbedded build system creates the final
1085 .config
1086 file used to configure the kernel.
1087
1088To create a ``defconfig``, start with a complete, working Linux kernel
1089``.config`` file. Copy that file to the appropriate
1090``${``\ ```PN`` <&YOCTO_DOCS_REF_URL;#var-PN>`__\ ``}`` directory in
1091your layer's ``recipes-kernel/linux`` directory, and rename the copied
1092file to "defconfig" (e.g.
1093``~/meta-mylayer/recipes-kernel/linux/linux-yocto/defconfig``). Then,
1094add the following lines to the linux-yocto ``.bbappend`` file in your
1095layer: FILESEXTRAPATHS_prepend := "${THISDIR}/${PN}:" SRC_URI +=
1096"file://defconfig" The
1097```SRC_URI`` <&YOCTO_DOCS_REF_URL;#var-SRC_URI>`__ tells the build
1098system how to search for the file, while the
1099```FILESEXTRAPATHS`` <&YOCTO_DOCS_REF_URL;#var-FILESEXTRAPATHS>`__
1100extends the ```FILESPATH`` <&YOCTO_DOCS_REF_URL;#var-FILESPATH>`__
1101variable (search directories) to include the ``${PN}`` directory you
1102created to hold the configuration changes.
1103
1104.. note::
1105
1106 The build system applies the configurations from the
1107 defconfig
1108 file before applying any subsequent configuration fragments. The
1109 final kernel configuration is a combination of the configurations in
1110 the
1111 defconfig
1112 file and any configuration fragments you provide. You need to realize
1113 that if you have any configuration fragments, the build system
1114 applies these on top of and after applying the existing defconfig
1115 file configurations.
1116
1117For more information on configuring the kernel, see the "`Changing the
1118Configuration <#changing-the-configuration>`__" section.
1119
1120.. _creating-config-fragments:
1121
1122Creating Configuration Fragments
1123--------------------------------
1124
1125Configuration fragments are simply kernel options that appear in a file
1126placed where the OpenEmbedded build system can find and apply them. The
1127build system applies configuration fragments after applying
1128configurations from a ``defconfig`` file. Thus, the final kernel
1129configuration is a combination of the configurations in the
1130``defconfig`` file and then any configuration fragments you provide. The
1131build system applies fragments on top of and after applying the existing
1132defconfig file configurations.
1133
1134Syntactically, the configuration statement is identical to what would
1135appear in the ``.config`` file, which is in the `Build
1136Directory <&YOCTO_DOCS_REF_URL;#build-directory>`__.
1137
1138.. note::
1139
1140 For more information about where the
1141 .config
1142 file is located, see the example in the "
1143 Using
1144 menuconfig
1145 " section.
1146
1147It is simple to create a configuration fragment. One method is to use
1148shell commands. For example, issuing the following from the shell
1149creates a configuration fragment file named ``my_smp.cfg`` that enables
1150multi-processor support within the kernel: $ echo "CONFIG_SMP=y" >>
1151my_smp.cfg
1152
1153.. note::
1154
1155 All configuration fragment files must use the
1156 .cfg
1157 extension in order for the OpenEmbedded build system to recognize
1158 them as a configuration fragment.
1159
1160Another method is to create a configuration fragment using the
1161differences between two configuration files: one previously created and
1162saved, and one freshly created using the ``menuconfig`` tool.
1163
1164To create a configuration fragment using this method, follow these
1165steps:
1166
11671. *Complete a Build Through Kernel Configuration:* Complete a build at
1168 least through the kernel configuration task as follows: $ bitbake
1169 linux-yocto -c kernel_configme -f This step ensures that you create a
1170 ``.config`` file from a known state. Because situations exist where
1171 your build state might become unknown, it is best to run this task
1172 prior to starting ``menuconfig``.
1173
11742. *Launch ``menuconfig``:* Run the ``menuconfig`` command: $ bitbake
1175 linux-yocto -c menuconfig
1176
11773. *Create the Configuration Fragment:* Run the ``diffconfig`` command
1178 to prepare a configuration fragment. The resulting file
1179 ``fragment.cfg`` is placed in the
1180 ``${``\ ```WORKDIR`` <&YOCTO_DOCS_REF_URL;#var-WORKDIR>`__\ ``}``
1181 directory: $ bitbake linux-yocto -c diffconfig
1182
1183The ``diffconfig`` command creates a file that is a list of Linux kernel
1184``CONFIG_`` assignments. See the "`Changing the
1185Configuration <#changing-the-configuration>`__" section for additional
1186information on how to use the output as a configuration fragment.
1187
1188.. note::
1189
1190 You can also use this method to create configuration fragments for a
1191 BSP. See the "
1192 BSP Descriptions
1193 " section for more information.
1194
1195Where do you put your configuration fragment files? You can place these
1196files in an area pointed to by
1197```SRC_URI`` <&YOCTO_DOCS_REF_URL;#var-SRC_URI>`__ as directed by your
1198``bblayers.conf`` file, which is located in your layer. The OpenEmbedded
1199build system picks up the configuration and adds it to the kernel's
1200configuration. For example, suppose you had a set of configuration
1201options in a file called ``myconfig.cfg``. If you put that file inside a
1202directory named ``linux-yocto`` that resides in the same directory as
1203the kernel's append file within your layer and then add the following
1204statements to the kernel's append file, those configuration options will
1205be picked up and applied when the kernel is built:
1206FILESEXTRAPATHS_prepend := "${THISDIR}/${PN}:" SRC_URI +=
1207"file://myconfig.cfg"
1208
1209As mentioned earlier, you can group related configurations into multiple
1210files and name them all in the ``SRC_URI`` statement as well. For
1211example, you could group separate configurations specifically for
1212Ethernet and graphics into their own files and add those by using a
1213``SRC_URI`` statement like the following in your append file: SRC_URI +=
1214"file://myconfig.cfg \\ file://eth.cfg \\ file://gfx.cfg"
1215
1216Validating Configuration
1217------------------------
1218
1219You can use the
1220```do_kernel_configcheck`` <&YOCTO_DOCS_REF_URL;#ref-tasks-kernel_configcheck>`__
1221task to provide configuration validation: $ bitbake linux-yocto -c
1222kernel_configcheck -f Running this task produces warnings for when a
1223requested configuration does not appear in the final ``.config`` file or
1224when you override a policy configuration in a hardware configuration
1225fragment.
1226
1227In order to run this task, you must have an existing ``.config`` file.
1228See the "`Using ``menuconfig`` <#using-menuconfig>`__" section for
1229information on how to create a configuration file.
1230
1231Following is sample output from the ``do_kernel_configcheck`` task:
1232Loading cache: 100%
1233\|########################################################\| Time:
12340:00:00 Loaded 1275 entries from dependency cache. NOTE: Resolving any
1235missing task queue dependencies Build Configuration: . . . NOTE:
1236Executing SetScene Tasks NOTE: Executing RunQueue Tasks WARNING:
1237linux-yocto-4.12.12+gitAUTOINC+eda4d18ce4_16de014967-r0
1238do_kernel_configcheck: [kernel config]: specified values did not make it
1239into the kernel's final configuration: ---------- CONFIG_X86_TSC
1240----------------- Config: CONFIG_X86_TSC From:
1241/home/scottrif/poky/build/tmp/work-shared/qemux86/kernel-source/.kernel-meta/configs/standard/bsp/common-pc/common-pc-cpu.cfg
1242Requested value: CONFIG_X86_TSC=y Actual value: ----------
1243CONFIG_X86_BIGSMP ----------------- Config: CONFIG_X86_BIGSMP From:
1244/home/scottrif/poky/build/tmp/work-shared/qemux86/kernel-source/.kernel-meta/configs/standard/cfg/smp.cfg
1245/home/scottrif/poky/build/tmp/work-shared/qemux86/kernel-source/.kernel-meta/configs/standard/defconfig
1246Requested value: # CONFIG_X86_BIGSMP is not set Actual value: ----------
1247CONFIG_NR_CPUS ----------------- Config: CONFIG_NR_CPUS From:
1248/home/scottrif/poky/build/tmp/work-shared/qemux86/kernel-source/.kernel-meta/configs/standard/cfg/smp.cfg
1249/home/scottrif/poky/build/tmp/work-shared/qemux86/kernel-source/.kernel-meta/configs/standard/bsp/common-pc/common-pc.cfg
1250/home/scottrif/poky/build/tmp/work-shared/qemux86/kernel-source/.kernel-meta/configs/standard/defconfig
1251Requested value: CONFIG_NR_CPUS=8 Actual value: CONFIG_NR_CPUS=1
1252---------- CONFIG_SCHED_SMT ----------------- Config: CONFIG_SCHED_SMT
1253From:
1254/home/scottrif/poky/build/tmp/work-shared/qemux86/kernel-source/.kernel-meta/configs/standard/cfg/smp.cfg
1255/home/scottrif/poky/build/tmp/work-shared/qemux86/kernel-source/.kernel-meta/configs/standard/defconfig
1256Requested value: CONFIG_SCHED_SMT=y Actual value: NOTE: Tasks Summary:
1257Attempted 288 tasks of which 285 didn't need to be rerun and all
1258succeeded. Summary: There were 3 WARNING messages shown.
1259
1260.. note::
1261
1262 The previous output example has artificial line breaks to make it
1263 more readable.
1264
1265The output describes the various problems that you can encounter along
1266with where to find the offending configuration items. You can use the
1267information in the logs to adjust your configuration files and then
1268repeat the
1269```do_kernel_configme`` <&YOCTO_DOCS_REF_URL;#ref-tasks-kernel_configme>`__
1270and
1271```do_kernel_configcheck`` <&YOCTO_DOCS_REF_URL;#ref-tasks-kernel_configcheck>`__
1272tasks until they produce no warnings.
1273
1274For more information on how to use the ``menuconfig`` tool, see the
1275"`Using ``menuconfig`` <#using-menuconfig>`__" section.
1276
1277Fine-Tuning the Kernel Configuration File
1278-----------------------------------------
1279
1280You can make sure the ``.config`` file is as lean or efficient as
1281possible by reading the output of the kernel configuration fragment
1282audit, noting any issues, making changes to correct the issues, and then
1283repeating.
1284
1285As part of the kernel build process, the ``do_kernel_configcheck`` task
1286runs. This task validates the kernel configuration by checking the final
1287``.config`` file against the input files. During the check, the task
1288produces warning messages for the following issues:
1289
1290- Requested options that did not make the final ``.config`` file.
1291
1292- Configuration items that appear twice in the same configuration
1293 fragment.
1294
1295- Configuration items tagged as "required" that were overridden.
1296
1297- A board overrides a non-board specific option.
1298
1299- Listed options not valid for the kernel being processed. In other
1300 words, the option does not appear anywhere.
1301
1302.. note::
1303
1304 The
1305 do_kernel_configcheck
1306 task can also optionally report if an option is overridden during
1307 processing.
1308
1309For each output warning, a message points to the file that contains a
1310list of the options and a pointer to the configuration fragment that
1311defines them. Collectively, the files are the key to streamlining the
1312configuration.
1313
1314To streamline the configuration, do the following:
1315
13161. *Use a Working Configuration:* Start with a full configuration that
1317 you know works. Be sure the configuration builds and boots
1318 successfully. Use this configuration file as your baseline.
1319
13202. *Run Configure and Check Tasks:* Separately run the
1321 ``do_kernel_configme`` and ``do_kernel_configcheck`` tasks: $ bitbake
1322 linux-yocto -c kernel_configme -f $ bitbake linux-yocto -c
1323 kernel_configcheck -f
1324
13253. *Process the Results:* Take the resulting list of files from the
1326 ``do_kernel_configcheck`` task warnings and do the following:
1327
1328 - Drop values that are redefined in the fragment but do not change
1329 the final ``.config`` file.
1330
1331 - Analyze and potentially drop values from the ``.config`` file that
1332 override required configurations.
1333
1334 - Analyze and potentially remove non-board specific options.
1335
1336 - Remove repeated and invalid options.
1337
13384. *Re-Run Configure and Check Tasks:* After you have worked through the
1339 output of the kernel configuration audit, you can re-run the
1340 ``do_kernel_configme`` and ``do_kernel_configcheck`` tasks to see the
1341 results of your changes. If you have more issues, you can deal with
1342 them as described in the previous step.
1343
1344Iteratively working through steps two through four eventually yields a
1345minimal, streamlined configuration file. Once you have the best
1346``.config``, you can build the Linux Yocto kernel.
1347
1348Expanding Variables
1349===================
1350
1351Sometimes it is helpful to determine what a variable expands to during a
1352build. You can do examine the values of variables by examining the
1353output of the ``bitbake -e`` command. The output is long and is more
1354easily managed in a text file, which allows for easy searches: $ bitbake
1355-e virtual/kernel > some_text_file Within the text file, you can see
1356exactly how each variable is expanded and used by the OpenEmbedded build
1357system.
1358
1359Working with a "Dirty" Kernel Version String
1360============================================
1361
1362If you build a kernel image and the version string has a "+" or a
1363"-dirty" at the end, uncommitted modifications exist in the kernel's
1364source directory. Follow these steps to clean up the version string:
1365
13661. *Discover the Uncommitted Changes:* Go to the kernel's locally cloned
1367 Git repository (source directory) and use the following Git command
1368 to list the files that have been changed, added, or removed: $ git
1369 status
1370
13712. *Commit the Changes:* You should commit those changes to the kernel
1372 source tree regardless of whether or not you will save, export, or
1373 use the changes: $ git add $ git commit -s -a -m "getting rid of
1374 -dirty"
1375
13763. *Rebuild the Kernel Image:* Once you commit the changes, rebuild the
1377 kernel.
1378
1379 Depending on your particular kernel development workflow, the
1380 commands you use to rebuild the kernel might differ. For information
1381 on building the kernel image when using ``devtool``, see the "`Using
1382 ``devtool`` to Patch the
1383 Kernel <#using-devtool-to-patch-the-kernel>`__" section. For
1384 information on building the kernel image when using Bitbake, see the
1385 "`Using Traditional Kernel Development to Patch the
1386 Kernel <#using-traditional-kernel-development-to-patch-the-kernel>`__"
1387 section.
1388
1389Working With Your Own Sources
1390=============================
1391
1392If you cannot work with one of the Linux kernel versions supported by
1393existing linux-yocto recipes, you can still make use of the Yocto
1394Project Linux kernel tooling by working with your own sources. When you
1395use your own sources, you will not be able to leverage the existing
1396kernel `Metadata <&YOCTO_DOCS_REF_URL;#metadata>`__ and stabilization
1397work of the linux-yocto sources. However, you will be able to manage
1398your own Metadata in the same format as the linux-yocto sources.
1399Maintaining format compatibility facilitates converging with linux-yocto
1400on a future, mutually-supported kernel version.
1401
1402To help you use your own sources, the Yocto Project provides a
1403linux-yocto custom recipe (``linux-yocto-custom.bb``) that uses
1404``kernel.org`` sources and the Yocto Project Linux kernel tools for
1405managing kernel Metadata. You can find this recipe in the ``poky`` Git
1406repository of the Yocto Project `Source Repository <&YOCTO_GIT_URL;>`__
1407at: poky/meta-skeleton/recipes-kernel/linux/linux-yocto-custom.bb
1408
1409Here are some basic steps you can use to work with your own sources:
1410
14111. *Create a Copy of the Kernel Recipe:* Copy the
1412 ``linux-yocto-custom.bb`` recipe to your layer and give it a
1413 meaningful name. The name should include the version of the Yocto
1414 Linux kernel you are using (e.g. ``linux-yocto-myproject_4.12.bb``,
1415 where "4.12" is the base version of the Linux kernel with which you
1416 would be working).
1417
14182. *Create a Directory for Your Patches:* In the same directory inside
1419 your layer, create a matching directory to store your patches and
1420 configuration files (e.g. ``linux-yocto-myproject``).
1421
14223. *Ensure You Have Configurations:* Make sure you have either a
1423 ``defconfig`` file or configuration fragment files in your layer.
1424 When you use the ``linux-yocto-custom.bb`` recipe, you must specify a
1425 configuration. If you do not have a ``defconfig`` file, you can run
1426 the following: $ make defconfig After running the command, copy the
1427 resulting ``.config`` file to the ``files`` directory in your layer
1428 as "defconfig" and then add it to the
1429 ```SRC_URI`` <&YOCTO_DOCS_REF_URL;#var-SRC_URI>`__ variable in the
1430 recipe.
1431
1432 Running the ``make defconfig`` command results in the default
1433 configuration for your architecture as defined by your kernel.
1434 However, no guarantee exists that this configuration is valid for
1435 your use case, or that your board will even boot. This is
1436 particularly true for non-x86 architectures.
1437
1438 To use non-x86 ``defconfig`` files, you need to be more specific and
1439 find one that matches your board (i.e. for arm, you look in
1440 ``arch/arm/configs`` and use the one that is the best starting point
1441 for your board).
1442
14434. *Edit the Recipe:* Edit the following variables in your recipe as
1444 appropriate for your project:
1445
1446 - ```SRC_URI`` <&YOCTO_DOCS_REF_URL;#var-SRC_URI>`__: The
1447 ``SRC_URI`` should specify a Git repository that uses one of the
1448 supported Git fetcher protocols (i.e. ``file``, ``git``, ``http``,
1449 and so forth). The ``SRC_URI`` variable should also specify either
1450 a ``defconfig`` file or some configuration fragment files. The
1451 skeleton recipe provides an example ``SRC_URI`` as a syntax
1452 reference.
1453
1454 - ```LINUX_VERSION`` <&YOCTO_DOCS_REF_URL;#var-LINUX_VERSION>`__:
1455 The Linux kernel version you are using (e.g. "4.12").
1456
1457 - ```LINUX_VERSION_EXTENSION`` <&YOCTO_DOCS_REF_URL;#var-LINUX_VERSION_EXTENSION>`__:
1458 The Linux kernel ``CONFIG_LOCALVERSION`` that is compiled into the
1459 resulting kernel and visible through the ``uname`` command.
1460
1461 - ```SRCREV`` <&YOCTO_DOCS_REF_URL;#var-SRCREV>`__: The commit ID
1462 from which you want to build.
1463
1464 - ```PR`` <&YOCTO_DOCS_REF_URL;#var-PR>`__: Treat this variable the
1465 same as you would in any other recipe. Increment the variable to
1466 indicate to the OpenEmbedded build system that the recipe has
1467 changed.
1468
1469 - ```PV`` <&YOCTO_DOCS_REF_URL;#var-PV>`__: The default ``PV``
1470 assignment is typically adequate. It combines the
1471 ``LINUX_VERSION`` with the Source Control Manager (SCM) revision
1472 as derived from the ```SRCPV`` <&YOCTO_DOCS_REF_URL;#var-SRCPV>`__
1473 variable. The combined results are a string with the following
1474 form:
1475 3.19.11+git1+68a635bf8dfb64b02263c1ac80c948647cc76d5f_1+218bd8d2022b9852c60d32f0d770931e3cf343e2
1476 While lengthy, the extra verbosity in ``PV`` helps ensure you are
1477 using the exact sources from which you intend to build.
1478
1479 - ```COMPATIBLE_MACHINE`` <&YOCTO_DOCS_REF_URL;#var-COMPATIBLE_MACHINE>`__:
1480 A list of the machines supported by your new recipe. This variable
1481 in the example recipe is set by default to a regular expression
1482 that matches only the empty string, "(^$)". This default setting
1483 triggers an explicit build failure. You must change it to match a
1484 list of the machines that your new recipe supports. For example,
1485 to support the ``qemux86`` and ``qemux86-64`` machines, use the
1486 following form: COMPATIBLE_MACHINE = "qemux86|qemux86-64"
1487
14885. *Customize Your Recipe as Needed:* Provide further customizations to
1489 your recipe as needed just as you would customize an existing
1490 linux-yocto recipe. See the "`Modifying an Existing
1491 Recipe <#modifying-an-existing-recipe>`__" section for information.
1492
1493Working with Out-of-Tree Modules
1494================================
1495
1496This section describes steps to build out-of-tree modules on your target
1497and describes how to incorporate out-of-tree modules in the build.
1498
1499Building Out-of-Tree Modules on the Target
1500------------------------------------------
1501
1502While the traditional Yocto Project development model would be to
1503include kernel modules as part of the normal build process, you might
1504find it useful to build modules on the target. This could be the case if
1505your target system is capable and powerful enough to handle the
1506necessary compilation. Before deciding to build on your target, however,
1507you should consider the benefits of using a proper cross-development
1508environment from your build host.
1509
1510If you want to be able to build out-of-tree modules on the target, there
1511are some steps you need to take on the target that is running your SDK
1512image. Briefly, the ``kernel-dev`` package is installed by default on
1513all ``*.sdk`` images and the ``kernel-devsrc`` package is installed on
1514many of the ``*.sdk`` images. However, you need to create some scripts
1515prior to attempting to build the out-of-tree modules on the target that
1516is running that image.
1517
1518Prior to attempting to build the out-of-tree modules, you need to be on
1519the target as root and you need to change to the ``/usr/src/kernel``
1520directory. Next, ``make`` the scripts: # cd /usr/src/kernel # make
1521scripts Because all SDK image recipes include ``dev-pkgs``, the
1522``kernel-dev`` packages will be installed as part of the SDK image and
1523the ``kernel-devsrc`` packages will be installed as part of applicable
1524SDK images. The SDK uses the scripts when building out-of-tree modules.
1525Once you have switched to that directory and created the scripts, you
1526should be able to build your out-of-tree modules on the target.
1527
1528Incorporating Out-of-Tree Modules
1529---------------------------------
1530
1531While it is always preferable to work with sources integrated into the
1532Linux kernel sources, if you need an external kernel module, the
1533``hello-mod.bb`` recipe is available as a template from which you can
1534create your own out-of-tree Linux kernel module recipe.
1535
1536This template recipe is located in the ``poky`` Git repository of the
1537Yocto Project `Source Repository <&YOCTO_GIT_URL;>`__ at:
1538poky/meta-skeleton/recipes-kernel/hello-mod/hello-mod_0.1.bb
1539
1540To get started, copy this recipe to your layer and give it a meaningful
1541name (e.g. ``mymodule_1.0.bb``). In the same directory, create a new
1542directory named ``files`` where you can store any source files, patches,
1543or other files necessary for building the module that do not come with
1544the sources. Finally, update the recipe as needed for the module.
1545Typically, you will need to set the following variables:
1546
1547- ```DESCRIPTION`` <&YOCTO_DOCS_REF_URL;#var-DESCRIPTION>`__
1548
1549- ```LICENSE*`` <&YOCTO_DOCS_REF_URL;#var-LICENSE>`__
1550
1551- ```SRC_URI`` <&YOCTO_DOCS_REF_URL;#var-SRC_URI>`__
1552
1553- ```PV`` <&YOCTO_DOCS_REF_URL;#var-PV>`__
1554
1555Depending on the build system used by the module sources, you might need
1556to make some adjustments. For example, a typical module ``Makefile``
1557looks much like the one provided with the ``hello-mod`` template: obj-m
1558:= hello.o SRC := $(shell pwd) all: $(MAKE) -C $(KERNEL_SRC) M=$(SRC)
1559modules_install: $(MAKE) -C $(KERNEL_SRC) M=$(SRC) modules_install ...
1560
1561The important point to note here is the
1562```KERNEL_SRC`` <&YOCTO_DOCS_REF_URL;#var-KERNEL_SRC>`__ variable. The
1563```module`` <&YOCTO_DOCS_REF_URL;#ref-classes-module>`__ class sets this
1564variable and the
1565```KERNEL_PATH`` <&YOCTO_DOCS_REF_URL;#var-KERNEL_PATH>`__ variable to
1566``${STAGING_KERNEL_DIR}`` with the necessary Linux kernel build
1567information to build modules. If your module ``Makefile`` uses a
1568different variable, you might want to override the
1569```do_compile`` <&YOCTO_DOCS_REF_URL;#ref-tasks-compile>`__ step, or
1570create a patch to the ``Makefile`` to work with the more typical
1571``KERNEL_SRC`` or ``KERNEL_PATH`` variables.
1572
1573After you have prepared your recipe, you will likely want to include the
1574module in your images. To do this, see the documentation for the
1575following variables in the Yocto Project Reference Manual and set one of
1576them appropriately for your machine configuration file:
1577
1578- ```MACHINE_ESSENTIAL_EXTRA_RDEPENDS`` <&YOCTO_DOCS_REF_URL;#var-MACHINE_ESSENTIAL_EXTRA_RDEPENDS>`__
1579
1580- ```MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS`` <&YOCTO_DOCS_REF_URL;#var-MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS>`__
1581
1582- ```MACHINE_EXTRA_RDEPENDS`` <&YOCTO_DOCS_REF_URL;#var-MACHINE_EXTRA_RDEPENDS>`__
1583
1584- ```MACHINE_EXTRA_RRECOMMENDS`` <&YOCTO_DOCS_REF_URL;#var-MACHINE_EXTRA_RRECOMMENDS>`__
1585
1586Modules are often not required for boot and can be excluded from certain
1587build configurations. The following allows for the most flexibility:
1588MACHINE_EXTRA_RRECOMMENDS += "kernel-module-mymodule" The value is
1589derived by appending the module filename without the ``.ko`` extension
1590to the string "kernel-module-".
1591
1592Because the variable is
1593```RRECOMMENDS`` <&YOCTO_DOCS_REF_URL;#var-RRECOMMENDS>`__ and not a
1594```RDEPENDS`` <&YOCTO_DOCS_REF_URL;#var-RDEPENDS>`__ variable, the build
1595will not fail if this module is not available to include in the image.
1596
1597Inspecting Changes and Commits
1598==============================
1599
1600A common question when working with a kernel is: "What changes have been
1601applied to this tree?" Rather than using "grep" across directories to
1602see what has changed, you can use Git to inspect or search the kernel
1603tree. Using Git is an efficient way to see what has changed in the tree.
1604
1605What Changed in a Kernel?
1606-------------------------
1607
1608Following are a few examples that show how to use Git commands to
1609examine changes. These examples are by no means the only way to see
1610changes.
1611
1612.. note::
1613
1614 In the following examples, unless you provide a commit range,
1615 kernel.org
1616 history is blended with Yocto Project kernel changes. You can form
1617 ranges by using branch names from the kernel tree as the upper and
1618 lower commit markers with the Git commands. You can see the branch
1619 names through the web interface to the Yocto Project source
1620 repositories at
1621 .
1622
1623To see a full range of the changes, use the ``git whatchanged`` command
1624and specify a commit range for the branch (commit\ ``..``\ commit).
1625
1626Here is an example that looks at what has changed in the ``emenlow``
1627branch of the ``linux-yocto-3.19`` kernel. The lower commit range is the
1628commit associated with the ``standard/base`` branch, while the upper
1629commit range is the commit associated with the ``standard/emenlow``
1630branch. $ git whatchanged origin/standard/base..origin/standard/emenlow
1631
1632To see short, one line summaries of changes use the ``git log`` command:
1633$ git log --oneline origin/standard/base..origin/standard/emenlow
1634
1635Use this command to see code differences for the changes: $ git diff
1636origin/standard/base..origin/standard/emenlow
1637
1638Use this command to see the commit log messages and the text
1639differences: $ git show origin/standard/base..origin/standard/emenlow
1640
1641Use this command to create individual patches for each change. Here is
1642an example that that creates patch files for each commit and places them
1643in your ``Documents`` directory: $ git format-patch -o $HOME/Documents
1644origin/standard/base..origin/standard/emenlow
1645
1646Showing a Particular Feature or Branch Change
1647---------------------------------------------
1648
1649Tags in the Yocto Project kernel tree divide changes for significant
1650features or branches. The ``git show`` tag command shows changes based
1651on a tag. Here is an example that shows ``systemtap`` changes: $ git
1652show systemtap You can use the ``git branch --contains`` tag command to
1653show the branches that contain a particular feature. This command shows
1654the branches that contain the ``systemtap`` feature: $ git branch
1655--contains systemtap
1656
1657Adding Recipe-Space Kernel Features
1658===================================
1659
1660You can add kernel features in the
1661`recipe-space <#recipe-space-metadata>`__ by using the
1662```KERNEL_FEATURES`` <&YOCTO_DOCS_REF_URL;#var-KERNEL_FEATURES>`__
1663variable and by specifying the feature's ``.scc`` file path in the
1664```SRC_URI`` <&YOCTO_DOCS_REF_URL;#var-SRC_URI>`__ statement. When you
1665add features using this method, the OpenEmbedded build system checks to
1666be sure the features are present. If the features are not present, the
1667build stops. Kernel features are the last elements processed for
1668configuring and patching the kernel. Therefore, adding features in this
1669manner is a way to enforce specific features are present and enabled
1670without needing to do a full audit of any other layer's additions to the
1671``SRC_URI`` statement.
1672
1673You add a kernel feature by providing the feature as part of the
1674``KERNEL_FEATURES`` variable and by providing the path to the feature's
1675``.scc`` file, which is relative to the root of the kernel Metadata. The
1676OpenEmbedded build system searches all forms of kernel Metadata on the
1677``SRC_URI`` statement regardless of whether the Metadata is in the
1678"kernel-cache", system kernel Metadata, or a recipe-space Metadata (i.e.
1679part of the kernel recipe). See the "`Kernel Metadata
1680Location <#kernel-metadata-location>`__" section for additional
1681information.
1682
1683When you specify the feature's ``.scc`` file on the ``SRC_URI``
1684statement, the OpenEmbedded build system adds the directory of that
1685``.scc`` file along with all its subdirectories to the kernel feature
1686search path. Because subdirectories are searched, you can reference a
1687single ``.scc`` file in the ``SRC_URI`` statement to reference multiple
1688kernel features.
1689
1690Consider the following example that adds the "test.scc" feature to the
1691build.
1692
16931. *Create the Feature File:* Create a ``.scc`` file and locate it just
1694 as you would any other patch file, ``.cfg`` file, or fetcher item you
1695 specify in the ``SRC_URI`` statement.
1696
1697 .. note::
1698
1699 - You must add the directory of the ``.scc`` file to the
1700 fetcher's search path in the same manner as you would add a
1701 ``.patch`` file.
1702
1703 - You can create additional ``.scc`` files beneath the directory
1704 that contains the file you are adding. All subdirectories are
1705 searched during the build as potential feature directories.
1706
1707 Continuing with the example, suppose the "test.scc" feature you are
1708 adding has a ``test.scc`` file in the following directory: my_recipe
1709 \| +-linux-yocto \| +-test.cfg +-test.scc In this example, the
1710 ``linux-yocto`` directory has both the feature ``test.scc`` file and
1711 a similarly named configuration fragment file ``test.cfg``.
1712
17132. *Add the Feature File to ``SRC_URI``:* Add the ``.scc`` file to the
1714 recipe's ``SRC_URI`` statement: SRC_URI_append = " file://test.scc"
1715 The leading space before the path is important as the path is
1716 appended to the existing path.
1717
17183. *Specify the Feature as a Kernel Feature:* Use the
1719 ``KERNEL_FEATURES`` statement to specify the feature as a kernel
1720 feature: KERNEL_FEATURES_append = " test.scc" The OpenEmbedded build
1721 system processes the kernel feature when it builds the kernel.
1722
1723 .. note::
1724
1725 If other features are contained below "test.scc", then their
1726 directories are relative to the directory containing the
1727 test.scc
1728 file.