summaryrefslogtreecommitdiffstats
path: root/documentation/yocto-project-qs
diff options
context:
space:
mode:
authorScott Rifenbark <scott.m.rifenbark@intel.com>2011-09-16 09:20:09 -0700
committerRichard Purdie <richard.purdie@linuxfoundation.org>2011-09-25 17:59:58 +0100
commit4a0f7440a05848f4b2414fdbb0031cc69cdb2a9d (patch)
treebe20e796ffab93c2e5103eb4fc92f64333073749 /documentation/yocto-project-qs
parenta3e0cb64ba6a47afbc4b0c4115b75fa34883c0c8 (diff)
downloadpoky-4a0f7440a05848f4b2414fdbb0031cc69cdb2a9d.tar.gz
documentation/yocto-project-qs/yocto-project-qs.xml: General edits
This was a final scrub of the manual. I updated all examples and links to be current for what I think will be the 1.1 release. I also added some cross-referencing into the YP dev manual that now exist. (From yocto-docs rev: 4c10b0e04856817a1d03aee7a9ed6e4d5d73a3ac) Signed-off-by: Scott Rifenbark <scott.m.rifenbark@intel.com> Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
Diffstat (limited to 'documentation/yocto-project-qs')
-rw-r--r--documentation/yocto-project-qs/yocto-project-qs.xml387
1 files changed, 215 insertions, 172 deletions
diff --git a/documentation/yocto-project-qs/yocto-project-qs.xml b/documentation/yocto-project-qs/yocto-project-qs.xml
index c95e1a02ab..fbc8f2251a 100644
--- a/documentation/yocto-project-qs/yocto-project-qs.xml
+++ b/documentation/yocto-project-qs/yocto-project-qs.xml
@@ -21,7 +21,7 @@
21 <para> 21 <para>
22 This short document will give you some basic information about the environment as well 22 This short document will give you some basic information about the environment as well
23 as let you experience it in its simplest form. 23 as let you experience it in its simplest form.
24 After reading this document you will have a basic understanding of what the Yocto Project is 24 After reading this document, you will have a basic understanding of what the Yocto Project is
25 and how to use some of its core components. 25 and how to use some of its core components.
26 This document steps you through a simple example showing you how to build a small image 26 This document steps you through a simple example showing you how to build a small image
27 and run it using the QEMU emulator. 27 and run it using the QEMU emulator.
@@ -29,7 +29,8 @@
29 <para> 29 <para>
30 For complete information on the Yocto Project, you should check out the 30 For complete information on the Yocto Project, you should check out the
31 <ulink url='http://www.yoctoproject.org'>Yocto Project Website</ulink>. 31 <ulink url='http://www.yoctoproject.org'>Yocto Project Website</ulink>.
32 You can find the latest builds, breaking news, full development documentation, and a 32 Through the website, you can find the latest builds, breaking news, full development
33 documentation, and a
33 rich Yocto Project Development Community into which you can tap. 34 rich Yocto Project Development Community into which you can tap.
34 </para> 35 </para>
35 <para> 36 <para>
@@ -74,7 +75,7 @@
74 </mediaobject> 75 </mediaobject>
75 76
76 <para> 77 <para>
77 Yocto Project: 78 Here are some highlights for the Yocto Project:
78 </para> 79 </para>
79 80
80 <itemizedlist> 81 <itemizedlist>
@@ -85,7 +86,7 @@
85 <para>Makes available system components such as X11, Matchbox, GTK+, Pimlico, Clutter, 86 <para>Makes available system components such as X11, Matchbox, GTK+, Pimlico, Clutter,
86 GuPNP and Qt (among others) so you can create a richer user interface experience on 87 GuPNP and Qt (among others) so you can create a richer user interface experience on
87 devices that use displays or have a GUI. 88 devices that use displays or have a GUI.
88 For devices that don't have a GUI or display you simply would not employ these 89 For devices that don't have a GUI or display, you simply would not employ these
89 components.</para> 90 components.</para>
90 </listitem> 91 </listitem>
91 <listitem> 92 <listitem>
@@ -100,9 +101,9 @@
100 101
101 <para> 102 <para>
102 The Yocto Project can generate images for many kinds of devices. 103 The Yocto Project can generate images for many kinds of devices.
103 However, the standard example machines target QEMU full system emulation for x86, ARM, MIPS, 104 However, the standard example machines target QEMU full-system emulation for x86, x86-64, ARM, MIPS,
104 and PPC-based architectures as well as specific hardware such as the Intel Desktop Board 105 and PPC-based architectures as well as specific hardware such as the
105 DH55TC. 106 <trademark class='registered'>Intel</trademark> Desktop Board DH55TC.
106 Because an image developed with the Yocto Project can boot inside a QEMU emulator, the 107 Because an image developed with the Yocto Project can boot inside a QEMU emulator, the
107 development environment works nicely as a test platform for developing embedded software. 108 development environment works nicely as a test platform for developing embedded software.
108 </para> 109 </para>
@@ -113,7 +114,7 @@
113 restricted screen sizes, sits neatly on top of a device using the 114 restricted screen sizes, sits neatly on top of a device using the
114 GNOME Mobile Stack and provides a well-defined user experience. 115 GNOME Mobile Stack and provides a well-defined user experience.
115 Implemented in its own layer, it makes it clear to developers how they can implement 116 Implemented in its own layer, it makes it clear to developers how they can implement
116 their own UIs on top of Yocto Linux. 117 their own user interface on top of Yocto Linux.
117 </para> 118 </para>
118</section> 119</section>
119 120
@@ -186,7 +187,7 @@
186 </para> 187 </para>
187 188
188 <note><para> 189 <note><para>
189 If you are using a Fedora version prior to version 15 you will need to take some 190 If you are using a Fedora version prior to version 15, you will need to take some
190 extra steps to enable <filename>sudo</filename>. 191 extra steps to enable <filename>sudo</filename>.
191 See <ulink url='https://fedoraproject.org/wiki/Configuring_Sudo'></ulink> for details. 192 See <ulink url='https://fedoraproject.org/wiki/Configuring_Sudo'></ulink> for details.
192 </para></note> 193 </para></note>
@@ -232,7 +233,7 @@
232 <title>Yocto Project Release</title> 233 <title>Yocto Project Release</title>
233 234
234 <para> 235 <para>
235 You can download the latest release images for the Yocto Project on the 236 You can download the latest Yocto Project release by going to the
236 <ulink url="http://yoctoproject.org/download">Yocto Project Download page</ulink>. 237 <ulink url="http://yoctoproject.org/download">Yocto Project Download page</ulink>.
237 Just go to the page and click the "Yocto Downloads" link found in the "Download" 238 Just go to the page and click the "Yocto Downloads" link found in the "Download"
238 navigation pane to the right to view all available Yocto Project releases. 239 navigation pane to the right to view all available Yocto Project releases.
@@ -242,6 +243,17 @@
242 <ulink url="http://autobuilder.yoctoproject.org/nightly/"></ulink>. 243 <ulink url="http://autobuilder.yoctoproject.org/nightly/"></ulink>.
243 However, for this document a released version of Yocto Project is used. 244 However, for this document a released version of Yocto Project is used.
244 </para> 245 </para>
246
247 <para>
248 You can also get the Yocto Project files by setting up a Git repository on your host
249 development system.
250 Doing so allows you to contribute back to the project.
251 For information on how to get set up using this method, see the
252 "<ulink url='http://www.yoctoproject.org/docs/1.1/dev-manual/dev-manual.html#local-yp-release'>Yocto
253 Project Release</ulink>" item in
254 <ulink url='http://www.yoctoproject.org/docs/1.1/dev-manual/dev-manual.html'>The Yocto Project
255 Development Manual</ulink>.
256 </para>
245 </section> 257 </section>
246</section> 258</section>
247 259
@@ -249,16 +261,16 @@
249 <title>A Quick Test Run</title> 261 <title>A Quick Test Run</title>
250 262
251 <para> 263 <para>
252 Now that you have your system requirements in order you can give Yocto Project a try. 264 Now that you have your system requirements in order, you can give Yocto Project a try.
253 This section presents some steps that let you do the following: 265 This section presents some steps that let you do the following:
254 </para> 266 </para>
255 267
256 <itemizedlist> 268 <itemizedlist>
257 <listitem> 269 <listitem>
258 <para>Build an image and run it in the emulator</para> 270 <para>Build an image and run it in the QEMU emulator</para>
259 </listitem> 271 </listitem>
260 <listitem> 272 <listitem>
261 <para>Or, use a pre-built image and run it in the emulator</para> 273 <para>Or, use a pre-built image and run it in the QEMU emulator</para>
262 </listitem> 274 </listitem>
263 </itemizedlist> 275 </itemizedlist>
264 276
@@ -266,7 +278,8 @@
266 <title>Building an Image</title> 278 <title>Building an Image</title>
267 279
268 <para> 280 <para>
269 In the development environment you will need to build an image whenever you change hardware support, add or change system libraries, or add or change services that have dependencies. 281 In the development environment you will need to build an image whenever you change hardware
282 support, add or change system libraries, or add or change services that have dependencies.
270 </para> 283 </para>
271 284
272 <mediaobject> 285 <mediaobject>
@@ -302,15 +315,17 @@
302 315
303 <para> 316 <para>
304 <literallayout class='monospaced'> 317 <literallayout class='monospaced'>
305 $ wget http://www.yoctoproject.org/downloads/poky/poky-bernard-5.0.1.tar.bz2 318 $ wget http://www.yoctoproject.org/downloads/poky/poky-einstein-6.0.tar.bz2
306 $ tar xjf poky-bernard-5.0.1.tar.bz2 319 $ tar xjf poky-einstein-6.0.tar.bz2
307 $ source poky-bernard-5.0.1/poky-init-build-env poky-5.0.1-build 320 $ source poky-einstein-6.0/oe-init-build-env einstein-6.0-build
308 </literallayout> 321 </literallayout>
309 </para> 322 </para>
310 323
311 <tip><para> 324 <tip><para>
312 To help conserve disk space during builds you can add the following statement 325 To help conserve disk space during builds, you can add the following statement
313 to your <filename>local.conf</filename> file. 326 to your <filename>local.conf</filename> file in the Yocto Project build
327 directory, which for this example
328 is <filename>einstein-6.0-build</filename>.
314 Adding this statement deletes the work directory used for building a package 329 Adding this statement deletes the work directory used for building a package
315 once the package is built. 330 once the package is built.
316 <literallayout class='monospaced'> 331 <literallayout class='monospaced'>
@@ -319,25 +334,55 @@
319 </para></tip> 334 </para></tip>
320 335
321 <itemizedlist> 336 <itemizedlist>
322 <listitem><para>The first two commands extract the Yocto Project files from the 337 <listitem><para>The first command retrieves the Yocto Project release tarball from the
323 release tarball and place them into a subdirectory of your current directory.</para></listitem> 338 source repositories.
324 <listitem><para>The <command>source</command> command creates the 339 Notice, the example uses the <filename>wget</filename> shell command.
325 <filename>poky-5.0.1-build</filename> directory and executes the <command>cd</command> 340 Alternatively, you can go to the
326 command to make <filename>poky-5.0.1-build</filename> the working directory. 341 <ulink url='http://www.yoctoproject.org'>Yocto Project website</ulink> downloads
327 The resulting build directory contains all the files created during the build. 342 area to retrieve the tarball.</para></listitem>
328 By default the target architecture is qemux86. 343 <listitem><para>The second command extracts the files from the tarball and places
329 To change this default, edit the value of the MACHINE variable in the 344 them into a directory named <filename>poky-einstein-6.0</filename> in the current
330 <filename>conf/local.conf</filename> file.</para></listitem> 345 directory.
346 </para></listitem>
347 <listitem><para>The third command runs the Yocto Project environment setup script.
348 Running this script defines Yocto Project build environment settings needed to
349 complete the build.
350 The script also creates the Yocto Project
351 build directory, which is <filename>einstein-6.0-build</filename> in this case.
352 After the script runs, your current working directory is set
353 to the build directory.
354 Later, when the build completes, the build directory contains all the files
355 created during the build.
356 </para></listitem>
331 </itemizedlist> 357 </itemizedlist>
332 <para> 358 <para>
333 Take some time to examine your <filename>conf/local.conf</filename> file found in the 359 Take some time to examine your <filename>conf/local.conf</filename> file found in the
334 Yocto Project file's <filename>conf</filename>. 360 Yocto Project build directory.
335 The defaults should work fine. 361 The defaults in the <filename>local.conf</filename> should work fine.
336 However, if you have a multi-core CPU you might want to set the variable 362 However, there are some variables of interest at which you might look.
337 BB_NUMBER_THREADS equal to twice the number of processor cores your system has. 363 </para>
338 And, set the variable PARALLEL_MAKE equal to the number of processor cores. 364
365 <para>
366 By default, the target architecture for the build is <filename>qemux86</filename>,
367 which is an image that can be used in the QEMU emulator and is targeted for an
368 <trademark class='registered'>Intel</trademark> 32-bit based architecture.
369 To change this default, edit the value of the <filename>MACHINE</filename> variable in the
370 <filename>conf/local.conf</filename> file in the build directory before
371 launching the build.
372 </para>
373
374 <para>
375 Another couple of variables of interest are the
376 <ulink url='http://www.yoctoproject.org/docs/1.1/poky-ref-manual/poky-ref-manual.html#var-BB_NUMBER_THREADS'><filename>BB_NUMBER_THREADS</filename></ulink> and the
377 <ulink url='http://www.yoctoproject.org/docs/1.1/poky-ref-manual/poky-ref-manual.html#var-PARALLEL_MAKE'><filename>PARALLEL_MAKE</filename></ulink> variables.
378 By default, these variables are commented out.
379 However, if you have a multi-core CPU you might want to remove the comment
380 and set the variable
381 <filename>BB_NUMBER_THREADS</filename> equal to twice the number of your
382 host's processor cores.
383 Also, you could set the variable <filename>PARALLEL_MAKE</filename> equal to the number
384 of processor cores.
339 Setting these variables can significantly shorten your build time. 385 Setting these variables can significantly shorten your build time.
340 By default, these variables are commented out.
341 </para> 386 </para>
342 387
343 <para> 388 <para>
@@ -345,9 +390,9 @@
345 the image. 390 the image.
346 By default, the Yocto Project build system uses the RPM package manager. 391 By default, the Yocto Project build system uses the RPM package manager.
347 You can control this configuration by using the 392 You can control this configuration by using the
348 <filename><ulink url='http://www.yoctoproject.org/docs/1.1/poky-ref-manual/poky-ref-manual.html#var-PACKAGE_CLASSES'>PACKAGE_CLASSES</ulink></filename> variable. 393 <filename><ulink url='http://www.yoctoproject.org/docs/1.1/poky-ref-manual/poky-ref-manual.html#var-PACKAGE_CLASSES'><filename>PACKAGE_CLASSES</filename></ulink></filename> variable.
349 For additional package manager selection information, see 394 For additional package manager selection information, see
350 <ulink url='http://www.yoctoproject.org/docs/1.1/poky-ref-manual/poky-ref-manual.html#ref-classes-package'>Packaging - <filename>package*.bbclass</filename></ulink> in 395 "<ulink url='http://www.yoctoproject.org/docs/1.1/poky-ref-manual/poky-ref-manual.html#ref-classes-package'>Packaging - <filename>package*.bbclass</filename></ulink>" in
351 <ulink url='http://www.yoctoproject.org/docs/1.1/poky-ref-manual/poky-ref-manual.html'> 396 <ulink url='http://www.yoctoproject.org/docs/1.1/poky-ref-manual/poky-ref-manual.html'>
352 The Yocto Project Reference Manual</ulink>. 397 The Yocto Project Reference Manual</ulink>.
353 </para> 398 </para>
@@ -355,10 +400,9 @@
355 <para> 400 <para>
356 Continue with the following command to build an OS image for the target, which is 401 Continue with the following command to build an OS image for the target, which is
357 <filename>core-image-sato</filename> in this example. 402 <filename>core-image-sato</filename> in this example.
358 For information on the <filename>&dash;k</filename> option use the 403 For information on the <filename>-k</filename> option use the
359 <filename>bitbake --help</filename> command or see 404 <filename>bitbake --help</filename> command or see the
360 <ulink url='http://www.yoctoproject.org/docs/poky-ref-manual/poky-ref-manual.html#usingpoky-components-bitbake'> 405 "<ulink url='http://www.yoctoproject.org/docs/poky-ref-manual/poky-ref-manual.html#usingpoky-components-bitbake'>BitBake</ulink>" section in the Yocto Project Reference Manual.
361 BitBake</ulink> section in the Yocto Project Reference Manual.
362 <literallayout class='monospaced'> 406 <literallayout class='monospaced'>
363 $ bitbake -k core-image-sato 407 $ bitbake -k core-image-sato
364 </literallayout> 408 </literallayout>
@@ -383,16 +427,13 @@
383 427
384 <section id='using-pre-built'> 428 <section id='using-pre-built'>
385 <title>Using Pre-Built Binaries and QEMU</title> 429 <title>Using Pre-Built Binaries and QEMU</title>
430
386 <para> 431 <para>
387 If hardware, libraries and services are stable you can get started by using a pre-built binary 432 If hardware, libraries and services are stable, you can get started by using a pre-built binary
388 of the image, kernel and toolchain and run it using the emulator QEMU. 433 of the image, kernel, and toolchain and run it using the QEMU emulator.
389 This scenario is useful for developing application software. 434 This scenario is useful for developing application software.
390 </para> 435 </para>
391 436
392 <para></para>
393 <para></para>
394 <para></para>
395
396 <mediaobject> 437 <mediaobject>
397 <imageobject> 438 <imageobject>
398 <imagedata fileref="figures/using-a-pre-built-image.png" format="PNG" align='center' scalefit='1'/> 439 <imagedata fileref="figures/using-a-pre-built-image.png" format="PNG" align='center' scalefit='1'/>
@@ -400,53 +441,38 @@
400 <caption> 441 <caption>
401 <para>Using a Pre-Built Image</para> 442 <para>Using a Pre-Built Image</para>
402 </caption> 443 </caption>
403 </mediaobject> 444 </mediaobject>
404 445
405 <para> 446 <para>
406 For this scenario you need to do several things: 447 For this scenario, you need to do several things:
407 </para> 448 </para>
408
409 <itemizedlist>
410 <listitem>
411 <para>
412 Install the stand-alone Yocto toolchain tarball.
413 </para>
414 </listitem>
415 <listitem>
416 <para>
417 Download the pre-built kernel that will boot with QEMU.
418 You need to be sure to get the QEMU image that matches your target machine’s
419 architecture (e.g. x86, ARM, etc.).
420 </para>
421 </listitem>
422 <listitem>
423 <para>
424 Download the filesystem image for your target machine's architecture.
425 </para>
426 </listitem>
427 <listitem>
428 <para>
429 Set up the environment to emulate the hardware and then start the QEMU emulator.
430 </para>
431 </listitem>
432 449
433 </itemizedlist> 450 <itemizedlist>
451 <listitem><para>Install the stand-alone Yocto toolchain tarball.</para></listitem>
452 <listitem><para>Download the pre-built image that will boot with QEMU.
453 You need to be sure to get the QEMU image that matches your target machine’s
454 architecture (e.g. x86, ARM, etc.).</para></listitem>
455 <listitem><para>Download the filesystem image for your target machine's architecture.
456 </para></listitem>
457 <listitem><para>Set up the environment to emulate the hardware and then start the QEMU emulator.
458 </para></listitem>
459 </itemizedlist>
434 460
435 <section id='installing-the-toolchain'> 461 <section id='installing-the-toolchain'>
436 <title>Installing the Toolchain</title> 462 <title>Installing the Toolchain</title>
437 <para> 463 <para>
438 You can download the pre-built toolchain, which includes the <filename>runqemu</filename> 464 You can download the pre-built toolchain, which includes the <filename>runqemu</filename>
439 script and support files, from 465 script and support files, from
440 <ulink url='http://yoctoproject.org/downloads/yocto-1.0/toolchain/'></ulink>. 466 <ulink url='http://yoctoproject.org/downloads/yocto-1.1/toolchain/'></ulink>.
441 Toolchains are available for 32-bit and 64-bit development systems from the 467 Toolchains are available for 32-bit and 64-bit development systems from the
442 <filename>i686</filename> and <filename>x86_64</filename> folders, respectively. 468 <filename>i686</filename> and <filename>x86_64</filename> folders, respectively.
443 Each type of development system supports five target architectures. 469 Each type of development system supports five target architectures.
444 The tarball files are named such that a string representing the host system appears 470 The tarball files are named such that a string representing the host system appears
445 first in the filename and then is immediately followed by a string representing 471 first in the filename and then is immediately followed by a string representing
446 the target architecture. 472 the target architecture.
447 </para> 473 </para>
448 474
449 <literallayout class='monospaced'> 475 <literallayout class='monospaced'>
450 yocto-eglibc&lt;<emphasis>host_system</emphasis>&gt;-&lt;<emphasis>arch</emphasis>&gt;-toolchain-gmae-&lt;<emphasis>release</emphasis>&gt;.tar.bz2 476 yocto-eglibc&lt;<emphasis>host_system</emphasis>&gt;-&lt;<emphasis>arch</emphasis>&gt;-toolchain-gmae-&lt;<emphasis>release</emphasis>&gt;.tar.bz2
451 477
452 Where: 478 Where:
@@ -457,50 +483,55 @@
457 i586, x86_64, powerpc, mips, or arm. 483 i586, x86_64, powerpc, mips, or arm.
458 484
459 &lt;<emphasis>release</emphasis>&gt; is the version of Yocto Project. 485 &lt;<emphasis>release</emphasis>&gt; is the version of Yocto Project.
460 </literallayout> 486 </literallayout>
461 487
462 <para> 488 <para>
463 For example, the following toolchain tarball is for a 64-bit development 489 For example, the following toolchain tarball is for a 64-bit development
464 host system and a 32-bit target architecture: 490 host system and a 32-bit target architecture:
465 </para> 491 </para>
466 492
467 <literallayout class='monospaced'> 493 <literallayout class='monospaced'>
468 yocto-eglibc-x86_64-i586-toolchain-gmae-1.1.tar.bz2 494 yocto-eglibc-x86_64-i586-toolchain-gmae-1.1.tar.bz2
469 </literallayout> 495 </literallayout>
470 496
471 <para> 497 <para>
472 The toolchain tarballs are self-contained and must be installed into <filename>/opt/poky</filename>. 498 The toolchain tarballs are self-contained and must be installed into <filename>/opt/poky</filename>.
473 The following commands show how you install the toolchain tarball given a 64-bit development host system 499 The following commands show how you install the toolchain tarball given a 64-bit development host system
474 and a 32-bit target architecture. 500 and a 32-bit target architecture.
475 The example assumes the toolchain tarball is located in <filename>~/toolchains/</filename>: 501 The example assumes the toolchain tarball is located in <filename>~/toolchains/</filename>:
476 </para> 502 </para>
477 503
478 <para> 504 <para>
479 <literallayout class='monospaced'> 505 <literallayout class='monospaced'>
480 $ cd / 506 $ cd /
481 $ sudo tar -xvjf ~/toolchains/yocto-eglibc-x86_64-i586-toolchain-gmae-1.1.tar.bz2 507 $ sudo tar -xvjf ~/toolchains/yocto-eglibc-x86_64-i586-toolchain-gmae-1.1.tar.bz2
482 </literallayout> 508 </literallayout>
483 </para> 509 </para>
484 </section>
485 510
486 <section id='downloading-the-pre-built-linux-kernel'> 511 <para>
487 <title>Downloading the Pre-Built Linux Kernel</title> 512 For more information on how to install tarballs, see the
488 <para> 513 "<ulink url='http://www.yoctoproject.org/docs/1.1/adt-manual/adt-manual.html#using-an-existing-toolchain-tarball'>Using a Cross-Toolchain Tarball</ulink>" and
489 You can download the pre-built Linux kernel and the filesystem image suitable for 514 "<ulink url='http://www.yoctoproject.org/docs/1.1/adt-manual/adt-manual.html#using-the-toolchain-from-within-the-build-tree'>Using BitBake and the Yocto Project Build Tree</ulink>" sections in
490 running in the emulator QEMU from 515 <ulink url='http://www.yoctoproject.org/docs/1.1/adt-manual/adt-manual.html'>The Yocto Project
491 <ulink url='http://yoctoproject.org/downloads/yocto-1.0/machines/qemu'></ulink>. 516 Application Development Toolkit (ADT) Development Manual</ulink>.
492 Be sure to use the kernel and filesystem image that matches the architecture you want 517 </para>
493 to simulate. 518 </section>
494 Download areas exist for the five supported machine architectures:
495 <filename>qemuarm</filename>, <filename>qemumips</filename>, <filename>qemuppc</filename>,
496 <filename>qemux86</filename>, and <filename>qemux86_64</filename>.
497 </para>
498
499 <para>
500 Most kernel files have one of the following forms:
501 </para>
502 519
503 <literallayout class='monospaced'> 520 <section id='downloading-the-pre-built-linux-kernel'>
521 <title>Downloading the Pre-Built Linux Kernel</title>
522
523 <para>
524 You can download the pre-built Linux kernel suitable for running in the QEMU emulator from
525 <ulink url='http://yoctoproject.org/downloads/yocto-1.1/machines/qemu'></ulink>.
526 Be sure to use the kernel that matches the architecture you want to simulate.
527 Download areas exist for the five supported machine architectures:
528 <filename>qemuarm</filename>, <filename>qemumips</filename>, <filename>qemuppc</filename>,
529 <filename>qemux86</filename>, and <filename>qemux86_64</filename>.
530 </para>
531
532 <para>
533 Most kernel files have one of the following forms:
534 <literallayout class='monospaced'>
504 *zImage-&lt;<emphasis>kernel-rev</emphasis>&gt;-qemu&lt;<emphasis>arch</emphasis>&gt;-&lt;<emphasis>release</emphasis>&gt;*.bin 535 *zImage-&lt;<emphasis>kernel-rev</emphasis>&gt;-qemu&lt;<emphasis>arch</emphasis>&gt;-&lt;<emphasis>release</emphasis>&gt;*.bin
505 vmlinux-&lt;<emphasis>kernel-rev</emphasis>&gt;-qemu&lt;<emphasis>arch</emphasis>&gt;-&lt;<emphasis>release</emphasis>&gt;*.bin 536 vmlinux-&lt;<emphasis>kernel-rev</emphasis>&gt;-qemu&lt;<emphasis>arch</emphasis>&gt;-&lt;<emphasis>release</emphasis>&gt;*.bin
506 537
@@ -512,21 +543,35 @@
512 x86, x86-64, ppc, mips, or arm. 543 x86, x86-64, ppc, mips, or arm.
513 544
514 &lt;<emphasis>release</emphasis>&gt; is the version of Yocto Project. 545 &lt;<emphasis>release</emphasis>&gt; is the version of Yocto Project.
515 </literallayout> 546 </literallayout>
516 </section> 547 </para>
548
549 <para>
550 You can learn more about downloading a Yocto Project kernel in the
551 "<ulink url='http://www.yoctoproject.org/docs/1.1/dev-manual/dev-manual.html#local-kernel-files'>Linux Yocto Kernel</ulink>" section of
552 <ulink url='http://www.yoctoproject.org/docs/1.1/dev-manual/dev-manual.html'>The
553 Yocto Project Development Manual</ulink>.
554 </para>
555 </section>
517 556
518 <section id='downloading-the-filesystem'> 557 <section id='downloading-the-filesystem'>
519 <title>Downloading the Filesystem</title> 558 <title>Downloading the Filesystem</title>
520 <para>
521 The filesystem image has two tarball forms: <filename>ext3</filename> and
522 <filename>tar</filename>.
523 You must use the <filename>ext3</filename> form when booting an image using the
524 QEMU emulator.
525 The <filename>tar</filename> form can be flattened out in your host development system
526 and used for Yocto Project build purposes.
527 </para>
528 559
529 <literallayout class='monospaced'> 560 <para>
561 You can also download the filesystem image suitable for your target architecture from
562 <ulink url='http://yoctoproject.org/downloads/yocto-1.1/machines/qemu'></ulink>.
563 Again, be sure to use the filesystem that matches the architecture you want
564 to simulate.
565 </para>
566
567 <para>
568 The filesystem image has two tarball forms: <filename>ext3</filename> and
569 <filename>tar</filename>.
570 You must use the <filename>ext3</filename> form when booting an image using the
571 QEMU emulator.
572 The <filename>tar</filename> form can be flattened out in your host development system
573 and used for Yocto Project build purposes.
574 <literallayout class='monospaced'>
530 yocto-image-&lt;<emphasis>profile</emphasis>&gt;-qemu&lt;<emphasis>arch</emphasis>&gt;-&lt;<emphasis>release</emphasis>&gt;.rootfs.ext3.bz2 575 yocto-image-&lt;<emphasis>profile</emphasis>&gt;-qemu&lt;<emphasis>arch</emphasis>&gt;-&lt;<emphasis>release</emphasis>&gt;.rootfs.ext3.bz2
531 yocto-image-&lt;<emphasis>profile</emphasis>&gt;-qemu&lt;<emphasis>arch</emphasis>&gt;-&lt;<emphasis>release</emphasis>&gt;.rootfs.tar.bz2 576 yocto-image-&lt;<emphasis>profile</emphasis>&gt;-qemu&lt;<emphasis>arch</emphasis>&gt;-&lt;<emphasis>release</emphasis>&gt;.rootfs.tar.bz2
532 577
@@ -540,17 +585,17 @@
540 x86, x86-64, ppc, mips, or arm. 585 x86, x86-64, ppc, mips, or arm.
541 586
542 &lt;<emphasis>release</emphasis>&gt; is the version of Yocto Project. 587 &lt;<emphasis>release</emphasis>&gt; is the version of Yocto Project.
543 </literallayout> 588 </literallayout>
544 </section> 589 </para>
590 </section>
545 591
546 <section id='setting-up-the-environment-and-starting-the-qemu-emulator'> 592 <section id='setting-up-the-environment-and-starting-the-qemu-emulator'>
547 <title>Setting Up the Environment and Starting the QEMU Emulator</title> 593 <title>Setting Up the Environment and Starting the QEMU Emulator</title>
548 <para> 594
549 Before you start the QEMU emulator you need to set up the emulation environment. 595 <para>
550 The following command form sets up the emulation environment. 596 Before you start the QEMU emulator, you need to set up the emulation environment.
551 </para> 597 The following command form sets up the emulation environment.
552 598 <literallayout class='monospaced'>
553 <literallayout class='monospaced'>
554 $ source /opt/poky/1.1/environment-setup-&lt;<emphasis>arch</emphasis>&gt;-poky-linux-&lt;<emphasis>if</emphasis>&gt; 599 $ source /opt/poky/1.1/environment-setup-&lt;<emphasis>arch</emphasis>&gt;-poky-linux-&lt;<emphasis>if</emphasis>&gt;
555 600
556 Where: 601 Where:
@@ -559,13 +604,12 @@
559 604
560 &lt;<emphasis>if</emphasis>&gt; is a string representing an embedded application binary interface. 605 &lt;<emphasis>if</emphasis>&gt; is a string representing an embedded application binary interface.
561 Not all setup scripts include this string. 606 Not all setup scripts include this string.
562 </literallayout> 607 </literallayout>
563 608 </para>
564 <para>
565 Finally, this command form invokes the QEMU emulator
566 </para>
567 609
568 <literallayout class='monospaced'> 610 <para>
611 Finally, this command form invokes the QEMU emulator
612 <literallayout class='monospaced'>
569 $ runqemu &lt;<emphasis>qemuarch</emphasis>&gt; &lt;<emphasis>kernel-image</emphasis>&gt; &lt;<emphasis>filesystem-image</emphasis>&gt; 613 $ runqemu &lt;<emphasis>qemuarch</emphasis>&gt; &lt;<emphasis>kernel-image</emphasis>&gt; &lt;<emphasis>filesystem-image</emphasis>&gt;
570 614
571 Where: 615 Where:
@@ -576,33 +620,32 @@
576 620
577 &lt;<emphasis>filesystem-image</emphasis>&gt; is the .ext3 filesystem image. 621 &lt;<emphasis>filesystem-image</emphasis>&gt; is the .ext3 filesystem image.
578 622
579 </literallayout> 623 </literallayout>
580 624 </para>
581 <para>
582 Continuing with the example, the following two commands setup the emulation
583 environment and launch QEMU.
584 This example assumes the root filesystem tarball has been downloaded and expanded, and
585 that the kernel and filesystem are for a 32-bit target architecture.
586 </para>
587 625
588 <literallayout class='monospaced'> 626 <para>
627 Continuing with the example, the following two commands setup the emulation
628 environment and launch QEMU.
629 This example assumes the root filesystem tarball has been downloaded and expanded, and
630 that the kernel and filesystem are for a 32-bit target architecture.
631 <literallayout class='monospaced'>
589 $ source /opt/poky/1.1/environment-setup-i686-poky-linux 632 $ source /opt/poky/1.1/environment-setup-i686-poky-linux
590 $ runqemu qemux86 bzImage-3.0-qemux86-1.1.bin \ 633 $ runqemu qemux86 bzImage-3.0-qemux86-1.1.bin \
591 yocto-image-sato-qemux86-1.1.rootfs.ext3 634 yocto-image-sato-qemux86-1.1.rootfs.ext3
592 </literallayout> 635 </literallayout>
636 </para>
593 637
594 <para> 638 <para>
595 The environment in which QEMU launches varies depending on the filesystem image and on the 639 The environment in which QEMU launches varies depending on the filesystem image and on the
596 target architecture. For example, if you source the environment for the ARM target 640 target architecture.
597 architecture and then boot the minimal QEMU image, the emulator comes up in a new 641 For example, if you source the environment for the ARM target
598 shell in command-line mode. However, if you boot the SDK image QEMU comes up with 642 architecture and then boot the minimal QEMU image, the emulator comes up in a new
599 a GUI. 643 shell in command-line mode.
600 </para> 644 However, if you boot the SDK image, QEMU comes up with a GUI.
601 645 <note>Booting the PPC image results in QEMU launching in the same shell in
602 <note><para> 646 command-line mode.</note>
603 Booting the PPC image results in QEMU launching in the same shell in command-line mode. 647 </para>
604 </para></note> 648 </section>
605 </section>
606 </section> 649 </section>
607</section> 650</section>
608 651