docs/system: convert Texinfo documentation to rST

Apart from targets.rst, which was written by hand, this is an automated
conversion obtained with the following command:

  makeinfo --force -o - --docbook \
    -D 'qemu_system_x86 QEMU_SYSTEM_X86_MACRO' \
    -D 'qemu_system     QEMU_SYSTEM_MACRO' \
    $texi | pandoc -f docbook -t rst+smart | perl -e '
      $/=undef;
      $_ = <>;
      s/^-  − /-  /gm;
      s/QEMU_SYSTEM_MACRO/|qemu_system|/g;
      s/QEMU_SYSTEM_X86_MACRO/|qemu_system_x86|/g;
      s/(?=::\n\n +\|qemu)/.. parsed-literal/g;
      s/:\n\n::$/::/gm;
      print' > $rst

In addition, the following changes were made manually:

- target-i386.rst and target-mips.rst: replace CPU model documentation with
  an include directive

- monitor.rst: replace the command section with a comment

- images.rst: add toctree

- target-arm.rst: Replace use of :math: (which Sphinx complains
  about) with :sup:, and hide it behind |I2C| and |I2C| substitutions.

Content that is not @included remains exclusive to qemu-doc.texi.

Signed-off-by: Paolo Bonzini <[email protected]>
Reviewed-by: Peter Maydell <[email protected]>
Reviewed-by: Alex Bennée <[email protected]>
Tested-by: Alex Bennée <[email protected]>
Signed-off-by: Peter Maydell <[email protected]>
Message-id: [email protected]
Message-id: [email protected]
[PMM: Fixed target-arm.rst use of :math:; remove out of date
 note about images.rst from commit message; fixed expansion
 of |qemu_system_x86|; use parsed-literal in invocation.rst
 when we want to use |qemu_system_x86|; fix incorrect subsection
 level for "OS requirements" in target-i386.rst; fix incorrect
 syntax for making links to other sections of the manual]
Reviewed-by: Peter Maydell <[email protected]>
Signed-off-by: Peter Maydell <[email protected]>

docs/defs.rst.inc

@@ -3,9 +3,13 @@
    all rST files as part of the epilogue by docs/conf.py.  conf.py
    also defines some dynamically generated substitutions like CONFDIR.
 
-   Note that |qemu_system| is intended to be used inside a parsed-literal
-   block: the definition must not include extra literal formatting with
-   ``..``: this works in the HTML output but the manpages will end up
-   misrendered with following normal text incorrectly in boldface.
+   Note that |qemu_system| and |qemu_system_x86| are intended to be
+   used inside a parsed-literal block: the definition must not include
+   extra literal formatting with ``..``: this works in the HTML output
+   but the manpages will end up misrendered with following normal text
+   incorrectly in boldface.
 
 .. |qemu_system| replace:: qemu-system-x86_64
+.. |qemu_system_x86| replace:: qemu_system-x86_64
+.. |I2C| replace:: I\ :sup:`2`\ C
+.. |I2S| replace:: I\ :sup:`2`\ S

docs/system/build-platforms.rst

@@ -0,0 +1,79 @@
+.. _Supported-build-platforms:
+
+Supported build platforms
+=========================
+
+QEMU aims to support building and executing on multiple host OS
+platforms. This appendix outlines which platforms are the major build
+targets. These platforms are used as the basis for deciding upon the
+minimum required versions of 3rd party software QEMU depends on. The
+supported platforms are the targets for automated testing performed by
+the project when patches are submitted for review, and tested before and
+after merge.
+
+If a platform is not listed here, it does not imply that QEMU won't
+work. If an unlisted platform has comparable software versions to a
+listed platform, there is every expectation that it will work. Bug
+reports are welcome for problems encountered on unlisted platforms
+unless they are clearly older vintage than what is described here.
+
+Note that when considering software versions shipped in distros as
+support targets, QEMU considers only the version number, and assumes the
+features in that distro match the upstream release with the same
+version. In other words, if a distro backports extra features to the
+software in their distro, QEMU upstream code will not add explicit
+support for those backports, unless the feature is auto-detectable in a
+manner that works for the upstream releases too.
+
+The Repology site https://repology.org is a useful resource to identify
+currently shipped versions of software in various operating systems,
+though it does not cover all distros listed below.
+
+Linux OS
+--------
+
+For distributions with frequent, short-lifetime releases, the project
+will aim to support all versions that are not end of life by their
+respective vendors. For the purposes of identifying supported software
+versions, the project will look at Fedora, Ubuntu, and openSUSE distros.
+Other short- lifetime distros will be assumed to ship similar software
+versions.
+
+For distributions with long-lifetime releases, the project will aim to
+support the most recent major version at all times. Support for the
+previous major version will be dropped 2 years after the new major
+version is released, or when it reaches "end of life". For the purposes
+of identifying supported software versions, the project will look at
+RHEL, Debian, Ubuntu LTS, and SLES distros. Other long-lifetime distros
+will be assumed to ship similar software versions.
+
+Windows
+-------
+
+The project supports building with current versions of the MinGW
+toolchain, hosted on Linux.
+
+macOS
+-----
+
+The project supports building with the two most recent versions of
+macOS, with the current homebrew package set available.
+
+FreeBSD
+-------
+
+The project aims to support the all the versions which are not end of
+life.
+
+NetBSD
+------
+
+The project aims to support the most recent major version at all times.
+Support for the previous major version will be dropped 2 years after the
+new major version is released.
+
+OpenBSD
+-------
+
+The project aims to support the all the versions which are not end of
+life.

docs/system/gdb.rst

