target-arm: Fix handling of SDCR for 32-bit code

[qemu.git] / qemu-doc.texi

diff --git a/qemu-doc.texi b/qemu-doc.texi
index 4e9c6e9b6e0ce3edafe1cf12af4b4337058412d7..bc9dd13cc913d2a8d2192a157fc8a911b14598ce 100644 (file)
--- a/qemu-doc.texi
+++ b/qemu-doc.texi
@@ -158,7 +158,8 @@ TODO (no longer available)
 * pcsys_introduction:: Introduction
 * pcsys_quickstart::   Quick Start
 * sec_invocation::     Invocation
 * pcsys_introduction:: Introduction
 * pcsys_quickstart::   Quick Start
 * sec_invocation::     Invocation

-* pcsys_keys::         Keys
+* pcsys_keys::         Keys in the graphical frontends
+* mux_keys::           Keys in the character backend multiplexer

 * pcsys_monitor::      QEMU Monitor
 * disk_images::        Disk Images
 * pcsys_network::      Network emulation
 * pcsys_monitor::      QEMU Monitor
 * disk_images::        Disk Images
 * pcsys_network::      Network emulation


@@ -195,6 +196,8 @@ PCI and ISA network adapters
 @item
 Serial ports
 @item
 @item
 Serial ports
 @item

+IPMI BMC, either and internal or external one
+@item

 Creative SoundBlaster 16 sound card
 @item
 ENSONIQ AudioPCI ES1370 sound card
 Creative SoundBlaster 16 sound card
 @item
 ENSONIQ AudioPCI ES1370 sound card


@@ -257,7 +260,7 @@ Linux should boot and give you a prompt.
 
 @example
 @c man begin SYNOPSIS
 
 @example
 @c man begin SYNOPSIS

-usage: qemu-system-i386 [options] [@var{disk_image}]
+@command{qemu-system-i386} [@var{options}] [@var{disk_image}]

 @c man end
 @end example
 
 @c man end
 @end example
 


@@ -270,7 +273,7 @@ targets do not need a disk image.
 @c man end
 
 @node pcsys_keys
 @c man end
 
 @node pcsys_keys

-@section Keys
+@section Keys in the graphical frontends

 
 @c man begin OPTIONS
 
 
 @c man begin OPTIONS
 


@@ -320,15 +323,23 @@ Toggle mouse and keyboard grab.
 In the virtual consoles, you can use @key{Ctrl-Up}, @key{Ctrl-Down},
 @key{Ctrl-PageUp} and @key{Ctrl-PageDown} to move in the back log.
 
 In the virtual consoles, you can use @key{Ctrl-Up}, @key{Ctrl-Down},
 @key{Ctrl-PageUp} and @key{Ctrl-PageDown} to move in the back log.
 

-@kindex Ctrl-a h
-During emulation, if you are using the @option{-nographic} option, use
-@key{Ctrl-a h} to get terminal commands:
+@c man end
+
+@node mux_keys
+@section Keys in the character backend multiplexer
+
+@c man begin OPTIONS
+
+During emulation, if you are using a character backend multiplexer
+(which is the default if you are using @option{-nographic}) then
+several commands are available via an escape sequence. These
+key sequences all start with an escape character, which is @key{Ctrl-a}
+by default, but can be changed with @option{-echr}. The list below assumes
+you're using the default.

 
 @table @key
 @item Ctrl-a h
 @kindex Ctrl-a h
 
 @table @key
 @item Ctrl-a h
 @kindex Ctrl-a h

-@item Ctrl-a ?
-@kindex Ctrl-a ?

 Print this help
 @item Ctrl-a x
 @kindex Ctrl-a x
 Print this help
 @item Ctrl-a x
 @kindex Ctrl-a x


@@ -344,10 +355,11 @@ Toggle console timestamps
 Send break (magic sysrq in Linux)
 @item Ctrl-a c
 @kindex Ctrl-a c
 Send break (magic sysrq in Linux)
 @item Ctrl-a c
 @kindex Ctrl-a c

-Switch between console and monitor
+Rotate between the frontends connected to the multiplexer (usually
+this switches between the monitor and the console)

 @item Ctrl-a Ctrl-a
 @item Ctrl-a Ctrl-a

