summaryrefslogtreecommitdiffstats
path: root/documentation
diff options
context:
space:
mode:
authorScott Rifenbark <srifenbark@gmail.com>2017-07-18 10:15:33 -0700
committerRichard Purdie <richard.purdie@linuxfoundation.org>2017-07-22 09:19:25 +0100
commit2217d97ba9f48ded4f229981ed4ad7e846b87db0 (patch)
tree11188124b3a221a193dee1ea505a3d2eadad41bd /documentation
parent88c188f9905f30361c67d51fcf989b30ebdb8bbc (diff)
downloadpoky-2217d97ba9f48ded4f229981ed4ad7e846b87db0.tar.gz
dev-manual, ref-manual: Re-wrote QEMU section.
Fixes [YOCTO #11630] I converted the QEMU section to a procedure. Also took the tips section and created individual sections from that. Cleaned up some areas in the QEMU conceptual section in the ref-manual (From yocto-docs rev: dfd3466be605fdd7438653bf54fd0df3594a5c50) Signed-off-by: Scott Rifenbark <srifenbark@gmail.com> Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
Diffstat (limited to 'documentation')
-rw-r--r--documentation/dev-manual/dev-manual-qemu.xml618
-rw-r--r--documentation/ref-manual/usingpoky.xml12
2 files changed, 261 insertions, 369 deletions
diff --git a/documentation/dev-manual/dev-manual-qemu.xml b/documentation/dev-manual/dev-manual-qemu.xml
index a8f5c01265..ed4040ca60 100644
--- a/documentation/dev-manual/dev-manual-qemu.xml
+++ b/documentation/dev-manual/dev-manual-qemu.xml
@@ -6,425 +6,305 @@
6 6
7<title>Using the Quick EMUlator (QEMU)</title> 7<title>Using the Quick EMUlator (QEMU)</title>
8 8
9<para>
10 Quick EMUlator (QEMU) is an Open Source project the Yocto Project uses
11 as part of its development "tool set".
12 As such, the information in this chapter is limited to the
13 Yocto Project integration of QEMU and not QEMU in general.
14 For official information and documentation on QEMU, see the
15 following references:
16 <itemizedlist>
17 <listitem><para><emphasis><ulink url='http://wiki.qemu.org/Main_Page'>QEMU Website</ulink>:</emphasis>
18 The official website for the QEMU Open Source project.
19 </para></listitem>
20 <listitem><para><emphasis><ulink url='http://wiki.qemu.org/Manual'>Documentation</ulink>:</emphasis>
21 The QEMU user manual.
22 </para></listitem>
23 </itemizedlist>
24</para>
25
26<para>
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, running
29 under a Network File System (NFS) server, and a few tips and tricks you
30 might find helpful when using QEMU.
31</para>
32
33<section id='qemu-overview'>
34 <title>Overview</title>
35
36 <para>
37 Within the context of the Yocto Project, QEMU is an
38 emulator and virtualization machine that allows you to run a complete
39 image you have built using the Yocto Project as just another task
40 on your build system.
41 QEMU is useful for running and testing images and applications on
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.
46 </para>
47
48 <para> 9 <para>
49 QEMU is made available with the Yocto Project a number of ways. 10 This chapter provides procedures that show you how to use the
50 One method is to install a Software Development Kit (SDK). 11 Quick EMUlator (QEMU), which is an Open Source project the Yocto
51 For more information on how to make sure you have 12 Project uses as part of its development "tool set".
52 QEMU available, see the 13 For reference information on the Yocto Project implementation of QEMU,
53 <ulink url='&YOCTO_DOCS_SDK_URL;#sdk-intro'>Yocto Project Software Development Kit (SDK) Developer's Guide</ulink>. 14 see the
15 "<ulink url='&YOCTO_DOCS_REF_URL;#ref-quick-emulator-qemu'>Quick EMUlator (QEMU)</ulink>"
16 section in the Yocto Project Reference Manual.
54 </para> 17 </para>
55</section>
56 18
57<section id='qemu-running-qemu'> 19 <section id='qemu-running-qemu'>
58 <title>Running QEMU</title> 20 <title>Running QEMU</title>
59
60 <para>
61 Running QEMU involves having your build environment set up, having the
62 right artifacts available, and understanding how to use the many
63 options that are available to you when you start QEMU using the
64 <filename>runqemu</filename> command.
65 </para>
66
67 <section id='qemu-setting-up-the-environment'>
68 <title>Setting Up the Environment</title>
69 21
70 <para> 22 <para>
71 You run QEMU in the same environment from which you run BitBake. 23 To use QEMU, you need to have QEMU installed and initialized as
72 This means you need to source a build environment script (i.e. 24 well as have the proper artifacts (i.e. image files and root
73 <ulink url='&YOCTO_DOCS_REF_URL;#structure-core-script'><filename>&OE_INIT_FILE;</filename></ulink> 25 filesystems) available.
74 or 26 Follow these general steps to run QEMU:
75 <ulink url='&YOCTO_DOCS_REF_URL;#structure-memres-core-script'><filename>oe-init-build-env-memres</filename></ulink>). 27 <orderedlist>
76 </para> 28 <listitem><para>
77 </section> 29 <emphasis>Install QEMU:</emphasis>
78 30 See
79 <section id='qemu-using-the-runqemu-command'> 31 "<ulink url='&YOCTO_DOCS_SDK_URL;#the-qemu-emulator'>The QEMU Emulator</ulink>"
80 <title>Using the <filename>runqemu</filename> Command</title> 32 section in the Yocto Project Software Development Kit (SDK)
81 33 Developer's Guide for information on how to install
82 <para> 34 QEMU.
83 The basic <filename>runqemu</filename> command syntax is as
84 follows:
85 <literallayout class='monospaced'>
86 $ runqemu [<replaceable>option</replaceable> ] [...]
87 </literallayout>
88 Based on what you provide on the command line,
89 <filename>runqemu</filename> does a good job of figuring out what
90 you are trying to do.
91 For example, by default, QEMU looks for the most recently built
92 image according to the timestamp when it needs to look for an
93 image.
94 Minimally, through the use of options, you must provide either
95 a machine name, a virtual machine image
96 (<filename>*.vmdk</filename>), or a kernel image
97 (<filename>*.bin</filename>).
98 </para>
99
100 <para>
101 Following is a description of <filename>runqemu</filename>
102 options you can provide on the command line:
103 <note><title>Tip</title>
104 If you do provide some "illegal" option combination or perhaps
105 you do not provide enough in the way of options,
106 <filename>runqemu</filename> provides appropriate error
107 messaging to help you correct the problem.
108 </note>
109 <itemizedlist>
110 <listitem><para><replaceable>QEMUARCH</replaceable>:
111 The QEMU machine architecture, which must be "qemuarm",
112 "qemuarm64", "qemumips", "qemumips64", "qemuppc",
113 "qemux86", or "qemux86-64".
114 </para></listitem>
115 <listitem><para><filename><replaceable>VM</replaceable></filename>:
116 The virtual machine image, which must be a
117 <filename>.vmdk</filename> file.
118 Use this option when you want to boot a
119 <filename>.vmdk</filename> image.
120 The image filename you provide must contain one of the
121 following strings: "qemux86-64", "qemux86", "qemuarm",
122 "qemumips64", "qemumips", "qemuppc", or "qemush4".
123 </para></listitem>
124 <listitem><para><replaceable>ROOTFS</replaceable>:
125 A root filesystem that has one of the following
126 filetype extensions: "ext2", "ext3", "ext4", "jffs2",
127 "nfs", or "btrfs".
128 If the filename you provide for this option uses “nfs”, it
129 must provide an explicit root filesystem path.
130 </para></listitem>
131 <listitem><para><replaceable>KERNEL</replaceable>:
132 A kernel image, which is a <filename>.bin</filename> file.
133 When you provide a <filename>.bin</filename> file,
134 <filename>runqemu</filename> detects it and assumes the
135 file is a kernel image.
136 </para></listitem> 35 </para></listitem>
137 <listitem><para><replaceable>MACHINE</replaceable>: 36 <listitem><para>
138 The architecture of the QEMU machine, which must be one 37 <emphasis>Setting Up the Environment:</emphasis>
139 of the following: "qemux86", 38 How you set up the QEMU environment depends on how you
140 "qemux86", "qemux86-64", "qemuarm", "qemuarm64", 39 installed QEMU:
141 "qemumips", “qemumips64", or "qemuppc".
142 The <replaceable>MACHINE</replaceable> and
143 <replaceable>QEMUARCH</replaceable> options are basically
144 identical.
145 If you do not provide a <replaceable>MACHINE</replaceable>
146 option, <filename>runqemu</filename> tries to determine
147 it based on other options.
148 </para></listitem>
149 <listitem><para><filename>ramfs</filename>:
150 Indicates you are booting an initial RAM disk (initramfs)
151 image, which means the <filename>FSTYPE</filename> is
152 <filename>cpio.gz</filename>.
153 </para></listitem>
154 <listitem><para><filename>iso</filename>:
155 Indicates you are booting an ISO image, which means the
156 <filename>FSTYPE</filename> is
157 <filename>.iso</filename>.
158 </para></listitem>
159 <listitem><para><filename>nographic</filename>:
160 Disables the video console, which sets the console to
161 "ttys0".
162 </para></listitem>
163 <listitem><para><filename>serial</filename>:
164 Enables a serial console on
165 <filename>/dev/ttyS0</filename>.
166 </para></listitem>
167 <listitem><para><filename>biosdir</filename>:
168 Establishes a custom directory for BIOS, VGA BIOS and
169 keymaps.
170 </para></listitem>
171 <listitem><para><filename>biosfilename</filename>:
172 Establishes a custom BIOS name.
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 id='kvm-cond'><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> 40 <itemizedlist>
202 <listitem><para> 41 <listitem><para>
203 Your <replaceable>MACHINE</replaceable> must be either 42 If you cloned the <filename>poky</filename>
204qemux86" or "qemux86-64". 43 repository or you downloaded and unpacked a
44 Yocto Project release tarball, you can source
45 the build environment script (i.e.
46 <ulink url='&YOCTO_DOCS_REF_URL;#structure-core-script'><filename>&OE_INIT_FILE;</filename></ulink>
47 or
48 <ulink url='&YOCTO_DOCS_REF_URL;#structure-memres-core-script'><filename>oe-init-build-env-memres</filename></ulink>):
49 <literallayout class='monospaced'>
50 $ cd ~/poky
51 $ source oe-init-build-env
52 </literallayout>
205 </para></listitem> 53 </para></listitem>
206 <listitem><para> 54 <listitem><para>
207 Your build host has to have the KVM modules 55 If you installed a cross-toolchain, you can
208 installed, which are 56 run the script that initializes the toolchain.
209 <filename>/dev/kvm</filename>. 57 For example, the following commands run the
58 initialization script from the default
59 <filename>poky_sdk</filename> directory:
60 <literallayout class='monospaced'>
61 . ~/poky_sdk/environment-setup-core2-64-poky-linux
62 </literallayout>
210 </para></listitem> 63 </para></listitem>
64 </itemizedlist>
65 </para></listitem>
66 <listitem><para>
67 <emphasis>Ensure the Artifacts are in Place:</emphasis>
68 You need to be sure you have a pre-built kernel that
69 will boot in QEMU.
70 You also need the target root filesystem for your target
71 machine’s architecture:
72 <itemizedlist>
211 <listitem><para> 73 <listitem><para>
212 The build host <filename>/dev/kvm</filename> 74 If you have previously built an image for QEMU
213 directory has to be both writable and readable. 75 (e.g. <filename>qemux86</filename>,
76 <filename>qemuarm</filename>, and so forth),
77 then the artifacts are in place in your
78 <ulink url='&YOCTO_DOCS_REF_URL;#build-directory'>Build Directory</ulink>.
214 </para></listitem> 79 </para></listitem>
215 </itemizedlist> 80 <listitem><para>
81 If you have not built an image, you can go to the
82 <ulink url='&YOCTO_MACHINES_DL_URL;'>machines/qemu</ulink>
83 area and download a pre-built image that matches
84 your architecture and can be run on QEMU.
85 </para></listitem>
86 </itemizedlist></para>
87
88 <para>See the
89 "<ulink url='&YOCTO_DOCS_SDK_URL;#sdk-extracting-the-root-filesystem'>Extracting the Root Filesystem</ulink>"
90 section in the Yocto Project Software Development Kit (SDK)
91 Developer's Guide for information on how to extract a
92 root filesystem.
216 </para></listitem> 93 </para></listitem>
217 <listitem><para><filename>kvm-vhost</filename>: 94 <listitem><para>
218 Enables KVM with VHOST support when running "qemux86" or "qemux86-64" 95 <emphasis>Run QEMU:</emphasis>
219 QEMU architectures. 96 The basic <filename>runqemu</filename> command syntax is as
220 For KVM with VHOST to work, the following conditions must 97 follows:
221 be met: 98 <literallayout class='monospaced'>
99 $ runqemu [<replaceable>option</replaceable> ] [...]
100 </literallayout>
101 Based on what you provide on the command line,
102 <filename>runqemu</filename> does a good job of figuring
103 out what you are trying to do.
104 For example, by default, QEMU looks for the most recently
105 built image according to the timestamp when it needs to
106 look for an image.
107 Minimally, through the use of options, you must provide
108 either a machine name, a virtual machine image
109 (<filename>*.vmdk</filename>), or a kernel image
110 (<filename>*.bin</filename>).</para>
111
112 <para>Here are some additional examples to help illustrate
113 further QEMU:
222 <itemizedlist> 114 <itemizedlist>
223 <listitem><para> 115 <listitem><para>
224 <link linkend='kvm-cond'>kvm</link> option 116 This example starts QEMU with
225 conditions must be met. 117 <replaceable>MACHINE</replaceable> set to "qemux86".
118 Assuming a standard
119 <ulink url='&YOCTO_DOCS_REF_URL;#build-directory'>Build Directory</ulink>,
120 <filename>runqemu</filename> automatically finds the
121 <filename>bzImage-qemux86.bin</filename> image file and
122 the
123 <filename>core-image-minimal-qemux86-20140707074611.rootfs.ext3</filename>
124 (assuming the current build created a
125 <filename>core-image-minimal</filename> image).
126 <note>
127 When more than one image with the same name exists, QEMU finds
128 and uses the most recently built image according to the
129 timestamp.
130 </note>
131 <literallayout class='monospaced'>
132 $ runqemu qemux86
133 </literallayout>
226 </para></listitem> 134 </para></listitem>
227 <listitem><para> 135 <listitem><para>
228 Your build host has to have virtio net device, which 136 This example produces the exact same results as the
229 are <filename>/dev/vhost-net</filename>. 137 previous example.
138 This command, however, specifically provides the image
139 and root filesystem type.
140 <literallayout class='monospaced'>
141 $ runqemu qemux86 core-image-minimal ext3
142 </literallayout>
230 </para></listitem> 143 </para></listitem>
231 <listitem><para> 144 <listitem><para>
232 The build host <filename>/dev/vhost-net</filename> 145 This example specifies to boot an initial RAM disk image
233 directory has to be either readable or writable 146 and to enable audio in QEMU.
234 and “slirp-enabled”. 147 For this case, <filename>runqemu</filename> set the
148 internal variable <filename>FSTYPE</filename> to
149 "cpio.gz".
150 Also, for audio to be enabled, an appropriate driver must
151 be installed (see the previous description for the
152 <filename>audio</filename> option for more information).
153 <literallayout class='monospaced'>
154 $ runqemu qemux86 ramfs audio
155 </literallayout>
156 </para></listitem>
157 <listitem><para>
158 This example does not provide enough information for
159 QEMU to launch.
160 While the command does provide a root filesystem type, it
161 must also minimally provide a
162 <replaceable>MACHINE</replaceable>,
163 <replaceable>KERNEL</replaceable>, or
164 <replaceable>VM</replaceable> option.
165 <literallayout class='monospaced'>
166 $ runqemu ext3
167 </literallayout>
168 </para></listitem>
169 <listitem><para>
170 This example specifies to boot a virtual machine image
171 (<filename>.vmdk</filename> file).
172 From the <filename>.vmdk</filename>,
173 <filename>runqemu</filename> determines the QEMU
174 architecture (<replaceable>MACHINE</replaceable>) to be
175 "qemux86" and the root filesystem type to be "vmdk".
176 <literallayout class='monospaced'>
177 $ runqemu /home/scott-lenovo/vm/core-image-minimal-qemux86.vmdk
178 </literallayout>
235 </para></listitem> 179 </para></listitem>
236 </itemizedlist> 180 </itemizedlist>
237 </para></listitem> 181 </para></listitem>
238 <listitem><para><filename>publicvnc</filename>: 182 </orderedlist>
239 Enables a VNC server open to all hosts.
240 </para></listitem>
241 </itemizedlist>
242 </para> 183 </para>
184 </section>
243 185
244 <para> 186 <section id='switching-between-consoles'>
245 For further understanding regarding option use with 187 <title>Switching Between Consoles</title>
246 <filename>runqemu</filename>, consider some examples.
247 </para>
248 188
249 <para> 189 <para>
250 This example starts QEMU with 190 When booting or running QEMU, you can switch between
251 <replaceable>MACHINE</replaceable> set to "qemux86". 191 supported consoles by using
252 Assuming a standard 192 Ctrl+Alt+<replaceable>number</replaceable>.
253 <ulink url='&YOCTO_DOCS_REF_URL;#build-directory'>Build Directory</ulink>, 193 For example, Ctrl+Alt+3 switches you to the serial console
254 <filename>runqemu</filename> automatically finds the 194 as long as that console is enabled.
255 <filename>bzImage-qemux86.bin</filename> image file and 195 Being able to switch consoles is helpful, for example, if
256 the 196 the main QEMU console breaks for some reason.
257 <filename>core-image-minimal-qemux86-20140707074611.rootfs.ext3</filename>
258 (assuming the current build created a
259 <filename>core-image-minimal</filename> image).
260 <note> 197 <note>
261 When more than one image with the same name exists, QEMU finds 198 Usually, "2" gets you to the main console and "3"
262 and uses the most recently built image according to the 199 gets you to the serial console.
263 timestamp.
264 </note> 200 </note>
265 <literallayout class='monospaced'>
266 $ runqemu qemux86
267 </literallayout>
268 This example produces the exact same results as the
269 previous example.
270 This command, however, specifically provides the image
271 and root filesystem type.
272 <literallayout class='monospaced'>
273 $ runqemu qemux86 core-image-minimal ext3
274 </literallayout>
275 This example specifies to boot an initial RAM disk image
276 and to enable audio in QEMU.
277 For this case, <filename>runqemu</filename> set the
278 internal variable <filename>FSTYPE</filename> to
279 "cpio.gz".
280 Also, for audio to be enabled, an appropriate driver must
281 be installed (see the previous description for the
282 <filename>audio</filename> option for more information).
283 <literallayout class='monospaced'>
284 $ runqemu qemux86 ramfs audio
285 </literallayout>
286 This example does not provide enough information for
287 QEMU to launch.
288 While the command does provide a root filesystem type, it
289 must also minimally provide a
290 <replaceable>MACHINE</replaceable>,
291 <replaceable>KERNEL</replaceable>, or
292 <replaceable>VM</replaceable> option.
293 <literallayout class='monospaced'>
294 $ runqemu ext3
295 </literallayout>
296 This example specifies to boot a virtual machine image
297 (<filename>.vmdk</filename> file).
298 From the <filename>.vmdk</filename>,
299 <filename>runqemu</filename> determines the QEMU
300 architecture (<replaceable>MACHINE</replaceable>) to be
301 "qemux86" and the root filesystem type to be "vmdk".
302 <literallayout class='monospaced'>
303 $ runqemu /home/scott-lenovo/vm/core-image-minimal-qemux86.vmdk
304 </literallayout>
305 </para> 201 </para>
306 </section> 202 </section>
307</section>
308 203
309<section id='qemu-running-under-a-network-file-system-nfs-server'> 204 <section id='removing-the-splash-screen'>
310 <title>Running Under a Network File System (NFS) Server</title> 205 <title>Removing the Splash Screen</title>
311 206
312 <para> 207 <para>
313 One method for running QEMU is to run it on an NFS server. 208 You can remove the splash screen when QEMU is booting by
314 This is useful when you need to access the same file system from both 209 using Alt+left.
315 the build and the emulated system at the same time. 210 Removing the splash screen allows you to see what is
316 It is also worth noting that the system does not need root privileges 211 happening in the background.
317 to run. 212 </para>
318 It uses a user space NFS server to avoid that. 213 </section>
319 This section describes how to set up for running QEMU using an NFS
320 server and then how you can start and stop the server.
321 </para>
322 214
323 <section id='qemu-setting-up-to-use-nfs'> 215 <section id='disabling-the-cursor-grab'>
324 <title>Setting Up to Use NFS</title> 216 <title>Disabling the Cursor Grab</title>
325 217
326 <para> 218 <para>
327 Once you are able to run QEMU in your environment, you can use the 219 The default QEMU integration captures the cursor within the
328 <filename>runqemu-extract-sdk</filename> script, which is located 220 main window.
329 in the <filename>scripts</filename> directory along with 221 It does this since standard mouse devices only provide
330 <filename>runqemu</filename> script. 222 relative input and not absolute coordinates.
331 The <filename>runqemu-extract-sdk</filename> takes a root 223 You then have to break out of the grab using the "Ctrl+Alt"
332 file system tarball and extracts it into a location that you 224 key combination.
333 specify. 225 However, the Yocto Project's integration of QEMU enables
334 Then, when you run <filename>runqemu</filename>, you can specify 226 the wacom USB touch pad driver by default to allow input
335 the location that has the file system to pass it to QEMU. 227 of absolute coordinates.
336 Here is an example that takes a file system and extracts it to 228 This default means that the mouse can enter and leave the
337 a directory named <filename>test-nfs</filename>: 229 main window without the grab taking effect leading to a
338 <literallayout class='monospaced'> 230 better user experience.
339 runqemu-extract-sdk ./tmp/deploy/images/qemux86/core-image-sato-qemux86.tar.bz2 test-nfs
340 </literallayout>
341 Once you have extracted the file system, you can run
342 <filename>runqemu</filename> normally with the additional
343 location of the file system.
344 You can then also make changes to the files within
345 <filename>./test-nfs</filename> and see those changes appear in the
346 image in real time.
347 Here is an example using the <filename>qemux86</filename> image:
348 <literallayout class='monospaced'>
349 runqemu qemux86 ./test-nfs
350 </literallayout>
351 </para> 231 </para>
352 </section> 232 </section>
353 233
354 <section id='qemu-starting-and-stopping-nfs'> 234 <section id='qemu-running-under-a-network-file-system-nfs-server'>
355 <title>Starting and Stopping NFS</title> 235 <title>Running Under a Network File System (NFS) Server</title>
356 236
357 <para> 237 <para>
358 You can manually start and stop the NFS share using these 238 One method for running QEMU is to run it on an NFS server.
359 commands: 239 This is useful when you need to access the same file system
360 <itemizedlist> 240 from both the build and the emulated system at the same time.
361 <listitem><para><emphasis><filename>start</filename>:</emphasis> 241 It is also worth noting that the system does not need root
362 Starts the NFS share: 242 privileges to run.
243 It uses a user space NFS server to avoid that.
244 Follow these steps to set up for running QEMU using an NFS
245 server.
246 <orderedlist>
247 <listitem><para>
248 <emphasis>Extract a Root Filesystem:</emphasis>
249 Once you are able to run QEMU in your environment, you can
250 use the <filename>runqemu-extract-sdk</filename> script,
251 which is located in the <filename>scripts</filename>
252 directory along with the <filename>runqemu</filename>
253 script.</para>
254
255 <para>The <filename>runqemu-extract-sdk</filename> takes a
256 root filesystem tarball and extracts it into a location
257 that you specify.
258 Here is an example that takes a file system and
259 extracts it to a directory named
260 <filename>test-nfs</filename>:
363 <literallayout class='monospaced'> 261 <literallayout class='monospaced'>
364 runqemu-export-rootfs start <replaceable>file-system-location</replaceable> 262 runqemu-extract-sdk ./tmp/deploy/images/qemux86/core-image-sato-qemux86.tar.bz2 test-nfs
365 </literallayout> 263 </literallayout>
366 </para></listitem> 264 </para></listitem>
367 <listitem><para><emphasis><filename>stop</filename>:</emphasis> 265 <listitem><para>
368 Stops the NFS share: 266 <emphasis>Start QEMU:</emphasis>
267 Once you have extracted the file system, you can run
268 <filename>runqemu</filename> normally with the additional
269 location of the file system.
270 You can then also make changes to the files within
271 <filename>./test-nfs</filename> and see those changes
272 appear in the image in real time.
273 Here is an example using the <filename>qemux86</filename>
274 image:
369 <literallayout class='monospaced'> 275 <literallayout class='monospaced'>
370 runqemu-export-rootfs stop <replaceable>file-system-location</replaceable> 276 runqemu qemux86 ./test-nfs
371 </literallayout> 277 </literallayout>
372 </para></listitem> 278 </para></listitem>
373 <listitem><para><emphasis><filename>restart</filename>:</emphasis> 279 </orderedlist>
374 Restarts the NFS share: 280 <note>
375 <literallayout class='monospaced'> 281 <para>
282 Should you need to start, stop, or restart the NFS share,
283 you can use the following commands:
284 <itemizedlist>
285 <listitem><para>
286 The following command starts the NFS share:
287 <literallayout class='monospaced'>
288 runqemu-export-rootfs start <replaceable>file-system-location</replaceable>
289 </literallayout>
290 </para></listitem>
291 <listitem><para>
292 The following command stops the NFS share:
293 <literallayout class='monospaced'>
294 runqemu-export-rootfs stop <replaceable>file-system-location</replaceable>
295 </literallayout>
296 </para></listitem>
297 <listitem><para>
298 The following command restarts the NFS share:
299 <literallayout class='monospaced'>
376 runqemu-export-rootfs restart <replaceable>file-system-location</replaceable> 300 runqemu-export-rootfs restart <replaceable>file-system-location</replaceable>
377 </literallayout> 301 </literallayout>
378 </para></listitem> 302 </para></listitem>
379 </itemizedlist> 303 </itemizedlist>
304 </para>
305 </note>
380 </para> 306 </para>
381 </section> 307 </section>
382</section>
383
384<section id='qemu-tips-and-tricks'>
385 <title>Tips and Tricks</title>
386
387 <para>
388 The following list describes things you can do to make running QEMU
389 in the context of the Yocto Project a better experience:
390 <itemizedlist>
391 <listitem><para><emphasis>Switching Between Consoles:</emphasis>
392 When booting or running QEMU, you can switch between
393 supported consoles by using
394 Ctrl+Alt+<replaceable>number</replaceable>.
395 For example, Ctrl+Alt+3 switches you to the serial console as
396 long as that console is enabled.
397 Being able to switch consoles is helpful, for example, if the
398 main QEMU console breaks for some reason.
399 <note>
400 Usually, "2" gets you to the main console and "3" gets you
401 to the serial console.
402 </note>
403 </para></listitem>
404 <listitem><para><emphasis>Removing the Splash Screen:</emphasis>
405 You can remove the splash screen when QEMU is booting by
406 using Alt+left.
407 Removing the splash screen allows you to see what is happening
408 in the background.
409 </para></listitem>
410 <listitem><para><emphasis>Disabling the Cursor Grab:</emphasis>
411 The default QEMU integration captures the cursor within the
412 main window.
413 It does this since standard mouse devices only provide relative
414 input and not absolute coordinates.
415 You then have to break out of the grab using the "Ctrl+Alt" key
416 combination.
417 However, the Yocto Project's integration of QEMU enables the
418 wacom USB touch pad driver by default to allow input of absolute
419 coordinates.
420 This default means that the mouse can enter and leave the
421 main window without the grab taking effect leading to a better
422 user experience.
423 </para></listitem>
424 </itemizedlist>
425 </para>
426</section>
427
428</chapter> 308</chapter>
429<!-- 309<!--
430vim: expandtab tw=80 ts=4 310vim: expandtab tw=80 ts=4
diff --git a/documentation/ref-manual/usingpoky.xml b/documentation/ref-manual/usingpoky.xml
index 5517a7541c..2f5316d54b 100644
--- a/documentation/ref-manual/usingpoky.xml
+++ b/documentation/ref-manual/usingpoky.xml
@@ -1056,6 +1056,18 @@
1056 The Yocto Project uses an implementation of the Quick EMUlator (QEMU) 1056 The Yocto Project uses an implementation of the Quick EMUlator (QEMU)
1057 Open Source project as part of the Yocto Project development "tool 1057 Open Source project as part of the Yocto Project development "tool
1058 set". 1058 set".
1059 </para>
1060
1061 <para>
1062 Within the context of the Yocto Project, QEMU is an
1063 emulator and virtualization machine that allows you to run a complete
1064 image you have built using the Yocto Project as just another task
1065 on your build system.
1066 QEMU is useful for running and testing images and applications on
1067 supported Yocto Project architectures without having actual hardware.
1068 Among other things, the Yocto Project uses QEMU to run automated
1069 Quality Assurance (QA) tests on final images shipped with each
1070 release.
1059 <note> 1071 <note>
1060 This implementation is not the same as QEMU in general. 1072 This implementation is not the same as QEMU in general.
1061 </note> 1073 </note>
generated by cgit v1.2.3-54-g00ecf (git 2.39.0) at 2026-01-31 21:52:04 +0000