[5/8] docs/specs/standard-vga: Convert to rST

Convert docs/specs/standard-vga.txt to rST format.

Signed-off-by: Peter Maydell <peter.maydell@linaro.org>
---
 docs/specs/index.rst        |  1 +
 docs/specs/standard-vga.rst | 94 +++++++++++++++++++++++++++++++++++++
 docs/specs/standard-vga.txt | 81 --------------------------------
 hw/display/vga-isa.c        |  2 +-
 hw/display/vga-pci.c        |  2 +-
 5 files changed, 97 insertions(+), 83 deletions(-)
 create mode 100644 docs/specs/standard-vga.rst
 delete mode 100644 docs/specs/standard-vga.txt

On 27/9/23 17:12, Peter Maydell wrote:
> Convert docs/specs/standard-vga.txt to rST format.
> 
> Signed-off-by: Peter Maydell <peter.maydell@linaro.org>
> ---
>   docs/specs/index.rst        |  1 +
>   docs/specs/standard-vga.rst | 94 +++++++++++++++++++++++++++++++++++++
>   docs/specs/standard-vga.txt | 81 --------------------------------
>   hw/display/vga-isa.c        |  2 +-
>   hw/display/vga-pci.c        |  2 +-
>   5 files changed, 97 insertions(+), 83 deletions(-)
>   create mode 100644 docs/specs/standard-vga.rst
>   delete mode 100644 docs/specs/standard-vga.txt

$ ./scripts/get_maintainer.pl -f docs/specs/standard-vga.txt
get_maintainer.pl: No maintainers found, printing recent contributors.
get_maintainer.pl: Do not blindly cc: them on patches!  Use common sense.

./scripts/get_maintainer.pl -f hw/display/vga-isa.c
Gerd Hoffmann <kraxel@redhat.com> (maintainer:Standard VGA)
qemu-devel@nongnu.org (open list:All patches CC here)

Cc'ing Gerd.

Reviewed-by: Philippe Mathieu-Daudé <philmd@linaro.org>

Maybe worth squashing:

-- >8 --
diff --git a/MAINTAINERS b/MAINTAINERS
index cd8d6b140f..1fdaaad072 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -2466,6 +2466,7 @@ F: hw/display/vga*
  F: hw/display/bochs-display.c
  F: include/hw/display/vga.h
  F: include/hw/display/bochs-vbe.h
+F: docs/specs/standard-vga.rst

---

