summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
-rw-r--r--documentation/kernel-manual/kernel-how-to.xml96
1 files changed, 53 insertions, 43 deletions
diff --git a/documentation/kernel-manual/kernel-how-to.xml b/documentation/kernel-manual/kernel-how-to.xml
index 9d15db44ab..0977a09896 100644
--- a/documentation/kernel-manual/kernel-how-to.xml
+++ b/documentation/kernel-manual/kernel-how-to.xml
@@ -1,5 +1,6 @@
1<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" 1<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
2"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> 2"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
3[<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] >
3 4
4<chapter id='kernel-how-to'> 5<chapter id='kernel-how-to'>
5 6
@@ -10,8 +11,8 @@
10 <title>Introduction</title> 11 <title>Introduction</title>
11 <para> 12 <para>
12 This chapter describes how to accomplish tasks involving the kernel's tree structure. 13 This chapter describes how to accomplish tasks involving the kernel's tree structure.
13 This information is designed to help the developer that wants to modify the Yocto Project kernel 14 The information is designed to help the developer that wants to modify the Yocto
14 and contribute changes upstream to the Yocto Project. 15 Project kernel and contribute changes upstream to the Yocto Project.
15 The information covers the following: 16 The information covers the following:
16 <itemizedlist> 17 <itemizedlist>
17 <listitem><para>Tree construction</para></listitem> 18 <listitem><para>Tree construction</para></listitem>
@@ -24,10 +25,11 @@
24 <section id='tree-construction'> 25 <section id='tree-construction'>
25 <title>Tree Construction</title> 26 <title>Tree Construction</title>
26 <para> 27 <para>
27 This section describes construction of the Yocto Project kernel repositories as accomplished 28 This section describes construction of the Yocto Project kernel repositories
28 by the Yocto Project team to create kernel repositories, which are found at 29 as accomplished by the Yocto Project team to create kernel repositories.
29 <ulink url='http://git.yoctoproject.org/cgit.cgi'>http://git.yoctoproject.org/cgit.cgi</ulink>, 30 These kernel repositories are found at
30 that can be shipped as part of a Yocto Project release. 31 <ulink url='&YOCTO_GIT_URL;/cgit.cgi'>&YOCTO_GIT_URL;/cgit.cgi</ulink>
32 and can be shipped as part of a Yocto Project release.
31 The team creates these repositories by 33 The team creates these repositories by
32 compiling and executing the set of feature descriptions for every BSP/feature 34 compiling and executing the set of feature descriptions for every BSP/feature
33 in the product. 35 in the product.
@@ -50,19 +52,25 @@
50 </literallayout> 52 </literallayout>
51 For another example of how to set up a local Git repository of the Linux Yocto 53 For another example of how to set up a local Git repository of the Linux Yocto
52 kernel files, see the 54 kernel files, see the
53 "<ulink url='http://www.yoctoproject.org/docs/1.1.1/dev-manual/dev-manual.html#local-kernel-files'>Linux Yocto Kernel</ulink>" bulleted item in 55 "<ulink url='&YOCTO_DOCS_DEV_URL;#local-kernel-files'>Linux Yocto Kernel</ulink>" bulleted item in The Yocto Project Development Manual.
54 <ulink url='http://www.yoctoproject.org/docs/1.1.1/dev-manual/dev-manual.html'>The Yocto Project Development Manual</ulink>.
55 </para> 56 </para>
56 <para> 57 <para>
57 Once the Git repository is set up on your local machine, you can switch to the 58 Once you have cloned the kernel Git repository on your local machine, you can
58 <filename>meta</filename> branch within the repository. 59 switch to the <filename>meta</filename> branch within the repository.
59 Here, you can see a snapshot of all the kernel configuration and feature descriptions that are 60 Here is an example that assumes the local Git repository for the kernel is in
60 used to build the kernel repository. 61 a top-level directory named <filename>linux-yocto-3.0</filename>:
62 <literallayout class='monospaced'>
63 $ cd ~/linux-yocto-3.0
64 $ git checkout -b meta origin/meta
65 </literallayout>
66 Once you have checked out and switched to the <filename>meta</filename> branch,
67 you can see a snapshot of all the kernel configuration and feature descriptions that are
68 used to build that particular kernel repository.
61 These descriptions are in the form of <filename>.scc</filename> files. 69 These descriptions are in the form of <filename>.scc</filename> files.
62 </para> 70 </para>
63 <para> 71 <para>
64 You should realize, however, that browsing your local snapshot of feature 72 You should realize, however, that browsing your local kernel repository
65 descriptions and patches is not an effective way to determine what is in a 73 for feature descriptions and patches is not an effective way to determine what is in a
66 particular kernel branch. 74 particular kernel branch.
67 Instead, you should use Git directly to discover the changes in a branch. 75 Instead, you should use Git directly to discover the changes in a branch.
68 Using Git is an efficient and flexible way to inspect changes to the kernel. 76 Using Git is an efficient and flexible way to inspect changes to the kernel.
@@ -76,10 +84,12 @@
76 </note> 84 </note>
77 </para> 85 </para>
78 <para> 86 <para>
79 The following steps describe what happens when the Yocto kernel team constructs 87 The following steps describe what happens when the Yocto Project Team constructs
80 the kernel tree given the introduction of a new top-level kernel feature or BSP. 88 the Yocto Linux kernel source Git repository (or tree) found at
81 These are the actions that effectively create the tree that includes the new feature, patch, 89 <ulink url='&YOCTO_GIT_URL;/cgit.cgi'></ulink> given the
82 or BSP: 90 introduction of a new top-level kernel feature or BSP.
91 These are the actions that effectively create the tree
92 that includes the new feature, patch or BSP:
83 <orderedlist> 93 <orderedlist>
84 <listitem><para>A top-level kernel feature is passed to the kernel build subsystem. 94 <listitem><para>A top-level kernel feature is passed to the kernel build subsystem.
85 Normally, this feature is a BSP for a particular kernel type.</para></listitem> 95 Normally, this feature is a BSP for a particular kernel type.</para></listitem>
@@ -126,10 +136,11 @@
126 Any add-ons and configuration data are applied to the end of an existing branch. 136 Any add-ons and configuration data are applied to the end of an existing branch.
127 The full repository generation that is found in the 137 The full repository generation that is found in the
128 official Yocto Project kernel repositories at 138 official Yocto Project kernel repositories at
129 <ulink url='http://git.yoctoproject.org/cgit.cgi'>http://git.yoctoproject.org/cgit.cgi</ulink> 139 <ulink url='&YOCTO_GIT_URL;/cgit.cgi'>http://git.yoctoproject.org/cgit.cgi</ulink>
130 is the combination of all supported boards and configurations.</para> 140 is the combination of all supported boards and configurations.</para>
131 <para>The technique the Yocto Project team uses is flexible and allows for seamless 141 <para>The technique the Yocto Project team uses is flexible and allows for seamless
132 blending of an immutable history with additional deployment specific patches. 142 blending of an immutable history with additional patches specific to a
143 deployment.
133 Any additions to the kernel become an integrated part of the branches.</para> 144 Any additions to the kernel become an integrated part of the branches.</para>
134 </note> 145 </note>
135 </para> 146 </para>
@@ -226,10 +237,8 @@
226 You can find Git documentation at 237 You can find Git documentation at
227 <ulink url='http://git-scm.com/documentation'></ulink>. 238 <ulink url='http://git-scm.com/documentation'></ulink>.
228 You can find a simple overview of using Git with the Yocto Project in the 239 You can find a simple overview of using Git with the Yocto Project in the
229 "<ulink url='http://www.yoctoproject.org/docs/1.1.1/dev-manual/dev-manual.html#git'>Git</ulink>" 240 "<ulink url='&YOCTO_DOCS_DEV_URL;#git'>Git</ulink>"
230 section of 241 section of The Yocto Project Development Manual.
231 <ulink url='http://www.yoctoproject.org/docs/1.1.1/dev-manual/dev-manual.html'>The Yocto
232 Project Development Manual</ulink>.
233 </para> 242 </para>
234 243
235 <section id='change-inspection-kernel-changes-commits'> 244 <section id='change-inspection-kernel-changes-commits'>
@@ -244,8 +253,8 @@
244 In projects that have a collection of directories that 253 In projects that have a collection of directories that
245 contain patches to the kernel, it is possible to inspect or "grep" the contents 254 contain patches to the kernel, it is possible to inspect or "grep" the contents
246 of the directories to get a general feel for the changes. 255 of the directories to get a general feel for the changes.
247 This sort of patch inspection is not an efficient way to determine what has been done to the 256 This sort of patch inspection is not an efficient way to determine what has been
248 kernel. 257 done to the kernel.
249 The reason it is inefficient is because there are many optional patches that are 258 The reason it is inefficient is because there are many optional patches that are
250 selected based on the kernel type and the feature description. 259 selected based on the kernel type and the feature description.
251 Additionally, patches could exist in directories that are not included in the search. 260 Additionally, patches could exist in directories that are not included in the search.
@@ -299,9 +308,11 @@
299 <title>Show a Particular Feature or Branch Change</title> 308 <title>Show a Particular Feature or Branch Change</title>
300 309
301 <para> 310 <para>
302 Significant features or branches are tagged in the Yocto Project tree to divide 311 Developers use tags in the Yocto Project tree to divide changes for significant
303 changes. 312 features or branches.
304 Remember to first determine (or add) the tag of interest. 313 Once you know a particular tag, you can use Git commands
314 to show changes associated with the tag and find the branches that contain
315 the feature.
305 <note> 316 <note>
306 Because BSP branch, <filename>kernel.org</filename>, and feature tags are all 317 Because BSP branch, <filename>kernel.org</filename>, and feature tags are all
307 present, there could be many tags. 318 present, there could be many tags.
@@ -354,10 +365,10 @@
354 The Yocto Project provides scripts that help you work in a collaborative development 365 The Yocto Project provides scripts that help you work in a collaborative development
355 environment. 366 environment.
356 For information on these scripts, see the 367 For information on these scripts, see the
357 "<ulink url='http://www.yoctoproject.org/docs/1.1.1/dev-manual/dev-manual.html#pushing-a-change-upstream'>Pushing a Change Upstream and Requesting a Pull</ulink>" and 368 "<ulink url='&YOCTO_DOCS_DEV_URL;#pushing-a-change-upstream'>Pushing a Change
358 "<ulink url='http://www.yoctoproject.org/docs/1.1.1/dev-manual/dev-manual.html#submitting-a-patch'>Submitting a Patch Through Email</ulink>" sections in 369 Upstream and Requesting a Pull</ulink>" and
359 <ulink url='http://www.yoctoproject.org/docs/1.1.1/dev-manual/dev-manual.html'>The 370 "<ulink url='&YOCTO_DOCS_DEV_URL;#submitting-a-patch'>Submitting a Patch Through
360 Yocto Project Development Manual</ulink>". 371 Email</ulink>" sections in The Yocto Project Development Manual.
361 </para> 372 </para>
362 373
363 <para> 374 <para>
@@ -637,9 +648,8 @@
637 The messages used to commit changes are a large part of these standards. 648 The messages used to commit changes are a large part of these standards.
638 Consequently, be sure that the headers for each commit have the required information. 649 Consequently, be sure that the headers for each commit have the required information.
639 For information on how to follow the Yocto Project commit message standards, see the 650 For information on how to follow the Yocto Project commit message standards, see the
640 "<ulink url='http://www.yoctoproject.org/docs/1.1.1/dev-manual/dev-manual.html#how-to-submit-a-change'>How to Submit a Change</ulink>" section in 651 "<ulink url='&YOCTO_DOCS_DEV_URL;#how-to-submit-a-change'>How to Submit a
641 <ulink url='http://www.yoctoproject.org/docs/1.1.1/dev-manual/dev-manual.html'>The 652 Change</ulink>" section in The Yocto Project Development Manual.
642 Yocto Project Development Manual</ulink>".
643 </para> 653 </para>
644 654
645 <para> 655 <para>
@@ -741,7 +751,8 @@
741 </para> 751 </para>
742 752
743 <para> 753 <para>
744 The following commands illustrate how you can condense and merge two BSPs into a second SCM: 754 The following commands illustrate how you can condense and merge two BSPs into a
755 second SCM:
745 <literallayout class='monospaced'> 756 <literallayout class='monospaced'>
746 &gt; git checkout yocto/standard/common-pc/base 757 &gt; git checkout yocto/standard/common-pc/base
747 &gt; git merge yocto/standard/common-pc-64/base 758 &gt; git merge yocto/standard/common-pc-64/base
@@ -772,10 +783,9 @@
772 existing similar BSP. 783 existing similar BSP.
773 The information is introductory in nature and does not provide step-by-step examples. 784 The information is introductory in nature and does not provide step-by-step examples.
774 For detailed information on how to create a BSP given an existing similar BSP, see 785 For detailed information on how to create a BSP given an existing similar BSP, see
775 the "<ulink url='http://www.yoctoproject.org/docs/1.1.1/dev-manual/dev-manual.html#dev-manual-bsp-appendix'>BSP Development Example</ulink>" appendix in 786 the "<ulink url='&YOCTO_DOCS_DEV_URL;#dev-manual-bsp-appendix'>BSP Development
776 <ulink url='http://www.yoctoproject.org/docs/1.1.1/dev-manual/dev-manual.html'>The 787 Example</ulink>" appendix in the Yocto Project Development Manual, or see the
777 Yocto Project Development Manual</ulink>, or see the 788 <ulink url='&YOCTO_WIKI_URL;/wiki/Transcript:_creating_one_generic_Atom_BSP_from_another'>Transcript:_creating_one_generic_Atom_BSP_from_another</ulink>
778 <ulink url='https://wiki.yoctoproject.org/wiki/Transcript:_creating_one_generic_Atom_BSP_from_another'>Transcript:_creating_one_generic_Atom_BSP_from_another</ulink>
779 wiki page. 789 wiki page.
780 </para> 790 </para>
781 791
@@ -792,7 +802,7 @@
792 your BSP easier. 802 your BSP easier.
793 You can find all the BSPs that are supported and ship with the Yocto Project 803 You can find all the BSPs that are supported and ship with the Yocto Project
794 on the Yocto Project's Download page at 804 on the Yocto Project's Download page at
795 <ulink url='http://www.yoctoproject.org/download'></ulink>.</para></listitem> 805 <ulink url='&YOCTO_HOME_URL;/download'></ulink>.</para></listitem>
796 <listitem><para><emphasis>Be sure you have the Base BSP:</emphasis> 806 <listitem><para><emphasis>Be sure you have the Base BSP:</emphasis>
797 You need to either have the Yocto Project Git repository set up or download 807 You need to either have the Yocto Project Git repository set up or download
798 the tarball of the base BSP. 808 the tarball of the base BSP.