summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorScott Rifenbark <srifenbark@gmail.com>2017-06-29 13:06:27 -0700
committerRichard Purdie <richard.purdie@linuxfoundation.org>2017-07-12 00:28:14 +0100
commit64f0f60b3fba36ff87fe78ec1e27e6398d206c51 (patch)
tree982a94c7f5c1455f16d0f03ae1396b4d464c131a
parentbdeb6db2fbc8563b03ea17d9c18a5fa19830e12f (diff)
downloadpoky-64f0f60b3fba36ff87fe78ec1e27e6398d206c51.tar.gz
dev-manual, kernel-dev: Moved kernel branch concepts to kernel-dev
Fixes [YOCTO #11630] The information in the dev-manual kernel overview area really neeeds to be in the Appendix on kernel structure in the kernel-dev manual. I moved that informtaion to the appendix. Removal of one redundant image was necessary from the dev-manual. The figure was literally repeated in the kernel manual already under a different file name. (From yocto-docs rev: 00ca68e760e41448c225fb1ca4a77f5201434b93) Signed-off-by: Scott Rifenbark <srifenbark@gmail.com> Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
-rw-r--r--documentation/Makefile4
-rw-r--r--documentation/dev-manual/dev-manual-model.xml75
-rw-r--r--documentation/dev-manual/figures/kernel-overview-1.pngbin35839 -> 0 bytes
-rw-r--r--documentation/kernel-dev/kernel-dev-concepts-appx.xml113
4 files changed, 92 insertions, 100 deletions
diff --git a/documentation/Makefile b/documentation/Makefile
index 3c02a3c2f0..a761c19dba 100644
--- a/documentation/Makefile
+++ b/documentation/Makefile
@@ -131,7 +131,7 @@ TARFILES = dev-style.css dev-manual.html \
131TARFILES = dev-style.css dev-manual.html \ 131TARFILES = dev-style.css dev-manual.html \
132 figures/dev-title.png \ 132 figures/dev-title.png \
133 figures/kernel-dev-flow.png \ 133 figures/kernel-dev-flow.png \
134 figures/kernel-overview-1.png figures/kernel-overview-2-generic.png \ 134 figures/kernel-overview-2-generic.png \
135 figures/recipe-workflow.png \ 135 figures/recipe-workflow.png \
136 figures/devtool-add-flow.png figures/devtool-modify-flow.png \ 136 figures/devtool-add-flow.png figures/devtool-modify-flow.png \
137 figures/devtool-upgrade-flow.png \ 137 figures/devtool-upgrade-flow.png \
@@ -205,7 +205,7 @@ TARFILES = mega-manual.html mega-style.css figures/yocto-environment.png \
205 figures/dev-title.png \ 205 figures/dev-title.png \
206 figures/git-workflow.png figures/index-downloads.png \ 206 figures/git-workflow.png figures/index-downloads.png \
207 figures/kernel-dev-flow.png \ 207 figures/kernel-dev-flow.png \
208 figures/kernel-overview-1.png figures/kernel-overview-2-generic.png \ 208 figures/kernel-overview-2-generic.png \
209 figures/source-repos.png figures/yp-download.png \ 209 figures/source-repos.png figures/yp-download.png \
210 figures/profile-title.png figures/kernelshark-all.png \ 210 figures/profile-title.png figures/kernelshark-all.png \
211 figures/kernelshark-choose-events.png \ 211 figures/kernelshark-choose-events.png \
diff --git a/documentation/dev-manual/dev-manual-model.xml b/documentation/dev-manual/dev-manual-model.xml
index bd6a85b987..05ff369f5d 100644
--- a/documentation/dev-manual/dev-manual-model.xml
+++ b/documentation/dev-manual/dev-manual-model.xml
@@ -86,67 +86,26 @@
86 <title>Kernel Overview</title> 86 <title>Kernel Overview</title>
87 87
88 <para> 88 <para>
89 The kernels are maintained using the Git revision control system 89 Upstream storage of all the available kernel source code is
90 that structures them using the familiar "tree", "branch", and "leaf" scheme. 90 one thing, while representing and using the code on your host
91 Branches represent diversions from general code to more specific code, while leaves 91 development system is another.
92 represent the end-points for a complete and unique kernel whose source files, 92 Conceptually, you can think of the kernel source repositories
93 when gathered from the root of the tree to the leaf, accumulate to create the files 93 as all the source files necessary for all the supported
94 necessary for a specific piece of hardware and its features. 94 Yocto Linux kernels.
95 The following figure displays this concept: 95 As a developer, you are just interested in the source files
96 <para> 96 for the kernel on which you are working.
97 <imagedata fileref="figures/kernel-overview-1.png"
98 width="6in" depth="6in" align="center" scale="100" />
99 </para>
100
101 <para>
102 Within the figure, the "Kernel.org Branch Point" represents the point in the tree
103 where a supported base kernel is modified from the Linux kernel.
104 For example, this could be the branch point for the <filename>linux-yocto-3.19</filename>
105 kernel.
106 Thus, everything further to the right in the structure is based on the
107 <filename>linux-yocto-3.19</filename> kernel.
108 Branch points to the right in the figure represent where the
109 <filename>linux-yocto-3.19</filename> kernel is modified for specific hardware
110 or types of kernels, such as real-time kernels.
111 Each leaf thus represents the end-point for a kernel designed to run on a specific
112 targeted device.
113 </para>
114
115 <para>
116 The overall result is a Git-maintained repository from which all the supported
117 kernel types can be derived for all the supported devices.
118 A big advantage to this scheme is the sharing of common features by keeping them in
119 "larger" branches within the tree.
120 This practice eliminates redundant storage of similar features shared among kernels.
121 </para>
122
123 <note>
124 Keep in mind the figure does not take into account all the supported Yocto
125 Project kernel types, but rather shows a single generic kernel just for conceptual purposes.
126 Also keep in mind that this structure represents the Yocto Project source repositories
127 that are either pulled from during the build or established on the host development system
128 prior to the build by either cloning a particular kernel's Git repository or by
129 downloading and unpacking a tarball.
130 </note>
131
132 <para>
133 Upstream storage of all the available kernel source code is one thing, while
134 representing and using the code on your host development system is another.
135 Conceptually, you can think of the kernel source repositories as all the
136 source files necessary for all the supported kernels.
137 As a developer, you are just interested in the source files for the kernel on
138 which you are working.
139 And, furthermore, you need them available on your host system. 97 And, furthermore, you need them available on your host system.
140 </para> 98 </para>
141 99
142 <para> 100 <para>
143 Kernel source code is available on your host system a couple of different 101 Kernel source code is available on your host system a couple
144 ways. 102 of different ways.
145 If you are working in the kernel all the time, you probably would want 103 If you are working in the kernel all the time, you probably
146 to set up your own local Git repository of the kernel tree. 104 would want to set up your own local Git repository of the
147 If you just need to make some patches to the kernel, you can access 105 Yocto Linux kernel tree.
148 temporary kernel source files that were extracted and used 106 If you just need to make some patches to the kernel, you can
149 during a build. 107 access temporary kernel source files that were extracted and
108 used during a build.
150 We will just talk about working with the temporary source code. 109 We will just talk about working with the temporary source code.
151 For more information on how to get kernel source code onto your 110 For more information on how to get kernel source code onto your
152 host system, see the 111 host system, see the
@@ -164,6 +123,8 @@
164 Thus, in a sense, the process constructs a local source tree specific to your 123 Thus, in a sense, the process constructs a local source tree specific to your
165 kernel to generate the new kernel image - a source generator if you will. 124 kernel to generate the new kernel image - a source generator if you will.
166 </para> 125 </para>
126
127 <para>
167 The following figure shows the temporary file structure 128 The following figure shows the temporary file structure
168 created on your host system when the build occurs. 129 created on your host system when the build occurs.
169 This 130 This
diff --git a/documentation/dev-manual/figures/kernel-overview-1.png b/documentation/dev-manual/figures/kernel-overview-1.png
deleted file mode 100644
index 116c0b9bd4..0000000000
--- a/documentation/dev-manual/figures/kernel-overview-1.png
+++ /dev/null
Binary files differ
diff --git a/documentation/kernel-dev/kernel-dev-concepts-appx.xml b/documentation/kernel-dev/kernel-dev-concepts-appx.xml
index 3606301cc7..ee40938b5d 100644
--- a/documentation/kernel-dev/kernel-dev-concepts-appx.xml
+++ b/documentation/kernel-dev/kernel-dev-concepts-appx.xml
@@ -175,74 +175,105 @@
175 175
176 <section id='kernel-architecture'> 176 <section id='kernel-architecture'>
177 <title>Kernel Architecture</title> 177 <title>Kernel Architecture</title>
178
178 <para> 179 <para>
179 This section describes the architecture of the kernels available through the 180 This section describes the architecture of the Yocto Linux kernels
180 Yocto Project and provides information 181 available through the Yocto Project and provides information
181 on the mechanisms used to achieve that architecture. 182 on the mechanisms used to achieve that architecture.
182 </para> 183 </para>
183 184
184 <section id='architecture-overview'> 185 <section id='architecture-overview'>
185 <title>Overview</title> 186 <title>Overview</title>
187
186 <para> 188 <para>
187 As mentioned earlier, a key goal of the Yocto Project is to present the 189 As mentioned earlier, a key goal of the Yocto Project is
188 developer with 190 to present the developer with a kernel that has a clear and
189 a kernel that has a clear and continuous history that is visible to the user. 191 continuous history that is visible to the user.
190 The architecture and mechanisms used achieve that goal in a manner similar to the 192 The architecture and mechanisms used achieve that goal in a
191 upstream <filename>kernel.org</filename>. 193 manner similar to upstream Linux kernel development in
194 <filename>kernel.org</filename>.
192 </para> 195 </para>
196
193 <para> 197 <para>
194 You can think of a Yocto Project kernel as consisting of a baseline Linux kernel with 198 You can think of a Yocto Linux kernel as consisting of a
195 added features logically structured on top of the baseline. 199 baseline Linux kernel with added features logically structured
196 The features are tagged and organized by way of a branching strategy implemented by the 200 on top of the baseline.
201 The features are tagged and organized by way of a branching
202 strategy implemented by the Yocto Project team using the
197 source code manager (SCM) Git. 203 source code manager (SCM) Git.
198 For information on Git as applied to the Yocto Project, see the 204 For information on Git as applied to the Yocto Project, see the
199 "<ulink url='&YOCTO_DOCS_REF_URL;#git'>Git</ulink>" section in the 205 "<ulink url='&YOCTO_DOCS_REF_URL;#git'>Git</ulink>" section
200 Yocto Project Development Manual. 206 in the Yocto Project Development Manual.
201 </para>
202 <para>
203 The result is that the user has the ability to see the added features and
204 the commits that make up those features.
205 In addition to being able to see added features, the user can also view the history of what
206 made up the baseline kernel.
207 </para> 207 </para>
208
208 <para> 209 <para>
209 The following illustration shows the conceptual Yocto Project kernel. 210 The result is that the user has the ability to see the added
211 features and the commits that make up those features.
212 In addition to being able to see added features, the user
213 can also view the history of what made up the baseline
214 Linux kernel.
210 </para> 215 </para>
216
211 <para> 217 <para>
218 The following illustration shows the conceptual Yocto
219 Linux kernel.
212 <imagedata fileref="figures/kernel-architecture-overview.png" width="6in" depth="7in" align="center" scale="100" /> 220 <imagedata fileref="figures/kernel-architecture-overview.png" width="6in" depth="7in" align="center" scale="100" />
213 </para> 221 </para>
222
214 <para> 223 <para>
215 In the illustration, the "Kernel.org Branch Point" 224 In the illustration, the "Kernel.org Branch Point" marks the
216 marks the specific spot (or release) from 225 specific spot (or Linux kernel release) from which the
217 which the Yocto Project kernel is created. 226 Yocto Linux kernel is created.
218 From this point "up" in the tree, features and differences are organized and tagged. 227 From this point forward in the tree, features and differences
228 are organized and tagged.
219 </para> 229 </para>
230
220 <para> 231 <para>
221 The "Yocto Project Baseline Kernel" contains functionality that is common to every kernel 232 The "Yocto Project Baseline Kernel" contains functionality that
222 type and BSP that is organized further up the tree. 233 is common to every kernel type and BSP that is organized
223 Placing these common features in the 234 further along in the tree.
224 tree this way means features do not have to be duplicated along individual branches of the 235 Placing these common features in the tree this way means
225 structure. 236 features do not have to be duplicated along individual
237 branches of the tree structure.
226 </para> 238 </para>
239
227 <para> 240 <para>
228 From the Yocto Project Baseline Kernel, branch points represent specific functionality 241 From the Yocto Project Baseline Kernel, branch points represent
229 for individual BSPs as well as real-time kernels. 242 specific functionality for individual Board Support Packages
230 The illustration represents this through three BSP-specific branches and a real-time 243 (BSPs) as well as real-time kernels.
231 kernel branch. 244 The illustration represents this through three BSP-specific
232 Each branch represents some unique functionality for the BSP or a real-time kernel. 245 branches and a real-time kernel branch.
246 Each branch represents some unique functionality for the BSP
247 or for a real-time Yocto Linux kernel.
233 </para> 248 </para>
249
234 <para> 250 <para>
235 In this example structure, the real-time kernel branch has common features for all 251 In this example structure, the real-time kernel branch has
236 real-time kernels and contains 252 common features for all real-time Yocto Linux kernels and
237 more branches for individual BSP-specific real-time kernels. 253 contains more branches for individual BSP-specific real-time
254 kernels.
238 The illustration shows three branches as an example. 255 The illustration shows three branches as an example.
239 Each branch points the way to specific, unique features for a respective real-time 256 Each branch points the way to specific, unique features for a
240 kernel as they apply to a given BSP. 257 respective real-time kernel as they apply to a given BSP.
241 </para> 258 </para>
259
242 <para> 260 <para>
243 The resulting tree structure presents a clear path of markers (or branches) to the 261 The resulting tree structure presents a clear path of markers
244 developer that, for all practical purposes, is the kernel needed for any given set 262 (or branches) to the developer that, for all practical
245 of requirements. 263 purposes, is the Yocto Linux kernel needed for any given set of
264 requirements.
265 <note>
266 Keep in mind the figure does not take into account all the
267 supported Yocto Linux kernels, but rather shows a single
268 generic kernel just for conceptual purposes.
269 Also keep in mind that this structure represents the Yocto
270 Project
271 <ulink url='&YOCTO_DOCS_REF_URL;#source-repositories'>Source Repositories</ulink>
272 that are either pulled from during the build or established
273 on the host development system prior to the build by either
274 cloning a particular kernel's Git repository or by
275 downloading and unpacking a tarball.
276 </note>
246 </para> 277 </para>
247 </section> 278 </section>
248 279