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