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