diff options
Diffstat (limited to 'documentation/kernel-dev/advanced.rst')
-rw-r--r-- | documentation/kernel-dev/advanced.rst | 56 |
1 files changed, 28 insertions, 28 deletions
diff --git a/documentation/kernel-dev/advanced.rst b/documentation/kernel-dev/advanced.rst index 0e745c375d..871ec8ae7b 100644 --- a/documentation/kernel-dev/advanced.rst +++ b/documentation/kernel-dev/advanced.rst | |||
@@ -46,15 +46,15 @@ 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 | 59 | however, these two variables can hold the same value. See the |
60 | ":ref:`kernel-dev/advanced:bsp descriptions`" section for more information. | 60 | ":ref:`kernel-dev/advanced:bsp descriptions`" section for more information. |
@@ -66,7 +66,7 @@ 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 | 71 | ||
72 | KBRANCH_edgerouter = "standard/edgerouter" | 72 | KBRANCH_edgerouter = "standard/edgerouter" |
@@ -81,8 +81,8 @@ variables: | |||
81 | 81 | ||
82 | :term:`LINUX_KERNEL_TYPE` | 82 | :term:`LINUX_KERNEL_TYPE` |
83 | defines the kernel type to be used in assembling the configuration. If | 83 | defines the kernel type to be used in assembling the configuration. If |
84 | you do not specify a ``LINUX_KERNEL_TYPE``, it defaults to "standard". | 84 | you do not specify a :term:`LINUX_KERNEL_TYPE`, it defaults to "standard". |
85 | Together with ``KMACHINE``, ``LINUX_KERNEL_TYPE`` defines the search | 85 | Together with :term:`KMACHINE`, :term:`LINUX_KERNEL_TYPE` defines the search |
86 | arguments used by the kernel tools to find the appropriate description | 86 | arguments used by the kernel tools to find the appropriate description |
87 | within the kernel Metadata with which to build out the sources and | 87 | within the kernel Metadata with which to build out the sources and |
88 | configuration. The linux-yocto recipes define "standard", "tiny", and | 88 | configuration. The linux-yocto recipes define "standard", "tiny", and |
@@ -90,21 +90,21 @@ configuration. The linux-yocto recipes define "standard", "tiny", and | |||
90 | section for more information on kernel types. | 90 | section for more information on kernel types. |
91 | 91 | ||
92 | During the build, the kern-tools search for the BSP description file | 92 | During the build, the kern-tools search for the BSP description file |
93 | that most closely matches the ``KMACHINE`` and ``LINUX_KERNEL_TYPE`` | 93 | that most closely matches the :term:`KMACHINE` and :term:`LINUX_KERNEL_TYPE` |
94 | variables passed in from the recipe. The tools use the first BSP | 94 | variables passed in from the recipe. The tools use the first BSP |
95 | description they find that matches both variables. If the tools cannot find | 95 | description they find that matches both variables. If the tools cannot find |
96 | a match, they issue a warning. | 96 | a match, they issue a warning. |
97 | 97 | ||
98 | The tools first search for the ``KMACHINE`` and then for the | 98 | The tools first search for the :term:`KMACHINE` and then for the |
99 | ``LINUX_KERNEL_TYPE``. If the tools cannot find a partial match, they | 99 | :term:`LINUX_KERNEL_TYPE`. If the tools cannot find a partial match, they |
100 | will use the sources from the ``KBRANCH`` and any configuration | 100 | will use the sources from the :term:`KBRANCH` and any configuration |
101 | specified in the :term:`SRC_URI`. | 101 | specified in the :term:`SRC_URI`. |
102 | 102 | ||
103 | You can use the | 103 | You can use the |
104 | :term:`KERNEL_FEATURES` | 104 | :term:`KERNEL_FEATURES` |
105 | variable to include features (configuration fragments, patches, or both) | 105 | variable to include features (configuration fragments, patches, or both) |
106 | that are not already included by the ``KMACHINE`` and | 106 | that are not already included by the :term:`KMACHINE` and |
107 | ``LINUX_KERNEL_TYPE`` variable combination. For example, to include a | 107 | :term:`LINUX_KERNEL_TYPE` variable combination. For example, to include a |
108 | feature specified as "features/netfilter/netfilter.scc", specify:: | 108 | feature specified as "features/netfilter/netfilter.scc", specify:: |
109 | 109 | ||
110 | KERNEL_FEATURES += "features/netfilter/netfilter.scc" | 110 | KERNEL_FEATURES += "features/netfilter/netfilter.scc" |
@@ -116,7 +116,7 @@ specify:: | |||
116 | KERNEL_FEATURES_append_qemux86 = " cfg/sound.scc" | 116 | KERNEL_FEATURES_append_qemux86 = " cfg/sound.scc" |
117 | 117 | ||
118 | The value of | 118 | The value of |
119 | the entries in ``KERNEL_FEATURES`` are dependent on their location | 119 | the entries in :term:`KERNEL_FEATURES` are dependent on their location |
120 | within the kernel Metadata itself. The examples here are taken from the | 120 | within the kernel Metadata itself. The examples here are taken from the |
121 | ``yocto-kernel-cache`` repository. Each branch of this repository | 121 | ``yocto-kernel-cache`` repository. Each branch of this repository |
122 | contains "features" and "cfg" subdirectories at the top-level. For more | 122 | contains "features" and "cfg" subdirectories at the top-level. For more |
@@ -344,7 +344,7 @@ as how an additional feature description file is included with the | |||
344 | 344 | ||
345 | Typically, features are less granular than configuration fragments and | 345 | Typically, features are less granular than configuration fragments and |
346 | are more likely than configuration fragments and patches to be the types | 346 | are more likely than configuration fragments and patches to be the types |
347 | of things you want to specify in the ``KERNEL_FEATURES`` variable of the | 347 | of things you want to specify in the :term:`KERNEL_FEATURES` variable of the |
348 | Linux kernel recipe. See the | 348 | Linux kernel recipe. See the |
349 | ":ref:`kernel-dev/advanced:using kernel metadata in a recipe`" section earlier | 349 | ":ref:`kernel-dev/advanced:using kernel metadata in a recipe`" section earlier |
350 | in the manual. | 350 | in the manual. |
@@ -509,12 +509,12 @@ description as meeting the criteria set by the recipe being built. This | |||
509 | example supports the "beaglebone" machine for the "standard" kernel and | 509 | example supports the "beaglebone" machine for the "standard" kernel and |
510 | the "arm" architecture. | 510 | the "arm" architecture. |
511 | 511 | ||
512 | Be aware that there is no hard link between the ``KTYPE`` variable and a kernel | 512 | Be aware that there is no hard link between the :term:`KTYPE` variable and a kernel |
513 | type description file. Thus, if you do not have the | 513 | type description file. Thus, if you do not have the |
514 | kernel type defined in your kernel Metadata as it is here, you only need | 514 | kernel type defined in your kernel Metadata as it is here, you only need |
515 | to ensure that the | 515 | to ensure that the |
516 | :term:`LINUX_KERNEL_TYPE` | 516 | :term:`LINUX_KERNEL_TYPE` |
517 | variable in the kernel recipe and the ``KTYPE`` variable in the BSP | 517 | variable in the kernel recipe and the :term:`KTYPE` variable in the BSP |
518 | description file match. | 518 | description file match. |
519 | 519 | ||
520 | To separate your kernel policy from your hardware configuration, you | 520 | To separate your kernel policy from your hardware configuration, you |
@@ -657,7 +657,7 @@ Notice again the three critical variables: | |||
657 | :term:`KMACHINE`, | 657 | :term:`KMACHINE`, |
658 | :term:`KTYPE`, and | 658 | :term:`KTYPE`, and |
659 | :term:`KARCH`. Of these variables, only | 659 | :term:`KARCH`. Of these variables, only |
660 | ``KTYPE`` has changed to specify the "tiny" kernel type. | 660 | :term:`KTYPE` has changed to specify the "tiny" kernel type. |
661 | 661 | ||
662 | Kernel Metadata Location | 662 | Kernel Metadata Location |
663 | ======================== | 663 | ======================== |
@@ -693,7 +693,7 @@ directory hierarchy below | |||
693 | a linux-yocto recipe or for a Linux kernel recipe derived by copying and | 693 | a linux-yocto recipe or for a Linux kernel recipe derived by copying and |
694 | modifying | 694 | modifying |
695 | ``oe-core/meta-skeleton/recipes-kernel/linux/linux-yocto-custom.bb`` to | 695 | ``oe-core/meta-skeleton/recipes-kernel/linux/linux-yocto-custom.bb`` to |
696 | a recipe in your layer, ``FILESEXTRAPATHS`` is typically set to | 696 | a recipe in your layer, :term:`FILESEXTRAPATHS` is typically set to |
697 | ``${``\ :term:`THISDIR`\ ``}/${``\ :term:`PN`\ ``}``. | 697 | ``${``\ :term:`THISDIR`\ ``}/${``\ :term:`PN`\ ``}``. |
698 | See the ":ref:`kernel-dev/common:modifying an existing recipe`" | 698 | See the ":ref:`kernel-dev/common:modifying an existing recipe`" |
699 | section for more information. | 699 | section for more information. |
@@ -718,10 +718,10 @@ and fetches any files referenced in the ``.scc`` files by the | |||
718 | ``include``, ``patch``, or ``kconf`` commands. Because of this, it is | 718 | ``include``, ``patch``, or ``kconf`` commands. Because of this, it is |
719 | necessary to bump the recipe :term:`PR` | 719 | necessary to bump the recipe :term:`PR` |
720 | value when changing the content of files not explicitly listed in the | 720 | value when changing the content of files not explicitly listed in the |
721 | ``SRC_URI``. | 721 | :term:`SRC_URI`. |
722 | 722 | ||
723 | If the BSP description is in recipe space, you cannot simply list the | 723 | If the BSP description is in recipe space, you cannot simply list the |
724 | ``*.scc`` in the ``SRC_URI`` statement. You need to use the following | 724 | ``*.scc`` in the :term:`SRC_URI` statement. You need to use the following |
725 | form from your kernel append file:: | 725 | form from your kernel append file:: |
726 | 726 | ||
727 | SRC_URI_append_myplatform = " \ | 727 | SRC_URI_append_myplatform = " \ |
@@ -735,7 +735,7 @@ When stored outside of the recipe-space, the kernel Metadata files | |||
735 | reside in a separate repository. The OpenEmbedded build system adds the | 735 | reside in a separate repository. The OpenEmbedded build system adds the |
736 | Metadata to the build as a "type=kmeta" repository through the | 736 | Metadata to the build as a "type=kmeta" repository through the |
737 | :term:`SRC_URI` variable. As an | 737 | :term:`SRC_URI` variable. As an |
738 | example, consider the following ``SRC_URI`` statement from the | 738 | example, consider the following :term:`SRC_URI` statement from the |
739 | ``linux-yocto_4.12.bb`` kernel recipe:: | 739 | ``linux-yocto_4.12.bb`` kernel recipe:: |
740 | 740 | ||
741 | SRC_URI = "git://git.yoctoproject.org/linux-yocto-4.12.git;name=machine;branch=${KBRANCH}; \ | 741 | SRC_URI = "git://git.yoctoproject.org/linux-yocto-4.12.git;name=machine;branch=${KBRANCH}; \ |
@@ -744,20 +744,20 @@ example, consider the following ``SRC_URI`` statement from the | |||
744 | 744 | ||
745 | ``${KMETA}``, in this context, is simply used to name the directory into | 745 | ``${KMETA}``, in this context, is simply used to name the directory into |
746 | which the Git fetcher places the Metadata. This behavior is no different | 746 | which the Git fetcher places the Metadata. This behavior is no different |
747 | than any multi-repository ``SRC_URI`` statement used in a recipe (e.g. | 747 | than any multi-repository :term:`SRC_URI` statement used in a recipe (e.g. |
748 | see the previous section). | 748 | see the previous section). |
749 | 749 | ||
750 | You can keep kernel Metadata in a "kernel-cache", which is a directory | 750 | You can keep kernel Metadata in a "kernel-cache", which is a directory |
751 | containing configuration fragments. As with any Metadata kept outside | 751 | containing configuration fragments. As with any Metadata kept outside |
752 | the recipe-space, you simply need to use the ``SRC_URI`` statement with | 752 | the recipe-space, you simply need to use the :term:`SRC_URI` statement with |
753 | the "type=kmeta" attribute. Doing so makes the kernel Metadata available | 753 | the "type=kmeta" attribute. Doing so makes the kernel Metadata available |
754 | during the configuration phase. | 754 | during the configuration phase. |
755 | 755 | ||
756 | If you modify the Metadata, you must not forget to update the ``SRCREV`` | 756 | If you modify the Metadata, you must not forget to update the :term:`SRCREV` |
757 | statements in the kernel's recipe. In particular, you need to update the | 757 | statements in the kernel's recipe. In particular, you need to update the |
758 | ``SRCREV_meta`` variable to match the commit in the ``KMETA`` branch you | 758 | ``SRCREV_meta`` variable to match the commit in the ``KMETA`` branch you |
759 | wish to use. Changing the data in these branches and not updating the | 759 | wish to use. Changing the data in these branches and not updating the |
760 | ``SRCREV`` statements to match will cause the build to fetch an older | 760 | :term:`SRCREV` statements to match will cause the build to fetch an older |
761 | commit. | 761 | commit. |
762 | 762 | ||
763 | Organizing Your Source | 763 | Organizing Your Source |
@@ -820,7 +820,7 @@ patches into a feature. | |||
820 | 820 | ||
821 | Once you have a new branch, you can set up your kernel Metadata to use | 821 | Once you have a new branch, you can set up your kernel Metadata to use |
822 | the branch a couple different ways. In the recipe, you can specify the | 822 | the branch a couple different ways. In the recipe, you can specify the |
823 | new branch as the ``KBRANCH`` to use for the board as follows:: | 823 | new branch as the :term:`KBRANCH` to use for the board as follows:: |
824 | 824 | ||
825 | KBRANCH = "mynewbranch" | 825 | KBRANCH = "mynewbranch" |
826 | 826 | ||