-@kindex Ctrl-a a
-Send Ctrl-a
+@kindex Ctrl-a Ctrl-a
+Send the escape character to the frontend

 @end table
 @c man end
 
 @end table
 @c man end
 


@@ -391,6 +403,8 @@ The following commands are available:
 
 @include qemu-monitor.texi
 
 
 @include qemu-monitor.texi
 

+@include qemu-monitor-info.texi
+

 @subsection Integer expressions
 
 The monitor understands integers expressions for every integer
 @subsection Integer expressions
 
 The monitor understands integers expressions for every integer


@@ -412,6 +426,7 @@ snapshots.
 * vm_snapshots::              VM snapshots
 * qemu_img_invocation::       qemu-img Invocation
 * qemu_nbd_invocation::       qemu-nbd Invocation
 * vm_snapshots::              VM snapshots
 * qemu_img_invocation::       qemu-img Invocation
 * qemu_nbd_invocation::       qemu-nbd Invocation

+* qemu_ga_invocation::        qemu-ga Invocation

 * disk_images_formats::       Disk image file formats
 * host_drives::               Using host drives
 * disk_images_fat_images::    Virtual FAT disk images
 * disk_images_formats::       Disk image file formats
 * host_drives::               Using host drives
 * disk_images_fat_images::    Virtual FAT disk images


@@ -505,6 +520,11 @@ state is not saved or restored properly (in particular USB).
 
 @include qemu-nbd.texi
 
 
 @include qemu-nbd.texi
 

+@node qemu_ga_invocation
+@subsection @code{qemu-ga} Invocation
+
+@include qemu-ga.texi
+

 @node disk_images_formats
 @subsection Disk image file formats
 
 @node disk_images_formats
 @subsection Disk image file formats
 


@@ -527,30 +547,57 @@ Linux or NTFS on Windows), then only the written sectors will reserve
 space. Use @code{qemu-img info} to know the real size used by the
 image or @code{ls -ls} on Unix/Linux.
 
 space. Use @code{qemu-img info} to know the real size used by the
 image or @code{ls -ls} on Unix/Linux.
 

+Supported options:
+@table @code
+@item preallocation
+Preallocation mode (allowed values: @code{off}, @code{falloc}, @code{full}).
+@code{falloc} mode preallocates space for image by calling posix_fallocate().
+@code{full} mode preallocates space for image by writing zeros to underlying
+storage.
+@end table
+

 @item qcow2
 QEMU image format, the most versatile format. Use it to have smaller
 images (useful if your filesystem does not supports holes, for example
 @item qcow2
 QEMU image format, the most versatile format. Use it to have smaller
 images (useful if your filesystem does not supports holes, for example

-on Windows), optional AES encryption, zlib based compression and
-support of multiple VM snapshots.
+on Windows), zlib based compression and support of multiple VM
+snapshots.

 
 Supported options:
 @table @code
 @item compat
 
 Supported options:
 @table @code
 @item compat

-Determines the qcow2 version to use. @code{compat=0.10} uses the traditional
-image format that can be read by any QEMU since 0.10 (this is the default).
+Determines the qcow2 version to use. @code{compat=0.10} uses the
+traditional image format that can be read by any QEMU since 0.10.

 @code{compat=1.1} enables image format extensions that only QEMU 1.1 and
 @code{compat=1.1} enables image format extensions that only QEMU 1.1 and

-newer understand. Amongst others, this includes zero clusters, which allow
-efficient copy-on-read for sparse images.
+newer understand (this is the default). Amongst others, this includes
+zero clusters, which allow efficient copy-on-read for sparse images.

 
 @item backing_file
 File name of a base image (see @option{create} subcommand)
 @item backing_fmt
 Image format of the base image
 @item encryption
 
 @item backing_file
 File name of a base image (see @option{create} subcommand)
 @item backing_fmt
 Image format of the base image
 @item encryption

