summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
Diffstat
-rw-r--r--documentation/dev-manual/dev-manual-qemu.xml332
-rw-r--r--documentation/dev-manual/dev-manual.xml2
2 files changed, 313 insertions, 21 deletions
diff --git a/documentation/dev-manual/dev-manual-qemu.xml b/documentation/dev-manual/dev-manual-qemu.xml
index 17bbc2774a..d206c111ed 100644
--- a/documentation/dev-manual/dev-manual-qemu.xml
+++ b/documentation/dev-manual/dev-manual-qemu.xml
@@ -4,13 +4,13 @@
4 4
5<chapter id='dev-manual-qemu'> 5<chapter id='dev-manual-qemu'>
6 6
7<title>Using the Quick EMUlator</title> 7<title>Using the Quick EMUlator (QEMU)</title>
8 8
9<para> 9<para>
10 Quick EMUlator (QEMU) is an Open Source project the Yocto Project uses 10 Quick EMUlator (QEMU) is an Open Source project the Yocto Project uses
11 as part of its development "toolset". 11 as part of its development "tool set".
12 As such, the information in this chapter is limited to the 12 As such, the information in this chapter is limited to the
13 Yocto Project instatiation of QEMU and not QEMU in general. 13 Yocto Project integration of QEMU and not QEMU in general.
14 For official information and documentation on QEMU, see the 14 For official information and documentation on QEMU, see the
15 following references: 15 following references:
16 <itemizedlist> 16 <itemizedlist>
@@ -24,9 +24,10 @@
24</para> 24</para>
25 25
26<para> 26<para>
27 This chapter provides an overview of the Yocto Project instantiation of 27 This chapter provides an overview of the Yocto Project's integration of
28 QEMU, a description of how you use QEMU and its various options and modes, 28 QEMU, a description of how you use QEMU and its various options, running
29 and a few tips and tricks you might find helpful when using QEMU. 29 under a Network File System (NFS) server, and a few tips and tricks you
30 might find helpful when using QEMU.
30</para> 31</para>
31 32
32<section id='qemu-overview'> 33<section id='qemu-overview'>
@@ -39,6 +40,9 @@
39 on your build system. 40 on your build system.
40 QEMU is useful for running and testing images and applications on 41 QEMU is useful for running and testing images and applications on
41 supported Yocto Project architectures without having actual hardware. 42 supported Yocto Project architectures without having actual hardware.
43 Among other things, the Yocto Project uses QEMU to run automated
44 Quality Assurance (QA) tests on final images shipped with each
45 release.
42 </para> 46 </para>
43 47
44 <para> 48 <para>
@@ -80,11 +84,14 @@
80 The basic <filename>runqemu</filename> command syntax is as 84 The basic <filename>runqemu</filename> command syntax is as
81 follows: 85 follows:
82 <literallayout class='monospaced'> 86 <literallayout class='monospaced'>
83 $ runqemu [<replaceable>option</replaceable> ] [<replaceable>option</replaceable> ] [...] 87 $ runqemu [<replaceable>option</replaceable> ] [...]
84 </literallayout> 88 </literallayout>
85 <filename>runqemu</filename> does a good job based on what you 89 Based on what you provide on the command line,
86 provide with the command at figuring out what you are trying 90 <filename>runqemu</filename> does a good job of figuring out what
87 to do. 91 you are trying to do.
92 For example, by default, QEMU looks for the most recently built
93 image according to the timestamp when it needs to look for an
94 image.
88 Minimally, through the use of options, you must provide either 95 Minimally, through the use of options, you must provide either
89 a machine name, a virtual machine image 96 a machine name, a virtual machine image
90 (<filename>*.vmdk</filename>), or a kernel image 97 (<filename>*.vmdk</filename>), or a kernel image
@@ -92,35 +99,318 @@
92 </para> 99 </para>
93 100
94 <para> 101 <para>
95 If you do provide some "illegal" combination or options or perhaps
96 do not provide enough in the way of options,
97 <filename>runqemu</filename> provides appropriate error messaging
98 to help you figure it out.
99 </para>
100
101 <para>
102 Following is a description of <filename>runqemu</filename> 102 Following is a description of <filename>runqemu</filename>
103 options you can provide on the command line: 103 options you can provide on the command line:
104 <note><title>Tip</title>
105 If you do provide some "illegal" option combination or perhaps
106 you do not provide enough in the way of options,
107 <filename>runqemu</filename> provides appropriate error
108 messaging to help you correct the problem.
109 </note>
104 <itemizedlist> 110 <itemizedlist>
105 <listitem><para><emphasis><replaceable>QEMUARCH</replaceable>:</emphasis> 111 <listitem><para><replaceable>QEMUARCH</replaceable>:
106 The QEMU machine architecture, which can be "qemux86", 112 The QEMU machine architecture, which must be "qemux86",
107 "qemux86-64", "qemuarm", "qemumips", "qemumipsel", 113 "qemux86-64", "qemuarm", "qemumips", "qemumipsel",
108 “qemumips64", "qemush4", "qemuppc", "qemumicroblaze", 114 “qemumips64", "qemush4", "qemuppc", "qemumicroblaze",
109 or "qemuzynq". 115 or "qemuzynq".
110 </para></listitem> 116 </para></listitem>
117 <listitem><para><filename><replaceable>VM</replaceable></filename>:
118 The virtual machine image, which must be a
119 <filename>.vmdk</filename> file.
120 Use this option when you want to boot a
121 <filename>.vmdk</filename> image.
122 The image filename you provide must contain one of the
123 following strings: "qemux86-64", "qemux86", "qemuarm",
124 "qemumips64", "qemumips", "qemuppc", or "qemush4".
125 </para></listitem>
126 <listitem><para><replaceable>ROOTFS</replaceable>:
127 A root filesystem that has one of the following
128 filetype extensions: "ext2", "ext3", "ext4", "jffs2",
129 "nfs", or "btrfs".
130 If the filename you provide for this option uses “nfs”, it
131 must provide an explicit root filesystem path.
132 </para></listitem>
133 <listitem><para><replaceable>KERNEL</replaceable>:
134 A kernel image, which is a <filename>.bin</filename> file.
135 When you provide a <filename>.bin</filename> file,
136 <filename>runqemu</filename> detects it and assumes the
137 file is a kernel image.
138 </para></listitem>
139 <listitem><para><replaceable>MACHINE</replaceable>:
140 The architecture of the QEMU machine, which must be one
141 of the following: "qemux86",
142 "qemux86-64", "qemuarm", "qemumips", "qemumipsel",
143 “qemumips64", "qemush4", "qemuppc", "qemumicroblaze",
144 or "qemuzynq".
145 The <replaceable>MACHINE</replaceable> and
146 <replaceable>QEMUARCH</replaceable> options are basically
147 identical.
148 If you do not provide a <replaceable>MACHINE</replaceable>
149 option, <filename>runqemu</filename> tries to determine
150 it based on other options.
151 </para></listitem>
152 <listitem><para><filename>ramfs</filename>:
153 Indicates you are booting an initial RAM disk (initramfs)
154 image, which means the <filename>FSTYPE</filename> is
155 <filename>cpio.gz</filename>.
156 </para></listitem>
157 <listitem><para><filename>iso</filename>:
158 Indicates you are booting an ISO image, which means the
159 <filename>FSTYPE</filename> is
160 <filename>.iso</filename>.
161 </para></listitem>
162 <listitem><para><filename>nographic</filename>:
163 Disables the video console, which sets the console to
164 "ttys0".
165 </para></listitem>
166 <listitem><para><filename>serial</filename>:
167 Enables a serial console on
168 <filename>/dev/ttyS0</filename>.
169 </para></listitem>
170 <listitem><para><filename>biosdir</filename>:
171 Establishes a custom directory for BIOS, VGA BIOS and
172 keymaps.
173 </para></listitem>
174 <listitem><para><filename>qemuparams=\"<replaceable>xyz</replaceable>\"</filename>:
175 Specifies custom QEMU parameters.
176 Use this option to pass options other than the simple
177 "kvm" and "serial" options.
178 </para></listitem>
179 <listitem><para><filename>bootparams=\"<replaceable>xyz</replaceable>\"</filename>:
180 Specifies custom boot parameters for the kernel.
181 </para></listitem>
182 <listitem><para><filename>audio</filename>:
183 Enables audio in QEMU.
184 The <replaceable>MACHINE</replaceable> option must be
185 either "qemux86" or "qemux86-64" in order for audio to be
186 enabled.
187 Additionally, the <filename>snd_intel8x0</filename>
188 or <filename>snd_ens1370</filename> driver must be
189 installed in linux guest.
190 </para></listitem>
191 <listitem><para><filename>slirp</filename>:
192 Enables "slirp" networking, which is a different way
193 of networking that does not need root access
194 but also is not as easy to use or comprehensive
195 as the default.
196 </para></listitem>
197 <listitem><para><filename>kvm</filename>:
198 Enables KVM when running "qemux86" or "qemux86-64"
199 QEMU architectures.
200 For KVM to work, all the following conditions must be met:
201 <itemizedlist>
202 <listitem><para>
203 Your <replaceable>MACHINE</replaceable> must be either
204 "qemux86" or "qemux86-64".
205 </para></listitem>
206 <listitem><para>
207 Your build host has to have the KVM modules
208 installed, which are
209 <filename>/dev/kvm</filename>.
210 </para></listitem>
211 <listitem><para>
212 Your build host has to have virtio net device, which
213 are <filename>/dev/vhost-net</filename>.
214 </para></listitem>
215 <listitem><para>
216 The build host <filename>/dev/kvm</filename>
217 directory has to be both writable and readable.
218 </para></listitem>
219 <listitem><para>
220 The build host <filename>/dev/vhost-net</filename>
221 directory has to be either readable or writable
222 and “slirp-enabled”.
223 </para></listitem>
224 </itemizedlist>
225 </para></listitem>
226 <listitem><para><filename>publicvnc</filename>:
227 Enables a VNC server open to all hosts.
228 </para></listitem>
111 </itemizedlist> 229 </itemizedlist>
112 </para> 230 </para>
231
232 <para>
233 For further understanding regarding option use with
234 <filename>runqemu</filename>, consider some examples.
235 </para>
236
237 <para>
238 This example starts QEMU with
239 <replaceable>MACHINE</replaceable> set to "qemux86".
240 Assuming a standard
241 <link linkend='build-directory'>Build Directory</link>,
242 <filename>runqemu</filename> automatically finds the
243 <filename>bzImage-qemux86.bin</filename> image file and
244 the
245 <filename>core-image-minimal-qemux86-20140707074611.rootfs.ext3</filename>
246 (assuming the current build created a
247 <filename>core-image-minimal</filename> image).
248 <note>
249 When more than one image with the same name exists, QEMU finds
250 and uses the most recently built image according to the
251 timestamp.
252 </note>
253 <literallayout class='monospaced'>
254 $ runqemu qemux86
255 </literallayout>
256 This example produces the exact same results as the
257 previous example.
258 This command, however, specifically provides the image
259 and root filesystem type.
260 <literallayout class='monospaced'>
261 $ runqemu qemux86 core-image-minimal ext3
262 </literallayout>
263 This example specifies to boot an initial RAM disk image
264 and to enable audio in QEMU.
265 For this case, <filename>runqemu</filename> set the
266 internal variable <filename>FSTYPE</filename> to
267 "cpio.gz".
268 Also, for audio to be enabled, an appropriate driver must
269 be installed (see the previous description for the
270 <filename>audio</filename> option for more information).
271 <literallayout class='monospaced'>
272 $ runqemu qemux86 ramfs audio
273 </literallayout>
274 This example does not provide enough information for
275 QEMU to launch.
276 While the command does provide a root filesystem type, it
277 must also minimally provide a
278 <replaceable>MACHINE</replaceable>,
279 <replaceable>KERNEL</replaceable>, or
280 <replaceable>VM</replaceable> option.
281 <literallayout class='monospaced'>
282 $ runqemu ext3
283 </literallayout>
284 This example specifies to boot a virtual machine image
285 (<filename>.vmdk</filename> file).
286 From the <filename>.vmdk</filename>,
287 <filename>runqemu</filename> determines the QEMU
288 architecture (<replaceable>MACHINE</replaceable>) to be
289 "qemux86" and the root filesystem type to be "vmdk".
290 <literallayout class='monospaced'>
291 $ runqemu /home/scott-lenovo/vm/core-image-minimal-qemux86.vmdk
292 </literallayout>
293 </para>
113 </section> 294 </section>
114</section> 295</section>
115 296
116<section id='qemu-modes'> 297<section id='qemu-running-under-a-network-file-system-nfs-server'>
117 <title>Modes</title> 298 <title>Running Under a Network File System (NFS) Server</title>
299
300 <para>
301 One method for running QEMU is to run it on an NFS server.
302 This is useful when you need to access the same file system from both
303 the build and the emulated system at the same time.
304 It is also worth noting that the system does not need root privileges
305 to run.
306 It uses a user space NFS server to avoid that.
307 This section describes how to set up for running QEMU using an NFS
308 server and then how you can start and stop the server.
309 </para>
310
311 <section id='qemu-setting-up-to-use-nfs'>
312 <title>Setting Up to Use NFS</title>
313
314 <para>
315 Once you are able to run QEMU in your environment, you can use the
316 <filename>runqemu-extract-sdk</filename> script, which is located
317 in the <filename>scripts</filename> directory along with
318 <filename>runqemu</filename> script.
319 The <filename>runqemu-extract-sdk</filename> takes a root
320 file system tarball and extracts it into a location that you
321 specify.
322 Then, when you run <filename>runqemu</filename>, you can specify
323 the location that has the file system to pass it to QEMU.
324 Here is an example that takes a file system and extracts it to
325 a directory named <filename>test-nfs</filename>:
326 <literallayout class='monospaced'>
327 runqemu-extract-sdk ./tmp/deploy/images/qemux86/core-image-sato-qemux86.tar.bz2 test-nfs
328 </literallayout>
329 Once you have extracted the file system, you can run
330 <filename>runqemu</filename> normally with the additional
331 location of the file system.
332 You can then also make changes to the files within
333 <filename>./test-nfs</filename> and see those changes appear in the
334 image in real time.
335 Here is an example using the <filename>qemux86</filename> image:
336 <literallayout class='monospaced'>
337 runqemu qemux86 ./test-nfs
338 </literallayout>
339 </para>
340 </section>
341
342 <section id='qemu-starting-and-stopping-nfs'>
343 <title>Starting and Stopping NFS</title>
118 344
345 <para>
346 You can manually start and stop the NFS share using these
347 commands:
348 <itemizedlist>
349 <listitem><para><emphasis><filename>start</filename>:</emphasis>
350 Starts the NFS share:
351 <literallayout class='monospaced'>
352 runqemu-export-rootfs start &lt;<replaceable>file-system-location</replaceable>&gt;
353 </literallayout>
354 </para></listitem>
355 <listitem><para><emphasis><filename>stop</filename>:</emphasis>
356 Stops the NFS share:
357 <literallayout class='monospaced'>
358 runqemu-export-rootfs stop &lt;<replaceable>file-system-location</replaceable>&gt;
359 </literallayout>
360 </para></listitem>
361 <listitem><para><emphasis><filename>restart</filename>:</emphasis>
362 Restarts the NFS share:
363 <literallayout class='monospaced'>
364 runqemu-export-rootfs restart &lt;<replaceable>file-system-location</replaceable>&gt;
365 </literallayout>
366 </para></listitem>
367 </itemizedlist>
368 </para>
369 </section>
119</section> 370</section>
120 371
121<section id='qemu-tips-and-tricks'> 372<section id='qemu-tips-and-tricks'>
122 <title>Tips and Tricks</title> 373 <title>Tips and Tricks</title>
123 374
375 <para>
376 The following list describes things you can do to make running QEMU
377 in the context of the Yocto Project a better experience:
378 <itemizedlist>
379 <listitem><para><emphasis>Switching Between Consoles:</emphasis>
380 When booting or running QEMU, you can switch between
381 supported consoles by using
382 Ctrl+Alt+&lt;<replaceable>number</replaceable>&gt;.
383 For example, Ctrl+Alt+3 switches you to the serial console as
384 long as that console is enabled.
385 Being able to switch consoles is helpful, for example, if the
386 main QEMU console breaks for some reason.
387 <note>
388 Usually, "2" gets you to the main console and "3" gets you
389 to the serial console.
390 </note>
391 </para></listitem>
392 <listitem><para><emphasis>Removing the Splash Screen:</emphasis>
393 You can remove the splash screen when QEMU is booting by
394 using Alt+left.
395 Removing the splash screen allows you to see what is happening
396 in the background.
397 </para></listitem>
398 <listitem><para><emphasis>Disabling the Cursor Grab:</emphasis>
399 The default QEMU integration captures the cursor within the
400 main window.
401 It does this since standard mouse devices only provide relative
402 input and not absolute coordinates.
403 You then have to break out of the grab using the "Ctrl+Alt" key
404 combination.
405 However, the Yocto Project's integration of QEMU enables the
406 wacom USB touch pad driver by default to allow input of absolute
407 coordinates.
408 This default means that the mouse can enter and leave the
409 main window without the grab taking effect leading to a better
410 user experience.
411 </para></listitem>
412 </itemizedlist>
413 </para>
124</section> 414</section>
125 415
126</chapter> 416</chapter>
diff --git a/documentation/dev-manual/dev-manual.xml b/documentation/dev-manual/dev-manual.xml
index b89e2b357e..d7e3177af8 100644
--- a/documentation/dev-manual/dev-manual.xml
+++ b/documentation/dev-manual/dev-manual.xml
@@ -106,6 +106,8 @@
106 106
107 <xi:include href="dev-manual-common-tasks.xml"/> 107 <xi:include href="dev-manual-common-tasks.xml"/>
108 108
109 <xi:include href="dev-manual-qemu.xml"/>
110
109</book> 111</book>
110<!-- 112<!--
111vim: expandtab tw=80 ts=4 113vim: expandtab tw=80 ts=4
generated by cgit v1.2.3-54-g00ecf (git 2.39.0) at 2025-10-24 20:54:20 +0000