summaryrefslogtreecommitdiffstats
path: root/documentation
diff options
context:
space:
mode:
authorScott Rifenbark <scott.m.rifenbark@intel.com>2011-07-27 07:03:00 -0700
committerRichard Purdie <richard.purdie@linuxfoundation.org>2011-08-04 15:06:44 +0100
commit313f932aaac55229e3e14209b18abe4d28bc8b46 (patch)
tree6f9f87ee7530f07d161435ec64285aeb274c7074 /documentation
parent2c7834cae617d75c89192ba65444a2f5c9b00357 (diff)
downloadpoky-313f932aaac55229e3e14209b18abe4d28bc8b46.tar.gz
documentation/dev-manual/dev-manual-bsp-appendix.xml: New appendix for BSP
I decided to take the long detailed example of the BSP creation and make it an appendix. This commit represents a simple copy of the existing dev-manual-cases chapter. Further commits will change the text to make it suitable as an appendix. (From yocto-docs rev: 8c1308c4361f48ce7f7aa104cde7e6f6a820faa4) Signed-off-by: Scott Rifenbark <scott.m.rifenbark@intel.com> Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
Diffstat (limited to 'documentation')
-rw-r--r--documentation/dev-manual/dev-manual-bsp-appendix.xml1192
1 files changed, 1192 insertions, 0 deletions
diff --git a/documentation/dev-manual/dev-manual-bsp-appendix.xml b/documentation/dev-manual/dev-manual-bsp-appendix.xml
new file mode 100644
index 0000000000..cf1033e530
--- /dev/null
+++ b/documentation/dev-manual/dev-manual-bsp-appendix.xml
@@ -0,0 +1,1192 @@
1<!DOCTYPE appendix PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
2"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
3
4<appendix id='dev-manual-bsp-appendix'>
5
6<title>Development Cases</title>
7
8<para>
9 Many development cases exist for which you can use the Yocto Project.
10 However, for the purposes of this manual we are going to focus on two common development cases or groupings:
11 System Development and User Application Development.
12 System Development covers Board Support Package (BSP) development and kernel modification.
13 User Application Development covers development of applications that you intend to run on some
14 target hardware.
15</para>
16
17<para>
18 [WRITERS NOTE: What is undetermined at this point is how much of the entire development process
19 we include in this particular chapter.
20 In other words, do we cover debugging and emulation steps here on a case-specific basis?
21 Or, do we capture that information in the appropriate subsequent chapter by case?]
22</para>
23
24<section id='system-development-app'>
25 <title>System Development</title>
26
27 <para>
28 System development involves modification or creation of an image that you want to run on
29 a specific hardware target.
30 Usually when you want to create an image that runs on embedded hardware the image does
31 not require the same amount of features that a full-fledged Linux distribution provides.
32 Thus, you can create a much smaller image that is designed to just use the hardware
33 features for your particular hardware.
34 </para>
35
36 <para>
37 To help you understand how system development works in the Yocto Project, this section
38 covers two types of image development: BSP creation and kernel modification.
39 </para>
40
41 <section id='developing-a-board-support-package-bsp-app'>
42 <title>Developing a Board Support Package (BSP)</title>
43
44 <para>
45 A BSP is a package of recipes that when applied while building an image results in
46 an image you can run on a particular board.
47 Thus, the package, when compiled into the new image, supports the operation of the board.
48 </para>
49
50 <note>
51 For a brief list of terms used when describing the development process in the Yocto Project,
52 see <xref linkend='yocto-project-terms'>Yocto Project Terms</xref> in this manual.
53 </note>
54
55 <para>
56 Here are the basic steps involved in creating a BSP:
57 <orderedlist>
58 <listitem><para>Be sure your host development system is set up to support
59 development using the Yocto Project.
60 See
61 <ulink url='http://www.yoctoproject.org/docs/1.1/yocto-project-qs/yocto-project-qs.html#the-linux-distro'>
62 The Linux Distributions</ulink> section and
63 <ulink url='http://www.yoctoproject.org/docs/1.1/yocto-project-qs/yocto-project-qs.html#packages'>
64 The Packages</ulink> section both
65 in the Yocto Project Quick Start for requirements.
66 You will also need a release of Yocto Project installed on the host.</para></listitem>
67 <listitem><para>Choose a BSP available with Yocto Project that most closely represents
68 your hardware.</para></listitem>
69 <listitem><para>Get set up with a base BSP.</para></listitem>
70 <listitem><para>Make a copy of the existing BSP and isolate your work by creating a layer
71 for your recipes.</para></listitem>
72 <listitem><para>Make configuration and recipe changes to your new BSP layer.</para></listitem>
73 <listitem><para>Prepare for the build.</para></listitem>
74 <listitem><para>Select and configure the kernel.</para></listitem>
75 <listitem><para>Identify the machine branch.</para></listitem>
76 <listitem><para>Build the image.</para></listitem>
77 </orderedlist>
78 You can view a video presentation of the BSP creation process
79 <ulink url='http://free-electrons.com/blog/elc-2011-videos'>here</ulink>.
80 You can also find supplemental information in the
81 <ulink url='http://yoctoproject.org/docs/1.1/bsp-guide/bsp-guide.html'>
82 Board Support Package (BSP) Development Guide</ulink>.
83 Finally, there is wiki page write up of the example located
84 <ulink url='https://wiki.yoctoproject.org/wiki/Transcript:_creating_one_generic_Atom_BSP_from_another'>
85 here</ulink> you might find helpful.
86 </para>
87
88 <section id='setting-up-yocto-project-app'>
89 <title>Setting Up Yocto Project</title>
90
91 <para>
92 You need to have the Yocto Project files available on your host system.
93 You can get files through tarball extraction or by cloning the <filename>poky</filename>
94 Git repository.
95 Typically, cloning the Git repository is the method to use.
96 This allows you to maintain a complete history of changes and facilitates you
97 contributing back to the Yocto Project.
98 However, if you just want a hierarchical file structure that contains the recipes
99 and metadata that let you develop you can download tarballs from the
100 <ulink url='http://yoctoproject.org/download'>download page</ulink>.
101 </para>
102
103 <para>
104 Regardless of the method you use this manual will refer to the resulting
105 hierarchical set of files as "the local Yocto Project files."
106 </para>
107
108 <para>
109 [WRITER'S NOTE: I need to substitute correct and actual filenames for the
110 1.1 release throughout this example once they become available.]
111 </para>
112
113 <para>
114 If you download a tarball you can extract it into any directory you want using the
115 tar command.
116 For example, the following command extracts the Yocto Project 1.1 release tarball
117 into the current working directory and sets up a file structure whose top-level
118 directory is named <filename>poky-1.1</filename>:
119 <literallayout class='monospaced'>
120 $ tar xfj poky-1.1.tar.bz2
121 </literallayout>
122 </para>
123
124 <para>
125 The following transcript shows how to clone the <filename>poky</filename> Git repository
126 into the current working directory.
127 The command creates the repository in a directory named <filename>poky</filename>:
128 <literallayout class='monospaced'>
129 $ git clone git://git.yoctoproject.org/poky
130 Initialized empty Git repository in /home/scottrif/poky/.git/
131 remote: Counting objects: 107624, done.
132 remote: Compressing objects: 100% (37128/37128), done.
133 remote: Total 107624 (delta 73393), reused 99851 (delta 67287)
134 Receiving objects: 100% (107624/107624), 69.74 MiB | 483 KiB/s, done.
135 Resolving deltas: 100% (73393/73393), done.
136 </literallayout>
137 </para>
138
139 <para>
140 Once you have the local <filename>poky</filename> Git repository set up,
141 you have many development branches from which you can work.
142 From inside the repository you can see the branch names and the tag names used
143 in the Git repository using either of the following two commands:
144 <literallayout class='monospaced'>
145 $ git branch -a
146 $ git tag -l
147 </literallayout>
148 For this example we are going to use the Yocto Project 1.1 Release,
149 which maps to the <filename>1.1</filename> branch in the repository.
150 These commands create a local branch named <filename>1.1</filename>
151 that tracks the remote branch of the same name.
152 <literallayout class='monospaced'>
153
154 $ cd poky
155 $ git checkout -b 1.1 origin/1.1
156 Switched to a new branch '1.1'
157 </literallayout>
158 </para>
159 </section>
160
161 <section id='choosing-a-base-bsp-app'>
162 <title>Choosing a Base BSP</title>
163
164 <para>
165 The Yocto Project ships with several BSPs that support various hardware.
166 It is best to base your new BSP on an existing BSP rather than create all the
167 recipes and configuration files from scratch.
168 While it is possible to create everything from scratch, basing your new BSP
169 on something that is close is much easier.
170 Or, at a minimum, it gives you some structure with which to start.
171 </para>
172
173 <para>
174 At this point you need to understand your target hardware well enough to determine which
175 existing BSP it most closely matches.
176 Things to consider are your hardware’s on-board features such as CPU type and graphics support.
177 You should look at the README files for supported BSPs to get an idea of which one
178 you could use.
179 A generic Atom-based BSP to consider is the Crown Bay that does not support
180 the Intel® Embedded Media Graphics Driver (EMGD).
181 The remainder of this example uses that base BSP.
182 </para>
183
184 <para>
185 To see the supported BSPs, go to the Yocto Project
186 <ulink url='http://www.yoctoproject.org/download'>download page</ulink> and click
187 on “BSP Downloads.”
188 </para>
189 </section>
190
191 <section id='getting-your-base-bsp-app'>
192 <title>Getting Your Base BSP</title>
193
194 <para>
195 You need to have the base BSP layer on your development system.
196 Like the local Yocto Project files, you can get the BSP
197 layer one of two ways:
198 download the BSP tarball and extract it, or set up a local Git repository that
199 has the Yocto Project BSP layers.
200 You should use the same method that you used to get the local Yocto Project files earlier.
201 </para>
202
203 <para>
204 If you are using tarball extraction, simply download the tarball for the base
205 BSP you chose in the previous step and then extract it into any directory
206 you choose using the tar command.
207 Upon extraction, the BSP source directory (layer) will be named
208 <filename>meta-&lt;BSP_name&gt;</filename>.
209 The following command extracts the Crown Bay BSP into the current directory and names it
210 <filename>meta-crownbay</filename>:
211 <literallayout class='monospaced'>
212 $ tar xjf crownbay-noemgd-1.1.tar.bz2
213 </literallayout>
214 </para>
215
216 <para>
217 If you cloned a <filename>poky</filename> Git repository
218 then you need to set up a different local Git repository
219 (<filename>meta-intel</filename>) for the BSP.
220 The <filename>meta-intel</filename> Git repository contains all the metadata
221 that supports BSP creation.
222 When you set up the <filename>meta-intel</filename> Git repository you can
223 set it up anywhere you want.
224 We will set up the repository inside the
225 <filename>poky</filename> Git repository in this example.
226 </para>
227
228 <para>
229 The following transcript shows the steps to clone the <filename>meta-intel</filename>
230 Git repository inside the <filename>poky</filename> Git repository created earlier in this
231 example.
232 <literallayout class='monospaced'>
233 $cd poky
234 $ git clone git://git.yoctoproject.org/meta-intel.git
235 Initialized empty Git repository in /home/scottrif/poky/meta-intel/.git/
236 remote: Counting objects: 1325, done.
237 remote: Compressing objects: 100% (1078/1078), done.
238 remote: Total 1325 (delta 546), reused 85 (delta 27)
239 Receiving objects: 100% (1325/1325), 1.56 MiB | 330 KiB/s, done.
240 Resolving deltas: 100% (546/546), done.
241 </literallayout>
242 </para>
243
244 <para>
245 Because <filename>meta-intel</filename> is its own Git repository you will want
246 to be sure you are in the appropriate branch for your work.
247 For this example we are going to use the <filename>1.1</filename> branch.
248 <literallayout class='monospaced'>
249 $ cd meta-intel
250 $ git checkout -b 1.1 origin/1.1
251 Switched to a new branch 'bernard'
252 </literallayout>
253 </para>
254 </section>
255
256 <section id='making-a-copy-of-the-base bsp-to-create-your-new-bsp-layer-app'>
257 <title>Making a Copy of the Base BSP to Create Your New BSP Layer</title>
258
259 <para>
260 Now that you have the local Yocto Project files and the base BSP files you need to create a
261 new layer for your BSP.
262 </para>
263
264 <para>
265 Layers are ideal for isolating and storing work for a given piece of hardware.
266 A layer is really just a location or area in which you place the recipes for your BSP.
267 In fact, a BSP is, in itself, a special type of layer.
268 Consider an application as another example that illustrates a layer.
269 Suppose you are creating an application that has library or other dependencies in
270 order for it to compile and run.
271 The layer, in this case, would be where all the recipes that define those dependencies
272 are kept. The key point for a layer is that it is an isolated area that contains
273 all the relevant information for the project that the Yocto Project build system knows about.
274 </para>
275
276 <note>
277 The Yocto Project supports four BSPs that are part of the
278 Yocto Project release: <filename>atom-pc</filename>, <filename>beagleboard</filename>,
279 <filename>mpc8315e</filename>, and <filename>routerstationpro</filename>.
280 The recipes and configurations for these four BSPs are located and dispersed
281 within local Yocto Project files.
282 Consequently, they are not totally isolated in the spirit of layers unless you think
283 of <filename>meta-yocto</filename> as a layer itself.
284 On the other hand, BSP layers for Crown Bay, Emenlow, Jasper Forest,
285 N450, and Sugar Bay are isolated.
286 </note>
287
288 <para>
289 When you set up a layer for a new BSP you should follow a standard layout.
290 This layout is described in the
291 <ulink url='http://www.yoctoproject.org/docs/1.1/bsp-guide/bsp-guide.html#bsp-filelayout'>
292 Example Filesystem Layout</ulink> section of the Board Support Package (BSP) Development
293 Guide.
294 In the standard layout you will notice a suggested structure for recipes and
295 configuration information.
296 You can see the standard layout for the Crown Bay BSP in this example by examining the
297 directory structure of the <filename>meta-crownbay</filename> layer inside the
298 local Yocto Project files.
299 </para>
300
301 <para>
302 To create your BSP layer you simply copy the <filename>meta-crownbay</filename>
303 layer to a new layer.
304 For this example the new layer will be named <filename>meta-mymachine</filename>.
305 The name must follow the BSP layer naming convention, which is
306 <filename>meta-&lt;name&gt;</filename>.
307 The following example assumes your working directory is <filename>meta-intel</filename>
308 inside the local Yocto Project files.
309 If you downloaded and expanded a Crown Bay tarball then you simply copy the resulting
310 <filename>meta-crownbay</filename> directory structure to a location of your choice.
311 Good practice for a Git repository, however, is to just copy the new layer alongside
312 the existing
313 BSP layers in the <filename>meta-intel</filename> Git repository:
314 <literallayout class='monospaced'>
315 $ cp -a meta-crownbay/ meta-mymachine
316 </literallayout>
317 </para>
318 </section>
319
320 <section id='making-changes-to-your-bsp-app'>
321 <title>Making Changes to Your BSP</title>
322
323 <para>
324 Right now you have two identical BSP layers with different names:
325 <filename>meta-crownbay</filename> and <filename>meta-mymachine</filename>.
326 You need to change your configurations so that they work for your new BSP and
327 your particular hardware.
328 We will look first at the configurations, which are all done in the layer’s
329 <filename>conf</filename> directory.
330 </para>
331
332 <para>
333 First, since in this example the new BSP will not support EMGD we will get rid of the
334 <filename>crownbay.conf</filename> file and then rename the
335 <filename>crownbay-noemgd.conf</filename> file to <filename>mymachine.conf</filename>.
336 Much of what we do in the configuration directory is designed to help the Yocto Project
337 build system work with the new layer and to be able to find and use the right software.
338 The following two commands result in a single machine configuration file named
339 <filename>mymachine.conf</filename>.
340 <literallayout class='monospaced'>
341 $ rm meta-mymachine/conf/machine/crownbay.conf
342 $ mv meta-mymachine/conf/machine/crownbay-noemgd.conf \
343 meta-mymachine/conf/machine/mymachine.conf
344 </literallayout>
345 </para>
346
347 <para>
348 The next step makes changes to <filename>mymachine.conf</filename> itself.
349 The only changes needed for this example are changes to the comment lines.
350 Here we simply substitute the Crown Bay name with an appropriate name.
351 </para>
352
353 <para>
354 Note that inside the <filename>mymachine.conf</filename> is the
355 <filename>PREFERRED_PROVIDER_virtual/kernel</filename> statement.
356 This statement identifies the kernel that the BSP is going to use.
357 In this case the BSP is using <filename>linux-yocto</filename>, which is the
358 current Linux Yocto kernel based on the Linux 2.6.37 release.
359 </para>
360
361 <para>
362 The next configuration file in the new BSP layer we need to edit is <filename>layer.conf</filename>.
363 This file identifies build information needed for the new layer.
364 You can see the
365 <ulink url='http://www.yoctoproject.org/docs/1.1/bsp-guide/bsp-guide.html#bsp-filelayout-layer'>
366 Layer Configuration File</ulink> section in the Board Support Packages (BSP) Development Guide
367 for more information on this configuration file.
368 Basically, we are changing the existing statements to work with our BSP.
369 </para>
370
371 <para>
372 The file contains these statements that reference the Crown Bay BSP:
373 <literallayout class='monospaced'>
374 BBFILE_COLLECTIONS += "crownbay"
375 BBFILE_PATTERN_crownbay := "^${LAYERDIR}/"
376 BBFILE_PRIORITY_crownbay = "6"
377 </literallayout>
378 </para>
379
380 <para>
381 Simply substitute the machine string name <filename>crownbay</filename>
382 with the new machine name <filename>mymachine</filename> to get the following:
383 <literallayout class='monospaced'>
384 BBFILE_COLLECTIONS_mymachine += "mymachine"
385 BBFILE_PATTERN_mymachine := "^${LAYERDIR}/"
386 BBFILE_PRIORITY_mymachine = "6"
387 </literallayout>
388 </para>
389
390 <para>
391 Now we will take a look at the recipes in your new layer.
392 The standard BSP structure has areas for BSP, graphics, core, and kernel recipes.
393 When you create a BSP you use these areas for appropriate recipes and append files.
394 Recipes take the form of <filename>.bb</filename> files.
395 If you want to leverage the existing recipes the Yocto Project build system uses
396 but change those recipes you can use <filename>.bbappend</filename> files.
397 All new recipes and append files for your layer must go in the layer’s
398 <filename>recipes-bsp</filename>, <filename>recipes-kernel</filename>,
399 <filename>recipes-core</filename>, and
400 <filename>recipes-graphics</filename> directories.
401 </para>
402
403 <para>
404 First, let's look at <filename>recipes-bsp</filename>.
405 For this example we are not adding any new BSP recipes.
406 And, we only need to remove the formfactor we do not want and change the name of
407 the remaining one that doesn't support EMGD.
408 These commands take care of the <filename>recipes-bsp</filename> recipes:
409 <literallayout class='monospaced'>
410 $ rm &dash;rf meta-mymachine/recipes-graphics/xorg-xserver/*emgd*
411 $ mv meta-mymachine/recipes-bsp/formfactor/formfactor/crownbay-noemgd/ \
412 meta-mymachine/recipes-bsp/formfactor/formfactor/mymachine
413 </literallayout>
414 </para>
415
416 <para>
417 Now let's look at <filename>recipes-graphics</filename>.
418 For this example we want to remove anything that supports EMGD and
419 be sure to rename remaining directories appropriately.
420 The following commands clean up the <filename>recipes-graphics</filename> directory:
421 <literallayout class='monospaced'>
422 $ rm &dash;rf meta-mymachine/recipes-graphics/xorg-xserver/xserver-xf86-emgd*
423 $ rm &dash;rf meta-mymachine/recipes-graphics/xorg-xserver/xserver-xf86-config/crownbay
424 $ mv meta-mymachine/recipes-graphics/xorg-xserver/xserver-xf86-config/crownbay-noemgd \
425 meta-mymachine/recipes-graphics/xorg-xserver/xserver-xf86-config/mymachine
426 </literallayout>
427 </para>
428
429 <para>
430 At this point the <filename>recipes-graphics</filename> directory just has files that
431 support Video Electronics Standards Association (VESA) graphics modes and not EMGD.
432 </para>
433
434 <para>
435 Now let's look at changes in <filename>recipes-core</filename>.
436 The file <filename>task-core-tools.bbappend</filename> in
437 <filename>recipes-core/tasks</filename> appends the similarly named recipe
438 located in the local Yocto Project files at
439 <filename>meta/recipes-core/tasks</filename>.
440 The "append" file in our layer right now is Crown Bay-specific and supports
441 EMGD and non-EMGD.
442 Here are the contents of the file:
443 <literallayout class='monospaced'>
444 RRECOMMENDS_task-core-tools-profile_append_crownbay = " systemtap"
445 RRECOMMENDS_task-core-tools-profile_append_crownbay-noemgd = " systemtap"
446 </literallayout>
447 </para>
448
449 <para>
450 The <filename>RRECOMMENDS</filename> statements list packages that
451 extend usability.
452 The first <filename>RRECOMMENDS</filename> statement can be removed, while the
453 second one can be changed to reflect <filename>meta-mymachine</filename>:
454 <literallayout class='monospaced'>
455 RRECOMMENDS_task-core-tools-profile_append_mymachine = " systemtap"
456 </literallayout>
457 </para>
458
459 <para>
460 Finally, let's look at <filename>recipes-kernel</filename> changes.
461 Recall that the BSP uses the <filename>linux-yocto</filename> kernel as determined
462 earlier in the <filename>mymachine.conf</filename>.
463 The recipe for that kernel is not located in the
464 BSP layer but rather in the local Yocto Project files at
465 <filename>meta/recipes-kernel/linux</filename> and is
466 named <filename>linux-yocto-2.6.37.bb</filename>.
467 The <filename>SRCREV_machine</filename> and <filename>SRCREV_meta</filename>
468 statements point to the exact commits used by the Yocto Project development team
469 in their source repositories that identify the right kernel for our hardware.
470 </para>
471
472 <para>
473 However, in the <filename>meta-mymachine</filename> layer in
474 <filename>recipes-kernel/linux</filename> resides a <filename>.bbappend</filename>
475 file named <filename>linux-yocto-2.6.37.bbappend</filename> that
476 is appended to the recipe of the same name in <filename>meta/recipes-kernel/link</filename>.
477 Thus, the <filename>SRCREV</filename> statements in the "append" file override
478 the more general statements found in <filename>meta</filename>.
479 </para>
480
481 <para>
482 The <filename>SRCREV</filename> statements in the "append" file currently identify
483 the kernel that supports the Crown Bay BSP with and without EMGD support.
484 Here are the statements:
485 <literallayout class='monospaced'>
486 SRCREV_machine_pn-linux-yocto_crownbay ?= \
487 "372c0ab135978bd8ca3a77c88816a25c5ed8f303"
488 SRCREV_meta_pn-linux-yocto_crownbay ?= \
489 "d5d3c6480d61f83503ccef7fbcd765f7aca8b71b"
490
491 SRCREV_machine_pn-linux-yocto_crownbay-noemgd ?= \
492 "372c0ab135978bd8ca3a77c88816a25c5ed8f303"
493 SRCREV_meta_pn-linux-yocto_crownbay-noemgd ?= \
494 "d5d3c6480d61f83503ccef7fbcd765f7aca8b71b"
495 </literallayout>
496 </para>
497
498 <para>
499 You will notice that there are two pairs of <filename>SRCREV</filename> statements.
500 The top pair identifies the kernel that supports
501 EMGD, which we don’t care about in this example.
502 The bottom pair identifies the kernel that we will use:
503 <filename>linux-yocto</filename>.
504 At this point though, the unique commit strings all are still associated with
505 Crown Bay and not <filename>meta-mymachine</filename>.
506 </para>
507
508 <para>
509 To fix this situation in <filename>linux-yocto-2.6.37.bbappend</filename>
510 we delete the two <filename>SRCREV</filename> statements that support
511 EMGD (the top pair).
512 We also change the remaining pair to specify <filename>mymachine</filename>
513 and insert the commit identifiers to identify the kernel in which we
514 are interested, which will be based on the <filename>atom-pc-standard</filename>
515 kernel.
516 Here are the final <filename>SRCREV</filename> statements:
517 <literallayout class='monospaced'>
518 SRCREV_machine_pn-linux-yocto-_mymachine ?= \
519 "fce17f046d3756045e4dfb49221d1cf60fcae329"
520 SRCREV_meta_pn-linux-yocto-stable_mymachine ?= \
521 "84f1a422d7e21fbc23a687035bdf9d42471f19e0"
522 </literallayout>
523 </para>
524
525 <para>
526 If you are familiar with Git repositories you probably won’t have trouble locating the
527 exact commit strings in the Yocto Project source repositories you need to change
528 the <filename>SRCREV</filename> statements.
529 You can find all the <filename>machine</filename> and <filename>meta</filename>
530 branch points (commits) for the <filename>linux-yocto-2.6.37</filename> kernel
531 <ulink url='http://git.yoctoproject.org/cgit/cgit.cgi/linux-yocto-2.6.37'>here</ulink>.
532 </para>
533
534 <para>
535 If you need a little more assistance after going to the link then do the following:
536 <orderedlist>
537 <listitem><para>Expand the list of branches by clicking <filename>[…]</filename></para></listitem>
538 <listitem><para>Click on the <filename>yocto/standard/common-pc/atom-pc</filename>
539 branch</para></listitem>
540 <listitem><para>Click on the commit column header to view the top commit</para></listitem>
541 <listitem><para>Copy the commit string for use in the
542 <filename>linux-yocto-2.6.37.bbappend</filename> file</para></listitem>
543 </orderedlist>
544 </para>
545
546 <para>
547 For the <filename>SRCREV</filename> statement that points to the <filename>meta</filename>
548 branch use the same procedure except expand the <filename>meta</filename>
549 branch in step 2 above.
550 </para>
551
552 <para>
553 Also in the <filename>linux-yocto-2.6.37.bbappend</filename> file are
554 <filename>COMPATIBLE_MACHINE</filename>, <filename>KMACHINE</filename>,
555 and <filename>KERNEL_FEATURES</filename> statements.
556 Two sets of these exist: one set supports EMGD and one set does not.
557 Because we are not interested in supporting EMGD those three can be deleted.
558 The remaining three must be changed so that <filename>mymachine</filename> replaces
559 <filename>crownbay-noemgd</filename> and <filename>crownbay</filename>.
560 Here is the final <filename>linux-yocto-2.6.37.bbappend</filename> file after all
561 the edits:
562 <literallayout class='monospaced'>
563 FILESEXTRAPATHS_prepend := "${THISDIR}/${PN}:"
564
565 COMPATIBLE_MACHINE_mymachine = "mymachine"
566 KMACHINE_mymachine = "yocto/standard/mymachine"
567 KERNEL_FEATURES_append_mymachine += " cfg/smp.scc"
568
569 SRCREV_machine_pn-linux-yocto_mymachine ?= \
570 "fce17f046d3756045e4dfb49221d1cf60fcae329"
571 SRCREV_meta_pn-linux-yocto_mymachine ?= \
572 "84f1a422d7e21fbc23a687035bdf9d42471f19e0"
573 </literallayout>
574 </para>
575
576 <para>
577 In summary, the edits to the layer’s recipe files result in removal of any files and
578 statements that do not support your targeted hardware in addition to the inclusion
579 of any new recipes you might need.
580 In this example, it was simply a matter of ridding the new layer
581 <filename>meta-machine</filename> of any code that supported the EMGD features
582 and making sure we were identifying the kernel that supports our example, which
583 is the <filename>atom-pc-standard</filename> kernel.
584 We did not introduce any new recipes to the layer.
585 </para>
586
587 <para>
588 Finally, it is also important to update the layer’s <filename>README</filename>
589 file so that the information in it reflects your BSP.
590 </para>
591 </section>
592
593 <section id='preparing-for-the-build-app'>
594 <title>Preparing for the Build</title>
595
596 <para>
597 Once you have made all the changes to your BSP layer there remains a few things
598 you need to do for the Yocto Project build system in order for it to create your image.
599 You need to get the build environment ready by sourcing an environment setup script
600 and you need to be sure two key configuration files are configured appropriately.
601 </para>
602
603 <para>
604 The entire process for building an image is overviewed in the
605 <ulink url='http://www.yoctoproject.org/docs/1.1/yocto-project-qs/yocto-project-qs.html#building-image'>
606 Building an Image</ulink> section of the Yocto Project Quick Start.
607 You might want to reference this information.
608 The remainder of this section will apply to our example of the
609 <filename>meta-mymachine</filename> layer.
610 </para>
611
612 <para>
613 To get ready to build your image that uses the new layer you need to do the following:
614 <orderedlist>
615 <listitem><para>Get the environment ready for the build by sourcing the environment
616 script.
617 The environment script is in the top-level of the local Yocto Project files
618 directory structure.
619 The script has the string
620 <filename>init-build-env</filename> in the file’s name.
621 For this example, the following command gets the build environment ready:
622 <literallayout class='monospaced'>
623 $ source oe-init-build-env yocto-build
624 </literallayout>
625 When you source the script a build directory is created in the current
626 working directory.
627 In our example we were in the <filename>poky</filename> directory.
628 Thus, entering the previous command created the <filename>yocto-build</filename> directory.
629 If you do not provide a name for the build directory it defaults to
630 <filename>build</filename>.
631 The <filename>yocot-build</filename> directory contains a
632 <filename>conf</filename> directory that has
633 two configuration files you will need to check: <filename>bblayers.conf</filename>
634 and <filename>local.conf</filename>.</para></listitem>
635 <listitem><para>Check and edit the resulting <filename>local.conf</filename> file.
636 This file minimally identifies the machine for which to build the image by
637 configuring the <filename>MACHINE</filename> variable.
638 For this example you must set the variable to mymachine as follows:
639 <literallayout class='monospaced'>
640 MACHINE ??= “mymachine”
641 </literallayout>
642 You should also be sure any other variables in which you are interested are set.
643 Some variables to consider are <filename>BB_NUMBER_THREADS</filename>
644 and <filename>PARALLEL_MAKE</filename>, both of which can greatly reduce your build time
645 if you are using a multi-threaded development system (e.g. values of
646 <filename>8</filename> and <filename>j 6</filename>, respectively are optimal
647 for a development machine that has four available cores).</para></listitem>
648 <listitem><para>Update the <filename>bblayers.conf</filename> file so that it includes
649 the path to your new BSP layer.
650 In this example you need to include the pathname to <filename>meta-mymachine</filename>.
651 For this example the
652 <filename>BBLAYERS</filename> variable in the file would need to include the following path:
653 <literallayout class='monospaced'>
654 $HOME/poky/meta-intel/meta-mymachine
655 </literallayout></para></listitem>
656 </orderedlist>
657 </para>
658
659 <para>
660 The appendix
661 <ulink url='http://www.yoctoproject.org/docs/1.1/poky-ref-manual/poky-ref-manual.html#ref-variables-glos'>
662 Reference: Variables Glossary</ulink> in the Yocto Project Reference Manual has more information
663 on configuration variables.
664 </para>
665 </section>
666
667 <section id='building-the-image-app'>
668 <title>Building the Image</title>
669
670 <para>
671 The Yocto Project uses the BitBake tool to build images based on the type of image
672 you want to create.
673 You can find more information on BitBake
674 <ulink url='http://bitbake.berlios.de/manual/'>here</ulink>.
675 </para>
676
677 <para>
678 The build process supports several types of images to satisfy different needs.
679 When you issue the BitBake command you provide a “top-level” recipe that essentially
680 starts the process off of building the type of image you want.
681 </para>
682
683 <para>
684 [WRITER'S NOTE: Consider moving this to the Poky Reference Manual.]
685 </para>
686
687 <para>
688 You can find these recipes in the <filename>meta/recipes-core/images</filename> and
689 <filename>meta/recipes-sato/images</filename> directories of your local Yocto Project
690 file structure (Git repository or extracted release tarball).
691 Although the recipe names are somewhat explanatory, here is a list that describes them:
692 <itemizedlist>
693 <listitem><para><emphasis>Base</emphasis> – A foundational basic image without support
694 for X that can be reasonably used for customization.</para></listitem>
695 <listitem><para><emphasis>Core</emphasis> – A foundational basic image with support for
696 X that can be reasonably used for customization.</para></listitem>
697 <listitem><para><emphasis>Direct Disk</emphasis> – An image that you can copy directory to
698 the disk of the target device.</para></listitem>
699 <listitem><para><emphasis>Live</emphasis> – An image you can run from a USB device or from
700 a CD without having to first install something.</para></listitem>
701 <listitem><para><emphasis>Minimal</emphasis> – A small image without a GUI.
702 This image is not much more than a kernel with a shell.</para></listitem>
703 <listitem><para><emphasis>Minimal Development</emphasis> – A Minimal image suitable for
704 development work.</para></listitem>
705 <listitem><para><emphasis>Minimal Direct Disk</emphasis> – A Minimal Direct Disk image.</para></listitem>
706 <listitem><para><emphasis>Minimal RAM-based Initial Root Filesystem</emphasis> – A minimal image
707 that has the <filename>initramfs</filename> as part of the kernel, which allows the
708 system to find the first “init” program more efficiently.</para></listitem>
709 <listitem><para><emphasis>Minimal Live</emphasis> – A Minimal Live image.</para></listitem>
710 <listitem><para><emphasis>Minimal MTD Utilities</emphasis> – A minimal image that has support
711 for the MTD utilities, which let the user interact with the MTD subsystem in
712 the kernel to perform operations on flash devices.</para></listitem>
713 <listitem><para><emphasis>Sato</emphasis> – An image with Sato support, a mobile environment
714 and visual style that works well with mobile devices.</para></listitem>
715 <listitem><para><emphasis>Sato Development</emphasis> – A Sato image suitable for
716 development work.</para></listitem>
717 <listitem><para><emphasis>Sato Direct Disk</emphasis> – A Sato Direct Disk image.</para></listitem>
718 <listitem><para><emphasis>Sato Live</emphasis> – A Sato Live image.</para></listitem>
719 <listitem><para><emphasis>Sato SDK</emphasis> – A Sato image that includes the Yocto Project
720 toolchain and development libraries.</para></listitem>
721 <listitem><para><emphasis>Sato SDK Direct Disk</emphasis> – A Sato SDK Direct
722 Disk image.</para></listitem>
723 <listitem><para><emphasis>Sato SDK Live</emphasis> – A Sato SDK Live image.</para></listitem>
724 </itemizedlist>
725 </para>
726
727 <para>
728 The remainder of this section applies to our example of the <filename>meta-mymachine</filename> layer.
729 </para>
730
731 <para>
732 To build the image for our <filename>meta-mymachine</filename> BSP enter the following command
733 from the same shell from which you ran the setup script.
734 You should run the <filename>bitbake</filename> command without any intervening shell commands.
735 For example, moving your working directory around could cause problems.
736 Here is the command for this example:
737 <literallayout class='monospaced'>
738 $ bitbake –k core-image-sato-live
739 </literallayout>
740 </para>
741
742 <para>
743 This command specifies an image that has Sato support and that can be run from a USB device or
744 from a CD without having to first install anything.
745 The build process takes significant time and includes thousands of tasks, which are reported
746 at the console.
747 If the build results in any type of error you should check for misspellings in the
748 files you changed or problems with your host development environment such as missing packages.
749 </para>
750 </section>
751 </section>
752
753 <section id='modifying-a-kernel-kernel-example-app'>
754 <title>Modifying a Kernel</title>
755
756 <para>
757 Kernel modification involves changing or adding configurations to an existing kernel, or
758 adding recipes to the kernel that are needed to support specific hardware features.
759 The process is similar to creating a Board Support Package (BSP) except that it does not
760 involve a BSP layer.
761 </para>
762
763 <para>
764 This section presents a brief overview of the kernel structure and then provides a simple
765 example that shows how to modify the kernel.
766 </para>
767
768 <section id='yocto-project-kernel-app'>
769 <title>Yocto Project Kernel Overview</title>
770
771 <para>
772 When one thinks of the source files for a kernel they usually think of a fixed structure
773 of files that contain kernel patches.
774 The Yocto Project, however, employs mechanisims that in a sense result in a kernel source
775 generator.
776 </para>
777
778 <para>
779 The Yocto Project uses the source code management (SCM) tool Git to manage and track Yocto
780 Project files.
781 Git employs branching strategies that effectively produce a tree-like structure whose
782 branches represent diversions from more general code.
783 For example, suppose two kernels are basically identical with the exception of a couple
784 different features in each.
785 In the Yocto Project source repositories managed by Git a main branch can contain the
786 common or shared
787 parts of the kernel source and two branches that diverge from that common branch can
788 each contain the features specific to the respective kernel.
789 The result is a managed tree whose "leaves" represent the end of a specific path that yields
790 a set of kernel source files necessary for a specific piece of hardware and its features.
791 </para>
792
793 <para>
794 A big advantage to this scheme is the sharing of common features by keeping them in
795 "larger" branches that are further up the tree.
796 This practice eliminates redundant storage of similar features shared among kernels.
797 </para>
798
799 <para>
800 When you build the kernel on your development system all files needed for the build
801 are taken from the Yocto Project source repositories pointed to by the
802 <filename>SRC_URI</filename> variable and gathered in a temporary work area
803 where they are subsequently used to create the unique kernel.
804 Thus, in a sense, the process constructs a local source tree specific to your
805 kernel to generate the new kernel image - a source generator if you will.
806 </para>
807
808 <para>
809 For a complete discussion of the Yocto Project kernel's architcture and its branching strategy,
810 see the <ulink url='http://www.yoctoproject.org/docs/1.1/kernel-manual/kernel-manual.html'>
811 The Yocto Project Kernel Architecture and Use Manual</ulink>.
812 </para>
813
814 <para>
815 You can find a web interface to the Yocto Project source repository at
816 <ulink url='http://git.yoctoproject.org/'></ulink>.
817 Within the interface you will see groups of related source code, each of which can
818 be cloned using Git to result in a working Git repository on your local system
819 (referred to as the "local Yocto Project files" in this manual).
820 The Yocto Project supports four types of kernels in its source repositories at
821 <ulink url='http://git.yoctoproject.org/'></ulink>:
822 <itemizedlist>
823 <listitem><para><emphasis><filename>linux-yocto-2.6.34</filename></emphasis> - The
824 stable Linux Yocto kernel that is based on the Linux 2.6.34 release.</para></listitem>
825 <listitem><para><emphasis><filename>linux-yocto-2.6.37</filename></emphasis> - The current
826 Linux Yocto kernel that is based on the Linux 2.6.37 release.</para></listitem>
827 <listitem><para><emphasis><filename>linux-yocto-dev</filename></emphasis> - A development
828 kernel based on the Linux 2.6.39-rc1 release.</para></listitem>
829 <listitem><para><emphasis><filename>linux-2.6</filename></emphasis> - A kernel based on
830 minimal Linux mainline tracking.
831 [WRITER'S NOTE: I don't know which Git repository the user needs to clone to get this
832 repository on their development system.]</para></listitem>
833 </itemizedlist>
834 </para>
835 </section>
836
837 <section id='modifying-a-kernel-example-app'>
838 <title>Modifying a Kernel Example</title>
839
840 <para>
841 This section presents a simple example that illustrates kernel modification
842 based on the <filename>linux-yocto-2.6.37</filename> kernel.
843 The example uses the audio and mixer capabilities supported by the
844 <ulink url='http://www.alsa-project.org/main/index.php/Main_Page'>Advanced Linux
845 Sound Architecture (ALSA) Project</ulink>.
846 As the example progresses you will see how to do the following:
847 <itemizedlist>
848 <listitem><para>Iteratively modify a base kernel locally.</para></listitem>
849 <listitem><para>Provide a recipe-based solution for your modified kernel.
850 </para></listitem>
851 <listitem><para>Proved an "in-tree" solution for your modified kernel
852 (i.e. make the modifcations part of the Yocto Project).</para></listitem>
853 </itemizedlist>
854 </para>
855
856 <para>
857 The example flows as follows:
858 </para>
859
860 <para>
861 <itemizedlist>
862 <listitem><para>Be sure your host development system is set up to support
863 development using the Yocto Project.
864 See
865 <ulink url='http://www.yoctoproject.org/docs/1.1/yocto-project-qs/yocto-project-qs.html#the-linux-distro'>
866 The Linux Distributions</ulink> section and
867 <ulink url='http://www.yoctoproject.org/docs/1.1/yocto-project-qs/yocto-project-qs.html#packages'>
868 The Packages</ulink> section both
869 in the Yocto Project Quick Start for requirements.
870 You will also need a release of Yocto Project installed on the host.</para></listitem>
871 <listitem><para>Set up your environment for optimal local kernel development.
872 </para></listitem>
873 <listitem><para>Create a layer to isolate your kernel work.</para></listitem>
874 <listitem><para>Next item.</para></listitem>
875 <listitem><para>Next item.</para></listitem>
876 <listitem><para>Next item.</para></listitem>
877 <listitem><para>Next item.</para></listitem>
878 </itemizedlist>
879 </para>
880
881 <section id='setting-up-yocto-project-kernel-example-app'>
882 <title>Setting Up Yocto Project</title>
883
884 <para>
885 You need to have the Yocto Project files available on your host system.
886 The process is identical to that described in getting the files in section
887 <xref linkend='setting-up-yocto-project-app'>"Setting Up Yocto Project"</xref> for
888 the BSP development case.
889 Be sure to either set up a local Git repository for <filename>poky</filename>
890 or download and unpack the Yocto Project release tarball.
891 </para>
892 </section>
893
894 <section id='create-a-git-repository-of-poky-extras-app'>
895 <title>Create a Git Repository of <filename>poky-extras</filename></title>
896
897 <para>
898 Everytime you change a configuration or add a recipe to the kernel you need to
899 do a fetch from the Linux Yocto kernel source repositories.
900 This can get tedious and time consuming if you need to fetch the entire
901 Linux Yocto 2.6.37 Git repository down from the Internet everytime you make a change
902 to the kernel.
903 </para>
904
905 <para>
906 You can get around this by setting up a <filename>meta-kernel-dev</filename>
907 area on your local system.
908 This area contains "append" files for every kernel recipe, which also include
909 a <filename>KSRC</filename> statement that points to the kernel source files.
910 You can set up the environment so that the <filename>KSRC</filename> points to the
911 <filename>meta-kernel-dev</filename>, thus pulling source from a local area.
912 This setup can speed up development time.
913 </para>
914
915 <para>
916 To get set up you need to do two things: create a local Git repository
917 of the <filename>poky-extras</filename> repository, and create a bare clone of the
918 Linux Yocto 2.6.37 kernel Git repository.
919 </para>
920
921 <para>
922 The following transcript shows how to clone the <filename>poky-extras</filename>
923 Git repository into the current working directory, which is <filename>poky</filename>
924 in this example.
925 The command creates the repository in a directory named <filename>poky-extras</filename>:
926 <literallayout class='monospaced'>
927 $ git clone git://git.yoctoproject.org/poky-extras
928 Initialized empty Git repository in /home/scottrif/poky/poky-extras/.git/
929 remote: Counting objects: 532, done.
930 remote: Compressing objects: 100% (472/472), done.
931 remote: Total 532 (delta 138), reused 307 (delta 39)
932 Receiving objects: 100% (532/532), 534.28 KiB | 362 KiB/s, done.
933 Resolving deltas: 100% (138/138), done.
934 </literallayout>
935 </para>
936
937 <para>
938 This transcript shows how to clone a bare Git repository of the Linux Yocto
939 2.6.37 kernel:
940 <literallayout class='monospaced'>
941 $ git clone --bare git://git.yoctoproject.org/linux-yocto-2.6.37
942 Initialized empty Git repository in /home/scottrif/linux-yocto-2.6.37.git/
943 remote: Counting objects: 1886034, done.
944 remote: Compressing objects: 100% (314326/314326), done.
945 remote: Total 1886034 (delta 1570202), reused 1870335 (delta 1554798)
946 Receiving objects: 100% (1886034/1886034), 401.51 MiB | 714 KiB/s, done.
947 Resolving deltas: 100% (1570202/1570202), done.
948 </literallayout>
949 </para>
950
951 <para>
952 The bare clone of the Linux Yocto 2.6.37 kernel on your local system mirrors
953 the upstream repository of the kernel.
954 You can effectively point to this local clone now during development to avoid
955 having to fetch the entire Linux Yocto 2.6.37 kernel every time you make a
956 kernel change.
957 </para>
958 </section>
959
960 <section id='create-a-layer-for-your-kernel-work-app'>
961 <title>Create a Layer for Your Kernel Work</title>
962
963 <para>
964 It is always good to isolate your work using your own layer.
965 Doing so allows you to experiment and easily start over should things go wrong.
966 This example uses a layer named <filename>meta-amixer</filename>.
967 </para>
968
969 <para>
970 When you set up a layer for kernel work you should follow the general layout
971 guidelines as described for BSP layers.
972 This layout is described in the
973 <ulink url='http://www.yoctoproject.org/docs/1.1/bsp-guide/bsp-guide.html#bsp-filelayout'>
974 Example Filesystem Layout</ulink> section of the Board Support Package (BSP) Development
975 Guide.
976 In the standard layout you will notice a suggested structure for recipes and
977 configuration information.
978 [WRITER'S NOTE: The <filename>meta-elc</filename> example uses an
979 <filename>images</filename> directory.
980 Currently, <filename>images</filename> is not part of the standard BSP layout.
981 I need to find out from Darren if this directory is required for kernel work.]
982 </para>
983
984 <para>
985 [WRITER'S NOTE: I need a paragraph here describing how to set up the layer.
986 I am not sure if you should copy an existing BSP layer and modify from there.
987 Or, if you should just look at a BSP layer and then create your own files.
988 Email to Darren on this but no answer yet.]
989 </para>
990 </section>
991
992 <section id='making-changes-to-your-kernel-layer-app'>
993 <title>Making Changes to Your Kernel Layer</title>
994
995 <para>
996 In the standard layer structure you have several areas that you need to examine or
997 modify.
998 For this example the layer contains four areas:
999 <itemizedlist>
1000 <listitem><para><emphasis><filename>conf</filename></emphasis> - Contains the
1001 <filename>layer.conf</filename> that identifies the location of the recipe files.
1002 </para></listitem>
1003 <listitem><para><emphasis><filename>images</filename></emphasis> - Contains the
1004 image recipe file.
1005 This recipe includes the base image you will be using and specifies other
1006 packages the image might need.</para></listitem>
1007 <listitem><para><emphasis><filename>recipes-bsp</filename></emphasis> - Contains
1008 recipes specific to the hardware for which you are developing the kernel.
1009 </para></listitem>
1010 <listitem><para><emphasis><filename>recipes-kernel</filename></emphasis> - Contains the
1011 "append" files that add information to the main recipe kernel.
1012 </para></listitem>
1013 </itemizedlist>
1014 </para>
1015
1016 <para>
1017 Let's take a look at the <filename>layer.conf</filename> in the
1018 <filename>conf</filename> directory first.
1019 This configuration file enables the Yocto Project build system to locate and
1020 use the information in your new layer.
1021 </para>
1022
1023 <para>
1024 The variable <filename>BBPATH</filename> needs to include the path to your layer
1025 as follows:
1026 <literallayout class='monospaced'>
1027 BBPATH := "${BBPATH}:${LAYERDIR}"
1028 </literallayout>
1029 And, the variable <filename>BBFILES</filename> needs to be modified to include your
1030 recipe and append files:
1031 <literallayout class='monospaced'>
1032 BBFILES := "${BBFILES} ${LAYERDIR}/images/*.bb \
1033 ${LAYERDIR}/images/*.bbappend \
1034 ${LAYERDIR}/recipes-*/*/*.bb \
1035 ${LAYERDIR}/recipes-*/*/*.bbappend"
1036 </literallayout>
1037 Finally, you need to be sure to use your layer name in these variables at the
1038 end of the file:
1039 <literallayout class='monospaced'>
1040 BBFILE_COLLECTIONS += "elc"
1041 BBFILE_PATTERN_elc := "^${LAYERDIR}/"
1042 BBFILE_PRIORITY_elc = "9"
1043 </literallayout>
1044 </para>
1045
1046 <para>
1047 The <filename>images</filename> directory contains an append file that helps
1048 further define the image.
1049 In our example, the base image is <filename>core-image-minimal</filename>.
1050 The image does, however, need some additional modules that we are using
1051 for this example.
1052 These modules support the amixer functionality.
1053 Here is the append file:
1054 <literallayout class='monospaced'>
1055 require recipes-core/images/poky-image-minimal.bb
1056
1057 IMAGE_INSTALL += "dropbear alsa-utils-aplay alsa-utils-alsamixer"
1058 IMAGE_INSTALL_append_qemux86 += " kernel-module-snd-ens1370 \
1059 kernel-module-snd-rawmidi kernel-module-loop kernel-module-nls-cp437 \
1060 kernel-module-nls-iso8859-1 qemux86-audio alsa-utils-amixer"
1061
1062 LICENSE = "MIT"
1063 </literallayout>
1064 </para>
1065
1066 <para>
1067 While the focus of this example is not on the BSP, it is worth mentioning that the
1068 <filename>recipes-bsp</filename> directory has the recipes and append files for
1069 features that the hardware requires.
1070 In this example, there is a script and a recipe to support the
1071 <filename>amixer</filename> functionality in QEMU.
1072 It is beyond the scope of this manual to go too deeply into the script.
1073 Suffice it to say that the script tests for the presence of the mixer, sets up
1074 default mixer values, enables the mixer, unmutes master and then
1075 sets the volume to 100.
1076 </para>
1077
1078 <para>
1079 The recipe <filename>qemu86-audio.bb</filename> installs and runs the
1080 <filename>amixer</filename> when the system boots.
1081 Here is the recipe:
1082 <literallayout class='monospaced'>
1083 SUMMARY = "Provide a basic init script to enable audio"
1084 DESCRIPTION = "Set the volume and unmute the Front mixer setting during boot."
1085 SECTION = "base"
1086 LICENSE = "MIT"
1087 LIC_FILES_CHKSUM = "file://${POKYBASE}/LICENSE;md5=3f40d7994397109285ec7b81fdeb3b58"
1088
1089 PR = "r4"
1090
1091 inherit update-rc.d
1092
1093 RDEPENDS = "alsa-utils-amixer"
1094
1095 SRC_URI = "file://qemux86-audio"
1096
1097 INITSCRIPT_NAME = "qemux86-audio"
1098 INITSCRIPT_PARAMS = "defaults 90"
1099
1100 do_install() {
1101 install -d ${D}${sysconfdir} \
1102 ${D}${sysconfdir}/init.d
1103 install -m 0755 ${WORKDIR}/qemux86-audio ${D}${sysconfdir}/init.d
1104 cat ${WORKDIR}/${INITSCRIPT_NAME} | \
1105 sed -e 's,/etc,${sysconfdir},g' \
1106 -e 's,/usr/sbin,${sbindir},g' \
1107 -e 's,/var,${localstatedir},g' \
1108 -e 's,/usr/bin,${bindir},g' \
1109 -e 's,/usr,${prefix},g' > ${D}${sysconfdir}/init.d/${INITSCRIPT_NAME}
1110 chmod 755 ${D}${sysconfdir}/init.d/${INITSCRIPT_NAME}
1111 }
1112 </literallayout>
1113 </para>
1114
1115 <para>
1116 The last area to look at is <filename>recipes-kernel</filename>.
1117 This area holds configuration fragments and kernel append files.
1118 The append file must have the same name as the kernel recipe, which is
1119 <filename>linux-yocto-2.6.37</filename> in this example.
1120 The file can <filename>SRC_URI</filename> statements to point to configuration
1121 fragments you might have in the layer.
1122 The file can also contain <filename>KERNEL_FEATURES</filename> statements that specify
1123 included kernel configurations that ship with the Yocto Project.
1124 </para>
1125 </section>
1126 </section>
1127 </section>
1128</section>
1129
1130</appendix>
1131
1132
1133
1134
1135
1136<!--
1137
1138
1139 <para>
1140 [WRITER'S NOTE: This section is a second example that focuses on just modifying the kernel.
1141 I don't have any information on this yet.
1142 </para>
1143
1144 <para>
1145 Here are some points to consider though:
1146 <itemizedlist>
1147 <listitem><para>Reference Darren's presentation
1148 <ulink url='http://events.linuxfoundation.org/events/embedded-linux-conference/hart'>
1149 here</ulink></para></listitem>
1150 <listitem><para>Reference <xref linkend='dev-manual-start'>Getting Started with the Yocto Project</xref>
1151 section to get set up at minimum.</para></listitem>
1152 <listitem><para>Are there extra steps I need specific to kernel development to get started?</para></listitem>
1153 <listitem><para>What do I do to get set up?
1154 Is it a matter of just installing YP and having some pieces together?
1155 What are the pieces?</para></listitem>
1156 <listitem><para>Where do I get the base kernel to start with?</para></listitem>
1157 <listitem><para>Do I install the appropriate toolchain?</para></listitem>
1158 <listitem><para>What kernel git repository do I use?</para></listitem>
1159 <listitem><para>What is the conversion script?
1160 What does it do?</para></listitem>
1161 <listitem><para>What do I have to do to integrate the kernel layer?</para></listitem>
1162 <listitem><para>What do I use to integrate the kernel layer?
1163 HOB?
1164 Do I just Bitbake it?</para></listitem>
1165 <listitem><para>Using the System Image Creator.]</para></listitem>
1166 </itemizedlist>
1167 </para>
1168 </section>
1169 </section>
1170</section>
1171
1172<section id='user-application-development'>
1173 <title>User Application Development</title>
1174
1175 <para>
1176 [WRITER'S NOTE: This section is the second major development case - developing an application.
1177 Here are points to consider:
1178 <itemizedlist>
1179 <listitem><para>User-space Application Development scenario overview.</para></listitem>
1180 <listitem><para>Using the Yocto Eclipse Plug-in.</para></listitem>
1181 <listitem><para>Back-door support.</para></listitem>
1182 <listitem><para>I feel there is more to this area than we have captured during our two
1183 review meetings.]</para></listitem>
1184 </itemizedlist>
1185 </para>
1186</section>
1187</chapter>
1188-->
1189
1190<!--
1191vim: expandtab tw=80 ts=4
1192-->
generated by cgit v1.2.3-54-g00ecf (git 2.39.0) at 2026-01-23 22:34:36 +0000