diff options
Diffstat (limited to 'documentation')
-rw-r--r-- | documentation/kernel-manual/kernel-how-to.xml | 96 |
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 | > git checkout yocto/standard/common-pc/base | 757 | > git checkout yocto/standard/common-pc/base |
747 | > git merge yocto/standard/common-pc-64/base | 758 | > 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. |