@@ -0,0 +1,81 @@
+.. _gdb_005fusage:
+
+GDB usage
+---------
+
+QEMU has a primitive support to work with gdb, so that you can do
+'Ctrl-C' while the virtual machine is running and inspect its state.
+
+In order to use gdb, launch QEMU with the '-s' option. It will wait for
+a gdb connection:
+
+.. parsed-literal::
+
+   |qemu_system| -s -kernel bzImage -hda rootdisk.img -append "root=/dev/hda"
+   Connected to host network interface: tun0
+   Waiting gdb connection on port 1234
+
+Then launch gdb on the 'vmlinux' executable::
+
+   > gdb vmlinux
+
+In gdb, connect to QEMU::
+
+   (gdb) target remote localhost:1234
+
+Then you can use gdb normally. For example, type 'c' to launch the
+kernel::
+
+   (gdb) c
+
+Here are some useful tips in order to use gdb on system code:
+
+1. Use ``info reg`` to display all the CPU registers.
+
+2. Use ``x/10i $eip`` to display the code at the PC position.
+
+3. Use ``set architecture i8086`` to dump 16 bit code. Then use
+   ``x/10i $cs*16+$eip`` to dump the code at the PC position.
+
+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 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:
+
+``maintenance packet qqemu.sstepbits``
+   This will display the MASK bits used to control the single stepping
+   IE:
+
+   ::
+
+      (gdb) maintenance packet qqemu.sstepbits
+      sending: "qqemu.sstepbits"
+      received: "ENABLE=1,NOIRQ=2,NOTIMER=4"
+
+``maintenance packet qqemu.sstep``
+   This will display the current value of the mask used when single
+   stepping IE:
+
+   ::
+
+      (gdb) maintenance packet qqemu.sstep
+      sending: "qqemu.sstep"
+      received: "0x7"
+
+``maintenance packet Qqemu.sstep=HEX_VALUE``
+   This will change the single step mask, so if wanted to enable IRQs on
+   the single step, but not timers, you would use:
+
+   ::
+
+      (gdb) maintenance packet Qqemu.sstep=0x5
+      sending: "qemu.sstep=0x5"
+      received: "OK"

docs/system/images.rst

@@ -0,0 +1,85 @@
+.. _disk_005fimages:
+
+Disk Images
+-----------
+
+QEMU supports many disk image formats, including growable disk images
+(their size increase as non empty sectors are written), compressed and
+encrypted disk images.
+
+.. _disk_005fimages_005fquickstart:
+
+Quick start for disk image creation
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+You can create a disk image with the command::
+
+   qemu-img create myimage.img mysize
+
+where myimage.img is the disk image filename and mysize is its size in
+kilobytes. You can add an ``M`` suffix to give the size in megabytes and
+a ``G`` suffix for gigabytes.
+
+See the qemu-img invocation documentation for more information.
+
+.. _disk_005fimages_005fsnapshot_005fmode:
+
+Snapshot mode
+~~~~~~~~~~~~~
+
+If you use the option ``-snapshot``, all disk images are considered as
+read only. When sectors in written, they are written in a temporary file
+created in ``/tmp``. You can however force the write back to the raw
+disk images by using the ``commit`` monitor command (or C-a s in the
+serial console).
+
+.. _vm_005fsnapshots:
+
+VM snapshots
+~~~~~~~~~~~~
+
+VM snapshots are snapshots of the complete virtual machine including CPU
+state, RAM, device state and the content of all the writable disks. In
+order to use VM snapshots, you must have at least one non removable and
+writable block device using the ``qcow2`` disk image format. Normally
+this device is the first virtual hard drive.
+
+Use the monitor command ``savevm`` to create a new VM snapshot or
+replace an existing one. A human readable name can be assigned to each
+snapshot in addition to its numerical ID.
+
+Use ``loadvm`` to restore a VM snapshot and ``delvm`` to remove a VM
+snapshot. ``info snapshots`` lists the available snapshots with their
+associated information::
+
+   (qemu) info snapshots
+   Snapshot devices: hda
+   Snapshot list (from hda):
+   ID        TAG                 VM SIZE                DATE       VM CLOCK
+   1         start                   41M 2006-08-06 12:38:02   00:00:14.954
+   2                                 40M 2006-08-06 12:43:29   00:00:18.633
+   3         msys                    40M 2006-08-06 12:44:04   00:00:23.514
+
+A VM snapshot is made of a VM state info (its size is shown in
+``info snapshots``) and a snapshot of every writable disk image. The VM
+state info is stored in the first ``qcow2`` non removable and writable
+block device. The disk image snapshots are stored in every disk image.
+The size of a snapshot in a disk image is difficult to evaluate and is
+not shown by ``info snapshots`` because the associated disk sectors are
+shared among all the snapshots to save disk space (otherwise each
+snapshot would need a full copy of all the disk images).
+
+When using the (unrelated) ``-snapshot`` option
+(:ref:`disk_005fimages_005fsnapshot_005fmode`),
+you can always make VM snapshots, but they are deleted as soon as you
+exit QEMU.
+
+VM snapshots currently have the following known limitations:
+
+-  They cannot cope with removable devices if they are removed or
+   inserted after a snapshot is done.
+
+-  A few device drivers still have incomplete snapshot support so their
+   state is not saved or restored properly (in particular USB).
+
+.. include:: qemu-block-drivers.rst.inc

docs/system/index.rst

@@ -12,8 +12,25 @@ or Hypervisor.Framework.
 Contents:
 
 .. toctree::
-   :maxdepth: 2
+   :maxdepth: 3
+
+   quickstart
+   invocation
+   keys
+   mux-chardev
+   monitor
+   images
+   net
+   usb
+   ivshmem
+   linuxboot
+   vnc-security
+   tls
+   gdb
    managed-startup
+   targets
    security
    vfio-ap
    deprecated
+   build-platforms
+   license