summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorScott Rifenbark <scott.m.rifenbark@intel.com>2011-08-31 06:46:23 -0700
committerRichard Purdie <richard.purdie@linuxfoundation.org>2011-09-02 23:38:49 +0100
commit837a46434f2c8b846880ca6da87cf69c1f0df12f (patch)
tree770f6ac18a0ced45af02f78286373c8e9ff3a41f
parent5da4d3eb2b0108f66b461906fa69a562ddcce462 (diff)
downloadpoky-837a46434f2c8b846880ca6da87cf69c1f0df12f.tar.gz
documentation/dev-manual/dev-manual-model.xml: Edits to Modifying Kernel
Complete re-write of this section based on feedback from Dave Stewart. Dave's comments centered around not being able to understand the overall concepts of the Git repositories, the source areas on the host, etc. I have added several illustrations and written around them to try and better explain the kernel storage system in Git used by YP and how that tranlates into host-resident code that the developer ultimately uses and the Poky build system uses for the build. (From yocto-docs rev: 4e37f68f77261f6519426fb81ba407c456f8d1a1) Signed-off-by: Scott Rifenbark <scott.m.rifenbark@intel.com> Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
-rw-r--r--documentation/dev-manual/dev-manual-model.xml162
1 files changed, 118 insertions, 44 deletions
diff --git a/documentation/dev-manual/dev-manual-model.xml b/documentation/dev-manual/dev-manual-model.xml
index 2dfc46e740..813c96eca8 100644
--- a/documentation/dev-manual/dev-manual-model.xml
+++ b/documentation/dev-manual/dev-manual-model.xml
@@ -172,9 +172,9 @@
172 <para> 172 <para>
173 You can view a video presentation on "Building Custom Embedded Images with Yocto" 173 You can view a video presentation on "Building Custom Embedded Images with Yocto"
174 at <ulink url='http://free-electrons.com/blog/elc-2011-videos'>Free Electrons</ulink>. 174 at <ulink url='http://free-electrons.com/blog/elc-2011-videos'>Free Electrons</ulink>.
175 You can also find supplemental information in the 175 You can also find supplemental information in
176 <ulink url='http://yoctoproject.org/docs/1.1/bsp-guide/bsp-guide.html'> 176 <ulink url='http://yoctoproject.org/docs/1.1/bsp-guide/bsp-guide.html'>
177 Board Support Package (BSP) Development Guide</ulink>. 177 The Board Support Package (BSP) Development Guide</ulink>.
178 Finally, there is wiki page write up of the example located 178 Finally, there is wiki page write up of the example located
179 <ulink url='https://wiki.yoctoproject.org/wiki/Transcript:_creating_one_generic_Atom_BSP_from_another'> 179 <ulink url='https://wiki.yoctoproject.org/wiki/Transcript:_creating_one_generic_Atom_BSP_from_another'>
180 here</ulink> you might find helpful. 180 here</ulink> you might find helpful.
@@ -195,9 +195,9 @@
195 <para> 195 <para>
196 The remainder of this section presents a high-level overview of the Linux Yocto 196 The remainder of this section presents a high-level overview of the Linux Yocto
197 kernel architecture and the steps to modify the Linux Yocto kernel. 197 kernel architecture and the steps to modify the Linux Yocto kernel.
198 For a complete discussion of the kernel, see the 198 For a complete discussion of the kernel, see
199 <ulink url='http://www.yoctoproject.org/docs/1.1/kernel-manual/kernel-manual.html'> 199 <ulink url='http://www.yoctoproject.org/docs/1.1/kernel-manual/kernel-manual.html'>
200 Yocto Project Kernel Architecture and Use Manual</ulink>. 200 The Yocto Project Kernel Architecture and Use Manual</ulink>.
201 You can reference <xref linkend='dev-manual-kernel-appendix'>Kernel Modification Example</xref> 201 You can reference <xref linkend='dev-manual-kernel-appendix'>Kernel Modification Example</xref>
202 for a detailed example that changes the configuration of a kernel. 202 for a detailed example that changes the configuration of a kernel.
203 </para> 203 </para>
@@ -208,32 +208,120 @@
208 <para> 208 <para>
209 When one thinks of the source files for a kernel they usually think of a fixed structure 209 When one thinks of the source files for a kernel they usually think of a fixed structure
210 of files that contain kernel patches. 210 of files that contain kernel patches.
211 The Yocto Project, however, employs mechanisims that in a sense result in a kernel source 211 The Yocto Project, however, employs mechanisims, that in a sense, result in a kernel source
212 generator. 212 generator.
213 </para> 213 </para>
214 214
215 <para> 215 <para>
216 The Yocto Project uses the source code management (SCM) tool Git to manage and track Yocto 216 You can find a web interface to the Linux Yocto kernel source repositories at
217 Project files. 217 <ulink url='http://git.yoctoproject.org/'></ulink>.
218 Git employs branching strategies that effectively produce a tree-like structure whose 218 If you look at the interface, you will see to the left a grouping of
219 branches represent diversions from more general code. 219 Git repositories titled "Yocto Linux Kernel."
220 For example, suppose two kernels are basically identical with the exception of a couple 220 Within this group, you will find the four different kernels supported by
221 different features in each. 221 the Yocto Project:
222 In the Yocto Project source repositories managed by Git a main branch can contain the 222 <itemizedlist>
223 common or shared 223 <listitem><para><emphasis><filename>linux-yocto-2.6.34</filename></emphasis> - The
224 parts of the kernel source and two branches that diverge from that common branch can 224 stable Linux Yocto kernel that is based on the Linux 2.6.34 release.</para></listitem>
225 each contain the features specific to the respective kernel. 225 <listitem><para><emphasis><filename>linux-yocto-2.6.37</filename></emphasis> - The
226 The result is a managed tree whose "leaves" represent the end of a specific path that yields 226 stable Linux Yocto kernel that is based on the Linux 2.6.37 release.</para></listitem>
227 a set of kernel source files necessary for a specific piece of hardware and its features. 227 <listitem><para><emphasis><filename>linux-yocto-3.0</filename></emphasis> - The current
228 Linux Yocto kernel that is based on the Linux 3.0 release.</para></listitem>
229 <listitem><para><emphasis><filename>linux-yocto-dev</filename></emphasis> - A development
230 kernel based on the latest upstream release candidate available.</para></listitem>
231 </itemizedlist>
232 </para>
233
234 <para>
235 The kernels are maintained using the Git application that, in a sense, structures
236 them in a "tree" complete with branches and leaves.
237 Branches represent diversions from general code to more specific code, while leaves
238 represent the end-points for a complete and unique kernel whose source files
239 when gathered from the root of the tree to the leaf accumulate to create the files
240 necessary for a specific piece of hardware and its features.
241 The following figure displays this concept:
242 <para>
243 <imagedata fileref="figures/kernel-overview-1.png"
244 width="6in" depth="6in" align="center" scale="100" />
245 </para>
246
247 <para>
248 Within the figure, the "Kernel.org Branch Point" represents the point in the tree
249 where a supported base kernel diverges from the Linux kernel.
250 For example, this could be the branch point for the <filename>linux-yocto-3.0</filename>
251 kernel.
252 Thus, everything further to the right in the structure is based on the
253 <filename>linux-yocto-3.0</filename> kernel.
254 Branch points to right in the figure represent where the
255 <filename>linux-yocto-3.0</filename> kernel is modified for specific hardware
256 or types of kernels, such as real-time kernels.
257 Each leaf thus represents the end-point for a kernel designed to run on a specific
258 targeted device.
228 </para> 259 </para>
229 260
230 <para> 261 <para>
262 The overall result is a Git-maintained repository from which all the supported
263 Yocto Project kernels can be derived for all the supported Yocto Project devices.
231 A big advantage to this scheme is the sharing of common features by keeping them in 264 A big advantage to this scheme is the sharing of common features by keeping them in
232 "larger" branches that are further up the tree. 265 "larger" branches within the tree.
233 This practice eliminates redundant storage of similar features shared among kernels. 266 This practice eliminates redundant storage of similar features shared among kernels.
234 </para> 267 </para>
235 268
269 <note>
270 Keep in mind the figure does not take into account all four supported Linux Yocto
271 kernel types, but rather shows a single generic kernel just for conceptual purposes.
272 Also keep in mind that this structure represents the Yocto Project source repositories
273 that are either pulled from during the build or established on the host development system
274 prior to the build by either cloning a particular kernel's Git repository or by
275 downloading and unpacking a tarball.
276 </note>
277
278 <para>
279 Storage of all the available kernel source code is one thing, while representing the
280 code on your host development system is another.
281 Conceptually, you can think of the Yocto Project kernel source repositories as all the
282 source files necessary for all the supported kernels.
283 As a developer, you are just interested in the source files for the kernel on
284 on which you are working.
285 And, furthermore, you need them available on your host system.
286 </para>
287
236 <para> 288 <para>
289 You make kernel source code available on your host development system by using
290 Git to create a bare clone of the Linux Yocto kernel Git repository
291 in which you are interested.
292 Then, you use Git again to clone a copy of that bare clone.
293 This copy represents the directory structure on your host system that is particular
294 to the kernel you want.
295 These are the files you actually modify to change the kernel.
296 See the <link linkend='local-kernel-files'>Linux Yocto Kernel</link> item earlier
297 in this manual for an example of how to set up the kernel source directory
298 structure on your host system.
299 </para>
300
301 <para>
302 This next figure illustrates how the kernel source files might be arranged on
303 your host system.
304 </para>
305
306 <para>
307 <imagedata fileref="figures/kernel-overview-3.png"
308 width="6in" depth="4in" align="center" scale="100" />
309 </para>
310
311 <para>
312 In the previous figure, the file structure on the left represents the bare clone
313 set up to track the Yocto Project kernel Git repository.
314 The structure on the right represents the copy of the bare clone.
315 When you make modifcations to the kernel source code, this is the area in which
316 you work.
317 Once you make corrections, you must use Git to push the committed changes to the
318 bare clone.
319 The example in <xref linkend='modifying-the-kernel-source-code'>
320 Modifying the Kernel Source Code</xref> provides a detailed example.
321 </para>
322
323 <para>
324 What happens during the build?
237 When you build the kernel on your development system all files needed for the build 325 When you build the kernel on your development system all files needed for the build
238 are taken from the Yocto Project source repositories pointed to by the 326 are taken from the Yocto Project source repositories pointed to by the
239 <filename>SRC_URI</filename> variable and gathered in a temporary work area 327 <filename>SRC_URI</filename> variable and gathered in a temporary work area
@@ -241,38 +329,24 @@
241 Thus, in a sense, the process constructs a local source tree specific to your 329 Thus, in a sense, the process constructs a local source tree specific to your
242 kernel to generate the new kernel image - a source generator if you will. 330 kernel to generate the new kernel image - a source generator if you will.
243 </para> 331 </para>
244 332 The following figure shows the temporary file structure
245 <para> 333 created on your host system when the build occurs.
246 You can find a web interface to the Yocto Project source repository at 334 This build directory contains all the source files used during the build.
247 <ulink url='http://git.yoctoproject.org/'></ulink>.
248 Within the interface you will see groups of related source code, each of which can
249 be cloned using Git to result in a working Git repository on your local system
250 (referred to as the "local Yocto Project files" in this manual).
251 </para> 335 </para>
252 336
253 <para> 337 <para>
254 The Yocto Project supports four types of kernels in its source repositories at 338 <imagedata fileref="figures/kernel-overview-2.png"
255 <ulink url='http://git.yoctoproject.org/'></ulink>: 339 width="6in" depth="5in" align="center" scale="100" />
256 <itemizedlist> 340 </para>
257 <listitem><para><emphasis><filename>linux-yocto-2.6.34</filename></emphasis> - The
258 stable Linux Yocto kernel that is based on the Linux 2.6.34 release.</para></listitem>
259 <listitem><para><emphasis><filename>linux-yocto-2.6.37</filename></emphasis> - The
260 stable Linux Yocto kernel that is based on the Linux 2.6.37 release.</para></listitem>
261 <listitem><para><emphasis><filename>linux-yocto-3.0</filename></emphasis> - The current
262 Linux Yocto kernel that is based on the Linux 3.0 release.</para></listitem>
263 <listitem><para><emphasis><filename>linux-yocto-dev</filename></emphasis> - A development
264 kernel based on the latest upstream release candidate available.</para></listitem>
265 <listitem><para><emphasis><filename>linux-2.6</filename></emphasis> - A kernel based on
266 minimal Linux mainline tracking.
267 You can find the <filename>.bbappend</filename> for this kernel in the
268 <filename>meta-kernel-dev</filename> Git repository.</para></listitem>
269 </itemizedlist>
270 </para>
271 341
272 <para> 342 <para>
273 For a complete discussion of the Yocto Project kernel's architcture and its branching strategy, 343 Again, for a complete discussion of the Yocto Project kernel's architcture and its
344 branching strategy,
274 see the <ulink url='http://www.yoctoproject.org/docs/1.1/kernel-manual/kernel-manual.html'> 345 see the <ulink url='http://www.yoctoproject.org/docs/1.1/kernel-manual/kernel-manual.html'>
275 The Yocto Project Kernel Architecture and Use Manual</ulink>. 346 The Yocto Project Kernel Architecture and Use Manual</ulink>.
347 Also, you can reference
348 <xref linkend='modifying-the-kernel-source-code'>Modifying the Kernel Source Code</xref>
349 for a detailed example that modifies the kernel.
276 </para> 350 </para>
277 </section> 351 </section>
278 352