summaryrefslogtreecommitdiffstats
path: root/documentation/dev-manual/dev-manual-qemu.rst
diff options
context:
space:
mode:
authorNicolas Dechesne <nicolas.dechesne@linaro.org>2020-06-26 19:10:51 +0200
committerRichard Purdie <richard.purdie@linuxfoundation.org>2020-09-17 10:09:33 +0100
commit9bd69b1f1d71a9692189beeac75af9dfbad816cc (patch)
tree305347fca899074aed5610e0e82eaec180bf630c /documentation/dev-manual/dev-manual-qemu.rst
parentc40a8d5904c29046f1cbbeb998e6cd7c24f9b206 (diff)
downloadpoky-9bd69b1f1d71a9692189beeac75af9dfbad816cc.tar.gz
sphinx: initial sphinx support
This commit is autogenerated pandoc to generate an inital set of reST files based on DocBook XML files. A .rst file is generated for each .xml files in all manuals with this command: cd <manual> for i in *.xml; do \ pandoc -f docbook -t rst --shift-heading-level-by=-1 \ $i -o $(basename $i .xml).rst \ done The conversion was done with: pandoc 2.9.2.1-91 (Arch Linux). Also created an initial top level index file for each document, and added all 'books' to the top leve index.rst file. The YP manuals layout is organized as: Book Chapter Section Section Section Sphinx uses section headers to create the document structure. ReStructuredText defines sections headers like that: To break longer text up into sections, you use section headers. These are a single line of text (one or more words) with adornment: an underline alone, or an underline and an overline together, in dashes "-----", equals "======", tildes "~~~~~~" or any of the non-alphanumeric characters = - ` : ' " ~ ^ _ * + # < > that you feel comfortable with. An underline-only adornment is distinct from an overline-and-underline adornment using the same character. The underline/overline must be at least as long as the title text. Be consistent, since all sections marked with the same adornment style are deemed to be at the same level: Let's define the following convention when converting from Docbook: Book => overline === (Title) Chapter => overline *** (1.) Section => ==== (1.1) Section => ---- (1.1.1) Section => ~~~~ (1.1.1.1) Section => ^^^^ (1.1.1.1.1) During the conversion with pandoc, we used --shift-heading-level=-1 to convert most of DocBook headings automatically. However with this setting, the Chapter header was removed, so I added it back manually. Without this setting all headings were off by one, which was more difficult to manually fix. At least with this change, we now have the same TOC with Sphinx and DocBook. (From yocto-docs rev: 3c73d64a476d4423ee4c6808c685fa94d88d7df8) Signed-off-by: Nicolas Dechesne <nicolas.dechesne@linaro.org> Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
Diffstat (limited to 'documentation/dev-manual/dev-manual-qemu.rst')
-rw-r--r--documentation/dev-manual/dev-manual-qemu.rst429
1 files changed, 429 insertions, 0 deletions
diff --git a/documentation/dev-manual/dev-manual-qemu.rst b/documentation/dev-manual/dev-manual-qemu.rst
new file mode 100644
index 0000000000..b3cd69d805
--- /dev/null
+++ b/documentation/dev-manual/dev-manual-qemu.rst
@@ -0,0 +1,429 @@
1*******************************
2Using the Quick EMUlator (QEMU)
3*******************************
4
5The Yocto Project uses an implementation of the Quick EMUlator (QEMU)
6Open Source project as part of the Yocto Project development "tool set".
7This chapter provides both procedures that show you how to use the Quick
8EMUlator (QEMU) and other QEMU information helpful for development
9purposes.
10
11.. _qemu-dev-overview:
12
13Overview
14========
15
16Within the context of the Yocto Project, QEMU is an emulator and
17virtualization machine that allows you to run a complete image you have
18built using the Yocto Project as just another task on your build system.
19QEMU is useful for running and testing images and applications on
20supported Yocto Project architectures without having actual hardware.
21Among other things, the Yocto Project uses QEMU to run automated Quality
22Assurance (QA) tests on final images shipped with each release.
23
24.. note::
25
26 This implementation is not the same as QEMU in general.
27
28This section provides a brief reference for the Yocto Project
29implementation of QEMU.
30
31For official information and documentation on QEMU in general, see the
32following references:
33
34- `QEMU Website <http://wiki.qemu.org/Main_Page>`__\ *:* The official
35 website for the QEMU Open Source project.
36
37- `Documentation <http://wiki.qemu.org/Manual>`__\ *:* The QEMU user
38 manual.
39
40.. _qemu-running-qemu:
41
42Running QEMU
43============
44
45To use QEMU, you need to have QEMU installed and initialized as well as
46have the proper artifacts (i.e. image files and root filesystems)
47available. Follow these general steps to run QEMU:
48
491. *Install QEMU:* QEMU is made available with the Yocto Project a
50 number of ways. One method is to install a Software Development Kit
51 (SDK). See "`The QEMU
52 Emulator <&YOCTO_DOCS_SDK_URL;#the-qemu-emulator>`__" section in the
53 Yocto Project Application Development and the Extensible Software
54 Development Kit (eSDK) manual for information on how to install QEMU.
55
562. *Setting Up the Environment:* How you set up the QEMU environment
57 depends on how you installed QEMU:
58
59 - If you cloned the ``poky`` repository or you downloaded and
60 unpacked a Yocto Project release tarball, you can source the build
61 environment script (i.e.
62 ````` <&YOCTO_DOCS_REF_URL;#structure-core-script>`__): $ cd
63 ~/poky $ source oe-init-build-env
64
65 - If you installed a cross-toolchain, you can run the script that
66 initializes the toolchain. For example, the following commands run
67 the initialization script from the default ``poky_sdk`` directory:
68 . ~/poky_sdk/environment-setup-core2-64-poky-linux
69
703. *Ensure the Artifacts are in Place:* You need to be sure you have a
71 pre-built kernel that will boot in QEMU. You also need the target
72 root filesystem for your target machine’s architecture:
73
74 - If you have previously built an image for QEMU (e.g. ``qemux86``,
75 ``qemuarm``, and so forth), then the artifacts are in place in
76 your `Build Directory <&YOCTO_DOCS_REF_URL;#build-directory>`__.
77
78 - If you have not built an image, you can go to the
79 `machines/qemu <&YOCTO_MACHINES_DL_URL;>`__ area and download a
80 pre-built image that matches your architecture and can be run on
81 QEMU.
82
83 See the "`Extracting the Root
84 Filesystem <&YOCTO_DOCS_SDK_URL;#sdk-extracting-the-root-filesystem>`__"
85 section in the Yocto Project Application Development and the
86 Extensible Software Development Kit (eSDK) manual for information on
87 how to extract a root filesystem.
88
894. *Run QEMU:* The basic ``runqemu`` command syntax is as follows: $
90 runqemu [option ] [...] Based on what you provide on the command
91 line, ``runqemu`` does a good job of figuring out what you are trying
92 to do. For example, by default, QEMU looks for the most recently
93 built image according to the timestamp when it needs to look for an
94 image. Minimally, through the use of options, you must provide either
95 a machine name, a virtual machine image (``*wic.vmdk``), or a kernel
96 image (``*.bin``).
97
98 Here are some additional examples to help illustrate further QEMU:
99
100 - This example starts QEMU with MACHINE set to "qemux86-64".
101 Assuming a standard `Build
102 Directory <&YOCTO_DOCS_REF_URL;#build-directory>`__, ``runqemu``
103 automatically finds the ``bzImage-qemux86-64.bin`` image file and
104 the ``core-image-minimal-qemux86-64-20200218002850.rootfs.ext4``
105 (assuming the current build created a ``core-image-minimal``
106 image).
107
108 .. note::
109
110 When more than one image with the same name exists, QEMU finds
111 and uses the most recently built image according to the
112 timestamp.
113
114 $ runqemu qemux86-64
115
116 - This example produces the exact same results as the previous
117 example. This command, however, specifically provides the image
118 and root filesystem type. $ runqemu qemux86-64 core-image-minimal
119 ext4
120
121 - This example specifies to boot an initial RAM disk image and to
122 enable audio in QEMU. For this case, ``runqemu`` set the internal
123 variable ``FSTYPE`` to "cpio.gz". Also, for audio to be enabled,
124 an appropriate driver must be installed (see the previous
125 description for the ``audio`` option for more information). $
126 runqemu qemux86-64 ramfs audio
127
128 - This example does not provide enough information for QEMU to
129 launch. While the command does provide a root filesystem type, it
130 must also minimally provide a MACHINE, KERNEL, or VM option. $
131 runqemu ext4
132
133 - This example specifies to boot a virtual machine image
134 (``.wic.vmdk`` file). From the ``.wic.vmdk``, ``runqemu``
135 determines the QEMU architecture (MACHINE) to be "qemux86-64" and
136 the root filesystem type to be "vmdk". $ runqemu
137 /home/scott-lenovo/vm/core-image-minimal-qemux86-64.wic.vmdk
138
139Switching Between Consoles
140==========================
141
142When booting or running QEMU, you can switch between supported consoles
143by using Ctrl+Alt+number. For example, Ctrl+Alt+3 switches you to the
144serial console as long as that console is enabled. Being able to switch
145consoles is helpful, for example, if the main QEMU console breaks for
146some reason.
147
148.. note::
149
150 Usually, "2" gets you to the main console and "3" gets you to the
151 serial console.
152
153Removing the Splash Screen
154==========================
155
156You can remove the splash screen when QEMU is booting by using Alt+left.
157Removing the splash screen allows you to see what is happening in the
158background.
159
160Disabling the Cursor Grab
161=========================
162
163The default QEMU integration captures the cursor within the main window.
164It does this since standard mouse devices only provide relative input
165and not absolute coordinates. You then have to break out of the grab
166using the "Ctrl+Alt" key combination. However, the Yocto Project's
167integration of QEMU enables the wacom USB touch pad driver by default to
168allow input of absolute coordinates. This default means that the mouse
169can enter and leave the main window without the grab taking effect
170leading to a better user experience.
171
172.. _qemu-running-under-a-network-file-system-nfs-server:
173
174Running Under a Network File System (NFS) Server
175================================================
176
177One method for running QEMU is to run it on an NFS server. This is
178useful when you need to access the same file system from both the build
179and the emulated system at the same time. It is also worth noting that
180the system does not need root privileges to run. It uses a user space
181NFS server to avoid that. Follow these steps to set up for running QEMU
182using an NFS server.
183
1841. *Extract a Root Filesystem:* Once you are able to run QEMU in your
185 environment, you can use the ``runqemu-extract-sdk`` script, which is
186 located in the ``scripts`` directory along with the ``runqemu``
187 script.
188
189 The ``runqemu-extract-sdk`` takes a root filesystem tarball and
190 extracts it into a location that you specify. Here is an example that
191 takes a file system and extracts it to a directory named
192 ``test-nfs``: runqemu-extract-sdk
193 ./tmp/deploy/images/qemux86-64/core-image-sato-qemux86-64.tar.bz2
194 test-nfs
195
1962. *Start QEMU:* Once you have extracted the file system, you can run
197 ``runqemu`` normally with the additional location of the file system.
198 You can then also make changes to the files within ``./test-nfs`` and
199 see those changes appear in the image in real time. Here is an
200 example using the ``qemux86`` image: runqemu qemux86-64 ./test-nfs
201
202.. note::
203
204 Should you need to start, stop, or restart the NFS share, you can use
205 the following commands:
206
207 - The following command starts the NFS share: runqemu-export-rootfs
208 start file-system-location
209
210 - The following command stops the NFS share: runqemu-export-rootfs
211 stop file-system-location
212
213 - The following command restarts the NFS share:
214 runqemu-export-rootfs restart file-system-location
215
216.. _qemu-kvm-cpu-compatibility:
217
218QEMU CPU Compatibility Under KVM
219================================
220
221By default, the QEMU build compiles for and targets 64-bit and x86 Intel
222Core2 Duo processors and 32-bit x86 Intel Pentium II processors. QEMU
223builds for and targets these CPU types because they display a broad
224range of CPU feature compatibility with many commonly used CPUs.
225
226Despite this broad range of compatibility, the CPUs could support a
227feature that your host CPU does not support. Although this situation is
228not a problem when QEMU uses software emulation of the feature, it can
229be a problem when QEMU is running with KVM enabled. Specifically,
230software compiled with a certain CPU feature crashes when run on a CPU
231under KVM that does not support that feature. To work around this
232problem, you can override QEMU's runtime CPU setting by changing the
233``QB_CPU_KVM`` variable in ``qemuboot.conf`` in the `Build
234Directory's <&YOCTO_DOCS_REF_URL;#build-directory>`__ ``deploy/image``
235directory. This setting specifies a ``-cpu`` option passed into QEMU in
236the ``runqemu`` script. Running ``qemu -cpu help`` returns a list of
237available supported CPU types.
238
239.. _qemu-dev-performance:
240
241QEMU Performance
242================
243
244Using QEMU to emulate your hardware can result in speed issues depending
245on the target and host architecture mix. For example, using the
246``qemux86`` image in the emulator on an Intel-based 32-bit (x86) host
247machine is fast because the target and host architectures match. On the
248other hand, using the ``qemuarm`` image on the same Intel-based host can
249be slower. But, you still achieve faithful emulation of ARM-specific
250issues.
251
252To speed things up, the QEMU images support using ``distcc`` to call a
253cross-compiler outside the emulated system. If you used ``runqemu`` to
254start QEMU, and the ``distccd`` application is present on the host
255system, any BitBake cross-compiling toolchain available from the build
256system is automatically used from within QEMU simply by calling
257``distcc``. You can accomplish this by defining the cross-compiler
258variable (e.g. ``export CC="distcc"``). Alternatively, if you are using
259a suitable SDK image or the appropriate stand-alone toolchain is
260present, the toolchain is also automatically used.
261
262.. note::
263
264 Several mechanisms exist that let you connect to the system running
265 on the QEMU emulator:
266
267 - QEMU provides a framebuffer interface that makes standard consoles
268 available.
269
270 - Generally, headless embedded devices have a serial port. If so,
271 you can configure the operating system of the running image to use
272 that port to run a console. The connection uses standard IP
273 networking.
274
275 - SSH servers exist in some QEMU images. The ``core-image-sato``
276 QEMU image has a Dropbear secure shell (SSH) server that runs with
277 the root password disabled. The ``core-image-full-cmdline`` and
278 ``core-image-lsb`` QEMU images have OpenSSH instead of Dropbear.
279 Including these SSH servers allow you to use standard ``ssh`` and
280 ``scp`` commands. The ``core-image-minimal`` QEMU image, however,
281 contains no SSH server.
282
283 - You can use a provided, user-space NFS server to boot the QEMU
284 session using a local copy of the root filesystem on the host. In
285 order to make this connection, you must extract a root filesystem
286 tarball by using the ``runqemu-extract-sdk`` command. After
287 running the command, you must then point the ``runqemu`` script to
288 the extracted directory instead of a root filesystem image file.
289 See the "`Running Under a Network File System (NFS)
290 Server <#qemu-running-under-a-network-file-system-nfs-server>`__"
291 section for more information.
292
293.. _qemu-dev-command-line-syntax:
294
295QEMU Command-Line Syntax
296========================
297
298The basic ``runqemu`` command syntax is as follows: $ runqemu [option ]
299[...] Based on what you provide on the command line, ``runqemu`` does a
300good job of figuring out what you are trying to do. For example, by
301default, QEMU looks for the most recently built image according to the
302timestamp when it needs to look for an image. Minimally, through the use
303of options, you must provide either a machine name, a virtual machine
304image (``*wic.vmdk``), or a kernel image (``*.bin``).
305
306Following is the command-line help output for the ``runqemu`` command: $
307runqemu --help Usage: you can run this script with any valid combination
308of the following environment variables (in any order): KERNEL - the
309kernel image file to use ROOTFS - the rootfs image file or nfsroot
310directory to use MACHINE - the machine name (optional, autodetected from
311KERNEL filename if unspecified) Simplified QEMU command-line options can
312be passed with: nographic - disable video console serial - enable a
313serial console on /dev/ttyS0 slirp - enable user networking, no root
314privileges is required kvm - enable KVM when running x86/x86_64
315(VT-capable CPU required) kvm-vhost - enable KVM with vhost when running
316x86/x86_64 (VT-capable CPU required) publicvnc - enable a VNC server
317open to all hosts audio - enable audio [*/]ovmf\* - OVMF firmware file
318or base name for booting with UEFI tcpserial=<port> - specify tcp serial
319port number biosdir=<dir> - specify custom bios dir
320biosfilename=<filename> - specify bios filename qemuparams=<xyz> -
321specify custom parameters to QEMU bootparams=<xyz> - specify custom
322kernel parameters during boot help, -h, --help: print this text
323Examples: runqemu runqemu qemuarm runqemu tmp/deploy/images/qemuarm
324runqemu tmp/deploy/images/qemux86/<qemuboot.conf> runqemu qemux86-64
325core-image-sato ext4 runqemu qemux86-64 wic-image-minimal wic runqemu
326path/to/bzImage-qemux86.bin path/to/nfsrootdir/ serial runqemu qemux86
327iso/hddimg/wic.vmdk/wic.qcow2/wic.vdi/ramfs/cpio.gz... runqemu qemux86
328qemuparams="-m 256" runqemu qemux86 bootparams="psplash=false" runqemu
329path/to/<image>-<machine>.wic runqemu path/to/<image>-<machine>.wic.vmdk
330
331.. _qemu-dev-runqemu-command-line-options:
332
333``runqemu`` Command-Line Options
334================================
335
336Following is a description of ``runqemu`` options you can provide on the
337command line:
338
339.. note::
340
341 If you do provide some "illegal" option combination or perhaps you do
342 not provide enough in the way of options,
343 runqemu
344 provides appropriate error messaging to help you correct the problem.
345
346- QEMUARCH: The QEMU machine architecture, which must be "qemuarm",
347 "qemuarm64", "qemumips", "qemumips64", "qemuppc", "qemux86", or
348 "qemux86-64".
349
350- ``VM``: The virtual machine image, which must be a ``.wic.vmdk``
351 file. Use this option when you want to boot a ``.wic.vmdk`` image.
352 The image filename you provide must contain one of the following
353 strings: "qemux86-64", "qemux86", "qemuarm", "qemumips64",
354 "qemumips", "qemuppc", or "qemush4".
355
356- ROOTFS: A root filesystem that has one of the following filetype
357 extensions: "ext2", "ext3", "ext4", "jffs2", "nfs", or "btrfs". If
358 the filename you provide for this option uses “nfs”, it must provide
359 an explicit root filesystem path.
360
361- KERNEL: A kernel image, which is a ``.bin`` file. When you provide a
362 ``.bin`` file, ``runqemu`` detects it and assumes the file is a
363 kernel image.
364
365- MACHINE: The architecture of the QEMU machine, which must be one of
366 the following: "qemux86", "qemux86-64", "qemuarm", "qemuarm64",
367 "qemumips", “qemumips64", or "qemuppc". The MACHINE and QEMUARCH
368 options are basically identical. If you do not provide a MACHINE
369 option, ``runqemu`` tries to determine it based on other options.
370
371- ``ramfs``: Indicates you are booting an initial RAM disk (initramfs)
372 image, which means the ``FSTYPE`` is ``cpio.gz``.
373
374- ``iso``: Indicates you are booting an ISO image, which means the
375 ``FSTYPE`` is ``.iso``.
376
377- ``nographic``: Disables the video console, which sets the console to
378 "ttys0". This option is useful when you have logged into a server and
379 you do not want to disable forwarding from the X Window System (X11)
380 to your workstation or laptop.
381
382- ``serial``: Enables a serial console on ``/dev/ttyS0``.
383
384- ``biosdir``: Establishes a custom directory for BIOS, VGA BIOS and
385 keymaps.
386
387- ``biosfilename``: Establishes a custom BIOS name.
388
389- ``qemuparams=\"xyz\"``: Specifies custom QEMU parameters. Use this
390 option to pass options other than the simple "kvm" and "serial"
391 options.
392
393- ``bootparams=\"xyz\"``: Specifies custom boot parameters for the
394 kernel.
395
396- ``audio``: Enables audio in QEMU. The MACHINE option must be either
397 "qemux86" or "qemux86-64" in order for audio to be enabled.
398 Additionally, the ``snd_intel8x0`` or ``snd_ens1370`` driver must be
399 installed in linux guest.
400
401- ``slirp``: Enables "slirp" networking, which is a different way of
402 networking that does not need root access but also is not as easy to
403 use or comprehensive as the default.
404
405- ``kvm``: Enables KVM when running "qemux86" or "qemux86-64" QEMU
406 architectures. For KVM to work, all the following conditions must be
407 met:
408
409 - Your MACHINE must be either qemux86" or "qemux86-64".
410
411 - Your build host has to have the KVM modules installed, which are
412 ``/dev/kvm``.
413
414 - The build host ``/dev/kvm`` directory has to be both writable and
415 readable.
416
417- ``kvm-vhost``: Enables KVM with VHOST support when running "qemux86"
418 or "qemux86-64" QEMU architectures. For KVM with VHOST to work, the
419 following conditions must be met:
420
421 - `kvm <#kvm-cond>`__ option conditions must be met.
422
423 - Your build host has to have virtio net device, which are
424 ``/dev/vhost-net``.
425
426 - The build host ``/dev/vhost-net`` directory has to be either
427 readable or writable and “slirp-enabled”.
428
429- ``publicvnc``: Enables a VNC server open to all hosts.