summaryrefslogtreecommitdiffstats
path: root/documentation/kernel-dev
diff options
context:
space:
mode:
authorScott Rifenbark <srifenbark@gmail.com>2017-06-30 14:51:55 -0700
committerRichard Purdie <richard.purdie@linuxfoundation.org>2017-07-12 00:28:15 +0100
commit431ceaea6c7786df0b78bf441752229515ac5f0d (patch)
tree4f459030200b7c809a7d900ddbd7db10f01e664d /documentation/kernel-dev
parent1d60050201b792c4536cd94e0c9a04fd122eb0d4 (diff)
downloadpoky-431ceaea6c7786df0b78bf441752229515ac5f0d.tar.gz
kernel-dev, dev-manual: Moved Kernel workflow section to kernel-dev
Fixes [YOCTO #11630] The overview section of modifying the kernel needed to be in the kernel-dev manual and not in the dev-manual. I moved it and took care of all the links and external references throughout the YP doc set. One figure was involved that had to be moved to the figures folder in kernel-dev from dev-manual. That is why the Makefile had to be edited. (From yocto-docs rev: 3a704b64544678785b883f82d6e82aedac6790c5) Signed-off-by: Scott Rifenbark <srifenbark@gmail.com> Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
Diffstat (limited to 'documentation/kernel-dev')
-rw-r--r--documentation/kernel-dev/figures/kernel-dev-flow.pngbin0 -> 35561 bytes
-rw-r--r--documentation/kernel-dev/kernel-dev-concepts-appx.xml5
-rw-r--r--documentation/kernel-dev/kernel-dev-intro.xml320
3 files changed, 227 insertions, 98 deletions
diff --git a/documentation/kernel-dev/figures/kernel-dev-flow.png b/documentation/kernel-dev/figures/kernel-dev-flow.png
new file mode 100644
index 0000000000..009105d122
--- /dev/null
+++ b/documentation/kernel-dev/figures/kernel-dev-flow.png
Binary files differ
diff --git a/documentation/kernel-dev/kernel-dev-concepts-appx.xml b/documentation/kernel-dev/kernel-dev-concepts-appx.xml
index 8eb8c30dce..7f6b82fee5 100644
--- a/documentation/kernel-dev/kernel-dev-concepts-appx.xml
+++ b/documentation/kernel-dev/kernel-dev-concepts-appx.xml
@@ -406,9 +406,8 @@
406 Yocto Project, is the preferred method by which to 406 Yocto Project, is the preferred method by which to
407 modify the kernel. 407 modify the kernel.
408 See the 408 See the
409 "<ulink url='&YOCTO_DOCS_DEV_URL;#kernel-modification-workflow'>Kernel Modification Workflow</ulink>" 409 "<link linkend='kernel-modification-workflow'>Kernel Modification Workflow</link>"
410 section in the Yocto Project Development Manual for 410 section.
411 information.
412 </para></listitem> 411 </para></listitem>
413 <listitem><para> 412 <listitem><para>
414 <emphasis>Cloned Repository:</emphasis> 413 <emphasis>Cloned Repository:</emphasis>
diff --git a/documentation/kernel-dev/kernel-dev-intro.xml b/documentation/kernel-dev/kernel-dev-intro.xml
index 83ca988acf..9f385d9751 100644
--- a/documentation/kernel-dev/kernel-dev-intro.xml
+++ b/documentation/kernel-dev/kernel-dev-intro.xml
@@ -5,105 +5,234 @@
5<chapter id='kernel-dev-intro'> 5<chapter id='kernel-dev-intro'>
6<title>Introduction</title> 6<title>Introduction</title>
7 7
8<!-- 8<section id='kernel-dev-overview'>
9<para> 9 <title>Overview</title>
10 <emphasis>AR - Darren Hart:</emphasis> See if the concepts in these
11 three bullets are adequately covered in somewhere in this manual:
12 <itemizedlist>
13 <listitem><para>Do we convey that our kernel Git repositories
14 have a clear and continuous history, similar to the way the
15 kernel Git repositories for <filename>kernel.org</filename>
16 do.
17 </para></listitem>
18 <listitem><para>Does the manual note that Yocto Project delivers
19 a key set of supported kernel types, where
20 each type is tailored to meet a specific use (e.g. networking,
21 consumer, devices, and so forth).</para></listitem>
22 <listitem><para>Do we convey that the Yocto Project uses a
23 Git branching strategy that, from a
24 developer's point of view, results in a linear path from the
25 baseline kernel.org, through a select group of features and
26 ends with their BSP-specific commits.</para></listitem>
27 </itemizedlist>
28</para>
29-->
30 10
31 <section id='kernel-dev-overview'> 11 <para>
32 <title>Overview</title> 12 Regardless of how you intend to make use of the Yocto Project,
13 chances are you will work with the Linux kernel.
14 This manual introduces the kernel development process and
15 provides background information on the Yocto Linux kernel
16 <ulink url='&YOCTO_DOCS_REF_URL;#metadata'>Metadata</ulink>,
17 describes common tasks you can perform using the kernel tools,
18 and shows you how to use the kernel Metadata needed to work with
19 the kernel inside the Yocto Project.
20 </para>
33 21
34 <para> 22 <para>
35 Regardless of how you intend to make use of the Yocto Project, 23 Each Yocto Project release has a set of Yocto Linux kernel recipes,
36 chances are you will work with the Linux kernel. 24 whose Git repositories you can view in the Yocto
37 This manual provides background information on the Yocto Linux kernel 25 <ulink url='&YOCTO_GIT_URL;'>Source Repositories</ulink> under
38 <ulink url='&YOCTO_DOCS_REF_URL;#metadata'>Metadata</ulink>, 26 the "Yocto Linux Kernel" heading.
39 describes common tasks you can perform using the kernel tools, 27 New recipes for the release track the latest Linux kernel
40 and shows you how to use the kernel Metadata needed to work with 28 upstream developments from
41 the kernel inside the Yocto Project. 29 <ulink url='http://www.kernel.org'></ulink> and introduce
42 </para> 30 newly-supported platforms.
43 31 Previous recipes in the release are refreshed and supported for at
44 <para> 32 least one additional Yocto Project release.
45 Each Yocto Project release has a set of linux-yocto recipes, whose 33 As they align, these previous releases are updated to include the
46 Git repositories you can view in the Yocto 34 latest from the
47 <ulink url='&YOCTO_GIT_URL;'>Source Repositories</ulink> under 35 <ulink url='&YOCTO_HOME_URL;/organization/long-term-support-initiative-ltsi'>Long Term Support Initiative</ulink>
48 the "Yocto Linux Kernel" heading. 36 (LTSI) project.
49 New recipes for the release track the latest upstream developments 37 Also included is a Yocto Linux kernel development recipe
50 and introduce newly-supported platforms. 38 (<filename>linux-yocto-dev.bb</filename>) should you want to work
51 Previous recipes in the release are refreshed and supported for at 39 with the very latest in upstream Yocto Linux kernel development and
52 least one additional release. 40 kernel Metadata development.
53 As they align, these previous releases are updated to include the 41 <note>
54 latest from the 42 For more on Yocto Linux kernels, see the
55 <ulink url='&YOCTO_HOME_URL;/organization/long-term-support-initiative-ltsi'>Long Term Support Initiative</ulink> 43 "<link linkend='kernel-big-picture'>Yocto Project Kernel Development and Maintenance</link>
56 (LTSI) project. 44 section.
57 Also included is a linux-yocto development recipe 45 </note>
58 (<filename>linux-yocto-dev.bb</filename>) should you want to work 46 </para>
59 with the very latest in upstream Linux kernel development and
60 kernel Metadata development.
61 </para>
62 47
63 <para> 48 <para>
64 The Yocto Project also provides a powerful set of kernel 49 The Yocto Project also provides a powerful set of kernel
65 tools for managing Linux kernel sources and configuration data. 50 tools for managing Yocto Linux kernel sources and configuration data.
66 You can use these tools to make a single configuration change, 51 You can use these tools to make a single configuration change,
67 apply multiple patches, or work with your own kernel sources. 52 apply multiple patches, or work with your own kernel sources.
68 </para> 53 </para>
69 54
70 <para> 55 <para>
71 In particular, the kernel tools allow you to generate configuration 56 In particular, the kernel tools allow you to generate configuration
72 fragments that specify only what you must, and nothing more. 57 fragments that specify only what you must, and nothing more.
73 Configuration fragments only need to contain the highest level 58 Configuration fragments only need to contain the highest level
74 visible <filename>CONFIG</filename> options as presented by the Linux 59 visible <filename>CONFIG</filename> options as presented by the
75 kernel <filename>menuconfig</filename> system. 60 Yocto Linux kernel <filename>menuconfig</filename> system.
76 Contrast this against a complete Linux kernel 61 Contrast this against a complete Yocto Linux kernel
77 <filename>.config</filename>, which includes all the automatically 62 <filename>.config</filename> file, which includes all the automatically
78 selected <filename>CONFIG</filename> options. 63 selected <filename>CONFIG</filename> options.
79 This efficiency reduces your maintenance effort and allows you 64 This efficiency reduces your maintenance effort and allows you
80 to further separate your configuration in ways that make sense for 65 to further separate your configuration in ways that make sense for
81 your project. 66 your project.
82 A common split separates policy and hardware. 67 A common split separates policy and hardware.
83 For example, all your kernels might support 68 For example, all your kernels might support the
84 the <filename>proc</filename> and <filename>sys</filename> filesystems, 69 <filename>proc</filename> and <filename>sys</filename> filesystems,
85 but only specific boards require sound, USB, or specific drivers. 70 but only specific boards require sound, USB, or specific drivers.
86 Specifying these configurations individually allows you to aggregate 71 Specifying these configurations individually allows you to aggregate
87 them together as needed, but maintains them in only one place. 72 them together as needed, but maintains them in only one place.
88 Similar logic applies to separating source changes. 73 Similar logic applies to separating source changes.
89 </para> 74 </para>
90 75
91 <para> 76 <para>
92 If you do not maintain your own kernel sources and need to make 77 If you do not maintain your own kernel sources and need to make
93 only minimal changes to the sources, the released recipes provide a 78 only minimal changes to the sources, the released recipes provide a
94 vetted base upon which to layer your changes. 79 vetted base upon which to layer your changes.
95 Doing so allows you to benefit from the continual kernel 80 Doing so allows you to benefit from the continual kernel
96 integration and testing performed during development of the 81 integration and testing performed during development of the
97 Yocto Project. 82 Yocto Project.
98 </para> 83 </para>
84
85 <para>
86 If, instead, you have a very specific Linux kernel source tree
87 and are unable to align with one of the official Yocto Linux kernel
88 recipes, an alternative exists by which you can use the Yocto
89 Project Linux kernel tools with your own kernel sources.
90 </para>
91</section>
92
93<section id='kernel-modification-workflow'>
94 <title>Kernel Modification Workflow</title>
95
96 <para>
97 Kernel modification involves changing the Yocto Project kernel,
98 which could involve changing configuration options as well as adding
99 new kernel recipes.
100 Configuration changes can be added in the form of configuration
101 fragments, while recipe modification comes through the kernel's
102 <filename>recipes-kernel</filename> area in a kernel layer you create.
103 </para>
104
105 <para>
106 This section presents a high-level overview of the Yocto Project
107 kernel modification workflow.
108 You can find additional information here:
109 <itemizedlist>
110 <listitem><para>
111 "<ulink url='&YOCTO_DOCS_DEV_URL;#patching-the-kernel'>Patching the Kernel</ulink>"
112 in the Yocto Project Development Manual.
113 </para></listitem>
114 <listitem><para>
115 "<ulink url='&YOCTO_DOCS_DEV_URL;#configuring-the-kernel'>Configuring the Kernel</ulink>"
116 in the Yocto Project Development Manual.
117 </para></listitem>
118 </itemizedlist>
119 This illustration and the following list summarizes the kernel
120 modification general workflow.
121 <imagedata fileref="figures/kernel-dev-flow.png"
122 width="6in" depth="5in" align="center" scalefit="1" />
123 </para>
124
125 <para>
126 <orderedlist>
127 <listitem><para>
128 <emphasis>Set up Your Host Development System to Support
129 Development Using the Yocto Project</emphasis>:
130 See
131 "<ulink url='&YOCTO_DOCS_QS_URL;#the-linux-distro'>The Linux Distribution</ulink>"
132 and
133 "<ulink url='&YOCTO_DOCS_QS_URL;#packages'>The Build Host Packages</ulink>"
134 sections both in the Yocto Project Quick Start for
135 requirements.
136 </para></listitem>
137 <listitem><para>
138 <emphasis>Clone the <filename>poky</filename> Repository</emphasis>:
139 Having the
140 <ulink url='&YOCTO_DOCS_REF_URL;#source-directory'>Source Directory</ulink>
141 on your system gives you access to the build process and tools
142 you need.
143 For information on how to get these files, see the
144 "<ulink url='&YOCTO_DOCS_DEV_URL;#cloning-the-poky-repository'>Cloning the <filename>poky</filename> Repository</ulink>"
145 section in the Yocto Project Development Manual.
146 </para></listitem>
147 <listitem><para>
148 <emphasis>Establish the Temporary Kernel Source Files</emphasis>:
149 Temporary kernel source files are kept in the
150 <ulink url='&YOCTO_DOCS_REF_URL;#build-directory'>Build Directory</ulink>
151 created by the OpenEmbedded build system when you run BitBake.
152 If you have never built the kernel in which you are
153 interested, you need to run an initial build to
154 establish local kernel source files.</para>
155
156 <para>If you are building an image for the first time, you
157 need to get the build environment ready by sourcing an
158 environment setup script
159 (i.e. <filename>oe-init-build-env</filename> or
160 <filename>oe-init-build-env-memres</filename>).
161 You also need to be sure two key configuration files
162 (<filename>local.conf</filename> and
163 <filename>bblayers.conf</filename>) are configured
164 appropriately.</para>
165
166 <para>The entire process for building an image is overviewed
167 in the
168 "<ulink url='&YOCTO_DOCS_QS_URL;#qs-building-images'>Building Images</ulink>"
169 section of the Yocto Project Quick Start.
170 You might want to reference this information.
171 You can find more information on BitBake in the
172 <ulink url='&YOCTO_DOCS_BB_URL;'>BitBake User Manual</ulink>.
173 </para>
174
175 <para>The build process supports several types of images to
176 satisfy different needs.
177 See the "<ulink url='&YOCTO_DOCS_REF_URL;#ref-images'>Images</ulink>"
178 chapter in the Yocto Project Reference Manual for information
179 on supported images.
180 </para></listitem>
181 <listitem><para>
182 <emphasis>Make Changes to the Kernel Source Code if
183 applicable</emphasis>:
184 Modifying the kernel does not always mean directly
185 changing source files.
186 However, if you have to do this, you make the changes to the
187 files in the Build Directory.
188 </para></listitem>
189 <listitem><para>
190 <emphasis>Make Kernel Configuration Changes if
191 Applicable</emphasis>:
192 If your situation calls for changing the kernel's
193 configuration, you can use
194 <link linkend='generating-configuration-files'><filename>menuconfig</filename></link>,
195 which allows you to interactively develop and test the
196 configuration changes you are making to the kernel.
197 Saving changes you make with <filename>menuconfig</filename>
198 updates the kernel's <filename>.config</filename> file.
199 <note><title>Warning</title>
200 Try to resist the temptation to directly edit an
201 existing <filename>.config</filename> file, which is
202 found in the Build Directory among the source code
203 used for the build (e.g. see the workflow illustration
204 in the
205 "<link linkend='kernel-modification-workflow'>Kernel Modification Workflow</link>"
206 section).
207 Doing so, can produce unexpected results when the
208 OpenEmbedded build system regenerates the configuration
209 file.
210 </note>
211 Once you are satisfied with the configuration
212 changes made using <filename>menuconfig</filename>
213 and you have saved them, you can directly compare the
214 resulting <filename>.config</filename> file against an
215 existing original and gather those changes into a
216 <ulink url='&YOCTO_DOCS_DEV_URL;#creating-config-fragments'>configuration fragment file</ulink>
217 to be referenced from within the kernel's
218 <filename>.bbappend</filename> file.</para>
219
220 <para>Additionally, if you are working in a BSP layer
221 and need to modify the BSP's kernel's configuration,
222 you can use the
223 <ulink url='&YOCTO_DOCS_BSP_URL;#managing-kernel-patches-and-config-items-with-yocto-kernel'><filename>yocto-kernel</filename></ulink>
224 script as well as <filename>menuconfig</filename>.
225 The <filename>yocto-kernel</filename> script lets
226 you interactively set up kernel configurations.
227 </para></listitem>
228 <listitem><para>
229 <emphasis>Rebuild the Kernel Image With Your Changes</emphasis>:
230 Rebuilding the kernel image applies your changes.
231 </para></listitem>
232 </orderedlist>
233 </para>
234</section>
99 235
100 <para>
101 If, instead, you have a very specific Linux kernel source tree
102 and are unable to align with one of the official linux-yocto
103 recipes, an alternative exists by which you can use the Yocto
104 Project Linux kernel tools with your own kernel sources.
105 </para>
106 </section>
107 236
108 <section id='kernel-dev-other-resources'> 237 <section id='kernel-dev-other-resources'>
109 <title>Other Resources</title> 238 <title>Other Resources</title>
@@ -126,8 +255,9 @@
126 </para></listitem> 255 </para></listitem>
127 <listitem><para>The "<ulink url='&YOCTO_DOCS_DEV_URL;#understanding-and-creating-layers'>Understanding and Creating Layers</ulink>" section 256 <listitem><para>The "<ulink url='&YOCTO_DOCS_DEV_URL;#understanding-and-creating-layers'>Understanding and Creating Layers</ulink>" section
128 in the Yocto Project Development Manual</para></listitem> 257 in the Yocto Project Development Manual</para></listitem>
129 <listitem><para>The "<ulink url='&YOCTO_DOCS_DEV_URL;#modifying-the-kernel'>Modifying the Kernel</ulink>" section 258 <listitem><para>The "<link linkend='kernel-modification-workflow'>Kernel Modification Workflow</link>"
130 in the Yocto Project Development Manual.</para></listitem> 259 section.
260 </para></listitem>
131 </itemizedlist> 261 </itemizedlist>
132 </para> 262 </para>
133 263