-If this option is set to @code{on}, the image is encrypted.
+If this option is set to @code{on}, the image is encrypted with 128-bit AES-CBC.
+
+The use of encryption in qcow and qcow2 images is considered to be flawed by
+modern cryptography standards, suffering from a number of design problems:
+
+@itemize @minus
+@item The AES-CBC cipher is used with predictable initialization vectors based
+on the sector number. This makes it vulnerable to chosen plaintext attacks
+which can reveal the existence of encrypted data.
+@item The user passphrase is directly used as the encryption key. A poorly
+chosen or short passphrase will compromise the security of the encryption.
+@item In the event of the passphrase being compromised there is no way to
+change the passphrase to protect data in any qcow images. The files must
+be cloned, using a different encryption passphrase in the new file. The
+original file must then be securely erased using a program like shred,
+though even this is ineffective with many modern storage technologies.
+@end itemize

 
 

-Encryption uses the AES format which is very secure (128 bit keys). Use
-a long password (16 characters) to get maximum protection.
+Use of qcow / qcow2 encryption with QEMU is deprecated, and support for
+it will go away in a future release.  Users are recommended to use an
+alternative encryption technology such as the Linux dm-crypt / LUKS
+system.

 
 @item cluster_size
 Changes the qcow2 cluster size (must be between 512 and 2M). Smaller cluster
 
 @item cluster_size
 Changes the qcow2 cluster size (must be between 512 and 2M). Smaller cluster


@@ -558,9 +605,11 @@ sizes can improve the image file size whereas larger cluster sizes generally
 provide better performance.
 
 @item preallocation
 provide better performance.
 
 @item preallocation

-Preallocation mode (allowed values: off, metadata). An image with preallocated
-metadata is initially larger but can improve performance when the image needs
-to grow.
+Preallocation mode (allowed values: @code{off}, @code{metadata}, @code{falloc},
+@code{full}). An image with preallocated metadata is initially larger but can
+improve performance when the image needs to grow. @code{falloc} and @code{full}
+preallocations are like the same options of @code{raw} format, but sets up
+metadata also.

 
 @item lazy_refcounts
 If this option is set to @code{on}, reference count updates are postponed with
 
 @item lazy_refcounts
 If this option is set to @code{on}, reference count updates are postponed with


@@ -572,6 +621,22 @@ check -r all} is required, which may take some time.
 
 This option can only be enabled if @code{compat=1.1} is specified.
 
 
 This option can only be enabled if @code{compat=1.1} is specified.
 

+@item nocow
+If this option is set to @code{on}, it will turn off COW of the file. It's only
+valid on btrfs, no effect on other file systems.
+
+Btrfs has low performance when hosting a VM image file, even more when the guest
+on the VM also using btrfs as file system. Turning off COW is a way to mitigate
+this bad performance. Generally there are two ways to turn off COW on btrfs:
+a) Disable it by mounting with nodatacow, then all newly created files will be
+NOCOW. b) For an empty file, add the NOCOW file attribute. That's what this option
+does.
+
+Note: this option is only valid to new or empty files. If there is an existing
+file which is COW and has data blocks already, it couldn't be changed to NOCOW
+by setting @code{nocow=on}. One can issue @code{lsattr filename} to check if
+the NOCOW flag is set or not (Capital 'C' is NOCOW flag).
+

 @end table
 
 @item qed
 @end table
 
 @item qed


@@ -610,15 +675,6 @@ File name of a base image (see @option{create} subcommand)
 If this option is set to @code{on}, the image is encrypted.
 @end table
 
 If this option is set to @code{on}, the image is encrypted.
 @end table
 

-@item cow
-User Mode Linux Copy On Write image format. It is supported only for
-compatibility with previous versions.
-Supported options:
-@table @code
-@item backing_file
-File name of a base image (see @option{create} subcommand)
-@end table
-

 @item vdi
 VirtualBox 1.1 compatible image format.
 Supported options:
 @item vdi
 VirtualBox 1.1 compatible image format.
 Supported options:


@@ -663,7 +719,11 @@ Supported options:
 Specifies which VHDX subformat to use. Valid options are
 @code{dynamic} (default) and @code{fixed}.
 @item block_state_zero
 Specifies which VHDX subformat to use. Valid options are
 @code{dynamic} (default) and @code{fixed}.
 @item block_state_zero

