blob: 6bb0cf6fd0cd53beb77b0a48bda372d816286986 [file] [log] [blame]
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
2"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
3[<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] >
4
5<appendix id='kernel-dev-maint-appx'>
6<title>Kernel Maintenance</title>
7
8 <section id='tree-construction'>
9 <title>Tree Construction</title>
10 <para>
11 This section describes construction of the Yocto Project kernel source repositories
12 as accomplished by the Yocto Project team to create kernel repositories.
13 These kernel repositories are found under the heading "Yocto Linux Kernel" at
14 <ulink url='&YOCTO_GIT_URL;/cgit.cgi'>&YOCTO_GIT_URL;/cgit.cgi</ulink>
15 and can be shipped as part of a Yocto Project release.
16 The team creates these repositories by
17 compiling and executing the set of feature descriptions for every BSP
18 and feature in the product.
19 Those feature descriptions list all necessary patches,
20 configuration, branching, tagging and feature divisions found in a kernel.
21 Thus, the Yocto Project kernel repository (or tree) is built.
22 </para>
23 <para>
24 The existence of this tree allows you to access and clone a particular
25 Yocto Project kernel repository and use it to build images based on their configurations
26 and features.
27 </para>
28 <para>
29 You can find the files used to describe all the valid features and BSPs
30 in the Yocto Project kernel in any clone of the Yocto Project kernel source repository
31 Git tree.
32 For example, the following command clones the Yocto Project baseline kernel that
33 branched off of <filename>linux.org</filename> version 3.19:
34 <literallayout class='monospaced'>
35 $ git clone git://git.yoctoproject.org/linux-yocto-3.19
36 </literallayout>
37 For another example of how to set up a local Git repository of the Yocto Project
38 kernel files, see the
39 "<ulink url='&YOCTO_DOCS_DEV_URL;#local-kernel-files'>Yocto Project Kernel</ulink>" bulleted
40 item in the Yocto Project Development Manual.
41 </para>
42 <para>
43 Once you have cloned the kernel Git repository on your local machine, you can
44 switch to the <filename>meta</filename> branch within the repository.
45 Here is an example that assumes the local Git repository for the kernel is in
46 a top-level directory named <filename>linux-yocto-3.19</filename>:
47 <literallayout class='monospaced'>
48 $ cd linux-yocto-3.19
49 $ git checkout -b meta origin/meta
50 </literallayout>
51 Once you have checked out and switched to the <filename>meta</filename> branch,
52 you can see a snapshot of all the kernel configuration and feature descriptions that are
53 used to build that particular kernel repository.
54 These descriptions are in the form of <filename>.scc</filename> files.
55 </para>
56 <para>
57 You should realize, however, that browsing your local kernel repository
58 for feature descriptions and patches is not an effective way to determine what is in a
59 particular kernel branch.
60 Instead, you should use Git directly to discover the changes in a branch.
61 Using Git is an efficient and flexible way to inspect changes to the kernel.
62 <note>
63 Ground up reconstruction of the complete kernel tree is an action only taken by the
64 Yocto Project team during an active development cycle.
65 When you create a clone of the kernel Git repository, you are simply making it
66 efficiently available for building and development.
67 </note>
68 </para>
69 <para>
70 The following steps describe what happens when the Yocto Project Team constructs
71 the Yocto Project kernel source Git repository (or tree) found at
72 <ulink url='&YOCTO_GIT_URL;/cgit.cgi'></ulink> given the
73 introduction of a new top-level kernel feature or BSP.
74 These are the actions that effectively create the tree
75 that includes the new feature, patch or BSP:
76 <orderedlist>
77 <listitem><para>A top-level kernel feature is passed to the kernel build subsystem.
78 Normally, this feature is a BSP for a particular kernel type.</para></listitem>
79 <listitem><para>The file that describes the top-level feature is located by searching
80 these system directories:
81 <itemizedlist>
82 <listitem><para>The in-tree kernel-cache directories, which are located
83 in <filename>meta/cfg/kernel-cache</filename></para></listitem>
84 <listitem><para>Areas pointed to by <filename>SRC_URI</filename> statements
85 found in recipes</para></listitem>
86 </itemizedlist>
87 For a typical build, the target of the search is a
88 feature description in an <filename>.scc</filename> file
89 whose name follows this format:
90 <literallayout class='monospaced'>
91 <replaceable>bsp_name</replaceable>-<replaceable>kernel_type</replaceable>.scc
92 </literallayout>
93 </para></listitem>
94 <listitem><para>Once located, the feature description is either compiled into a simple script
95 of actions, or into an existing equivalent script that is already part of the
96 shipped kernel.</para></listitem>
97 <listitem><para>Extra features are appended to the top-level feature description.
98 These features can come from the
99 <ulink url='&YOCTO_DOCS_REF_URL;#var-KERNEL_FEATURES'><filename>KERNEL_FEATURES</filename></ulink>
100 variable in recipes.</para></listitem>
101 <listitem><para>Each extra feature is located, compiled and appended to the script
102 as described in step three.</para></listitem>
103 <listitem><para>The script is executed to produce a series of <filename>meta-*</filename>
104 directories.
105 These directories are descriptions of all the branches, tags, patches and configurations that
106 need to be applied to the base Git repository to completely create the
107 source (build) branch for the new BSP or feature.</para></listitem>
108 <listitem><para>The base repository is cloned, and the actions
109 listed in the <filename>meta-*</filename> directories are applied to the
110 tree.</para></listitem>
111 <listitem><para>The Git repository is left with the desired branch checked out and any
112 required branching, patching and tagging has been performed.</para></listitem>
113 </orderedlist>
114 </para>
115 <para>
116 The kernel tree is now ready for developer consumption to be locally cloned,
117 configured, and built into a Yocto Project kernel specific to some target hardware.
118 <note><para>The generated <filename>meta-*</filename> directories add to the kernel
119 as shipped with the Yocto Project release.
120 Any add-ons and configuration data are applied to the end of an existing branch.
121 The full repository generation that is found in the
122 official Yocto Project kernel repositories at
123 <ulink url='&YOCTO_GIT_URL;/cgit.cgi'>http://git.yoctoproject.org/cgit.cgi</ulink>
124 is the combination of all supported boards and configurations.</para>
125 <para>The technique the Yocto Project team uses is flexible and allows for seamless
126 blending of an immutable history with additional patches specific to a
127 deployment.
128 Any additions to the kernel become an integrated part of the branches.</para>
129 </note>
130 </para>
131 </section>
132
133 <section id='build-strategy'>
134 <title>Build Strategy</title>
135
136<!--
137 <para>
138 <emphasis>AR - Darren Hart:</emphasis> Some parts of this section
139 need to be in the
140 "<link linkend='using-an-iterative-development-process'>Using an Iterative Development Process</link>"
141 section.
142 Darren needs to figure out which parts and identify them.
143 </para>
144-->
145
146 <para>
147 Once a local Git repository of the Yocto Project kernel exists on a development system,
148 you can consider the compilation phase of kernel development - building a kernel image.
149 Some prerequisites exist that are validated by the build process before compilation
150 starts:
151 </para>
152
153 <itemizedlist>
154 <listitem><para>The
155 <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink> points
156 to the kernel Git repository.</para></listitem>
157 <listitem><para>A BSP build branch exists.
158 This branch has the following form:
159 <literallayout class='monospaced'>
160 <replaceable>kernel_type</replaceable>/<replaceable>bsp_name</replaceable>
161 </literallayout></para></listitem>
162 </itemizedlist>
163
164 <para>
165 The OpenEmbedded build system makes sure these conditions exist before attempting compilation.
166 Other means, however, do exist, such as as bootstrapping a BSP.
167 </para>
168
169 <para>
170 Before building a kernel, the build process verifies the tree
171 and configures the kernel by processing all of the
172 configuration "fragments" specified by feature descriptions in the <filename>.scc</filename>
173 files.
174 As the features are compiled, associated kernel configuration fragments are noted
175 and recorded in the <filename>meta-*</filename> series of directories in their compilation order.
176 The fragments are migrated, pre-processed and passed to the Linux Kernel
177 Configuration subsystem (<filename>lkc</filename>) as raw input in the form
178 of a <filename>.config</filename> file.
179 The <filename>lkc</filename> uses its own internal dependency constraints to do the final
180 processing of that information and generates the final <filename>.config</filename> file
181 that is used during compilation.
182 </para>
183
184 <para>
185 Using the board's architecture and other relevant values from the board's template,
186 kernel compilation is started and a kernel image is produced.
187 </para>
188
189 <para>
190 The other thing that you notice once you configure a kernel is that
191 the build process generates a build tree that is separate from your kernel's local Git
192 source repository tree.
193 This build tree has a name that uses the following form, where
194 <filename>${MACHINE}</filename> is the metadata name of the machine (BSP) and "kernel_type" is one
195 of the Yocto Project supported kernel types (e.g. "standard"):
196 <literallayout class='monospaced'>
197 linux-${MACHINE}-<replaceable>kernel_type</replaceable>-build
198 </literallayout>
199 </para>
200
201 <para>
202 The existing support in the <filename>kernel.org</filename> tree achieves this
203 default functionality.
204 </para>
205
206 <para>
207 This behavior means that all the generated files for a particular machine or BSP are now in
208 the build tree directory.
209 The files include the final <filename>.config</filename> file, all the <filename>.o</filename>
210 files, the <filename>.a</filename> files, and so forth.
211 Since each machine or BSP has its own separate
212 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>
213 in its own separate branch
214 of the Git repository, you can easily switch between different builds.
215 </para>
216 </section>
217</appendix>
218<!--
219vim: expandtab tw=80 ts=4
220-->