summaryrefslogtreecommitdiffstats
path: root/documentation/dev-manual/dev-manual-qemu.xml
blob: 903028f5cf58f01f2834a1a71bafe9d2502bf787 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
[<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] >

<chapter id='dev-manual-qemu'>

<title>Using the Quick EMUlator (QEMU)</title>

<para>
    Quick EMUlator (QEMU) is an Open Source project the Yocto Project uses
    as part of its development "tool set".
    As such, the information in this chapter is limited to the
    Yocto Project integration of QEMU and not QEMU in general.
    For official information and documentation on QEMU, see the
    following references:
    <itemizedlist>
        <listitem><para><emphasis><ulink url='http://wiki.qemu.org/Main_Page'>QEMU Website</ulink>:</emphasis>
            The official website for the QEMU Open Source project.
            </para></listitem>
        <listitem><para><emphasis><ulink url='http://wiki.qemu.org/Manual'>Documentation</ulink>:</emphasis>
            The QEMU user manual.
            </para></listitem>
    </itemizedlist>
</para>

<para>
    This chapter provides an overview of the Yocto Project's integration of
    QEMU, a description of how you use QEMU and its various options, running
    under a Network File System (NFS) server, and a few tips and tricks you
    might find helpful when using QEMU.
</para>

<section id='qemu-overview'>
    <title>Overview</title>

    <para>
        Within the context of the Yocto Project, QEMU is an
        emulator and virtualization machine that allows you to run a complete
        image you have built using the Yocto Project as just another task
        on your build system.
        QEMU is useful for running and testing images and applications on
        supported Yocto Project architectures without having actual hardware.
        Among other things, the Yocto Project uses QEMU to run automated
        Quality Assurance (QA) tests on final images shipped with each
        release.
    </para>

    <para>
        QEMU is made available with the Yocto Project a number of ways.
        The easiest and recommended method for getting QEMU is to run the
        ADT installer.  For more information on how to make sure you have
        QEMU available, see the
        "<ulink url='&YOCTO_DOCS_ADT_URL;#the-qemu-emulator'>The QEMU Emulator</ulink>"
        section in the Yocto Project Application Developer's Guide.
    </para>
</section>