-Force use of payload blocks of type 'ZERO'.
+Force use of payload blocks of type 'ZERO'.  Can be set to @code{on} (default)
+or @code{off}.  When set to @code{off}, new blocks will be created as
+@code{PAYLOAD_BLOCK_NOT_PRESENT}, which means parsers are free to return
+arbitrary data for those blocks.  Do not set to @code{off} when using
+@code{qemu-img convert} with @code{subformat=dynamic}.

 @item block_size
 Block size; min 1 MB, max 256 MB.  0 means auto-calculate based on image size.
 @item log_size
 @item block_size
 Block size; min 1 MB, max 256 MB.  0 means auto-calculate based on image size.
 @item log_size


@@ -696,8 +756,7 @@ devices. We describe here the usage for QEMU version >= 0.8.3.
 
 On Linux, you can directly use the host device filename instead of a
 disk image filename provided you have enough privileges to access
 
 On Linux, you can directly use the host device filename instead of a
 disk image filename provided you have enough privileges to access

-it. For example, use @file{/dev/cdrom} to access to the CDROM or
-@file{/dev/fd0} for the floppy.
+it. For example, use @file{/dev/cdrom} to access to the CDROM.

 
 @table @code
 @item CD
 
 @table @code
 @item CD


@@ -709,6 +768,8 @@ You can specify a floppy device even if no floppy is loaded. Floppy
 removal is currently not detected accurately (if you change floppy
 without doing floppy access while the floppy is not loaded, the guest
 OS will think that the same floppy is loaded).
 removal is currently not detected accurately (if you change floppy
 without doing floppy access while the floppy is not loaded, the guest
 OS will think that the same floppy is loaded).

+Use of the host's floppy device is deprecated, and support for it will
+be removed in a future release.

 @item Hard disks
 Hard disks can be used. Normally you must specify the whole disk
 (@file{/dev/hdb} instead of @file{/dev/hdb1}) so that the guest OS can
 @item Hard disks
 Hard disks can be used. Normally you must specify the whole disk
 (@file{/dev/hdb} instead of @file{/dev/hdb1}) so that the guest OS can


@@ -806,7 +867,7 @@ In this case, the block device must be exported using qemu-nbd:
 qemu-nbd --socket=/tmp/my_socket my_disk.qcow2
 @end example
 
 qemu-nbd --socket=/tmp/my_socket my_disk.qcow2
 @end example
 

-The use of qemu-nbd allows to share a disk between several guests:
+The use of qemu-nbd allows sharing of a disk between several guests:

 @example
 qemu-nbd --socket=/tmp/my_socket --share=2 my_disk.qcow2
 @end example
 @example
 qemu-nbd --socket=/tmp/my_socket --share=2 my_disk.qcow2
 @end example


@@ -1020,7 +1081,7 @@ type is assumed.
 @var{server} specifies the server where the volume file specification for
 the given volume resides. This can be either hostname, ipv4 address
 or ipv6 address. ipv6 address needs to be within square brackets [ ].
 @var{server} specifies the server where the volume file specification for
 the given volume resides. This can be either hostname, ipv4 address
 or ipv6 address. ipv6 address needs to be within square brackets [ ].

-If transport type is unix, then @var{server} field should not be specifed.
+If transport type is unix, then @var{server} field should not be specified.

 Instead @var{socket} field needs to be populated with the path to unix domain
 socket.
 
 Instead @var{socket} field needs to be populated with the path to unix domain
 socket.
 


@@ -1172,16 +1233,23 @@ In order to check that the user mode network is working, you can ping
 the address 10.0.2.2 and verify that you got an address in the range
 10.0.2.x from the QEMU virtual DHCP server.
 
 the address 10.0.2.2 and verify that you got an address in the range
 10.0.2.x from the QEMU virtual DHCP server.
 

-Note that @code{ping} is not supported reliably to the internet as it
-would require root privileges. It means you can only ping the local
-router (10.0.2.2).
+Note that ICMP traffic in general does not work with user mode networking.
+@code{ping}, aka. ICMP echo, to the local router (10.0.2.2) shall work,
+however. If you're using QEMU on Linux >= 3.0, it can use unprivileged ICMP
+ping sockets to allow @code{ping} to the Internet. The host admin has to set
+the ping_group_range in order to grant access to those sockets. To allow ping
+for GID 100 (usually users group):
+
+@example
+echo 100 100 > /proc/sys/net/ipv4/ping_group_range
+@end example

 
 When using the built-in TFTP server, the router is also the TFTP
 server.
 
 
 When using the built-in TFTP server, the router is also the TFTP
 server.
 