> diff --git a/docs/specs/index.rst b/docs/specs/index.rst
> index 52bfab2f68b..ee84b8109d6 100644
> --- a/docs/specs/index.rst
> +++ b/docs/specs/index.rst
> @@ -28,3 +28,4 @@ guest hardware that is specific to QEMU.
>      edu
>      ivshmem-spec
>      pvpanic
> +   standard-vga
> diff --git a/docs/specs/standard-vga.rst b/docs/specs/standard-vga.rst
> new file mode 100644
> index 00000000000..992f429ced1
> --- /dev/null
> +++ b/docs/specs/standard-vga.rst
> @@ -0,0 +1,94 @@
> +
> +QEMU Standard VGA
> +=================
> +
> +Exists in two variants, for isa and pci.
> +
> +command line switches:
> +
> +``-vga std``
> +   picks isa for -M isapc, otherwise pci
> +``-device VGA``
> +   pci variant
> +``-device isa-vga``
> +   isa variant
> +``-device secondary-vga``
> +   legacy-free pci variant
> +
> +
> +PCI spec
> +--------
> +
> +Applies to the pci variant only for obvious reasons.
> +
> +PCI ID
> +   ``1234:1111``
> +
> +PCI Region 0
> +   Framebuffer memory, 16 MB in size (by default).
> +   Size is tunable via vga_mem_mb property.
> +
> +PCI Region 1
> +   Reserved (so we have the option to make the framebuffer bar 64bit).
> +
> +PCI Region 2
> +   MMIO bar, 4096 bytes in size (QEMU 1.3+)
> +
> +PCI ROM Region
> +   Holds the vgabios (QEMU 0.14+).
> +
> +
> +The legacy-free variant has no ROM and has ``PCI_CLASS_DISPLAY_OTHER``
> +instead of ``PCI_CLASS_DISPLAY_VGA``.
> +
> +
> +IO ports used
> +-------------
> +
> +Doesn't apply to the legacy-free pci variant, use the MMIO bar instead.
> +
> +``03c0 - 03df``
> +   standard vga ports
> +``01ce``
> +   bochs vbe interface index port
> +``01cf``
> +   bochs vbe interface data port (x86 only)
> +``01d0``
> +   bochs vbe interface data port
> +
> +
> +Memory regions used
> +-------------------
> +
> +``0xe0000000``
> +  Framebuffer memory, isa variant only.
> +
> +The pci variant used to mirror the framebuffer bar here, QEMU 0.14+
> +stops doing that (except when in ``-M pc-$old`` compat mode).
> +
> +
> +MMIO area spec
> +--------------
> +
> +Likewise applies to the pci variant only for obvious reasons.
> +
> +``0000 - 03ff``
> +  edid data blob.
> +``0400 - 041f``
> +  vga ioports (``0x3c0`` to ``0x3df``), remapped 1:1. Word access
> +  is supported, bytes are written in little endian order (aka index
> +  port first),  so indexed registers can be updated with a single
> +  mmio write (and thus only one vmexit).
> +``0500 - 0515``
> +  bochs dispi interface registers, mapped flat without index/data ports.
> +  Use ``(index << 1)`` as offset for (16bit) register access.
> +``0600 - 0607``
> +  QEMU extended registers.  QEMU 2.2+ only.
> +  The pci revision is 2 (or greater) when these registers are present.
> +  The registers are 32bit.
> +``0600``
> +  QEMU extended register region size, in bytes.
> +``0604``
> +  framebuffer endianness register.
> +  - ``0xbebebebe`` indicates big endian.
> +  - ``0x1e1e1e1e`` indicates little endian.
> diff --git a/docs/specs/standard-vga.txt b/docs/specs/standard-vga.txt
> deleted file mode 100644
> index 18f75f1b302..00000000000
> --- a/docs/specs/standard-vga.txt
> +++ /dev/null
> @@ -1,81 +0,0 @@
> -
> -QEMU Standard VGA
> -=================
> -
> -Exists in two variants, for isa and pci.
> -
> -command line switches:
> -    -vga std               [ picks isa for -M isapc, otherwise pci ]
> -    -device VGA            [ pci variant ]
> -    -device isa-vga        [ isa variant ]
> -    -device secondary-vga  [ legacy-free pci variant ]
> -
> -
> -PCI spec
> ---------
> -
> -Applies to the pci variant only for obvious reasons.
> -
> -PCI ID: 1234:1111
> -
> -PCI Region 0:
> -   Framebuffer memory, 16 MB in size (by default).
> -   Size is tunable via vga_mem_mb property.
> -
> -PCI Region 1:
> -   Reserved (so we have the option to make the framebuffer bar 64bit).
> -
> -PCI Region 2:
> -   MMIO bar, 4096 bytes in size (qemu 1.3+)
> -
> -PCI ROM Region:
> -   Holds the vgabios (qemu 0.14+).
> -
> -
> -The legacy-free variant has no ROM and has PCI_CLASS_DISPLAY_OTHER
> -instead of PCI_CLASS_DISPLAY_VGA.
> -
> -
> -IO ports used
> --------------
> -
> -Doesn't apply to the legacy-free pci variant, use the MMIO bar instead.
> -
> -03c0 - 03df : standard vga ports
> -01ce        : bochs vbe interface index port
> -01cf        : bochs vbe interface data port (x86 only)
> -01d0        : bochs vbe interface data port
> -
> -
> -Memory regions used
> --------------------
> -
> -0xe0000000 : Framebuffer memory, isa variant only.
> -
> -The pci variant used to mirror the framebuffer bar here, qemu 0.14+
> -stops doing that (except when in -M pc-$old compat mode).
> -
> -
> -MMIO area spec
> ---------------
> -
> -Likewise applies to the pci variant only for obvious reasons.
> -
> -0000 - 03ff : edid data blob.
> -0400 - 041f : vga ioports (0x3c0 -> 0x3df), remapped 1:1.
> -              word access is supported, bytes are written
> -              in little endia order (aka index port first),
> -              so indexed registers can be updated with a
> -              single mmio write (and thus only one vmexit).
> -0500 - 0515 : bochs dispi interface registers, mapped flat
> -              without index/data ports.  Use (index << 1)
> -              as offset for (16bit) register access.
> -
> -0600 - 0607 : qemu extended registers.  qemu 2.2+ only.
> -              The pci revision is 2 (or greater) when
> -              these registers are present.  The registers
> -              are 32bit.
> -  0600      : qemu extended register region size, in bytes.
> -  0604      : framebuffer endianness register.
> -              - 0xbebebebe indicates big endian.
> -              - 0x1e1e1e1e indicates little endian.
> diff --git a/hw/display/vga-isa.c b/hw/display/vga-isa.c
> index 2a5437d8037..c096ec93e52 100644
> --- a/hw/display/vga-isa.c
> +++ b/hw/display/vga-isa.c
> @@ -1,7 +1,7 @@
>   /*
>    * QEMU ISA VGA Emulator.
>    *
> - * see docs/specs/standard-vga.txt for virtual hardware specs.
> + * see docs/specs/standard-vga.rst for virtual hardware specs.
>    *
>    * Copyright (c) 2003 Fabrice Bellard
>    *
> diff --git a/hw/display/vga-pci.c b/hw/display/vga-pci.c
> index b351b8f299d..e4f45b4476d 100644
> --- a/hw/display/vga-pci.c
> +++ b/hw/display/vga-pci.c
> @@ -1,7 +1,7 @@
>   /*
>    * QEMU PCI VGA Emulator.
>    *
> - * see docs/specs/standard-vga.txt for virtual hardware specs.
> + * see docs/specs/standard-vga.rst for virtual hardware specs.
>    *
>    * Copyright (c) 2003 Fabrice Bellard
>    *