summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
Diffstat
-rw-r--r--documentation/dev-manual/dev-manual-bsp-appendix.xml713
-rw-r--r--documentation/dev-manual/dev-manual.xml2
2 files changed, 0 insertions, 715 deletions
diff --git a/documentation/dev-manual/dev-manual-bsp-appendix.xml b/documentation/dev-manual/dev-manual-bsp-appendix.xml
deleted file mode 100644
index a4de731dfa..0000000000
--- a/documentation/dev-manual/dev-manual-bsp-appendix.xml
+++ /dev/null
@@ -1,713 +0,0 @@
1<!DOCTYPE appendix PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
2"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
3[<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] >
4
5<appendix id='dev-manual-bsp-appendix'>
6
7<title>BSP Development Example</title>
8
9<para>
10 This appendix provides a complete BSP development example.
11 The example assumes the following:
12 <itemizedlist>
13 <listitem><para>No previous preparation or use of the Yocto Project.</para></listitem>
14 <listitem><para>Use of the Fish River Island 2 Board Support Package (BSP) as a "base" BSP from
15 which to work.
16 The example begins with the Fish River Island 2 BSP as the starting point
17 but ends by building a new 'atom-pc' BSP, which was based on the Fish River Island 2 BSP.
18 </para></listitem>
19 <listitem><para>Shell commands assume <filename>bash</filename></para></listitem>
20 <listitem><para>Example was developed on an Intel-based Core i7 platform running
21 Ubuntu 10.04 LTS released in April of 2010.</para></listitem>
22 </itemizedlist>
23</para>
24
25<section id='getting-local-yocto-project-files-and-bsp-files'>
26 <title>Getting Local Source Files and BSP Files</title>
27
28 <para>
29 You need to have the <link linkend='source-directory'>Source Directory</link>
30 available on your host system.
31 You can set up this directory through tarball extraction or by cloning the
32 <filename>poky</filename> Git repository.
33 The following paragraphs describe both methods.
34 For additional information, see the bulleted item
35 "<link linkend='local-yp-release'>Yocto Project Release</link>".
36 </para>
37
38 <para>
39 As mentioned, one way to set up the Source Directory is to use Git to clone the
40 <filename>poky</filename> repository.
41 These commands create a local copy of the Git repository.
42 By default, the top-level directory of the repository is named <filename>poky</filename>:
43 <literallayout class='monospaced'>
44 $ git clone git://git.yoctoproject.org/poky
45 $ cd poky
46 </literallayout>
47 Alternatively, you can start with the downloaded Poky "&DISTRO_NAME;" tarball.
48 These commands unpack the tarball into a Source Directory structure.
49 By default, the top-level directory of the Source Directory is named
50 <filename>&YOCTO_POKY;</filename>:
51 <literallayout class='monospaced'>
52 $ tar xfj &YOCTO_POKY_TARBALL;
53 $ cd &YOCTO_POKY;
54 </literallayout>
55 <note><para>If you're using the tarball method, you can ignore all the following steps that
56 ask you to carry out Git operations.
57 You already have the results of those operations
58 in the form of the &DISTRO_NAME; release tarballs.
59 Consequently, there is nothing left to do other than extract those tarballs into the
60 proper locations.</para>
61
62 <para>Once you expand the released tarball, you have a snapshot of the Git repository
63 that represents a specific release.
64 Fundamentally, this is different than having a local copy of the Poky Git repository.
65 Given the tarball method, changes you make are building on top of a release.
66 With the Git repository method you have the ability to track development
67 and keep changes in revision control.
68 See the
69 "<link linkend='repositories-tags-and-branches'>Repositories, Tags, and Branches</link>" section
70 for more discussion around these differences.</para></note>
71 </para>
72
73 <para>
74 With the local <filename>poky</filename> Git repository set up,
75 you have all the development branches available to you from which you can work.
76 Next, you need to be sure that your local repository reflects the exact
77 release in which you are interested.
78 From inside the repository you can see the development branches that represent
79 areas of development that have diverged from the main (master) branch
80 at some point, such as a branch to track a maintenance release's development.
81 You can also see the tag names used to mark snapshots of stable releases or
82 points in the repository.
83 Use the following commands to list out the branches and the tags in the repository,
84 respectively.
85 <literallayout class='monospaced'>
86 $ git branch -a
87 $ git tag -l
88 </literallayout>
89 For this example, we are going to use the Yocto Project &DISTRO; Release, which is code
90 named "&DISTRO_NAME;".
91 To make sure we have a local area (branch in Git terms) on our machine that
92 reflects the &DISTRO; release, we can use the following commands:
93 <literallayout class='monospaced'>
94 $ cd ~/poky
95 $ git fetch --tags
96 $ git checkout -b &DISTRO_NAME;-&POKYVERSION; origin/&DISTRO_NAME;
97 Switched to a new branch '&DISTRO_NAME;-&POKYVERSION;'
98 </literallayout>
99 The <filename>git fetch --tags</filename> is somewhat redundant since you just set
100 up the repository and should have all the tags.
101 The <filename>fetch</filename> command makes sure all the tags are available in your
102 local repository.
103 The Git <filename>checkout</filename> command with the <filename>-b</filename> option
104 creates a local branch for you named <filename>&DISTRO_NAME;-&POKYVERSION;</filename>.
105 Your local branch begins in the same state as the Yocto Project &DISTRO; released tarball
106 marked with the <filename>&DISTRO_NAME;-&POKYVERSION;</filename> tag in the source repositories.
107 </para>
108</section>
109
110<section id='choosing-a-base-bsp-app'>
111 <title>Choosing a Base BSP</title>
112
113 <para>
114 For this example, the base BSP is the <trademark class='registered'>Intel</trademark>
115 <trademark class='trade'>Atom</trademark> Processor E660 with Intel Platform
116 Controller Hub EG20T Development Kit, which is otherwise referred to as "Fish River Island 2."
117 The BSP layer is <filename>meta-fri2</filename>.
118 The base BSP is simply the BSP
119 we will be using as a starting point, so don't worry if you don't actually have Fish River Island 2
120 hardware.
121 The remainder of the example transforms the base BSP into a BSP that should be
122 able to boot on generic atom-pc (netbook) hardware.
123 </para>
124
125 <para>
126 For information on how to choose a base BSP, see
127 "<link linkend='developing-a-board-support-package-bsp'>Developing a Board Support Package (BSP)</link>".
128 </para>
129</section>
130
131<section id='getting-your-base-bsp-app'>
132 <title>Getting Your Base BSP</title>
133
134 <para>
135 You need to have the base BSP layer on your development system.
136 Similar to the local <link linkend='source-directory'>Source Directory</link>,
137 you can get the BSP
138 layer in a couple of different ways:
139 download the BSP tarball and extract it, or set up a local Git repository that
140 has the BSP layers.
141 You should use the same method that you used to set up the Source Directory earlier.
142 See "<link linkend='getting-setup'>Getting Setup</link>" for information on how to get
143 the BSP files.
144 </para>
145
146 <para>
147 This example assumes the BSP layer will be located within a directory named
148 <filename>meta-intel</filename> contained within the <filename>poky</filename>
149 parent directory.
150 The following steps will automatically create the
151 <filename>meta-intel</filename> directory and the contained
152 <filename>meta-fri2</filename> starting point in both the Git and the tarball cases.
153 </para>
154
155 <para>
156 If you're using the Git method, you could do the following to create
157 the starting layout after you have made sure you are in the <filename>poky</filename>
158 directory created in the previous steps:
159 <literallayout class='monospaced'>
160 $ git clone git://git.yoctoproject.org/meta-intel.git
161 $ cd meta-intel
162 </literallayout>
163 Alternatively, you can start with the downloaded Fish River Island 2 tarball.
164 You can download the &DISTRO_NAME; version of the BSP tarball from the
165 <ulink url='&YOCTO_HOME_URL;/download'>Downloads</ulink> page of the
166 Yocto Project website.
167 Here is the specific link for the tarball needed for this example:
168 <ulink url='&YOCTO_MACHINES_DL_URL;/fri2-noemgd/fri2-noemgd-&DISTRO_NAME;-&POKYVERSION;.tar.bz2'></ulink>.
169 Again, be sure that you are already in the <filename>poky</filename> directory
170 as described previously before installing the tarball:
171 <literallayout class='monospaced'>
172 $ tar xfj fri2-noemgd-&DISTRO_NAME;-&POKYVERSION;.tar.bz2
173 $ cd meta-intel
174 </literallayout>
175 </para>
176
177 <para>
178 The <filename>meta-intel</filename> directory contains all the metadata
179 that supports BSP creation.
180 If you're using the Git method, the following
181 step will switch to the &DISTRO_NAME; metadata.
182 If you're using the tarball method, you already have the correct metadata and can
183 skip to the next step.
184 Because <filename>meta-intel</filename> is its own Git repository, you will want
185 to be sure you are in the appropriate branch for your work.
186 For this example we are going to use the <filename>&DISTRO_NAME;</filename>
187 branch.
188 <literallayout class='monospaced'>
189 $ git checkout -b &DISTRO_NAME;-&POKYVERSION; origin/&DISTRO_NAME;
190 Branch &DISTRO_NAME;-&POKYVERSION; set up to track remote branch &DISTRO_NAME; from origin.
191 Switched to a new branch '&DISTRO_NAME;-&POKYVERSION;'
192 </literallayout>
193 </para>
194</section>
195
196<section id='making-a-copy-of-the-base bsp-to-create-your-new-bsp-layer-app'>
197 <title>Making a Copy of the Base BSP to Create Your New BSP Layer</title>
198
199 <para>
200 Now that you have set up the Source Directory and included the base BSP files, you need to
201 create a new layer for your BSP.
202 To create your BSP layer, you simply copy the <filename>meta-fri2</filename>
203 layer to a new layer.
204 </para>
205
206 <para>
207 For this example, the new layer will be named <filename>meta-mymachine</filename>.
208 The name should follow the BSP layer naming convention, which is
209 <filename>meta-&lt;name&gt;</filename>.
210 The following assumes your working directory is <filename>meta-intel</filename>
211 inside your Source Directory.
212 To start your new layer, just copy the new layer alongside the existing
213 BSP layers in the <filename>meta-intel</filename> directory:
214 <literallayout class='monospaced'>
215 $ cp -a meta-fri2/ meta-mymachine
216 </literallayout>
217 </para>
218</section>
219
220<section id='making-changes-to-your-bsp-app'>
221 <title>Making Changes to Your BSP</title>
222
223 <para>
224 Right now you have two identical BSP layers with different names:
225 <filename>meta-fri2</filename> and <filename>meta-mymachine</filename>.
226 You need to change your configurations so that they work for your new BSP and
227 your particular hardware.
228 The following sections look at each of these areas of the BSP.
229 </para>
230
231 <section id='changing-the-bsp-configuration'>
232 <title>Changing the BSP Configuration</title>
233
234 <para>
235 We will look first at the configurations, which are all done in the layer’s
236 <filename>conf</filename> directory.
237 </para>
238
239 <para>
240 First, since in this example the new BSP will not support EMGD, we will get rid of the
241 <filename>fri2.conf</filename> file and then rename the
242 <filename>fri2-noemgd.conf</filename> file to <filename>mymachine.conf</filename>.
243 Much of what we do in the configuration directory is designed to help the OpenEmbedded
244 build system work with the new layer and to be able to find and use the right software.
245 The following two commands result in a single machine configuration file named
246 <filename>mymachine.conf</filename>.
247 <literallayout class='monospaced'>
248 $ rm meta-mymachine/conf/machine/fri2.conf
249 $ mv meta-mymachine/conf/machine/fri2-noemgd.conf \
250 meta-mymachine/conf/machine/mymachine.conf
251 </literallayout>
252 </para>
253
254 <para>
255 Next, we need to make changes to the <filename>mymachine.conf</filename> itself.
256 The only changes we want to make for this example are to the comment lines.
257 Changing comments, of course, is never strictly necessary, but it's always good form to make
258 them reflect reality as much as possible.
259
260 Here, simply substitute the Fish River Island 2 name with an appropriate name for the BSP
261 (<filename>mymachine</filename> in this case) and change the description to
262 something that describes your hardware.
263 </para>
264
265 <para>
266 Note that inside the <filename>mymachine.conf</filename> is the
267 <filename>PREFERRED_VERSION_linux-yocto</filename> statement.
268 This statement identifies the kernel that the BSP is going to use.
269 In this case, the BSP is using <filename>linux-yocto</filename>, which is the
270 current Yocto Project kernel based on the Linux 3.4 release.
271 </para>
272
273 <para>
274 The next configuration file in the new BSP layer we need to edit is
275 <filename>meta-mymachine/conf/layer.conf</filename>.
276 This file identifies build information needed for the new layer.
277 You can see the
278 "<ulink url='&YOCTO_DOCS_BSP_URL;#bsp-filelayout-layer'>Layer Configuration File</ulink>" section
279 in The Board Support Packages (BSP) Development Guide for more information on this configuration file.
280 Basically, we are changing the existing statements to work with our BSP.
281 </para>
282
283 <para>
284 The file contains these statements that reference the Fish River Island 2 BSP:
285 <literallayout class='monospaced'>
286 BBFILE_COLLECTIONS += "fri2"
287 BBFILE_PATTERN_fri2 := "^${LAYERDIR}/"
288 BBFILE_PRIORITY_fri2 = "6"
289
290 LAYERDEPENDS_fri2 = "intel"
291 </literallayout>
292 </para>
293
294 <para>
295 Simply substitute the machine string name <filename>fri2</filename>
296 with the new machine name <filename>mymachine</filename> to get the following:
297 <literallayout class='monospaced'>
298 BBFILE_COLLECTIONS += "mymachine"
299 BBFILE_PATTERN_mymachine := "^${LAYERDIR}/"
300 BBFILE_PRIORITY_mymachine = "6"
301
302 LAYERDEPENDS_mymachine = "intel"
303 </literallayout>
304 </para>
305 </section>
306
307 <section id='changing-the-recipes-in-your-bsp'>
308 <title>Changing the Recipes in Your BSP</title>
309
310 <para>
311 Now we will take a look at the recipes in your new layer.
312 The standard BSP structure has areas for BSP, graphics, core, and kernel recipes.
313 When you create a BSP, you use these areas for appropriate recipes and append files.
314 Recipes take the form of <filename>.bb</filename> files, while append files take
315 the form of <filename>.bbappend</filename> files.
316 If you want to leverage the existing recipes the OpenEmbedded build system uses
317 but change those recipes, you can use <filename>.bbappend</filename> files.
318 All new recipes and append files for your layer must go in the layer’s
319 <filename>recipes-bsp</filename>, <filename>recipes-kernel</filename>,
320 <filename>recipes-core</filename>, and
321 <filename>recipes-graphics</filename> directories.
322 </para>
323
324 <section id='changing-recipes-bsp'>
325 <title>Changing&nbsp;&nbsp;<filename>recipes-bsp</filename></title>
326
327 <para>
328 First, let's look at <filename>recipes-bsp</filename>.
329 For this example we are not adding any new BSP recipes.
330 And, we only need to remove the formfactor we do not want and change the name of
331 the remaining one that doesn't support EMGD.
332 These commands take care of the <filename>recipes-bsp</filename> recipes:
333 <literallayout class='monospaced'>
334 $ rm -rf meta-mymachine/recipes-bsp/formfactor/formfactor/fri2
335 $ mv meta-mymachine/recipes-bsp/formfactor/formfactor/fri2-noemgd/ \
336 meta-mymachine/recipes-bsp/formfactor/formfactor/mymachine
337 </literallayout>
338 </para>
339 </section>
340
341 <section id='changing-recipes-graphics'>
342 <title>Changing&nbsp;&nbsp;<filename>recipes-graphics</filename></title>
343
344 <para>
345 Now let's look at <filename>recipes-graphics</filename>.
346 For this example we want to remove anything that supports EMGD and
347 be sure to rename remaining directories appropriately.
348 The following commands clean up the <filename>recipes-graphics</filename> directory:
349 <literallayout class='monospaced'>
350 $ rm -rf meta-mymachine/recipes-graphics/xorg-xserver/xserver-xf86-config/fri2
351 $ mv meta-mymachine/recipes-graphics/xorg-xserver/xserver-xf86-config/fri2-noemgd \
352 meta-mymachine/recipes-graphics/xorg-xserver/xserver-xf86-config/mymachine
353 </literallayout>
354 </para>
355
356 <para>
357 At this point the <filename>recipes-graphics</filename> directory just has files that
358 support Video Electronics Standards Association (VESA) graphics modes and not EMGD.
359 </para>
360 </section>
361
362 <section id='changing-recipes-kernel'>
363 <title>Changing&nbsp;&nbsp;<filename>recipes-kernel</filename></title>
364
365 <para>
366 Finally, let's look at <filename>recipes-kernel</filename> changes.
367 Recall that the BSP uses the <filename>linux-yocto</filename> kernel as determined
368 earlier in the <filename>mymachine.conf</filename>.
369 The recipe for that kernel is not located in the
370 BSP layer but rather in the Source Directory at
371 <filename>meta/recipes-kernel/linux</filename> and is
372 named <filename>linux-yocto_3.4.bb</filename>.
373 The <filename>SRCREV_machine</filename> and <filename>SRCREV_meta</filename>
374 statements point to the exact commits used by the Yocto Project development team
375 in their source repositories that identify the right kernel for our hardware.
376 In other words, the <filename>SRCREV</filename> values are simply Git commit
377 IDs that identify which commit on each
378 of the kernel branches (machine and meta) will be checked out and used to build
379 the kernel.
380 </para>
381
382 <para>
383 However, in the <filename>meta-mymachine</filename> layer in
384 <filename>recipes-kernel/linux</filename> resides a <filename>.bbappend</filename>
385 file named <filename>linux-yocto_3.4.bbappend</filename> that
386 appends the information to the recipe of the same name
387 that is found in <filename>meta/recipes-kernel/linux</filename>.
388 Thus, the <filename>SRCREV</filename> statements in our
389 <filename>mymachine</filename> append file override
390 the more general statements found in the more general recipe.
391 </para>
392
393 <para>
394 The <filename>SRCREV</filename> statements in the
395 <filename>mymachine</filename> append file currently identify
396 the kernel that supports the Fish River Island 2 BSP with and without EMGD support.
397 Here are the statements:
398 <note>The commit ID strings used in this manual might not match the actual commit
399 ID strings found in the <filename>linux-yocto_3.4.bbappend</filename> file.
400 For the example, this difference does not matter.</note>
401 <literallayout class='monospaced'>
402 SRCREV_machine_pn-linux-yocto_fri2 ?= \
403 "59c3ff750831338d05ab67d5efd7fc101c451aff"
404 #SRCREV_meta_pn-linux-yocto_fri2 ?= \
405 "c5bddf8ea379406ffec550528e17b777a0eba24b"
406
407 SRCREV_machine_pn-linux-yocto_fri2-noemgd ?= \
408 "59c3ff750831338d05ab67d5efd7fc101c451aff"
409 #SRCREV_meta_pn-linux-yocto_fir2-noemgd ?= \
410 "c5bddf8ea379406ffec550528e17b777a0eba24b"
411 </literallayout>
412 <note>The <filename>SRCREV_meta_pn-linux-yocto_fir2-noemgd</filename>
413 statements in the <filename>mymachine</filename> append file,
414 which originated from the Fish River Island 2 BSP, are
415 commented out.
416 The reason they are not used is because the commit IDs are identical to
417 those in the general <filename>linux-yocto_3.4.bbappend</filename> recipe,
418 which is found in <filename>meta/recipes-kernel/linux</filename>.
419 </note>
420 </para>
421
422 <para>
423 You will notice that there are two pairs of <filename>SRCREV</filename> statements.
424 The top pair identifies the kernel that supports
425 EMGD, which we don’t care about in this example.
426 The bottom pair identifies the kernel that we will use:
427 <filename>linux-yocto</filename>.
428 At this point though, the unique commit strings all are still associated with
429 Fish River Island 2 and not <filename>meta-mymachine</filename>.
430 </para>
431
432 <para>
433 To fix this situation in <filename>linux-yocto_3.4.bbappend</filename>
434 for <filename>mymachine</filename>,
435 we delete the two <filename>SRCREV</filename> statements that support
436 EMGD (the top pair).
437 We also change the remaining pair to specify <filename>mymachine</filename>
438 and insert the commit identifiers to identify the kernel in which we
439 are interested, which will be based on the <filename>atom-pc-standard</filename>
440 kernel.
441 In this case, because we're working with the &DISTRO_NAME; branch of everything, we
442 need to use the <filename>SRCREV</filename> values for the atom-pc branch
443 that are associated with the &DISTRO_NAME; release.
444 </para>
445
446 <para>
447 To find the machine value, we need to find the <filename>SRCREV</filename>
448 value that &DISTRO_NAME; uses for the atom-pc branch, which we find in the
449 <filename>poky/meta-yocto-bsp/recipes-kernel/linux/linux-yocto_3.4.bbappend</filename>
450 file.
451 The machine <filename>SRCREV</filename> we want is in the
452 <filename>SRCREV_machine_atom-pc</filename> variable.
453 </para>
454
455 <para>
456 The meta <filename>SRCREV</filename> isn't specified in this file, so if you
457 needed it, you would find it in the base kernel recipe in the
458 <filename>poky/meta/recipes-kernel/linux/linux-yocto_3.4.bb</filename>.
459 Recall that for this example the commit ID's for the <filename>SRCREV</filename>
460 meta statements are identical and do not have to be used in the
461 <filename>mymachine</filename> append file.
462 </para>
463
464 <para>
465 Here are the final <filename>SRCREV</filename> statements for the
466 <filename>mymachine</filename> append file:
467 <literallayout class='monospaced'>
468 SRCREV_machine_pn-linux-yocto_mymachine ?= \
469 "0985844fa6235422c67ef269952fa4e765f252f9"
470 #SRCREV_meta_pn-linux-yocto_mymachine ?= \
471 "c5bddf8ea379406ffec550528e17b777a0eba24b"
472 </literallayout>
473 </para>
474
475 <para>
476 In this example, we're using the <filename>SRCREV</filename> values we
477 found already captured in the &DISTRO_NAME; release because we're creating a BSP based on
478 &DISTRO_NAME;.
479 If, instead, we had based our BSP on the master branches, we would want to use
480 the most recent <filename>SRCREV</filename> values taken directly from the kernel's
481 repository.
482 We will not be doing that for this example.
483 However, if you do base a future BSP on master and
484 if you are familiar with Git repositories, you probably won’t have trouble locating the
485 exact commit strings in the Yocto Project source repositories you need to change
486 the <filename>SRCREV</filename> statements.
487 You can find all the <filename>machine</filename> and <filename>meta</filename>
488 branch points (commits) for the <filename>linux-yocto-3.4</filename> kernel at
489 <ulink url='&YOCTO_GIT_URL;/cgit/cgit.cgi/linux-yocto-3.4'></ulink>.
490 </para>
491
492 <para>
493 If you need a little more assistance after going to the link then do the following:
494 <orderedlist>
495 <listitem><para>Expand the list of branches by clicking <filename>[…]</filename></para></listitem>
496 <listitem><para>Click on the <filename>standard/default/common-pc/atom-pc</filename>
497 branch</para></listitem>
498 <listitem><para>Click on the commit column header to view the top commit</para></listitem>
499 <listitem><para>Copy the commit string for use in the
500 <filename>linux-yocto_3.4.bbappend</filename> file</para></listitem>
501 </orderedlist>
502 </para>
503
504 <para>
505 For the <filename>SRCREV</filename> statement that points to the <filename>meta</filename>
506 branch use the same procedure except expand the <filename>meta</filename>
507 branch in step 2 above.
508 </para>
509
510 <para>
511 Also in the <filename>linux-yocto_3.4.bbappend</filename> file are
512 <ulink url='&YOCTO_DOCS_REF_URL;#var-COMPATIBLE_MACHINE'><filename>COMPATIBLE_MACHINE</filename></ulink>,
513 <ulink url='&YOCTO_DOCS_REF_URL;#var-KMACHINE'><filename>KMACHINE</filename></ulink>,
514 and
515 <ulink url='&YOCTO_DOCS_REF_URL;#var-KBRANCH'><filename>KBRANCH</filename></ulink> statements.
516 Two sets of these exist: one set supports EMGD and one set does not.
517 Because we are not interested in supporting EMGD those three can be deleted.
518 The remaining three must be changed so that <filename>mymachine</filename> replaces
519 <filename>fri2-noemgd</filename> and <filename>fri2</filename>.
520 </para>
521
522 <para>
523 Because we are using the <filename>atom-pc</filename> branch for this new BSP, we can also find
524 the exact branch we need for the <filename>KMACHINE</filename>
525 and <filename>KBRANCH</filename> variables in our new BSP from the value
526 we find in the
527 <filename>poky/meta-yocto-bsp/recipes-kernel/linux/linux-yocto_3.4.bbappend</filename>
528 file we looked at in a previous step.
529 In this case, the values we want are in the <filename>KMACHINE_atom-pc</filename> variable
530 and the <filename>KBRANCH_atom-pc</filename> variables in that file.
531 Here is the final <filename>linux-yocto_3.4.bbappend</filename> file after all
532 the edits:
533 <literallayout class='monospaced'>
534 FILESEXTRAPATHS_prepend := "${THISDIR}/${PN}:"
535
536 COMPATIBLE_MACHINE_mymachine = "mymachine"
537 KMACHINE_mymachine = "atom-pc"
538 KBRANCH_mymachine = "standard/default/common-pc/atom-pc"
539
540 SRCREV_machine_pn-linux-yocto_mymachine ?= \
541 "f29531a41df15d74be5ad47d958e4117ca9e489e"
542 SRCREV_meta_pn-linux-yocto_mymachine ?= \
543 "b14a08f5c7b469a5077c10942f4e1aec171faa9d"
544 </literallayout>
545 </para>
546 </section>
547 </section>
548
549 <section id='bsp-recipe-change-summary'>
550 <title>BSP Recipe Change Summary</title>
551
552 <para>
553 In summary, the edits to the layer’s recipe files result in removal of any files and
554 statements that do not support your targeted hardware in addition to the inclusion
555 of any new recipes you might need.
556 In this example, it was simply a matter of ridding the new layer
557 <filename>meta-mymachine</filename> of any code that supported the EMGD features
558 and making sure we were identifying the kernel that supports our example, which
559 is the <filename>atom-pc-standard</filename> kernel.
560 We did not introduce any new recipes to the layer.
561 </para>
562
563 <para>
564 Finally, it is also important to update the layer’s <filename>README</filename>
565 file so that the information in it reflects your BSP.
566 </para>
567 </section>
568</section>
569
570<section id='preparing-for-the-build-app'>
571 <title>Preparing for the Build</title>
572
573 <para>
574 To get ready to build your image that uses the new layer you need to do the following:
575 <orderedlist>
576 <listitem><para>Get the environment ready for the build by sourcing the environment
577 script.
578 The environment script is in the top-level of the Source Directory.
579 The script has the string
580 <filename>init-build-env</filename> in the file’s name.
581 For this example, the following command gets the build environment ready:
582 <literallayout class='monospaced'>
583 $ source oe-init-build-env yocto-build
584 </literallayout>
585 When you source the script, a build directory is created in the current
586 working directory.
587 In our example we were in the <filename>poky</filename> directory.
588 Thus, entering the previous command created the <filename>yocto-build</filename> directory.
589 If you do not provide a name for the build directory it defaults to
590 <filename>build</filename>.
591 The <filename>yocto-build</filename> directory contains a
592 <filename>conf</filename> directory that has
593 two configuration files you will need to check: <filename>bblayers.conf</filename>
594 and <filename>local.conf</filename>.</para></listitem>
595 <listitem><para>Check and edit the resulting <filename>local.conf</filename> file.
596 This file minimally identifies the machine for which to build the image by
597 configuring the <filename>MACHINE</filename> variable.
598 For this example you must set the variable to mymachine as follows:
599 <literallayout class='monospaced'>
600 MACHINE ??= “mymachine”
601 </literallayout>
602 You should also be sure any other variables in which you are interested are set.
603 Some variables to consider are <filename>BB_NUMBER_THREADS</filename>
604 and <filename>PARALLEL_MAKE</filename>, both of which can greatly reduce your build time
605 if your development system supports multiple cores.
606 For development systems that support multiple cores, a good rule of thumb is to set
607 both the <filename>BB_NUMBER_THREADS</filename> and <filename>PARALLEL_MAKE</filename>
608 variables to twice the number of cores your system supports.</para></listitem>
609 <listitem><para>Update the <filename>bblayers.conf</filename> file so that it includes
610 both the path to your new BSP layer and the path to the
611 <filename>meta-intel</filename> layer.
612 In this example, you need to include both these paths as part of the
613 <filename>BBLAYERS</filename> variable:
614 <literallayout class='monospaced'>
615 $HOME/poky/meta-intel
616 $HOME/poky/meta-intel/meta-mymachine
617 </literallayout></para></listitem>
618 </orderedlist>
619 </para>
620
621 <para>
622 The
623 <ulink url='&YOCTO_DOCS_REF_URL;#ref-variables-glos'>Variables Glossary</ulink> chapter in the
624 Yocto Project Reference Manual has more information on configuration variables.
625 </para>
626</section>
627
628<section id='building-the-image-app'>
629 <title>Building and Booting the Image</title>
630
631 <para>
632 To build the image for our <filename>meta-mymachine</filename> BSP enter the following command
633 from the same shell from which you ran the setup script.
634 You should run the <filename>bitbake</filename> command without any intervening shell commands.
635 For example, moving your working directory around could cause problems.
636 Here is the command for this example:
637 <literallayout class='monospaced'>
638 $ bitbake -k core-image-sato
639 </literallayout>
640 </para>
641
642 <para>
643 This command specifies an image that has Sato support and that can be run from a USB device or
644 from a CD without having to first install anything.
645 The build process takes significant time and includes thousands of tasks, which are reported
646 at the console.
647 If the build results in any type of error you should check for misspellings in the
648 files you changed or problems with your host development environment such as missing packages.
649 </para>
650
651 <para>
652 Finally, once you have an image, you can try booting it from a device
653 (e.g. a USB device).
654 To prepare a bootable USB device, insert a USB flash drive into your build system and
655 copy the <filename>.hddimg</filename> file, located in the
656 <filename>poky/build/tmp/deploy/images</filename>
657 directory after a successful build to the flash drive.
658 Assuming the USB flash drive takes device <filename>/dev/sdf</filename>,
659 use <filename>dd</filename> to copy the live image to it.
660 For example:
661 <literallayout class='monospaced'>
662 # dd if=core-image-sato-mymachine-20111101223904.hddimg of=/dev/sdf
663 # sync
664 # eject /dev/sdf
665 </literallayout>
666 You should now have a bootable USB flash device.
667 </para>
668
669 <para>
670 Insert the device
671 into a bootable USB socket on the target, and power it on.
672 The system should boot to the Sato graphical desktop.
673 <footnote><para>Because
674 this new image is not in any way tailored to the system you're
675 booting it on, which is assumed to be some sort of atom-pc (netbook) system for this
676 example, it might not be completely functional though it should at least boot to a text
677 prompt.
678 Specifically, it might fail to boot into graphics without some tweaking.
679 If this ends up being the case, a possible next step would be to replace the
680 <filename>mymachine.conf</filename>
681 contents with the contents of <filename>atom-pc.conf</filename> and replace
682 <filename>xorg.conf</filename> with <filename>atom-pc xorg.conf</filename>
683 in <filename>meta-yocto</filename> and see if it fares any better.
684 In any case, following the previous steps will give you a buildable image that
685 will probably boot on most systems.
686 Getting things working like you want
687 them to for your hardware will normally require some amount of experimentation with
688 configuration settings.</para></footnote>
689 </para>
690
691 <para>
692 For reference, the sato image produced by the previous steps for &DISTRO_NAME;
693 should look like the following in terms of size.
694 If your sato image is much different from this,
695 you probably made a mistake in one of the above steps:
696 <literallayout class='monospaced'>
697 260538368 2012-04-27 01:44 core-image-sato-mymachine-20120427025051.hddimg
698 </literallayout>
699 <note>The previous instructions are also present in the README that was copied
700 from meta-fri2, which should also be updated to reflect the specifics of your
701 new BSP.
702 That file and the <filename>README.hardware</filename> file in the top-level
703 <filename>poky</filename> directory
704 also provides some suggestions for things to try if booting fails and produces
705 strange error messages.</note>
706 </para>
707</section>
708</appendix>
709
710
711<!--
712vim: expandtab tw=80 ts=4
713-->
diff --git a/documentation/dev-manual/dev-manual.xml b/documentation/dev-manual/dev-manual.xml
index 0cbd85fc3b..a5856e0995 100644
--- a/documentation/dev-manual/dev-manual.xml
+++ b/documentation/dev-manual/dev-manual.xml
@@ -80,8 +80,6 @@
80 80
81 <xi:include href="dev-manual-model.xml"/> 81 <xi:include href="dev-manual-model.xml"/>
82 82
83 <xi:include href="dev-manual-bsp-appendix.xml"/>
84
85 <xi:include href="dev-manual-kernel-appendix.xml"/> 83 <xi:include href="dev-manual-kernel-appendix.xml"/>
86 84
87</book> 85</book>
generated by cgit v1.2.3-54-g00ecf (git 2.39.0) at 2025-11-27 16:30:20 +0000