-When using the @option{-redir} option, TCP or UDP connections can be
-redirected from the host to the guest. It allows for example to
-redirect X11, telnet or SSH connections.
+When using the @option{'-netdev user,hostfwd=...'} option, TCP or UDP
+connections can be redirected from the host to the guest. It allows for
+example to redirect X11, telnet or SSH connections.

 
 @subsection Connecting VLANs between QEMU instances
 
 
 @subsection Connecting VLANs between QEMU instances
 


@@ -1200,7 +1268,7 @@ zero-copy communication to the application level of the guests.  The basic
 syntax is:
 
 @example
 syntax is:
 
 @example

-qemu-system-i386 -device ivshmem,size=<size in format accepted by -m>[,shm=<shm name>]
+qemu-system-i386 -device ivshmem,size=@var{size},shm=@var{shm-name}

 @end example
 
 If desired, interrupts can be sent between guest VMs accessing the same shared
 @end example
 
 If desired, interrupts can be sent between guest VMs accessing the same shared


@@ -1210,9 +1278,13 @@ is qemu.git/contrib/ivshmem-server.  An example syntax when using the shared
 memory server is:
 
 @example
 memory server is:
 
 @example

-qemu-system-i386 -device ivshmem,size=<size in format accepted by -m>[,chardev=<id>]
-                 [,msi=on][,ioeventfd=on][,vectors=n][,role=peer|master]
-qemu-system-i386 -chardev socket,path=<path>,id=<id>
+# First start the ivshmem server once and for all
+ivshmem-server -p @var{pidfile} -S @var{path} -m @var{shm-name} -l @var{shm-size} -n @var{vectors}
+
+# Then start your qemu instances with matching arguments
+qemu-system-i386 -device ivshmem,size=@var{shm-size},vectors=@var{vectors},chardev=@var{id}
+                 [,msi=on][,ioeventfd=on][,role=peer|master]
+                 -chardev socket,path=@var{path},id=@var{id}

 @end example
 
 When using the server, the guest will be assigned a VM ID (>=0) that allows guests
 @end example
 
 When using the server, the guest will be assigned a VM ID (>=0) that allows guests


@@ -1233,6 +1305,19 @@ copy the shared memory on migration to the destination host.  With
 With the @option{peer} case, the device should be detached and then reattached
 after migration using the PCI hotplug support.
 
 With the @option{peer} case, the device should be detached and then reattached
 after migration using the PCI hotplug support.
 

+@subsubsection ivshmem and hugepages
+
+Instead of specifying the <shm size> using POSIX shm, you may specify
+a memory backend that has hugepage support:
+
+@example
+qemu-system-i386 -object memory-backend-file,size=1G,mem-path=/mnt/hugepages/my-shmem-file,id=mb1
+                 -device ivshmem,x-memdev=mb1
+@end example
+
+ivshmem-server also supports hugepages mount points with the
+@option{-m} memory path argument.
+

 @node direct_linux_boot
 @section Direct Linux Boot
 
 @node direct_linux_boot
 @section Direct Linux Boot
 


@@ -1331,7 +1416,7 @@ no type is given, the HCI logic corresponds to @code{-bt hci,vlan=0}.
 This USB device implements the USB Transport Layer of HCI.  Example
 usage:
 @example
 This USB device implements the USB Transport Layer of HCI.  Example
 usage:
 @example

-qemu-system-i386 [...OPTIONS...] -usbdevice bt:hci,vlan=3 -bt device:keyboard,vlan=3
+@command{qemu-system-i386} [...@var{OPTIONS}...] @option{-usbdevice} bt:hci,vlan=3 @option{-bt} device:keyboard,vlan=3

 @end example
 @end table
 
 @end example
 @end table
 


