hw/arm/nseries: Replace the bluetooth chardev with a "null" chardev
[qemu.git] / qemu-doc.texi
1 \input texinfo @c -*- texinfo -*-
2 @c %**start of header
3 @setfilename qemu-doc.info
4 @include version.texi
5
6 @documentlanguage en
7 @documentencoding UTF-8
8
9 @settitle QEMU version @value{VERSION} User Documentation
10 @exampleindent 0
11 @paragraphindent 0
12 @c %**end of header
13
14 @set qemu_system qemu-system-x86_64
15 @set qemu_system_x86 qemu-system-x86_64
16
17 @ifinfo
18 @direntry
19 * QEMU: (qemu-doc).    The QEMU Emulator User Documentation.
20 @end direntry
21 @end ifinfo
22
23 @iftex
24 @titlepage
25 @sp 7
26 @center @titlefont{QEMU version @value{VERSION}}
27 @sp 1
28 @center @titlefont{User Documentation}
29 @sp 3
30 @end titlepage
31 @end iftex
32
33 @ifnottex
34 @node Top
35 @top
36
37 @menu
38 * Introduction::
39 * QEMU PC System emulator::
40 * QEMU System emulator for non PC targets::
41 * QEMU Guest Agent::
42 * QEMU User space emulator::
43 * System requirements::
44 * Security::
45 * Implementation notes::
46 * Deprecated features::
47 * Recently removed features::
48 * Supported build platforms::
49 * License::
50 * Index::
51 @end menu
52 @end ifnottex
53
54 @contents
55
56 @node Introduction
57 @chapter Introduction
58
59 @menu
60 * intro_features:: Features
61 @end menu
62
63 @node intro_features
64 @section Features
65
66 QEMU is a FAST! processor emulator using dynamic translation to
67 achieve good emulation speed.
68
69 @cindex operating modes
70 QEMU has two operating modes:
71
72 @itemize
73 @cindex system emulation
74 @item Full system emulation. In this mode, QEMU emulates a full system (for
75 example a PC), including one or several processors and various
76 peripherals. It can be used to launch different Operating Systems
77 without rebooting the PC or to debug system code.
78
79 @cindex user mode emulation
80 @item User mode emulation. In this mode, QEMU can launch
81 processes compiled for one CPU on another CPU. It can be used to
82 launch the Wine Windows API emulator (@url{https://www.winehq.org}) or
83 to ease cross-compilation and cross-debugging.
84
85 @end itemize
86
87 QEMU has the following features:
88
89 @itemize
90 @item QEMU can run without a host kernel driver and yet gives acceptable
91 performance.  It uses dynamic translation to native code for reasonable speed,
92 with support for self-modifying code and precise exceptions.
93
94 @item It is portable to several operating systems (GNU/Linux, *BSD, Mac OS X,
95 Windows) and architectures.
96
97 @item It performs accurate software emulation of the FPU.
98 @end itemize
99
100 QEMU user mode emulation has the following features:
101 @itemize
102 @item Generic Linux system call converter, including most ioctls.
103
104 @item clone() emulation using native CPU clone() to use Linux scheduler for threads.
105
106 @item Accurate signal handling by remapping host signals to target signals.
107 @end itemize
108
109 QEMU full system emulation has the following features:
110 @itemize
111 @item
112 QEMU uses a full software MMU for maximum portability.
113
114 @item
115 QEMU can optionally use an in-kernel accelerator, like kvm. The accelerators
116 execute most of the guest code natively, while
117 continuing to emulate the rest of the machine.
118
119 @item
120 Various hardware devices can be emulated and in some cases, host
121 devices (e.g. serial and parallel ports, USB, drives) can be used
122 transparently by the guest Operating System. Host device passthrough
123 can be used for talking to external physical peripherals (e.g. a
124 webcam, modem or tape drive).
125
126 @item
127 Symmetric multiprocessing (SMP) support.  Currently, an in-kernel
128 accelerator is required to use more than one host CPU for emulation.
129
130 @end itemize
131
132
133 @node QEMU PC System emulator
134 @chapter QEMU PC System emulator
135 @cindex system emulation (PC)
136
137 @menu
138 * pcsys_introduction:: Introduction
139 * pcsys_quickstart::   Quick Start
140 * sec_invocation::     Invocation
141 * pcsys_keys::         Keys in the graphical frontends
142 * mux_keys::           Keys in the character backend multiplexer
143 * pcsys_monitor::      QEMU Monitor
144 * cpu_models::         CPU models
145 * disk_images::        Disk Images
146 * pcsys_network::      Network emulation
147 * pcsys_other_devs::   Other Devices
148 * direct_linux_boot::  Direct Linux Boot
149 * pcsys_usb::          USB emulation
150 * vnc_security::       VNC security
151 * network_tls::        TLS setup for network services
152 * gdb_usage::          GDB usage
153 * pcsys_os_specific::  Target OS specific information
154 @end menu
155
156 @node pcsys_introduction
157 @section Introduction
158
159 @c man begin DESCRIPTION
160
161 The QEMU PC System emulator simulates the
162 following peripherals:
163
164 @itemize @minus
165 @item
166 i440FX host PCI bridge and PIIX3 PCI to ISA bridge
167 @item
168 Cirrus CLGD 5446 PCI VGA card or dummy VGA card with Bochs VESA
169 extensions (hardware level, including all non standard modes).
170 @item
171 PS/2 mouse and keyboard
172 @item
173 2 PCI IDE interfaces with hard disk and CD-ROM support
174 @item
175 Floppy disk
176 @item
177 PCI and ISA network adapters
178 @item
179 Serial ports
180 @item
181 IPMI BMC, either and internal or external one
182 @item
183 Creative SoundBlaster 16 sound card
184 @item
185 ENSONIQ AudioPCI ES1370 sound card
186 @item
187 Intel 82801AA AC97 Audio compatible sound card
188 @item
189 Intel HD Audio Controller and HDA codec
190 @item
191 Adlib (OPL2) - Yamaha YM3812 compatible chip
192 @item
193 Gravis Ultrasound GF1 sound card
194 @item
195 CS4231A compatible sound card
196 @item
197 PCI UHCI, OHCI, EHCI or XHCI USB controller and a virtual USB-1.1 hub.
198 @end itemize
199
200 SMP is supported with up to 255 CPUs.
201
202 QEMU uses the PC BIOS from the Seabios project and the Plex86/Bochs LGPL
203 VGA BIOS.
204
205 QEMU uses YM3812 emulation by Tatsuyuki Satoh.
206
207 QEMU uses GUS emulation (GUSEMU32 @url{http://www.deinmeister.de/gusemu/})
208 by Tibor "TS" Schütz.
209
210 Note that, by default, GUS shares IRQ(7) with parallel ports and so
211 QEMU must be told to not have parallel ports to have working GUS.
212
213 @example
214 @value{qemu_system_x86} dos.img -soundhw gus -parallel none
215 @end example
216
217 Alternatively:
218 @example
219 @value{qemu_system_x86} dos.img -device gus,irq=5
220 @end example
221
222 Or some other unclaimed IRQ.
223
224 CS4231A is the chip used in Windows Sound System and GUSMAX products
225
226 @c man end
227
228 @node pcsys_quickstart
229 @section Quick Start
230 @cindex quick start
231
232 Download and uncompress a hard disk image with Linux installed (e.g.
233 @file{linux.img}) and type:
234
235 @example
236 @value{qemu_system} linux.img
237 @end example
238
239 Linux should boot and give you a prompt.
240
241 @node sec_invocation
242 @section Invocation
243
244 @example
245 @c man begin SYNOPSIS
246 @command{@value{qemu_system}} [@var{options}] [@var{disk_image}]
247 @c man end
248 @end example
249
250 @c man begin OPTIONS
251 @var{disk_image} is a raw hard disk image for IDE hard disk 0. Some
252 targets do not need a disk image.
253
254 @include qemu-options.texi
255
256 @c man end
257
258 @subsection Device URL Syntax
259 @c TODO merge this with section Disk Images
260
261 @c man begin NOTES
262
263 In addition to using normal file images for the emulated storage devices,
264 QEMU can also use networked resources such as iSCSI devices. These are
265 specified using a special URL syntax.
266
267 @table @option
268 @item iSCSI
269 iSCSI support allows QEMU to access iSCSI resources directly and use as
270 images for the guest storage. Both disk and cdrom images are supported.
271
272 Syntax for specifying iSCSI LUNs is
273 ``iscsi://<target-ip>[:<port>]/<target-iqn>/<lun>''
274
275 By default qemu will use the iSCSI initiator-name
276 'iqn.2008-11.org.linux-kvm[:<name>]' but this can also be set from the command
277 line or a configuration file.
278
279 Since version Qemu 2.4 it is possible to specify a iSCSI request timeout to detect
280 stalled requests and force a reestablishment of the session. The timeout
281 is specified in seconds. The default is 0 which means no timeout. Libiscsi
282 1.15.0 or greater is required for this feature.
283
284 Example (without authentication):
285 @example
286 @value{qemu_system} -iscsi initiator-name=iqn.2001-04.com.example:my-initiator \
287                  -cdrom iscsi://192.0.2.1/iqn.2001-04.com.example/2 \
288                  -drive file=iscsi://192.0.2.1/iqn.2001-04.com.example/1
289 @end example
290
291 Example (CHAP username/password via URL):
292 @example
293 @value{qemu_system} -drive file=iscsi://user%password@@192.0.2.1/iqn.2001-04.com.example/1
294 @end example
295
296 Example (CHAP username/password via environment variables):
297 @example
298 LIBISCSI_CHAP_USERNAME="user" \
299 LIBISCSI_CHAP_PASSWORD="password" \
300 @value{qemu_system} -drive file=iscsi://192.0.2.1/iqn.2001-04.com.example/1
301 @end example
302
303 @item NBD
304 QEMU supports NBD (Network Block Devices) both using TCP protocol as well
305 as Unix Domain Sockets.  With TCP, the default port is 10809.
306
307 Syntax for specifying a NBD device using TCP, in preferred URI form:
308 ``nbd://<server-ip>[:<port>]/[<export>]''
309
310 Syntax for specifying a NBD device using Unix Domain Sockets; remember
311 that '?' is a shell glob character and may need quoting:
312 ``nbd+unix:///[<export>]?socket=<domain-socket>''
313
314 Older syntax that is also recognized:
315 ``nbd:<server-ip>:<port>[:exportname=<export>]''
316
317 Syntax for specifying a NBD device using Unix Domain Sockets
318 ``nbd:unix:<domain-socket>[:exportname=<export>]''
319
320 Example for TCP
321 @example
322 @value{qemu_system} --drive file=nbd:192.0.2.1:30000
323 @end example
324
325 Example for Unix Domain Sockets
326 @example
327 @value{qemu_system} --drive file=nbd:unix:/tmp/nbd-socket
328 @end example
329
330 @item SSH
331 QEMU supports SSH (Secure Shell) access to remote disks.
332
333 Examples:
334 @example
335 @value{qemu_system} -drive file=ssh://user@@host/path/to/disk.img
336 @value{qemu_system} -drive file.driver=ssh,file.user=user,file.host=host,file.port=22,file.path=/path/to/disk.img
337 @end example
338
339 Currently authentication must be done using ssh-agent.  Other
340 authentication methods may be supported in future.
341
342 @item Sheepdog
343 Sheepdog is a distributed storage system for QEMU.
344 QEMU supports using either local sheepdog devices or remote networked
345 devices.
346
347 Syntax for specifying a sheepdog device
348 @example
349 sheepdog[+tcp|+unix]://[host:port]/vdiname[?socket=path][#snapid|#tag]
350 @end example
351
352 Example
353 @example
354 @value{qemu_system} --drive file=sheepdog://192.0.2.1:30000/MyVirtualMachine
355 @end example
356
357 See also @url{https://sheepdog.github.io/sheepdog/}.
358
359 @item GlusterFS
360 GlusterFS is a user space distributed file system.
361 QEMU supports the use of GlusterFS volumes for hosting VM disk images using
362 TCP, Unix Domain Sockets and RDMA transport protocols.
363
364 Syntax for specifying a VM disk image on GlusterFS volume is
365 @example
366
367 URI:
368 gluster[+type]://[host[:port]]/volume/path[?socket=...][,debug=N][,logfile=...]
369
370 JSON:
371 'json:@{"driver":"qcow2","file":@{"driver":"gluster","volume":"testvol","path":"a.img","debug":N,"logfile":"...",
372 @                                 "server":[@{"type":"tcp","host":"...","port":"..."@},
373 @                                           @{"type":"unix","socket":"..."@}]@}@}'
374 @end example
375
376
377 Example
378 @example
379 URI:
380 @value{qemu_system} --drive file=gluster://192.0.2.1/testvol/a.img,
381 @                               file.debug=9,file.logfile=/var/log/qemu-gluster.log
382
383 JSON:
384 @value{qemu_system} 'json:@{"driver":"qcow2",
385 @                          "file":@{"driver":"gluster",
386 @                                   "volume":"testvol","path":"a.img",
387 @                                   "debug":9,"logfile":"/var/log/qemu-gluster.log",
388 @                                   "server":[@{"type":"tcp","host":"1.2.3.4","port":24007@},
389 @                                             @{"type":"unix","socket":"/var/run/glusterd.socket"@}]@}@}'
390 @value{qemu_system} -drive driver=qcow2,file.driver=gluster,file.volume=testvol,file.path=/path/a.img,
391 @                                      file.debug=9,file.logfile=/var/log/qemu-gluster.log,
392 @                                      file.server.0.type=tcp,file.server.0.host=1.2.3.4,file.server.0.port=24007,
393 @                                      file.server.1.type=unix,file.server.1.socket=/var/run/glusterd.socket
394 @end example
395
396 See also @url{http://www.gluster.org}.
397
398 @item HTTP/HTTPS/FTP/FTPS
399 QEMU supports read-only access to files accessed over http(s) and ftp(s).
400
401 Syntax using a single filename:
402 @example
403 <protocol>://[<username>[:<password>]@@]<host>/<path>
404 @end example
405
406 where:
407 @table @option
408 @item protocol
409 'http', 'https', 'ftp', or 'ftps'.
410
411 @item username
412 Optional username for authentication to the remote server.
413
414 @item password
415 Optional password for authentication to the remote server.
416
417 @item host
418 Address of the remote server.
419
420 @item path
421 Path on the remote server, including any query string.
422 @end table
423
424 The following options are also supported:
425 @table @option
426 @item url
427 The full URL when passing options to the driver explicitly.
428
429 @item readahead
430 The amount of data to read ahead with each range request to the remote server.
431 This value may optionally have the suffix 'T', 'G', 'M', 'K', 'k' or 'b'. If it
432 does not have a suffix, it will be assumed to be in bytes. The value must be a
433 multiple of 512 bytes. It defaults to 256k.
434
435 @item sslverify
436 Whether to verify the remote server's certificate when connecting over SSL. It
437 can have the value 'on' or 'off'. It defaults to 'on'.
438
439 @item cookie
440 Send this cookie (it can also be a list of cookies separated by ';') with
441 each outgoing request.  Only supported when using protocols such as HTTP
442 which support cookies, otherwise ignored.
443
444 @item timeout
445 Set the timeout in seconds of the CURL connection. This timeout is the time
446 that CURL waits for a response from the remote server to get the size of the
447 image to be downloaded. If not set, the default timeout of 5 seconds is used.
448 @end table
449
450 Note that when passing options to qemu explicitly, @option{driver} is the value
451 of <protocol>.
452
453 Example: boot from a remote Fedora 20 live ISO image
454 @example
455 @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
456
457 @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
458 @end example
459
460 Example: boot from a remote Fedora 20 cloud image using a local overlay for
461 writes, copy-on-read, and a readahead of 64k
462 @example
463 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
464
465 @value{qemu_system_x86} -drive file=/tmp/Fedora-x86_64-20-20131211.1-sda.qcow2,copy-on-read=on
466 @end example
467
468 Example: boot from an image stored on a VMware vSphere server with a self-signed
469 certificate using a local overlay for writes, a readahead of 64k and a timeout
470 of 10 seconds.
471 @example
472 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
473
474 @value{qemu_system_x86} -drive file=/tmp/test.qcow2
475 @end example
476
477 @end table
478
479 @c man end
480
481 @node pcsys_keys
482 @section Keys in the graphical frontends
483
484 @c man begin OPTIONS
485
486 During the graphical emulation, you can use special key combinations to change
487 modes. The default key mappings are shown below, but if you use @code{-alt-grab}
488 then the modifier is Ctrl-Alt-Shift (instead of Ctrl-Alt) and if you use
489 @code{-ctrl-grab} then the modifier is the right Ctrl key (instead of Ctrl-Alt):
490
491 @table @key
492 @item Ctrl-Alt-f
493 @kindex Ctrl-Alt-f
494 Toggle full screen
495
496 @item Ctrl-Alt-+
497 @kindex Ctrl-Alt-+
498 Enlarge the screen
499
500 @item Ctrl-Alt--
501 @kindex Ctrl-Alt--
502 Shrink the screen
503
504 @item Ctrl-Alt-u
505 @kindex Ctrl-Alt-u
506 Restore the screen's un-scaled dimensions
507
508 @item Ctrl-Alt-n
509 @kindex Ctrl-Alt-n
510 Switch to virtual console 'n'. Standard console mappings are:
511 @table @emph
512 @item 1
513 Target system display
514 @item 2
515 Monitor
516 @item 3
517 Serial port
518 @end table
519
520 @item Ctrl-Alt
521 @kindex Ctrl-Alt
522 Toggle mouse and keyboard grab.
523 @end table
524
525 @kindex Ctrl-Up
526 @kindex Ctrl-Down
527 @kindex Ctrl-PageUp
528 @kindex Ctrl-PageDown
529 In the virtual consoles, you can use @key{Ctrl-Up}, @key{Ctrl-Down},
530 @key{Ctrl-PageUp} and @key{Ctrl-PageDown} to move in the back log.
531
532 @c man end
533
534 @node mux_keys
535 @section Keys in the character backend multiplexer
536
537 @c man begin OPTIONS
538
539 During emulation, if you are using a character backend multiplexer
540 (which is the default if you are using @option{-nographic}) then
541 several commands are available via an escape sequence. These
542 key sequences all start with an escape character, which is @key{Ctrl-a}
543 by default, but can be changed with @option{-echr}. The list below assumes
544 you're using the default.
545
546 @table @key
547 @item Ctrl-a h
548 @kindex Ctrl-a h
549 Print this help
550 @item Ctrl-a x
551 @kindex Ctrl-a x
552 Exit emulator
553 @item Ctrl-a s
554 @kindex Ctrl-a s
555 Save disk data back to file (if -snapshot)
556 @item Ctrl-a t
557 @kindex Ctrl-a t
558 Toggle console timestamps
559 @item Ctrl-a b
560 @kindex Ctrl-a b
561 Send break (magic sysrq in Linux)
562 @item Ctrl-a c
563 @kindex Ctrl-a c
564 Rotate between the frontends connected to the multiplexer (usually
565 this switches between the monitor and the console)
566 @item Ctrl-a Ctrl-a
567 @kindex Ctrl-a Ctrl-a
568 Send the escape character to the frontend
569 @end table
570 @c man end
571
572 @ignore
573
574 @c man begin SEEALSO
575 The HTML documentation of QEMU for more precise information and Linux
576 user mode emulator invocation.
577 @c man end
578
579 @c man begin AUTHOR
580 Fabrice Bellard
581 @c man end
582
583 @end ignore
584
585 @node pcsys_monitor
586 @section QEMU Monitor
587 @cindex QEMU monitor
588
589 The QEMU monitor is used to give complex commands to the QEMU
590 emulator. You can use it to:
591
592 @itemize @minus
593
594 @item
595 Remove or insert removable media images
596 (such as CD-ROM or floppies).
597
598 @item
599 Freeze/unfreeze the Virtual Machine (VM) and save or restore its state
600 from a disk file.
601
602 @item Inspect the VM state without an external debugger.
603
604 @end itemize
605
606 @subsection Commands
607
608 The following commands are available:
609
610 @include qemu-monitor.texi
611
612 @include qemu-monitor-info.texi
613
614 @subsection Integer expressions
615
616 The monitor understands integers expressions for every integer
617 argument. You can use register names to get the value of specifics
618 CPU registers by prefixing them with @emph{$}.
619
620 @node cpu_models
621 @section CPU models
622
623 @include docs/qemu-cpu-models.texi
624
625 @node disk_images
626 @section Disk Images
627
628 QEMU supports many disk image formats, including growable disk images
629 (their size increase as non empty sectors are written), compressed and
630 encrypted disk images.
631
632 @menu
633 * disk_images_quickstart::    Quick start for disk image creation
634 * disk_images_snapshot_mode:: Snapshot mode
635 * vm_snapshots::              VM snapshots
636 * qemu_img_invocation::       qemu-img Invocation
637 * qemu_nbd_invocation::       qemu-nbd Invocation
638 * disk_images_formats::       Disk image file formats
639 * host_drives::               Using host drives
640 * disk_images_fat_images::    Virtual FAT disk images
641 * disk_images_nbd::           NBD access
642 * disk_images_sheepdog::      Sheepdog disk images
643 * disk_images_iscsi::         iSCSI LUNs
644 * disk_images_gluster::       GlusterFS disk images
645 * disk_images_ssh::           Secure Shell (ssh) disk images
646 * disk_images_nvme::          NVMe userspace driver
647 * disk_image_locking::        Disk image file locking
648 @end menu
649
650 @node disk_images_quickstart
651 @subsection Quick start for disk image creation
652
653 You can create a disk image with the command:
654 @example
655 qemu-img create myimage.img mysize
656 @end example
657 where @var{myimage.img} is the disk image filename and @var{mysize} is its
658 size in kilobytes. You can add an @code{M} suffix to give the size in
659 megabytes and a @code{G} suffix for gigabytes.
660
661 See @ref{qemu_img_invocation} for more information.
662
663 @node disk_images_snapshot_mode
664 @subsection Snapshot mode
665
666 If you use the option @option{-snapshot}, all disk images are
667 considered as read only. When sectors in written, they are written in
668 a temporary file created in @file{/tmp}. You can however force the
669 write back to the raw disk images by using the @code{commit} monitor
670 command (or @key{C-a s} in the serial console).
671
672 @node vm_snapshots
673 @subsection VM snapshots
674
675 VM snapshots are snapshots of the complete virtual machine including
676 CPU state, RAM, device state and the content of all the writable
677 disks. In order to use VM snapshots, you must have at least one non
678 removable and writable block device using the @code{qcow2} disk image
679 format. Normally this device is the first virtual hard drive.
680
681 Use the monitor command @code{savevm} to create a new VM snapshot or
682 replace an existing one. A human readable name can be assigned to each
683 snapshot in addition to its numerical ID.
684
685 Use @code{loadvm} to restore a VM snapshot and @code{delvm} to remove
686 a VM snapshot. @code{info snapshots} lists the available snapshots
687 with their associated information:
688
689 @example
690 (qemu) info snapshots
691 Snapshot devices: hda
692 Snapshot list (from hda):
693 ID        TAG                 VM SIZE                DATE       VM CLOCK
694 1         start                   41M 2006-08-06 12:38:02   00:00:14.954
695 2                                 40M 2006-08-06 12:43:29   00:00:18.633
696 3         msys                    40M 2006-08-06 12:44:04   00:00:23.514
697 @end example
698
699 A VM snapshot is made of a VM state info (its size is shown in
700 @code{info snapshots}) and a snapshot of every writable disk image.
701 The VM state info is stored in the first @code{qcow2} non removable
702 and writable block device. The disk image snapshots are stored in
703 every disk image. The size of a snapshot in a disk image is difficult
704 to evaluate and is not shown by @code{info snapshots} because the
705 associated disk sectors are shared among all the snapshots to save
706 disk space (otherwise each snapshot would need a full copy of all the
707 disk images).
708
709 When using the (unrelated) @code{-snapshot} option
710 (@ref{disk_images_snapshot_mode}), you can always make VM snapshots,
711 but they are deleted as soon as you exit QEMU.
712
713 VM snapshots currently have the following known limitations:
714 @itemize
715 @item
716 They cannot cope with removable devices if they are removed or
717 inserted after a snapshot is done.
718 @item
719 A few device drivers still have incomplete snapshot support so their
720 state is not saved or restored properly (in particular USB).
721 @end itemize
722
723 @node qemu_img_invocation
724 @subsection @code{qemu-img} Invocation
725
726 @include qemu-img.texi
727
728 @node qemu_nbd_invocation
729 @subsection @code{qemu-nbd} Invocation
730
731 @include qemu-nbd.texi
732
733 @include docs/qemu-block-drivers.texi
734
735 @node pcsys_network
736 @section Network emulation
737
738 QEMU can simulate several network cards (e.g. PCI or ISA cards on the PC
739 target) and can connect them to a network backend on the host or an emulated
740 hub. The various host network backends can either be used to connect the NIC of
741 the guest to a real network (e.g. by using a TAP devices or the non-privileged
742 user mode network stack), or to other guest instances running in another QEMU
743 process (e.g. by using the socket host network backend).
744
745 @subsection Using TAP network interfaces
746
747 This is the standard way to connect QEMU to a real network. QEMU adds
748 a virtual network device on your host (called @code{tapN}), and you
749 can then configure it as if it was a real ethernet card.
750
751 @subsubsection Linux host
752
753 As an example, you can download the @file{linux-test-xxx.tar.gz}
754 archive and copy the script @file{qemu-ifup} in @file{/etc} and
755 configure properly @code{sudo} so that the command @code{ifconfig}
756 contained in @file{qemu-ifup} can be executed as root. You must verify
757 that your host kernel supports the TAP network interfaces: the
758 device @file{/dev/net/tun} must be present.
759
760 See @ref{sec_invocation} to have examples of command lines using the
761 TAP network interfaces.
762
763 @subsubsection Windows host
764
765 There is a virtual ethernet driver for Windows 2000/XP systems, called
766 TAP-Win32. But it is not included in standard QEMU for Windows,
767 so you will need to get it separately. It is part of OpenVPN package,
768 so download OpenVPN from : @url{https://openvpn.net/}.
769
770 @subsection Using the user mode network stack
771
772 By using the option @option{-net user} (default configuration if no
773 @option{-net} option is specified), QEMU uses a completely user mode
774 network stack (you don't need root privilege to use the virtual
775 network). The virtual network configuration is the following:
776
777 @example
778
779      guest (10.0.2.15)  <------>  Firewall/DHCP server <-----> Internet
780                            |          (10.0.2.2)
781                            |
782                            ---->  DNS server (10.0.2.3)
783                            |
784                            ---->  SMB server (10.0.2.4)
785 @end example
786
787 The QEMU VM behaves as if it was behind a firewall which blocks all
788 incoming connections. You can use a DHCP client to automatically
789 configure the network in the QEMU VM. The DHCP server assign addresses
790 to the hosts starting from 10.0.2.15.
791
792 In order to check that the user mode network is working, you can ping
793 the address 10.0.2.2 and verify that you got an address in the range
794 10.0.2.x from the QEMU virtual DHCP server.
795
796 Note that ICMP traffic in general does not work with user mode networking.
797 @code{ping}, aka. ICMP echo, to the local router (10.0.2.2) shall work,
798 however. If you're using QEMU on Linux >= 3.0, it can use unprivileged ICMP
799 ping sockets to allow @code{ping} to the Internet. The host admin has to set
800 the ping_group_range in order to grant access to those sockets. To allow ping
801 for GID 100 (usually users group):
802
803 @example
804 echo 100 100 > /proc/sys/net/ipv4/ping_group_range
805 @end example
806
807 When using the built-in TFTP server, the router is also the TFTP
808 server.
809
810 When using the @option{'-netdev user,hostfwd=...'} option, TCP or UDP
811 connections can be redirected from the host to the guest. It allows for
812 example to redirect X11, telnet or SSH connections.
813
814 @subsection Hubs
815
816 QEMU can simulate several hubs. A hub can be thought of as a virtual connection
817 between several network devices. These devices can be for example QEMU virtual
818 ethernet cards or virtual Host ethernet devices (TAP devices). You can connect
819 guest NICs or host network backends to such a hub using the @option{-netdev
820 hubport} or @option{-nic hubport} options. The legacy @option{-net} option
821 also connects the given device to the emulated hub with ID 0 (i.e. the default
822 hub) unless you specify a netdev with @option{-net nic,netdev=xxx} here.
823
824 @subsection Connecting emulated networks between QEMU instances
825
826 Using the @option{-netdev socket} (or @option{-nic socket} or
827 @option{-net socket}) option, it is possible to create emulated
828 networks that span several QEMU instances.
829 See the description of the @option{-netdev socket} option in the
830 @ref{sec_invocation,,Invocation chapter} to have a basic example.
831
832 @node pcsys_other_devs
833 @section Other Devices
834
835 @subsection Inter-VM Shared Memory device
836
837 On Linux hosts, a shared memory device is available.  The basic syntax
838 is:
839
840 @example
841 @value{qemu_system_x86} -device ivshmem-plain,memdev=@var{hostmem}
842 @end example
843
844 where @var{hostmem} names a host memory backend.  For a POSIX shared
845 memory backend, use something like
846
847 @example
848 -object memory-backend-file,size=1M,share,mem-path=/dev/shm/ivshmem,id=@var{hostmem}
849 @end example
850
851 If desired, interrupts can be sent between guest VMs accessing the same shared
852 memory region.  Interrupt support requires using a shared memory server and
853 using a chardev socket to connect to it.  The code for the shared memory server
854 is qemu.git/contrib/ivshmem-server.  An example syntax when using the shared
855 memory server is:
856
857 @example
858 # First start the ivshmem server once and for all
859 ivshmem-server -p @var{pidfile} -S @var{path} -m @var{shm-name} -l @var{shm-size} -n @var{vectors}
860
861 # Then start your qemu instances with matching arguments
862 @value{qemu_system_x86} -device ivshmem-doorbell,vectors=@var{vectors},chardev=@var{id}
863                  -chardev socket,path=@var{path},id=@var{id}
864 @end example
865
866 When using the server, the guest will be assigned a VM ID (>=0) that allows guests
867 using the same server to communicate via interrupts.  Guests can read their
868 VM ID from a device register (see ivshmem-spec.txt).
869
870 @subsubsection Migration with ivshmem
871
872 With device property @option{master=on}, the guest will copy the shared
873 memory on migration to the destination host.  With @option{master=off},
874 the guest will not be able to migrate with the device attached.  In the
875 latter case, the device should be detached and then reattached after
876 migration using the PCI hotplug support.
877
878 At most one of the devices sharing the same memory can be master.  The
879 master must complete migration before you plug back the other devices.
880
881 @subsubsection ivshmem and hugepages
882
883 Instead of specifying the <shm size> using POSIX shm, you may specify
884 a memory backend that has hugepage support:
885
886 @example
887 @value{qemu_system_x86} -object memory-backend-file,size=1G,mem-path=/dev/hugepages/my-shmem-file,share,id=mb1
888                  -device ivshmem-plain,memdev=mb1
889 @end example
890
891 ivshmem-server also supports hugepages mount points with the
892 @option{-m} memory path argument.
893
894 @node direct_linux_boot
895 @section Direct Linux Boot
896
897 This section explains how to launch a Linux kernel inside QEMU without
898 having to make a full bootable image. It is very useful for fast Linux
899 kernel testing.
900
901 The syntax is:
902 @example
903 @value{qemu_system} -kernel bzImage -hda rootdisk.img -append "root=/dev/hda"
904 @end example
905
906 Use @option{-kernel} to provide the Linux kernel image and
907 @option{-append} to give the kernel command line arguments. The
908 @option{-initrd} option can be used to provide an INITRD image.
909
910 If you do not need graphical output, you can disable it and redirect
911 the virtual serial port and the QEMU monitor to the console with the
912 @option{-nographic} option. The typical command line is:
913 @example
914 @value{qemu_system} -kernel bzImage -hda rootdisk.img \
915                  -append "root=/dev/hda console=ttyS0" -nographic
916 @end example
917
918 Use @key{Ctrl-a c} to switch between the serial console and the
919 monitor (@pxref{pcsys_keys}).
920
921 @node pcsys_usb
922 @section USB emulation
923
924 QEMU can emulate a PCI UHCI, OHCI, EHCI or XHCI USB controller. You can
925 plug virtual USB devices or real host USB devices (only works with certain
926 host operating systems). QEMU will automatically create and connect virtual
927 USB hubs as necessary to connect multiple USB devices.
928
929 @menu
930 * usb_devices::
931 * host_usb_devices::
932 @end menu
933 @node usb_devices
934 @subsection Connecting USB devices
935
936 USB devices can be connected with the @option{-device usb-...} command line
937 option or the @code{device_add} monitor command. Available devices are:
938
939 @table @code
940 @item usb-mouse
941 Virtual Mouse.  This will override the PS/2 mouse emulation when activated.
942 @item usb-tablet
943 Pointer device that uses absolute coordinates (like a touchscreen).
944 This means QEMU is able to report the mouse position without having
945 to grab the mouse.  Also overrides the PS/2 mouse emulation when activated.
946 @item usb-storage,drive=@var{drive_id}
947 Mass storage device backed by @var{drive_id} (@pxref{disk_images})
948 @item usb-uas
949 USB attached SCSI device, see
950 @url{https://git.qemu.org/?p=qemu.git;a=blob_plain;f=docs/usb-storage.txt,usb-storage.txt}
951 for details
952 @item usb-bot
953 Bulk-only transport storage device, see
954 @url{https://git.qemu.org/?p=qemu.git;a=blob_plain;f=docs/usb-storage.txt,usb-storage.txt}
955 for details here, too
956 @item usb-mtp,rootdir=@var{dir}
957 Media transfer protocol device, using @var{dir} as root of the file tree
958 that is presented to the guest.
959 @item usb-host,hostbus=@var{bus},hostaddr=@var{addr}
960 Pass through the host device identified by @var{bus} and @var{addr}
961 @item usb-host,vendorid=@var{vendor},productid=@var{product}
962 Pass through the host device identified by @var{vendor} and @var{product} ID
963 @item usb-wacom-tablet
964 Virtual Wacom PenPartner tablet.  This device is similar to the @code{tablet}
965 above but it can be used with the tslib library because in addition to touch
966 coordinates it reports touch pressure.
967 @item usb-kbd
968 Standard USB keyboard.  Will override the PS/2 keyboard (if present).
969 @item usb-serial,chardev=@var{id}
970 Serial converter. This emulates an FTDI FT232BM chip connected to host character
971 device @var{id}.
972 @item usb-braille,chardev=@var{id}
973 Braille device.  This will use BrlAPI to display the braille output on a real
974 or fake device referenced by @var{id}.
975 @item usb-net[,netdev=@var{id}]
976 Network adapter that supports CDC ethernet and RNDIS protocols.  @var{id}
977 specifies a netdev defined with @code{-netdev @dots{},id=@var{id}}.
978 For instance, user-mode networking can be used with
979 @example
980 @value{qemu_system} [...] -netdev user,id=net0 -device usb-net,netdev=net0
981 @end example
982 @item usb-ccid
983 Smartcard reader device
984 @item usb-audio
985 USB audio device
986 @item usb-bt-dongle
987 Bluetooth dongle for the transport layer of HCI. It is connected to HCI
988 scatternet 0 by default (corresponds to @code{-bt hci,vlan=0}).
989 Note that the syntax for the @code{-device usb-bt-dongle} option is not as
990 useful yet as it was with the legacy @code{-usbdevice} option. So to
991 configure an USB bluetooth device, you might need to use
992 "@code{-usbdevice bt}[:@var{hci-type}]" instead. This configures a
993 bluetooth dongle whose type is specified in the same format as with
994 the @option{-bt hci} option, @pxref{bt-hcis,,allowed HCI types}.  If
995 no type is given, the HCI logic corresponds to @code{-bt hci,vlan=0}.
996 This USB device implements the USB Transport Layer of HCI.  Example
997 usage:
998 @example
999 @command{@value{qemu_system}} [...@var{OPTIONS}...] @option{-usbdevice} bt:hci,vlan=3 @option{-bt} device:keyboard,vlan=3
1000 @end example
1001 @end table
1002
1003 @node host_usb_devices
1004 @subsection Using host USB devices on a Linux host
1005
1006 WARNING: this is an experimental feature. QEMU will slow down when
1007 using it. USB devices requiring real time streaming (i.e. USB Video
1008 Cameras) are not supported yet.
1009
1010 @enumerate
1011 @item If you use an early Linux 2.4 kernel, verify that no Linux driver
1012 is actually using the USB device. A simple way to do that is simply to
1013 disable the corresponding kernel module by renaming it from @file{mydriver.o}
1014 to @file{mydriver.o.disabled}.
1015
1016 @item Verify that @file{/proc/bus/usb} is working (most Linux distributions should enable it by default). You should see something like that:
1017 @example
1018 ls /proc/bus/usb
1019 001  devices  drivers
1020 @end example
1021
1022 @item Since only root can access to the USB devices directly, you can either launch QEMU as root or change the permissions of the USB devices you want to use. For testing, the following suffices:
1023 @example
1024 chown -R myuid /proc/bus/usb
1025 @end example
1026
1027 @item Launch QEMU and do in the monitor:
1028 @example
1029 info usbhost
1030   Device 1.2, speed 480 Mb/s
1031     Class 00: USB device 1234:5678, USB DISK
1032 @end example
1033 You should see the list of the devices you can use (Never try to use
1034 hubs, it won't work).
1035
1036 @item Add the device in QEMU by using:
1037 @example
1038 device_add usb-host,vendorid=0x1234,productid=0x5678
1039 @end example
1040
1041 Normally the guest OS should report that a new USB device is plugged.
1042 You can use the option @option{-device usb-host,...} to do the same.
1043
1044 @item Now you can try to use the host USB device in QEMU.
1045
1046 @end enumerate
1047
1048 When relaunching QEMU, you may have to unplug and plug again the USB
1049 device to make it work again (this is a bug).
1050
1051 @node vnc_security
1052 @section VNC security
1053
1054 The VNC server capability provides access to the graphical console
1055 of the guest VM across the network. This has a number of security
1056 considerations depending on the deployment scenarios.
1057
1058 @menu
1059 * vnc_sec_none::
1060 * vnc_sec_password::
1061 * vnc_sec_certificate::
1062 * vnc_sec_certificate_verify::
1063 * vnc_sec_certificate_pw::
1064 * vnc_sec_sasl::
1065 * vnc_sec_certificate_sasl::
1066 * vnc_setup_sasl::
1067 @end menu
1068 @node vnc_sec_none
1069 @subsection Without passwords
1070
1071 The simplest VNC server setup does not include any form of authentication.
1072 For this setup it is recommended to restrict it to listen on a UNIX domain
1073 socket only. For example
1074
1075 @example
1076 @value{qemu_system} [...OPTIONS...] -vnc unix:/home/joebloggs/.qemu-myvm-vnc
1077 @end example
1078
1079 This ensures that only users on local box with read/write access to that
1080 path can access the VNC server. To securely access the VNC server from a
1081 remote machine, a combination of netcat+ssh can be used to provide a secure
1082 tunnel.
1083
1084 @node vnc_sec_password
1085 @subsection With passwords
1086
1087 The VNC protocol has limited support for password based authentication. Since
1088 the protocol limits passwords to 8 characters it should not be considered
1089 to provide high security. The password can be fairly easily brute-forced by
1090 a client making repeat connections. For this reason, a VNC server using password
1091 authentication should be restricted to only listen on the loopback interface
1092 or UNIX domain sockets. Password authentication is not supported when operating
1093 in FIPS 140-2 compliance mode as it requires the use of the DES cipher. Password
1094 authentication is requested with the @code{password} option, and then once QEMU
1095 is running the password is set with the monitor. Until the monitor is used to
1096 set the password all clients will be rejected.
1097
1098 @example
1099 @value{qemu_system} [...OPTIONS...] -vnc :1,password -monitor stdio
1100 (qemu) change vnc password
1101 Password: ********
1102 (qemu)
1103 @end example
1104
1105 @node vnc_sec_certificate
1106 @subsection With x509 certificates
1107
1108 The QEMU VNC server also implements the VeNCrypt extension allowing use of
1109 TLS for encryption of the session, and x509 certificates for authentication.
1110 The use of x509 certificates is strongly recommended, because TLS on its
1111 own is susceptible to man-in-the-middle attacks. Basic x509 certificate
1112 support provides a secure session, but no authentication. This allows any
1113 client to connect, and provides an encrypted session.
1114
1115 @example
1116 @value{qemu_system} [...OPTIONS...] \
1117   -object tls-creds-x509,id=tls0,dir=/etc/pki/qemu,endpoint=server,verify-peer=no \
1118   -vnc :1,tls-creds=tls0 -monitor stdio
1119 @end example
1120
1121 In the above example @code{/etc/pki/qemu} should contain at least three files,
1122 @code{ca-cert.pem}, @code{server-cert.pem} and @code{server-key.pem}. Unprivileged
1123 users will want to use a private directory, for example @code{$HOME/.pki/qemu}.
1124 NB the @code{server-key.pem} file should be protected with file mode 0600 to
1125 only be readable by the user owning it.
1126
1127 @node vnc_sec_certificate_verify
1128 @subsection With x509 certificates and client verification
1129
1130 Certificates can also provide a means to authenticate the client connecting.
1131 The server will request that the client provide a certificate, which it will
1132 then validate against the CA certificate. This is a good choice if deploying
1133 in an environment with a private internal certificate authority. It uses the
1134 same syntax as previously, but with @code{verify-peer} set to @code{yes}
1135 instead.
1136
1137 @example
1138 @value{qemu_system} [...OPTIONS...] \
1139   -object tls-creds-x509,id=tls0,dir=/etc/pki/qemu,endpoint=server,verify-peer=yes \
1140   -vnc :1,tls-creds=tls0 -monitor stdio
1141 @end example
1142
1143
1144 @node vnc_sec_certificate_pw
1145 @subsection With x509 certificates, client verification and passwords
1146
1147 Finally, the previous method can be combined with VNC password authentication
1148 to provide two layers of authentication for clients.
1149
1150 @example
1151 @value{qemu_system} [...OPTIONS...] \
1152   -object tls-creds-x509,id=tls0,dir=/etc/pki/qemu,endpoint=server,verify-peer=yes \
1153   -vnc :1,tls-creds=tls0,password -monitor stdio
1154 (qemu) change vnc password
1155 Password: ********
1156 (qemu)
1157 @end example
1158
1159
1160 @node vnc_sec_sasl
1161 @subsection With SASL authentication
1162
1163 The SASL authentication method is a VNC extension, that provides an
1164 easily extendable, pluggable authentication method. This allows for
1165 integration with a wide range of authentication mechanisms, such as
1166 PAM, GSSAPI/Kerberos, LDAP, SQL databases, one-time keys and more.
1167 The strength of the authentication depends on the exact mechanism
1168 configured. If the chosen mechanism also provides a SSF layer, then
1169 it will encrypt the datastream as well.
1170
1171 Refer to the later docs on how to choose the exact SASL mechanism
1172 used for authentication, but assuming use of one supporting SSF,
1173 then QEMU can be launched with:
1174
1175 @example
1176 @value{qemu_system} [...OPTIONS...] -vnc :1,sasl -monitor stdio
1177 @end example
1178
1179 @node vnc_sec_certificate_sasl
1180 @subsection With x509 certificates and SASL authentication
1181
1182 If the desired SASL authentication mechanism does not supported
1183 SSF layers, then it is strongly advised to run it in combination
1184 with TLS and x509 certificates. This provides securely encrypted
1185 data stream, avoiding risk of compromising of the security
1186 credentials. This can be enabled, by combining the 'sasl' option
1187 with the aforementioned TLS + x509 options:
1188
1189 @example
1190 @value{qemu_system} [...OPTIONS...] \
1191   -object tls-creds-x509,id=tls0,dir=/etc/pki/qemu,endpoint=server,verify-peer=yes \
1192   -vnc :1,tls-creds=tls0,sasl -monitor stdio
1193 @end example
1194
1195 @node vnc_setup_sasl
1196
1197 @subsection Configuring SASL mechanisms
1198
1199 The following documentation assumes use of the Cyrus SASL implementation on a
1200 Linux host, but the principles should apply to any other SASL implementation
1201 or host. When SASL is enabled, the mechanism configuration will be loaded from
1202 system default SASL service config /etc/sasl2/qemu.conf. If running QEMU as an
1203 unprivileged user, an environment variable SASL_CONF_PATH can be used to make
1204 it search alternate locations for the service config file.
1205
1206 If the TLS option is enabled for VNC, then it will provide session encryption,
1207 otherwise the SASL mechanism will have to provide encryption. In the latter
1208 case the list of possible plugins that can be used is drastically reduced. In
1209 fact only the GSSAPI SASL mechanism provides an acceptable level of security
1210 by modern standards. Previous versions of QEMU referred to the DIGEST-MD5
1211 mechanism, however, it has multiple serious flaws described in detail in
1212 RFC 6331 and thus should never be used any more. The SCRAM-SHA-1 mechanism
1213 provides a simple username/password auth facility similar to DIGEST-MD5, but
1214 does not support session encryption, so can only be used in combination with
1215 TLS.
1216
1217 When not using TLS the recommended configuration is
1218
1219 @example
1220 mech_list: gssapi
1221 keytab: /etc/qemu/krb5.tab
1222 @end example
1223
1224 This says to use the 'GSSAPI' mechanism with the Kerberos v5 protocol, with
1225 the server principal stored in /etc/qemu/krb5.tab. For this to work the
1226 administrator of your KDC must generate a Kerberos principal for the server,
1227 with a name of 'qemu/somehost.example.com@@EXAMPLE.COM' replacing
1228 'somehost.example.com' with the fully qualified host name of the machine
1229 running QEMU, and 'EXAMPLE.COM' with the Kerberos Realm.
1230
1231 When using TLS, if username+password authentication is desired, then a
1232 reasonable configuration is
1233
1234 @example
1235 mech_list: scram-sha-1
1236 sasldb_path: /etc/qemu/passwd.db
1237 @end example
1238
1239 The @code{saslpasswd2} program can be used to populate the @code{passwd.db}
1240 file with accounts.
1241
1242 Other SASL configurations will be left as an exercise for the reader. Note that
1243 all mechanisms, except GSSAPI, should be combined with use of TLS to ensure a
1244 secure data channel.
1245
1246
1247 @node network_tls
1248 @section TLS setup for network services
1249
1250 Almost all network services in QEMU have the ability to use TLS for
1251 session data encryption, along with x509 certificates for simple
1252 client authentication. What follows is a description of how to
1253 generate certificates suitable for usage with QEMU, and applies to
1254 the VNC server, character devices with the TCP backend, NBD server
1255 and client, and migration server and client.
1256
1257 At a high level, QEMU requires certificates and private keys to be
1258 provided in PEM format. Aside from the core fields, the certificates
1259 should include various extension data sets, including v3 basic
1260 constraints data, key purpose, key usage and subject alt name.
1261
1262 The GnuTLS package includes a command called @code{certtool} which can
1263 be used to easily generate certificates and keys in the required format
1264 with expected data present. Alternatively a certificate management
1265 service may be used.
1266
1267 At a minimum it is necessary to setup a certificate authority, and
1268 issue certificates to each server. If using x509 certificates for
1269 authentication, then each client will also need to be issued a
1270 certificate.
1271
1272 Assuming that the QEMU network services will only ever be exposed to
1273 clients on a private intranet, there is no need to use a commercial
1274 certificate authority to create certificates. A self-signed CA is
1275 sufficient, and in fact likely to be more secure since it removes
1276 the ability of malicious 3rd parties to trick the CA into mis-issuing
1277 certs for impersonating your services. The only likely exception
1278 where a commercial CA might be desirable is if enabling the VNC
1279 websockets server and exposing it directly to remote browser clients.
1280 In such a case it might be useful to use a commercial CA to avoid
1281 needing to install custom CA certs in the web browsers.
1282
1283 The recommendation is for the server to keep its certificates in either
1284 @code{/etc/pki/qemu} or for unprivileged users in @code{$HOME/.pki/qemu}.
1285
1286 @menu
1287 * tls_generate_ca::
1288 * tls_generate_server::
1289 * tls_generate_client::
1290 * tls_creds_setup::
1291 * tls_psk::
1292 @end menu
1293 @node tls_generate_ca
1294 @subsection Setup the Certificate Authority
1295
1296 This step only needs to be performed once per organization / organizational
1297 unit. First the CA needs a private key. This key must be kept VERY secret
1298 and secure. If this key is compromised the entire trust chain of the certificates
1299 issued with it is lost.
1300
1301 @example
1302 # certtool --generate-privkey > ca-key.pem
1303 @end example
1304
1305 To generate a self-signed certificate requires one core piece of information,
1306 the name of the organization. A template file @code{ca.info} should be
1307 populated with the desired data to avoid having to deal with interactive
1308 prompts from certtool:
1309 @example
1310 # cat > ca.info <<EOF
1311 cn = Name of your organization
1312 ca
1313 cert_signing_key
1314 EOF
1315 # certtool --generate-self-signed \
1316            --load-privkey ca-key.pem
1317            --template ca.info \
1318            --outfile ca-cert.pem
1319 @end example
1320
1321 The @code{ca} keyword in the template sets the v3 basic constraints extension
1322 to indicate this certificate is for a CA, while @code{cert_signing_key} sets
1323 the key usage extension to indicate this will be used for signing other keys.
1324 The generated @code{ca-cert.pem} file should be copied to all servers and
1325 clients wishing to utilize TLS support in the VNC server. The @code{ca-key.pem}
1326 must not be disclosed/copied anywhere except the host responsible for issuing
1327 certificates.
1328
1329 @node tls_generate_server
1330 @subsection Issuing server certificates
1331
1332 Each server (or host) needs to be issued with a key and certificate. When connecting
1333 the certificate is sent to the client which validates it against the CA certificate.
1334 The core pieces of information for a server certificate are the hostnames and/or IP
1335 addresses that will be used by clients when connecting. The hostname / IP address
1336 that the client specifies when connecting will be validated against the hostname(s)
1337 and IP address(es) recorded in the server certificate, and if no match is found
1338 the client will close the connection.
1339
1340 Thus it is recommended that the server certificate include both the fully qualified
1341 and unqualified hostnames. If the server will have permanently assigned IP address(es),
1342 and clients are likely to use them when connecting, they may also be included in the
1343 certificate. Both IPv4 and IPv6 addresses are supported. Historically certificates
1344 only included 1 hostname in the @code{CN} field, however, usage of this field for
1345 validation is now deprecated. Instead modern TLS clients will validate against the
1346 Subject Alt Name extension data, which allows for multiple entries. In the future
1347 usage of the @code{CN} field may be discontinued entirely, so providing SAN
1348 extension data is strongly recommended.
1349
1350 On the host holding the CA, create template files containing the information
1351 for each server, and use it to issue server certificates.
1352
1353 @example
1354 # cat > server-hostNNN.info <<EOF
1355 organization = Name  of your organization
1356 cn = hostNNN.foo.example.com
1357 dns_name = hostNNN
1358 dns_name = hostNNN.foo.example.com
1359 ip_address = 10.0.1.87
1360 ip_address = 192.8.0.92
1361 ip_address = 2620:0:cafe::87
1362 ip_address = 2001:24::92
1363 tls_www_server
1364 encryption_key
1365 signing_key
1366 EOF
1367 # certtool --generate-privkey > server-hostNNN-key.pem
1368 # certtool --generate-certificate \
1369            --load-ca-certificate ca-cert.pem \
1370            --load-ca-privkey ca-key.pem \
1371            --load-privkey server-hostNNN-key.pem \
1372            --template server-hostNNN.info \
1373            --outfile server-hostNNN-cert.pem
1374 @end example
1375
1376 The @code{dns_name} and @code{ip_address} fields in the template are setting
1377 the subject alt name extension data. The @code{tls_www_server} keyword is the
1378 key purpose extension to indicate this certificate is intended for usage in
1379 a web server. Although QEMU network services are not in fact HTTP servers
1380 (except for VNC websockets), setting this key purpose is still recommended.
1381 The @code{encryption_key} and @code{signing_key} keyword is the key usage
1382 extension to indicate this certificate is intended for usage in the data
1383 session.
1384
1385 The @code{server-hostNNN-key.pem} and @code{server-hostNNN-cert.pem} files
1386 should now be securely copied to the server for which they were generated,
1387 and renamed to @code{server-key.pem} and @code{server-cert.pem} when added
1388 to the @code{/etc/pki/qemu} directory on the target host. The @code{server-key.pem}
1389 file is security sensitive and should be kept protected with file mode 0600
1390 to prevent disclosure.
1391
1392 @node tls_generate_client
1393 @subsection Issuing client certificates
1394
1395 The QEMU x509 TLS credential setup defaults to enabling client verification
1396 using certificates, providing a simple authentication mechanism. If this
1397 default is used, each client also needs to be issued a certificate. The client
1398 certificate contains enough metadata to uniquely identify the client with the
1399 scope of the certificate authority. The client certificate would typically
1400 include fields for organization, state, city, building, etc.
1401
1402 Once again on the host holding the CA, create template files containing the
1403 information for each client, and use it to issue client certificates.
1404
1405
1406 @example
1407 # cat > client-hostNNN.info <<EOF
1408 country = GB
1409 state = London
1410 locality = City Of London
1411 organization = Name of your organization
1412 cn = hostNNN.foo.example.com
1413 tls_www_client
1414 encryption_key
1415 signing_key
1416 EOF
1417 # certtool --generate-privkey > client-hostNNN-key.pem
1418 # certtool --generate-certificate \
1419            --load-ca-certificate ca-cert.pem \
1420            --load-ca-privkey ca-key.pem \
1421            --load-privkey client-hostNNN-key.pem \
1422            --template client-hostNNN.info \
1423            --outfile client-hostNNN-cert.pem
1424 @end example
1425
1426 The subject alt name extension data is not required for clients, so the
1427 the @code{dns_name} and @code{ip_address} fields are not included.
1428 The @code{tls_www_client} keyword is the key purpose extension to indicate
1429 this certificate is intended for usage in a web client. Although QEMU
1430 network clients are not in fact HTTP clients, setting this key purpose is
1431 still recommended. The @code{encryption_key} and @code{signing_key} keyword
1432 is the key usage extension to indicate this certificate is intended for
1433 usage in the data session.
1434
1435 The @code{client-hostNNN-key.pem} and @code{client-hostNNN-cert.pem} files
1436 should now be securely copied to the client for which they were generated,
1437 and renamed to @code{client-key.pem} and @code{client-cert.pem} when added
1438 to the @code{/etc/pki/qemu} directory on the target host. The @code{client-key.pem}
1439 file is security sensitive and should be kept protected with file mode 0600
1440 to prevent disclosure.
1441
1442 If a single host is going to be using TLS in both a client and server
1443 role, it is possible to create a single certificate to cover both roles.
1444 This would be quite common for the migration and NBD services, where a
1445 QEMU process will be started by accepting a TLS protected incoming migration,
1446 and later itself be migrated out to another host. To generate a single
1447 certificate, simply include the template data from both the client and server
1448 instructions in one.
1449
1450 @example
1451 # cat > both-hostNNN.info <<EOF
1452 country = GB
1453 state = London
1454 locality = City Of London
1455 organization = Name of your organization
1456 cn = hostNNN.foo.example.com
1457 dns_name = hostNNN
1458 dns_name = hostNNN.foo.example.com
1459 ip_address = 10.0.1.87
1460 ip_address = 192.8.0.92
1461 ip_address = 2620:0:cafe::87
1462 ip_address = 2001:24::92
1463 tls_www_server
1464 tls_www_client
1465 encryption_key
1466 signing_key
1467 EOF
1468 # certtool --generate-privkey > both-hostNNN-key.pem
1469 # certtool --generate-certificate \
1470            --load-ca-certificate ca-cert.pem \
1471            --load-ca-privkey ca-key.pem \
1472            --load-privkey both-hostNNN-key.pem \
1473            --template both-hostNNN.info \
1474            --outfile both-hostNNN-cert.pem
1475 @end example
1476
1477 When copying the PEM files to the target host, save them twice,
1478 once as @code{server-cert.pem} and @code{server-key.pem}, and
1479 again as @code{client-cert.pem} and @code{client-key.pem}.
1480
1481 @node tls_creds_setup
1482 @subsection TLS x509 credential configuration
1483
1484 QEMU has a standard mechanism for loading x509 credentials that will be
1485 used for network services and clients. It requires specifying the
1486 @code{tls-creds-x509} class name to the @code{--object} command line
1487 argument for the system emulators.  Each set of credentials loaded should
1488 be given a unique string identifier via the @code{id} parameter. A single
1489 set of TLS credentials can be used for multiple network backends, so VNC,
1490 migration, NBD, character devices can all share the same credentials. Note,
1491 however, that credentials for use in a client endpoint must be loaded
1492 separately from those used in a server endpoint.
1493
1494 When specifying the object, the @code{dir} parameters specifies which
1495 directory contains the credential files. This directory is expected to
1496 contain files with the names mentioned previously, @code{ca-cert.pem},
1497 @code{server-key.pem}, @code{server-cert.pem}, @code{client-key.pem}
1498 and @code{client-cert.pem} as appropriate. It is also possible to
1499 include a set of pre-generated Diffie-Hellman (DH) parameters in a file
1500 @code{dh-params.pem}, which can be created using the
1501 @code{certtool --generate-dh-params} command. If omitted, QEMU will
1502 dynamically generate DH parameters when loading the credentials.
1503
1504 The @code{endpoint} parameter indicates whether the credentials will
1505 be used for a network client or server, and determines which PEM
1506 files are loaded.
1507
1508 The @code{verify} parameter determines whether x509 certificate
1509 validation should be performed. This defaults to enabled, meaning
1510 clients will always validate the server hostname against the
1511 certificate subject alt name fields and/or CN field. It also
1512 means that servers will request that clients provide a certificate
1513 and validate them. Verification should never be turned off for
1514 client endpoints, however, it may be turned off for server endpoints
1515 if an alternative mechanism is used to authenticate clients. For
1516 example, the VNC server can use SASL to authenticate clients
1517 instead.
1518
1519 To load server credentials with client certificate validation
1520 enabled
1521
1522 @example
1523 @value{qemu_system} -object tls-creds-x509,id=tls0,dir=/etc/pki/qemu,endpoint=server
1524 @end example
1525
1526 while to load client credentials use
1527
1528 @example
1529 @value{qemu_system} -object tls-creds-x509,id=tls0,dir=/etc/pki/qemu,endpoint=client
1530 @end example
1531
1532 Network services which support TLS will all have a @code{tls-creds}
1533 parameter which expects the ID of the TLS credentials object. For
1534 example with VNC:
1535
1536 @example
1537 @value{qemu_system} -vnc 0.0.0.0:0,tls-creds=tls0
1538 @end example
1539
1540 @node tls_psk
1541 @subsection TLS Pre-Shared Keys (PSK)
1542
1543 Instead of using certificates, you may also use TLS Pre-Shared Keys
1544 (TLS-PSK).  This can be simpler to set up than certificates but is
1545 less scalable.
1546
1547 Use the GnuTLS @code{psktool} program to generate a @code{keys.psk}
1548 file containing one or more usernames and random keys:
1549
1550 @example
1551 mkdir -m 0700 /tmp/keys
1552 psktool -u rich -p /tmp/keys/keys.psk
1553 @end example
1554
1555 TLS-enabled servers such as qemu-nbd can use this directory like so:
1556
1557 @example
1558 qemu-nbd \
1559   -t -x / \
1560   --object tls-creds-psk,id=tls0,endpoint=server,dir=/tmp/keys \
1561   --tls-creds tls0 \
1562   image.qcow2
1563 @end example
1564
1565 When connecting from a qemu-based client you must specify the
1566 directory containing @code{keys.psk} and an optional @var{username}
1567 (defaults to ``qemu''):
1568
1569 @example
1570 qemu-img info \
1571   --object tls-creds-psk,id=tls0,dir=/tmp/keys,username=rich,endpoint=client \
1572   --image-opts \
1573   file.driver=nbd,file.host=localhost,file.port=10809,file.tls-creds=tls0,file.export=/
1574 @end example
1575
1576 @node gdb_usage
1577 @section GDB usage
1578
1579 QEMU has a primitive support to work with gdb, so that you can do
1580 'Ctrl-C' while the virtual machine is running and inspect its state.
1581
1582 In order to use gdb, launch QEMU with the '-s' option. It will wait for a
1583 gdb connection:
1584 @example
1585 @value{qemu_system} -s -kernel bzImage -hda rootdisk.img -append "root=/dev/hda"
1586 Connected to host network interface: tun0
1587 Waiting gdb connection on port 1234
1588 @end example
1589
1590 Then launch gdb on the 'vmlinux' executable:
1591 @example
1592 > gdb vmlinux
1593 @end example
1594
1595 In gdb, connect to QEMU:
1596 @example
1597 (gdb) target remote localhost:1234
1598 @end example
1599
1600 Then you can use gdb normally. For example, type 'c' to launch the kernel:
1601 @example
1602 (gdb) c
1603 @end example
1604
1605 Here are some useful tips in order to use gdb on system code:
1606
1607 @enumerate
1608 @item
1609 Use @code{info reg} to display all the CPU registers.
1610 @item
1611 Use @code{x/10i $eip} to display the code at the PC position.
1612 @item
1613 Use @code{set architecture i8086} to dump 16 bit code. Then use
1614 @code{x/10i $cs*16+$eip} to dump the code at the PC position.
1615 @end enumerate
1616
1617 Advanced debugging options:
1618
1619 The default single stepping behavior is step with the IRQs and timer service routines off.  It is set this way because when gdb executes a single step it expects to advance beyond the current instruction.  With the IRQs and timer service routines on, a single step might jump into the one of the interrupt or exception vectors instead of executing the current instruction. This means you may hit the same breakpoint a number of times before executing the instruction gdb wants to have executed.  Because there are rare circumstances where you want to single step into an interrupt vector the behavior can be controlled from GDB.  There are three commands you can query and set the single step behavior:
1620 @table @code
1621 @item maintenance packet qqemu.sstepbits
1622
1623 This will display the MASK bits used to control the single stepping IE:
1624 @example
1625 (gdb) maintenance packet qqemu.sstepbits
1626 sending: "qqemu.sstepbits"
1627 received: "ENABLE=1,NOIRQ=2,NOTIMER=4"
1628 @end example
1629 @item maintenance packet qqemu.sstep
1630
1631 This will display the current value of the mask used when single stepping IE:
1632 @example
1633 (gdb) maintenance packet qqemu.sstep
1634 sending: "qqemu.sstep"
1635 received: "0x7"
1636 @end example
1637 @item maintenance packet Qqemu.sstep=HEX_VALUE
1638
1639 This will change the single step mask, so if wanted to enable IRQs on the single step, but not timers, you would use:
1640 @example
1641 (gdb) maintenance packet Qqemu.sstep=0x5
1642 sending: "qemu.sstep=0x5"
1643 received: "OK"
1644 @end example
1645 @end table
1646
1647 @node pcsys_os_specific
1648 @section Target OS specific information
1649
1650 @subsection Linux
1651
1652 To have access to SVGA graphic modes under X11, use the @code{vesa} or
1653 the @code{cirrus} X11 driver. For optimal performances, use 16 bit
1654 color depth in the guest and the host OS.
1655
1656 When using a 2.6 guest Linux kernel, you should add the option
1657 @code{clock=pit} on the kernel command line because the 2.6 Linux
1658 kernels make very strict real time clock checks by default that QEMU
1659 cannot simulate exactly.
1660
1661 When using a 2.6 guest Linux kernel, verify that the 4G/4G patch is
1662 not activated because QEMU is slower with this patch. The QEMU
1663 Accelerator Module is also much slower in this case. Earlier Fedora
1664 Core 3 Linux kernel (< 2.6.9-1.724_FC3) were known to incorporate this
1665 patch by default. Newer kernels don't have it.
1666
1667 @subsection Windows
1668
1669 If you have a slow host, using Windows 95 is better as it gives the
1670 best speed. Windows 2000 is also a good choice.
1671
1672 @subsubsection SVGA graphic modes support
1673
1674 QEMU emulates a Cirrus Logic GD5446 Video
1675 card. All Windows versions starting from Windows 95 should recognize
1676 and use this graphic card. For optimal performances, use 16 bit color
1677 depth in the guest and the host OS.
1678
1679 If you are using Windows XP as guest OS and if you want to use high
1680 resolution modes which the Cirrus Logic BIOS does not support (i.e. >=
1681 1280x1024x16), then you should use the VESA VBE virtual graphic card
1682 (option @option{-std-vga}).
1683
1684 @subsubsection CPU usage reduction
1685
1686 Windows 9x does not correctly use the CPU HLT
1687 instruction. The result is that it takes host CPU cycles even when
1688 idle. You can install the utility from
1689 @url{https://web.archive.org/web/20060212132151/http://www.user.cityline.ru/~maxamn/amnhltm.zip}
1690 to solve this problem. Note that no such tool is needed for NT, 2000 or XP.
1691
1692 @subsubsection Windows 2000 disk full problem
1693
1694 Windows 2000 has a bug which gives a disk full problem during its
1695 installation. When installing it, use the @option{-win2k-hack} QEMU
1696 option to enable a specific workaround. After Windows 2000 is
1697 installed, you no longer need this option (this option slows down the
1698 IDE transfers).
1699
1700 @subsubsection Windows 2000 shutdown
1701
1702 Windows 2000 cannot automatically shutdown in QEMU although Windows 98
1703 can. It comes from the fact that Windows 2000 does not automatically
1704 use the APM driver provided by the BIOS.
1705
1706 In order to correct that, do the following (thanks to Struan
1707 Bartlett): go to the Control Panel => Add/Remove Hardware & Next =>
1708 Add/Troubleshoot a device => Add a new device & Next => No, select the
1709 hardware from a list & Next => NT Apm/Legacy Support & Next => Next
1710 (again) a few times. Now the driver is installed and Windows 2000 now
1711 correctly instructs QEMU to shutdown at the appropriate moment.
1712
1713 @subsubsection Share a directory between Unix and Windows
1714
1715 See @ref{sec_invocation} about the help of the option
1716 @option{'-netdev user,smb=...'}.
1717
1718 @subsubsection Windows XP security problem
1719
1720 Some releases of Windows XP install correctly but give a security
1721 error when booting:
1722 @example
1723 A problem is preventing Windows from accurately checking the
1724 license for this computer. Error code: 0x800703e6.
1725 @end example
1726
1727 The workaround is to install a service pack for XP after a boot in safe
1728 mode. Then reboot, and the problem should go away. Since there is no
1729 network while in safe mode, its recommended to download the full
1730 installation of SP1 or SP2 and transfer that via an ISO or using the
1731 vvfat block device ("-hdb fat:directory_which_holds_the_SP").
1732
1733 @subsection MS-DOS and FreeDOS
1734
1735 @subsubsection CPU usage reduction
1736
1737 DOS does not correctly use the CPU HLT instruction. The result is that
1738 it takes host CPU cycles even when idle. You can install the utility from
1739 @url{https://web.archive.org/web/20051222085335/http://www.vmware.com/software/dosidle210.zip}
1740 to solve this problem.
1741
1742 @node QEMU System emulator for non PC targets
1743 @chapter QEMU System emulator for non PC targets
1744
1745 QEMU is a generic emulator and it emulates many non PC
1746 machines. Most of the options are similar to the PC emulator. The
1747 differences are mentioned in the following sections.
1748
1749 @menu
1750 * PowerPC System emulator::
1751 * Sparc32 System emulator::
1752 * Sparc64 System emulator::
1753 * MIPS System emulator::
1754 * ARM System emulator::
1755 * ColdFire System emulator::
1756 * Cris System emulator::
1757 * Microblaze System emulator::
1758 * SH4 System emulator::
1759 * Xtensa System emulator::
1760 @end menu
1761
1762 @node PowerPC System emulator
1763 @section PowerPC System emulator
1764 @cindex system emulation (PowerPC)
1765
1766 Use the executable @file{qemu-system-ppc} to simulate a complete PREP
1767 or PowerMac PowerPC system.
1768
1769 QEMU emulates the following PowerMac peripherals:
1770
1771 @itemize @minus
1772 @item
1773 UniNorth or Grackle PCI Bridge
1774 @item
1775 PCI VGA compatible card with VESA Bochs Extensions
1776 @item
1777 2 PMAC IDE interfaces with hard disk and CD-ROM support
1778 @item
1779 NE2000 PCI adapters
1780 @item
1781 Non Volatile RAM
1782 @item
1783 VIA-CUDA with ADB keyboard and mouse.
1784 @end itemize
1785
1786 QEMU emulates the following PREP peripherals:
1787
1788 @itemize @minus
1789 @item
1790 PCI Bridge
1791 @item
1792 PCI VGA compatible card with VESA Bochs Extensions
1793 @item
1794 2 IDE interfaces with hard disk and CD-ROM support
1795 @item
1796 Floppy disk
1797 @item
1798 NE2000 network adapters
1799 @item
1800 Serial port
1801 @item
1802 PREP Non Volatile RAM
1803 @item
1804 PC compatible keyboard and mouse.
1805 @end itemize
1806
1807 QEMU uses the Open Hack'Ware Open Firmware Compatible BIOS available at
1808 @url{http://perso.magic.fr/l_indien/OpenHackWare/index.htm}.
1809
1810 Since version 0.9.1, QEMU uses OpenBIOS @url{https://www.openbios.org/}
1811 for the g3beige and mac99 PowerMac machines. OpenBIOS is a free (GPL
1812 v2) portable firmware implementation. The goal is to implement a 100%
1813 IEEE 1275-1994 (referred to as Open Firmware) compliant firmware.
1814
1815 @c man begin OPTIONS
1816
1817 The following options are specific to the PowerPC emulation:
1818
1819 @table @option
1820
1821 @item -g @var{W}x@var{H}[x@var{DEPTH}]
1822
1823 Set the initial VGA graphic mode. The default is 800x600x32.
1824
1825 @item -prom-env @var{string}
1826
1827 Set OpenBIOS variables in NVRAM, for example:
1828
1829 @example
1830 qemu-system-ppc -prom-env 'auto-boot?=false' \
1831  -prom-env 'boot-device=hd:2,\yaboot' \
1832  -prom-env 'boot-args=conf=hd:2,\yaboot.conf'
1833 @end example
1834
1835 These variables are not used by Open Hack'Ware.
1836
1837 @end table
1838
1839 @c man end
1840
1841
1842 More information is available at
1843 @url{http://perso.magic.fr/l_indien/qemu-ppc/}.
1844
1845 @node Sparc32 System emulator
1846 @section Sparc32 System emulator
1847 @cindex system emulation (Sparc32)
1848
1849 Use the executable @file{qemu-system-sparc} to simulate the following
1850 Sun4m architecture machines:
1851 @itemize @minus
1852 @item
1853 SPARCstation 4
1854 @item
1855 SPARCstation 5
1856 @item
1857 SPARCstation 10
1858 @item
1859 SPARCstation 20
1860 @item
1861 SPARCserver 600MP
1862 @item
1863 SPARCstation LX
1864 @item
1865 SPARCstation Voyager
1866 @item
1867 SPARCclassic
1868 @item
1869 SPARCbook
1870 @end itemize
1871
1872 The emulation is somewhat complete. SMP up to 16 CPUs is supported,
1873 but Linux limits the number of usable CPUs to 4.
1874
1875 QEMU emulates the following sun4m peripherals:
1876
1877 @itemize @minus
1878 @item
1879 IOMMU
1880 @item
1881 TCX or cgthree Frame buffer
1882 @item
1883 Lance (Am7990) Ethernet
1884 @item
1885 Non Volatile RAM M48T02/M48T08
1886 @item
1887 Slave I/O: timers, interrupt controllers, Zilog serial ports, keyboard
1888 and power/reset logic
1889 @item
1890 ESP SCSI controller with hard disk and CD-ROM support
1891 @item
1892 Floppy drive (not on SS-600MP)
1893 @item
1894 CS4231 sound device (only on SS-5, not working yet)
1895 @end itemize
1896
1897 The number of peripherals is fixed in the architecture.  Maximum
1898 memory size depends on the machine type, for SS-5 it is 256MB and for
1899 others 2047MB.
1900
1901 Since version 0.8.2, QEMU uses OpenBIOS
1902 @url{https://www.openbios.org/}. OpenBIOS is a free (GPL v2) portable
1903 firmware implementation. The goal is to implement a 100% IEEE
1904 1275-1994 (referred to as Open Firmware) compliant firmware.
1905
1906 A sample Linux 2.6 series kernel and ram disk image are available on
1907 the QEMU web site. There are still issues with NetBSD and OpenBSD, but
1908 most kernel versions work. Please note that currently older Solaris kernels
1909 don't work probably due to interface issues between OpenBIOS and
1910 Solaris.
1911
1912 @c man begin OPTIONS
1913
1914 The following options are specific to the Sparc32 emulation:
1915
1916 @table @option
1917
1918 @item -g @var{W}x@var{H}x[x@var{DEPTH}]
1919
1920 Set the initial graphics mode. For TCX, the default is 1024x768x8 with the
1921 option of 1024x768x24. For cgthree, the default is 1024x768x8 with the option
1922 of 1152x900x8 for people who wish to use OBP.
1923
1924 @item -prom-env @var{string}
1925
1926 Set OpenBIOS variables in NVRAM, for example:
1927
1928 @example
1929 qemu-system-sparc -prom-env 'auto-boot?=false' \
1930  -prom-env 'boot-device=sd(0,2,0):d' -prom-env 'boot-args=linux single'
1931 @end example
1932
1933 @item -M [SS-4|SS-5|SS-10|SS-20|SS-600MP|LX|Voyager|SPARCClassic] [|SPARCbook]
1934
1935 Set the emulated machine type. Default is SS-5.
1936
1937 @end table
1938
1939 @c man end
1940
1941 @node Sparc64 System emulator
1942 @section Sparc64 System emulator
1943 @cindex system emulation (Sparc64)
1944
1945 Use the executable @file{qemu-system-sparc64} to simulate a Sun4u
1946 (UltraSPARC PC-like machine), Sun4v (T1 PC-like machine), or generic
1947 Niagara (T1) machine. The Sun4u emulator is mostly complete, being
1948 able to run Linux, NetBSD and OpenBSD in headless (-nographic) mode. The
1949 Sun4v emulator is still a work in progress.
1950
1951 The Niagara T1 emulator makes use of firmware and OS binaries supplied in the S10image/ directory
1952 of the OpenSPARC T1 project @url{http://download.oracle.com/technetwork/systems/opensparc/OpenSPARCT1_Arch.1.5.tar.bz2}
1953 and is able to boot the disk.s10hw2 Solaris image.
1954 @example
1955 qemu-system-sparc64 -M niagara -L /path-to/S10image/ \
1956                     -nographic -m 256 \
1957                     -drive if=pflash,readonly=on,file=/S10image/disk.s10hw2
1958 @end example
1959
1960
1961 QEMU emulates the following peripherals:
1962
1963 @itemize @minus
1964 @item
1965 UltraSparc IIi APB PCI Bridge
1966 @item
1967 PCI VGA compatible card with VESA Bochs Extensions
1968 @item
1969 PS/2 mouse and keyboard
1970 @item
1971 Non Volatile RAM M48T59
1972 @item
1973 PC-compatible serial ports
1974 @item
1975 2 PCI IDE interfaces with hard disk and CD-ROM support
1976 @item
1977 Floppy disk
1978 @end itemize
1979
1980 @c man begin OPTIONS
1981
1982 The following options are specific to the Sparc64 emulation:
1983
1984 @table @option
1985
1986 @item -prom-env @var{string}
1987
1988 Set OpenBIOS variables in NVRAM, for example:
1989
1990 @example
1991 qemu-system-sparc64 -prom-env 'auto-boot?=false'
1992 @end example
1993
1994 @item -M [sun4u|sun4v|niagara]
1995
1996 Set the emulated machine type. The default is sun4u.
1997
1998 @end table
1999
2000 @c man end
2001
2002 @node MIPS System emulator
2003 @section MIPS System emulator
2004 @cindex system emulation (MIPS)
2005
2006 @menu
2007 * nanoMIPS System emulator ::
2008 @end menu
2009
2010 Four executables cover simulation of 32 and 64-bit MIPS systems in
2011 both endian options, @file{qemu-system-mips}, @file{qemu-system-mipsel}
2012 @file{qemu-system-mips64} and @file{qemu-system-mips64el}.
2013 Five different machine types are emulated:
2014
2015 @itemize @minus
2016 @item
2017 A generic ISA PC-like machine "mips"
2018 @item
2019 The MIPS Malta prototype board "malta"
2020 @item
2021 An ACER Pica "pica61". This machine needs the 64-bit emulator.
2022 @item
2023 MIPS emulator pseudo board "mipssim"
2024 @item
2025 A MIPS Magnum R4000 machine "magnum". This machine needs the 64-bit emulator.
2026 @end itemize
2027
2028 The generic emulation is supported by Debian 'Etch' and is able to
2029 install Debian into a virtual disk image. The following devices are
2030 emulated:
2031
2032 @itemize @minus
2033 @item
2034 A range of MIPS CPUs, default is the 24Kf
2035 @item
2036 PC style serial port
2037 @item
2038 PC style IDE disk
2039 @item
2040 NE2000 network card
2041 @end itemize
2042
2043 The Malta emulation supports the following devices:
2044
2045 @itemize @minus
2046 @item
2047 Core board with MIPS 24Kf CPU and Galileo system controller
2048 @item
2049 PIIX4 PCI/USB/SMbus controller
2050 @item
2051 The Multi-I/O chip's serial device
2052 @item
2053 PCI network cards (PCnet32 and others)
2054 @item
2055 Malta FPGA serial device
2056 @item
2057 Cirrus (default) or any other PCI VGA graphics card
2058 @end itemize
2059
2060 The Boston board emulation supports the following devices:
2061
2062 @itemize @minus
2063 @item
2064 Xilinx FPGA, which includes a PCIe root port and an UART
2065 @item
2066 Intel EG20T PCH connects the I/O peripherals, but only the SATA bus is emulated
2067 @end itemize
2068
2069 The ACER Pica emulation supports:
2070
2071 @itemize @minus
2072 @item
2073 MIPS R4000 CPU
2074 @item
2075 PC-style IRQ and DMA controllers
2076 @item
2077 PC Keyboard
2078 @item
2079 IDE controller
2080 @end itemize
2081
2082 The MIPS Magnum R4000 emulation supports:
2083
2084 @itemize @minus
2085 @item
2086 MIPS R4000 CPU
2087 @item
2088 PC-style IRQ controller
2089 @item
2090 PC Keyboard
2091 @item
2092 SCSI controller
2093 @item
2094 G364 framebuffer
2095 @end itemize
2096
2097 The Fulong 2E emulation supports:
2098
2099 @itemize @minus
2100 @item
2101 Loongson 2E CPU
2102 @item
2103 Bonito64 system controller as North Bridge
2104 @item
2105 VT82C686 chipset as South Bridge
2106 @item
2107 RTL8139D as a network card chipset
2108 @end itemize
2109
2110 The mipssim pseudo board emulation provides an environment similar
2111 to what the proprietary MIPS emulator uses for running Linux.
2112 It supports:
2113
2114 @itemize @minus
2115 @item
2116 A range of MIPS CPUs, default is the 24Kf
2117 @item
2118 PC style serial port
2119 @item
2120 MIPSnet network emulation
2121 @end itemize
2122
2123 @node nanoMIPS System emulator
2124 @subsection nanoMIPS System emulator
2125 @cindex system emulation (nanoMIPS)
2126
2127 Executable @file{qemu-system-mipsel} also covers simulation of
2128 32-bit nanoMIPS system in little endian mode:
2129
2130 @itemize @minus
2131 @item
2132 nanoMIPS I7200 CPU
2133 @end itemize
2134
2135 Example of @file{qemu-system-mipsel} usage for nanoMIPS is shown below:
2136
2137 Download @code{<disk_image_file>} from @url{https://mipsdistros.mips.com/LinuxDistro/nanomips/buildroot/index.html}.
2138
2139 Download @code{<kernel_image_file>} from @url{https://mipsdistros.mips.com/LinuxDistro/nanomips/kernels/v4.15.18-432-gb2eb9a8b07a1-20180627102142/index.html}.
2140
2141 Start system emulation of Malta board with nanoMIPS I7200 CPU:
2142 @example
2143 qemu-system-mipsel -cpu I7200 -kernel @code{<kernel_image_file>} \
2144     -M malta -serial stdio -m @code{<memory_size>} -hda @code{<disk_image_file>} \
2145     -append "mem=256m@@0x0 rw console=ttyS0 vga=cirrus vesa=0x111 root=/dev/sda"
2146 @end example
2147
2148
2149 @node ARM System emulator
2150 @section ARM System emulator
2151 @cindex system emulation (ARM)
2152
2153 Use the executable @file{qemu-system-arm} to simulate a ARM
2154 machine. The ARM Integrator/CP board is emulated with the following
2155 devices:
2156
2157 @itemize @minus
2158 @item
2159 ARM926E, ARM1026E, ARM946E, ARM1136 or Cortex-A8 CPU
2160 @item
2161 Two PL011 UARTs
2162 @item
2163 SMC 91c111 Ethernet adapter
2164 @item
2165 PL110 LCD controller
2166 @item
2167 PL050 KMI with PS/2 keyboard and mouse.
2168 @item
2169 PL181 MultiMedia Card Interface with SD card.
2170 @end itemize
2171
2172 The ARM Versatile baseboard is emulated with the following devices:
2173
2174 @itemize @minus
2175 @item
2176 ARM926E, ARM1136 or Cortex-A8 CPU
2177 @item
2178 PL190 Vectored Interrupt Controller
2179 @item
2180 Four PL011 UARTs
2181 @item
2182 SMC 91c111 Ethernet adapter
2183 @item
2184 PL110 LCD controller
2185 @item
2186 PL050 KMI with PS/2 keyboard and mouse.
2187 @item
2188 PCI host bridge.  Note the emulated PCI bridge only provides access to
2189 PCI memory space.  It does not provide access to PCI IO space.
2190 This means some devices (eg. ne2k_pci NIC) are not usable, and others
2191 (eg. rtl8139 NIC) are only usable when the guest drivers use the memory
2192 mapped control registers.
2193 @item
2194 PCI OHCI USB controller.
2195 @item
2196 LSI53C895A PCI SCSI Host Bus Adapter with hard disk and CD-ROM devices.
2197 @item
2198 PL181 MultiMedia Card Interface with SD card.
2199 @end itemize
2200
2201 Several variants of the ARM RealView baseboard are emulated,
2202 including the EB, PB-A8 and PBX-A9.  Due to interactions with the
2203 bootloader, only certain Linux kernel configurations work out
2204 of the box on these boards.
2205
2206 Kernels for the PB-A8 board should have CONFIG_REALVIEW_HIGH_PHYS_OFFSET
2207 enabled in the kernel, and expect 512M RAM.  Kernels for The PBX-A9 board
2208 should have CONFIG_SPARSEMEM enabled, CONFIG_REALVIEW_HIGH_PHYS_OFFSET
2209 disabled and expect 1024M RAM.
2210
2211 The following devices are emulated:
2212
2213 @itemize @minus
2214 @item
2215 ARM926E, ARM1136, ARM11MPCore, Cortex-A8 or Cortex-A9 MPCore CPU
2216 @item
2217 ARM AMBA Generic/Distributed Interrupt Controller
2218 @item
2219 Four PL011 UARTs
2220 @item
2221 SMC 91c111 or SMSC LAN9118 Ethernet adapter
2222 @item
2223 PL110 LCD controller
2224 @item
2225 PL050 KMI with PS/2 keyboard and mouse
2226 @item
2227 PCI host bridge
2228 @item
2229 PCI OHCI USB controller
2230 @item
2231 LSI53C895A PCI SCSI Host Bus Adapter with hard disk and CD-ROM devices
2232 @item
2233 PL181 MultiMedia Card Interface with SD card.
2234 @end itemize
2235
2236 The XScale-based clamshell PDA models ("Spitz", "Akita", "Borzoi"
2237 and "Terrier") emulation includes the following peripherals:
2238
2239 @itemize @minus
2240 @item
2241 Intel PXA270 System-on-chip (ARM V5TE core)
2242 @item
2243 NAND Flash memory
2244 @item
2245 IBM/Hitachi DSCM microdrive in a PXA PCMCIA slot - not in "Akita"
2246 @item
2247 On-chip OHCI USB controller
2248 @item
2249 On-chip LCD controller
2250 @item
2251 On-chip Real Time Clock
2252 @item
2253 TI ADS7846 touchscreen controller on SSP bus
2254 @item
2255 Maxim MAX1111 analog-digital converter on I@math{^2}C bus
2256 @item
2257 GPIO-connected keyboard controller and LEDs
2258 @item
2259 Secure Digital card connected to PXA MMC/SD host
2260 @item
2261 Three on-chip UARTs
2262 @item
2263 WM8750 audio CODEC on I@math{^2}C and I@math{^2}S busses
2264 @end itemize
2265
2266 The Palm Tungsten|E PDA (codename "Cheetah") emulation includes the
2267 following elements:
2268
2269 @itemize @minus
2270 @item
2271 Texas Instruments OMAP310 System-on-chip (ARM 925T core)
2272 @item
2273 ROM and RAM memories (ROM firmware image can be loaded with -option-rom)
2274 @item
2275 On-chip LCD controller
2276 @item
2277 On-chip Real Time Clock
2278 @item
2279 TI TSC2102i touchscreen controller / analog-digital converter / Audio
2280 CODEC, connected through MicroWire and I@math{^2}S busses
2281 @item
2282 GPIO-connected matrix keypad
2283 @item
2284 Secure Digital card connected to OMAP MMC/SD host
2285 @item
2286 Three on-chip UARTs
2287 @end itemize
2288
2289 Nokia N800 and N810 internet tablets (known also as RX-34 and RX-44 / 48)
2290 emulation supports the following elements:
2291
2292 @itemize @minus
2293 @item
2294 Texas Instruments OMAP2420 System-on-chip (ARM 1136 core)
2295 @item
2296 RAM and non-volatile OneNAND Flash memories
2297 @item
2298 Display connected to EPSON remote framebuffer chip and OMAP on-chip
2299 display controller and a LS041y3 MIPI DBI-C controller
2300 @item
2301 TI TSC2301 (in N800) and TI TSC2005 (in N810) touchscreen controllers
2302 driven through SPI bus
2303 @item
2304 National Semiconductor LM8323-controlled qwerty keyboard driven
2305 through I@math{^2}C bus
2306 @item
2307 Secure Digital card connected to OMAP MMC/SD host
2308 @item
2309 Three OMAP on-chip UARTs and on-chip STI debugging console
2310 @item
2311 Mentor Graphics "Inventra" dual-role USB controller embedded in a TI
2312 TUSB6010 chip - only USB host mode is supported
2313 @item
2314 TI TMP105 temperature sensor driven through I@math{^2}C bus
2315 @item
2316 TI TWL92230C power management companion with an RTC on I@math{^2}C bus
2317 @item
2318 Nokia RETU and TAHVO multi-purpose chips with an RTC, connected
2319 through CBUS
2320 @end itemize
2321
2322 The Luminary Micro Stellaris LM3S811EVB emulation includes the following
2323 devices:
2324
2325 @itemize @minus
2326 @item
2327 Cortex-M3 CPU core.
2328 @item
2329 64k Flash and 8k SRAM.
2330 @item
2331 Timers, UARTs, ADC and I@math{^2}C interface.
2332 @item
2333 OSRAM Pictiva 96x16 OLED with SSD0303 controller on I@math{^2}C bus.
2334 @end itemize
2335
2336 The Luminary Micro Stellaris LM3S6965EVB emulation includes the following
2337 devices:
2338
2339 @itemize @minus
2340 @item
2341 Cortex-M3 CPU core.
2342 @item
2343 256k Flash and 64k SRAM.
2344 @item
2345 Timers, UARTs, ADC, I@math{^2}C and SSI interfaces.
2346 @item
2347 OSRAM Pictiva 128x64 OLED with SSD0323 controller connected via SSI.
2348 @end itemize
2349
2350 The Freecom MusicPal internet radio emulation includes the following
2351 elements:
2352
2353 @itemize @minus
2354 @item
2355 Marvell MV88W8618 ARM core.
2356 @item
2357 32 MB RAM, 256 KB SRAM, 8 MB flash.
2358 @item
2359 Up to 2 16550 UARTs
2360 @item
2361 MV88W8xx8 Ethernet controller
2362 @item
2363 MV88W8618 audio controller, WM8750 CODEC and mixer
2364 @item
2365 128×64 display with brightness control
2366 @item
2367 2 buttons, 2 navigation wheels with button function
2368 @end itemize
2369
2370 The Siemens SX1 models v1 and v2 (default) basic emulation.
2371 The emulation includes the following elements:
2372
2373 @itemize @minus
2374 @item
2375 Texas Instruments OMAP310 System-on-chip (ARM 925T core)
2376 @item
2377 ROM and RAM memories (ROM firmware image can be loaded with -pflash)
2378 V1
2379 1 Flash of 16MB and 1 Flash of 8MB
2380 V2
2381 1 Flash of 32MB
2382 @item
2383 On-chip LCD controller
2384 @item
2385 On-chip Real Time Clock
2386 @item
2387 Secure Digital card connected to OMAP MMC/SD host
2388 @item
2389 Three on-chip UARTs
2390 @end itemize
2391
2392 A Linux 2.6 test image is available on the QEMU web site. More
2393 information is available in the QEMU mailing-list archive.
2394
2395 @c man begin OPTIONS
2396
2397 The following options are specific to the ARM emulation:
2398
2399 @table @option
2400
2401 @item -semihosting
2402 Enable semihosting syscall emulation.
2403
2404 On ARM this implements the "Angel" interface.
2405
2406 Note that this allows guest direct access to the host filesystem,
2407 so should only be used with trusted guest OS.
2408
2409 @end table
2410
2411 @c man end
2412
2413 @node ColdFire System emulator
2414 @section ColdFire System emulator
2415 @cindex system emulation (ColdFire)
2416 @cindex system emulation (M68K)
2417
2418 Use the executable @file{qemu-system-m68k} to simulate a ColdFire machine.
2419 The emulator is able to boot a uClinux kernel.
2420
2421 The M5208EVB emulation includes the following devices:
2422
2423 @itemize @minus
2424 @item
2425 MCF5208 ColdFire V2 Microprocessor (ISA A+ with EMAC).
2426 @item
2427 Three Two on-chip UARTs.
2428 @item
2429 Fast Ethernet Controller (FEC)
2430 @end itemize
2431
2432 The AN5206 emulation includes the following devices:
2433
2434 @itemize @minus
2435 @item
2436 MCF5206 ColdFire V2 Microprocessor.
2437 @item
2438 Two on-chip UARTs.
2439 @end itemize
2440
2441 @c man begin OPTIONS
2442
2443 The following options are specific to the ColdFire emulation:
2444
2445 @table @option
2446
2447 @item -semihosting
2448 Enable semihosting syscall emulation.
2449
2450 On M68K this implements the "ColdFire GDB" interface used by libgloss.
2451
2452 Note that this allows guest direct access to the host filesystem,
2453 so should only be used with trusted guest OS.
2454
2455 @end table
2456
2457 @c man end
2458
2459 @node Cris System emulator
2460 @section Cris System emulator
2461 @cindex system emulation (Cris)
2462
2463 TODO
2464
2465 @node Microblaze System emulator
2466 @section Microblaze System emulator
2467 @cindex system emulation (Microblaze)
2468
2469 TODO
2470
2471 @node SH4 System emulator
2472 @section SH4 System emulator
2473 @cindex system emulation (SH4)
2474
2475 TODO
2476
2477 @node Xtensa System emulator
2478 @section Xtensa System emulator
2479 @cindex system emulation (Xtensa)
2480
2481 Two executables cover simulation of both Xtensa endian options,
2482 @file{qemu-system-xtensa} and @file{qemu-system-xtensaeb}.
2483 Two different machine types are emulated:
2484
2485 @itemize @minus
2486 @item
2487 Xtensa emulator pseudo board "sim"
2488 @item
2489 Avnet LX60/LX110/LX200 board
2490 @end itemize
2491
2492 The sim pseudo board emulation provides an environment similar
2493 to one provided by the proprietary Tensilica ISS.
2494 It supports:
2495
2496 @itemize @minus
2497 @item
2498 A range of Xtensa CPUs, default is the DC232B
2499 @item
2500 Console and filesystem access via semihosting calls
2501 @end itemize
2502
2503 The Avnet LX60/LX110/LX200 emulation supports:
2504
2505 @itemize @minus
2506 @item
2507 A range of Xtensa CPUs, default is the DC232B
2508 @item
2509 16550 UART
2510 @item
2511 OpenCores 10/100 Mbps Ethernet MAC
2512 @end itemize
2513
2514 @c man begin OPTIONS
2515
2516 The following options are specific to the Xtensa emulation:
2517
2518 @table @option
2519
2520 @item -semihosting
2521 Enable semihosting syscall emulation.
2522
2523 Xtensa semihosting provides basic file IO calls, such as open/read/write/seek/select.
2524 Tensilica baremetal libc for ISS and linux platform "sim" use this interface.
2525
2526 Note that this allows guest direct access to the host filesystem,
2527 so should only be used with trusted guest OS.
2528
2529 @end table
2530
2531 @c man end
2532
2533 @node QEMU User space emulator
2534 @chapter QEMU User space emulator
2535
2536 @menu
2537 * Supported Operating Systems ::
2538 * Features::
2539 * Linux User space emulator::
2540 * BSD User space emulator ::
2541 @end menu
2542
2543 @node Supported Operating Systems
2544 @section Supported Operating Systems
2545
2546 The following OS are supported in user space emulation:
2547
2548 @itemize @minus
2549 @item
2550 Linux (referred as qemu-linux-user)
2551 @item
2552 BSD (referred as qemu-bsd-user)
2553 @end itemize
2554
2555 @node Features
2556 @section Features
2557
2558 QEMU user space emulation has the following notable features:
2559
2560 @table @strong
2561 @item System call translation:
2562 QEMU includes a generic system call translator.  This means that
2563 the parameters of the system calls can be converted to fix
2564 endianness and 32/64-bit mismatches between hosts and targets.
2565 IOCTLs can be converted too.
2566
2567 @item POSIX signal handling:
2568 QEMU can redirect to the running program all signals coming from
2569 the host (such as @code{SIGALRM}), as well as synthesize signals from
2570 virtual CPU exceptions (for example @code{SIGFPE} when the program
2571 executes a division by zero).
2572
2573 QEMU relies on the host kernel to emulate most signal system
2574 calls, for example to emulate the signal mask.  On Linux, QEMU
2575 supports both normal and real-time signals.
2576
2577 @item Threading:
2578 On Linux, QEMU can emulate the @code{clone} syscall and create a real
2579 host thread (with a separate virtual CPU) for each emulated thread.
2580 Note that not all targets currently emulate atomic operations correctly.
2581 x86 and ARM use a global lock in order to preserve their semantics.
2582 @end table
2583
2584 QEMU was conceived so that ultimately it can emulate itself. Although
2585 it is not very useful, it is an important test to show the power of the
2586 emulator.
2587
2588 @node Linux User space emulator
2589 @section Linux User space emulator
2590
2591 @menu
2592 * Quick Start::
2593 * Wine launch::
2594 * Command line options::
2595 * Other binaries::
2596 @end menu
2597
2598 @node Quick Start
2599 @subsection Quick Start
2600
2601 In order to launch a Linux process, QEMU needs the process executable
2602 itself and all the target (x86) dynamic libraries used by it.
2603
2604 @itemize
2605
2606 @item On x86, you can just try to launch any process by using the native
2607 libraries:
2608
2609 @example
2610 qemu-i386 -L / /bin/ls
2611 @end example
2612
2613 @code{-L /} tells that the x86 dynamic linker must be searched with a
2614 @file{/} prefix.
2615
2616 @item Since QEMU is also a linux process, you can launch QEMU with
2617 QEMU (NOTE: you can only do that if you compiled QEMU from the sources):
2618
2619 @example
2620 qemu-i386 -L / qemu-i386 -L / /bin/ls
2621 @end example
2622
2623 @item On non x86 CPUs, you need first to download at least an x86 glibc
2624 (@file{qemu-runtime-i386-XXX-.tar.gz} on the QEMU web page). Ensure that
2625 @code{LD_LIBRARY_PATH} is not set:
2626
2627 @example
2628 unset LD_LIBRARY_PATH
2629 @end example
2630
2631 Then you can launch the precompiled @file{ls} x86 executable:
2632
2633 @example
2634 qemu-i386 tests/i386/ls
2635 @end example
2636 You can look at @file{scripts/qemu-binfmt-conf.sh} so that
2637 QEMU is automatically launched by the Linux kernel when you try to
2638 launch x86 executables. It requires the @code{binfmt_misc} module in the
2639 Linux kernel.
2640
2641 @item The x86 version of QEMU is also included. You can try weird things such as:
2642 @example
2643 qemu-i386 /usr/local/qemu-i386/bin/qemu-i386 \
2644           /usr/local/qemu-i386/bin/ls-i386
2645 @end example
2646
2647 @end itemize
2648
2649 @node Wine launch
2650 @subsection Wine launch
2651
2652 @itemize
2653
2654 @item Ensure that you have a working QEMU with the x86 glibc
2655 distribution (see previous section). In order to verify it, you must be
2656 able to do:
2657
2658 @example
2659 qemu-i386 /usr/local/qemu-i386/bin/ls-i386
2660 @end example
2661
2662 @item Download the binary x86 Wine install
2663 (@file{qemu-XXX-i386-wine.tar.gz} on the QEMU web page).
2664
2665 @item Configure Wine on your account. Look at the provided script
2666 @file{/usr/local/qemu-i386/@/bin/wine-conf.sh}. Your previous
2667 @code{$@{HOME@}/.wine} directory is saved to @code{$@{HOME@}/.wine.org}.
2668
2669 @item Then you can try the example @file{putty.exe}:
2670
2671 @example
2672 qemu-i386 /usr/local/qemu-i386/wine/bin/wine \
2673           /usr/local/qemu-i386/wine/c/Program\ Files/putty.exe
2674 @end example
2675
2676 @end itemize
2677
2678 @node Command line options
2679 @subsection Command line options
2680
2681 @example
2682 @command{qemu-i386} [@option{-h]} [@option{-d]} [@option{-L} @var{path}] [@option{-s} @var{size}] [@option{-cpu} @var{model}] [@option{-g} @var{port}] [@option{-B} @var{offset}] [@option{-R} @var{size}] @var{program} [@var{arguments}...]
2683 @end example
2684
2685 @table @option
2686 @item -h
2687 Print the help
2688 @item -L path
2689 Set the x86 elf interpreter prefix (default=/usr/local/qemu-i386)
2690 @item -s size
2691 Set the x86 stack size in bytes (default=524288)
2692 @item -cpu model
2693 Select CPU model (-cpu help for list and additional feature selection)
2694 @item -E @var{var}=@var{value}
2695 Set environment @var{var} to @var{value}.
2696 @item -U @var{var}
2697 Remove @var{var} from the environment.
2698 @item -B offset
2699 Offset guest address by the specified number of bytes.  This is useful when
2700 the address region required by guest applications is reserved on the host.
2701 This option is currently only supported on some hosts.
2702 @item -R size
2703 Pre-allocate a guest virtual address space of the given size (in bytes).
2704 "G", "M", and "k" suffixes may be used when specifying the size.
2705 @end table
2706
2707 Debug options:
2708
2709 @table @option
2710 @item -d item1,...
2711 Activate logging of the specified items (use '-d help' for a list of log items)
2712 @item -p pagesize
2713 Act as if the host page size was 'pagesize' bytes
2714 @item -g port
2715 Wait gdb connection to port
2716 @item -singlestep
2717 Run the emulation in single step mode.
2718 @end table
2719
2720 Environment variables:
2721
2722 @table @env
2723 @item QEMU_STRACE
2724 Print system calls and arguments similar to the 'strace' program
2725 (NOTE: the actual 'strace' program will not work because the user
2726 space emulator hasn't implemented ptrace).  At the moment this is
2727 incomplete.  All system calls that don't have a specific argument
2728 format are printed with information for six arguments.  Many
2729 flag-style arguments don't have decoders and will show up as numbers.
2730 @end table
2731
2732 @node Other binaries
2733 @subsection Other binaries
2734
2735 @cindex user mode (Alpha)
2736 @command{qemu-alpha} TODO.
2737
2738 @cindex user mode (ARM)
2739 @command{qemu-armeb} TODO.
2740
2741 @cindex user mode (ARM)
2742 @command{qemu-arm} is also capable of running ARM "Angel" semihosted ELF
2743 binaries (as implemented by the arm-elf and arm-eabi Newlib/GDB
2744 configurations), and arm-uclinux bFLT format binaries.
2745
2746 @cindex user mode (ColdFire)
2747 @cindex user mode (M68K)
2748 @command{qemu-m68k} is capable of running semihosted binaries using the BDM
2749 (m5xxx-ram-hosted.ld) or m68k-sim (sim.ld) syscall interfaces, and
2750 coldfire uClinux bFLT format binaries.
2751
2752 The binary format is detected automatically.
2753
2754 @cindex user mode (Cris)
2755 @command{qemu-cris} TODO.
2756
2757 @cindex user mode (i386)
2758 @command{qemu-i386} TODO.
2759 @command{qemu-x86_64} TODO.
2760
2761 @cindex user mode (Microblaze)
2762 @command{qemu-microblaze} TODO.
2763
2764 @cindex user mode (MIPS)
2765 @command{qemu-mips} executes 32-bit big endian MIPS binaries (MIPS O32 ABI).
2766
2767 @command{qemu-mipsel} executes 32-bit little endian MIPS binaries (MIPS O32 ABI).
2768
2769 @command{qemu-mips64} executes 64-bit big endian MIPS binaries (MIPS N64 ABI).
2770
2771 @command{qemu-mips64el} executes 64-bit little endian MIPS binaries (MIPS N64 ABI).
2772
2773 @command{qemu-mipsn32} executes 32-bit big endian MIPS binaries (MIPS N32 ABI).
2774
2775 @command{qemu-mipsn32el} executes 32-bit little endian MIPS binaries (MIPS N32 ABI).
2776
2777 @cindex user mode (NiosII)
2778 @command{qemu-nios2} TODO.
2779
2780 @cindex user mode (PowerPC)
2781 @command{qemu-ppc64abi32} TODO.
2782 @command{qemu-ppc64} TODO.
2783 @command{qemu-ppc} TODO.
2784
2785 @cindex user mode (SH4)
2786 @command{qemu-sh4eb} TODO.
2787 @command{qemu-sh4} TODO.
2788
2789 @cindex user mode (SPARC)
2790 @command{qemu-sparc} can execute Sparc32 binaries (Sparc32 CPU, 32 bit ABI).
2791
2792 @command{qemu-sparc32plus} can execute Sparc32 and SPARC32PLUS binaries
2793 (Sparc64 CPU, 32 bit ABI).
2794
2795 @command{qemu-sparc64} can execute some Sparc64 (Sparc64 CPU, 64 bit ABI) and
2796 SPARC32PLUS binaries (Sparc64 CPU, 32 bit ABI).
2797
2798 @node BSD User space emulator
2799 @section BSD User space emulator
2800
2801 @menu
2802 * BSD Status::
2803 * BSD Quick Start::
2804 * BSD Command line options::
2805 @end menu
2806
2807 @node BSD Status
2808 @subsection BSD Status
2809
2810 @itemize @minus
2811 @item
2812 target Sparc64 on Sparc64: Some trivial programs work.
2813 @end itemize
2814
2815 @node BSD Quick Start
2816 @subsection Quick Start
2817
2818 In order to launch a BSD process, QEMU needs the process executable
2819 itself and all the target dynamic libraries used by it.
2820
2821 @itemize
2822
2823 @item On Sparc64, you can just try to launch any process by using the native
2824 libraries:
2825
2826 @example
2827 qemu-sparc64 /bin/ls
2828 @end example
2829
2830 @end itemize
2831
2832 @node BSD Command line options
2833 @subsection Command line options
2834
2835 @example
2836 @command{qemu-sparc64} [@option{-h]} [@option{-d]} [@option{-L} @var{path}] [@option{-s} @var{size}] [@option{-bsd} @var{type}] @var{program} [@var{arguments}...]
2837 @end example
2838
2839 @table @option
2840 @item -h
2841 Print the help
2842 @item -L path
2843 Set the library root path (default=/)
2844 @item -s size
2845 Set the stack size in bytes (default=524288)
2846 @item -ignore-environment
2847 Start with an empty environment. Without this option,
2848 the initial environment is a copy of the caller's environment.
2849 @item -E @var{var}=@var{value}
2850 Set environment @var{var} to @var{value}.
2851 @item -U @var{var}
2852 Remove @var{var} from the environment.
2853 @item -bsd type
2854 Set the type of the emulated BSD Operating system. Valid values are
2855 FreeBSD, NetBSD and OpenBSD (default).
2856 @end table
2857
2858 Debug options:
2859
2860 @table @option
2861 @item -d item1,...
2862 Activate logging of the specified items (use '-d help' for a list of log items)
2863 @item -p pagesize
2864 Act as if the host page size was 'pagesize' bytes
2865 @item -singlestep
2866 Run the emulation in single step mode.
2867 @end table
2868
2869 @node System requirements
2870 @chapter System requirements
2871
2872 @section KVM kernel module
2873
2874 On x86_64 hosts, the default set of CPU features enabled by the KVM accelerator
2875 require the host to be running Linux v4.5 or newer.
2876
2877 The OpteronG[345] CPU models require KVM support for RDTSCP, which was
2878 added with Linux 4.5 which is supported by the major distros. And even
2879 if RHEL7 has kernel 3.10, KVM there has the required functionality there
2880 to make it close to a 4.5 or newer kernel.
2881
2882 @include docs/security.texi
2883
2884 @include qemu-tech.texi
2885
2886 @include qemu-deprecated.texi
2887
2888 @node Supported build platforms
2889 @appendix Supported build platforms
2890
2891 QEMU aims to support building and executing on multiple host OS platforms.
2892 This appendix outlines which platforms are the major build targets. These
2893 platforms are used as the basis for deciding upon the minimum required
2894 versions of 3rd party software QEMU depends on. The supported platforms
2895 are the targets for automated testing performed by the project when patches
2896 are submitted for review, and tested before and after merge.
2897
2898 If a platform is not listed here, it does not imply that QEMU won't work.
2899 If an unlisted platform has comparable software versions to a listed platform,
2900 there is every expectation that it will work. Bug reports are welcome for
2901 problems encountered on unlisted platforms unless they are clearly older
2902 vintage than what is described here.
2903
2904 Note that when considering software versions shipped in distros as support
2905 targets, QEMU considers only the version number, and assumes the features in
2906 that distro match the upstream release with the same version. In other words,
2907 if a distro backports extra features to the software in their distro, QEMU
2908 upstream code will not add explicit support for those backports, unless the
2909 feature is auto-detectable in a manner that works for the upstream releases
2910 too.
2911
2912 The Repology site @url{https://repology.org} is a useful resource to identify
2913 currently shipped versions of software in various operating systems, though
2914 it does not cover all distros listed below.
2915
2916 @section Linux OS
2917
2918 For distributions with frequent, short-lifetime releases, the project will
2919 aim to support all versions that are not end of life by their respective
2920 vendors. For the purposes of identifying supported software versions, the
2921 project will look at Fedora, Ubuntu, and openSUSE distros. Other short-
2922 lifetime distros will be assumed to ship similar software versions.
2923
2924 For distributions with long-lifetime releases, the project will aim to support
2925 the most recent major version at all times. Support for the previous major
2926 version will be dropped 2 years after the new major version is released. For
2927 the purposes of identifying supported software versions, the project will look
2928 at RHEL, Debian, Ubuntu LTS, and SLES distros. Other long-lifetime distros will
2929 be assumed to ship similar software versions.
2930
2931 @section Windows
2932
2933 The project supports building with current versions of the MinGW toolchain,
2934 hosted on Linux.
2935
2936 @section macOS
2937
2938 The project supports building with the two most recent versions of macOS, with
2939 the current homebrew package set available.
2940
2941 @section FreeBSD
2942
2943 The project aims to support the all the versions which are not end of life.
2944
2945 @section NetBSD
2946
2947 The project aims to support the most recent major version at all times. Support
2948 for the previous major version will be dropped 2 years after the new major
2949 version is released.
2950
2951 @section OpenBSD
2952
2953 The project aims to support the all the versions which are not end of life.
2954
2955 @node License
2956 @appendix License
2957
2958 QEMU is a trademark of Fabrice Bellard.
2959
2960 QEMU is released under the
2961 @url{https://www.gnu.org/licenses/gpl-2.0.txt,GNU General Public License},
2962 version 2. Parts of QEMU have specific licenses, see file
2963 @url{https://git.qemu.org/?p=qemu.git;a=blob_plain;f=LICENSE,LICENSE}.
2964
2965 @node Index
2966 @appendix Index
2967 @menu
2968 * Concept Index::
2969 * Function Index::
2970 * Keystroke Index::
2971 * Program Index::
2972 * Data Type Index::
2973 * Variable Index::
2974 @end menu
2975
2976 @node Concept Index
2977 @section Concept Index
2978 This is the main index. Should we combine all keywords in one index? TODO
2979 @printindex cp
2980
2981 @node Function Index
2982 @section Function Index
2983 This index could be used for command line options and monitor functions.
2984 @printindex fn
2985
2986 @node Keystroke Index
2987 @section Keystroke Index
2988
2989 This is a list of all keystrokes which have a special function
2990 in system emulation.
2991
2992 @printindex ky
2993
2994 @node Program Index
2995 @section Program Index
2996 @printindex pg
2997
2998 @node Data Type Index
2999 @section Data Type Index
3000
3001 This index could be used for qdev device names and options.
3002
3003 @printindex tp
3004
3005 @node Variable Index
3006 @section Variable Index
3007 @printindex vr
3008
3009 @bye