diff options
Diffstat (limited to 'documentation/kernel-dev/kernel-dev-advanced.rst')
-rw-r--r-- | documentation/kernel-dev/kernel-dev-advanced.rst | 54 |
1 files changed, 27 insertions, 27 deletions
diff --git a/documentation/kernel-dev/kernel-dev-advanced.rst b/documentation/kernel-dev/kernel-dev-advanced.rst index 90323d3e2a..36a34ca28c 100644 --- a/documentation/kernel-dev/kernel-dev-advanced.rst +++ b/documentation/kernel-dev/kernel-dev-advanced.rst | |||
@@ -11,7 +11,7 @@ Overview | |||
11 | 11 | ||
12 | In addition to supporting configuration fragments and patches, the Yocto | 12 | In addition to supporting configuration fragments and patches, the Yocto |
13 | Project kernel tools also support rich | 13 | Project kernel tools also support rich |
14 | `Metadata <&YOCTO_DOCS_REF_URL;#metadata>`__ that you can use to define | 14 | :term:`Metadata` that you can use to define |
15 | complex policies and Board Support Package (BSP) support. The purpose of | 15 | complex policies and Board Support Package (BSP) support. The purpose of |
16 | the Metadata and the tools that manage it is to help you manage the | 16 | the Metadata and the tools that manage it is to help you manage the |
17 | complexity of the configuration and sources used to support multiple | 17 | complexity of the configuration and sources used to support multiple |
@@ -27,7 +27,7 @@ Kernel development tools ("kern-tools") exist also in the Yocto Project | |||
27 | Source Repositories under the "Yocto Linux Kernel" heading in the | 27 | Source Repositories under the "Yocto Linux Kernel" heading in the |
28 | ``yocto-kernel-tools`` Git repository. The recipe that builds these | 28 | ``yocto-kernel-tools`` Git repository. The recipe that builds these |
29 | tools is ``meta/recipes-kernel/kern-tools/kern-tools-native_git.bb`` in | 29 | tools is ``meta/recipes-kernel/kern-tools/kern-tools-native_git.bb`` in |
30 | the `Source Directory <&YOCTO_DOCS_REF_URL;#source-directory>`__ (e.g. | 30 | the :term:`Source Directory` (e.g. |
31 | ``poky``). | 31 | ``poky``). |
32 | 32 | ||
33 | Using Kernel Metadata in a Recipe | 33 | Using Kernel Metadata in a Recipe |
@@ -49,9 +49,9 @@ linux-yocto recipe. | |||
49 | file) is said to be a "linux-yocto style" recipe. | 49 | file) is said to be a "linux-yocto style" recipe. |
50 | 50 | ||
51 | Every linux-yocto style recipe must define the | 51 | Every linux-yocto style recipe must define the |
52 | ```KMACHINE`` <&YOCTO_DOCS_REF_URL;#var-KMACHINE>`__ variable. This | 52 | :term:`KMACHINE` variable. This |
53 | variable is typically set to the same value as the ``MACHINE`` variable, | 53 | variable is typically set to the same value as the ``MACHINE`` variable, |
54 | which is used by `BitBake <&YOCTO_DOCS_REF_URL;#bitbake-term>`__. | 54 | which is used by :term:`BitBake`. |
55 | However, in some cases, the variable might instead refer to the | 55 | However, in some cases, the variable might instead refer to the |
56 | underlying platform of the ``MACHINE``. | 56 | underlying platform of the ``MACHINE``. |
57 | 57 | ||
@@ -65,7 +65,7 @@ Descriptions <#bsp-descriptions>`__ section for more information. | |||
65 | 65 | ||
66 | Every linux-yocto style recipe must also indicate the Linux kernel | 66 | Every linux-yocto style recipe must also indicate the Linux kernel |
67 | source repository branch used to build the Linux kernel. The | 67 | source repository branch used to build the Linux kernel. The |
68 | ```KBRANCH`` <&YOCTO_DOCS_REF_URL;#var-KBRANCH>`__ variable must be set | 68 | :term:`KBRANCH` variable must be set |
69 | to indicate the branch. | 69 | to indicate the branch. |
70 | 70 | ||
71 | .. note:: | 71 | .. note:: |
@@ -84,7 +84,7 @@ to indicate the branch. | |||
84 | The linux-yocto style recipes can optionally define the following | 84 | The linux-yocto style recipes can optionally define the following |
85 | variables: KERNEL_FEATURES LINUX_KERNEL_TYPE | 85 | variables: KERNEL_FEATURES LINUX_KERNEL_TYPE |
86 | 86 | ||
87 | ```LINUX_KERNEL_TYPE`` <&YOCTO_DOCS_REF_URL;#var-LINUX_KERNEL_TYPE>`__ | 87 | :term:`LINUX_KERNEL_TYPE` |
88 | defines the kernel type to be used in assembling the configuration. If | 88 | defines the kernel type to be used in assembling the configuration. If |
89 | you do not specify a ``LINUX_KERNEL_TYPE``, it defaults to "standard". | 89 | you do not specify a ``LINUX_KERNEL_TYPE``, it defaults to "standard". |
90 | Together with ``KMACHINE``, ``LINUX_KERNEL_TYPE`` defines the search | 90 | Together with ``KMACHINE``, ``LINUX_KERNEL_TYPE`` defines the search |
@@ -103,10 +103,10 @@ a match, they issue a warning. | |||
103 | The tools first search for the ``KMACHINE`` and then for the | 103 | The tools first search for the ``KMACHINE`` and then for the |
104 | ``LINUX_KERNEL_TYPE``. If the tools cannot find a partial match, they | 104 | ``LINUX_KERNEL_TYPE``. If the tools cannot find a partial match, they |
105 | will use the sources from the ``KBRANCH`` and any configuration | 105 | will use the sources from the ``KBRANCH`` and any configuration |
106 | specified in the ```SRC_URI`` <&YOCTO_DOCS_REF_URL;#var-SRC_URI>`__. | 106 | specified in the :term:`SRC_URI`. |
107 | 107 | ||
108 | You can use the | 108 | You can use the |
109 | ```KERNEL_FEATURES`` <&YOCTO_DOCS_REF_URL;#var-KERNEL_FEATURES>`__ | 109 | :term:`KERNEL_FEATURES` |
110 | variable to include features (configuration fragments, patches, or both) | 110 | variable to include features (configuration fragments, patches, or both) |
111 | that are not already included by the ``KMACHINE`` and | 111 | that are not already included by the ``KMACHINE`` and |
112 | ``LINUX_KERNEL_TYPE`` variable combination. For example, to include a | 112 | ``LINUX_KERNEL_TYPE`` variable combination. For example, to include a |
@@ -185,7 +185,7 @@ contain "features" as far as the kernel tools are concerned. | |||
185 | 185 | ||
186 | Paths used in kernel Metadata files are relative to base, which is | 186 | Paths used in kernel Metadata files are relative to base, which is |
187 | either | 187 | either |
188 | ```FILESEXTRAPATHS`` <&YOCTO_DOCS_REF_URL;#var-FILESEXTRAPATHS>`__ if | 188 | :term:`FILESEXTRAPATHS` if |
189 | you are creating Metadata in `recipe-space <#recipe-space-metadata>`__, | 189 | you are creating Metadata in `recipe-space <#recipe-space-metadata>`__, |
190 | or the top level of | 190 | or the top level of |
191 | ```yocto-kernel-cache`` <&YOCTO_GIT_URL;/cgit/cgit.cgi/yocto-kernel-cache/tree/>`__ | 191 | ```yocto-kernel-cache`` <&YOCTO_GIT_URL;/cgit/cgit.cgi/yocto-kernel-cache/tree/>`__ |
@@ -218,7 +218,7 @@ fragment files in the "`Creating Configuration | |||
218 | Fragments <#creating-config-fragments>`__" section. | 218 | Fragments <#creating-config-fragments>`__" section. |
219 | 219 | ||
220 | Within the ``smp.scc`` file, the | 220 | Within the ``smp.scc`` file, the |
221 | ```KFEATURE_DESCRIPTION`` <&YOCTO_DOCS_REF_URL;#var-KFEATURE_DESCRIPTION>`__ | 221 | :term:`KFEATURE_DESCRIPTION` |
222 | statement provides a short description of the fragment. Higher level | 222 | statement provides a short description of the fragment. Higher level |
223 | kernel tools use this description. | 223 | kernel tools use this description. |
224 | 224 | ||
@@ -312,7 +312,7 @@ non-hardware configuration fragments with patches you want to use when | |||
312 | building a Linux kernel of a specific type (e.g. a real-time kernel). | 312 | building a Linux kernel of a specific type (e.g. a real-time kernel). |
313 | Syntactically, kernel types are no different than features as described | 313 | Syntactically, kernel types are no different than features as described |
314 | in the "`Features <#features>`__" section. The | 314 | in the "`Features <#features>`__" section. The |
315 | ```LINUX_KERNEL_TYPE`` <&YOCTO_DOCS_REF_URL;#var-LINUX_KERNEL_TYPE>`__ | 315 | :term:`LINUX_KERNEL_TYPE` |
316 | variable in the kernel recipe selects the kernel type. For example, in | 316 | variable in the kernel recipe selects the kernel type. For example, in |
317 | the ``linux-yocto_4.12.bb`` kernel recipe found in | 317 | the ``linux-yocto_4.12.bb`` kernel recipe found in |
318 | ``poky/meta/recipes-kernel/linux``, a | 318 | ``poky/meta/recipes-kernel/linux``, a |
@@ -432,9 +432,9 @@ ktypes/standard/standard.scc branch beaglebone include beaglebone.scc # | |||
432 | default policy for standard kernels include | 432 | default policy for standard kernels include |
433 | features/latencytop/latencytop.scc include | 433 | features/latencytop/latencytop.scc include |
434 | features/profiling/profiling.scc Every top-level BSP description file | 434 | features/profiling/profiling.scc Every top-level BSP description file |
435 | should define the ```KMACHINE`` <&YOCTO_DOCS_REF_URL;#var-KMACHINE>`__, | 435 | should define the :term:`KMACHINE`, |
436 | ```KTYPE`` <&YOCTO_DOCS_REF_URL;#var-KTYPE>`__, and | 436 | :term:`KTYPE`, and |
437 | ```KARCH`` <&YOCTO_DOCS_REF_URL;#var-KARCH>`__ variables. These | 437 | :term:`KARCH` variables. These |
438 | variables allow the OpenEmbedded build system to identify the | 438 | variables allow the OpenEmbedded build system to identify the |
439 | description as meeting the criteria set by the recipe being built. This | 439 | description as meeting the criteria set by the recipe being built. This |
440 | example supports the "beaglebone" machine for the "standard" kernel and | 440 | example supports the "beaglebone" machine for the "standard" kernel and |
@@ -444,7 +444,7 @@ Be aware that a hard link between the ``KTYPE`` variable and a kernel | |||
444 | type description file does not exist. Thus, if you do not have the | 444 | type description file does not exist. Thus, if you do not have the |
445 | kernel type defined in your kernel Metadata as it is here, you only need | 445 | kernel type defined in your kernel Metadata as it is here, you only need |
446 | to ensure that the | 446 | to ensure that the |
447 | ```LINUX_KERNEL_TYPE`` <&YOCTO_DOCS_REF_URL;#var-LINUX_KERNEL_TYPE>`__ | 447 | :term:`LINUX_KERNEL_TYPE` |
448 | variable in the kernel recipe and the ``KTYPE`` variable in the BSP | 448 | variable in the kernel recipe and the ``KTYPE`` variable in the BSP |
449 | description file match. | 449 | description file match. |
450 | 450 | ||
@@ -529,9 +529,9 @@ with the most basic functionality of the system as defined in the base | |||
529 | "minnow" description file. | 529 | "minnow" description file. |
530 | 530 | ||
531 | Notice again the three critical variables: | 531 | Notice again the three critical variables: |
532 | ```KMACHINE`` <&YOCTO_DOCS_REF_URL;#var-KMACHINE>`__, | 532 | :term:`KMACHINE`, |
533 | ```KTYPE`` <&YOCTO_DOCS_REF_URL;#var-KTYPE>`__, and | 533 | :term:`KTYPE`, and |
534 | ```KARCH`` <&YOCTO_DOCS_REF_URL;#var-KARCH>`__. Of these variables, only | 534 | :term:`KARCH`. Of these variables, only |
535 | ``KTYPE`` has changed to specify the "tiny" kernel type. | 535 | ``KTYPE`` has changed to specify the "tiny" kernel type. |
536 | 536 | ||
537 | Kernel Metadata Location | 537 | Kernel Metadata Location |
@@ -564,12 +564,12 @@ Recipe-Space Metadata | |||
564 | 564 | ||
565 | When stored in recipe-space, the kernel Metadata files reside in a | 565 | When stored in recipe-space, the kernel Metadata files reside in a |
566 | directory hierarchy below | 566 | directory hierarchy below |
567 | ```FILESEXTRAPATHS`` <&YOCTO_DOCS_REF_URL;#var-FILESEXTRAPATHS>`__. For | 567 | :term:`FILESEXTRAPATHS`. For |
568 | a linux-yocto recipe or for a Linux kernel recipe derived by copying and | 568 | a linux-yocto recipe or for a Linux kernel recipe derived by copying and |
569 | modifying | 569 | modifying |
570 | ``oe-core/meta-skeleton/recipes-kernel/linux/linux-yocto-custom.bb`` to | 570 | ``oe-core/meta-skeleton/recipes-kernel/linux/linux-yocto-custom.bb`` to |
571 | a recipe in your layer, ``FILESEXTRAPATHS`` is typically set to | 571 | a recipe in your layer, ``FILESEXTRAPATHS`` is typically set to |
572 | ``${``\ ```THISDIR`` <&YOCTO_DOCS_REF_URL;#var-THISDIR>`__\ ``}/${``\ ```PN`` <&YOCTO_DOCS_REF_URL;#var-PN>`__\ ``}``. | 572 | ``${``\ :term:`THISDIR`\ ``}/${``\ :term:`PN`\ ``}``. |
573 | See the "`Modifying an Existing | 573 | See the "`Modifying an Existing |
574 | Recipe <#modifying-an-existing-recipe>`__" section for more information. | 574 | Recipe <#modifying-an-existing-recipe>`__" section for more information. |
575 | 575 | ||
@@ -582,10 +582,10 @@ When the Metadata is stored in recipe-space, you must take steps to | |||
582 | ensure BitBake has the necessary information to decide what files to | 582 | ensure BitBake has the necessary information to decide what files to |
583 | fetch and when they need to be fetched again. It is only necessary to | 583 | fetch and when they need to be fetched again. It is only necessary to |
584 | specify the ``.scc`` files on the | 584 | specify the ``.scc`` files on the |
585 | ```SRC_URI`` <&YOCTO_DOCS_REF_URL;#var-SRC_URI>`__. BitBake parses them | 585 | :term:`SRC_URI`. BitBake parses them |
586 | and fetches any files referenced in the ``.scc`` files by the | 586 | and fetches any files referenced in the ``.scc`` files by the |
587 | ``include``, ``patch``, or ``kconf`` commands. Because of this, it is | 587 | ``include``, ``patch``, or ``kconf`` commands. Because of this, it is |
588 | necessary to bump the recipe ```PR`` <&YOCTO_DOCS_REF_URL;#var-PR>`__ | 588 | necessary to bump the recipe :term:`PR` |
589 | value when changing the content of files not explicitly listed in the | 589 | value when changing the content of files not explicitly listed in the |
590 | ``SRC_URI``. | 590 | ``SRC_URI``. |
591 | 591 | ||
@@ -600,7 +600,7 @@ Metadata Outside the Recipe-Space | |||
600 | When stored outside of the recipe-space, the kernel Metadata files | 600 | When stored outside of the recipe-space, the kernel Metadata files |
601 | reside in a separate repository. The OpenEmbedded build system adds the | 601 | reside in a separate repository. The OpenEmbedded build system adds the |
602 | Metadata to the build as a "type=kmeta" repository through the | 602 | Metadata to the build as a "type=kmeta" repository through the |
603 | ```SRC_URI`` <&YOCTO_DOCS_REF_URL;#var-SRC_URI>`__ variable. As an | 603 | :term:`SRC_URI` variable. As an |
604 | example, consider the following ``SRC_URI`` statement from the | 604 | example, consider the following ``SRC_URI`` statement from the |
605 | ``linux-yocto_4.12.bb`` kernel recipe: SRC_URI = | 605 | ``linux-yocto_4.12.bb`` kernel recipe: SRC_URI = |
606 | "git://git.yoctoproject.org/linux-yocto-4.12.git;name=machine;branch=${KBRANCH}; | 606 | "git://git.yoctoproject.org/linux-yocto-4.12.git;name=machine;branch=${KBRANCH}; |
@@ -742,10 +742,10 @@ within an SCC description file (``.scc``): | |||
742 | "ref" if specified. | 742 | "ref" if specified. |
743 | 743 | ||
744 | - ``define``: Defines variables, such as | 744 | - ``define``: Defines variables, such as |
745 | ```KMACHINE`` <&YOCTO_DOCS_REF_URL;#var-KMACHINE>`__, | 745 | :term:`KMACHINE`, |
746 | ```KTYPE`` <&YOCTO_DOCS_REF_URL;#var-KTYPE>`__, | 746 | :term:`KTYPE`, |
747 | ```KARCH`` <&YOCTO_DOCS_REF_URL;#var-KARCH>`__, and | 747 | :term:`KARCH`, and |
748 | ```KFEATURE_DESCRIPTION`` <&YOCTO_DOCS_REF_URL;#var-KFEATURE_DESCRIPTION>`__. | 748 | :term:`KFEATURE_DESCRIPTION`. |
749 | 749 | ||
750 | - ``include SCC_FILE``: Includes an SCC file in the current file. The | 750 | - ``include SCC_FILE``: Includes an SCC file in the current file. The |
751 | file is parsed as if you had inserted it inline. | 751 | file is parsed as if you had inserted it inline. |