@@ -1589,7 +1674,7 @@ EOF
 # certtool --generate-certificate \
            --load-ca-certificate ca-cert.pem \
            --load-ca-privkey ca-key.pem \
 # certtool --generate-certificate \
            --load-ca-certificate ca-cert.pem \
            --load-ca-privkey ca-key.pem \

-           --load-privkey server server-key.pem \
+           --load-privkey server-key.pem \

            --template server.info \
            --outfile server-cert.pem
 @end example
            --template server.info \
            --outfile server-cert.pem
 @end example


@@ -1612,7 +1697,7 @@ the secure CA private key:
 country = GB
 state = London
 locality = London
 country = GB
 state = London
 locality = London

-organiazation = Name of your organization
+organization = Name of your organization

 cn = client.foo.example.com
 tls_www_client
 encryption_key
 cn = client.foo.example.com
 tls_www_client
 encryption_key


@@ -1718,7 +1803,7 @@ Use @code{set architecture i8086} to dump 16 bit code. Then use
 
 Advanced debugging options:
 
 
 Advanced debugging options:
 

-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 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:
+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:

 @table @code
 @item maintenance packet qqemu.sstepbits
 
 @table @code
 @item maintenance packet qqemu.sstepbits
 


@@ -1814,7 +1899,8 @@ correctly instructs QEMU to shutdown at the appropriate moment.
 
 @subsubsection Share a directory between Unix and Windows
 
 
 @subsubsection Share a directory between Unix and Windows
 

-See @ref{sec_invocation} about the help of the option @option{-smb}.
+See @ref{sec_invocation} about the help of the option
+@option{'-netdev user,smb=...'}.

 
 @subsubsection Windows XP security problem
 
 
 @subsubsection Windows XP security problem
 


@@ -1921,7 +2007,7 @@ The following options are specific to the PowerPC emulation:
 
 @item -g @var{W}x@var{H}[x@var{DEPTH}]
 
 
 @item -g @var{W}x@var{H}[x@var{DEPTH}]
 

-Set the initial VGA graphic mode. The default is 800x600x15.
+Set the initial VGA graphic mode. The default is 800x600x32.

 
 @item -prom-env @var{string}
 
 
 @item -prom-env @var{string}
 


@@ -1979,7 +2065,7 @@ QEMU emulates the following sun4m peripherals:
 @item
 IOMMU
 @item
 @item
 IOMMU
 @item

-TCX Frame buffer
+TCX or cgthree Frame buffer

 @item
 Lance (Am7990) Ethernet
 @item
 @item
 Lance (Am7990) Ethernet
 @item


@@ -2006,7 +2092,7 @@ firmware implementation. The goal is to implement a 100% IEEE
 
 A sample Linux 2.6 series kernel and ram disk image are available on
 the QEMU web site. There are still issues with NetBSD and OpenBSD, but
 
 A sample Linux 2.6 series kernel and ram disk image are available on
 the QEMU web site. There are still issues with NetBSD and OpenBSD, but

-some kernel versions work. Please note that currently Solaris kernels
+most kernel versions work. Please note that currently older Solaris kernels

 don't work probably due to interface issues between OpenBIOS and
 Solaris.
 
 don't work probably due to interface issues between OpenBIOS and
 Solaris.
 


@@ -2018,8 +2104,9 @@ The following options are specific to the Sparc32 emulation:
 
 @item -g @var{W}x@var{H}x[x@var{DEPTH}]
 
 
 @item -g @var{W}x@var{H}x[x@var{DEPTH}]
 

-Set the initial TCX graphic mode. The default is 1024x768x8, currently
-the only other possible mode is 1024x768x24.
+Set the initial graphics mode. For TCX, the default is 1024x768x8 with the
+option of 1024x768x24. For cgthree, the default is 1024x768x8 with the option
+of 1152x900x8 for people who wish to use OBP.

 
 @item -prom-env @var{string}
 
 
 @item -prom-env @var{string}
 


@@ -2044,8 +2131,9 @@ Set the emulated machine type. Default is SS-5.
 
 Use the executable @file{qemu-system-sparc64} to simulate a Sun4u
 (UltraSPARC PC-like machine), Sun4v (T1 PC-like machine), or generic
 
 Use the executable @file{qemu-system-sparc64} to simulate a Sun4u
 (UltraSPARC PC-like machine), Sun4v (T1 PC-like machine), or generic

