summaryrefslogtreecommitdiffstats
path: root/documentation/dev-manual/dev-manual-qemu.rst
diff options
context:
space:
mode:
Diffstat (limited to 'documentation/dev-manual/dev-manual-qemu.rst')
-rw-r--r--documentation/dev-manual/dev-manual-qemu.rst139
1 files changed, 89 insertions, 50 deletions
diff --git a/documentation/dev-manual/dev-manual-qemu.rst b/documentation/dev-manual/dev-manual-qemu.rst
index d695b90202..82c214b9bb 100644
--- a/documentation/dev-manual/dev-manual-qemu.rst
+++ b/documentation/dev-manual/dev-manual-qemu.rst
@@ -50,8 +50,7 @@ available. Follow these general steps to run QEMU:
50 50
511. *Install QEMU:* QEMU is made available with the Yocto Project a 511. *Install QEMU:* QEMU is made available with the Yocto Project a
52 number of ways. One method is to install a Software Development Kit 52 number of ways. One method is to install a Software Development Kit
53 (SDK). See "`The QEMU 53 (SDK). See ":ref:`sdk-manual/sdk-intro:the qemu emulator`" section in the
54 Emulator <&YOCTO_DOCS_SDK_URL;#the-qemu-emulator>`__" section in the
55 Yocto Project Application Development and the Extensible Software 54 Yocto Project Application Development and the Extensible Software
56 Development Kit (eSDK) manual for information on how to install QEMU. 55 Development Kit (eSDK) manual for information on how to install QEMU.
57 56
@@ -60,14 +59,18 @@ available. Follow these general steps to run QEMU:
60 59
61 - If you cloned the ``poky`` repository or you downloaded and 60 - If you cloned the ``poky`` repository or you downloaded and
62 unpacked a Yocto Project release tarball, you can source the build 61 unpacked a Yocto Project release tarball, you can source the build
63 environment script (i.e. 62 environment script (i.e. :ref:`structure-core-script`):
64 ````` <&YOCTO_DOCS_REF_URL;#structure-core-script>`__): $ cd 63 ::
65 ~/poky $ source oe-init-build-env 64
65 $ cd ~/poky
66 $ source oe-init-build-env
66 67
67 - If you installed a cross-toolchain, you can run the script that 68 - If you installed a cross-toolchain, you can run the script that
68 initializes the toolchain. For example, the following commands run 69 initializes the toolchain. For example, the following commands run
69 the initialization script from the default ``poky_sdk`` directory: 70 the initialization script from the default ``poky_sdk`` directory:
70 . ~/poky_sdk/environment-setup-core2-64-poky-linux 71 ::
72
73 . ~/poky_sdk/environment-setup-core2-64-poky-linux
71 74
723. *Ensure the Artifacts are in Place:* You need to be sure you have a 753. *Ensure the Artifacts are in Place:* You need to be sure you have a
73 pre-built kernel that will boot in QEMU. You also need the target 76 pre-built kernel that will boot in QEMU. You also need the target
@@ -78,18 +81,21 @@ available. Follow these general steps to run QEMU:
78 your :term:`Build Directory`. 81 your :term:`Build Directory`.
79 82
80 - If you have not built an image, you can go to the 83 - If you have not built an image, you can go to the
81 `machines/qemu <&YOCTO_MACHINES_DL_URL;>`__ area and download a 84 :yocto_dl:`machines/qemu <releases/yocto/yocto-3.1.2/machines/qemu/>` area and download a
82 pre-built image that matches your architecture and can be run on 85 pre-built image that matches your architecture and can be run on
83 QEMU. 86 QEMU.
84 87
85 See the "`Extracting the Root 88 See the ":ref:`sdk-manual/sdk-appendix-obtain:extracting the root filesystem`"
86 Filesystem <&YOCTO_DOCS_SDK_URL;#sdk-extracting-the-root-filesystem>`__"
87 section in the Yocto Project Application Development and the 89 section in the Yocto Project Application Development and the
88 Extensible Software Development Kit (eSDK) manual for information on 90 Extensible Software Development Kit (eSDK) manual for information on
89 how to extract a root filesystem. 91 how to extract a root filesystem.
90 92
914. *Run QEMU:* The basic ``runqemu`` command syntax is as follows: $ 934. *Run QEMU:* The basic ``runqemu`` command syntax is as follows:
92 runqemu [option ] [...] Based on what you provide on the command 94 ::
95
96 $ runqemu [option ] [...]
97
98 Based on what you provide on the command
93 line, ``runqemu`` does a good job of figuring out what you are trying 99 line, ``runqemu`` does a good job of figuring out what you are trying
94 to do. For example, by default, QEMU looks for the most recently 100 to do. For example, by default, QEMU looks for the most recently
95 built image according to the timestamp when it needs to look for an 101 built image according to the timestamp when it needs to look for an
@@ -113,30 +119,40 @@ available. Follow these general steps to run QEMU:
113 and uses the most recently built image according to the 119 and uses the most recently built image according to the
114 timestamp. 120 timestamp.
115 121
116 $ runqemu qemux86-64 122 ::
123
124 $ runqemu qemux86-64
117 125
118 - This example produces the exact same results as the previous 126 - This example produces the exact same results as the previous
119 example. This command, however, specifically provides the image 127 example. This command, however, specifically provides the image
120 and root filesystem type. $ runqemu qemux86-64 core-image-minimal 128 and root filesystem type.
121 ext4 129 ::
130
131 $ runqemu qemux86-64 core-image-minimal ext4
122 132
123 - This example specifies to boot an initial RAM disk image and to 133 - This example specifies to boot an initial RAM disk image and to
124 enable audio in QEMU. For this case, ``runqemu`` set the internal 134 enable audio in QEMU. For this case, ``runqemu`` set the internal
125 variable ``FSTYPE`` to "cpio.gz". Also, for audio to be enabled, 135 variable ``FSTYPE`` to "cpio.gz". Also, for audio to be enabled,
126 an appropriate driver must be installed (see the previous 136 an appropriate driver must be installed (see the previous
127 description for the ``audio`` option for more information). $ 137 description for the ``audio`` option for more information).
128 runqemu qemux86-64 ramfs audio 138 ::
139
140 $ runqemu qemux86-64 ramfs audio
129 141
130 - This example does not provide enough information for QEMU to 142 - This example does not provide enough information for QEMU to
131 launch. While the command does provide a root filesystem type, it 143 launch. While the command does provide a root filesystem type, it
132 must also minimally provide a MACHINE, KERNEL, or VM option. $ 144 must also minimally provide a MACHINE, KERNEL, or VM option.
133 runqemu ext4 145 ::
146
147 $ runqemu ext4
134 148
135 - This example specifies to boot a virtual machine image 149 - This example specifies to boot a virtual machine image
136 (``.wic.vmdk`` file). From the ``.wic.vmdk``, ``runqemu`` 150 (``.wic.vmdk`` file). From the ``.wic.vmdk``, ``runqemu``
137 determines the QEMU architecture (MACHINE) to be "qemux86-64" and 151 determines the QEMU architecture (MACHINE) to be "qemux86-64" and
138 the root filesystem type to be "vmdk". $ runqemu 152 the root filesystem type to be "vmdk".
139 /home/scott-lenovo/vm/core-image-minimal-qemux86-64.wic.vmdk 153 ::
154
155 $ runqemu /home/scott-lenovo/vm/core-image-minimal-qemux86-64.wic.vmdk
140 156
141Switching Between Consoles 157Switching Between Consoles
142========================== 158==========================
@@ -191,15 +207,19 @@ using an NFS server.
191 The ``runqemu-extract-sdk`` takes a root filesystem tarball and 207 The ``runqemu-extract-sdk`` takes a root filesystem tarball and
192 extracts it into a location that you specify. Here is an example that 208 extracts it into a location that you specify. Here is an example that
193 takes a file system and extracts it to a directory named 209 takes a file system and extracts it to a directory named
194 ``test-nfs``: runqemu-extract-sdk 210 ``test-nfs``:
195 ./tmp/deploy/images/qemux86-64/core-image-sato-qemux86-64.tar.bz2 211 ::
196 test-nfs 212
213 runqemu-extract-sdk ./tmp/deploy/images/qemux86-64/core-image-sato-qemux86-64.tar.bz2 test-nfs
197 214
1982. *Start QEMU:* Once you have extracted the file system, you can run 2152. *Start QEMU:* Once you have extracted the file system, you can run
199 ``runqemu`` normally with the additional location of the file system. 216 ``runqemu`` normally with the additional location of the file system.
200 You can then also make changes to the files within ``./test-nfs`` and 217 You can then also make changes to the files within ``./test-nfs`` and
201 see those changes appear in the image in real time. Here is an 218 see those changes appear in the image in real time. Here is an
202 example using the ``qemux86`` image: runqemu qemux86-64 ./test-nfs 219 example using the ``qemux86`` image:
220 ::
221
222 runqemu qemux86-64 ./test-nfs
203 223
204.. note:: 224.. note::
205 225
@@ -297,38 +317,57 @@ present, the toolchain is also automatically used.
297QEMU Command-Line Syntax 317QEMU Command-Line Syntax
298======================== 318========================
299 319
300The basic ``runqemu`` command syntax is as follows: $ runqemu [option ] 320The basic ``runqemu`` command syntax is as follows:
301[...] Based on what you provide on the command line, ``runqemu`` does a 321::
322
323 $ runqemu [option ] [...]
324
325Based on what you provide on the command line, ``runqemu`` does a
302good job of figuring out what you are trying to do. For example, by 326good job of figuring out what you are trying to do. For example, by
303default, QEMU looks for the most recently built image according to the 327default, QEMU looks for the most recently built image according to the
304timestamp when it needs to look for an image. Minimally, through the use 328timestamp when it needs to look for an image. Minimally, through the use
305of options, you must provide either a machine name, a virtual machine 329of options, you must provide either a machine name, a virtual machine
306image (``*wic.vmdk``), or a kernel image (``*.bin``). 330image (``*wic.vmdk``), or a kernel image (``*.bin``).
307 331
308Following is the command-line help output for the ``runqemu`` command: $ 332Following is the command-line help output for the ``runqemu`` command:
309runqemu --help Usage: you can run this script with any valid combination 333::
310of the following environment variables (in any order): KERNEL - the 334
311kernel image file to use ROOTFS - the rootfs image file or nfsroot 335 $ runqemu --help
312directory to use MACHINE - the machine name (optional, autodetected from 336
313KERNEL filename if unspecified) Simplified QEMU command-line options can 337 Usage: you can run this script with any valid combination
314be passed with: nographic - disable video console serial - enable a 338 of the following environment variables (in any order):
315serial console on /dev/ttyS0 slirp - enable user networking, no root 339 KERNEL - the kernel image file to use
316privileges is required kvm - enable KVM when running x86/x86_64 340 ROOTFS - the rootfs image file or nfsroot directory to use
317(VT-capable CPU required) kvm-vhost - enable KVM with vhost when running 341 MACHINE - the machine name (optional, autodetected from KERNEL filename if unspecified)
318x86/x86_64 (VT-capable CPU required) publicvnc - enable a VNC server 342 Simplified QEMU command-line options can be passed with:
319open to all hosts audio - enable audio [*/]ovmf\* - OVMF firmware file 343 nographic - disable video console
320or base name for booting with UEFI tcpserial=<port> - specify tcp serial 344 serial - enable a serial console on /dev/ttyS0
321port number biosdir=<dir> - specify custom bios dir 345 slirp - enable user networking, no root privileges is required
322biosfilename=<filename> - specify bios filename qemuparams=<xyz> - 346 kvm - enable KVM when running x86/x86_64 (VT-capable CPU required)
323specify custom parameters to QEMU bootparams=<xyz> - specify custom 347 kvm-vhost - enable KVM with vhost when running x86/x86_64 (VT-capable CPU required)
324kernel parameters during boot help, -h, --help: print this text 348 publicvnc - enable a VNC server open to all hosts
325Examples: runqemu runqemu qemuarm runqemu tmp/deploy/images/qemuarm 349 audio - enable audio
326runqemu tmp/deploy/images/qemux86/<qemuboot.conf> runqemu qemux86-64 350 [*/]ovmf* - OVMF firmware file or base name for booting with UEFI
327core-image-sato ext4 runqemu qemux86-64 wic-image-minimal wic runqemu 351 tcpserial=<port> - specify tcp serial port number
328path/to/bzImage-qemux86.bin path/to/nfsrootdir/ serial runqemu qemux86 352 biosdir=<dir> - specify custom bios dir
329iso/hddimg/wic.vmdk/wic.qcow2/wic.vdi/ramfs/cpio.gz... runqemu qemux86 353 biosfilename=<filename> - specify bios filename
330qemuparams="-m 256" runqemu qemux86 bootparams="psplash=false" runqemu 354 qemuparams=<xyz> - specify custom parameters to QEMU
331path/to/<image>-<machine>.wic runqemu path/to/<image>-<machine>.wic.vmdk 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
332 371
333.. _qemu-dev-runqemu-command-line-options: 372.. _qemu-dev-runqemu-command-line-options:
334 373