[PULL 12/33] docs/specs/standard-vga: Convert to rST

From: Peter Maydell <peter.maydell@linaro.org>
To: qemu-devel@nongnu.org
Subject: [PULL 12/33] docs/specs/standard-vga: Convert to rST
Date: Thu,  2 Nov 2023 17:38:14 +0000	[thread overview]
Message-ID: <20231102173835.609985-13-peter.maydell@linaro.org> (raw)
In-Reply-To: <20231102173835.609985-1-peter.maydell@linaro.org>

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

Signed-off-by: Peter Maydell <peter.maydell@linaro.org>
Message-id: 20230927151205.70930-6-peter.maydell@linaro.org
Reviewed-by: Philippe Mathieu-Daudé <philmd@linaro.org>
---
 MAINTAINERS                 |  1 +
 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 +-
 6 files changed, 98 insertions(+), 83 deletions(-)
 create mode 100644 docs/specs/standard-vga.rst
 delete mode 100644 docs/specs/standard-vga.txt

diff --git a/MAINTAINERS b/MAINTAINERS
index 8e10bd085ff..b5e1765d7a6 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -2468,6 +2468,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
 
 ramfb
 M: Gerd Hoffmann <kraxel@redhat.com>
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
  *
-- 
2.34.1


