summaryrefslogtreecommitdiffstats
path: root/documentation/ref-manual
diff options
context:
space:
mode:
Diffstat (limited to 'documentation/ref-manual')
-rw-r--r--documentation/ref-manual/usingpoky.xml370
1 files changed, 0 insertions, 370 deletions
diff --git a/documentation/ref-manual/usingpoky.xml b/documentation/ref-manual/usingpoky.xml
index 7c2f0f67bc..e379459a20 100644
--- a/documentation/ref-manual/usingpoky.xml
+++ b/documentation/ref-manual/usingpoky.xml
@@ -11,376 +11,6 @@
11 documentation set provide more details on how to use the Yocto Project. 11 documentation set provide more details on how to use the Yocto Project.
12 </para> 12 </para>
13 13
14<section id='ref-quick-emulator-qemu'>
15 <title>Quick EMUlator (QEMU)</title>
16
17 <para>
18 The Yocto Project uses an implementation of the Quick EMUlator (QEMU)
19 Open Source project as part of the Yocto Project development "tool
20 set".
21 </para>
22
23 <para>
24 Within the context of the Yocto Project, QEMU is an
25 emulator and virtualization machine that allows you to run a complete
26 image you have built using the Yocto Project as just another task
27 on your build system.
28 QEMU is useful for running and testing images and applications on
29 supported Yocto Project architectures without having actual hardware.
30 Among other things, the Yocto Project uses QEMU to run automated
31 Quality Assurance (QA) tests on final images shipped with each
32 release.
33 <note>
34 This implementation is not the same as QEMU in general.
35 </note>
36 This section provides a brief reference for the Yocto Project
37 implementation of QEMU.
38 </para>
39
40 <para>
41 For official information and documentation on QEMU in general, see the
42 following references:
43 <itemizedlist>
44 <listitem><para>
45 <emphasis><ulink url='http://wiki.qemu.org/Main_Page'>QEMU Website</ulink>:</emphasis>
46 The official website for the QEMU Open Source project.
47 </para></listitem>
48 <listitem><para>
49 <emphasis><ulink url='http://wiki.qemu.org/Manual'>Documentation</ulink>:</emphasis>
50 The QEMU user manual.
51 </para></listitem>
52 </itemizedlist>
53 </para>
54
55 <para>
56 For information on how to use the Yocto Project implementation of
57 QEMU, see the
58 "<ulink url='&YOCTO_DOCS_DEV_URL;#dev-manual-qemu'>Using the Quick EMUlator (QEMU)</ulink>"
59 chapter in the Yocto Project Development Tasks Manual.
60 </para>
61
62 <section id='qemu-availability'>
63 <title>QEMU Availability</title>
64
65 <para>
66 QEMU is made available with the Yocto Project a number of ways.
67 One method is to install a Software Development Kit (SDK).
68 For more information on how to make sure you have
69 QEMU available, see
70 "<ulink url='&YOCTO_DOCS_SDK_URL;#the-qemu-emulator'>The QEMU Emulator</ulink>"
71 section in the Yocto Project Application Development and the
72 Extensible Software Development Kit (eSDK) manual.
73 </para>
74 </section>
75
76 <section id='qemu-performance'>
77 <title>QEMU Performance</title>
78
79 <para>
80 Using QEMU to emulate your hardware can result in speed issues
81 depending on the target and host architecture mix.
82 For example, using the <filename>qemux86</filename> image in the
83 emulator on an Intel-based 32-bit (x86) host machine is fast
84 because the target and host architectures match.
85 On the other hand, using the <filename>qemuarm</filename> image
86 on the same Intel-based host can be slower.
87 But, you still achieve faithful emulation of ARM-specific issues.
88 </para>
89
90 <para>
91 To speed things up, the QEMU images support using
92 <filename>distcc</filename> to call a cross-compiler outside the
93 emulated system.
94 If you used <filename>runqemu</filename> to start QEMU, and the
95 <filename>distccd</filename> application is present on the host
96 system, any BitBake cross-compiling toolchain available from the
97 build system is automatically used from within QEMU simply by
98 calling <filename>distcc</filename>.
99 You can accomplish this by defining the cross-compiler variable
100 (e.g. <filename>export CC="distcc"</filename>).
101 Alternatively, if you are using a suitable SDK image or the
102 appropriate stand-alone toolchain is present, the toolchain is
103 also automatically used.
104 </para>
105
106 <note>
107 Several mechanisms exist that let you connect to the system
108 running on the QEMU emulator:
109 <itemizedlist>
110 <listitem><para>
111 QEMU provides a framebuffer interface that makes standard
112 consoles available.
113 </para></listitem>
114 <listitem><para>
115 Generally, headless embedded devices have a serial port.
116 If so, you can configure the operating system of the
117 running image to use that port to run a console.
118 The connection uses standard IP networking.
119 </para></listitem>
120 <listitem><para>
121 SSH servers exist in some QEMU images.
122 The <filename>core-image-sato</filename> QEMU image has a
123 Dropbear secure shell (SSH) server that runs with the root
124 password disabled.
125 The <filename>core-image-full-cmdline</filename> and
126 <filename>core-image-lsb</filename> QEMU images
127 have OpenSSH instead of Dropbear.
128 Including these SSH servers allow you to use standard
129 <filename>ssh</filename> and <filename>scp</filename>
130 commands.
131 The <filename>core-image-minimal</filename> QEMU image,
132 however, contains no SSH server.
133 </para></listitem>
134 <listitem><para>
135 You can use a provided, user-space NFS server to boot
136 the QEMU session using a local copy of the root
137 filesystem on the host.
138 In order to make this connection, you must extract a
139 root filesystem tarball by using the
140 <filename>runqemu-extract-sdk</filename> command.
141 After running the command, you must then point the
142 <filename>runqemu</filename>
143 script to the extracted directory instead of a root
144 filesystem image file.
145 See the
146 "<ulink url='&YOCTO_DOCS_DEV_URL;#qemu-running-under-a-network-file-system-nfs-server'>Running Under a Network File System (NFS) Server</ulink>"
147 section in the Yocto Project Development Tasks Manual for
148 more information.
149 </para></listitem>
150 </itemizedlist>
151 </note>
152 </section>
153
154 <section id='qemu-command-line-syntax'>
155 <title>QEMU Command-Line Syntax</title>
156
157 <para>
158 The basic <filename>runqemu</filename> command syntax is as
159 follows:
160 <literallayout class='monospaced'>
161 $ runqemu [<replaceable>option</replaceable> ] [...]
162 </literallayout>
163 Based on what you provide on the command line,
164 <filename>runqemu</filename> does a good job of figuring out what
165 you are trying to do.
166 For example, by default, QEMU looks for the most recently built
167 image according to the timestamp when it needs to look for an
168 image.
169 Minimally, through the use of options, you must provide either
170 a machine name, a virtual machine image
171 (<filename>*wic.vmdk</filename>), or a kernel image
172 (<filename>*.bin</filename>).
173 </para>
174
175 <para>
176 Following is the command-line help output for the
177 <filename>runqemu</filename> command:
178 <literallayout class='monospaced'>
179 $ runqemu --help
180
181 Usage: you can run this script with any valid combination
182 of the following environment variables (in any order):
183 KERNEL - the kernel image file to use
184 ROOTFS - the rootfs image file or nfsroot directory to use
185 MACHINE - the machine name (optional, autodetected from KERNEL filename if unspecified)
186 Simplified QEMU command-line options can be passed with:
187 nographic - disable video console
188 serial - enable a serial console on /dev/ttyS0
189 slirp - enable user networking, no root privileges is required
190 kvm - enable KVM when running x86/x86_64 (VT-capable CPU required)
191 kvm-vhost - enable KVM with vhost when running x86/x86_64 (VT-capable CPU required)
192 publicvnc - enable a VNC server open to all hosts
193 audio - enable audio
194 [*/]ovmf* - OVMF firmware file or base name for booting with UEFI
195 tcpserial=&lt;port&gt; - specify tcp serial port number
196 biosdir=&lt;dir&gt; - specify custom bios dir
197 biosfilename=&lt;filename&gt; - specify bios filename
198 qemuparams=&lt;xyz&gt; - specify custom parameters to QEMU
199 bootparams=&lt;xyz&gt; - specify custom kernel parameters during boot
200 help, -h, --help: print this text
201
202 Examples:
203 runqemu
204 runqemu qemuarm
205 runqemu tmp/deploy/images/qemuarm
206 runqemu tmp/deploy/images/qemux86/&lt;qemuboot.conf&gt;
207 runqemu qemux86-64 core-image-sato ext4
208 runqemu qemux86-64 wic-image-minimal wic
209 runqemu path/to/bzImage-qemux86.bin path/to/nfsrootdir/ serial
210 runqemu qemux86 iso/hddimg/wic.vmdk/wic.qcow2/wic.vdi/ramfs/cpio.gz...
211 runqemu qemux86 qemuparams="-m 256"
212 runqemu qemux86 bootparams="psplash=false"
213 runqemu path/to/&lt;image&gt;-&lt;machine&gt;.wic
214 runqemu path/to/&lt;image&gt;-&lt;machine&gt;.wic.vmdk
215 </literallayout>
216 </para>
217 </section>
218
219 <section id='runqemu-command-line-options'>
220 <title><filename>runqemu</filename> Command-Line Options</title>
221
222 <para>
223 Following is a description of <filename>runqemu</filename>
224 options you can provide on the command line:
225 <note><title>Tip</title>
226 If you do provide some "illegal" option combination or perhaps
227 you do not provide enough in the way of options,
228 <filename>runqemu</filename> provides appropriate error
229 messaging to help you correct the problem.
230 </note>
231 <itemizedlist>
232 <listitem><para>
233 <replaceable>QEMUARCH</replaceable>:
234 The QEMU machine architecture, which must be "qemuarm",
235 "qemuarm64", "qemumips", "qemumips64", "qemuppc",
236 "qemux86", or "qemux86-64".
237 </para></listitem>
238 <listitem><para>
239 <filename><replaceable>VM</replaceable></filename>:
240 The virtual machine image, which must be a
241 <filename>.wic.vmdk</filename> file.
242 Use this option when you want to boot a
243 <filename>.wic.vmdk</filename> image.
244 The image filename you provide must contain one of the
245 following strings: "qemux86-64", "qemux86", "qemuarm",
246 "qemumips64", "qemumips", "qemuppc", or "qemush4".
247 </para></listitem>
248 <listitem><para>
249 <replaceable>ROOTFS</replaceable>:
250 A root filesystem that has one of the following
251 filetype extensions: "ext2", "ext3", "ext4", "jffs2",
252 "nfs", or "btrfs".
253 If the filename you provide for this option uses “nfs”, it
254 must provide an explicit root filesystem path.
255 </para></listitem>
256 <listitem><para>
257 <replaceable>KERNEL</replaceable>:
258 A kernel image, which is a <filename>.bin</filename> file.
259 When you provide a <filename>.bin</filename> file,
260 <filename>runqemu</filename> detects it and assumes the
261 file is a kernel image.
262 </para></listitem>
263 <listitem><para>
264 <replaceable>MACHINE</replaceable>:
265 The architecture of the QEMU machine, which must be one
266 of the following: "qemux86", "qemux86-64", "qemuarm",
267 "qemuarm64", "qemumips", “qemumips64", or "qemuppc".
268 The <replaceable>MACHINE</replaceable> and
269 <replaceable>QEMUARCH</replaceable> options are basically
270 identical.
271 If you do not provide a <replaceable>MACHINE</replaceable>
272 option, <filename>runqemu</filename> tries to determine
273 it based on other options.
274 </para></listitem>
275 <listitem><para>
276 <filename>ramfs</filename>:
277 Indicates you are booting an initial RAM disk (initramfs)
278 image, which means the <filename>FSTYPE</filename> is
279 <filename>cpio.gz</filename>.
280 </para></listitem>
281 <listitem><para>
282 <filename>iso</filename>:
283 Indicates you are booting an ISO image, which means the
284 <filename>FSTYPE</filename> is
285 <filename>.iso</filename>.
286 </para></listitem>
287 <listitem><para>
288 <filename>nographic</filename>:
289 Disables the video console, which sets the console to
290 "ttys0".
291 </para></listitem>
292 <listitem><para>
293 <filename>serial</filename>:
294 Enables a serial console on
295 <filename>/dev/ttyS0</filename>.
296 </para></listitem>
297 <listitem><para>
298 <filename>biosdir</filename>:
299 Establishes a custom directory for BIOS, VGA BIOS and
300 keymaps.
301 </para></listitem>
302 <listitem><para>
303 <filename>biosfilename</filename>:
304 Establishes a custom BIOS name.
305 </para></listitem>
306 <listitem><para>
307 <filename>qemuparams=\"<replaceable>xyz</replaceable>\"</filename>:
308 Specifies custom QEMU parameters.
309 Use this option to pass options other than the simple
310 "kvm" and "serial" options.
311 </para></listitem>
312 <listitem><para><filename>bootparams=\"<replaceable>xyz</replaceable>\"</filename>:
313 Specifies custom boot parameters for the kernel.
314 </para></listitem>
315 <listitem><para>
316 <filename>audio</filename>:
317 Enables audio in QEMU.
318 The <replaceable>MACHINE</replaceable> option must be
319 either "qemux86" or "qemux86-64" in order for audio to be
320 enabled.
321 Additionally, the <filename>snd_intel8x0</filename>
322 or <filename>snd_ens1370</filename> driver must be
323 installed in linux guest.
324 </para></listitem>
325 <listitem><para>
326 <filename>slirp</filename>:
327 Enables "slirp" networking, which is a different way
328 of networking that does not need root access
329 but also is not as easy to use or comprehensive
330 as the default.
331 </para></listitem>
332 <listitem><para id='kvm-cond'>
333 <filename>kvm</filename>:
334 Enables KVM when running "qemux86" or "qemux86-64"
335 QEMU architectures.
336 For KVM to work, all the following conditions must be met:
337 <itemizedlist>
338 <listitem><para>
339 Your <replaceable>MACHINE</replaceable> must be either
340qemux86" or "qemux86-64".
341 </para></listitem>
342 <listitem><para>
343 Your build host has to have the KVM modules
344 installed, which are
345 <filename>/dev/kvm</filename>.
346 </para></listitem>
347 <listitem><para>
348 The build host <filename>/dev/kvm</filename>
349 directory has to be both writable and readable.
350 </para></listitem>
351 </itemizedlist>
352 </para></listitem>
353 <listitem><para>
354 <filename>kvm-vhost</filename>:
355 Enables KVM with VHOST support when running "qemux86"
356 or "qemux86-64" QEMU architectures.
357 For KVM with VHOST to work, the following conditions must
358 be met:
359 <itemizedlist>
360 <listitem><para>
361 <link linkend='kvm-cond'>kvm</link> option
362 conditions must be met.
363 </para></listitem>
364 <listitem><para>
365 Your build host has to have virtio net device, which
366 are <filename>/dev/vhost-net</filename>.
367 </para></listitem>
368 <listitem><para>
369 The build host <filename>/dev/vhost-net</filename>
370 directory has to be either readable or writable
371 and “slirp-enabled”.
372 </para></listitem>
373 </itemizedlist>
374 </para></listitem>
375 <listitem><para>
376 <filename>publicvnc</filename>:
377 Enables a VNC server open to all hosts.
378 </para></listitem>
379 </itemizedlist>
380 </para>
381 </section>
382</section>
383
384<section id='maintaining-build-output-quality'> 14<section id='maintaining-build-output-quality'>
385 <title>Maintaining Build Output Quality</title> 15 <title>Maintaining Build Output Quality</title>
386 16
generated by cgit v1.2.3-54-g00ecf (git 2.39.0) at 2026-01-24 13:32:06 +0000