diff options
Diffstat (limited to 'documentation/dev-manual/dev-manual-qemu.rst')
-rw-r--r-- | documentation/dev-manual/dev-manual-qemu.rst | 139 |
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 | ||
51 | 1. *Install QEMU:* QEMU is made available with the Yocto Project a | 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 | 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 | ||
72 | 3. *Ensure the Artifacts are in Place:* You need to be sure you have a | 75 | 3. *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 | ||
91 | 4. *Run QEMU:* The basic ``runqemu`` command syntax is as follows: $ | 93 | 4. *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 | ||
141 | Switching Between Consoles | 157 | Switching 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 | ||
198 | 2. *Start QEMU:* Once you have extracted the file system, you can run | 215 | 2. *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. | |||
297 | QEMU Command-Line Syntax | 317 | QEMU Command-Line Syntax |
298 | ======================== | 318 | ======================== |
299 | 319 | ||
300 | The basic ``runqemu`` command syntax is as follows: $ runqemu [option ] | 320 | The 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 | |||
325 | Based on what you provide on the command line, ``runqemu`` does a | ||
302 | good job of figuring out what you are trying to do. For example, by | 326 | good job of figuring out what you are trying to do. For example, by |
303 | default, QEMU looks for the most recently built image according to the | 327 | default, QEMU looks for the most recently built image according to the |
304 | timestamp when it needs to look for an image. Minimally, through the use | 328 | timestamp when it needs to look for an image. Minimally, through the use |
305 | of options, you must provide either a machine name, a virtual machine | 329 | of options, you must provide either a machine name, a virtual machine |
306 | image (``*wic.vmdk``), or a kernel image (``*.bin``). | 330 | image (``*wic.vmdk``), or a kernel image (``*.bin``). |
307 | 331 | ||
308 | Following is the command-line help output for the ``runqemu`` command: $ | 332 | Following is the command-line help output for the ``runqemu`` command: |
309 | runqemu --help Usage: you can run this script with any valid combination | 333 | :: |
310 | of the following environment variables (in any order): KERNEL - the | 334 | |
311 | kernel image file to use ROOTFS - the rootfs image file or nfsroot | 335 | $ runqemu --help |
312 | directory to use MACHINE - the machine name (optional, autodetected from | 336 | |
313 | KERNEL filename if unspecified) Simplified QEMU command-line options can | 337 | Usage: you can run this script with any valid combination |
314 | be passed with: nographic - disable video console serial - enable a | 338 | of the following environment variables (in any order): |
315 | serial console on /dev/ttyS0 slirp - enable user networking, no root | 339 | KERNEL - the kernel image file to use |
316 | privileges 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) |
318 | x86/x86_64 (VT-capable CPU required) publicvnc - enable a VNC server | 342 | Simplified QEMU command-line options can be passed with: |
319 | open to all hosts audio - enable audio [*/]ovmf\* - OVMF firmware file | 343 | nographic - disable video console |
320 | or base name for booting with UEFI tcpserial=<port> - specify tcp serial | 344 | serial - enable a serial console on /dev/ttyS0 |
321 | port number biosdir=<dir> - specify custom bios dir | 345 | slirp - enable user networking, no root privileges is required |
322 | biosfilename=<filename> - specify bios filename qemuparams=<xyz> - | 346 | kvm - enable KVM when running x86/x86_64 (VT-capable CPU required) |
323 | specify custom parameters to QEMU bootparams=<xyz> - specify custom | 347 | kvm-vhost - enable KVM with vhost when running x86/x86_64 (VT-capable CPU required) |
324 | kernel parameters during boot help, -h, --help: print this text | 348 | publicvnc - enable a VNC server open to all hosts |
325 | Examples: runqemu runqemu qemuarm runqemu tmp/deploy/images/qemuarm | 349 | audio - enable audio |
326 | runqemu tmp/deploy/images/qemux86/<qemuboot.conf> runqemu qemux86-64 | 350 | [*/]ovmf* - OVMF firmware file or base name for booting with UEFI |
327 | core-image-sato ext4 runqemu qemux86-64 wic-image-minimal wic runqemu | 351 | tcpserial=<port> - specify tcp serial port number |
328 | path/to/bzImage-qemux86.bin path/to/nfsrootdir/ serial runqemu qemux86 | 352 | biosdir=<dir> - specify custom bios dir |
329 | iso/hddimg/wic.vmdk/wic.qcow2/wic.vdi/ramfs/cpio.gz... runqemu qemux86 | 353 | biosfilename=<filename> - specify bios filename |
330 | qemuparams="-m 256" runqemu qemux86 bootparams="psplash=false" runqemu | 354 | qemuparams=<xyz> - specify custom parameters to QEMU |
331 | path/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 | ||