-Niagara (T1) machine. The emulator is not usable for anything yet, but
-it can launch some kernels.
+Niagara (T1) machine. The Sun4u emulator is mostly complete, being
+able to run Linux, NetBSD and OpenBSD in headless (-nographic) mode. The
+Sun4v and Niagara emulators are still a work in progress.

 
 QEMU emulates the following peripherals:
 
 
 QEMU emulates the following peripherals:
 


@@ -2678,7 +2766,7 @@ qemu-i386 /usr/local/qemu-i386/wine/bin/wine \
 @subsection Command line options
 
 @example
 @subsection Command line options
 
 @example

-usage: qemu-i386 [-h] [-d] [-L path] [-s size] [-cpu model] [-g port] [-B offset] [-R size] program [arguments...]
+@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}...]

 @end example
 
 @table @option
 @end example
 
 @table @option


@@ -2820,7 +2908,7 @@ qemu-sparc64 /bin/ls
 @subsection Command line options
 
 @example
 @subsection Command line options
 
 @example

-usage: qemu-sparc64 [-h] [-d] [-L path] [-s size] [-bsd type] program [arguments...]
+@command{qemu-sparc64} [@option{-h]} [@option{-d]} [@option{-L} @var{path}] [@option{-s} @var{size}] [@option{-bsd} @var{type}] @var{program} [@var{arguments}...]

 @end example
 
 @table @option
 @end example
 
 @table @option


@@ -2971,9 +3059,62 @@ and all other qemu-system-@var{target}.exe compiled for Win32.
 @node Mac OS X
 @section Mac OS X
 
 @node Mac OS X
 @section Mac OS X
 

-The Mac OS X patches are not fully merged in QEMU, so you should look
-at the QEMU mailing list archive to have all the necessary
-information.
+System Requirements:
+@itemize
+@item Mac OS 10.5 or higher
+@item The clang compiler shipped with Xcode 4.2 or higher,
+or GCC 4.3 or higher
+@end itemize
+
+Additional Requirements (install in order):
+@enumerate
+@item libffi: @uref{https://sourceware.org/libffi/}
+@item gettext: @uref{http://www.gnu.org/software/gettext/}
+@item glib: @uref{http://ftp.gnome.org/pub/GNOME/sources/glib/}
+@item pkg-config: @uref{http://www.freedesktop.org/wiki/Software/pkg-config/}
+@item autoconf: @uref{http://www.gnu.org/software/autoconf/autoconf.html}
+@item automake: @uref{http://www.gnu.org/software/automake/}
+@item pixman: @uref{http://www.pixman.org/}
+@end enumerate
+
+* You may find it easiest to get these from a third-party packager
+such as Homebrew, Macports, or Fink.
+
+After downloading the QEMU source code, double-click it to expand it.
+
+Then configure and make QEMU:
+@example
+./configure
+make
+@end example
+
+If you have a recent version of Mac OS X (OSX 10.7 or better
+with Xcode 4.2 or better) we recommend building QEMU with the
+default compiler provided by Apple, for your version of Mac OS X
+(which will be 'clang'). The configure script will
+automatically pick this.
+
+Note: If after the configure step you see a message like this:
+@example
+ERROR: Your compiler does not support the __thread specifier for
+       Thread-Local Storage (TLS). Please upgrade to a version that does.
+@end example
+you may have to build your own version of gcc from source. Expect that to take
+several hours. More information can be found here:
+@uref{https://gcc.gnu.org/install/} @*
+
+These are some of the third party binaries of gcc available for download:
+@itemize
+@item Homebrew: @uref{http://brew.sh/}
+@item @uref{https://www.litebeam.net/gcc/gcc_472.pkg}
+@item @uref{http://www.macports.org/ports.php?by=name&substr=gcc}
+@end itemize
+
+You can have several versions of GCC on your system. To specify a certain version,
+use the --cc and --cxx options.
+@example
+./configure --cxx=<path of your c++ compiler> --cc=<path of your c compiler> <other options>
+@end example

 
 @node Make targets
 @section Make targets
 
 @node Make targets
 @section Make targets