diff options
Diffstat (limited to 'documentation/kernel-dev/kernel-dev-maint-appx.rst')
-rw-r--r-- | documentation/kernel-dev/kernel-dev-maint-appx.rst | 226 |
1 files changed, 226 insertions, 0 deletions
diff --git a/documentation/kernel-dev/kernel-dev-maint-appx.rst b/documentation/kernel-dev/kernel-dev-maint-appx.rst new file mode 100644 index 0000000000..4653e51eba --- /dev/null +++ b/documentation/kernel-dev/kernel-dev-maint-appx.rst | |||
@@ -0,0 +1,226 @@ | |||
1 | ****************** | ||
2 | Kernel Maintenance | ||
3 | ****************** | ||
4 | |||
5 | Tree Construction | ||
6 | ================= | ||
7 | |||
8 | This section describes construction of the Yocto Project kernel source | ||
9 | repositories as accomplished by the Yocto Project team to create Yocto | ||
10 | Linux kernel repositories. These kernel repositories are found under the | ||
11 | heading "Yocto Linux Kernel" at `YOCTO_GIT_URL <&YOCTO_GIT_URL;>`__ and | ||
12 | are shipped as part of a Yocto Project release. The team creates these | ||
13 | repositories by compiling and executing the set of feature descriptions | ||
14 | for every BSP and feature in the product. Those feature descriptions | ||
15 | list all necessary patches, configurations, branches, tags, and feature | ||
16 | divisions found in a Yocto Linux kernel. Thus, the Yocto Project Linux | ||
17 | kernel repository (or tree) and accompanying Metadata in the | ||
18 | ``yocto-kernel-cache`` are built. | ||
19 | |||
20 | The existence of these repositories allow you to access and clone a | ||
21 | particular Yocto Project Linux kernel repository and use it to build | ||
22 | images based on their configurations and features. | ||
23 | |||
24 | You can find the files used to describe all the valid features and BSPs | ||
25 | in the Yocto Project Linux kernel in any clone of the Yocto Project | ||
26 | Linux kernel source repository and ``yocto-kernel-cache`` Git trees. For | ||
27 | example, the following commands clone the Yocto Project baseline Linux | ||
28 | kernel that branches off ``linux.org`` version 4.12 and the | ||
29 | ``yocto-kernel-cache``, which contains stores of kernel Metadata: $ git | ||
30 | clone git://git.yoctoproject.org/linux-yocto-4.12 $ git clone | ||
31 | git://git.yoctoproject.org/linux-kernel-cache For more information on | ||
32 | how to set up a local Git repository of the Yocto Project Linux kernel | ||
33 | files, see the "`Preparing the Build Host to Work on the | ||
34 | Kernel <#preparing-the-build-host-to-work-on-the-kernel>`__" section. | ||
35 | |||
36 | Once you have cloned the kernel Git repository and the cache of Metadata | ||
37 | on your local machine, you can discover the branches that are available | ||
38 | in the repository using the following Git command: $ git branch -a | ||
39 | Checking out a branch allows you to work with a particular Yocto Linux | ||
40 | kernel. For example, the following commands check out the | ||
41 | "standard/beagleboard" branch of the Yocto Linux kernel repository and | ||
42 | the "yocto-4.12" branch of the ``yocto-kernel-cache`` repository: $ cd | ||
43 | ~/linux-yocto-4.12 $ git checkout -b my-kernel-4.12 | ||
44 | remotes/origin/standard/beagleboard $ cd ~/linux-kernel-cache $ git | ||
45 | checkout -b my-4.12-metadata remotes/origin/yocto-4.12 | ||
46 | |||
47 | .. note:: | ||
48 | |||
49 | Branches in the | ||
50 | yocto-kernel-cache | ||
51 | repository correspond to Yocto Linux kernel versions (e.g. | ||
52 | "yocto-4.12", "yocto-4.10", "yocto-4.9", and so forth). | ||
53 | |||
54 | Once you have checked out and switched to appropriate branches, you can | ||
55 | see a snapshot of all the kernel source files used to used to build that | ||
56 | particular Yocto Linux kernel for a particular board. | ||
57 | |||
58 | To see the features and configurations for a particular Yocto Linux | ||
59 | kernel, you need to examine the ``yocto-kernel-cache`` Git repository. | ||
60 | As mentioned, branches in the ``yocto-kernel-cache`` repository | ||
61 | correspond to Yocto Linux kernel versions (e.g. ``yocto-4.12``). | ||
62 | Branches contain descriptions in the form of ``.scc`` and ``.cfg`` | ||
63 | files. | ||
64 | |||
65 | You should realize, however, that browsing your local | ||
66 | ``yocto-kernel-cache`` repository for feature descriptions and patches | ||
67 | is not an effective way to determine what is in a particular kernel | ||
68 | branch. Instead, you should use Git directly to discover the changes in | ||
69 | a branch. Using Git is an efficient and flexible way to inspect changes | ||
70 | to the kernel. | ||
71 | |||
72 | .. note:: | ||
73 | |||
74 | Ground up reconstruction of the complete kernel tree is an action | ||
75 | only taken by the Yocto Project team during an active development | ||
76 | cycle. When you create a clone of the kernel Git repository, you are | ||
77 | simply making it efficiently available for building and development. | ||
78 | |||
79 | The following steps describe what happens when the Yocto Project Team | ||
80 | constructs the Yocto Project kernel source Git repository (or tree) | ||
81 | found at ` <&YOCTO_GIT_URL;>`__ given the introduction of a new | ||
82 | top-level kernel feature or BSP. The following actions effectively | ||
83 | provide the Metadata and create the tree that includes the new feature, | ||
84 | patch, or BSP: | ||
85 | |||
86 | 1. *Pass Feature to the OpenEmbedded Build System:* A top-level kernel | ||
87 | feature is passed to the kernel build subsystem. Normally, this | ||
88 | feature is a BSP for a particular kernel type. | ||
89 | |||
90 | 2. *Locate Feature:* The file that describes the top-level feature is | ||
91 | located by searching these system directories: | ||
92 | |||
93 | - The in-tree kernel-cache directories, which are located in the | ||
94 | ```yocto-kernel-cache`` <&YOCTO_GIT_URL;/cgit/cgit.cgi/yocto-kernel-cache/tree/bsp>`__ | ||
95 | repository organized under the "Yocto Linux Kernel" heading in the | ||
96 | `Yocto Project Source | ||
97 | Repositories <http://git.yoctoproject.org/cgit/cgit.cgi>`__. | ||
98 | |||
99 | - Areas pointed to by ``SRC_URI`` statements found in kernel recipes | ||
100 | |||
101 | For a typical build, the target of the search is a feature | ||
102 | description in an ``.scc`` file whose name follows this format (e.g. | ||
103 | ``beaglebone-standard.scc`` and ``beaglebone-preempt-rt.scc``): | ||
104 | bsp_root_name-kernel_type.scc | ||
105 | |||
106 | 3. *Expand Feature:* Once located, the feature description is either | ||
107 | expanded into a simple script of actions, or into an existing | ||
108 | equivalent script that is already part of the shipped kernel. | ||
109 | |||
110 | 4. *Append Extra Features:* Extra features are appended to the top-level | ||
111 | feature description. These features can come from the | ||
112 | ```KERNEL_FEATURES`` <&YOCTO_DOCS_REF_URL;#var-KERNEL_FEATURES>`__ | ||
113 | variable in recipes. | ||
114 | |||
115 | 5. *Locate, Expand, and Append Each Feature:* Each extra feature is | ||
116 | located, expanded and appended to the script as described in step | ||
117 | three. | ||
118 | |||
119 | 6. *Execute the Script:* The script is executed to produce files | ||
120 | ``.scc`` and ``.cfg`` files in appropriate directories of the | ||
121 | ``yocto-kernel-cache`` repository. These files are descriptions of | ||
122 | all the branches, tags, patches and configurations that need to be | ||
123 | applied to the base Git repository to completely create the source | ||
124 | (build) branch for the new BSP or feature. | ||
125 | |||
126 | 7. *Clone Base Repository:* The base repository is cloned, and the | ||
127 | actions listed in the ``yocto-kernel-cache`` directories are applied | ||
128 | to the tree. | ||
129 | |||
130 | 8. *Perform Cleanup:* The Git repositories are left with the desired | ||
131 | branches checked out and any required branching, patching and tagging | ||
132 | has been performed. | ||
133 | |||
134 | The kernel tree and cache are ready for developer consumption to be | ||
135 | locally cloned, configured, and built into a Yocto Project kernel | ||
136 | specific to some target hardware. | ||
137 | |||
138 | .. note:: | ||
139 | |||
140 | - The generated ``yocto-kernel-cache`` repository adds to the kernel | ||
141 | as shipped with the Yocto Project release. Any add-ons and | ||
142 | configuration data are applied to the end of an existing branch. | ||
143 | The full repository generation that is found in the official Yocto | ||
144 | Project kernel repositories at | ||
145 | `http://git.yoctoproject.org <&YOCTO_GIT_URL;>`__ is the | ||
146 | combination of all supported boards and configurations. | ||
147 | |||
148 | - The technique the Yocto Project team uses is flexible and allows | ||
149 | for seamless blending of an immutable history with additional | ||
150 | patches specific to a deployment. Any additions to the kernel | ||
151 | become an integrated part of the branches. | ||
152 | |||
153 | - The full kernel tree that you see on ` <&YOCTO_GIT_URL;>`__ is | ||
154 | generated through repeating the above steps for all valid BSPs. | ||
155 | The end result is a branched, clean history tree that makes up the | ||
156 | kernel for a given release. You can see the script (``kgit-scc``) | ||
157 | responsible for this in the | ||
158 | ```yocto-kernel-tools`` <&YOCTO_GIT_URL;/cgit.cgi/yocto-kernel-tools/tree/tools>`__ | ||
159 | repository. | ||
160 | |||
161 | - The steps used to construct the full kernel tree are the same | ||
162 | steps that BitBake uses when it builds a kernel image. | ||
163 | |||
164 | Build Strategy | ||
165 | ============== | ||
166 | |||
167 | Once you have cloned a Yocto Linux kernel repository and the cache | ||
168 | repository (``yocto-kernel-cache``) onto your development system, you | ||
169 | can consider the compilation phase of kernel development, which is | ||
170 | building a kernel image. Some prerequisites exist that are validated by | ||
171 | the build process before compilation starts: | ||
172 | |||
173 | - The ```SRC_URI`` <&YOCTO_DOCS_REF_URL;#var-SRC_URI>`__ points to the | ||
174 | kernel Git repository. | ||
175 | |||
176 | - A BSP build branch with Metadata exists in the ``yocto-kernel-cache`` | ||
177 | repository. The branch is based on the Yocto Linux kernel version and | ||
178 | has configurations and features grouped under the | ||
179 | ``yocto-kernel-cache/bsp`` directory. For example, features and | ||
180 | configurations for the BeagleBone Board assuming a | ||
181 | ``linux-yocto_4.12`` kernel reside in the following area of the | ||
182 | ``yocto-kernel-cache`` repository: yocto-kernel-cache/bsp/beaglebone | ||
183 | |||
184 | .. note:: | ||
185 | |||
186 | In the previous example, the "yocto-4.12" branch is checked out in | ||
187 | the | ||
188 | yocto-kernel-cache | ||
189 | repository. | ||
190 | |||
191 | The OpenEmbedded build system makes sure these conditions exist before | ||
192 | attempting compilation. Other means, however, do exist, such as as | ||
193 | bootstrapping a BSP. | ||
194 | |||
195 | Before building a kernel, the build process verifies the tree and | ||
196 | configures the kernel by processing all of the configuration "fragments" | ||
197 | specified by feature descriptions in the ``.scc`` files. As the features | ||
198 | are compiled, associated kernel configuration fragments are noted and | ||
199 | recorded in the series of directories in their compilation order. The | ||
200 | fragments are migrated, pre-processed and passed to the Linux Kernel | ||
201 | Configuration subsystem (``lkc``) as raw input in the form of a | ||
202 | ``.config`` file. The ``lkc`` uses its own internal dependency | ||
203 | constraints to do the final processing of that information and generates | ||
204 | the final ``.config`` file that is used during compilation. | ||
205 | |||
206 | Using the board's architecture and other relevant values from the | ||
207 | board's template, kernel compilation is started and a kernel image is | ||
208 | produced. | ||
209 | |||
210 | The other thing that you notice once you configure a kernel is that the | ||
211 | build process generates a build tree that is separate from your kernel's | ||
212 | local Git source repository tree. This build tree has a name that uses | ||
213 | the following form, where ``${MACHINE}`` is the metadata name of the | ||
214 | machine (BSP) and "kernel_type" is one of the Yocto Project supported | ||
215 | kernel types (e.g. "standard"): linux-${MACHINE}-kernel_type-build | ||
216 | |||
217 | The existing support in the ``kernel.org`` tree achieves this default | ||
218 | functionality. | ||
219 | |||
220 | This behavior means that all the generated files for a particular | ||
221 | machine or BSP are now in the build tree directory. The files include | ||
222 | the final ``.config`` file, all the ``.o`` files, the ``.a`` files, and | ||
223 | so forth. Since each machine or BSP has its own separate `Build | ||
224 | Directory <&YOCTO_DOCS_REF_URL;#build-directory>`__ in its own separate | ||
225 | branch of the Git repository, you can easily switch between different | ||
226 | builds. | ||