summaryrefslogtreecommitdiffstats
path: root/documentation/dev-manual
diff options
context:
space:
mode:
authorScott Rifenbark <scott.m.rifenbark@intel.com>2011-07-27 13:03:18 -0700
committerRichard Purdie <richard.purdie@linuxfoundation.org>2011-08-04 15:06:48 +0100
commit568a15c821dca324d3e7a1691ad784025a8c8319 (patch)
treec71db19fa9a6965a623b92accd492ef3212dfa52 /documentation/dev-manual
parent3a9da1c68157b26117c74796b2304b5d25f4cb91 (diff)
downloadpoky-568a15c821dca324d3e7a1691ad784025a8c8319.tar.gz
documentation/dev-manual/dev-manual-kernel-appendix.xml: Added appendix
New file for the kernel example. this will be an appendix. (From yocto-docs rev: fca7e4fbb3d1e738700349d6169d7217c04e4b31) Signed-off-by: Scott Rifenbark <scott.m.rifenbark@intel.com> Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
Diffstat (limited to 'documentation/dev-manual')
-rw-r--r--documentation/dev-manual/dev-manual-kernel-appendix.xml446
1 files changed, 446 insertions, 0 deletions
diff --git a/documentation/dev-manual/dev-manual-kernel-appendix.xml b/documentation/dev-manual/dev-manual-kernel-appendix.xml
new file mode 100644
index 0000000000..fc93b53744
--- /dev/null
+++ b/documentation/dev-manual/dev-manual-kernel-appendix.xml
@@ -0,0 +1,446 @@
1<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
2"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
3
4<chapter id='dev-manual-cases'>
5
6<title>Development Cases</title>
7
8 <section id='modifying-a-kernel-kernel-example'>
9 <title>Modifying a Kernel</title>
10
11 <para>
12 Kernel modification involves changing or adding configurations to an existing kernel, or
13 adding recipes to the kernel that are needed to support specific hardware features.
14 The process is similar to creating a Board Support Package (BSP) except that it does not
15 involve a BSP layer.
16 </para>
17
18 <para>
19 This section presents a brief overview of the kernel structure and then provides a simple
20 example that shows how to modify the kernel.
21 </para>
22
23 <section id='yocto-project-kernel'>
24 <title>Yocto Project Kernel Overview</title>
25
26 <para>
27 When one thinks of the source files for a kernel they usually think of a fixed structure
28 of files that contain kernel patches.
29 The Yocto Project, however, employs mechanisims that in a sense result in a kernel source
30 generator.
31 </para>
32
33 <para>
34 The Yocto Project uses the source code management (SCM) tool Git to manage and track Yocto
35 Project files.
36 Git employs branching strategies that effectively produce a tree-like structure whose
37 branches represent diversions from more general code.
38 For example, suppose two kernels are basically identical with the exception of a couple
39 different features in each.
40 In the Yocto Project source repositories managed by Git a main branch can contain the
41 common or shared
42 parts of the kernel source and two branches that diverge from that common branch can
43 each contain the features specific to the respective kernel.
44 The result is a managed tree whose "leaves" represent the end of a specific path that yields
45 a set of kernel source files necessary for a specific piece of hardware and its features.
46 </para>
47
48 <para>
49 A big advantage to this scheme is the sharing of common features by keeping them in
50 "larger" branches that are further up the tree.
51 This practice eliminates redundant storage of similar features shared among kernels.
52 </para>
53
54 <para>
55 When you build the kernel on your development system all files needed for the build
56 are taken from the Yocto Project source repositories pointed to by the
57 <filename>SRC_URI</filename> variable and gathered in a temporary work area
58 where they are subsequently used to create the unique kernel.
59 Thus, in a sense, the process constructs a local source tree specific to your
60 kernel to generate the new kernel image - a source generator if you will.
61 </para>
62
63 <para>
64 For a complete discussion of the Yocto Project kernel's architcture and its branching strategy,
65 see the <ulink url='http://www.yoctoproject.org/docs/1.1/kernel-manual/kernel-manual.html'>
66 The Yocto Project Kernel Architecture and Use Manual</ulink>.
67 </para>
68
69 <para>
70 You can find a web interface to the Yocto Project source repository at
71 <ulink url='http://git.yoctoproject.org/'></ulink>.
72 Within the interface you will see groups of related source code, each of which can
73 be cloned using Git to result in a working Git repository on your local system
74 (referred to as the "local Yocto Project files" in this manual).
75 The Yocto Project supports four types of kernels in its source repositories at
76 <ulink url='http://git.yoctoproject.org/'></ulink>:
77 <itemizedlist>
78 <listitem><para><emphasis><filename>linux-yocto-2.6.34</filename></emphasis> - The
79 stable Linux Yocto kernel that is based on the Linux 2.6.34 release.</para></listitem>
80 <listitem><para><emphasis><filename>linux-yocto-2.6.37</filename></emphasis> - The current
81 Linux Yocto kernel that is based on the Linux 2.6.37 release.</para></listitem>
82 <listitem><para><emphasis><filename>linux-yocto-dev</filename></emphasis> - A development
83 kernel based on the Linux 2.6.39-rc1 release.</para></listitem>
84 <listitem><para><emphasis><filename>linux-2.6</filename></emphasis> - A kernel based on
85 minimal Linux mainline tracking.
86 [WRITER'S NOTE: I don't know which Git repository the user needs to clone to get this
87 repository on their development system.]</para></listitem>
88 </itemizedlist>
89 </para>
90 </section>
91
92 <section id='modifying-a-kernel-example'>
93 <title>Modifying a Kernel Example</title>
94
95 <para>
96 This section presents a simple example that illustrates kernel modification
97 based on the <filename>linux-yocto-2.6.37</filename> kernel.
98 The example uses the audio and mixer capabilities supported by the
99 <ulink url='http://www.alsa-project.org/main/index.php/Main_Page'>Advanced Linux
100 Sound Architecture (ALSA) Project</ulink>.
101 As the example progresses you will see how to do the following:
102 <itemizedlist>
103 <listitem><para>Iteratively modify a base kernel locally.</para></listitem>
104 <listitem><para>Provide a recipe-based solution for your modified kernel.
105 </para></listitem>
106 <listitem><para>Proved an "in-tree" solution for your modified kernel
107 (i.e. make the modifcations part of the Yocto Project).</para></listitem>
108 </itemizedlist>
109 </para>
110
111 <para>
112 The example flows as follows:
113 </para>
114
115 <para>
116 <itemizedlist>
117 <listitem><para>Be sure your host development system is set up to support
118 development using the Yocto Project.
119 See
120 <ulink url='http://www.yoctoproject.org/docs/1.1/yocto-project-qs/yocto-project-qs.html#the-linux-distro'>
121 The Linux Distributions</ulink> section and
122 <ulink url='http://www.yoctoproject.org/docs/1.1/yocto-project-qs/yocto-project-qs.html#packages'>
123 The Packages</ulink> section both
124 in the Yocto Project Quick Start for requirements.
125 You will also need a release of Yocto Project installed on the host.</para></listitem>
126 <listitem><para>Set up your environment for optimal local kernel development.
127 </para></listitem>
128 <listitem><para>Create a layer to isolate your kernel work.</para></listitem>
129 <listitem><para>Next item.</para></listitem>
130 <listitem><para>Next item.</para></listitem>
131 <listitem><para>Next item.</para></listitem>
132 <listitem><para>Next item.</para></listitem>
133 </itemizedlist>
134 </para>
135
136 <section id='setting-up-yocto-project-kernel-example'>
137 <title>Setting Up Yocto Project</title>
138
139 <para>
140 You need to have the Yocto Project files available on your host system.
141 The process is identical to that described in the
142 <xref linkend='getting-setup'>"Getting Setup"</xref> section earlier in this
143 manual.
144 Be sure to either set up a local Git repository for <filename>poky</filename>
145 or download and unpack the Yocto Project release tarball.
146 </para>
147 </section>
148
149 <section id='create-a-git-repository-of-poky-extras'>
150 <title>Create a Git Repository of <filename>poky-extras</filename></title>
151
152 <para>
153 Everytime you change a configuration or add a recipe to the kernel you need to
154 do a fetch from the Linux Yocto kernel source repositories.
155 This can get tedious and time consuming if you need to fetch the entire
156 Linux Yocto 2.6.37 Git repository down from the Internet everytime you make a change
157 to the kernel.
158 </para>
159
160 <para>
161 You can get around this by setting up a <filename>meta-kernel-dev</filename>
162 area on your local system.
163 This area contains "append" files for every kernel recipe, which also include
164 a <filename>KSRC</filename> statement that points to the kernel source files.
165 You can set up the environment so that the <filename>KSRC</filename> points to the
166 <filename>meta-kernel-dev</filename>, thus pulling source from a local area.
167 This setup can speed up development time.
168 </para>
169
170 <para>
171 To get set up you need to do two things: create a local Git repository
172 of the <filename>poky-extras</filename> repository, and create a bare clone of the
173 Linux Yocto 2.6.37 kernel Git repository.
174 </para>
175
176 <para>
177 The following transcript shows how to clone the <filename>poky-extras</filename>
178 Git repository into the current working directory, which is <filename>poky</filename>
179 in this example.
180 The command creates the repository in a directory named <filename>poky-extras</filename>:
181 <literallayout class='monospaced'>
182 $ git clone git://git.yoctoproject.org/poky-extras
183 Initialized empty Git repository in /home/scottrif/poky/poky-extras/.git/
184 remote: Counting objects: 532, done.
185 remote: Compressing objects: 100% (472/472), done.
186 remote: Total 532 (delta 138), reused 307 (delta 39)
187 Receiving objects: 100% (532/532), 534.28 KiB | 362 KiB/s, done.
188 Resolving deltas: 100% (138/138), done.
189 </literallayout>
190 </para>
191
192 <para>
193 This transcript shows how to clone a bare Git repository of the Linux Yocto
194 2.6.37 kernel:
195 <literallayout class='monospaced'>
196 $ git clone --bare git://git.yoctoproject.org/linux-yocto-2.6.37
197 Initialized empty Git repository in /home/scottrif/linux-yocto-2.6.37.git/
198 remote: Counting objects: 1886034, done.
199 remote: Compressing objects: 100% (314326/314326), done.
200 remote: Total 1886034 (delta 1570202), reused 1870335 (delta 1554798)
201 Receiving objects: 100% (1886034/1886034), 401.51 MiB | 714 KiB/s, done.
202 Resolving deltas: 100% (1570202/1570202), done.
203 </literallayout>
204 </para>
205
206 <para>
207 The bare clone of the Linux Yocto 2.6.37 kernel on your local system mirrors
208 the upstream repository of the kernel.
209 You can effectively point to this local clone now during development to avoid
210 having to fetch the entire Linux Yocto 2.6.37 kernel every time you make a
211 kernel change.
212 </para>
213 </section>
214
215 <section id='create-a-layer-for-your-kernel-work'>
216 <title>Create a Layer for Your Kernel Work</title>
217
218 <para>
219 It is always good to isolate your work using your own layer.
220 Doing so allows you to experiment and easily start over should things go wrong.
221 This example uses a layer named <filename>meta-amixer</filename>.
222 </para>
223
224 <para>
225 When you set up a layer for kernel work you should follow the general layout
226 guidelines as described for BSP layers.
227 This layout is described in the
228 <ulink url='http://www.yoctoproject.org/docs/1.1/bsp-guide/bsp-guide.html#bsp-filelayout'>
229 Example Filesystem Layout</ulink> section of the Board Support Package (BSP) Development
230 Guide.
231 In the standard layout you will notice a suggested structure for recipes and
232 configuration information.
233 [WRITER'S NOTE: The <filename>meta-elc</filename> example uses an
234 <filename>images</filename> directory.
235 Currently, <filename>images</filename> is not part of the standard BSP layout.
236 I need to find out from Darren if this directory is required for kernel work.]
237 </para>
238
239 <para>
240 [WRITER'S NOTE: I need a paragraph here describing how to set up the layer.
241 I am not sure if you should copy an existing BSP layer and modify from there.
242 Or, if you should just look at a BSP layer and then create your own files.
243 Email to Darren on this but no answer yet.]
244 </para>
245 </section>
246
247 <section id='making-changes-to-your-kernel-layer'>
248 <title>Making Changes to Your Kernel Layer</title>
249
250 <para>
251 In the standard layer structure you have several areas that you need to examine or
252 modify.
253 For this example the layer contains four areas:
254 <itemizedlist>
255 <listitem><para><emphasis><filename>conf</filename></emphasis> - Contains the
256 <filename>layer.conf</filename> that identifies the location of the recipe files.
257 </para></listitem>
258 <listitem><para><emphasis><filename>images</filename></emphasis> - Contains the
259 image recipe file.
260 This recipe includes the base image you will be using and specifies other
261 packages the image might need.</para></listitem>
262 <listitem><para><emphasis><filename>recipes-bsp</filename></emphasis> - Contains
263 recipes specific to the hardware for which you are developing the kernel.
264 </para></listitem>
265 <listitem><para><emphasis><filename>recipes-kernel</filename></emphasis> - Contains the
266 "append" files that add information to the main recipe kernel.
267 </para></listitem>
268 </itemizedlist>
269 </para>
270
271 <para>
272 Let's take a look at the <filename>layer.conf</filename> in the
273 <filename>conf</filename> directory first.
274 This configuration file enables the Yocto Project build system to locate and
275 use the information in your new layer.
276 </para>
277
278 <para>
279 The variable <filename>BBPATH</filename> needs to include the path to your layer
280 as follows:
281 <literallayout class='monospaced'>
282 BBPATH := "${BBPATH}:${LAYERDIR}"
283 </literallayout>
284 And, the variable <filename>BBFILES</filename> needs to be modified to include your
285 recipe and append files:
286 <literallayout class='monospaced'>
287 BBFILES := "${BBFILES} ${LAYERDIR}/images/*.bb \
288 ${LAYERDIR}/images/*.bbappend \
289 ${LAYERDIR}/recipes-*/*/*.bb \
290 ${LAYERDIR}/recipes-*/*/*.bbappend"
291 </literallayout>
292 Finally, you need to be sure to use your layer name in these variables at the
293 end of the file:
294 <literallayout class='monospaced'>
295 BBFILE_COLLECTIONS += "elc"
296 BBFILE_PATTERN_elc := "^${LAYERDIR}/"
297 BBFILE_PRIORITY_elc = "9"
298 </literallayout>
299 </para>
300
301 <para>
302 The <filename>images</filename> directory contains an append file that helps
303 further define the image.
304 In our example, the base image is <filename>core-image-minimal</filename>.
305 The image does, however, need some additional modules that we are using
306 for this example.
307 These modules support the amixer functionality.
308 Here is the append file:
309 <literallayout class='monospaced'>
310 require recipes-core/images/poky-image-minimal.bb
311
312 IMAGE_INSTALL += "dropbear alsa-utils-aplay alsa-utils-alsamixer"
313 IMAGE_INSTALL_append_qemux86 += " kernel-module-snd-ens1370 \
314 kernel-module-snd-rawmidi kernel-module-loop kernel-module-nls-cp437 \
315 kernel-module-nls-iso8859-1 qemux86-audio alsa-utils-amixer"
316
317 LICENSE = "MIT"
318 </literallayout>
319 </para>
320
321 <para>
322 While the focus of this example is not on the BSP, it is worth mentioning that the
323 <filename>recipes-bsp</filename> directory has the recipes and append files for
324 features that the hardware requires.
325 In this example, there is a script and a recipe to support the
326 <filename>amixer</filename> functionality in QEMU.
327 It is beyond the scope of this manual to go too deeply into the script.
328 Suffice it to say that the script tests for the presence of the mixer, sets up
329 default mixer values, enables the mixer, unmutes master and then
330 sets the volume to 100.
331 </para>
332
333 <para>
334 The recipe <filename>qemu86-audio.bb</filename> installs and runs the
335 <filename>amixer</filename> when the system boots.
336 Here is the recipe:
337 <literallayout class='monospaced'>
338 SUMMARY = "Provide a basic init script to enable audio"
339 DESCRIPTION = "Set the volume and unmute the Front mixer setting during boot."
340 SECTION = "base"
341 LICENSE = "MIT"
342 LIC_FILES_CHKSUM = "file://${POKYBASE}/LICENSE;md5=3f40d7994397109285ec7b81fdeb3b58"
343
344 PR = "r4"
345
346 inherit update-rc.d
347
348 RDEPENDS = "alsa-utils-amixer"
349
350 SRC_URI = "file://qemux86-audio"
351
352 INITSCRIPT_NAME = "qemux86-audio"
353 INITSCRIPT_PARAMS = "defaults 90"
354
355 do_install() {
356 install -d ${D}${sysconfdir} \
357 ${D}${sysconfdir}/init.d
358 install -m 0755 ${WORKDIR}/qemux86-audio ${D}${sysconfdir}/init.d
359 cat ${WORKDIR}/${INITSCRIPT_NAME} | \
360 sed -e 's,/etc,${sysconfdir},g' \
361 -e 's,/usr/sbin,${sbindir},g' \
362 -e 's,/var,${localstatedir},g' \
363 -e 's,/usr/bin,${bindir},g' \
364 -e 's,/usr,${prefix},g' > ${D}${sysconfdir}/init.d/${INITSCRIPT_NAME}
365 chmod 755 ${D}${sysconfdir}/init.d/${INITSCRIPT_NAME}
366 }
367 </literallayout>
368 </para>
369
370 <para>
371 The last area to look at is <filename>recipes-kernel</filename>.
372 This area holds configuration fragments and kernel append files.
373 The append file must have the same name as the kernel recipe, which is
374 <filename>linux-yocto-2.6.37</filename> in this example.
375 The file can <filename>SRC_URI</filename> statements to point to configuration
376 fragments you might have in the layer.
377 The file can also contain <filename>KERNEL_FEATURES</filename> statements that specify
378 included kernel configurations that ship with the Yocto Project.
379 </para>
380 </section>
381 </section>
382 </section>
383
384</chapter>
385
386
387
388
389
390<!--
391
392
393 <para>
394 [WRITER'S NOTE: This section is a second example that focuses on just modifying the kernel.
395 I don't have any information on this yet.
396 </para>
397
398 <para>
399 Here are some points to consider though:
400 <itemizedlist>
401 <listitem><para>Reference Darren's presentation
402 <ulink url='http://events.linuxfoundation.org/events/embedded-linux-conference/hart'>
403 here</ulink></para></listitem>
404 <listitem><para>Reference <xref linkend='dev-manual-start'>Getting Started with the Yocto Project</xref>
405 section to get set up at minimum.</para></listitem>
406 <listitem><para>Are there extra steps I need specific to kernel development to get started?</para></listitem>
407 <listitem><para>What do I do to get set up?
408 Is it a matter of just installing YP and having some pieces together?
409 What are the pieces?</para></listitem>
410 <listitem><para>Where do I get the base kernel to start with?</para></listitem>
411 <listitem><para>Do I install the appropriate toolchain?</para></listitem>
412 <listitem><para>What kernel git repository do I use?</para></listitem>
413 <listitem><para>What is the conversion script?
414 What does it do?</para></listitem>
415 <listitem><para>What do I have to do to integrate the kernel layer?</para></listitem>
416 <listitem><para>What do I use to integrate the kernel layer?
417 HOB?
418 Do I just Bitbake it?</para></listitem>
419 <listitem><para>Using the System Image Creator.]</para></listitem>
420 </itemizedlist>
421 </para>
422 </section>
423 </section>
424</section>
425
426<section id='user-application-development'>
427 <title>User Application Development</title>
428
429 <para>
430 [WRITER'S NOTE: This section is the second major development case - developing an application.
431 Here are points to consider:
432 <itemizedlist>
433 <listitem><para>User-space Application Development scenario overview.</para></listitem>
434 <listitem><para>Using the Yocto Eclipse Plug-in.</para></listitem>
435 <listitem><para>Back-door support.</para></listitem>
436 <listitem><para>I feel there is more to this area than we have captured during our two
437 review meetings.]</para></listitem>
438 </itemizedlist>
439 </para>
440</section>
441</chapter>
442-->
443
444<!--
445vim: expandtab tw=80 ts=4
446-->
generated by cgit v1.2.3-54-g00ecf (git 2.39.0) at 2024-11-17 02:49:11 +0000