diff options
Diffstat (limited to 'documentation/kernel-dev')
-rw-r--r-- | documentation/kernel-dev/advanced.rst | 259 | ||||
-rw-r--r-- | documentation/kernel-dev/common.rst | 795 | ||||
-rw-r--r-- | documentation/kernel-dev/concepts-appx.rst | 25 | ||||
-rw-r--r-- | documentation/kernel-dev/faq.rst | 18 | ||||
-rw-r--r-- | documentation/kernel-dev/history.rst | 58 | ||||
-rw-r--r-- | documentation/kernel-dev/index.rst | 1 | ||||
-rw-r--r-- | documentation/kernel-dev/intro.rst | 33 | ||||
-rw-r--r-- | documentation/kernel-dev/maint-appx.rst | 44 |
8 files changed, 481 insertions, 752 deletions
diff --git a/documentation/kernel-dev/advanced.rst b/documentation/kernel-dev/advanced.rst index dd0b76bc31..4c463503f6 100644 --- a/documentation/kernel-dev/advanced.rst +++ b/documentation/kernel-dev/advanced.rst | |||
@@ -21,7 +21,7 @@ is the ``yocto-kernel-cache`` Git repository. You can find this repository | |||
21 | grouped under the "Yocto Linux Kernel" heading in the | 21 | grouped under the "Yocto Linux Kernel" heading in the |
22 | :yocto_git:`Yocto Project Source Repositories <>`. | 22 | :yocto_git:`Yocto Project Source Repositories <>`. |
23 | 23 | ||
24 | Kernel development tools ("kern-tools") exist also in the Yocto Project | 24 | Kernel development tools ("kern-tools") are also available in the Yocto Project |
25 | Source Repositories under the "Yocto Linux Kernel" heading in the | 25 | Source Repositories under the "Yocto Linux Kernel" heading in the |
26 | ``yocto-kernel-tools`` Git repository. The recipe that builds these | 26 | ``yocto-kernel-tools`` Git repository. The recipe that builds these |
27 | tools is ``meta/recipes-kernel/kern-tools/kern-tools-native_git.bb`` in | 27 | tools is ``meta/recipes-kernel/kern-tools/kern-tools-native_git.bb`` in |
@@ -46,18 +46,18 @@ linux-yocto recipe. | |||
46 | 46 | ||
47 | Every linux-yocto style recipe must define the | 47 | Every linux-yocto style recipe must define the |
48 | :term:`KMACHINE` variable. This | 48 | :term:`KMACHINE` variable. This |
49 | variable is typically set to the same value as the ``MACHINE`` variable, | 49 | variable is typically set to the same value as the :term:`MACHINE` variable, |
50 | which is used by :term:`BitBake`. | 50 | which is used by :term:`BitBake`. |
51 | However, in some cases, the variable might instead refer to the | 51 | However, in some cases, the variable might instead refer to the |
52 | underlying platform of the ``MACHINE``. | 52 | underlying platform of the :term:`MACHINE`. |
53 | 53 | ||
54 | Multiple BSPs can reuse the same ``KMACHINE`` name if they are built | 54 | Multiple BSPs can reuse the same :term:`KMACHINE` name if they are built |
55 | using the same BSP description. Multiple Corei7-based BSPs could share | 55 | using the same BSP description. Multiple Corei7-based BSPs could share |
56 | the same "intel-corei7-64" value for ``KMACHINE``. It is important to | 56 | the same "intel-corei7-64" value for :term:`KMACHINE`. It is important to |
57 | realize that ``KMACHINE`` is just for kernel mapping, while ``MACHINE`` | 57 | realize that :term:`KMACHINE` is just for kernel mapping, while :term:`MACHINE` |
58 | is the machine type within a BSP Layer. Even with this distinction, | 58 | is the machine type within a BSP Layer. Even with this distinction, |
59 | however, these two variables can hold the same value. See the `BSP | 59 | however, these two variables can hold the same value. See the |
60 | Descriptions <#bsp-descriptions>`__ section for more information. | 60 | ":ref:`kernel-dev/advanced:bsp descriptions`" section for more information. |
61 | 61 | ||
62 | Every linux-yocto style recipe must also indicate the Linux kernel | 62 | Every linux-yocto style recipe must also indicate the Linux kernel |
63 | source repository branch used to build the Linux kernel. The | 63 | source repository branch used to build the Linux kernel. The |
@@ -66,12 +66,10 @@ to indicate the branch. | |||
66 | 66 | ||
67 | .. note:: | 67 | .. note:: |
68 | 68 | ||
69 | You can use the ``KBRANCH`` value to define an alternate branch typically | 69 | You can use the :term:`KBRANCH` value to define an alternate branch typically |
70 | with a machine override as shown here from the ``meta-yocto-bsp`` layer: | 70 | with a machine override as shown here from the ``meta-yocto-bsp`` layer:: |
71 | :: | ||
72 | |||
73 | KBRANCH_edgerouter = "standard/edgerouter" | ||
74 | 71 | ||
72 | KBRANCH:beaglebone-yocto = "standard/beaglebone" | ||
75 | 73 | ||
76 | The linux-yocto style recipes can optionally define the following | 74 | The linux-yocto style recipes can optionally define the following |
77 | variables: | 75 | variables: |
@@ -82,49 +80,47 @@ variables: | |||
82 | 80 | ||
83 | :term:`LINUX_KERNEL_TYPE` | 81 | :term:`LINUX_KERNEL_TYPE` |
84 | defines the kernel type to be used in assembling the configuration. If | 82 | defines the kernel type to be used in assembling the configuration. If |
85 | you do not specify a ``LINUX_KERNEL_TYPE``, it defaults to "standard". | 83 | you do not specify a :term:`LINUX_KERNEL_TYPE`, it defaults to "standard". |
86 | Together with ``KMACHINE``, ``LINUX_KERNEL_TYPE`` defines the search | 84 | Together with :term:`KMACHINE`, :term:`LINUX_KERNEL_TYPE` defines the search |
87 | arguments used by the kernel tools to find the appropriate description | 85 | arguments used by the kernel tools to find the appropriate description |
88 | within the kernel Metadata with which to build out the sources and | 86 | within the kernel Metadata with which to build out the sources and |
89 | configuration. The linux-yocto recipes define "standard", "tiny", and | 87 | configuration. The linux-yocto recipes define "standard", "tiny", and |
90 | "preempt-rt" kernel types. See the "`Kernel Types <#kernel-types>`__" | 88 | "preempt-rt" kernel types. See the ":ref:`kernel-dev/advanced:kernel types`" |
91 | section for more information on kernel types. | 89 | section for more information on kernel types. |
92 | 90 | ||
93 | During the build, the kern-tools search for the BSP description file | 91 | During the build, the kern-tools search for the BSP description file |
94 | that most closely matches the ``KMACHINE`` and ``LINUX_KERNEL_TYPE`` | 92 | that most closely matches the :term:`KMACHINE` and :term:`LINUX_KERNEL_TYPE` |
95 | variables passed in from the recipe. The tools use the first BSP | 93 | variables passed in from the recipe. The tools use the first BSP |
96 | description they find that matches both variables. If the tools cannot find | 94 | description they find that matches both variables. If the tools cannot find |
97 | a match, they issue a warning. | 95 | a match, they issue a warning. |
98 | 96 | ||
99 | The tools first search for the ``KMACHINE`` and then for the | 97 | The tools first search for the :term:`KMACHINE` and then for the |
100 | ``LINUX_KERNEL_TYPE``. If the tools cannot find a partial match, they | 98 | :term:`LINUX_KERNEL_TYPE`. If the tools cannot find a partial match, they |
101 | will use the sources from the ``KBRANCH`` and any configuration | 99 | will use the sources from the :term:`KBRANCH` and any configuration |
102 | specified in the :term:`SRC_URI`. | 100 | specified in the :term:`SRC_URI`. |
103 | 101 | ||
104 | You can use the | 102 | You can use the |
105 | :term:`KERNEL_FEATURES` | 103 | :term:`KERNEL_FEATURES` |
106 | variable to include features (configuration fragments, patches, or both) | 104 | variable to include features (configuration fragments, patches, or both) |
107 | that are not already included by the ``KMACHINE`` and | 105 | that are not already included by the :term:`KMACHINE` and |
108 | ``LINUX_KERNEL_TYPE`` variable combination. For example, to include a | 106 | :term:`LINUX_KERNEL_TYPE` variable combination. For example, to include a |
109 | feature specified as "features/netfilter/netfilter.scc", specify: | 107 | feature specified as "features/netfilter/netfilter.scc", specify:: |
110 | :: | ||
111 | 108 | ||
112 | KERNEL_FEATURES += "features/netfilter/netfilter.scc" | 109 | KERNEL_FEATURES += "features/netfilter/netfilter.scc" |
113 | 110 | ||
114 | To include a | 111 | To include a |
115 | feature called "cfg/sound.scc" just for the ``qemux86`` machine, | 112 | feature called "cfg/sound.scc" just for the ``qemux86`` machine, |
116 | specify: | 113 | specify:: |
117 | :: | ||
118 | 114 | ||
119 | KERNEL_FEATURES_append_qemux86 = " cfg/sound.scc" | 115 | KERNEL_FEATURES:append:qemux86 = " cfg/sound.scc" |
120 | 116 | ||
121 | The value of | 117 | The value of |
122 | the entries in ``KERNEL_FEATURES`` are dependent on their location | 118 | the entries in :term:`KERNEL_FEATURES` are dependent on their location |
123 | within the kernel Metadata itself. The examples here are taken from the | 119 | within the kernel Metadata itself. The examples here are taken from the |
124 | ``yocto-kernel-cache`` repository. Each branch of this repository | 120 | ``yocto-kernel-cache`` repository. Each branch of this repository |
125 | contains "features" and "cfg" subdirectories at the top-level. For more | 121 | contains "features" and "cfg" subdirectories at the top-level. For more |
126 | information, see the "`Kernel Metadata | 122 | information, see the ":ref:`kernel-dev/advanced:kernel metadata syntax`" |
127 | Syntax <#kernel-metadata-syntax>`__" section. | 123 | section. |
128 | 124 | ||
129 | Kernel Metadata Syntax | 125 | Kernel Metadata Syntax |
130 | ====================== | 126 | ====================== |
@@ -148,7 +144,7 @@ Features aggregate sources in the form of patches and configuration | |||
148 | fragments into a modular reusable unit. You can use features to | 144 | fragments into a modular reusable unit. You can use features to |
149 | implement conceptually separate kernel Metadata descriptions such as | 145 | implement conceptually separate kernel Metadata descriptions such as |
150 | pure configuration fragments, simple patches, complex features, and | 146 | pure configuration fragments, simple patches, complex features, and |
151 | kernel types. `Kernel types <#kernel-types>`__ define general kernel | 147 | kernel types. :ref:`kernel-dev/advanced:kernel types` define general kernel |
152 | features and policy to be reused in the BSPs. | 148 | features and policy to be reused in the BSPs. |
153 | 149 | ||
154 | BSPs define hardware-specific features and aggregate them with kernel | 150 | BSPs define hardware-specific features and aggregate them with kernel |
@@ -157,8 +153,7 @@ types to form the final description of what will be assembled and built. | |||
157 | While the kernel Metadata syntax does not enforce any logical separation | 153 | While the kernel Metadata syntax does not enforce any logical separation |
158 | of configuration fragments, patches, features or kernel types, best | 154 | of configuration fragments, patches, features or kernel types, best |
159 | practices dictate a logical separation of these types of Metadata. The | 155 | practices dictate a logical separation of these types of Metadata. The |
160 | following Metadata file hierarchy is recommended: | 156 | following Metadata file hierarchy is recommended:: |
161 | :: | ||
162 | 157 | ||
163 | base/ | 158 | base/ |
164 | bsp/ | 159 | bsp/ |
@@ -167,10 +162,9 @@ following Metadata file hierarchy is recommended: | |||
167 | ktypes/ | 162 | ktypes/ |
168 | patches/ | 163 | patches/ |
169 | 164 | ||
170 | The ``bsp`` directory contains the `BSP | 165 | The ``bsp`` directory contains the :ref:`kernel-dev/advanced:bsp descriptions`. |
171 | descriptions <#bsp-descriptions>`__. The remaining directories all | 166 | The remaining directories all contain "features". Separating ``bsp`` from the |
172 | contain "features". Separating ``bsp`` from the rest of the structure | 167 | rest of the structure aids conceptualizing intended usage. |
173 | aids conceptualizing intended usage. | ||
174 | 168 | ||
175 | Use these guidelines to help place your ``scc`` description files within | 169 | Use these guidelines to help place your ``scc`` description files within |
176 | the structure: | 170 | the structure: |
@@ -188,7 +182,7 @@ the structure: | |||
188 | order to define a base kernel policy or major kernel type to be | 182 | order to define a base kernel policy or major kernel type to be |
189 | reused across multiple BSPs, place the file in ``ktypes`` directory. | 183 | reused across multiple BSPs, place the file in ``ktypes`` directory. |
190 | 184 | ||
191 | These distinctions can easily become blurred - especially as out-of-tree | 185 | These distinctions can easily become blurred --- especially as out-of-tree |
192 | features slowly merge upstream over time. Also, remember that how the | 186 | features slowly merge upstream over time. Also, remember that how the |
193 | description files are placed is a purely logical organization and has no | 187 | description files are placed is a purely logical organization and has no |
194 | impact on the functionality of the kernel Metadata. There is no impact | 188 | impact on the functionality of the kernel Metadata. There is no impact |
@@ -198,11 +192,12 @@ contain "features" as far as the kernel tools are concerned. | |||
198 | Paths used in kernel Metadata files are relative to base, which is | 192 | Paths used in kernel Metadata files are relative to base, which is |
199 | either | 193 | either |
200 | :term:`FILESEXTRAPATHS` if | 194 | :term:`FILESEXTRAPATHS` if |
201 | you are creating Metadata in `recipe-space <#recipe-space-metadata>`__, | 195 | you are creating Metadata in |
196 | :ref:`recipe-space <kernel-dev/advanced:recipe-space metadata>`, | ||
202 | or the top level of | 197 | or the top level of |
203 | :yocto_git:`yocto-kernel-cache </yocto-kernel-cache/tree/>` | 198 | :yocto_git:`yocto-kernel-cache </yocto-kernel-cache/tree/>` |
204 | if you are creating `Metadata outside of the | 199 | if you are creating |
205 | recipe-space <#metadata-outside-the-recipe-space>`__. | 200 | :ref:`kernel-dev/advanced:metadata outside the recipe-space`. |
206 | 201 | ||
207 | .. [1] | 202 | .. [1] |
208 | ``scc`` stands for Series Configuration Control, but the naming has | 203 | ``scc`` stands for Series Configuration Control, but the naming has |
@@ -222,8 +217,7 @@ used with the ``linux-yocto-4.12`` kernel as defined outside of the | |||
222 | recipe space (i.e. ``yocto-kernel-cache``). This Metadata consists of | 217 | recipe space (i.e. ``yocto-kernel-cache``). This Metadata consists of |
223 | two files: ``smp.scc`` and ``smp.cfg``. You can find these files in the | 218 | two files: ``smp.scc`` and ``smp.cfg``. You can find these files in the |
224 | ``cfg`` directory of the ``yocto-4.12`` branch in the | 219 | ``cfg`` directory of the ``yocto-4.12`` branch in the |
225 | ``yocto-kernel-cache`` Git repository: | 220 | ``yocto-kernel-cache`` Git repository:: |
226 | :: | ||
227 | 221 | ||
228 | cfg/smp.scc: | 222 | cfg/smp.scc: |
229 | define KFEATURE_DESCRIPTION "Enable SMP for 32 bit builds" | 223 | define KFEATURE_DESCRIPTION "Enable SMP for 32 bit builds" |
@@ -265,8 +259,7 @@ non-hardware fragment. | |||
265 | 259 | ||
266 | As described in the | 260 | As described in the |
267 | ":ref:`kernel-dev/common:validating configuration`" section, you can | 261 | ":ref:`kernel-dev/common:validating configuration`" section, you can |
268 | use the following BitBake command to audit your configuration: | 262 | use the following BitBake command to audit your configuration:: |
269 | :: | ||
270 | 263 | ||
271 | $ bitbake linux-yocto -c kernel_configcheck -f | 264 | $ bitbake linux-yocto -c kernel_configcheck -f |
272 | 265 | ||
@@ -287,8 +280,7 @@ in the ``patches/build`` directory of the ``yocto-4.12`` branch in the | |||
287 | ``yocto-kernel-cache`` Git repository. | 280 | ``yocto-kernel-cache`` Git repository. |
288 | 281 | ||
289 | The following listings show the ``build.scc`` file and part of the | 282 | The following listings show the ``build.scc`` file and part of the |
290 | ``modpost-mask-trivial-warnings.patch`` file: | 283 | ``modpost-mask-trivial-warnings.patch`` file:: |
291 | :: | ||
292 | 284 | ||
293 | patches/build/build.scc: | 285 | patches/build/build.scc: |
294 | patch arm-serialize-build-targets.patch | 286 | patch arm-serialize-build-targets.patch |
@@ -311,8 +303,8 @@ The following listings show the ``build.scc`` file and part of the | |||
311 | . | 303 | . |
312 | . | 304 | . |
313 | . | 305 | . |
314 | char *dump_write = NULL, *files_source = NULL; | 306 | char *dump_write = NULL, *files_source = NULL; |
315 | int opt; | 307 | int opt; |
316 | -- | 308 | -- |
317 | 2.10.1 | 309 | 2.10.1 |
318 | 310 | ||
@@ -320,7 +312,7 @@ The following listings show the ``build.scc`` file and part of the | |||
320 | 312 | ||
321 | The description file can | 313 | The description file can |
322 | include multiple patch statements where each statement handles a single | 314 | include multiple patch statements where each statement handles a single |
323 | patch. In the example ``build.scc`` file, five patch statements exist | 315 | patch. In the example ``build.scc`` file, there are five patch statements |
324 | for the five patches in the directory. | 316 | for the five patches in the directory. |
325 | 317 | ||
326 | You can create a typical ``.patch`` file using ``diff -Nurp`` or | 318 | You can create a typical ``.patch`` file using ``diff -Nurp`` or |
@@ -334,8 +326,7 @@ Features | |||
334 | 326 | ||
335 | Features are complex kernel Metadata types that consist of configuration | 327 | Features are complex kernel Metadata types that consist of configuration |
336 | fragments, patches, and possibly other feature description files. As an | 328 | fragments, patches, and possibly other feature description files. As an |
337 | example, consider the following generic listing: | 329 | example, consider the following generic listing:: |
338 | :: | ||
339 | 330 | ||
340 | features/myfeature.scc | 331 | features/myfeature.scc |
341 | define KFEATURE_DESCRIPTION "Enable myfeature" | 332 | define KFEATURE_DESCRIPTION "Enable myfeature" |
@@ -352,34 +343,30 @@ as how an additional feature description file is included with the | |||
352 | 343 | ||
353 | Typically, features are less granular than configuration fragments and | 344 | Typically, features are less granular than configuration fragments and |
354 | are more likely than configuration fragments and patches to be the types | 345 | are more likely than configuration fragments and patches to be the types |
355 | of things you want to specify in the ``KERNEL_FEATURES`` variable of the | 346 | of things you want to specify in the :term:`KERNEL_FEATURES` variable of the |
356 | Linux kernel recipe. See the "`Using Kernel Metadata in a | 347 | Linux kernel recipe. See the |
357 | Recipe <#using-kernel-metadata-in-a-recipe>`__" section earlier in the | 348 | ":ref:`kernel-dev/advanced:using kernel metadata in a recipe`" section earlier |
358 | manual. | 349 | in the manual. |
359 | 350 | ||
360 | Kernel Types | 351 | Kernel Types |
361 | ------------ | 352 | ------------ |
362 | 353 | ||
363 | A kernel type defines a high-level kernel policy by aggregating | 354 | A kernel type defines a high-level kernel policy by aggregating non-hardware |
364 | non-hardware configuration fragments with patches you want to use when | 355 | configuration fragments with patches you want to use when building a Linux |
365 | building a Linux kernel of a specific type (e.g. a real-time kernel). | 356 | kernel of a specific type (e.g. a real-time kernel). Syntactically, kernel |
366 | Syntactically, kernel types are no different than features as described | 357 | types are no different than features as described in the |
367 | in the "`Features <#features>`__" section. The | 358 | ":ref:`kernel-dev/advanced:features`" section. The :term:`LINUX_KERNEL_TYPE` |
368 | :term:`LINUX_KERNEL_TYPE` | 359 | variable in the kernel recipe selects the kernel type. For example, in the |
369 | variable in the kernel recipe selects the kernel type. For example, in | 360 | ``linux-yocto_4.12.bb`` kernel recipe found in ``poky/meta/recipes-kernel/linux``, a |
370 | the ``linux-yocto_4.12.bb`` kernel recipe found in | 361 | :ref:`require <bitbake-user-manual/bitbake-user-manual-metadata:\`\`require\`\` directive>` |
371 | ``poky/meta/recipes-kernel/linux``, a | 362 | directive includes the ``poky/meta/recipes-kernel/linux/linux-yocto.inc`` file, |
372 | :ref:`require <bitbake:bitbake-user-manual/bitbake-user-manual-metadata:\`\`require\`\` directive>` directive | 363 | which has the following statement that defines the default kernel type:: |
373 | includes the ``poky/meta/recipes-kernel/linux/linux-yocto.inc`` file, | ||
374 | which has the following statement that defines the default kernel type: | ||
375 | :: | ||
376 | 364 | ||
377 | LINUX_KERNEL_TYPE ??= "standard" | 365 | LINUX_KERNEL_TYPE ??= "standard" |
378 | 366 | ||
379 | Another example would be the real-time kernel (i.e. | 367 | Another example would be the real-time kernel (i.e. |
380 | ``linux-yocto-rt_4.12.bb``). This kernel recipe directly sets the kernel | 368 | ``linux-yocto-rt_4.12.bb``). This kernel recipe directly sets the kernel |
381 | type as follows: | 369 | type as follows:: |
382 | :: | ||
383 | 370 | ||
384 | LINUX_KERNEL_TYPE = "preempt-rt" | 371 | LINUX_KERNEL_TYPE = "preempt-rt" |
385 | 372 | ||
@@ -412,8 +399,7 @@ for Linux Yocto kernels: | |||
412 | For any given kernel type, the Metadata is defined by the ``.scc`` (e.g. | 399 | For any given kernel type, the Metadata is defined by the ``.scc`` (e.g. |
413 | ``standard.scc``). Here is a partial listing for the ``standard.scc`` | 400 | ``standard.scc``). Here is a partial listing for the ``standard.scc`` |
414 | file, which is found in the ``ktypes/standard`` directory of the | 401 | file, which is found in the ``ktypes/standard`` directory of the |
415 | ``yocto-kernel-cache`` Git repository: | 402 | ``yocto-kernel-cache`` Git repository:: |
416 | :: | ||
417 | 403 | ||
418 | # Include this kernel type fragment to get the standard features and | 404 | # Include this kernel type fragment to get the standard features and |
419 | # configuration values. | 405 | # configuration values. |
@@ -482,15 +468,13 @@ Description Overview | |||
482 | For simplicity, consider the following root BSP layer description files | 468 | For simplicity, consider the following root BSP layer description files |
483 | for the BeagleBone board. These files employ both a structure and naming | 469 | for the BeagleBone board. These files employ both a structure and naming |
484 | convention for consistency. The naming convention for the file is as | 470 | convention for consistency. The naming convention for the file is as |
485 | follows: | 471 | follows:: |
486 | :: | ||
487 | 472 | ||
488 | bsp_root_name-kernel_type.scc | 473 | bsp_root_name-kernel_type.scc |
489 | 474 | ||
490 | Here are some example root layer | 475 | Here are some example root layer |
491 | BSP filenames for the BeagleBone Board BSP, which is supported by the | 476 | BSP filenames for the BeagleBone Board BSP, which is supported by the |
492 | Yocto Project: | 477 | Yocto Project:: |
493 | :: | ||
494 | 478 | ||
495 | beaglebone-standard.scc | 479 | beaglebone-standard.scc |
496 | beaglebone-preempt-rt.scc | 480 | beaglebone-preempt-rt.scc |
@@ -498,8 +482,7 @@ Yocto Project: | |||
498 | Each file uses the root name (i.e "beaglebone") BSP name followed by the | 482 | Each file uses the root name (i.e "beaglebone") BSP name followed by the |
499 | kernel type. | 483 | kernel type. |
500 | 484 | ||
501 | Examine the ``beaglebone-standard.scc`` file: | 485 | Examine the ``beaglebone-standard.scc`` file:: |
502 | :: | ||
503 | 486 | ||
504 | define KMACHINE beaglebone | 487 | define KMACHINE beaglebone |
505 | define KTYPE standard | 488 | define KTYPE standard |
@@ -523,34 +506,31 @@ description as meeting the criteria set by the recipe being built. This | |||
523 | example supports the "beaglebone" machine for the "standard" kernel and | 506 | example supports the "beaglebone" machine for the "standard" kernel and |
524 | the "arm" architecture. | 507 | the "arm" architecture. |
525 | 508 | ||
526 | Be aware that a hard link between the ``KTYPE`` variable and a kernel | 509 | Be aware that there is no hard link between the :term:`KTYPE` variable and a kernel |
527 | type description file does not exist. Thus, if you do not have the | 510 | type description file. Thus, if you do not have the |
528 | kernel type defined in your kernel Metadata as it is here, you only need | 511 | kernel type defined in your kernel Metadata as it is here, you only need |
529 | to ensure that the | 512 | to ensure that the |
530 | :term:`LINUX_KERNEL_TYPE` | 513 | :term:`LINUX_KERNEL_TYPE` |
531 | variable in the kernel recipe and the ``KTYPE`` variable in the BSP | 514 | variable in the kernel recipe and the :term:`KTYPE` variable in the BSP |
532 | description file match. | 515 | description file match. |
533 | 516 | ||
534 | To separate your kernel policy from your hardware configuration, you | 517 | To separate your kernel policy from your hardware configuration, you |
535 | include a kernel type (``ktype``), such as "standard". In the previous | 518 | include a kernel type (``ktype``), such as "standard". In the previous |
536 | example, this is done using the following: | 519 | example, this is done using the following:: |
537 | :: | ||
538 | 520 | ||
539 | include ktypes/standard/standard.scc | 521 | include ktypes/standard/standard.scc |
540 | 522 | ||
541 | This file aggregates all the configuration | 523 | This file aggregates all the configuration |
542 | fragments, patches, and features that make up your standard kernel | 524 | fragments, patches, and features that make up your standard kernel |
543 | policy. See the "`Kernel Types <#kernel-types>`__" section for more | 525 | policy. See the ":ref:`kernel-dev/advanced:kernel types`" section for more |
544 | information. | 526 | information. |
545 | 527 | ||
546 | To aggregate common configurations and features specific to the kernel | 528 | To aggregate common configurations and features specific to the kernel |
547 | for `mybsp`, use the following: | 529 | for `mybsp`, use the following:: |
548 | :: | ||
549 | 530 | ||
550 | include mybsp.scc | 531 | include mybsp.scc |
551 | 532 | ||
552 | You can see that in the BeagleBone example with the following: | 533 | You can see that in the BeagleBone example with the following:: |
553 | :: | ||
554 | 534 | ||
555 | include beaglebone.scc | 535 | include beaglebone.scc |
556 | 536 | ||
@@ -558,15 +538,13 @@ For information on how to break a complete ``.config`` file into the various | |||
558 | configuration fragments, see the ":ref:`kernel-dev/common:creating configuration fragments`" section. | 538 | configuration fragments, see the ":ref:`kernel-dev/common:creating configuration fragments`" section. |
559 | 539 | ||
560 | Finally, if you have any configurations specific to the hardware that | 540 | Finally, if you have any configurations specific to the hardware that |
561 | are not in a ``*.scc`` file, you can include them as follows: | 541 | are not in a ``*.scc`` file, you can include them as follows:: |
562 | :: | ||
563 | 542 | ||
564 | kconf hardware mybsp-extra.cfg | 543 | kconf hardware mybsp-extra.cfg |
565 | 544 | ||
566 | The BeagleBone example does not include these | 545 | The BeagleBone example does not include these |
567 | types of configurations. However, the Malta 32-bit board does | 546 | types of configurations. However, the Malta 32-bit board does |
568 | ("mti-malta32"). Here is the ``mti-malta32-le-standard.scc`` file: | 547 | ("mti-malta32"). Here is the ``mti-malta32-le-standard.scc`` file:: |
569 | :: | ||
570 | 548 | ||
571 | define KMACHINE mti-malta32-le | 549 | define KMACHINE mti-malta32-le |
572 | define KMACHINE qemumipsel | 550 | define KMACHINE qemumipsel |
@@ -585,15 +563,7 @@ Example | |||
585 | Many real-world examples are more complex. Like any other ``.scc`` file, | 563 | Many real-world examples are more complex. Like any other ``.scc`` file, |
586 | BSP descriptions can aggregate features. Consider the Minnow BSP | 564 | BSP descriptions can aggregate features. Consider the Minnow BSP |
587 | definition given the ``linux-yocto-4.4`` branch of the | 565 | definition given the ``linux-yocto-4.4`` branch of the |
588 | ``yocto-kernel-cache`` (i.e. | 566 | ``yocto-kernel-cache`` (i.e. ``yocto-kernel-cache/bsp/minnow/minnow.scc``):: |
589 | ``yocto-kernel-cache/bsp/minnow/minnow.scc``): | ||
590 | |||
591 | .. note:: | ||
592 | |||
593 | Although the Minnow Board BSP is unused, the Metadata remains and is | ||
594 | being used here just as an example. | ||
595 | |||
596 | :: | ||
597 | 567 | ||
598 | include cfg/x86.scc | 568 | include cfg/x86.scc |
599 | include features/eg20t/eg20t.scc | 569 | include features/eg20t/eg20t.scc |
@@ -616,6 +586,11 @@ definition given the ``linux-yocto-4.4`` branch of the | |||
616 | kconf hardware minnow.cfg | 586 | kconf hardware minnow.cfg |
617 | kconf hardware minnow-dev.cfg | 587 | kconf hardware minnow-dev.cfg |
618 | 588 | ||
589 | .. note:: | ||
590 | |||
591 | Although the Minnow Board BSP is unused, the Metadata remains and is | ||
592 | being used here just as an example. | ||
593 | |||
619 | The ``minnow.scc`` description file includes a hardware configuration | 594 | The ``minnow.scc`` description file includes a hardware configuration |
620 | fragment (``minnow.cfg``) specific to the Minnow BSP as well as several | 595 | fragment (``minnow.cfg``) specific to the Minnow BSP as well as several |
621 | more general configuration fragments and features enabling hardware | 596 | more general configuration fragments and features enabling hardware |
@@ -623,8 +598,7 @@ found on the machine. This ``minnow.scc`` description file is then | |||
623 | included in each of the three "minnow" description files for the | 598 | included in each of the three "minnow" description files for the |
624 | supported kernel types (i.e. "standard", "preempt-rt", and "tiny"). | 599 | supported kernel types (i.e. "standard", "preempt-rt", and "tiny"). |
625 | Consider the "minnow" description for the "standard" kernel type (i.e. | 600 | Consider the "minnow" description for the "standard" kernel type (i.e. |
626 | ``minnow-standard.scc``): | 601 | ``minnow-standard.scc``):: |
627 | :: | ||
628 | 602 | ||
629 | define KMACHINE minnow | 603 | define KMACHINE minnow |
630 | define KTYPE standard | 604 | define KTYPE standard |
@@ -656,8 +630,7 @@ that defines all enabled hardware for the BSP that is common to all | |||
656 | kernel types. Using this command significantly reduces duplication. | 630 | kernel types. Using this command significantly reduces duplication. |
657 | 631 | ||
658 | Now consider the "minnow" description for the "tiny" kernel type (i.e. | 632 | Now consider the "minnow" description for the "tiny" kernel type (i.e. |
659 | ``minnow-tiny.scc``): | 633 | ``minnow-tiny.scc``):: |
660 | :: | ||
661 | 634 | ||
662 | define KMACHINE minnow | 635 | define KMACHINE minnow |
663 | define KTYPE tiny | 636 | define KTYPE tiny |
@@ -678,7 +651,7 @@ Notice again the three critical variables: | |||
678 | :term:`KMACHINE`, | 651 | :term:`KMACHINE`, |
679 | :term:`KTYPE`, and | 652 | :term:`KTYPE`, and |
680 | :term:`KARCH`. Of these variables, only | 653 | :term:`KARCH`. Of these variables, only |
681 | ``KTYPE`` has changed to specify the "tiny" kernel type. | 654 | :term:`KTYPE` has changed to specify the "tiny" kernel type. |
682 | 655 | ||
683 | Kernel Metadata Location | 656 | Kernel Metadata Location |
684 | ======================== | 657 | ======================== |
@@ -709,19 +682,17 @@ Recipe-Space Metadata | |||
709 | --------------------- | 682 | --------------------- |
710 | 683 | ||
711 | When stored in recipe-space, the kernel Metadata files reside in a | 684 | When stored in recipe-space, the kernel Metadata files reside in a |
712 | directory hierarchy below | 685 | directory hierarchy below :term:`FILESEXTRAPATHS`. For |
713 | :term:`FILESEXTRAPATHS`. For | 686 | a linux-yocto recipe or for a Linux kernel recipe derived by copying |
714 | a linux-yocto recipe or for a Linux kernel recipe derived by copying and | 687 | :oe_git:`meta-skeleton/recipes-kernel/linux/linux-yocto-custom.bb |
715 | modifying | 688 | </openembedded-core/tree/meta-skeleton/recipes-kernel/linux/linux-yocto-custom.bb>` |
716 | ``oe-core/meta-skeleton/recipes-kernel/linux/linux-yocto-custom.bb`` to | 689 | into your layer and modifying it, :term:`FILESEXTRAPATHS` is typically set to |
717 | a recipe in your layer, ``FILESEXTRAPATHS`` is typically set to | ||
718 | ``${``\ :term:`THISDIR`\ ``}/${``\ :term:`PN`\ ``}``. | 690 | ``${``\ :term:`THISDIR`\ ``}/${``\ :term:`PN`\ ``}``. |
719 | See the ":ref:`kernel-dev/common:modifying an existing recipe`" | 691 | See the ":ref:`kernel-dev/common:modifying an existing recipe`" |
720 | section for more information. | 692 | section for more information. |
721 | 693 | ||
722 | Here is an example that shows a trivial tree of kernel Metadata stored | 694 | Here is an example that shows a trivial tree of kernel Metadata stored |
723 | in recipe-space within a BSP layer: | 695 | in recipe-space within a BSP layer:: |
724 | :: | ||
725 | 696 | ||
726 | meta-my_bsp_layer/ | 697 | meta-my_bsp_layer/ |
727 | `-- recipes-kernel | 698 | `-- recipes-kernel |
@@ -740,14 +711,13 @@ and fetches any files referenced in the ``.scc`` files by the | |||
740 | ``include``, ``patch``, or ``kconf`` commands. Because of this, it is | 711 | ``include``, ``patch``, or ``kconf`` commands. Because of this, it is |
741 | necessary to bump the recipe :term:`PR` | 712 | necessary to bump the recipe :term:`PR` |
742 | value when changing the content of files not explicitly listed in the | 713 | value when changing the content of files not explicitly listed in the |
743 | ``SRC_URI``. | 714 | :term:`SRC_URI`. |
744 | 715 | ||
745 | If the BSP description is in recipe space, you cannot simply list the | 716 | If the BSP description is in recipe space, you cannot simply list the |
746 | ``*.scc`` in the ``SRC_URI`` statement. You need to use the following | 717 | ``*.scc`` in the :term:`SRC_URI` statement. You need to use the following |
747 | form from your kernel append file: | 718 | form from your kernel append file:: |
748 | :: | ||
749 | 719 | ||
750 | SRC_URI_append_myplatform = " \ | 720 | SRC_URI:append:myplatform = " \ |
751 | file://myplatform;type=kmeta;destsuffix=myplatform \ | 721 | file://myplatform;type=kmeta;destsuffix=myplatform \ |
752 | " | 722 | " |
753 | 723 | ||
@@ -758,37 +728,35 @@ When stored outside of the recipe-space, the kernel Metadata files | |||
758 | reside in a separate repository. The OpenEmbedded build system adds the | 728 | reside in a separate repository. The OpenEmbedded build system adds the |
759 | Metadata to the build as a "type=kmeta" repository through the | 729 | Metadata to the build as a "type=kmeta" repository through the |
760 | :term:`SRC_URI` variable. As an | 730 | :term:`SRC_URI` variable. As an |
761 | example, consider the following ``SRC_URI`` statement from the | 731 | example, consider the following :term:`SRC_URI` statement from the |
762 | ``linux-yocto_4.12.bb`` kernel recipe: | 732 | ``linux-yocto_5.15.bb`` kernel recipe:: |
763 | :: | ||
764 | |||
765 | SRC_URI = "git://git.yoctoproject.org/linux-yocto-4.12.git;name=machine;branch=${KBRANCH}; \ | ||
766 | git://git.yoctoproject.org/yocto-kernel-cache;type=kmeta;name=meta;branch=yocto-4.12;destsuffix=${KMETA}" | ||
767 | 733 | ||
734 | SRC_URI = "git://git.yoctoproject.org/linux-yocto.git;name=machine;branch=${KBRANCH};protocol=https \ | ||
735 | git://git.yoctoproject.org/yocto-kernel-cache;type=kmeta;name=meta;branch=yocto-5.15;destsuffix=${KMETA};protocol=https" | ||
768 | 736 | ||
769 | ``${KMETA}``, in this context, is simply used to name the directory into | 737 | ``${KMETA}``, in this context, is simply used to name the directory into |
770 | which the Git fetcher places the Metadata. This behavior is no different | 738 | which the Git fetcher places the Metadata. This behavior is no different |
771 | than any multi-repository ``SRC_URI`` statement used in a recipe (e.g. | 739 | than any multi-repository :term:`SRC_URI` statement used in a recipe (e.g. |
772 | see the previous section). | 740 | see the previous section). |
773 | 741 | ||
774 | You can keep kernel Metadata in a "kernel-cache", which is a directory | 742 | You can keep kernel Metadata in a "kernel-cache", which is a directory |
775 | containing configuration fragments. As with any Metadata kept outside | 743 | containing configuration fragments. As with any Metadata kept outside |
776 | the recipe-space, you simply need to use the ``SRC_URI`` statement with | 744 | the recipe-space, you simply need to use the :term:`SRC_URI` statement with |
777 | the "type=kmeta" attribute. Doing so makes the kernel Metadata available | 745 | the "type=kmeta" attribute. Doing so makes the kernel Metadata available |
778 | during the configuration phase. | 746 | during the configuration phase. |
779 | 747 | ||
780 | If you modify the Metadata, you must not forget to update the ``SRCREV`` | 748 | If you modify the Metadata, you must not forget to update the :term:`SRCREV` |
781 | statements in the kernel's recipe. In particular, you need to update the | 749 | statements in the kernel's recipe. In particular, you need to update the |
782 | ``SRCREV_meta`` variable to match the commit in the ``KMETA`` branch you | 750 | ``SRCREV_meta`` variable to match the commit in the ``KMETA`` branch you |
783 | wish to use. Changing the data in these branches and not updating the | 751 | wish to use. Changing the data in these branches and not updating the |
784 | ``SRCREV`` statements to match will cause the build to fetch an older | 752 | :term:`SRCREV` statements to match will cause the build to fetch an older |
785 | commit. | 753 | commit. |
786 | 754 | ||
787 | Organizing Your Source | 755 | Organizing Your Source |
788 | ====================== | 756 | ====================== |
789 | 757 | ||
790 | Many recipes based on the ``linux-yocto-custom.bb`` recipe use Linux | 758 | Many recipes based on the ``linux-yocto-custom.bb`` recipe use Linux |
791 | kernel sources that have only a single branch - "master". This type of | 759 | kernel sources that have only a single branch. This type of |
792 | repository structure is fine for linear development supporting a single | 760 | repository structure is fine for linear development supporting a single |
793 | machine and architecture. However, if you work with multiple boards and | 761 | machine and architecture. However, if you work with multiple boards and |
794 | architectures, a kernel source repository with multiple branches is more | 762 | architectures, a kernel source repository with multiple branches is more |
@@ -797,11 +765,11 @@ board to boot. Sometimes, these patches are works-in-progress or | |||
797 | fundamentally wrong, yet they are still necessary for specific boards. | 765 | fundamentally wrong, yet they are still necessary for specific boards. |
798 | In these situations, you most likely do not want to include these | 766 | In these situations, you most likely do not want to include these |
799 | patches in every kernel you build (i.e. have the patches as part of the | 767 | patches in every kernel you build (i.e. have the patches as part of the |
800 | lone "master" branch). It is situations like these that give rise to | 768 | default branch). It is situations like these that give rise to |
801 | multiple branches used within a Linux kernel sources Git repository. | 769 | multiple branches used within a Linux kernel sources Git repository. |
802 | 770 | ||
803 | Repository organization strategies exist that maximize source reuse, | 771 | Here are repository organization strategies maximizing source reuse, |
804 | remove redundancy, and logically order your changes. This section | 772 | removing redundancy, and logically ordering your changes. This section |
805 | presents strategies for the following cases: | 773 | presents strategies for the following cases: |
806 | 774 | ||
807 | - Encapsulating patches in a feature description and only including the | 775 | - Encapsulating patches in a feature description and only including the |
@@ -825,11 +793,11 @@ Given this scenario, you do not need to create any branches in the | |||
825 | source repository. Rather, you just take the static patches you need and | 793 | source repository. Rather, you just take the static patches you need and |
826 | encapsulate them within a feature description. Once you have the feature | 794 | encapsulate them within a feature description. Once you have the feature |
827 | description, you simply include that into the BSP description as | 795 | description, you simply include that into the BSP description as |
828 | described in the "`BSP Descriptions <#bsp-descriptions>`__" section. | 796 | described in the ":ref:`kernel-dev/advanced:bsp descriptions`" section. |
829 | 797 | ||
830 | You can find information on how to create patches and BSP descriptions | 798 | You can find information on how to create patches and BSP descriptions |
831 | in the "`Patches <#patches>`__" and "`BSP | 799 | in the ":ref:`kernel-dev/advanced:patches`" and |
832 | Descriptions <#bsp-descriptions>`__" sections. | 800 | ":ref:`kernel-dev/advanced:bsp descriptions`" sections. |
833 | 801 | ||
834 | Machine Branches | 802 | Machine Branches |
835 | ---------------- | 803 | ---------------- |
@@ -837,21 +805,19 @@ Machine Branches | |||
837 | When you have multiple machines and architectures to support, or you are | 805 | When you have multiple machines and architectures to support, or you are |
838 | actively working on board support, it is more efficient to create | 806 | actively working on board support, it is more efficient to create |
839 | branches in the repository based on individual machines. Having machine | 807 | branches in the repository based on individual machines. Having machine |
840 | branches allows common source to remain in the "master" branch with any | 808 | branches allows common source to remain in the development branch with any |
841 | features specific to a machine stored in the appropriate machine branch. | 809 | features specific to a machine stored in the appropriate machine branch. |
842 | This organization method frees you from continually reintegrating your | 810 | This organization method frees you from continually reintegrating your |
843 | patches into a feature. | 811 | patches into a feature. |
844 | 812 | ||
845 | Once you have a new branch, you can set up your kernel Metadata to use | 813 | Once you have a new branch, you can set up your kernel Metadata to use |
846 | the branch a couple different ways. In the recipe, you can specify the | 814 | the branch a couple different ways. In the recipe, you can specify the |
847 | new branch as the ``KBRANCH`` to use for the board as follows: | 815 | new branch as the :term:`KBRANCH` to use for the board as follows:: |
848 | :: | ||
849 | 816 | ||
850 | KBRANCH = "mynewbranch" | 817 | KBRANCH = "mynewbranch" |
851 | 818 | ||
852 | Another method is to use the ``branch`` command in the BSP | 819 | Another method is to use the ``branch`` command in the BSP |
853 | description: | 820 | description:: |
854 | :: | ||
855 | 821 | ||
856 | mybsp.scc: | 822 | mybsp.scc: |
857 | define KMACHINE mybsp | 823 | define KMACHINE mybsp |
@@ -865,15 +831,13 @@ description: | |||
865 | 831 | ||
866 | If you find yourself with numerous branches, you might consider using a | 832 | If you find yourself with numerous branches, you might consider using a |
867 | hierarchical branching system similar to what the Yocto Linux Kernel Git | 833 | hierarchical branching system similar to what the Yocto Linux Kernel Git |
868 | repositories use: | 834 | repositories use:: |
869 | :: | ||
870 | 835 | ||
871 | common/kernel_type/machine | 836 | common/kernel_type/machine |
872 | 837 | ||
873 | If you had two kernel types, "standard" and "small" for instance, three | 838 | If you had two kernel types, "standard" and "small" for instance, three |
874 | machines, and common as ``mydir``, the branches in your Git repository | 839 | machines, and common as ``mydir``, the branches in your Git repository |
875 | might look like this: | 840 | might look like this:: |
876 | :: | ||
877 | 841 | ||
878 | mydir/base | 842 | mydir/base |
879 | mydir/standard/base | 843 | mydir/standard/base |
@@ -905,8 +869,7 @@ that have to be regularly updated. The Yocto Project Linux kernel tools | |||
905 | provide for this with the ``git merge`` command. | 869 | provide for this with the ``git merge`` command. |
906 | 870 | ||
907 | To merge a feature branch into a BSP, insert the ``git merge`` command | 871 | To merge a feature branch into a BSP, insert the ``git merge`` command |
908 | after any ``branch`` commands: | 872 | after any ``branch`` commands:: |
909 | :: | ||
910 | 873 | ||
911 | mybsp.scc: | 874 | mybsp.scc: |
912 | define KMACHINE mybsp | 875 | define KMACHINE mybsp |
diff --git a/documentation/kernel-dev/common.rst b/documentation/kernel-dev/common.rst index 58adcc9b70..fda41694dc 100644 --- a/documentation/kernel-dev/common.rst +++ b/documentation/kernel-dev/common.rst | |||
@@ -52,12 +52,11 @@ image and ready to make modifications as described in the | |||
52 | ":ref:`kernel-dev/common:using \`\`devtool\`\` to patch the kernel`" | 52 | ":ref:`kernel-dev/common:using \`\`devtool\`\` to patch the kernel`" |
53 | section: | 53 | section: |
54 | 54 | ||
55 | 1. *Initialize the BitBake Environment:* Before building an extensible | 55 | #. *Initialize the BitBake Environment:* |
56 | SDK, you need to initialize the BitBake build environment by sourcing | 56 | you need to initialize the BitBake build environment by sourcing |
57 | the build environment script (i.e. :ref:`structure-core-script`): | 57 | the build environment script (i.e. :ref:`structure-core-script`):: |
58 | :: | ||
59 | 58 | ||
60 | $ cd ~/poky | 59 | $ cd poky |
61 | $ source oe-init-build-env | 60 | $ source oe-init-build-env |
62 | 61 | ||
63 | .. note:: | 62 | .. note:: |
@@ -67,34 +66,28 @@ section: | |||
67 | (i.e. ``poky``) have been cloned using Git and the local repository is named | 66 | (i.e. ``poky``) have been cloned using Git and the local repository is named |
68 | "poky". | 67 | "poky". |
69 | 68 | ||
70 | 2. *Prepare Your local.conf File:* By default, the | 69 | #. *Prepare Your local.conf File:* By default, the :term:`MACHINE` variable |
71 | :term:`MACHINE` variable is set to | 70 | is set to "qemux86-64", which is fine if you are building for the QEMU |
72 | "qemux86-64", which is fine if you are building for the QEMU emulator | 71 | emulator in 64-bit mode. However, if you are not, you need to set the |
73 | in 64-bit mode. However, if you are not, you need to set the | 72 | :term:`MACHINE` variable appropriately in your ``conf/local.conf`` file |
74 | ``MACHINE`` variable appropriately in your ``conf/local.conf`` file | 73 | found in the :term:`Build Directory` (i.e. ``poky/build`` in this example). |
75 | found in the | ||
76 | :term:`Build Directory` (i.e. | ||
77 | ``~/poky/build`` in this example). | ||
78 | 74 | ||
79 | Also, since you are preparing to work on the kernel image, you need | 75 | Also, since you are preparing to work on the kernel image, you need |
80 | to set the | 76 | to set the :term:`MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS` variable to include |
81 | :term:`MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS` | 77 | kernel modules. |
82 | variable to include kernel modules. | ||
83 | 78 | ||
84 | In this example we wish to build for qemux86 so we must set the | 79 | 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". | 80 | :term:`MACHINE` variable to "qemux86" and also add the "kernel-modules". |
86 | As described we do this by appending to ``conf/local.conf``: | 81 | As described we do this by appending to ``conf/local.conf``:: |
87 | :: | ||
88 | 82 | ||
89 | MACHINE = "qemux86" | 83 | MACHINE = "qemux86" |
90 | MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS += "kernel-modules" | 84 | MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS += "kernel-modules" |
91 | 85 | ||
92 | 3. *Create a Layer for Patches:* You need to create a layer to hold | 86 | #. *Create a Layer for Patches:* You need to create a layer to hold |
93 | patches created for the kernel image. You can use the | 87 | patches created for the kernel image. You can use the |
94 | ``bitbake-layers create-layer`` command as follows: | 88 | ``bitbake-layers create-layer`` command as follows:: |
95 | :: | ||
96 | 89 | ||
97 | $ cd ~/poky/build | 90 | $ cd poky/build |
98 | $ bitbake-layers create-layer ../../meta-mylayer | 91 | $ bitbake-layers create-layer ../../meta-mylayer |
99 | NOTE: Starting bitbake server... | 92 | NOTE: Starting bitbake server... |
100 | Add your new layer with 'bitbake-layers add-layer ../../meta-mylayer' | 93 | Add your new layer with 'bitbake-layers add-layer ../../meta-mylayer' |
@@ -104,92 +97,29 @@ section: | |||
104 | 97 | ||
105 | For background information on working with common and BSP layers, | 98 | For background information on working with common and BSP layers, |
106 | see the | 99 | see the |
107 | ":ref:`dev-manual/common-tasks:understanding and creating layers`" | 100 | ":ref:`dev-manual/layers:understanding and creating layers`" |
108 | section in the Yocto Project Development Tasks Manual and the | 101 | section in the Yocto Project Development Tasks Manual and the |
109 | ":ref:`bsp-guide/bsp:bsp layers`" section in the Yocto Project Board | 102 | ":ref:`bsp-guide/bsp:bsp layers`" section in the Yocto Project Board |
110 | Support (BSP) Developer's Guide, respectively. For information on how to | 103 | 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, | 104 | use the ``bitbake-layers create-layer`` command to quickly set up a layer, |
112 | see the | 105 | see the |
113 | ":ref:`dev-manual/common-tasks:creating a general layer using the \`\`bitbake-layers\`\` script`" | 106 | ":ref:`dev-manual/layers:creating a general layer using the \`\`bitbake-layers\`\` script`" |
114 | section in the Yocto Project Development Tasks Manual. | 107 | section in the Yocto Project Development Tasks Manual. |
115 | 108 | ||
116 | 4. *Inform the BitBake Build Environment About Your Layer:* As directed | 109 | #. *Inform the BitBake Build Environment About Your Layer:* As directed |
117 | when you created your layer, you need to add the layer to the | 110 | when you created your layer, you need to add the layer to the |
118 | :term:`BBLAYERS` variable in the | 111 | :term:`BBLAYERS` variable in the |
119 | ``bblayers.conf`` file as follows: | 112 | ``bblayers.conf`` file as follows:: |
120 | :: | ||
121 | 113 | ||
122 | $ cd ~/poky/build | 114 | $ cd poky/build |
123 | $ bitbake-layers add-layer ../../meta-mylayer | 115 | $ bitbake-layers add-layer ../../meta-mylayer |
124 | NOTE: Starting bitbake server... | 116 | NOTE: Starting bitbake server... |
125 | $ | 117 | $ |
126 | 118 | ||
127 | 5. *Build the Extensible SDK:* Use BitBake to build the extensible SDK | 119 | #. *Build the Clean Image:* The final step in preparing to work on the |
128 | specifically for use with images to be run using QEMU: | 120 | kernel is to build an initial image using ``bitbake``:: |
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 | 121 | ||
192 | $ devtool build-image | 122 | $ bitbake core-image-minimal |
193 | Parsing recipes: 100% |##########################################| Time: 0:00:05 | 123 | 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. | 124 | 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 | 125 | WARNING: No packages to add, building image core-image-minimal unmodified |
@@ -201,7 +131,6 @@ section: | |||
201 | NOTE: Executing SetScene Tasks | 131 | NOTE: Executing SetScene Tasks |
202 | NOTE: Executing RunQueue Tasks | 132 | NOTE: Executing RunQueue Tasks |
203 | NOTE: Tasks Summary: Attempted 2866 tasks of which 2604 didn't need to be rerun and all succeeded. | 133 | 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 | 134 | ||
206 | If you were | 135 | If you were |
207 | building for actual hardware and not for emulation, you could flash | 136 | building for actual hardware and not for emulation, you could flash |
@@ -211,7 +140,7 @@ section: | |||
211 | Wiki page. | 140 | Wiki page. |
212 | 141 | ||
213 | At this point you have set up to start making modifications to the | 142 | 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 | 143 | kernel. For a continued example, see the |
215 | ":ref:`kernel-dev/common:using \`\`devtool\`\` to patch the kernel`" | 144 | ":ref:`kernel-dev/common:using \`\`devtool\`\` to patch the kernel`" |
216 | section. | 145 | section. |
217 | 146 | ||
@@ -229,7 +158,7 @@ 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`" | 158 | source as described in the ":ref:`kernel-dev/common:using traditional kernel development to patch the kernel`" |
230 | section: | 159 | section: |
231 | 160 | ||
232 | 1. *Initialize the BitBake Environment:* Before you can do anything | 161 | #. *Initialize the BitBake Environment:* Before you can do anything |
233 | using BitBake, you need to initialize the BitBake build environment | 162 | using BitBake, you need to initialize the BitBake build environment |
234 | by sourcing the build environment script (i.e. | 163 | by sourcing the build environment script (i.e. |
235 | :ref:`structure-core-script`). | 164 | :ref:`structure-core-script`). |
@@ -237,10 +166,9 @@ section: | |||
237 | checked out for ``poky`` is the Yocto Project &DISTRO_NAME; branch. If | 166 | checked out for ``poky`` is the Yocto Project &DISTRO_NAME; branch. If |
238 | you need to checkout out the &DISTRO_NAME; branch, see the | 167 | you need to checkout out the &DISTRO_NAME; branch, see the |
239 | ":ref:`dev-manual/start:checking out by branch in poky`" | 168 | ":ref:`dev-manual/start:checking out by branch in poky`" |
240 | section in the Yocto Project Development Tasks Manual. | 169 | section in the Yocto Project Development Tasks Manual:: |
241 | :: | ||
242 | 170 | ||
243 | $ cd ~/poky | 171 | $ cd poky |
244 | $ git branch | 172 | $ git branch |
245 | master | 173 | master |
246 | * &DISTRO_NAME_NO_CAP; | 174 | * &DISTRO_NAME_NO_CAP; |
@@ -253,14 +181,11 @@ section: | |||
253 | (i.e. ``poky``) have been cloned using Git and the local repository is named | 181 | (i.e. ``poky``) have been cloned using Git and the local repository is named |
254 | "poky". | 182 | "poky". |
255 | 183 | ||
256 | 2. *Prepare Your local.conf File:* By default, the | 184 | #. *Prepare Your local.conf File:* By default, the :term:`MACHINE` variable is |
257 | :term:`MACHINE` variable is set to | 185 | set to "qemux86-64", which is fine if you are building for the QEMU emulator |
258 | "qemux86-64", which is fine if you are building for the QEMU emulator | 186 | in 64-bit mode. However, if you are not, you need to set the :term:`MACHINE` |
259 | in 64-bit mode. However, if you are not, you need to set the | 187 | variable appropriately in your ``conf/local.conf`` file found in the |
260 | ``MACHINE`` variable appropriately in your ``conf/local.conf`` file | 188 | :term:`Build Directory` (i.e. ``poky/build`` in this example). |
261 | found in the | ||
262 | :term:`Build Directory` (i.e. | ||
263 | ``~/poky/build`` in this example). | ||
264 | 189 | ||
265 | Also, since you are preparing to work on the kernel image, you need | 190 | Also, since you are preparing to work on the kernel image, you need |
266 | to set the | 191 | to set the |
@@ -268,19 +193,17 @@ section: | |||
268 | variable to include kernel modules. | 193 | variable to include kernel modules. |
269 | 194 | ||
270 | In this example we wish to build for qemux86 so we must set the | 195 | 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". | 196 | :term:`MACHINE` variable to "qemux86" and also add the "kernel-modules". |
272 | As described we do this by appending to ``conf/local.conf``: | 197 | As described we do this by appending to ``conf/local.conf``:: |
273 | :: | ||
274 | 198 | ||
275 | MACHINE = "qemux86" | 199 | MACHINE = "qemux86" |
276 | MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS += "kernel-modules" | 200 | MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS += "kernel-modules" |
277 | 201 | ||
278 | 3. *Create a Layer for Patches:* You need to create a layer to hold | 202 | #. *Create a Layer for Patches:* You need to create a layer to hold |
279 | patches created for the kernel image. You can use the | 203 | patches created for the kernel image. You can use the |
280 | ``bitbake-layers create-layer`` command as follows: | 204 | ``bitbake-layers create-layer`` command as follows:: |
281 | :: | ||
282 | 205 | ||
283 | $ cd ~/poky/build | 206 | $ cd poky/build |
284 | $ bitbake-layers create-layer ../../meta-mylayer | 207 | $ bitbake-layers create-layer ../../meta-mylayer |
285 | NOTE: Starting bitbake server... | 208 | NOTE: Starting bitbake server... |
286 | Add your new layer with 'bitbake-layers add-layer ../../meta-mylayer' | 209 | Add your new layer with 'bitbake-layers add-layer ../../meta-mylayer' |
@@ -289,27 +212,26 @@ section: | |||
289 | 212 | ||
290 | For background information on working with common and BSP layers, | 213 | For background information on working with common and BSP layers, |
291 | see the | 214 | see the |
292 | ":ref:`dev-manual/common-tasks:understanding and creating layers`" | 215 | ":ref:`dev-manual/layers:understanding and creating layers`" |
293 | section in the Yocto Project Development Tasks Manual and the | 216 | section in the Yocto Project Development Tasks Manual and the |
294 | ":ref:`bsp-guide/bsp:bsp layers`" section in the Yocto Project Board | 217 | ":ref:`bsp-guide/bsp:bsp layers`" section in the Yocto Project Board |
295 | Support (BSP) Developer's Guide, respectively. For information on how to | 218 | 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, | 219 | use the ``bitbake-layers create-layer`` command to quickly set up a layer, |
297 | see the | 220 | see the |
298 | ":ref:`dev-manual/common-tasks:creating a general layer using the \`\`bitbake-layers\`\` script`" | 221 | ":ref:`dev-manual/layers:creating a general layer using the \`\`bitbake-layers\`\` script`" |
299 | section in the Yocto Project Development Tasks Manual. | 222 | section in the Yocto Project Development Tasks Manual. |
300 | 223 | ||
301 | 4. *Inform the BitBake Build Environment About Your Layer:* As directed | 224 | #. *Inform the BitBake Build Environment About Your Layer:* As directed |
302 | when you created your layer, you need to add the layer to the | 225 | when you created your layer, you need to add the layer to the |
303 | :term:`BBLAYERS` variable in the | 226 | :term:`BBLAYERS` variable in the |
304 | ``bblayers.conf`` file as follows: | 227 | ``bblayers.conf`` file as follows:: |
305 | :: | ||
306 | 228 | ||
307 | $ cd ~/poky/build | 229 | $ cd poky/build |
308 | $ bitbake-layers add-layer ../../meta-mylayer | 230 | $ bitbake-layers add-layer ../../meta-mylayer |
309 | NOTE: Starting bitbake server ... | 231 | NOTE: Starting bitbake server ... |
310 | $ | 232 | $ |
311 | 233 | ||
312 | 5. *Create a Local Copy of the Kernel Git Repository:* You can find Git | 234 | #. *Create a Local Copy of the Kernel Git Repository:* You can find Git |
313 | repositories of supported Yocto Project kernels organized under | 235 | repositories of supported Yocto Project kernels organized under |
314 | "Yocto Linux Kernel" in the Yocto Project Source Repositories at | 236 | "Yocto Linux Kernel" in the Yocto Project Source Repositories at |
315 | :yocto_git:`/`. | 237 | :yocto_git:`/`. |
@@ -321,16 +243,7 @@ section: | |||
321 | ``standard/base`` branch. | 243 | ``standard/base`` branch. |
322 | 244 | ||
323 | The following commands show how to create a local copy of the | 245 | 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. | 246 | ``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 | 247 | ||
335 | $ cd ~ | 248 | $ cd ~ |
336 | $ git clone git://git.yoctoproject.org/linux-yocto-4.12 --branch standard/base | 249 | $ git clone git://git.yoctoproject.org/linux-yocto-4.12 --branch standard/base |
@@ -342,7 +255,14 @@ section: | |||
342 | Resolving deltas: 100% (5152604/5152604), done. Checking connectivity... done. | 255 | Resolving deltas: 100% (5152604/5152604), done. Checking connectivity... done. |
343 | Checking out files: 100% (59846/59846), done. | 256 | Checking out files: 100% (59846/59846), done. |
344 | 257 | ||
345 | 6. *Create a Local Copy of the Kernel Cache Git Repository:* For | 258 | .. note:: |
259 | |||
260 | The ``linux-yocto-4.12`` kernel can be used with the Yocto Project 2.4 | ||
261 | release and forward. | ||
262 | You cannot use the ``linux-yocto-4.12`` kernel with releases prior to | ||
263 | Yocto Project 2.4. | ||
264 | |||
265 | #. *Create a Local Copy of the Kernel Cache Git Repository:* For | ||
346 | simplicity, it is recommended that you create your copy of the kernel | 266 | simplicity, it is recommended that you create your copy of the kernel |
347 | cache Git repository outside of the | 267 | cache Git repository outside of the |
348 | :term:`Source Directory`, which is | 268 | :term:`Source Directory`, which is |
@@ -350,8 +270,7 @@ section: | |||
350 | the ``yocto-4.12`` branch. | 270 | the ``yocto-4.12`` branch. |
351 | 271 | ||
352 | The following commands show how to create a local copy of the | 272 | The following commands show how to create a local copy of the |
353 | ``yocto-kernel-cache`` and be in the ``yocto-4.12`` branch: | 273 | ``yocto-kernel-cache`` and switch to the ``yocto-4.12`` branch:: |
354 | :: | ||
355 | 274 | ||
356 | $ cd ~ | 275 | $ cd ~ |
357 | $ git clone git://git.yoctoproject.org/yocto-kernel-cache --branch yocto-4.12 | 276 | $ git clone git://git.yoctoproject.org/yocto-kernel-cache --branch yocto-4.12 |
@@ -365,8 +284,7 @@ section: | |||
365 | 284 | ||
366 | At this point, you are ready to start making modifications to the kernel | 285 | At this point, you are ready to start making modifications to the kernel |
367 | using traditional kernel development steps. For a continued example, see | 286 | using traditional kernel development steps. For a continued example, see |
368 | the "`Using Traditional Kernel Development to Patch the | 287 | the ":ref:`kernel-dev/common:using traditional kernel development to patch the kernel`" |
369 | Kernel <#using-traditional-kernel-development-to-patch-the-kernel>`__" | ||
370 | section. | 288 | section. |
371 | 289 | ||
372 | Creating and Preparing a Layer | 290 | Creating and Preparing a Layer |
@@ -378,7 +296,7 @@ layer contains its own :term:`BitBake` | |||
378 | append files (``.bbappend``) and provides a convenient mechanism to | 296 | append files (``.bbappend``) and provides a convenient mechanism to |
379 | create your own recipe files (``.bb``) as well as store and use kernel | 297 | 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 | 298 | patch files. For background information on working with layers, see the |
381 | ":ref:`dev-manual/common-tasks:understanding and creating layers`" | 299 | ":ref:`dev-manual/layers:understanding and creating layers`" |
382 | section in the Yocto Project Development Tasks Manual. | 300 | section in the Yocto Project Development Tasks Manual. |
383 | 301 | ||
384 | .. note:: | 302 | .. note:: |
@@ -386,7 +304,7 @@ section in the Yocto Project Development Tasks Manual. | |||
386 | The Yocto Project comes with many tools that simplify tasks you need | 304 | The Yocto Project comes with many tools that simplify tasks you need |
387 | to perform. One such tool is the ``bitbake-layers create-layer`` | 305 | to perform. One such tool is the ``bitbake-layers create-layer`` |
388 | command, which simplifies creating a new layer. See the | 306 | command, which simplifies creating a new layer. See the |
389 | ":ref:`dev-manual/common-tasks:creating a general layer using the \`\`bitbake-layers\`\` script`" | 307 | ":ref:`dev-manual/layers:creating a general layer using the \`\`bitbake-layers\`\` script`" |
390 | section in the Yocto Project Development Tasks Manual for | 308 | section in the Yocto Project Development Tasks Manual for |
391 | information on how to use this script to quick set up a new layer. | 309 | information on how to use this script to quick set up a new layer. |
392 | 310 | ||
@@ -395,24 +313,17 @@ 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 | 313 | tools. These steps assume creation of a layer named ``mylayer`` in your |
396 | home directory: | 314 | home directory: |
397 | 315 | ||
398 | 1. *Create Structure*: Create the layer's structure: | 316 | #. *Create Structure*: Create the layer's structure:: |
399 | :: | ||
400 | 317 | ||
401 | $ cd $HOME | 318 | $ mkdir -p meta-mylayer/conf meta-mylayer/recipes-kernel/linux/linux-yocto |
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 | 319 | ||
408 | The ``conf`` directory holds your configuration files, while the | 320 | The ``conf`` directory holds your configuration files, while the |
409 | ``recipes-kernel`` directory holds your append file and eventual | 321 | ``recipes-kernel`` directory holds your append file and eventual |
410 | patch files. | 322 | patch files. |
411 | 323 | ||
412 | 2. *Create the Layer Configuration File*: Move to the | 324 | #. *Create the Layer Configuration File*: Move to the |
413 | ``meta-mylayer/conf`` directory and create the ``layer.conf`` file as | 325 | ``meta-mylayer/conf`` directory and create the ``layer.conf`` file as |
414 | follows: | 326 | follows:: |
415 | :: | ||
416 | 327 | ||
417 | # We have a conf and classes directory, add to BBPATH | 328 | # We have a conf and classes directory, add to BBPATH |
418 | BBPATH .= ":${LAYERDIR}" | 329 | BBPATH .= ":${LAYERDIR}" |
@@ -427,23 +338,22 @@ home directory: | |||
427 | 338 | ||
428 | Notice ``mylayer`` as part of the last three statements. | 339 | Notice ``mylayer`` as part of the last three statements. |
429 | 340 | ||
430 | 3. *Create the Kernel Recipe Append File*: Move to the | 341 | #. *Create the Kernel Recipe Append File*: Move to the |
431 | ``meta-mylayer/recipes-kernel/linux`` directory and create the | 342 | ``meta-mylayer/recipes-kernel/linux`` directory and create the |
432 | kernel's append file. This example uses the ``linux-yocto-4.12`` | 343 | kernel's append file. This example uses the ``linux-yocto-4.12`` |
433 | kernel. Thus, the name of the append file is | 344 | kernel. Thus, the name of the append file is |
434 | ``linux-yocto_4.12.bbappend``: | 345 | ``linux-yocto_4.12.bbappend``:: |
435 | :: | ||
436 | 346 | ||
437 | FILESEXTRAPATHS_prepend := "${THISDIR}/${PN}:" | 347 | FILESEXTRAPATHS:prepend := "${THISDIR}/${PN}:" |
438 | 348 | ||
439 | SRC_URI_append = " file://patch-file-one.patch" | 349 | SRC_URI += "file://patch-file-one.patch" |
440 | SRC_URI_append = " file://patch-file-two.patch" | 350 | SRC_URI += "file://patch-file-two.patch" |
441 | SRC_URI_append = " file://patch-file-three.patch" | 351 | SRC_URI += "file://patch-file-three.patch" |
442 | 352 | ||
443 | The :term:`FILESEXTRAPATHS` and :term:`SRC_URI` statements | 353 | The :term:`FILESEXTRAPATHS` and :term:`SRC_URI` statements |
444 | enable the OpenEmbedded build system to find patch files. For more | 354 | enable the OpenEmbedded build system to find patch files. For more |
445 | information on using append files, see the | 355 | information on using append files, see the |
446 | ":ref:`dev-manual/common-tasks:using .bbappend files in your layer`" | 356 | ":ref:`dev-manual/layers:appending other layers metadata with your layer`" |
447 | section in the Yocto Project Development Tasks Manual. | 357 | section in the Yocto Project Development Tasks Manual. |
448 | 358 | ||
449 | Modifying an Existing Recipe | 359 | Modifying an Existing Recipe |
@@ -464,8 +374,8 @@ Modifying an existing recipe can consist of the following: | |||
464 | - :ref:`kernel-dev/common:changing the configuration` | 374 | - :ref:`kernel-dev/common:changing the configuration` |
465 | 375 | ||
466 | Before modifying an existing recipe, be sure that you have created a | 376 | 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 | 377 | minimal, custom layer from which you can work. See the |
468 | Preparing a Layer <#creating-and-preparing-a-layer>`__" section for | 378 | ":ref:`kernel-dev/common:creating and preparing a layer`" section for |
469 | information. | 379 | information. |
470 | 380 | ||
471 | Creating the Append File | 381 | Creating the Append File |
@@ -473,29 +383,27 @@ Creating the Append File | |||
473 | 383 | ||
474 | You create this file in your custom layer. You also name it accordingly | 384 | 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 | 385 | 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, | 386 | modifying the ``meta/recipes-kernel/linux/linux-yocto_6.1.bb`` recipe, |
477 | the append file will typically be located as follows within your custom | 387 | the append file will typically be located as follows within your custom |
478 | layer: | 388 | layer: |
479 | 389 | ||
480 | .. code-block:: none | 390 | .. code-block:: none |
481 | 391 | ||
482 | your-layer/recipes-kernel/linux/linux-yocto_4.12.bbappend | 392 | your-layer/recipes-kernel/linux/linux-yocto_6.1.bbappend |
483 | 393 | ||
484 | The append file should initially extend the | 394 | The append file should initially extend the |
485 | :term:`FILESPATH` search path by | 395 | :term:`FILESPATH` search path by |
486 | prepending the directory that contains your files to the | 396 | prepending the directory that contains your files to the |
487 | :term:`FILESEXTRAPATHS` | 397 | :term:`FILESEXTRAPATHS` |
488 | variable as follows: | 398 | variable as follows:: |
489 | :: | ||
490 | 399 | ||
491 | FILESEXTRAPATHS_prepend := "${THISDIR}/${PN}:" | 400 | FILESEXTRAPATHS:prepend := "${THISDIR}/${PN}:" |
492 | 401 | ||
493 | The path ``${``\ :term:`THISDIR`\ ``}/${``\ :term:`PN`\ ``}`` | 402 | The path ``${``\ :term:`THISDIR`\ ``}/${``\ :term:`PN`\ ``}`` |
494 | expands to "linux-yocto" in the current directory for this example. If | 403 | 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 | 404 | 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 | 405 | extended :term:`FILESPATH` as described above, you must place the files in |
497 | your layer in the following area: | 406 | your layer in the following area:: |
498 | :: | ||
499 | 407 | ||
500 | your-layer/recipes-kernel/linux/linux-yocto/ | 408 | your-layer/recipes-kernel/linux/linux-yocto/ |
501 | 409 | ||
@@ -509,36 +417,31 @@ As an example, consider the following append file used by the BSPs in | |||
509 | 417 | ||
510 | .. code-block:: none | 418 | .. code-block:: none |
511 | 419 | ||
512 | meta-yocto-bsp/recipes-kernel/linux/linux-yocto_4.12.bbappend | 420 | meta-yocto-bsp/recipes-kernel/linux/linux-yocto_6.1.bbappend |
513 | 421 | ||
514 | The following listing shows the file. Be aware that the actual commit ID | 422 | Here are the contents of this file. Be aware that the actual commit ID |
515 | strings in this example listing might be different than the actual | 423 | strings in this example listing might be different than the actual |
516 | strings in the file from the ``meta-yocto-bsp`` layer upstream. | 424 | 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 | 425 | ||
522 | KMACHINE_genericx86 ?= "common-pc" | 426 | KBRANCH:genericx86 = "v6.1/standard/base" |
523 | KMACHINE_genericx86-64 ?= "common-pc-64" | 427 | KBRANCH:genericx86-64 = "v6.1/standard/base" |
524 | KBRANCH_edgerouter = "standard/edgerouter" | 428 | KBRANCH:beaglebone-yocto = "v6.1/standard/beaglebone" |
525 | KBRANCH_beaglebone = "standard/beaglebone" | ||
526 | 429 | ||
527 | SRCREV_machine_genericx86 ?= "d09f2ce584d60ecb7890550c22a80c48b83c2e19" | 430 | KMACHINE:genericx86 ?= "common-pc" |
528 | SRCREV_machine_genericx86-64 ?= "d09f2ce584d60ecb7890550c22a80c48b83c2e19" | 431 | KMACHINE:genericx86-64 ?= "common-pc-64" |
529 | SRCREV_machine_edgerouter ?= "b5c8cfda2dfe296410d51e131289fb09c69e1e7d" | 432 | KMACHINE:beaglebone-yocto ?= "beaglebone" |
530 | SRCREV_machine_beaglebone ?= "b5c8cfda2dfe296410d51e131289fb09c69e1e7d" | ||
531 | 433 | ||
434 | SRCREV_machine:genericx86 ?= "6ec439b4b456ce929c4c07fe457b5d6a4b468e86" | ||
435 | SRCREV_machine:genericx86-64 ?= "6ec439b4b456ce929c4c07fe457b5d6a4b468e86" | ||
436 | SRCREV_machine:beaglebone-yocto ?= "423e1996694b61fbfc8ec3bf062fc6461d64fde1" | ||
532 | 437 | ||
533 | COMPATIBLE_MACHINE_genericx86 = "genericx86" | 438 | COMPATIBLE_MACHINE:genericx86 = "genericx86" |
534 | COMPATIBLE_MACHINE_genericx86-64 = "genericx86-64" | 439 | COMPATIBLE_MACHINE:genericx86-64 = "genericx86-64" |
535 | COMPATIBLE_MACHINE_edgerouter = "edgerouter" | 440 | COMPATIBLE_MACHINE:beaglebone-yocto = "beaglebone-yocto" |
536 | COMPATIBLE_MACHINE_beaglebone = "beaglebone" | ||
537 | 441 | ||
538 | LINUX_VERSION_genericx86 = "4.12.7" | 442 | LINUX_VERSION:genericx86 = "6.1.30" |
539 | LINUX_VERSION_genericx86-64 = "4.12.7" | 443 | LINUX_VERSION:genericx86-64 = "6.1.30" |
540 | LINUX_VERSION_edgerouter = "4.12.10" | 444 | LINUX_VERSION:beaglebone-yocto = "6.1.20" |
541 | LINUX_VERSION_beaglebone = "4.12.10" | ||
542 | 445 | ||
543 | This append file | 446 | This append file |
544 | contains statements used to support several BSPs that ship with the | 447 | contains statements used to support several BSPs that ship with the |
@@ -573,19 +476,17 @@ the append file. | |||
573 | 476 | ||
574 | For example, suppose you had some configuration options in a file called | 477 | For example, suppose you had some configuration options in a file called |
575 | ``network_configs.cfg``. You can place that file inside a directory | 478 | ``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 | 479 | named ``linux-yocto`` and then add a :term:`SRC_URI` statement such as the |
577 | following to the append file. When the OpenEmbedded build system builds | 480 | following to the append file. When the OpenEmbedded build system builds |
578 | the kernel, the configuration options are picked up and applied. | 481 | the kernel, the configuration options are picked up and applied:: |
579 | :: | ||
580 | 482 | ||
581 | SRC_URI += "file://network_configs.cfg" | 483 | SRC_URI += "file://network_configs.cfg" |
582 | 484 | ||
583 | To group related configurations into multiple files, you perform a | 485 | To group related configurations into multiple files, you perform a |
584 | similar procedure. Here is an example that groups separate | 486 | similar procedure. Here is an example that groups separate |
585 | configurations specifically for Ethernet and graphics into their own | 487 | configurations specifically for Ethernet and graphics into their own |
586 | files and adds the configurations by using a ``SRC_URI`` statement like | 488 | files and adds the configurations by using a :term:`SRC_URI` statement like |
587 | the following in your append file: | 489 | the following in your append file:: |
588 | :: | ||
589 | 490 | ||
590 | SRC_URI += "file://myconfig.cfg \ | 491 | SRC_URI += "file://myconfig.cfg \ |
591 | file://eth.cfg \ | 492 | file://eth.cfg \ |
@@ -599,7 +500,7 @@ recipe is processed. | |||
599 | 500 | ||
600 | .. note:: | 501 | .. note:: |
601 | 502 | ||
602 | Other methods exist to accomplish grouping and defining configuration | 503 | There are other ways of grouping and defining configuration |
603 | options. For example, if you are working with a local clone of the | 504 | options. For example, if you are working with a local clone of the |
604 | kernel repository, you could checkout the kernel's ``meta`` branch, | 505 | kernel repository, you could checkout the kernel's ``meta`` branch, |
605 | make your changes, and then push the changes to the local bare clone | 506 | make your changes, and then push the changes to the local bare clone |
@@ -609,9 +510,9 @@ recipe is processed. | |||
609 | added to the Yocto Project. | 510 | added to the Yocto Project. |
610 | 511 | ||
611 | In general, however, the Yocto Project maintainers take care of | 512 | In general, however, the Yocto Project maintainers take care of |
612 | moving the ``SRC_URI``-specified configuration options to the | 513 | moving the :term:`SRC_URI`-specified configuration options to the |
613 | kernel's ``meta`` branch. Not only is it easier for BSP developers to | 514 | kernel's ``meta`` branch. Not only is it easier for BSP developers |
614 | not have to worry about putting those configurations in the branch, | 515 | not to have to put those configurations in the branch, |
615 | but having the maintainers do it allows them to apply 'global' | 516 | but having the maintainers do it allows them to apply 'global' |
616 | knowledge about the kinds of common configuration options multiple | 517 | knowledge about the kinds of common configuration options multiple |
617 | BSPs in the tree are typically using. This allows for promotion of | 518 | BSPs in the tree are typically using. This allows for promotion of |
@@ -629,8 +530,7 @@ reference them in :term:`SRC_URI` | |||
629 | statements. | 530 | statements. |
630 | 531 | ||
631 | For example, you can apply a three-patch series by adding the following | 532 | For example, you can apply a three-patch series by adding the following |
632 | lines to your linux-yocto ``.bbappend`` file in your layer: | 533 | lines to your linux-yocto ``.bbappend`` file in your layer:: |
633 | :: | ||
634 | 534 | ||
635 | SRC_URI += "file://0001-first-change.patch" | 535 | SRC_URI += "file://0001-first-change.patch" |
636 | SRC_URI += "file://0002-second-change.patch" | 536 | SRC_URI += "file://0002-second-change.patch" |
@@ -660,19 +560,27 @@ 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 | 560 | to use for the configuration, as before, copy that file to the |
661 | appropriate ``${PN}`` directory in your layer's ``recipes-kernel/linux`` | 561 | appropriate ``${PN}`` directory in your layer's ``recipes-kernel/linux`` |
662 | directory, and rename the copied file to "defconfig". Then, add the | 562 | directory, and rename the copied file to "defconfig". Then, add the |
663 | following lines to the linux-yocto ``.bbappend`` file in your layer: | 563 | following lines to the linux-yocto ``.bbappend`` file in your layer:: |
664 | :: | ||
665 | 564 | ||
666 | FILESEXTRAPATHS_prepend := "${THISDIR}/${PN}:" | 565 | FILESEXTRAPATHS:prepend := "${THISDIR}/${PN}:" |
667 | SRC_URI += "file://defconfig" | 566 | SRC_URI += "file://defconfig" |
668 | 567 | ||
669 | The ``SRC_URI`` tells the build system how to search | 568 | The :term:`SRC_URI` tells the build system how to search |
670 | for the file, while the | 569 | for the file, while the |
671 | :term:`FILESEXTRAPATHS` | 570 | :term:`FILESEXTRAPATHS` |
672 | extends the :term:`FILESPATH` | 571 | extends the :term:`FILESPATH` |
673 | variable (search directories) to include the ``${PN}`` directory you | 572 | variable (search directories) to include the ``${PN}`` directory you |
674 | created to hold the configuration changes. | 573 | created to hold the configuration changes. |
675 | 574 | ||
575 | You can also use a regular ``defconfig`` file, as generated by the | ||
576 | :ref:`ref-tasks-savedefconfig` | ||
577 | task instead of a complete ``.config`` file. This only specifies the | ||
578 | non-default configuration values. You need to additionally set | ||
579 | :term:`KCONFIG_MODE` | ||
580 | in the linux-yocto ``.bbappend`` file in your layer:: | ||
581 | |||
582 | KCONFIG_MODE = "alldefconfig" | ||
583 | |||
676 | .. note:: | 584 | .. note:: |
677 | 585 | ||
678 | The build system applies the configurations from the ``defconfig`` | 586 | The build system applies the configurations from the ``defconfig`` |
@@ -687,8 +595,7 @@ Generally speaking, the preferred approach is to determine the | |||
687 | incremental change you want to make and add that as a configuration | 595 | 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 | 596 | 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 | 597 | console, create a file named ``8250.cfg`` in the ``${PN}`` directory |
690 | with the following content (without indentation): | 598 | with the following content (without indentation):: |
691 | :: | ||
692 | 599 | ||
693 | CONFIG_SERIAL_8250=y | 600 | CONFIG_SERIAL_8250=y |
694 | CONFIG_SERIAL_8250_CONSOLE=y | 601 | CONFIG_SERIAL_8250_CONSOLE=y |
@@ -699,11 +606,10 @@ with the following content (without indentation): | |||
699 | CONFIG_SERIAL_CORE_CONSOLE=y | 606 | CONFIG_SERIAL_CORE_CONSOLE=y |
700 | 607 | ||
701 | Next, include this | 608 | Next, include this |
702 | configuration fragment and extend the ``FILESPATH`` variable in your | 609 | configuration fragment and extend the :term:`FILESPATH` variable in your |
703 | ``.bbappend`` file: | 610 | ``.bbappend`` file:: |
704 | :: | ||
705 | 611 | ||
706 | FILESEXTRAPATHS_prepend := "${THISDIR}/${PN}:" | 612 | FILESEXTRAPATHS:prepend := "${THISDIR}/${PN}:" |
707 | SRC_URI += "file://8250.cfg" | 613 | SRC_URI += "file://8250.cfg" |
708 | 614 | ||
709 | The next time you run BitBake to build the | 615 | The next time you run BitBake to build the |
@@ -711,7 +617,7 @@ Linux kernel, BitBake detects the change in the recipe and fetches and | |||
711 | applies the new configuration before building the kernel. | 617 | applies the new configuration before building the kernel. |
712 | 618 | ||
713 | For a detailed example showing how to configure the kernel, see the | 619 | For a detailed example showing how to configure the kernel, see the |
714 | "`Configuring the Kernel <#configuring-the-kernel>`__" section. | 620 | ":ref:`kernel-dev/common:configuring the kernel`" section. |
715 | 621 | ||
716 | Using an "In-Tree"Â Â ``defconfig`` File | 622 | Using an "In-Tree"Â Â ``defconfig`` File |
717 | -------------------------------------- | 623 | -------------------------------------- |
@@ -720,8 +626,7 @@ It might be desirable to have kernel configuration fragment support | |||
720 | through a ``defconfig`` file that is pulled from the kernel source tree | 626 | through a ``defconfig`` file that is pulled from the kernel source tree |
721 | for the configured machine. By default, the OpenEmbedded build system | 627 | for the configured machine. By default, the OpenEmbedded build system |
722 | looks for ``defconfig`` files in the layer used for Metadata, which is | 628 | looks for ``defconfig`` files in the layer used for Metadata, which is |
723 | "out-of-tree", and then configures them using the following: | 629 | "out-of-tree", and then configures them using the following:: |
724 | :: | ||
725 | 630 | ||
726 | SRC_URI += "file://defconfig" | 631 | SRC_URI += "file://defconfig" |
727 | 632 | ||
@@ -734,26 +639,24 @@ append files, you can direct the OpenEmbedded build system to use a | |||
734 | ``defconfig`` file that is "in-tree". | 639 | ``defconfig`` file that is "in-tree". |
735 | 640 | ||
736 | To specify an "in-tree" ``defconfig`` file, use the following statement | 641 | To specify an "in-tree" ``defconfig`` file, use the following statement |
737 | form: | 642 | form:: |
738 | :: | ||
739 | 643 | ||
740 | KBUILD_DEFCONFIG_KMACHINE ?= "defconfig_file" | 644 | KBUILD_DEFCONFIG:<machine> ?= "defconfig_file" |
741 | 645 | ||
742 | Here is an example | 646 | Here is an example that assigns the :term:`KBUILD_DEFCONFIG` variable utilizing |
743 | that assigns the ``KBUILD_DEFCONFIG`` variable based on "raspberrypi2" | 647 | an override for the "raspberrypi2" :term:`MACHINE` and provides the path to the |
744 | and provides the path to the "in-tree" ``defconfig`` file to be used for | 648 | "in-tree" ``defconfig`` file to be used for a Raspberry Pi 2, which is based on |
745 | a Raspberry Pi 2, which is based on the Broadcom 2708/2709 chipset: | 649 | the Broadcom 2708/2709 chipset:: |
746 | :: | ||
747 | 650 | ||
748 | KBUILD_DEFCONFIG_raspberrypi2 ?= "bcm2709_defconfig" | 651 | KBUILD_DEFCONFIG:raspberrypi2 ?= "bcm2709_defconfig" |
749 | 652 | ||
750 | Aside from modifying your kernel recipe and providing your own | 653 | Aside from modifying your kernel recipe and providing your own |
751 | ``defconfig`` file, you need to be sure no files or statements set | 654 | ``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. | 655 | :term:`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 | 656 | a kernel's ``linux-``\ `machine`\ ``.inc`` file). In other words, if the |
754 | build system detects a statement that identifies an "out-of-tree" | 657 | build system detects a statement that identifies an "out-of-tree" |
755 | ``defconfig`` file, that statement will override your | 658 | ``defconfig`` file, that statement will override your |
756 | ``KBUILD_DEFCONFIG`` variable. | 659 | :term:`KBUILD_DEFCONFIG` variable. |
757 | 660 | ||
758 | See the | 661 | See the |
759 | :term:`KBUILD_DEFCONFIG` | 662 | :term:`KBUILD_DEFCONFIG` |
@@ -763,7 +666,7 @@ Using ``devtool`` to Patch the Kernel | |||
763 | ===================================== | 666 | ===================================== |
764 | 667 | ||
765 | The steps in this procedure show you how you can patch the kernel using | 668 | The steps in this procedure show you how you can patch the kernel using |
766 | the extensible SDK and ``devtool``. | 669 | ``devtool``. |
767 | 670 | ||
768 | .. note:: | 671 | .. note:: |
769 | 672 | ||
@@ -784,9 +687,8 @@ 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 | 687 | 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. | 688 | the ":ref:`kernel-dev/common:getting ready to develop using \`\`devtool\`\``" Section. |
786 | 689 | ||
787 | 1. *Check Out the Kernel Source Files:* First you must use ``devtool`` | 690 | #. *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 | 691 | to checkout the kernel source code in its workspace. |
789 | in the terminal set up to do work with the extensible SDK. | ||
790 | 692 | ||
791 | .. note:: | 693 | .. note:: |
792 | 694 | ||
@@ -794,15 +696,14 @@ the ":ref:`kernel-dev/common:getting ready to develop using \`\`devtool\`\``" Se | |||
794 | ":ref:`kernel-dev/common:getting ready to develop using \`\`devtool\`\``" | 696 | ":ref:`kernel-dev/common:getting ready to develop using \`\`devtool\`\``" |
795 | section for more information. | 697 | section for more information. |
796 | 698 | ||
797 | Use the following ``devtool`` command to check out the code: | 699 | Use the following ``devtool`` command to check out the code:: |
798 | :: | ||
799 | 700 | ||
800 | $ devtool modify linux-yocto | 701 | $ devtool modify linux-yocto |
801 | 702 | ||
802 | .. note:: | 703 | .. note:: |
803 | 704 | ||
804 | During the checkout operation, a bug exists that could cause | 705 | During the checkout operation, there is a bug that could cause |
805 | errors such as the following to appear: | 706 | errors such as the following: |
806 | 707 | ||
807 | .. code-block:: none | 708 | .. code-block:: none |
808 | 709 | ||
@@ -814,21 +715,19 @@ the ":ref:`kernel-dev/common:getting ready to develop using \`\`devtool\`\``" Se | |||
814 | You can safely ignore these messages. The source code is correctly | 715 | You can safely ignore these messages. The source code is correctly |
815 | checked out. | 716 | checked out. |
816 | 717 | ||
817 | 2. *Edit the Source Files* Follow these steps to make some simple | 718 | #. *Edit the Source Files* Follow these steps to make some simple |
818 | changes to the source files: | 719 | changes to the source files: |
819 | 720 | ||
820 | 1. *Change the working directory*: In the previous step, the output | 721 | #. *Change the working directory*: In the previous step, the output |
821 | noted where you can find the source files (e.g. | 722 | noted where you can find the source files (e.g. |
822 | ``~/poky_sdk/workspace/sources/linux-yocto``). Change to where the | 723 | ``poky_sdk/workspace/sources/linux-yocto``). Change to where the |
823 | kernel source code is before making your edits to the | 724 | kernel source code is before making your edits to the |
824 | ``calibrate.c`` file: | 725 | ``calibrate.c`` file:: |
825 | :: | ||
826 | 726 | ||
827 | $ cd ~/poky_sdk/workspace/sources/linux-yocto | 727 | $ cd poky_sdk/workspace/sources/linux-yocto |
828 | 728 | ||
829 | 2. *Edit the source file*: Edit the ``init/calibrate.c`` file to have | 729 | #. *Edit the source file*: Edit the ``init/calibrate.c`` file to have |
830 | the following changes: | 730 | the following changes:: |
831 | :: | ||
832 | 731 | ||
833 | void calibrate_delay(void) | 732 | void calibrate_delay(void) |
834 | { | 733 | { |
@@ -847,15 +746,17 @@ the ":ref:`kernel-dev/common:getting ready to develop using \`\`devtool\`\``" Se | |||
847 | . | 746 | . |
848 | . | 747 | . |
849 | 748 | ||
850 | 3. *Build the Updated Kernel Source:* To build the updated kernel | 749 | #. *Build the Updated Kernel Source:* To build the updated kernel |
851 | source, use ``devtool``: | 750 | source, use ``devtool``:: |
852 | :: | ||
853 | 751 | ||
854 | $ devtool build linux-yocto | 752 | $ devtool build linux-yocto |
855 | 753 | ||
856 | 4. *Create the Image With the New Kernel:* Use the | 754 | #. *Create the Image With the New Kernel:* Use the |
857 | ``devtool build-image`` command to create a new image that has the | 755 | ``devtool build-image`` command to create a new image that has the |
858 | new kernel. | 756 | new kernel:: |
757 | |||
758 | $ cd ~ | ||
759 | $ devtool build-image core-image-minimal | ||
859 | 760 | ||
860 | .. note:: | 761 | .. note:: |
861 | 762 | ||
@@ -865,21 +766,15 @@ the ":ref:`kernel-dev/common:getting ready to develop using \`\`devtool\`\``" Se | |||
865 | :yocto_wiki:`TipsAndTricks/KernelDevelopmentWithEsdk </TipsAndTricks/KernelDevelopmentWithEsdk>` | 766 | :yocto_wiki:`TipsAndTricks/KernelDevelopmentWithEsdk </TipsAndTricks/KernelDevelopmentWithEsdk>` |
866 | Wiki Page. | 767 | Wiki Page. |
867 | 768 | ||
868 | :: | 769 | #. *Test the New Image:* For this example, you can run the new image |
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: | 770 | using QEMU to verify your changes: |
875 | 771 | ||
876 | 1. *Boot the image*: Boot the modified image in the QEMU emulator | 772 | #. *Boot the image*: Boot the modified image in the QEMU emulator |
877 | using this command: | 773 | using this command:: |
878 | :: | ||
879 | 774 | ||
880 | $ runqemu qemux86 | 775 | $ runqemu qemux86 |
881 | 776 | ||
882 | 2. *Verify the changes*: Log into the machine using ``root`` with no | 777 | #. *Verify the changes*: Log into the machine using ``root`` with no |
883 | password and then use the following shell command to scroll | 778 | password and then use the following shell command to scroll |
884 | through the console's boot output. | 779 | through the console's boot output. |
885 | 780 | ||
@@ -891,21 +786,18 @@ the ":ref:`kernel-dev/common:getting ready to develop using \`\`devtool\`\``" Se | |||
891 | the results of your ``printk`` statements as part of the output | 786 | the results of your ``printk`` statements as part of the output |
892 | when you scroll down the console window. | 787 | when you scroll down the console window. |
893 | 788 | ||
894 | 6. *Stage and commit your changes*: Within your eSDK terminal, change | 789 | #. *Stage and commit your changes*: Change |
895 | your working directory to where you modified the ``calibrate.c`` file | 790 | your working directory to where you modified the ``calibrate.c`` file |
896 | and use these Git commands to stage and commit your changes: | 791 | and use these Git commands to stage and commit your changes:: |
897 | :: | ||
898 | 792 | ||
899 | $ cd ~/poky_sdk/workspace/sources/linux-yocto | 793 | $ cd poky_sdk/workspace/sources/linux-yocto |
900 | $ git status | 794 | $ git status |
901 | $ git add init/calibrate.c | 795 | $ git add init/calibrate.c |
902 | $ git commit -m "calibrate: Add printk example" | 796 | $ git commit -m "calibrate: Add printk example" |
903 | 797 | ||
904 | 7. *Export the Patches and Create an Append File:* To export your | 798 | #. *Export the Patches and Create an Append File:* To export your |
905 | commits as patches and create a ``.bbappend`` file, use the following | 799 | commits as patches and create a ``.bbappend`` file, use the following |
906 | command in the terminal used to work with the extensible SDK. This | 800 | command. This example uses the previously established layer named ``meta-mylayer``:: |
907 | example uses the previously established layer named ``meta-mylayer``. | ||
908 | :: | ||
909 | 801 | ||
910 | $ devtool finish linux-yocto ~/meta-mylayer | 802 | $ devtool finish linux-yocto ~/meta-mylayer |
911 | 803 | ||
@@ -919,22 +811,20 @@ the ":ref:`kernel-dev/common:getting ready to develop using \`\`devtool\`\``" Se | |||
919 | finishes, the patches and the ``.bbappend`` file are located in the | 811 | finishes, the patches and the ``.bbappend`` file are located in the |
920 | ``~/meta-mylayer/recipes-kernel/linux`` directory. | 812 | ``~/meta-mylayer/recipes-kernel/linux`` directory. |
921 | 813 | ||
922 | 8. *Build the Image With Your Modified Kernel:* You can now build an | 814 | #. *Build the Image With Your Modified Kernel:* You can now build an |
923 | image that includes your kernel patches. Execute the following | 815 | image that includes your kernel patches. Execute the following |
924 | command from your | 816 | command from your :term:`Build Directory` in the terminal |
925 | :term:`Build Directory` in the terminal | 817 | set up to run BitBake:: |
926 | set up to run BitBake: | ||
927 | :: | ||
928 | 818 | ||
929 | $ cd ~/poky/build | 819 | $ cd poky/build |
930 | $ bitbake core-image-minimal | 820 | $ bitbake core-image-minimal |
931 | 821 | ||
932 | Using Traditional Kernel Development to Patch the Kernel | 822 | Using Traditional Kernel Development to Patch the Kernel |
933 | ======================================================== | 823 | ======================================================== |
934 | 824 | ||
935 | The steps in this procedure show you how you can patch the kernel using | 825 | 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 | 826 | traditional kernel development (i.e. not using ``devtool`` |
937 | extensible SDK as described in the | 827 | as described in the |
938 | ":ref:`kernel-dev/common:using \`\`devtool\`\` to patch the kernel`" | 828 | ":ref:`kernel-dev/common:using \`\`devtool\`\` to patch the kernel`" |
939 | section). | 829 | section). |
940 | 830 | ||
@@ -955,28 +845,25 @@ emulator console output at boot time through ``printk`` statements in | |||
955 | the kernel's ``calibrate.c`` source code file. Applying the patch and | 845 | 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 | 846 | 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 | 847 | emulator's console. The example is a continuation of the setup procedure |
958 | found in the "`Getting Ready for Traditional Kernel | 848 | found in the |
959 | Development <#getting-ready-for-traditional-kernel-development>`__" | 849 | ":ref:`kernel-dev/common:getting ready for traditional kernel development`" |
960 | Section. | 850 | Section. |
961 | 851 | ||
962 | 1. *Edit the Source Files* Prior to this step, you should have used Git | 852 | #. *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 | 853 | to create a local copy of the repository for your kernel. Assuming |
964 | you created the repository as directed in the "`Getting Ready for | 854 | you created the repository as directed in the |
965 | Traditional Kernel | 855 | ":ref:`kernel-dev/common:getting ready for traditional kernel development`" |
966 | Development <#getting-ready-for-traditional-kernel-development>`__" | ||
967 | section, use the following commands to edit the ``calibrate.c`` file: | 856 | section, use the following commands to edit the ``calibrate.c`` file: |
968 | 857 | ||
969 | 1. *Change the working directory*: You need to locate the source | 858 | #. *Change the working directory*: You need to locate the source |
970 | files in the local copy of the kernel Git repository. Change to | 859 | 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 | 860 | where the kernel source code is before making your edits to the |
972 | ``calibrate.c`` file: | 861 | ``calibrate.c`` file:: |
973 | :: | ||
974 | 862 | ||
975 | $ cd ~/linux-yocto-4.12/init | 863 | $ cd ~/linux-yocto-4.12/init |
976 | 864 | ||
977 | 2. *Edit the source file*: Edit the ``calibrate.c`` file to have the | 865 | #. *Edit the source file*: Edit the ``calibrate.c`` file to have the |
978 | following changes: | 866 | following changes:: |
979 | :: | ||
980 | 867 | ||
981 | void calibrate_delay(void) | 868 | void calibrate_delay(void) |
982 | { | 869 | { |
@@ -995,9 +882,8 @@ Section. | |||
995 | . | 882 | . |
996 | . | 883 | . |
997 | 884 | ||
998 | 2. *Stage and Commit Your Changes:* Use standard Git commands to stage | 885 | #. *Stage and Commit Your Changes:* Use standard Git commands to stage |
999 | and commit the changes you just made: | 886 | and commit the changes you just made:: |
1000 | :: | ||
1001 | 887 | ||
1002 | $ git add calibrate.c | 888 | $ git add calibrate.c |
1003 | $ git commit -m "calibrate.c - Added some printk statements" | 889 | $ git commit -m "calibrate.c - Added some printk statements" |
@@ -1006,24 +892,22 @@ Section. | |||
1006 | stage and commit your changes, the OpenEmbedded Build System will not | 892 | stage and commit your changes, the OpenEmbedded Build System will not |
1007 | pick up the changes. | 893 | pick up the changes. |
1008 | 894 | ||
1009 | 3. *Update Your local.conf File to Point to Your Source Files:* In | 895 | #. *Update Your local.conf File to Point to Your Source Files:* In |
1010 | addition to your ``local.conf`` file specifying to use | 896 | addition to your ``local.conf`` file specifying to use |
1011 | "kernel-modules" and the "qemux86" machine, it must also point to the | 897 | "kernel-modules" and the "qemux86" machine, it must also point to the |
1012 | updated kernel source files. Add | 898 | updated kernel source files. Add |
1013 | :term:`SRC_URI` and | 899 | :term:`SRC_URI` and |
1014 | :term:`SRCREV` statements similar | 900 | :term:`SRCREV` statements similar |
1015 | to the following to your ``local.conf``: | 901 | to the following to your ``local.conf``:: |
1016 | :: | ||
1017 | 902 | ||
1018 | $ cd ~/poky/build/conf | 903 | $ cd poky/build/conf |
1019 | 904 | ||
1020 | Add the following to the ``local.conf``: | 905 | Add the following to the ``local.conf``:: |
1021 | :: | ||
1022 | 906 | ||
1023 | SRC_URI_pn-linux-yocto = "git:///path-to/linux-yocto-4.12;protocol=file;name=machine;branch=standard/base; \ | 907 | 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}" | 908 | git:///path-to/yocto-kernel-cache;protocol=file;type=kmeta;name=meta;branch=yocto-4.12;destsuffix=${KMETA}" |
1025 | SRCREV_meta_qemux86 = "${AUTOREV}" | 909 | SRCREV_meta:qemux86 = "${AUTOREV}" |
1026 | SRCREV_machine_qemux86 = "${AUTOREV}" | 910 | SRCREV_machine:qemux86 = "${AUTOREV}" |
1027 | 911 | ||
1028 | .. note:: | 912 | .. note:: |
1029 | 913 | ||
@@ -1032,23 +916,21 @@ Section. | |||
1032 | be sure to specify the correct branch and machine types. For this | 916 | be sure to specify the correct branch and machine types. For this |
1033 | example, the branch is ``standard/base`` and the machine is ``qemux86``. | 917 | example, the branch is ``standard/base`` and the machine is ``qemux86``. |
1034 | 918 | ||
1035 | 4. *Build the Image:* With the source modified, your changes staged and | 919 | #. *Build the Image:* With the source modified, your changes staged and |
1036 | committed, and the ``local.conf`` file pointing to the kernel files, | 920 | committed, and the ``local.conf`` file pointing to the kernel files, |
1037 | you can now use BitBake to build the image: | 921 | you can now use BitBake to build the image:: |
1038 | :: | ||
1039 | 922 | ||
1040 | $ cd ~/poky/build | 923 | $ cd poky/build |
1041 | $ bitbake core-image-minimal | 924 | $ bitbake core-image-minimal |
1042 | 925 | ||
1043 | 5. *Boot the image*: Boot the modified image in the QEMU emulator using | 926 | #. *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" | 927 | this command. When prompted to login to the QEMU console, use "root" |
1045 | with no password: | 928 | with no password:: |
1046 | :: | ||
1047 | 929 | ||
1048 | $ cd ~/poky/build | 930 | $ cd poky/build |
1049 | $ runqemu qemux86 | 931 | $ runqemu qemux86 |
1050 | 932 | ||
1051 | 6. *Look for Your Changes:* As QEMU booted, you might have seen your | 933 | #. *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 | 934 | changes rapidly scroll by. If not, use these commands to see your |
1053 | changes: | 935 | changes: |
1054 | 936 | ||
@@ -1060,55 +942,49 @@ Section. | |||
1060 | ``printk`` statements as part of the output when you scroll down the | 942 | ``printk`` statements as part of the output when you scroll down the |
1061 | console window. | 943 | console window. |
1062 | 944 | ||
1063 | 7. *Generate the Patch File:* Once you are sure that your patch works | 945 | #. *Generate the Patch File:* Once you are sure that your patch works |
1064 | correctly, you can generate a ``*.patch`` file in the kernel source | 946 | correctly, you can generate a ``*.patch`` file in the kernel source |
1065 | repository: | 947 | repository:: |
1066 | :: | ||
1067 | 948 | ||
1068 | $ cd ~/linux-yocto-4.12/init | 949 | $ cd ~/linux-yocto-4.12/init |
1069 | $ git format-patch -1 | 950 | $ git format-patch -1 |
1070 | 0001-calibrate.c-Added-some-printk-statements.patch | 951 | 0001-calibrate.c-Added-some-printk-statements.patch |
1071 | 952 | ||
1072 | 8. *Move the Patch File to Your Layer:* In order for subsequent builds | 953 | #. *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 | 954 | 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, | 955 | the previous step to your layer ``meta-mylayer``. For this example, |
1075 | the layer created earlier is located in your home directory as | 956 | the layer created earlier is located in your home directory as |
1076 | ``meta-mylayer``. When the layer was created using the | 957 | ``meta-mylayer``. When the layer was created using the |
1077 | ``yocto-create`` script, no additional hierarchy was created to | 958 | ``yocto-create`` script, no additional hierarchy was created to |
1078 | support patches. Before moving the patch file, you need to add | 959 | support patches. Before moving the patch file, you need to add |
1079 | additional structure to your layer using the following commands: | 960 | additional structure to your layer using the following commands:: |
1080 | :: | ||
1081 | 961 | ||
1082 | $ cd ~/meta-mylayer | 962 | $ cd ~/meta-mylayer |
1083 | $ mkdir recipes-kernel | 963 | $ mkdir -p recipes-kernel recipes-kernel/linux/linux-yocto |
1084 | $ mkdir recipes-kernel/linux | ||
1085 | $ mkdir recipes-kernel/linux/linux-yocto | ||
1086 | 964 | ||
1087 | Once you have created this | 965 | Once you have created this |
1088 | hierarchy in your layer, you can move the patch file using the | 966 | hierarchy in your layer, you can move the patch file using the |
1089 | following command: | 967 | following command:: |
1090 | :: | ||
1091 | 968 | ||
1092 | $ mv ~/linux-yocto-4.12/init/0001-calibrate.c-Added-some-printk-statements.patch ~/meta-mylayer/recipes-kernel/linux/linux-yocto | 969 | $ mv ~/linux-yocto-4.12/init/0001-calibrate.c-Added-some-printk-statements.patch ~/meta-mylayer/recipes-kernel/linux/linux-yocto |
1093 | 970 | ||
1094 | 9. *Create the Append File:* Finally, you need to create the | 971 | #. *Create the Append File:* Finally, you need to create the |
1095 | ``linux-yocto_4.12.bbappend`` file and insert statements that allow | 972 | ``linux-yocto_4.12.bbappend`` file and insert statements that allow |
1096 | the OpenEmbedded build system to find the patch. The append file | 973 | 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 | 974 | 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 | 975 | must be named ``linux-yocto_4.12.bbappend`` and have the following |
1099 | contents: | 976 | contents:: |
1100 | :: | ||
1101 | 977 | ||
1102 | FILESEXTRAPATHS_prepend := "${THISDIR}/${PN}:" | 978 | FILESEXTRAPATHS:prepend := "${THISDIR}/${PN}:" |
1103 | SRC_URI_append = "file://0001-calibrate.c-Added-some-printk-statements.patch" | 979 | SRC_URI += "file://0001-calibrate.c-Added-some-printk-statements.patch" |
1104 | 980 | ||
1105 | The :term:`FILESEXTRAPATHS` and :term:`SRC_URI` statements | 981 | The :term:`FILESEXTRAPATHS` and :term:`SRC_URI` statements |
1106 | enable the OpenEmbedded build system to find the patch file. | 982 | enable the OpenEmbedded build system to find the patch file. |
1107 | 983 | ||
1108 | For more information on append files and patches, see the "`Creating | 984 | For more information on append files and patches, see the |
1109 | the Append File <#creating-the-append-file>`__" and "`Applying | 985 | ":ref:`kernel-dev/common:creating the append file`" and |
1110 | Patches <#applying-patches>`__" sections. You can also see the | 986 | ":ref:`kernel-dev/common:applying patches`" sections. You can also see the |
1111 | ":ref:`dev-manual/common-tasks:using .bbappend files in your layer`" | 987 | ":ref:`dev-manual/layers:appending other layers metadata with your layer`" |
1112 | section in the Yocto Project Development Tasks Manual. | 988 | section in the Yocto Project Development Tasks Manual. |
1113 | 989 | ||
1114 | .. note:: | 990 | .. note:: |
@@ -1116,11 +992,10 @@ Section. | |||
1116 | To build ``core-image-minimal`` again and see the effects of your patch, | 992 | To build ``core-image-minimal`` again and see the effects of your patch, |
1117 | you can essentially eliminate the temporary source files saved in | 993 | you can essentially eliminate the temporary source files saved in |
1118 | ``poky/build/tmp/work/...`` and residual effects of the build by entering | 994 | ``poky/build/tmp/work/...`` and residual effects of the build by entering |
1119 | the following sequence of commands: | 995 | the following sequence of commands:: |
1120 | :: | ||
1121 | 996 | ||
1122 | $ cd ~/poky/build | 997 | $ cd poky/build |
1123 | $ bitbake -c cleanall yocto-linux | 998 | $ bitbake -c cleanall linux-yocto |
1124 | $ bitbake core-image-minimal -c cleanall | 999 | $ bitbake core-image-minimal -c cleanall |
1125 | $ bitbake core-image-minimal | 1000 | $ bitbake core-image-minimal |
1126 | $ runqemu qemux86 | 1001 | $ runqemu qemux86 |
@@ -1141,8 +1016,8 @@ configuration fragments, and how to interactively modify your | |||
1141 | ``.config`` file to create the leanest kernel configuration file | 1016 | ``.config`` file to create the leanest kernel configuration file |
1142 | possible. | 1017 | possible. |
1143 | 1018 | ||
1144 | For more information on kernel configuration, see the "`Changing the | 1019 | For more information on kernel configuration, see the |
1145 | Configuration <#changing-the-configuration>`__" section. | 1020 | ":ref:`kernel-dev/common:changing the configuration`" section. |
1146 | 1021 | ||
1147 | Using  ``menuconfig`` | 1022 | Using  ``menuconfig`` |
1148 | --------------------- | 1023 | --------------------- |
@@ -1150,21 +1025,19 @@ Using  ``menuconfig`` | |||
1150 | The easiest way to define kernel configurations is to set them through | 1025 | The easiest way to define kernel configurations is to set them through |
1151 | the ``menuconfig`` tool. This tool provides an interactive method with | 1026 | the ``menuconfig`` tool. This tool provides an interactive method with |
1152 | which to set kernel configurations. For general information on | 1027 | which to set kernel configurations. For general information on |
1153 | ``menuconfig``, see https://en.wikipedia.org/wiki/Menuconfig. | 1028 | ``menuconfig``, see :wikipedia:`Menuconfig`. |
1154 | 1029 | ||
1155 | To use the ``menuconfig`` tool in the Yocto Project development | 1030 | To use the ``menuconfig`` tool in the Yocto Project development |
1156 | environment, you must do the following: | 1031 | environment, you must do the following: |
1157 | 1032 | ||
1158 | - Because you launch ``menuconfig`` using BitBake, you must be sure to | 1033 | - Because you launch ``menuconfig`` using BitBake, you must be sure to |
1159 | set up your environment by running the | 1034 | set up your environment by running the :ref:`structure-core-script` script |
1160 | :ref:`structure-core-script` script found in | 1035 | found in the :term:`Build Directory`. |
1161 | the :term:`Build Directory`. | ||
1162 | 1036 | ||
1163 | - You must be sure of the state of your build's configuration in the | 1037 | - You must be sure of the state of your build's configuration in the |
1164 | :term:`Source Directory`. | 1038 | :term:`Source Directory`. |
1165 | 1039 | ||
1166 | - Your build host must have the following two packages installed: | 1040 | - Your build host must have the following two packages installed:: |
1167 | :: | ||
1168 | 1041 | ||
1169 | libncurses5-dev | 1042 | libncurses5-dev |
1170 | libtinfo-dev | 1043 | libtinfo-dev |
@@ -1172,8 +1045,7 @@ environment, you must do the following: | |||
1172 | The following commands initialize the BitBake environment, run the | 1045 | The following commands initialize the BitBake environment, run the |
1173 | :ref:`ref-tasks-kernel_configme` | 1046 | :ref:`ref-tasks-kernel_configme` |
1174 | task, and launch ``menuconfig``. These commands assume the Source | 1047 | task, and launch ``menuconfig``. These commands assume the Source |
1175 | Directory's top-level folder is ``~/poky``: | 1048 | Directory's top-level folder is ``poky``:: |
1176 | :: | ||
1177 | 1049 | ||
1178 | $ cd poky | 1050 | $ cd poky |
1179 | $ source oe-init-build-env | 1051 | $ source oe-init-build-env |
@@ -1201,7 +1073,7 @@ Consider an example that configures the "CONFIG_SMP" setting for the | |||
1201 | .. note:: | 1073 | .. note:: |
1202 | 1074 | ||
1203 | The OpenEmbedded build system recognizes this kernel as ``linux-yocto`` | 1075 | The OpenEmbedded build system recognizes this kernel as ``linux-yocto`` |
1204 | through Metadata (e.g. :term:`PREFERRED_VERSION`\ ``_linux-yocto ?= "12.4%"``). | 1076 | through Metadata (e.g. :term:`PREFERRED_VERSION`\ ``_linux-yocto ?= "4.12%"``). |
1205 | 1077 | ||
1206 | Once ``menuconfig`` launches, use the interface to navigate through the | 1078 | Once ``menuconfig`` launches, use the interface to navigate through the |
1207 | selections to find the configuration settings in which you are | 1079 | selections to find the configuration settings in which you are |
@@ -1212,10 +1084,10 @@ can find the option under "Processor Type and Features". To deselect | |||
1212 | Multi-Processing Support" and enter "N" to clear the asterisk. When you | 1084 | Multi-Processing Support" and enter "N" to clear the asterisk. When you |
1213 | are finished, exit out and save the change. | 1085 | are finished, exit out and save the change. |
1214 | 1086 | ||
1215 | Saving the selections updates the ``.config`` configuration file. This | 1087 | Saving the selections updates the ``.config`` configuration file. This is the |
1216 | is the file that the OpenEmbedded build system uses to configure the | 1088 | file that the OpenEmbedded build system uses to configure the kernel during |
1217 | kernel during the build. You can find and examine this file in the Build | 1089 | the build. You can find and examine this file in the :term:`Build Directory` |
1218 | Directory in ``tmp/work/``. The actual ``.config`` is located in the | 1090 | in ``tmp/work/``. The actual ``.config`` is located in the |
1219 | area where the specific kernel is built. For example, if you were | 1091 | 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 | 1092 | 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, | 1093 | and you were building a QEMU image targeted for ``x86`` architecture, |
@@ -1235,8 +1107,7 @@ the ``.config`` file would be: | |||
1235 | 1107 | ||
1236 | Within the ``.config`` file, you can see the kernel settings. For | 1108 | Within the ``.config`` file, you can see the kernel settings. For |
1237 | example, the following entry shows that symmetric multi-processor | 1109 | example, the following entry shows that symmetric multi-processor |
1238 | support is not set: | 1110 | support is not set:: |
1239 | :: | ||
1240 | 1111 | ||
1241 | # CONFIG_SMP is not set | 1112 | # CONFIG_SMP is not set |
1242 | 1113 | ||
@@ -1277,10 +1148,9 @@ your layer's ``recipes-kernel/linux`` directory, and rename the copied | |||
1277 | file to "defconfig" (e.g. | 1148 | file to "defconfig" (e.g. |
1278 | ``~/meta-mylayer/recipes-kernel/linux/linux-yocto/defconfig``). Then, | 1149 | ``~/meta-mylayer/recipes-kernel/linux/linux-yocto/defconfig``). Then, |
1279 | add the following lines to the linux-yocto ``.bbappend`` file in your | 1150 | add the following lines to the linux-yocto ``.bbappend`` file in your |
1280 | layer: | 1151 | layer:: |
1281 | :: | ||
1282 | 1152 | ||
1283 | FILESEXTRAPATHS_prepend := "${THISDIR}/${PN}:" | 1153 | FILESEXTRAPATHS:prepend := "${THISDIR}/${PN}:" |
1284 | SRC_URI += "file://defconfig" | 1154 | SRC_URI += "file://defconfig" |
1285 | 1155 | ||
1286 | The :term:`SRC_URI` tells the build system how to search for the file, while the | 1156 | The :term:`SRC_URI` tells the build system how to search for the file, while the |
@@ -1298,8 +1168,8 @@ created to hold the configuration changes. | |||
1298 | applies these on top of and after applying the existing ``defconfig`` file | 1168 | applies these on top of and after applying the existing ``defconfig`` file |
1299 | configurations. | 1169 | configurations. |
1300 | 1170 | ||
1301 | For more information on configuring the kernel, see the "`Changing the | 1171 | For more information on configuring the kernel, see the |
1302 | Configuration <#changing-the-configuration>`__" section. | 1172 | ":ref:`kernel-dev/common:changing the configuration`" section. |
1303 | 1173 | ||
1304 | Creating Configuration Fragments | 1174 | Creating Configuration Fragments |
1305 | -------------------------------- | 1175 | -------------------------------- |
@@ -1326,8 +1196,7 @@ appear in the ``.config`` file, which is in the :term:`Build Directory`. | |||
1326 | It is simple to create a configuration fragment. One method is to use | 1196 | It is simple to create a configuration fragment. One method is to use |
1327 | shell commands. For example, issuing the following from the shell | 1197 | shell commands. For example, issuing the following from the shell |
1328 | creates a configuration fragment file named ``my_smp.cfg`` that enables | 1198 | creates a configuration fragment file named ``my_smp.cfg`` that enables |
1329 | multi-processor support within the kernel: | 1199 | multi-processor support within the kernel:: |
1330 | :: | ||
1331 | 1200 | ||
1332 | $ echo "CONFIG_SMP=y" >> my_smp.cfg | 1201 | $ echo "CONFIG_SMP=y" >> my_smp.cfg |
1333 | 1202 | ||
@@ -1344,34 +1213,31 @@ saved, and one freshly created using the ``menuconfig`` tool. | |||
1344 | To create a configuration fragment using this method, follow these | 1213 | To create a configuration fragment using this method, follow these |
1345 | steps: | 1214 | steps: |
1346 | 1215 | ||
1347 | 1. *Complete a Build Through Kernel Configuration:* Complete a build at | 1216 | #. *Complete a Build Through Kernel Configuration:* Complete a build at |
1348 | least through the kernel configuration task as follows: | 1217 | least through the kernel configuration task as follows:: |
1349 | :: | ||
1350 | 1218 | ||
1351 | $ bitbake linux-yocto -c kernel_configme -f | 1219 | $ bitbake linux-yocto -c kernel_configme -f |
1352 | 1220 | ||
1353 | This step ensures that you create a | 1221 | This step ensures that you create a |
1354 | ``.config`` file from a known state. Because situations exist where | 1222 | ``.config`` file from a known state. Because there are situations where |
1355 | your build state might become unknown, it is best to run this task | 1223 | your build state might become unknown, it is best to run this task |
1356 | prior to starting ``menuconfig``. | 1224 | prior to starting ``menuconfig``. |
1357 | 1225 | ||
1358 | 2. *Launch menuconfig:* Run the ``menuconfig`` command: | 1226 | #. *Launch menuconfig:* Run the ``menuconfig`` command:: |
1359 | :: | ||
1360 | 1227 | ||
1361 | $ bitbake linux-yocto -c menuconfig | 1228 | $ bitbake linux-yocto -c menuconfig |
1362 | 1229 | ||
1363 | 3. *Create the Configuration Fragment:* Run the ``diffconfig`` command | 1230 | #. *Create the Configuration Fragment:* Run the ``diffconfig`` command |
1364 | to prepare a configuration fragment. The resulting file | 1231 | to prepare a configuration fragment. The resulting file |
1365 | ``fragment.cfg`` is placed in the | 1232 | ``fragment.cfg`` is placed in the |
1366 | ``${``\ :term:`WORKDIR`\ ``}`` | 1233 | ``${``\ :term:`WORKDIR`\ ``}`` |
1367 | directory: | 1234 | directory:: |
1368 | :: | ||
1369 | 1235 | ||
1370 | $ bitbake linux-yocto -c diffconfig | 1236 | $ bitbake linux-yocto -c diffconfig |
1371 | 1237 | ||
1372 | The ``diffconfig`` command creates a file that is a list of Linux kernel | 1238 | The ``diffconfig`` command creates a file that is a list of Linux kernel |
1373 | ``CONFIG_`` assignments. See the "`Changing the | 1239 | ``CONFIG_`` assignments. See the |
1374 | Configuration <#changing-the-configuration>`__" section for additional | 1240 | ":ref:`kernel-dev/common:changing the configuration`" section for additional |
1375 | information on how to use the output as a configuration fragment. | 1241 | information on how to use the output as a configuration fragment. |
1376 | 1242 | ||
1377 | .. note:: | 1243 | .. note:: |
@@ -1390,18 +1256,16 @@ 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 | 1256 | 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 | 1257 | 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 | 1258 | statements to the kernel's append file, those configuration options will |
1393 | be picked up and applied when the kernel is built: | 1259 | be picked up and applied when the kernel is built:: |
1394 | :: | ||
1395 | 1260 | ||
1396 | FILESEXTRAPATHS_prepend := "${THISDIR}/${PN}:" | 1261 | FILESEXTRAPATHS:prepend := "${THISDIR}/${PN}:" |
1397 | SRC_URI += "file://myconfig.cfg" | 1262 | SRC_URI += "file://myconfig.cfg" |
1398 | 1263 | ||
1399 | As mentioned earlier, you can group related configurations into multiple | 1264 | As mentioned earlier, you can group related configurations into multiple |
1400 | files and name them all in the ``SRC_URI`` statement as well. For | 1265 | files and name them all in the :term:`SRC_URI` statement as well. For |
1401 | example, you could group separate configurations specifically for | 1266 | example, you could group separate configurations specifically for |
1402 | Ethernet and graphics into their own files and add those by using a | 1267 | Ethernet and graphics into their own files and add those by using a |
1403 | ``SRC_URI`` statement like the following in your append file: | 1268 | :term:`SRC_URI` statement like the following in your append file:: |
1404 | :: | ||
1405 | 1269 | ||
1406 | SRC_URI += "file://myconfig.cfg \ | 1270 | SRC_URI += "file://myconfig.cfg \ |
1407 | file://eth.cfg \ | 1271 | file://eth.cfg \ |
@@ -1412,8 +1276,7 @@ Validating Configuration | |||
1412 | 1276 | ||
1413 | You can use the | 1277 | You can use the |
1414 | :ref:`ref-tasks-kernel_configcheck` | 1278 | :ref:`ref-tasks-kernel_configcheck` |
1415 | task to provide configuration validation: | 1279 | task to provide configuration validation:: |
1416 | :: | ||
1417 | 1280 | ||
1418 | $ bitbake linux-yocto -c kernel_configcheck -f | 1281 | $ bitbake linux-yocto -c kernel_configcheck -f |
1419 | 1282 | ||
@@ -1426,7 +1289,7 @@ In order to run this task, you must have an existing ``.config`` file. | |||
1426 | See the ":ref:`kernel-dev/common:using \`\`menuconfig\`\``" section for | 1289 | See the ":ref:`kernel-dev/common:using \`\`menuconfig\`\``" section for |
1427 | information on how to create a configuration file. | 1290 | information on how to create a configuration file. |
1428 | 1291 | ||
1429 | Following is sample output from the ``do_kernel_configcheck`` task: | 1292 | Here is sample output from the :ref:`ref-tasks-kernel_configcheck` task: |
1430 | 1293 | ||
1431 | .. code-block:: none | 1294 | .. code-block:: none |
1432 | 1295 | ||
@@ -1506,12 +1369,12 @@ possible by reading the output of the kernel configuration fragment | |||
1506 | audit, noting any issues, making changes to correct the issues, and then | 1369 | audit, noting any issues, making changes to correct the issues, and then |
1507 | repeating. | 1370 | repeating. |
1508 | 1371 | ||
1509 | As part of the kernel build process, the ``do_kernel_configcheck`` task | 1372 | As part of the kernel build process, the :ref:`ref-tasks-kernel_configcheck` task |
1510 | runs. This task validates the kernel configuration by checking the final | 1373 | runs. This task validates the kernel configuration by checking the final |
1511 | ``.config`` file against the input files. During the check, the task | 1374 | ``.config`` file against the input files. During the check, the task |
1512 | produces warning messages for the following issues: | 1375 | produces warning messages for the following issues: |
1513 | 1376 | ||
1514 | - Requested options that did not make the final ``.config`` file. | 1377 | - Requested options that did not make it into the final ``.config`` file. |
1515 | 1378 | ||
1516 | - Configuration items that appear twice in the same configuration | 1379 | - Configuration items that appear twice in the same configuration |
1517 | fragment. | 1380 | fragment. |
@@ -1535,19 +1398,18 @@ configuration. | |||
1535 | 1398 | ||
1536 | To streamline the configuration, do the following: | 1399 | To streamline the configuration, do the following: |
1537 | 1400 | ||
1538 | 1. *Use a Working Configuration:* Start with a full configuration that | 1401 | #. *Use a Working Configuration:* Start with a full configuration that |
1539 | you know works. Be sure the configuration builds and boots | 1402 | you know works. Be sure the configuration builds and boots |
1540 | successfully. Use this configuration file as your baseline. | 1403 | successfully. Use this configuration file as your baseline. |
1541 | 1404 | ||
1542 | 2. *Run Configure and Check Tasks:* Separately run the | 1405 | #. *Run Configure and Check Tasks:* Separately run the |
1543 | ``do_kernel_configme`` and ``do_kernel_configcheck`` tasks: | 1406 | :ref:`ref-tasks-kernel_configme` and :ref:`ref-tasks-kernel_configcheck` tasks:: |
1544 | :: | ||
1545 | 1407 | ||
1546 | $ bitbake linux-yocto -c kernel_configme -f | 1408 | $ bitbake linux-yocto -c kernel_configme -f |
1547 | $ bitbake linux-yocto -c kernel_configcheck -f | 1409 | $ bitbake linux-yocto -c kernel_configcheck -f |
1548 | 1410 | ||
1549 | 3. *Process the Results:* Take the resulting list of files from the | 1411 | #. *Process the Results:* Take the resulting list of files from the |
1550 | ``do_kernel_configcheck`` task warnings and do the following: | 1412 | :ref:`ref-tasks-kernel_configcheck` task warnings and do the following: |
1551 | 1413 | ||
1552 | - Drop values that are redefined in the fragment but do not change | 1414 | - Drop values that are redefined in the fragment but do not change |
1553 | the final ``.config`` file. | 1415 | the final ``.config`` file. |
@@ -1559,9 +1421,9 @@ To streamline the configuration, do the following: | |||
1559 | 1421 | ||
1560 | - Remove repeated and invalid options. | 1422 | - Remove repeated and invalid options. |
1561 | 1423 | ||
1562 | 4. *Re-Run Configure and Check Tasks:* After you have worked through the | 1424 | #. *Re-Run Configure and Check Tasks:* After you have worked through the |
1563 | output of the kernel configuration audit, you can re-run the | 1425 | output of the kernel configuration audit, you can re-run the |
1564 | ``do_kernel_configme`` and ``do_kernel_configcheck`` tasks to see the | 1426 | :ref:`ref-tasks-kernel_configme` and :ref:`ref-tasks-kernel_configcheck` tasks to see the |
1565 | results of your changes. If you have more issues, you can deal with | 1427 | results of your changes. If you have more issues, you can deal with |
1566 | them as described in the previous step. | 1428 | them as described in the previous step. |
1567 | 1429 | ||
@@ -1575,8 +1437,7 @@ Expanding Variables | |||
1575 | Sometimes it is helpful to determine what a variable expands to during a | 1437 | 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 | 1438 | 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 | 1439 | 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: | 1440 | easily managed in a text file, which allows for easy searches:: |
1579 | :: | ||
1580 | 1441 | ||
1581 | $ bitbake -e virtual/kernel > some_text_file | 1442 | $ bitbake -e virtual/kernel > some_text_file |
1582 | 1443 | ||
@@ -1588,25 +1449,23 @@ Working with a "Dirty" Kernel Version String | |||
1588 | ============================================ | 1449 | ============================================ |
1589 | 1450 | ||
1590 | If you build a kernel image and the version string has a "+" or a | 1451 | 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 | 1452 | "-dirty" at the end, it means there are uncommitted modifications in the kernel's |
1592 | source directory. Follow these steps to clean up the version string: | 1453 | source directory. Follow these steps to clean up the version string: |
1593 | 1454 | ||
1594 | 1. *Discover the Uncommitted Changes:* Go to the kernel's locally cloned | 1455 | #. *Discover the Uncommitted Changes:* Go to the kernel's locally cloned |
1595 | Git repository (source directory) and use the following Git command | 1456 | Git repository (source directory) and use the following Git command |
1596 | to list the files that have been changed, added, or removed: | 1457 | to list the files that have been changed, added, or removed:: |
1597 | :: | ||
1598 | 1458 | ||
1599 | $ git status | 1459 | $ git status |
1600 | 1460 | ||
1601 | 2. *Commit the Changes:* You should commit those changes to the kernel | 1461 | #. *Commit the Changes:* You should commit those changes to the kernel |
1602 | source tree regardless of whether or not you will save, export, or | 1462 | source tree regardless of whether or not you will save, export, or |
1603 | use the changes: | 1463 | use the changes:: |
1604 | :: | ||
1605 | 1464 | ||
1606 | $ git add | 1465 | $ git add |
1607 | $ git commit -s -a -m "getting rid of -dirty" | 1466 | $ git commit -s -a -m "getting rid of -dirty" |
1608 | 1467 | ||
1609 | 3. *Rebuild the Kernel Image:* Once you commit the changes, rebuild the | 1468 | #. *Rebuild the Kernel Image:* Once you commit the changes, rebuild the |
1610 | kernel. | 1469 | kernel. |
1611 | 1470 | ||
1612 | Depending on your particular kernel development workflow, the | 1471 | Depending on your particular kernel development workflow, the |
@@ -1614,9 +1473,8 @@ source directory. Follow these steps to clean up the version string: | |||
1614 | on building the kernel image when using ``devtool``, see the | 1473 | on building the kernel image when using ``devtool``, see the |
1615 | ":ref:`kernel-dev/common:using \`\`devtool\`\` to patch the kernel`" | 1474 | ":ref:`kernel-dev/common:using \`\`devtool\`\` to patch the kernel`" |
1616 | section. For | 1475 | section. For |
1617 | information on building the kernel image when using Bitbake, see the | 1476 | information on building the kernel image when using BitBake, see the |
1618 | "`Using Traditional Kernel Development to Patch the | 1477 | ":ref:`kernel-dev/common:using traditional kernel development to patch the kernel`" |
1619 | Kernel <#using-traditional-kernel-development-to-patch-the-kernel>`__" | ||
1620 | section. | 1478 | section. |
1621 | 1479 | ||
1622 | Working With Your Own Sources | 1480 | Working With Your Own Sources |
@@ -1633,34 +1491,30 @@ Maintaining format compatibility facilitates converging with linux-yocto | |||
1633 | on a future, mutually-supported kernel version. | 1491 | on a future, mutually-supported kernel version. |
1634 | 1492 | ||
1635 | To help you use your own sources, the Yocto Project provides a | 1493 | To help you use your own sources, the Yocto Project provides a |
1636 | linux-yocto custom recipe (``linux-yocto-custom.bb``) that uses | 1494 | linux-yocto custom recipe that uses ``kernel.org`` sources and |
1637 | ``kernel.org`` sources and the Yocto Project Linux kernel tools for | 1495 | the Yocto Project Linux kernel tools for managing kernel Metadata. |
1638 | managing kernel Metadata. You can find this recipe in the ``poky`` Git | 1496 | You can find this recipe in the ``poky`` Git repository: |
1639 | repository of the Yocto Project :yocto_git:`Source Repository <>` | 1497 | :yocto_git:`meta-skeleton/recipes-kernel/linux/linux-yocto-custom.bb |
1640 | at: | 1498 | </poky/tree/meta-skeleton/recipes-kernel/linux/linux-yocto-custom.bb>`. |
1641 | :: | ||
1642 | |||
1643 | poky/meta-skeleton/recipes-kernel/linux/linux-yocto-custom.bb | ||
1644 | 1499 | ||
1645 | Here are some basic steps you can use to work with your own sources: | 1500 | Here are some basic steps you can use to work with your own sources: |
1646 | 1501 | ||
1647 | 1. *Create a Copy of the Kernel Recipe:* Copy the | 1502 | #. *Create a Copy of the Kernel Recipe:* Copy the |
1648 | ``linux-yocto-custom.bb`` recipe to your layer and give it a | 1503 | ``linux-yocto-custom.bb`` recipe to your layer and give it a |
1649 | meaningful name. The name should include the version of the Yocto | 1504 | 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``, | 1505 | 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 | 1506 | where "4.12" is the base version of the Linux kernel with which you |
1652 | would be working). | 1507 | would be working). |
1653 | 1508 | ||
1654 | 2. *Create a Directory for Your Patches:* In the same directory inside | 1509 | #. *Create a Directory for Your Patches:* In the same directory inside |
1655 | your layer, create a matching directory to store your patches and | 1510 | your layer, create a matching directory to store your patches and |
1656 | configuration files (e.g. ``linux-yocto-myproject``). | 1511 | configuration files (e.g. ``linux-yocto-myproject``). |
1657 | 1512 | ||
1658 | 3. *Ensure You Have Configurations:* Make sure you have either a | 1513 | #. *Ensure You Have Configurations:* Make sure you have either a |
1659 | ``defconfig`` file or configuration fragment files in your layer. | 1514 | ``defconfig`` file or configuration fragment files in your layer. |
1660 | When you use the ``linux-yocto-custom.bb`` recipe, you must specify a | 1515 | 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 | 1516 | configuration. If you do not have a ``defconfig`` file, you can run |
1662 | the following: | 1517 | the following:: |
1663 | :: | ||
1664 | 1518 | ||
1665 | $ make defconfig | 1519 | $ make defconfig |
1666 | 1520 | ||
@@ -1672,7 +1526,7 @@ Here are some basic steps you can use to work with your own sources: | |||
1672 | 1526 | ||
1673 | Running the ``make defconfig`` command results in the default | 1527 | Running the ``make defconfig`` command results in the default |
1674 | configuration for your architecture as defined by your kernel. | 1528 | configuration for your architecture as defined by your kernel. |
1675 | However, no guarantee exists that this configuration is valid for | 1529 | However, there is no guarantee that this configuration is valid for |
1676 | your use case, or that your board will even boot. This is | 1530 | your use case, or that your board will even boot. This is |
1677 | particularly true for non-x86 architectures. | 1531 | particularly true for non-x86 architectures. |
1678 | 1532 | ||
@@ -1681,15 +1535,15 @@ Here are some basic steps you can use to work with your own sources: | |||
1681 | ``arch/arm/configs`` and use the one that is the best starting point | 1535 | ``arch/arm/configs`` and use the one that is the best starting point |
1682 | for your board). | 1536 | for your board). |
1683 | 1537 | ||
1684 | 4. *Edit the Recipe:* Edit the following variables in your recipe as | 1538 | #. *Edit the Recipe:* Edit the following variables in your recipe as |
1685 | appropriate for your project: | 1539 | appropriate for your project: |
1686 | 1540 | ||
1687 | - :term:`SRC_URI`: The | 1541 | - :term:`SRC_URI`: The |
1688 | ``SRC_URI`` should specify a Git repository that uses one of the | 1542 | :term:`SRC_URI` should specify a Git repository that uses one of the |
1689 | supported Git fetcher protocols (i.e. ``file``, ``git``, ``http``, | 1543 | supported Git fetcher protocols (i.e. ``file``, ``git``, ``http``, |
1690 | and so forth). The ``SRC_URI`` variable should also specify either | 1544 | and so forth). The :term:`SRC_URI` variable should also specify either |
1691 | a ``defconfig`` file or some configuration fragment files. The | 1545 | a ``defconfig`` file or some configuration fragment files. The |
1692 | skeleton recipe provides an example ``SRC_URI`` as a syntax | 1546 | skeleton recipe provides an example :term:`SRC_URI` as a syntax |
1693 | reference. | 1547 | reference. |
1694 | 1548 | ||
1695 | - :term:`LINUX_VERSION`: | 1549 | - :term:`LINUX_VERSION`: |
@@ -1707,17 +1561,16 @@ Here are some basic steps you can use to work with your own sources: | |||
1707 | indicate to the OpenEmbedded build system that the recipe has | 1561 | indicate to the OpenEmbedded build system that the recipe has |
1708 | changed. | 1562 | changed. |
1709 | 1563 | ||
1710 | - :term:`PV`: The default ``PV`` | 1564 | - :term:`PV`: The default :term:`PV` |
1711 | assignment is typically adequate. It combines the | 1565 | assignment is typically adequate. It combines the |
1712 | ``LINUX_VERSION`` with the Source Control Manager (SCM) revision | 1566 | :term:`LINUX_VERSION` with the Source Control Manager (SCM) revision |
1713 | as derived from the :term:`SRCPV` | 1567 | as derived from the :term:`SRCPV` |
1714 | variable. The combined results are a string with the following | 1568 | variable. The combined results are a string with the following |
1715 | form: | 1569 | form:: |
1716 | :: | ||
1717 | 1570 | ||
1718 | 3.19.11+git1+68a635bf8dfb64b02263c1ac80c948647cc76d5f_1+218bd8d2022b9852c60d32f0d770931e3cf343e2 | 1571 | 3.19.11+git1+68a635bf8dfb64b02263c1ac80c948647cc76d5f_1+218bd8d2022b9852c60d32f0d770931e3cf343e2 |
1719 | 1572 | ||
1720 | While lengthy, the extra verbosity in ``PV`` helps ensure you are | 1573 | While lengthy, the extra verbosity in :term:`PV` helps ensure you are |
1721 | using the exact sources from which you intend to build. | 1574 | using the exact sources from which you intend to build. |
1722 | 1575 | ||
1723 | - :term:`COMPATIBLE_MACHINE`: | 1576 | - :term:`COMPATIBLE_MACHINE`: |
@@ -1727,15 +1580,15 @@ Here are some basic steps you can use to work with your own sources: | |||
1727 | triggers an explicit build failure. You must change it to match a | 1580 | triggers an explicit build failure. You must change it to match a |
1728 | list of the machines that your new recipe supports. For example, | 1581 | list of the machines that your new recipe supports. For example, |
1729 | to support the ``qemux86`` and ``qemux86-64`` machines, use the | 1582 | to support the ``qemux86`` and ``qemux86-64`` machines, use the |
1730 | following form: | 1583 | following form:: |
1731 | :: | ||
1732 | 1584 | ||
1733 | COMPATIBLE_MACHINE = "qemux86|qemux86-64" | 1585 | COMPATIBLE_MACHINE = "qemux86|qemux86-64" |
1734 | 1586 | ||
1735 | 5. *Customize Your Recipe as Needed:* Provide further customizations to | 1587 | #. *Customize Your Recipe as Needed:* Provide further customizations to |
1736 | your recipe as needed just as you would customize an existing | 1588 | your recipe as needed just as you would customize an existing |
1737 | linux-yocto recipe. See the "`Modifying an Existing | 1589 | linux-yocto recipe. See the |
1738 | Recipe <#modifying-an-existing-recipe>`__" section for information. | 1590 | ":ref:`ref-manual/devtool-reference:modifying an existing recipe`" section |
1591 | for information. | ||
1739 | 1592 | ||
1740 | Working with Out-of-Tree Modules | 1593 | Working with Out-of-Tree Modules |
1741 | ================================ | 1594 | ================================ |
@@ -1787,11 +1640,9 @@ Linux kernel sources, if you need an external kernel module, the | |||
1787 | create your own out-of-tree Linux kernel module recipe. | 1640 | create your own out-of-tree Linux kernel module recipe. |
1788 | 1641 | ||
1789 | This template recipe is located in the ``poky`` Git repository of the | 1642 | This template recipe is located in the ``poky`` Git repository of the |
1790 | Yocto Project :yocto_git:`Source Repository <>` at: | 1643 | Yocto Project: |
1791 | 1644 | :yocto_git:`meta-skeleton/recipes-kernel/hello-mod/hello-mod_0.1.bb | |
1792 | .. code-block:: none | 1645 | </poky/tree/meta-skeleton/recipes-kernel/hello-mod/hello-mod_0.1.bb>`. |
1793 | |||
1794 | poky/meta-skeleton/recipes-kernel/hello-mod/hello-mod_0.1.bb | ||
1795 | 1646 | ||
1796 | To get started, copy this recipe to your layer and give it a meaningful | 1647 | 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 | 1648 | name (e.g. ``mymodule_1.0.bb``). In the same directory, create a new |
@@ -1810,29 +1661,26 @@ Typically, you will need to set the following variables: | |||
1810 | 1661 | ||
1811 | Depending on the build system used by the module sources, you might need | 1662 | Depending on the build system used by the module sources, you might need |
1812 | to make some adjustments. For example, a typical module ``Makefile`` | 1663 | to make some adjustments. For example, a typical module ``Makefile`` |
1813 | looks much like the one provided with the ``hello-mod`` template: | 1664 | looks much like the one provided with the ``hello-mod`` template:: |
1814 | :: | ||
1815 | 1665 | ||
1816 | obj-m := hello.o | 1666 | obj-m := hello.o |
1817 | 1667 | ||
1818 | SRC := $(shell pwd) | 1668 | SRC := $(shell pwd) |
1819 | 1669 | ||
1820 | all: | 1670 | all: |
1821 | $(MAKE) -C $(KERNEL_SRC) M=$(SRC) | 1671 | $(MAKE) -C $(KERNEL_SRC) M=$(SRC) |
1822 | 1672 | ||
1823 | modules_install: | 1673 | modules_install: |
1824 | $(MAKE) -C $(KERNEL_SRC) M=$(SRC) modules_install | 1674 | $(MAKE) -C $(KERNEL_SRC) M=$(SRC) modules_install |
1825 | ... | 1675 | ... |
1826 | 1676 | ||
1827 | The important point to note here is the :term:`KERNEL_SRC` variable. The | 1677 | 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 | 1678 | :ref:`ref-classes-module` class sets this variable and the :term:`KERNEL_PATH` |
1829 | :term:`KERNEL_PATH` variable to | 1679 | variable to ``${STAGING_KERNEL_DIR}`` with the necessary Linux kernel build |
1830 | ``${STAGING_KERNEL_DIR}`` with the necessary Linux kernel build | 1680 | information to build modules. If your module ``Makefile`` uses a different |
1831 | information to build modules. If your module ``Makefile`` uses a | 1681 | variable, you might want to override the :ref:`ref-tasks-compile` step, or |
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 | 1682 | create a patch to the ``Makefile`` to work with the more typical |
1835 | ``KERNEL_SRC`` or ``KERNEL_PATH`` variables. | 1683 | :term:`KERNEL_SRC` or :term:`KERNEL_PATH` variables. |
1836 | 1684 | ||
1837 | After you have prepared your recipe, you will likely want to include the | 1685 | 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 | 1686 | module in your images. To do this, see the documentation for the |
@@ -1848,8 +1696,7 @@ them appropriately for your machine configuration file: | |||
1848 | - :term:`MACHINE_EXTRA_RRECOMMENDS` | 1696 | - :term:`MACHINE_EXTRA_RRECOMMENDS` |
1849 | 1697 | ||
1850 | Modules are often not required for boot and can be excluded from certain | 1698 | Modules are often not required for boot and can be excluded from certain |
1851 | build configurations. The following allows for the most flexibility: | 1699 | build configurations. The following allows for the most flexibility:: |
1852 | :: | ||
1853 | 1700 | ||
1854 | MACHINE_EXTRA_RRECOMMENDS += "kernel-module-mymodule" | 1701 | MACHINE_EXTRA_RRECOMMENDS += "kernel-module-mymodule" |
1855 | 1702 | ||
@@ -1873,7 +1720,7 @@ tree. Using Git is an efficient way to see what has changed in the tree. | |||
1873 | What Changed in a Kernel? | 1720 | What Changed in a Kernel? |
1874 | ------------------------- | 1721 | ------------------------- |
1875 | 1722 | ||
1876 | Following are a few examples that show how to use Git commands to | 1723 | Here 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 | 1724 | examine changes. These examples are by no means the only way to see |
1878 | changes. | 1725 | changes. |
1879 | 1726 | ||
@@ -1893,31 +1740,26 @@ 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 | 1740 | 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 | 1741 | commit associated with the ``standard/base`` branch, while the upper |
1895 | commit range is the commit associated with the ``standard/emenlow`` | 1742 | commit range is the commit associated with the ``standard/emenlow`` |
1896 | branch. | 1743 | branch:: |
1897 | :: | ||
1898 | 1744 | ||
1899 | $ git whatchanged origin/standard/base..origin/standard/emenlow | 1745 | $ git whatchanged origin/standard/base..origin/standard/emenlow |
1900 | 1746 | ||
1901 | To see short, one line summaries of changes use the ``git log`` command: | 1747 | To see short, one line summaries of changes use the ``git log`` command:: |
1902 | :: | ||
1903 | 1748 | ||
1904 | $ git log --oneline origin/standard/base..origin/standard/emenlow | 1749 | $ git log --oneline origin/standard/base..origin/standard/emenlow |
1905 | 1750 | ||
1906 | Use this command to see code differences for the changes: | 1751 | Use this command to see code differences for the changes:: |
1907 | :: | ||
1908 | 1752 | ||
1909 | $ git diff origin/standard/base..origin/standard/emenlow | 1753 | $ git diff origin/standard/base..origin/standard/emenlow |
1910 | 1754 | ||
1911 | Use this command to see the commit log messages and the text | 1755 | Use this command to see the commit log messages and the text |
1912 | differences: | 1756 | differences:: |
1913 | :: | ||
1914 | 1757 | ||
1915 | $ git show origin/standard/base..origin/standard/emenlow | 1758 | $ git show origin/standard/base..origin/standard/emenlow |
1916 | 1759 | ||
1917 | Use this command to create individual patches for each change. Here is | 1760 | 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 | 1761 | an example that creates patch files for each commit and places them |
1919 | in your ``Documents`` directory: | 1762 | in your ``Documents`` directory:: |
1920 | :: | ||
1921 | 1763 | ||
1922 | $ git format-patch -o $HOME/Documents origin/standard/base..origin/standard/emenlow | 1764 | $ git format-patch -o $HOME/Documents origin/standard/base..origin/standard/emenlow |
1923 | 1765 | ||
@@ -1926,15 +1768,13 @@ Showing a Particular Feature or Branch Change | |||
1926 | 1768 | ||
1927 | Tags in the Yocto Project kernel tree divide changes for significant | 1769 | Tags in the Yocto Project kernel tree divide changes for significant |
1928 | features or branches. The ``git show``Â tag command shows changes based | 1770 | features or branches. The ``git show``Â tag command shows changes based |
1929 | on a tag. Here is an example that shows ``systemtap`` changes: | 1771 | on a tag. Here is an example that shows ``systemtap`` changes:: |
1930 | :: | ||
1931 | 1772 | ||
1932 | $ git show systemtap | 1773 | $ git show systemtap |
1933 | 1774 | ||
1934 | You can use the ``git branch --contains``Â tag command to | 1775 | You can use the ``git branch --contains``Â tag command to |
1935 | show the branches that contain a particular feature. This command shows | 1776 | show the branches that contain a particular feature. This command shows |
1936 | the branches that contain the ``systemtap`` feature: | 1777 | the branches that contain the ``systemtap`` feature:: |
1937 | :: | ||
1938 | 1778 | ||
1939 | $ git branch --contains systemtap | 1779 | $ git branch --contains systemtap |
1940 | 1780 | ||
@@ -1952,31 +1792,31 @@ build stops. Kernel features are the last elements processed for | |||
1952 | configuring and patching the kernel. Therefore, adding features in this | 1792 | configuring and patching the kernel. Therefore, adding features in this |
1953 | manner is a way to enforce specific features are present and enabled | 1793 | 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 | 1794 | without needing to do a full audit of any other layer's additions to the |
1955 | ``SRC_URI`` statement. | 1795 | :term:`SRC_URI` statement. |
1956 | 1796 | ||
1957 | You add a kernel feature by providing the feature as part of the | 1797 | 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 | 1798 | :term:`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 | 1799 | ``.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 | 1800 | OpenEmbedded build system searches all forms of kernel Metadata on the |
1961 | ``SRC_URI`` statement regardless of whether the Metadata is in the | 1801 | :term:`SRC_URI` statement regardless of whether the Metadata is in the |
1962 | "kernel-cache", system kernel Metadata, or a recipe-space Metadata (i.e. | 1802 | "kernel-cache", system kernel Metadata, or a recipe-space Metadata (i.e. |
1963 | part of the kernel recipe). See the | 1803 | part of the kernel recipe). See the |
1964 | ":ref:`kernel-dev/advanced:kernel metadata location`" section for | 1804 | ":ref:`kernel-dev/advanced:kernel metadata location`" section for |
1965 | additional information. | 1805 | additional information. |
1966 | 1806 | ||
1967 | When you specify the feature's ``.scc`` file on the ``SRC_URI`` | 1807 | When you specify the feature's ``.scc`` file on the :term:`SRC_URI` |
1968 | statement, the OpenEmbedded build system adds the directory of that | 1808 | statement, the OpenEmbedded build system adds the directory of that |
1969 | ``.scc`` file along with all its subdirectories to the kernel feature | 1809 | ``.scc`` file along with all its subdirectories to the kernel feature |
1970 | search path. Because subdirectories are searched, you can reference a | 1810 | search path. Because subdirectories are searched, you can reference a |
1971 | single ``.scc`` file in the ``SRC_URI`` statement to reference multiple | 1811 | single ``.scc`` file in the :term:`SRC_URI` statement to reference multiple |
1972 | kernel features. | 1812 | kernel features. |
1973 | 1813 | ||
1974 | Consider the following example that adds the "test.scc" feature to the | 1814 | Consider the following example that adds the "test.scc" feature to the |
1975 | build. | 1815 | build. |
1976 | 1816 | ||
1977 | 1. *Create the Feature File:* Create a ``.scc`` file and locate it just | 1817 | #. *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 | 1818 | as you would any other patch file, ``.cfg`` file, or fetcher item you |
1979 | specify in the ``SRC_URI`` statement. | 1819 | specify in the :term:`SRC_URI` statement. |
1980 | 1820 | ||
1981 | .. note:: | 1821 | .. note:: |
1982 | 1822 | ||
@@ -1989,8 +1829,7 @@ build. | |||
1989 | searched during the build as potential feature directories. | 1829 | searched during the build as potential feature directories. |
1990 | 1830 | ||
1991 | Continuing with the example, suppose the "test.scc" feature you are | 1831 | Continuing with the example, suppose the "test.scc" feature you are |
1992 | adding has a ``test.scc`` file in the following directory: | 1832 | adding has a ``test.scc`` file in the following directory:: |
1993 | :: | ||
1994 | 1833 | ||
1995 | my_recipe | 1834 | my_recipe |
1996 | | | 1835 | | |
@@ -2003,21 +1842,19 @@ build. | |||
2003 | ``linux-yocto`` directory has both the feature ``test.scc`` file and | 1842 | ``linux-yocto`` directory has both the feature ``test.scc`` file and |
2004 | a similarly named configuration fragment file ``test.cfg``. | 1843 | a similarly named configuration fragment file ``test.cfg``. |
2005 | 1844 | ||
2006 | 2. *Add the Feature File to SRC_URI:* Add the ``.scc`` file to the | 1845 | #. *Add the Feature File to SRC_URI:* Add the ``.scc`` file to the |
2007 | recipe's ``SRC_URI`` statement: | 1846 | recipe's :term:`SRC_URI` statement:: |
2008 | :: | ||
2009 | 1847 | ||
2010 | SRC_URI_append = " file://test.scc" | 1848 | SRC_URI += "file://test.scc" |
2011 | 1849 | ||
2012 | The leading space before the path is important as the path is | 1850 | The leading space before the path is important as the path is |
2013 | appended to the existing path. | 1851 | appended to the existing path. |
2014 | 1852 | ||
2015 | 3. *Specify the Feature as a Kernel Feature:* Use the | 1853 | #. *Specify the Feature as a Kernel Feature:* Use the |
2016 | ``KERNEL_FEATURES`` statement to specify the feature as a kernel | 1854 | :term:`KERNEL_FEATURES` statement to specify the feature as a kernel |
2017 | feature: | 1855 | feature:: |
2018 | :: | ||
2019 | 1856 | ||
2020 | KERNEL_FEATURES_append = " test.scc" | 1857 | KERNEL_FEATURES += "test.scc" |
2021 | 1858 | ||
2022 | The OpenEmbedded build | 1859 | The OpenEmbedded build |
2023 | system processes the kernel feature when it builds the kernel. | 1860 | system processes the kernel feature when it builds the kernel. |
diff --git a/documentation/kernel-dev/concepts-appx.rst b/documentation/kernel-dev/concepts-appx.rst index 4b6dbe5ef9..6a2fe4bb0b 100644 --- a/documentation/kernel-dev/concepts-appx.rst +++ b/documentation/kernel-dev/concepts-appx.rst | |||
@@ -117,7 +117,7 @@ upstream Linux kernel development and are managed by the Yocto Project | |||
117 | team's Yocto Linux kernel development strategy. It is the Yocto Project | 117 | team's Yocto Linux kernel development strategy. It is the Yocto Project |
118 | team's policy to not back-port minor features to the released Yocto | 118 | team's policy to not back-port minor features to the released Yocto |
119 | Linux kernel. They only consider back-porting significant technological | 119 | Linux kernel. They only consider back-porting significant technological |
120 | jumps - and, that is done after a complete gap analysis. The reason | 120 | jumps --- and, that is done after a complete gap analysis. The reason |
121 | for this policy is that back-porting any small to medium sized change | 121 | for this policy is that back-porting any small to medium sized change |
122 | from an evolving Linux kernel can easily create mismatches, | 122 | from an evolving Linux kernel can easily create mismatches, |
123 | incompatibilities and very subtle errors. | 123 | incompatibilities and very subtle errors. |
@@ -211,9 +211,9 @@ view, there is a linear path that travels from the baseline | |||
211 | ``kernel.org``, through a select group of features and ends with their | 211 | ``kernel.org``, through a select group of features and ends with their |
212 | BSP-specific commits. In other words, the divisions of the kernel are | 212 | BSP-specific commits. In other words, the divisions of the kernel are |
213 | transparent and are not relevant to the developer on a day-to-day basis. | 213 | transparent and are not relevant to the developer on a day-to-day basis. |
214 | From the developer's perspective, this path is the "master" branch in | 214 | From the developer's perspective, this path is the development branch. |
215 | Git terms. The developer does not need to be aware of the existence of | 215 | The developer does not need to be aware of the existence of |
216 | any other branches at all. Of course, value exists in the having these | 216 | any other branches at all. Of course, it can make sense to have these |
217 | branches in the tree, should a person decide to explore them. For | 217 | branches in the tree, should a person decide to explore them. For |
218 | example, a comparison between two BSPs at either the commit level or at | 218 | example, a comparison between two BSPs at either the commit level or at |
219 | the line-by-line code ``diff`` level is now a trivial operation. | 219 | the line-by-line code ``diff`` level is now a trivial operation. |
@@ -221,7 +221,7 @@ the line-by-line code ``diff`` level is now a trivial operation. | |||
221 | The following illustration shows the conceptual Yocto Linux kernel. | 221 | The following illustration shows the conceptual Yocto Linux kernel. |
222 | 222 | ||
223 | .. image:: figures/kernel-architecture-overview.png | 223 | .. image:: figures/kernel-architecture-overview.png |
224 | :align: center | 224 | :width: 100% |
225 | 225 | ||
226 | In the illustration, the "Kernel.org Branch Point" marks the specific | 226 | In the illustration, the "Kernel.org Branch Point" marks the specific |
227 | spot (or Linux kernel release) from which the Yocto Linux kernel is | 227 | spot (or Linux kernel release) from which the Yocto Linux kernel is |
@@ -318,12 +318,12 @@ tree specific to your kernel from which to generate the new kernel | |||
318 | image. | 318 | image. |
319 | 319 | ||
320 | The following figure shows the temporary file structure created on your | 320 | The following figure shows the temporary file structure created on your |
321 | host system when you build the kernel using Bitbake. This | 321 | host system when you build the kernel using BitBake. This |
322 | :term:`Build Directory` contains all the | 322 | :term:`Build Directory` contains all the source files used during the build. |
323 | source files used during the build. | ||
324 | 323 | ||
325 | .. image:: figures/kernel-overview-2-generic.png | 324 | .. image:: figures/kernel-overview-2-generic.png |
326 | :align: center | 325 | :align: center |
326 | :width: 70% | ||
327 | 327 | ||
328 | Again, for additional information on the Yocto Project kernel's | 328 | Again, for additional information on the Yocto Project kernel's |
329 | architecture and its branching strategy, see the | 329 | architecture and its branching strategy, see the |
@@ -359,8 +359,7 @@ To determine whether or not a given option is "hardware" or | |||
359 | "non-hardware", the kernel Metadata in ``yocto-kernel-cache`` contains | 359 | "non-hardware", the kernel Metadata in ``yocto-kernel-cache`` contains |
360 | files that classify individual or groups of options as either hardware | 360 | files that classify individual or groups of options as either hardware |
361 | or non-hardware. To better show this, consider a situation where the | 361 | or non-hardware. To better show this, consider a situation where the |
362 | ``yocto-kernel-cache`` contains the following files: | 362 | ``yocto-kernel-cache`` contains the following files:: |
363 | :: | ||
364 | 363 | ||
365 | yocto-kernel-cache/features/drm-psb/hardware.cfg | 364 | yocto-kernel-cache/features/drm-psb/hardware.cfg |
366 | yocto-kernel-cache/features/kgdb/hardware.cfg | 365 | yocto-kernel-cache/features/kgdb/hardware.cfg |
@@ -380,8 +379,7 @@ or non-hardware. To better show this, consider a situation where the | |||
380 | yocto-kernel-cache/ktypes/base/hardware.kcf | 379 | yocto-kernel-cache/ktypes/base/hardware.kcf |
381 | yocto-kernel-cache/bsp/qemu-ppc32/hardware.kcf | 380 | yocto-kernel-cache/bsp/qemu-ppc32/hardware.kcf |
382 | 381 | ||
383 | The following list | 382 | Here are explanations for the various files: |
384 | provides explanations for the various files: | ||
385 | 383 | ||
386 | - ``hardware.kcf``: Specifies a list of kernel Kconfig files that | 384 | - ``hardware.kcf``: Specifies a list of kernel Kconfig files that |
387 | contain hardware options only. | 385 | contain hardware options only. |
@@ -400,8 +398,7 @@ provides explanations for the various files: | |||
400 | (i.e. ``hardware.kcf`` or ``non-hardware.kcf``). | 398 | (i.e. ``hardware.kcf`` or ``non-hardware.kcf``). |
401 | 399 | ||
402 | Here is a specific example using the | 400 | Here is a specific example using the |
403 | ``kernel-cache/bsp/mti-malta32/hardware.cfg``: | 401 | ``kernel-cache/bsp/mti-malta32/hardware.cfg``:: |
404 | :: | ||
405 | 402 | ||
406 | CONFIG_SERIAL_8250 | 403 | CONFIG_SERIAL_8250 |
407 | CONFIG_SERIAL_8250_CONSOLE | 404 | CONFIG_SERIAL_8250_CONSOLE |
diff --git a/documentation/kernel-dev/faq.rst b/documentation/kernel-dev/faq.rst index c2106f81e1..4dffa90dbd 100644 --- a/documentation/kernel-dev/faq.rst +++ b/documentation/kernel-dev/faq.rst | |||
@@ -7,7 +7,7 @@ Kernel Development FAQ | |||
7 | Common Questions and Solutions | 7 | Common Questions and Solutions |
8 | ============================== | 8 | ============================== |
9 | 9 | ||
10 | The following lists some solutions for common questions. | 10 | Here are some solutions for common questions. |
11 | 11 | ||
12 | How do I use my own Linux kernel ``.config`` file? | 12 | How do I use my own Linux kernel ``.config`` file? |
13 | -------------------------------------------------- | 13 | -------------------------------------------------- |
@@ -30,15 +30,15 @@ Refer to the | |||
30 | ":ref:`kernel-dev/common:working with your own sources`" | 30 | ":ref:`kernel-dev/common:working with your own sources`" |
31 | section for information. | 31 | section for information. |
32 | 32 | ||
33 | How do I install/not-install the kernel image on the rootfs? | 33 | How do I install/not-install the kernel image on the root filesystem? |
34 | ------------------------------------------------------------ | 34 | --------------------------------------------------------------------- |
35 | 35 | ||
36 | The kernel image (e.g. ``vmlinuz``) is provided by the | 36 | The kernel image (e.g. ``vmlinuz``) is provided by the |
37 | ``kernel-image`` package. Image recipes depend on ``kernel-base``. To | 37 | ``kernel-image`` package. Image recipes depend on ``kernel-base``. To |
38 | specify whether or not the kernel image is installed in the generated | 38 | specify whether or not the kernel image is installed in the generated |
39 | root filesystem, override ``RDEPENDS_${KERNEL_PACKAGE_NAME}-base`` to include or not | 39 | root filesystem, override ``RRECOMMENDS:${KERNEL_PACKAGE_NAME}-base`` to include or not |
40 | include "kernel-image". See the | 40 | include "kernel-image". See the |
41 | ":ref:`dev-manual/common-tasks:using .bbappend files in your layer`" | 41 | ":ref:`dev-manual/layers:appending other layers metadata with your layer`" |
42 | section in the | 42 | section in the |
43 | Yocto Project Development Tasks Manual for information on how to use an | 43 | Yocto Project Development Tasks Manual for information on how to use an |
44 | append file to override metadata. | 44 | append file to override metadata. |
@@ -57,8 +57,7 @@ These other variables are useful for installing specific modules: | |||
57 | 57 | ||
58 | For example, set the following in the ``qemux86.conf`` file to include | 58 | For example, set the following in the ``qemux86.conf`` file to include |
59 | the ``ab123`` kernel modules with images built for the ``qemux86`` | 59 | the ``ab123`` kernel modules with images built for the ``qemux86`` |
60 | machine: | 60 | machine:: |
61 | :: | ||
62 | 61 | ||
63 | MACHINE_EXTRA_RRECOMMENDS += "kernel-module-ab123" | 62 | MACHINE_EXTRA_RRECOMMENDS += "kernel-module-ab123" |
64 | 63 | ||
@@ -69,10 +68,9 @@ How do I change the Linux kernel command line? | |||
69 | ---------------------------------------------- | 68 | ---------------------------------------------- |
70 | 69 | ||
71 | The Linux kernel command line is | 70 | The Linux kernel command line is |
72 | typically specified in the machine config using the ``APPEND`` variable. | 71 | typically specified in the machine config using the :term:`APPEND` variable. |
73 | For example, you can add some helpful debug information doing the | 72 | For example, you can add some helpful debug information doing the |
74 | following: | 73 | following:: |
75 | :: | ||
76 | 74 | ||
77 | APPEND += "printk.time=y initcall_debug debug" | 75 | APPEND += "printk.time=y initcall_debug debug" |
78 | 76 | ||
diff --git a/documentation/kernel-dev/history.rst b/documentation/kernel-dev/history.rst deleted file mode 100644 index 761b506aca..0000000000 --- a/documentation/kernel-dev/history.rst +++ /dev/null | |||
@@ -1,58 +0,0 @@ | |||
1 | .. SPDX-License-Identifier: CC-BY-SA-2.0-UK | ||
2 | |||
3 | *********************** | ||
4 | Manual Revision History | ||
5 | *********************** | ||
6 | |||
7 | .. list-table:: | ||
8 | :widths: 10 15 40 | ||
9 | :header-rows: 1 | ||
10 | |||
11 | * - Revision | ||
12 | - Date | ||
13 | - Note | ||
14 | * - 1.4 | ||
15 | - April 2013 | ||
16 | - The initial document released with the Yocto Project 1.4 Release | ||
17 | * - 1.5 | ||
18 | - October 2013 | ||
19 | - Released with the Yocto Project 1.5 Release. | ||
20 | * - 1.6 | ||
21 | - April 2014 | ||
22 | - Released with the Yocto Project 1.6 Release. | ||
23 | * - 1.7 | ||
24 | - October 2014 | ||
25 | - Released with the Yocto Project 1.7 Release. | ||
26 | * - 1.8 | ||
27 | - April 2015 | ||
28 | - Released with the Yocto Project 1.8 Release. | ||
29 | * - 2.0 | ||
30 | - October 2015 | ||
31 | - Released with the Yocto Project 2.0 Release. | ||
32 | * - 2.1 | ||
33 | - April 2016 | ||
34 | - Released with the Yocto Project 2.1 Release. | ||
35 | * - 2.2 | ||
36 | - October 2016 | ||
37 | - Released with the Yocto Project 2.2 Release. | ||
38 | * - 2.3 | ||
39 | - May 2017 | ||
40 | - Released with the Yocto Project 2.3 Release. | ||
41 | * - 2.4 | ||
42 | - October 2017 | ||
43 | - Released with the Yocto Project 2.4 Release. | ||
44 | * - 2.5 | ||
45 | - May 2018 | ||
46 | - Released with the Yocto Project 2.5 Release. | ||
47 | * - 2.6 | ||
48 | - November 2018 | ||
49 | - Released with the Yocto Project 2.6 Release. | ||
50 | * - 2.7 | ||
51 | - May 2019 | ||
52 | - Released with the Yocto Project 2.7 Release. | ||
53 | * - 3.0 | ||
54 | - October 2019 | ||
55 | - Released with the Yocto Project 3.0 Release. | ||
56 | * - 3.1 | ||
57 | - April 2020 | ||
58 | - Released with the Yocto Project 3.1 Release. | ||
diff --git a/documentation/kernel-dev/index.rst b/documentation/kernel-dev/index.rst index a8848ec8cc..bd20e371e0 100644 --- a/documentation/kernel-dev/index.rst +++ b/documentation/kernel-dev/index.rst | |||
@@ -16,6 +16,5 @@ Yocto Project Linux Kernel Development Manual | |||
16 | concepts-appx | 16 | concepts-appx |
17 | maint-appx | 17 | maint-appx |
18 | faq | 18 | faq |
19 | history | ||
20 | 19 | ||
21 | .. include:: /boilerplate.rst | 20 | .. include:: /boilerplate.rst |
diff --git a/documentation/kernel-dev/intro.rst b/documentation/kernel-dev/intro.rst index f6c9b97137..a663733a1d 100644 --- a/documentation/kernel-dev/intro.rst +++ b/documentation/kernel-dev/intro.rst | |||
@@ -66,9 +66,9 @@ from the continual kernel integration and testing performed during | |||
66 | development of the Yocto Project. | 66 | development of the Yocto Project. |
67 | 67 | ||
68 | If, instead, you have a very specific Linux kernel source tree and are | 68 | If, instead, you have a very specific Linux kernel source tree and are |
69 | unable to align with one of the official Yocto Linux kernel recipes, an | 69 | unable to align with one of the official Yocto Linux kernel recipes, |
70 | alternative exists by which you can use the Yocto Project Linux kernel | 70 | you have a way to use the Yocto Project Linux kernel tools with your |
71 | tools with your own kernel sources. | 71 | own kernel sources. |
72 | 72 | ||
73 | The remainder of this manual provides instructions for completing | 73 | The remainder of this manual provides instructions for completing |
74 | specific Linux kernel development tasks. These instructions assume you | 74 | specific Linux kernel development tasks. These instructions assume you |
@@ -87,11 +87,10 @@ understand the following documentation: | |||
87 | as described in the Yocto Project Application Development and the | 87 | as described in the Yocto Project Application Development and the |
88 | Extensible Software Development Kit (eSDK) manual. | 88 | Extensible Software Development Kit (eSDK) manual. |
89 | 89 | ||
90 | - The ":ref:`dev-manual/common-tasks:understanding and creating layers`" | 90 | - The ":ref:`dev-manual/layers:understanding and creating layers`" |
91 | section in the Yocto Project Development Tasks Manual. | 91 | section in the Yocto Project Development Tasks Manual. |
92 | 92 | ||
93 | - The "`Kernel Modification | 93 | - The ":ref:`kernel-dev/intro:kernel modification workflow`" section. |
94 | Workflow <#kernel-modification-workflow>`__" section. | ||
95 | 94 | ||
96 | Kernel Modification Workflow | 95 | Kernel Modification Workflow |
97 | ============================ | 96 | ============================ |
@@ -107,21 +106,21 @@ modification workflow. The illustration and accompanying list provide | |||
107 | general information and references for further information. | 106 | general information and references for further information. |
108 | 107 | ||
109 | .. image:: figures/kernel-dev-flow.png | 108 | .. image:: figures/kernel-dev-flow.png |
110 | :align: center | 109 | :width: 100% |
111 | 110 | ||
112 | 1. *Set up Your Host Development System to Support Development Using the | 111 | #. *Set up Your Host Development System to Support Development Using the |
113 | Yocto Project*: See the ":doc:`/dev-manual/start`" section in | 112 | Yocto Project*: See the ":doc:`/dev-manual/start`" section in |
114 | the Yocto Project Development Tasks Manual for options on how to get | 113 | the Yocto Project Development Tasks Manual for options on how to get |
115 | a build host ready to use the Yocto Project. | 114 | a build host ready to use the Yocto Project. |
116 | 115 | ||
117 | 2. *Set Up Your Host Development System for Kernel Development:* It is | 116 | #. *Set Up Your Host Development System for Kernel Development:* It is |
118 | recommended that you use ``devtool`` and an extensible SDK for kernel | 117 | recommended that you use ``devtool`` for kernel |
119 | development. Alternatively, you can use traditional kernel | 118 | development. Alternatively, you can use traditional kernel |
120 | development methods with the Yocto Project. Either way, there are | 119 | development methods with the Yocto Project. Either way, there are |
121 | steps you need to take to get the development environment ready. | 120 | steps you need to take to get the development environment ready. |
122 | 121 | ||
123 | Using ``devtool`` and the eSDK requires that you have a clean build | 122 | Using ``devtool`` requires that you have a clean build |
124 | of the image and that you are set up with the appropriate eSDK. For | 123 | of the image. For |
125 | more information, see the | 124 | more information, see the |
126 | ":ref:`kernel-dev/common:getting ready to develop using \`\`devtool\`\``" | 125 | ":ref:`kernel-dev/common:getting ready to develop using \`\`devtool\`\``" |
127 | section. | 126 | section. |
@@ -132,10 +131,10 @@ general information and references for further information. | |||
132 | ":ref:`kernel-dev/common:getting ready for traditional kernel development`" | 131 | ":ref:`kernel-dev/common:getting ready for traditional kernel development`" |
133 | section. | 132 | section. |
134 | 133 | ||
135 | 3. *Make Changes to the Kernel Source Code if applicable:* Modifying the | 134 | #. *Make Changes to the Kernel Source Code if applicable:* Modifying the |
136 | kernel does not always mean directly changing source files. However, | 135 | kernel does not always mean directly changing source files. However, |
137 | if you have to do this, you make the changes to the files in the | 136 | if you have to do this, you make the changes to the files in the |
138 | eSDK's Build Directory if you are using ``devtool``. For more | 137 | Yocto's :term:`Build Directory` if you are using ``devtool``. For more |
139 | information, see the | 138 | information, see the |
140 | ":ref:`kernel-dev/common:using \`\`devtool\`\` to patch the kernel`" | 139 | ":ref:`kernel-dev/common:using \`\`devtool\`\` to patch the kernel`" |
141 | section. | 140 | section. |
@@ -145,7 +144,7 @@ general information and references for further information. | |||
145 | ":ref:`kernel-dev/common:using traditional kernel development to patch the kernel`" | 144 | ":ref:`kernel-dev/common:using traditional kernel development to patch the kernel`" |
146 | section. | 145 | section. |
147 | 146 | ||
148 | 4. *Make Kernel Configuration Changes if Applicable:* If your situation | 147 | #. *Make Kernel Configuration Changes if Applicable:* If your situation |
149 | calls for changing the kernel's configuration, you can use | 148 | calls for changing the kernel's configuration, you can use |
150 | :ref:`menuconfig <kernel-dev/common:using \`\`menuconfig\`\`>`, | 149 | :ref:`menuconfig <kernel-dev/common:using \`\`menuconfig\`\`>`, |
151 | which allows you to | 150 | which allows you to |
@@ -156,7 +155,7 @@ general information and references for further information. | |||
156 | .. note:: | 155 | .. note:: |
157 | 156 | ||
158 | Try to resist the temptation to directly edit an existing ``.config`` | 157 | Try to resist the temptation to directly edit an existing ``.config`` |
159 | file, which is found in the Build Directory among the source code | 158 | file, which is found in the :term:`Build Directory` among the source code |
160 | used for the build. Doing so, can produce unexpected results when | 159 | used for the build. Doing so, can produce unexpected results when |
161 | the OpenEmbedded build system regenerates the configuration file. | 160 | the OpenEmbedded build system regenerates the configuration file. |
162 | 161 | ||
@@ -170,7 +169,7 @@ general information and references for further information. | |||
170 | Additionally, if you are working in a BSP layer and need to modify | 169 | Additionally, if you are working in a BSP layer and need to modify |
171 | the BSP's kernel's configuration, you can use ``menuconfig``. | 170 | the BSP's kernel's configuration, you can use ``menuconfig``. |
172 | 171 | ||
173 | 5. *Rebuild the Kernel Image With Your Changes:* Rebuilding the kernel | 172 | #. *Rebuild the Kernel Image With Your Changes:* Rebuilding the kernel |
174 | image applies your changes. Depending on your target hardware, you | 173 | image applies your changes. Depending on your target hardware, you |
175 | can verify your changes on actual hardware or perhaps QEMU. | 174 | can verify your changes on actual hardware or perhaps QEMU. |
176 | 175 | ||
diff --git a/documentation/kernel-dev/maint-appx.rst b/documentation/kernel-dev/maint-appx.rst index 89f4b43343..53b7376089 100644 --- a/documentation/kernel-dev/maint-appx.rst +++ b/documentation/kernel-dev/maint-appx.rst | |||
@@ -28,8 +28,7 @@ in the Yocto Project Linux kernel in any clone of the Yocto Project | |||
28 | Linux kernel source repository and ``yocto-kernel-cache`` Git trees. For | 28 | Linux kernel source repository and ``yocto-kernel-cache`` Git trees. For |
29 | example, the following commands clone the Yocto Project baseline Linux | 29 | example, the following commands clone the Yocto Project baseline Linux |
30 | kernel that branches off ``linux.org`` version 4.12 and the | 30 | kernel that branches off ``linux.org`` version 4.12 and the |
31 | ``yocto-kernel-cache``, which contains stores of kernel Metadata: | 31 | ``yocto-kernel-cache``, which contains stores of kernel Metadata:: |
32 | :: | ||
33 | 32 | ||
34 | $ git clone git://git.yoctoproject.org/linux-yocto-4.12 | 33 | $ git clone git://git.yoctoproject.org/linux-yocto-4.12 |
35 | $ git clone git://git.yoctoproject.org/linux-kernel-cache | 34 | $ git clone git://git.yoctoproject.org/linux-kernel-cache |
@@ -42,16 +41,14 @@ section. | |||
42 | 41 | ||
43 | Once you have cloned the kernel Git repository and the cache of Metadata | 42 | Once you have cloned the kernel Git repository and the cache of Metadata |
44 | on your local machine, you can discover the branches that are available | 43 | on your local machine, you can discover the branches that are available |
45 | in the repository using the following Git command: | 44 | in the repository using the following Git command:: |
46 | :: | ||
47 | 45 | ||
48 | $ git branch -a | 46 | $ git branch -a |
49 | 47 | ||
50 | Checking out a branch allows you to work with a particular Yocto Linux | 48 | Checking out a branch allows you to work with a particular Yocto Linux |
51 | kernel. For example, the following commands check out the | 49 | kernel. For example, the following commands check out the |
52 | "standard/beagleboard" branch of the Yocto Linux kernel repository and | 50 | "standard/beagleboard" branch of the Yocto Linux kernel repository and |
53 | the "yocto-4.12" branch of the ``yocto-kernel-cache`` repository: | 51 | the "yocto-4.12" branch of the ``yocto-kernel-cache`` repository:: |
54 | :: | ||
55 | 52 | ||
56 | $ cd ~/linux-yocto-4.12 | 53 | $ cd ~/linux-yocto-4.12 |
57 | $ git checkout -b my-kernel-4.12 remotes/origin/standard/beagleboard | 54 | $ git checkout -b my-kernel-4.12 remotes/origin/standard/beagleboard |
@@ -64,7 +61,7 @@ the "yocto-4.12" branch of the ``yocto-kernel-cache`` repository: | |||
64 | kernel versions (e.g. "yocto-4.12", "yocto-4.10", "yocto-4.9", and so forth). | 61 | kernel versions (e.g. "yocto-4.12", "yocto-4.10", "yocto-4.9", and so forth). |
65 | 62 | ||
66 | Once you have checked out and switched to appropriate branches, you can | 63 | Once you have checked out and switched to appropriate branches, you can |
67 | see a snapshot of all the kernel source files used to used to build that | 64 | see a snapshot of all the kernel source files used to build that |
68 | particular Yocto Linux kernel for a particular board. | 65 | particular Yocto Linux kernel for a particular board. |
69 | 66 | ||
70 | To see the features and configurations for a particular Yocto Linux | 67 | To see the features and configurations for a particular Yocto Linux |
@@ -95,11 +92,11 @@ top-level kernel feature or BSP. The following actions effectively | |||
95 | provide the Metadata and create the tree that includes the new feature, | 92 | provide the Metadata and create the tree that includes the new feature, |
96 | patch, or BSP: | 93 | patch, or BSP: |
97 | 94 | ||
98 | 1. *Pass Feature to the OpenEmbedded Build System:* A top-level kernel | 95 | #. *Pass Feature to the OpenEmbedded Build System:* A top-level kernel |
99 | feature is passed to the kernel build subsystem. Normally, this | 96 | feature is passed to the kernel build subsystem. Normally, this |
100 | feature is a BSP for a particular kernel type. | 97 | feature is a BSP for a particular kernel type. |
101 | 98 | ||
102 | 2. *Locate Feature:* The file that describes the top-level feature is | 99 | #. *Locate Feature:* The file that describes the top-level feature is |
103 | located by searching these system directories: | 100 | located by searching these system directories: |
104 | 101 | ||
105 | - The in-tree kernel-cache directories, which are located in the | 102 | - The in-tree kernel-cache directories, which are located in the |
@@ -107,40 +104,39 @@ patch, or BSP: | |||
107 | repository organized under the "Yocto Linux Kernel" heading in the | 104 | repository organized under the "Yocto Linux Kernel" heading in the |
108 | :yocto_git:`Yocto Project Source Repositories <>`. | 105 | :yocto_git:`Yocto Project Source Repositories <>`. |
109 | 106 | ||
110 | - Areas pointed to by ``SRC_URI`` statements found in kernel recipes. | 107 | - Areas pointed to by :term:`SRC_URI` statements found in kernel recipes. |
111 | 108 | ||
112 | For a typical build, the target of the search is a feature | 109 | For a typical build, the target of the search is a feature |
113 | description in an ``.scc`` file whose name follows this format (e.g. | 110 | description in an ``.scc`` file whose name follows this format (e.g. |
114 | ``beaglebone-standard.scc`` and ``beaglebone-preempt-rt.scc``): | 111 | ``beaglebone-standard.scc`` and ``beaglebone-preempt-rt.scc``):: |
115 | :: | ||
116 | 112 | ||
117 | bsp_root_name-kernel_type.scc | 113 | bsp_root_name-kernel_type.scc |
118 | 114 | ||
119 | 3. *Expand Feature:* Once located, the feature description is either | 115 | #. *Expand Feature:* Once located, the feature description is either |
120 | expanded into a simple script of actions, or into an existing | 116 | expanded into a simple script of actions, or into an existing |
121 | equivalent script that is already part of the shipped kernel. | 117 | equivalent script that is already part of the shipped kernel. |
122 | 118 | ||
123 | 4. *Append Extra Features:* Extra features are appended to the top-level | 119 | #. *Append Extra Features:* Extra features are appended to the top-level |
124 | feature description. These features can come from the | 120 | feature description. These features can come from the |
125 | :term:`KERNEL_FEATURES` | 121 | :term:`KERNEL_FEATURES` |
126 | variable in recipes. | 122 | variable in recipes. |
127 | 123 | ||
128 | 5. *Locate, Expand, and Append Each Feature:* Each extra feature is | 124 | #. *Locate, Expand, and Append Each Feature:* Each extra feature is |
129 | located, expanded and appended to the script as described in step | 125 | located, expanded and appended to the script as described in step |
130 | three. | 126 | three. |
131 | 127 | ||
132 | 6. *Execute the Script:* The script is executed to produce files | 128 | #. *Execute the Script:* The script is executed to produce files |
133 | ``.scc`` and ``.cfg`` files in appropriate directories of the | 129 | ``.scc`` and ``.cfg`` files in appropriate directories of the |
134 | ``yocto-kernel-cache`` repository. These files are descriptions of | 130 | ``yocto-kernel-cache`` repository. These files are descriptions of |
135 | all the branches, tags, patches and configurations that need to be | 131 | all the branches, tags, patches and configurations that need to be |
136 | applied to the base Git repository to completely create the source | 132 | applied to the base Git repository to completely create the source |
137 | (build) branch for the new BSP or feature. | 133 | (build) branch for the new BSP or feature. |
138 | 134 | ||
139 | 7. *Clone Base Repository:* The base repository is cloned, and the | 135 | #. *Clone Base Repository:* The base repository is cloned, and the |
140 | actions listed in the ``yocto-kernel-cache`` directories are applied | 136 | actions listed in the ``yocto-kernel-cache`` directories are applied |
141 | to the tree. | 137 | to the tree. |
142 | 138 | ||
143 | 8. *Perform Cleanup:* The Git repositories are left with the desired | 139 | #. *Perform Cleanup:* The Git repositories are left with the desired |
144 | branches checked out and any required branching, patching and tagging | 140 | branches checked out and any required branching, patching and tagging |
145 | has been performed. | 141 | has been performed. |
146 | 142 | ||
@@ -179,7 +175,7 @@ Build Strategy | |||
179 | Once you have cloned a Yocto Linux kernel repository and the cache | 175 | Once you have cloned a Yocto Linux kernel repository and the cache |
180 | repository (``yocto-kernel-cache``) onto your development system, you | 176 | repository (``yocto-kernel-cache``) onto your development system, you |
181 | can consider the compilation phase of kernel development, which is | 177 | can consider the compilation phase of kernel development, which is |
182 | building a kernel image. Some prerequisites exist that are validated by | 178 | building a kernel image. Some prerequisites are validated by |
183 | the build process before compilation starts: | 179 | the build process before compilation starts: |
184 | 180 | ||
185 | - The :term:`SRC_URI` points to the | 181 | - The :term:`SRC_URI` points to the |
@@ -198,7 +194,7 @@ the build process before compilation starts: | |||
198 | In the previous example, the "yocto-4.12" branch is checked out in | 194 | In the previous example, the "yocto-4.12" branch is checked out in |
199 | the ``yocto-kernel-cache`` repository. | 195 | the ``yocto-kernel-cache`` repository. |
200 | 196 | ||
201 | The OpenEmbedded build system makes sure these conditions exist before | 197 | The OpenEmbedded build system makes sure these conditions are satisfied before |
202 | attempting compilation. Other means, however, do exist, such as | 198 | attempting compilation. Other means, however, do exist, such as |
203 | bootstrapping a BSP. | 199 | bootstrapping a BSP. |
204 | 200 | ||
@@ -222,8 +218,7 @@ build process generates a build tree that is separate from your kernel's | |||
222 | local Git source repository tree. This build tree has a name that uses | 218 | local Git source repository tree. This build tree has a name that uses |
223 | the following form, where ``${MACHINE}`` is the metadata name of the | 219 | the following form, where ``${MACHINE}`` is the metadata name of the |
224 | machine (BSP) and "kernel_type" is one of the Yocto Project supported | 220 | machine (BSP) and "kernel_type" is one of the Yocto Project supported |
225 | kernel types (e.g. "standard"): | 221 | kernel types (e.g. "standard"):: |
226 | :: | ||
227 | 222 | ||
228 | linux-${MACHINE}-kernel_type-build | 223 | linux-${MACHINE}-kernel_type-build |
229 | 224 | ||
@@ -234,6 +229,5 @@ This behavior means that all the generated files for a particular | |||
234 | machine or BSP are now in the build tree directory. The files include | 229 | machine or BSP are now in the build tree directory. The files include |
235 | the final ``.config`` file, all the ``.o`` files, the ``.a`` files, and | 230 | the final ``.config`` file, all the ``.o`` files, the ``.a`` files, and |
236 | so forth. Since each machine or BSP has its own separate | 231 | so forth. Since each machine or BSP has its own separate |
237 | :term:`Build Directory` in its own separate | 232 | :term:`Build Directory` in its own separate branch of the Git repository, |
238 | branch of the Git repository, you can easily switch between different | 233 | you can easily switch between different builds. |
239 | builds. | ||