<section id='qemu-running-qemu'>
    <title>Running QEMU</title>

    <para>
        Running QEMU involves having your build environment set up, having the
        right artifacts available, and understanding how to use the many
        options that are available to you when you start QEMU using the
        <filename>runqemu</filename> command.
    </para>

    <section id='qemu-setting-up-the-environment'>
        <title>Setting Up the Environment</title>

        <para>
            You run QEMU in the same environment from which you run BitBake.
            This means you need to source a build environment script (i.e.
            <ulink url='&YOCTO_DOCS_REF_URL;#structure-core-script'><filename>&OE_INIT_FILE;</filename></ulink>
            or
            <ulink url='&YOCTO_DOCS_REF_URL;#structure-memres-core-script'><filename>oe-init-build-env-memres</filename></ulink>).
        </para>
    </section>

    <section id='qemu-using-the-runqemu-command'>
        <title>Using the <filename>runqemu</filename> Command</title>

        <para>
            The basic <filename>runqemu</filename> command syntax is as
            follows:
            <literallayout class='monospaced'>
     $ runqemu [<replaceable>option</replaceable> ]  [...]
            </literallayout>
            Based on what you provide on the command line,
            <filename>runqemu</filename> does a good job of figuring out what
            you are trying to do.
            For example, by default, QEMU looks for the most recently built
            image according to the timestamp when it needs to look for an
            image.
            Minimally, through the use of options, you must provide either
            a machine name, a virtual machine image
            (<filename>*.vmdk</filename>), or a kernel image
            (<filename>*.bin</filename>).
        </para>

        <para>
            Following is a description of <filename>runqemu</filename>
            options you can provide on the command line:
            <note><title>Tip</title>
                If you do provide some "illegal" option combination or perhaps
                you do not provide enough in the way of options,
                <filename>runqemu</filename> provides appropriate error
                messaging to help you correct the problem.
            </note>
            <itemizedlist>
                <listitem><para><replaceable>QEMUARCH</replaceable>:
                    The QEMU machine architecture, which must be "qemux86",
                    "qemux86_64", "qemuarm", "qemumips", "qemumipsel",
                    “qemumips64", "qemush4", "qemuppc", "qemumicroblaze",
                    or "qemuzynq".
                    </para></listitem>
                <listitem><para><filename><replaceable>VM</replaceable></filename>:
                    The virtual machine image, which must be a
                    <filename>.vmdk</filename> file.
                    Use this option when you want to boot a
                    <filename>.vmdk</filename> image.
                    The image filename you provide must contain one of the
                    following strings: "qemux86-64", "qemux86", "qemuarm",
                    "qemumips64", "qemumips", "qemuppc", or "qemush4".
                    </para></listitem>
                <listitem><para><replaceable>ROOTFS</replaceable>:
                    A root filesystem that has one of the following
                    filetype extensions: "ext2", "ext3", "ext4", "jffs2",
                    "nfs", or "btrfs".
                    If the filename you provide for this option uses “nfs”, it
                    must provide an explicit root filesystem path.
                    </para></listitem>
                <listitem><para><replaceable>KERNEL</replaceable>:
                    A kernel image, which is a <filename>.bin</filename> file.
                    When you provide a <filename>.bin</filename> file,
                    <filename>runqemu</filename> detects it and assumes the
                    file is a kernel image.
                    </para></listitem>
                <listitem><para><replaceable>MACHINE</replaceable>:
                    The architecture of the QEMU machine, which must be one
                    of the following: "qemux86",
                    "qemux86-64", "qemuarm", "qemumips", "qemumipsel",
                    “qemumips64", "qemush4", "qemuppc", "qemumicroblaze",
                    or "qemuzynq".
                    The <replaceable>MACHINE</replaceable> and
                    <replaceable>QEMUARCH</replaceable> options are basically
                    identical.
                    If you do not provide a <replaceable>MACHINE</replaceable>
                    option, <filename>runqemu</filename> tries to determine
                    it based on other options.
                    </para></listitem>
                <listitem><para><filename>ramfs</filename>:
                    Indicates you are booting an initial RAM disk (initramfs)
                    image, which means the <filename>FSTYPE</filename> is
                    <filename>cpio.gz</filename>.
                    </para></listitem>
                <listitem><para><filename>iso</filename>:
                    Indicates you are booting an ISO image, which means the
                    <filename>FSTYPE</filename> is
                    <filename>.iso</filename>.
                    </para></listitem>
                <listitem><para><filename>nographic</filename>:
                    Disables the video console, which sets the console to
                    "ttys0".
                    </para></listitem>
                <listitem><para><filename>serial</filename>:
                    Enables a serial console on
                    <filename>/dev/ttyS0</filename>.
                    </para></listitem>
                <listitem><para><filename>biosdir</filename>:
                    Establishes a custom directory for BIOS, VGA BIOS and
                    keymaps.
                    </para></listitem>
                <listitem><para><filename>biosfilename</filename>:
                    Establishes a custom BIOS name.
                    </para></listitem>
                <listitem><para><filename>qemuparams=\"<replaceable>xyz</replaceable>\"</filename>:
                    Specifies custom QEMU parameters.
                    Use this option to pass options other than the simple
                    "kvm" and "serial" options.
                    </para></listitem>
                <listitem><para><filename>bootparams=\"<replaceable>xyz</replaceable>\"</filename>:
                    Specifies custom boot parameters for the kernel.
                    </para></listitem>
                <listitem><para><filename>audio</filename>:
                    Enables audio in QEMU.
                    The <replaceable>MACHINE</replaceable> option must be
                    either "qemux86" or "qemux86-64" in order for audio to be
                    enabled.
                    Additionally, the <filename>snd_intel8x0</filename>
                    or <filename>snd_ens1370</filename> driver must be
                    installed in linux guest.
                    </para></listitem>
                <listitem><para><filename>slirp</filename>:
                    Enables "slirp" networking, which is a different way
                    of networking that does not need root access
                    but also is not as easy to use or comprehensive
                    as the default.
                    </para></listitem>
                <listitem><para id='kvm-cond'><filename>kvm</filename>:
                    Enables KVM when running "qemux86" or "qemux86-64"
                    QEMU architectures.
                    For KVM to work, all the following conditions must be met:
                    <itemizedlist>
                        <listitem><para>
                            Your <replaceable>MACHINE</replaceable> must be either
