X-Git-Url: https://git.proxmox.com/?a=blobdiff_plain;f=qemu-doc.texi;h=39f950471f2805481335cd0555da5454feca4c05;hb=c6b3a2e0c4342d171b35970921bff709c007dd62;hp=b8809177be8f823dc687604fd054bd4508fbd7ed;hpb=b8f7ff1e10b4d03555d6a5da011c2aae10063ab8;p=mirror_qemu.git diff --git a/qemu-doc.texi b/qemu-doc.texi index b8809177be..39f950471f 100644 --- a/qemu-doc.texi +++ b/qemu-doc.texi @@ -11,6 +11,9 @@ @paragraphindent 0 @c %**end of header +@set qemu_system qemu-system-x86_64 +@set qemu_system_x86 qemu-system-x86_64 + @ifinfo @direntry * QEMU: (qemu-doc). The QEMU Emulator User Documentation. @@ -35,10 +38,12 @@ * Introduction:: * QEMU PC System emulator:: * QEMU System emulator for non PC targets:: -* QEMU Guest Agent:: * QEMU User space emulator:: +* System requirements:: +* Security:: * Implementation notes:: * Deprecated features:: +* Recently removed features:: * Supported build platforms:: * License:: * Index:: @@ -135,6 +140,7 @@ accelerator is required to use more than one host CPU for emulation. * pcsys_keys:: Keys in the graphical frontends * mux_keys:: Keys in the character backend multiplexer * pcsys_monitor:: QEMU Monitor +* cpu_models:: CPU models * disk_images:: Disk Images * pcsys_network:: Network emulation * pcsys_other_devs:: Other Devices @@ -204,12 +210,12 @@ Note that, by default, GUS shares IRQ(7) with parallel ports and so QEMU must be told to not have parallel ports to have working GUS. @example -qemu-system-i386 dos.img -soundhw gus -parallel none +@value{qemu_system_x86} dos.img -soundhw gus -parallel none @end example Alternatively: @example -qemu-system-i386 dos.img -device gus,irq=5 +@value{qemu_system_x86} dos.img -device gus,irq=5 @end example Or some other unclaimed IRQ. @@ -222,10 +228,11 @@ CS4231A is the chip used in Windows Sound System and GUSMAX products @section Quick Start @cindex quick start -Download and uncompress the linux image (@file{linux.img}) and type: +Download and uncompress a hard disk image with Linux installed (e.g. +@file{linux.img}) and type: @example -qemu-system-i386 linux.img +@value{qemu_system} linux.img @end example Linux should boot and give you a prompt. @@ -235,7 +242,7 @@ Linux should boot and give you a prompt. @example @c man begin SYNOPSIS -@command{qemu-system-i386} [@var{options}] [@var{disk_image}] +@command{@value{qemu_system}} [@var{options}] [@var{disk_image}] @c man end @end example @@ -275,28 +282,35 @@ is specified in seconds. The default is 0 which means no timeout. Libiscsi Example (without authentication): @example -qemu-system-i386 -iscsi initiator-name=iqn.2001-04.com.example:my-initiator \ +@value{qemu_system} -iscsi initiator-name=iqn.2001-04.com.example:my-initiator \ -cdrom iscsi://192.0.2.1/iqn.2001-04.com.example/2 \ -drive file=iscsi://192.0.2.1/iqn.2001-04.com.example/1 @end example Example (CHAP username/password via URL): @example -qemu-system-i386 -drive file=iscsi://user%password@@192.0.2.1/iqn.2001-04.com.example/1 +@value{qemu_system} -drive file=iscsi://user%password@@192.0.2.1/iqn.2001-04.com.example/1 @end example Example (CHAP username/password via environment variables): @example LIBISCSI_CHAP_USERNAME="user" \ LIBISCSI_CHAP_PASSWORD="password" \ -qemu-system-i386 -drive file=iscsi://192.0.2.1/iqn.2001-04.com.example/1 +@value{qemu_system} -drive file=iscsi://192.0.2.1/iqn.2001-04.com.example/1 @end example @item NBD QEMU supports NBD (Network Block Devices) both using TCP protocol as well -as Unix Domain Sockets. +as Unix Domain Sockets. With TCP, the default port is 10809. + +Syntax for specifying a NBD device using TCP, in preferred URI form: +``nbd://[:]/[]'' + +Syntax for specifying a NBD device using Unix Domain Sockets; remember +that '?' is a shell glob character and may need quoting: +``nbd+unix:///[]?socket='' -Syntax for specifying a NBD device using TCP +Older syntax that is also recognized: ``nbd::[:exportname=]'' Syntax for specifying a NBD device using Unix Domain Sockets @@ -304,12 +318,12 @@ Syntax for specifying a NBD device using Unix Domain Sockets Example for TCP @example -qemu-system-i386 --drive file=nbd:192.0.2.1:30000 +@value{qemu_system} --drive file=nbd:192.0.2.1:30000 @end example Example for Unix Domain Sockets @example -qemu-system-i386 --drive file=nbd:unix:/tmp/nbd-socket +@value{qemu_system} --drive file=nbd:unix:/tmp/nbd-socket @end example @item SSH @@ -317,8 +331,8 @@ QEMU supports SSH (Secure Shell) access to remote disks. Examples: @example -qemu-system-i386 -drive file=ssh://user@@host/path/to/disk.img -qemu-system-i386 -drive file.driver=ssh,file.user=user,file.host=host,file.port=22,file.path=/path/to/disk.img +@value{qemu_system} -drive file=ssh://user@@host/path/to/disk.img +@value{qemu_system} -drive file.driver=ssh,file.user=user,file.host=host,file.port=22,file.path=/path/to/disk.img @end example Currently authentication must be done using ssh-agent. Other @@ -336,7 +350,7 @@ sheepdog[+tcp|+unix]://[host:port]/vdiname[?socket=path][#snapid|#tag] Example @example -qemu-system-i386 --drive file=sheepdog://192.0.2.1:30000/MyVirtualMachine +@value{qemu_system} --drive file=sheepdog://192.0.2.1:30000/MyVirtualMachine @end example See also @url{https://sheepdog.github.io/sheepdog/}. @@ -362,17 +376,17 @@ JSON: Example @example URI: -qemu-system-x86_64 --drive file=gluster://192.0.2.1/testvol/a.img, +@value{qemu_system} --drive file=gluster://192.0.2.1/testvol/a.img, @ file.debug=9,file.logfile=/var/log/qemu-gluster.log JSON: -qemu-system-x86_64 'json:@{"driver":"qcow2", +@value{qemu_system} 'json:@{"driver":"qcow2", @ "file":@{"driver":"gluster", @ "volume":"testvol","path":"a.img", @ "debug":9,"logfile":"/var/log/qemu-gluster.log", @ "server":[@{"type":"tcp","host":"1.2.3.4","port":24007@}, @ @{"type":"unix","socket":"/var/run/glusterd.socket"@}]@}@}' -qemu-system-x86_64 -drive driver=qcow2,file.driver=gluster,file.volume=testvol,file.path=/path/a.img, +@value{qemu_system} -drive driver=qcow2,file.driver=gluster,file.volume=testvol,file.path=/path/a.img, @ file.debug=9,file.logfile=/var/log/qemu-gluster.log, @ file.server.0.type=tcp,file.server.0.host=1.2.3.4,file.server.0.port=24007, @ file.server.1.type=unix,file.server.1.socket=/var/run/glusterd.socket @@ -437,17 +451,17 @@ of . Example: boot from a remote Fedora 20 live ISO image @example -qemu-system-x86_64 --drive media=cdrom,file=http://dl.fedoraproject.org/pub/fedora/linux/releases/20/Live/x86_64/Fedora-Live-Desktop-x86_64-20-1.iso,readonly +@value{qemu_system_x86} --drive media=cdrom,file=https://archives.fedoraproject.org/pub/archive/fedora/linux/releases/20/Live/x86_64/Fedora-Live-Desktop-x86_64-20-1.iso,readonly -qemu-system-x86_64 --drive media=cdrom,file.driver=http,file.url=http://dl.fedoraproject.org/pub/fedora/linux/releases/20/Live/x86_64/Fedora-Live-Desktop-x86_64-20-1.iso,readonly +@value{qemu_system_x86} --drive media=cdrom,file.driver=http,file.url=http://archives.fedoraproject.org/pub/fedora/linux/releases/20/Live/x86_64/Fedora-Live-Desktop-x86_64-20-1.iso,readonly @end example Example: boot from a remote Fedora 20 cloud image using a local overlay for writes, copy-on-read, and a readahead of 64k @example -qemu-img create -f qcow2 -o backing_file='json:@{"file.driver":"http",, "file.url":"https://dl.fedoraproject.org/pub/fedora/linux/releases/20/Images/x86_64/Fedora-x86_64-20-20131211.1-sda.qcow2",, "file.readahead":"64k"@}' /tmp/Fedora-x86_64-20-20131211.1-sda.qcow2 +qemu-img create -f qcow2 -o backing_file='json:@{"file.driver":"http",, "file.url":"http://archives.fedoraproject.org/pub/archive/fedora/linux/releases/20/Images/x86_64/Fedora-x86_64-20-20131211.1-sda.qcow2",, "file.readahead":"64k"@}' /tmp/Fedora-x86_64-20-20131211.1-sda.qcow2 -qemu-system-x86_64 -drive file=/tmp/Fedora-x86_64-20-20131211.1-sda.qcow2,copy-on-read=on +@value{qemu_system_x86} -drive file=/tmp/Fedora-x86_64-20-20131211.1-sda.qcow2,copy-on-read=on @end example Example: boot from an image stored on a VMware vSphere server with a self-signed @@ -456,7 +470,7 @@ of 10 seconds. @example qemu-img create -f qcow2 -o backing_file='json:@{"file.driver":"https",, "file.url":"https://user:password@@vsphere.example.com/folder/test/test-flat.vmdk?dcPath=Datacenter&dsName=datastore1",, "file.sslverify":"off",, "file.readahead":"64k",, "file.timeout":10@}' /tmp/test.qcow2 -qemu-system-x86_64 -drive file=/tmp/test.qcow2 +@value{qemu_system_x86} -drive file=/tmp/test.qcow2 @end example @end table @@ -602,6 +616,11 @@ The monitor understands integers expressions for every integer argument. You can use register names to get the value of specifics CPU registers by prefixing them with @emph{$}. +@node cpu_models +@section CPU models + +@include docs/qemu-cpu-models.texi + @node disk_images @section Disk Images @@ -818,7 +837,7 @@ On Linux hosts, a shared memory device is available. The basic syntax is: @example -qemu-system-x86_64 -device ivshmem-plain,memdev=@var{hostmem} +@value{qemu_system_x86} -device ivshmem-plain,memdev=@var{hostmem} @end example where @var{hostmem} names a host memory backend. For a POSIX shared @@ -839,7 +858,7 @@ memory server is: ivshmem-server -p @var{pidfile} -S @var{path} -m @var{shm-name} -l @var{shm-size} -n @var{vectors} # Then start your qemu instances with matching arguments -qemu-system-x86_64 -device ivshmem-doorbell,vectors=@var{vectors},chardev=@var{id} +@value{qemu_system_x86} -device ivshmem-doorbell,vectors=@var{vectors},chardev=@var{id} -chardev socket,path=@var{path},id=@var{id} @end example @@ -864,7 +883,7 @@ Instead of specifying the using POSIX shm, you may specify a memory backend that has hugepage support: @example -qemu-system-x86_64 -object memory-backend-file,size=1G,mem-path=/dev/hugepages/my-shmem-file,share,id=mb1 +@value{qemu_system_x86} -object memory-backend-file,size=1G,mem-path=/dev/hugepages/my-shmem-file,share,id=mb1 -device ivshmem-plain,memdev=mb1 @end example @@ -880,22 +899,18 @@ kernel testing. The syntax is: @example -qemu-system-i386 -kernel arch/i386/boot/bzImage -hda root-2.4.20.img -append "root=/dev/hda" +@value{qemu_system} -kernel bzImage -hda rootdisk.img -append "root=/dev/hda" @end example Use @option{-kernel} to provide the Linux kernel image and @option{-append} to give the kernel command line arguments. The @option{-initrd} option can be used to provide an INITRD image. -When using the direct Linux boot, a disk image for the first hard disk -@file{hda} is required because its boot sector is used to launch the -Linux kernel. - If you do not need graphical output, you can disable it and redirect the virtual serial port and the QEMU monitor to the console with the @option{-nographic} option. The typical command line is: @example -qemu-system-i386 -kernel arch/i386/boot/bzImage -hda root-2.4.20.img \ +@value{qemu_system} -kernel bzImage -hda rootdisk.img \ -append "root=/dev/hda console=ttyS0" -nographic @end example @@ -937,7 +952,7 @@ for details Bulk-only transport storage device, see @url{https://git.qemu.org/?p=qemu.git;a=blob_plain;f=docs/usb-storage.txt,usb-storage.txt} for details here, too -@item usb-mtp,x-root=@var{dir} +@item usb-mtp,rootdir=@var{dir} Media transfer protocol device, using @var{dir} as root of the file tree that is presented to the guest. @item usb-host,hostbus=@var{bus},hostaddr=@var{addr} @@ -961,27 +976,12 @@ Network adapter that supports CDC ethernet and RNDIS protocols. @var{id} specifies a netdev defined with @code{-netdev @dots{},id=@var{id}}. For instance, user-mode networking can be used with @example -qemu-system-i386 [...] -netdev user,id=net0 -device usb-net,netdev=net0 +@value{qemu_system} [...] -netdev user,id=net0 -device usb-net,netdev=net0 @end example @item usb-ccid Smartcard reader device @item usb-audio USB audio device -@item usb-bt-dongle -Bluetooth dongle for the transport layer of HCI. It is connected to HCI -scatternet 0 by default (corresponds to @code{-bt hci,vlan=0}). -Note that the syntax for the @code{-device usb-bt-dongle} option is not as -useful yet as it was with the legacy @code{-usbdevice} option. So to -configure an USB bluetooth device, you might need to use -"@code{-usbdevice bt}[:@var{hci-type}]" instead. This configures a -bluetooth dongle whose type is specified in the same format as with -the @option{-bt hci} option, @pxref{bt-hcis,,allowed HCI types}. If -no type is given, the HCI logic corresponds to @code{-bt hci,vlan=0}. -This USB device implements the USB Transport Layer of HCI. Example -usage: -@example -@command{qemu-system-i386} [...@var{OPTIONS}...] @option{-usbdevice} bt:hci,vlan=3 @option{-bt} device:keyboard,vlan=3 -@end example @end table @node host_usb_devices @@ -1057,7 +1057,7 @@ For this setup it is recommended to restrict it to listen on a UNIX domain socket only. For example @example -qemu-system-i386 [...OPTIONS...] -vnc unix:/home/joebloggs/.qemu-myvm-vnc +@value{qemu_system} [...OPTIONS...] -vnc unix:/home/joebloggs/.qemu-myvm-vnc @end example This ensures that only users on local box with read/write access to that @@ -1080,7 +1080,7 @@ is running the password is set with the monitor. Until the monitor is used to set the password all clients will be rejected. @example -qemu-system-i386 [...OPTIONS...] -vnc :1,password -monitor stdio +@value{qemu_system} [...OPTIONS...] -vnc :1,password -monitor stdio (qemu) change vnc password Password: ******** (qemu) @@ -1097,7 +1097,9 @@ support provides a secure session, but no authentication. This allows any client to connect, and provides an encrypted session. @example -qemu-system-i386 [...OPTIONS...] -vnc :1,tls,x509=/etc/pki/qemu -monitor stdio +@value{qemu_system} [...OPTIONS...] \ + -object tls-creds-x509,id=tls0,dir=/etc/pki/qemu,endpoint=server,verify-peer=no \ + -vnc :1,tls-creds=tls0 -monitor stdio @end example In the above example @code{/etc/pki/qemu} should contain at least three files, @@ -1112,10 +1114,14 @@ only be readable by the user owning it. Certificates can also provide a means to authenticate the client connecting. The server will request that the client provide a certificate, which it will then validate against the CA certificate. This is a good choice if deploying -in an environment with a private internal certificate authority. +in an environment with a private internal certificate authority. It uses the +same syntax as previously, but with @code{verify-peer} set to @code{yes} +instead. @example -qemu-system-i386 [...OPTIONS...] -vnc :1,tls,x509verify=/etc/pki/qemu -monitor stdio +@value{qemu_system} [...OPTIONS...] \ + -object tls-creds-x509,id=tls0,dir=/etc/pki/qemu,endpoint=server,verify-peer=yes \ + -vnc :1,tls-creds=tls0 -monitor stdio @end example @@ -1126,7 +1132,9 @@ Finally, the previous method can be combined with VNC password authentication to provide two layers of authentication for clients. @example -qemu-system-i386 [...OPTIONS...] -vnc :1,password,tls,x509verify=/etc/pki/qemu -monitor stdio +@value{qemu_system} [...OPTIONS...] \ + -object tls-creds-x509,id=tls0,dir=/etc/pki/qemu,endpoint=server,verify-peer=yes \ + -vnc :1,tls-creds=tls0,password -monitor stdio (qemu) change vnc password Password: ******** (qemu) @@ -1149,7 +1157,7 @@ used for authentication, but assuming use of one supporting SSF, then QEMU can be launched with: @example -qemu-system-i386 [...OPTIONS...] -vnc :1,sasl -monitor stdio +@value{qemu_system} [...OPTIONS...] -vnc :1,sasl -monitor stdio @end example @node vnc_sec_certificate_sasl @@ -1163,7 +1171,9 @@ credentials. This can be enabled, by combining the 'sasl' option with the aforementioned TLS + x509 options: @example -qemu-system-i386 [...OPTIONS...] -vnc :1,tls,x509,sasl -monitor stdio +@value{qemu_system} [...OPTIONS...] \ + -object tls-creds-x509,id=tls0,dir=/etc/pki/qemu,endpoint=server,verify-peer=yes \ + -vnc :1,tls-creds=tls0,sasl -monitor stdio @end example @node vnc_setup_sasl @@ -1494,13 +1504,13 @@ To load server credentials with client certificate validation enabled @example -$QEMU -object tls-creds-x509,id=tls0,dir=/etc/pki/qemu,endpoint=server +@value{qemu_system} -object tls-creds-x509,id=tls0,dir=/etc/pki/qemu,endpoint=server @end example while to load client credentials use @example -$QEMU -object tls-creds-x509,id=tls0,dir=/etc/pki/qemu,endpoint=client +@value{qemu_system} -object tls-creds-x509,id=tls0,dir=/etc/pki/qemu,endpoint=client @end example Network services which support TLS will all have a @code{tls-creds} @@ -1508,7 +1518,7 @@ parameter which expects the ID of the TLS credentials object. For example with VNC: @example -$QEMU -vnc 0.0.0.0:0,tls-creds=tls0 +@value{qemu_system} -vnc 0.0.0.0:0,tls-creds=tls0 @end example @node tls_psk @@ -1556,8 +1566,7 @@ QEMU has a primitive support to work with gdb, so that you can do In order to use gdb, launch QEMU with the '-s' option. It will wait for a gdb connection: @example -qemu-system-i386 -s -kernel arch/i386/boot/bzImage -hda root-2.4.20.img \ - -append "root=/dev/hda" +@value{qemu_system} -s -kernel bzImage -hda rootdisk.img -append "root=/dev/hda" Connected to host network interface: tun0 Waiting gdb connection on port 1234 @end example @@ -1978,6 +1987,10 @@ Set the emulated machine type. The default is sun4u. @section MIPS System emulator @cindex system emulation (MIPS) +@menu +* nanoMIPS System emulator :: +@end menu + Four executables cover simulation of 32 and 64-bit MIPS systems in both endian options, @file{qemu-system-mips}, @file{qemu-system-mipsel} @file{qemu-system-mips64} and @file{qemu-system-mips64el}. @@ -2028,6 +2041,15 @@ Malta FPGA serial device Cirrus (default) or any other PCI VGA graphics card @end itemize +The Boston board emulation supports the following devices: + +@itemize @minus +@item +Xilinx FPGA, which includes a PCIe root port and an UART +@item +Intel EG20T PCH connects the I/O peripherals, but only the SATA bus is emulated +@end itemize + The ACER Pica emulation supports: @itemize @minus @@ -2041,6 +2063,34 @@ PC Keyboard IDE controller @end itemize +The MIPS Magnum R4000 emulation supports: + +@itemize @minus +@item +MIPS R4000 CPU +@item +PC-style IRQ controller +@item +PC Keyboard +@item +SCSI controller +@item +G364 framebuffer +@end itemize + +The Fulong 2E emulation supports: + +@itemize @minus +@item +Loongson 2E CPU +@item +Bonito64 system controller as North Bridge +@item +VT82C686 chipset as South Bridge +@item +RTL8139D as a network card chipset +@end itemize + The mipssim pseudo board emulation provides an environment similar to what the proprietary MIPS emulator uses for running Linux. It supports: @@ -2054,21 +2104,31 @@ PC style serial port MIPSnet network emulation @end itemize -The MIPS Magnum R4000 emulation supports: +@node nanoMIPS System emulator +@subsection nanoMIPS System emulator +@cindex system emulation (nanoMIPS) + +Executable @file{qemu-system-mipsel} also covers simulation of +32-bit nanoMIPS system in little endian mode: @itemize @minus @item -MIPS R4000 CPU -@item -PC-style IRQ controller -@item -PC Keyboard -@item -SCSI controller -@item -G364 framebuffer +nanoMIPS I7200 CPU @end itemize +Example of @file{qemu-system-mipsel} usage for nanoMIPS is shown below: + +Download @code{} from @url{https://mipsdistros.mips.com/LinuxDistro/nanomips/buildroot/index.html}. + +Download @code{} from @url{https://mipsdistros.mips.com/LinuxDistro/nanomips/kernels/v4.15.18-432-gb2eb9a8b07a1-20180627102142/index.html}. + +Start system emulation of Malta board with nanoMIPS I7200 CPU: +@example +qemu-system-mipsel -cpu I7200 -kernel @code{} \ + -M malta -serial stdio -m @code{} -hda @code{} \ + -append "mem=256m@@0x0 rw console=ttyS0 vga=cirrus vesa=0x111 root=/dev/sda" +@end example + @node ARM System emulator @section ARM System emulator @@ -2232,8 +2292,6 @@ Secure Digital card connected to OMAP MMC/SD host @item Three OMAP on-chip UARTs and on-chip STI debugging console @item -A Bluetooth(R) transceiver and HCI connected to an UART -@item Mentor Graphics "Inventra" dual-role USB controller embedded in a TI TUSB6010 chip - only USB host mode is supported @item @@ -2456,11 +2514,6 @@ so should only be used with trusted guest OS. @c man end -@node QEMU Guest Agent -@chapter QEMU Guest Agent invocation - -@include qemu-ga.texi - @node QEMU User space emulator @chapter QEMU User space emulator @@ -2797,6 +2850,20 @@ Act as if the host page size was 'pagesize' bytes Run the emulation in single step mode. @end table +@node System requirements +@chapter System requirements + +@section KVM kernel module + +On x86_64 hosts, the default set of CPU features enabled by the KVM accelerator +require the host to be running Linux v4.5 or newer. + +The OpteronG[345] CPU models require KVM support for RDTSCP, which was +added with Linux 4.5 which is supported by the major distros. And even +if RHEL7 has kernel 3.10, KVM there has the required functionality there +to make it close to a 4.5 or newer kernel. + +@include docs/security.texi @include qemu-tech.texi