qemux86" or "qemux86-64".
                            </para></listitem>
                        <listitem><para>
                            Your build host has to have the KVM modules
                            installed, which are
                            <filename>/dev/kvm</filename>.
                            </para></listitem>
                        <listitem><para>
                            The  build host <filename>/dev/kvm</filename>
                            directory has to be both writable and readable.
                            </para></listitem>
                    </itemizedlist>
                    </para></listitem>
                <listitem><para><filename>kvm-vhost</filename>:
                    Enables KVM with VHOST support when running "qemux86" or "qemux86-64"
                    QEMU architectures.
                    For KVM with VHOST to work, the following conditions must
                    be met:
                    <itemizedlist>
                        <listitem><para>
                            <link linkend='kvm-cond'>kvm</link> option
                            conditions must be met.
                            </para></listitem>
                        <listitem><para>
                            Your build host has to have virtio net device, which
                            are <filename>/dev/vhost-net</filename>.
                            </para></listitem>
                        <listitem><para>
                            The build host <filename>/dev/vhost-net</filename>
                            directory has to be either readable or writable
                            and “slirp-enabled”.
                            </para></listitem>
                    </itemizedlist>
                    </para></listitem>
                <listitem><para><filename>publicvnc</filename>:
                    Enables a VNC server open to all hosts.
                    </para></listitem>
            </itemizedlist>
        </para>

        <para>
            For further understanding regarding option use with
            <filename>runqemu</filename>, consider some examples.
        </para>

        <para>
            This example starts QEMU with
            <replaceable>MACHINE</replaceable> set to "qemux86".
            Assuming a standard
            <link linkend='build-directory'>Build Directory</link>,
            <filename>runqemu</filename> automatically finds the
            <filename>bzImage-qemux86.bin</filename> image file and
            the
            <filename>core-image-minimal-qemux86-20140707074611.rootfs.ext3</filename>
            (assuming the current build created a
            <filename>core-image-minimal</filename> image).
            <note>
                When more than one image with the same name exists, QEMU finds
                and uses the most recently built image according to the
                timestamp.
            </note>
            <literallayout class='monospaced'>
    $ runqemu qemux86
            </literallayout>
            This example produces the exact same results as the
            previous example.
            This command, however, specifically provides the image
            and root filesystem type.
            <literallayout class='monospaced'>
     $ runqemu qemux86 core-image-minimal ext3
            </literallayout>
            This example specifies to boot an initial RAM disk image
            and to enable audio in QEMU.
            For this case, <filename>runqemu</filename> set the
            internal variable <filename>FSTYPE</filename> to
            "cpio.gz".
            Also, for audio to be enabled, an appropriate driver must
            be installed (see the previous description for the
            <filename>audio</filename> option for more information).
            <literallayout class='monospaced'>
     $ runqemu qemux86 ramfs audio
            </literallayout>
            This example does not provide enough information for
            QEMU to launch.
            While the command does provide a root filesystem type, it
            must also minimally provide a
            <replaceable>MACHINE</replaceable>,
            <replaceable>KERNEL</replaceable>, or
            <replaceable>VM</replaceable> option.
            <literallayout class='monospaced'>
     $ runqemu ext3
            </literallayout>
            This example specifies to boot a virtual machine image
            (<filename>.vmdk</filename> file).
            From the <filename>.vmdk</filename>,
            <filename>runqemu</filename> determines the QEMU
            architecture (<replaceable>MACHINE</replaceable>) to be
            "qemux86" and the root filesystem type to be "vmdk".
            <literallayout class='monospaced'>
     $ runqemu /home/scott-lenovo/vm/core-image-minimal-qemux86.vmdk
            </literallayout>
        </para>
    </section>
</section>

<section id='qemu-running-under-a-network-file-system-nfs-server'>
    <title>Running Under a Network File System (NFS) Server</title>

    <para>
        One method for running QEMU is to run it on an NFS server.
        This is useful when you need to access the same file system from both
        the build and the emulated system at the same time.
        It is also worth noting that the system does not need root privileges
        to run.
        It uses a user space NFS server to avoid that.
        This section describes how to set up for running QEMU using an NFS
        server and then how you can start and stop the server.
    </para>

    <section id='qemu-setting-up-to-use-nfs'>
        <title>Setting Up to Use NFS</title>

        <para>
            Once you are able to run QEMU in your environment, you can use the
            <filename>runqemu-extract-sdk</filename> script, which is located
            in the <filename>scripts</filename> directory along with
            <filename>runqemu</filename> script.
            The <filename>runqemu-extract-sdk</filename> takes a root
            file system tarball and extracts it into a location that you
            specify.
            Then, when you run <filename>runqemu</filename>, you can specify
            the location that has the file system to pass it to QEMU.
            Here is an example that takes a file system and extracts it to
            a directory named <filename>test-nfs</filename>:
            <literallayout class='monospaced'>
     runqemu-extract-sdk ./tmp/deploy/images/qemux86/core-image-sato-qemux86.tar.bz2 test-nfs
            </literallayout>
            Once you have extracted the file system, you can run
            <filename>runqemu</filename> normally with the additional
            location of the file system.
            You can then also make changes to the files within
            <filename>./test-nfs</filename> and see those changes appear in the
            image in real time.
            Here is an example using the <filename>qemux86</filename> image:
            <literallayout class='monospaced'>
     runqemu qemux86 ./test-nfs
            </literallayout>
        </para>
    </section>

    <section id='qemu-starting-and-stopping-nfs'>
        <title>Starting and Stopping NFS</title>

        <para>
            You can manually start and stop the NFS share using these
            commands:
            <itemizedlist>
                <listitem><para><emphasis><filename>start</filename>:</emphasis>
                    Starts the NFS share:
                    <literallayout class='monospaced'>
     runqemu-export-rootfs start <replaceable>file-system-location</replaceable>
                    </literallayout>
                    </para></listitem>
                <listitem><para><emphasis><filename>stop</filename>:</emphasis>
                    Stops the NFS share:
                    <literallayout class='monospaced'>
     runqemu-export-rootfs stop <replaceable>file-system-location</replaceable>
                    </literallayout>
                    </para></listitem>
                <listitem><para><emphasis><filename>restart</filename>:</emphasis>
                    Restarts the NFS share:
                    <literallayout class='monospaced'>
     runqemu-export-rootfs restart <replaceable>file-system-location</replaceable>
                    </literallayout>
                    </para></listitem>
            </itemizedlist>
        </para>
    </section>
</section>

<section id='qemu-tips-and-tricks'>
    <title>Tips and Tricks</title>

    <para>
        The following list describes things you can do to make running QEMU
        in the context of the Yocto Project a better experience:
        <itemizedlist>
            <listitem><para><emphasis>Switching Between Consoles:</emphasis>
                When booting or running QEMU, you can switch between
                supported consoles by using
                Ctrl+Alt+<replaceable>number</replaceable>.
                For example, Ctrl+Alt+3 switches you to the serial console as
                long as that console is enabled.
                Being able to switch consoles is helpful, for example, if the
                main QEMU console breaks for some reason.
                <note>
                    Usually, "2" gets you to the main console and "3" gets you
                    to the serial console.
                </note>
                </para></listitem>
            <listitem><para><emphasis>Removing the Splash Screen:</emphasis>
                You can remove the splash screen when QEMU is booting by
                using Alt+left.
                Removing the splash screen allows you to see what is happening
                in the background.
                </para></listitem>
            <listitem><para><emphasis>Disabling the Cursor Grab:</emphasis>
                The default QEMU integration captures the cursor within the
                main window.
                It does this since standard mouse devices only provide relative
                input and not absolute coordinates.
                You then have to break out of the grab using the "Ctrl+Alt" key
                combination.
                However, the Yocto Project's integration of QEMU enables the
                wacom USB touch pad driver by default to allow input of absolute
                coordinates.
                This default means that the mouse can enter and leave the
                main window without the grab taking effect leading to a better
                user experience.
                </para></listitem>
        </itemizedlist>
    </para>
</section>

</chapter>
<!--
vim: expandtab tw=80 ts=4
-->