docs/specs/edu: Convert to rST

Convert docs/specs/edu.txt to rST format.

Signed-off-by: Peter Maydell <peter.maydell@linaro.org>
Reviewed-by: Thomas Huth <thuth@redhat.com>
Message-id: 20230927151205.70930-3-peter.maydell@linaro.org

MAINTAINERS

@@ -1882,6 +1882,7 @@ EDU
 M: Jiri Slaby <jslaby@suse.cz>
 S: Maintained
 F: hw/misc/edu.c
+F: docs/specs/edu.rst
 
 IDE
 M: John Snow <jsnow@redhat.com>

docs/specs/edu.rst

@@ -2,9 +2,10 @@
 EDU device
 ==========
 
-Copyright (c) 2014-2015 Jiri Slaby
+..
+   Copyright (c) 2014-2015 Jiri Slaby
 
-This document is licensed under the GPLv2 (or later).
+   This document is licensed under the GPLv2 (or later).
 
 This is an educational device for writing (kernel) drivers. Its original
 intention was to support the Linux kernel lectures taught at the Masaryk
@@ -15,10 +16,11 @@ The devices behaves very similar to the PCI bridge present in the COMBO6 cards
 developed under the Liberouter wings. Both PCI device ID and PCI space is
 inherited from that device.
 
-Command line switches:
+Command line switches
-    -device edu[,dma_mask=mask]
+---------------------
 
-    dma_mask makes the virtual device work with DMA addresses with the given
+``-device edu[,dma_mask=mask]``
+    ``dma_mask`` makes the virtual device work with DMA addresses with the given
     mask. For educational purposes, the device supports only 28 bits (256 MiB)
     by default. Students shall set dma_mask for the device in the OS driver
     properly.
@@ -26,7 +28,8 @@ Command line switches:
 PCI specs
 ---------
 
-PCI ID: 1234:11e8
+PCI ID:
+   ``1234:11e8``
 
 PCI Region 0:
    I/O memory, 1 MB in size. Users are supposed to communicate with the card
@@ -35,24 +38,29 @@ PCI Region 0:
 MMIO area spec
 --------------
 
-Only size == 4 accesses are allowed for addresses < 0x80. size == 4 or
+Only ``size == 4`` accesses are allowed for addresses ``< 0x80``.
-size == 8 for the rest.
+``size == 4`` or ``size == 8`` for the rest.
 
-0x00 (RO) : identification (0xRRrr00edu)
+0x00 (RO) : identification
-	    RR -- major version
+            Value is in the form ``0xRRrr00edu`` where:
-	    rr -- minor version
+	    - ``RR`` -- major version
+	    - ``rr`` -- minor version
 
 0x04 (RW) : card liveness check
-	    It is a simple value inversion (~ C operator).
+	    It is a simple value inversion (``~`` C operator).
 
 0x08 (RW) : factorial computation
 	    The stored value is taken and factorial of it is put back here.
 	    This happens only after factorial bit in the status register (0x20
 	    below) is cleared.
 
-0x20 (RW) : status register, bitwise OR
+0x20 (RW) : status register
-	    0x01 -- computing factorial (RO)
+            Bitwise OR of:
-	    0x80 -- raise interrupt after finishing factorial computation
+
+            0x01
+              computing factorial (RO)
+	    0x80
+              raise interrupt after finishing factorial computation
 
 0x24 (RO) : interrupt status register
 	    It contains values which raised the interrupt (see interrupt raise
@@ -76,13 +84,19 @@ size == 8 for the rest.
 0x90 (RW) : DMA transfer count
 	    The size of the area to perform the DMA on.
 
-0x98 (RW) : DMA command register, bitwise OR
+0x98 (RW) : DMA command register
-	    0x01 -- start transfer
+            Bitwise OR of:
-	    0x02 -- direction (0: from RAM to EDU, 1: from EDU to RAM)
+
-	    0x04 -- raise interrupt 0x100 after finishing the DMA
+            0x01
+              start transfer
+	    0x02
+              direction (0: from RAM to EDU, 1: from EDU to RAM)
+	    0x04
+              raise interrupt 0x100 after finishing the DMA
 
 IRQ controller
 --------------
+
 An IRQ is generated when written to the interrupt raise register. The value
 appears in interrupt status register when the interrupt is raised and has to
 be written to the interrupt acknowledge register to lower it.
@@ -94,22 +108,28 @@ routine.
 
 DMA controller
 --------------
+
 One has to specify, source, destination, size, and start the transfer. One
 4096 bytes long buffer at offset 0x40000 is available in the EDU device. I.e.
 one can perform DMA to/from this space when programmed properly.
 
 Example of transferring a 100 byte block to and from the buffer using a given
-PCI address 'addr':
+PCI address ``addr``:
-addr     -> DMA source address
-0x40000  -> DMA destination address
-100      -> DMA transfer count
-1        -> DMA command register
-while (DMA command register & 1)
-	;
 
-0x40000  -> DMA source address
+::
-addr+100 -> DMA destination address
+
-100      -> DMA transfer count
+  addr     -> DMA source address
-3        -> DMA command register
+  0x40000  -> DMA destination address
-while (DMA command register & 1)
+  100      -> DMA transfer count
-	;
+  1        -> DMA command register
+  while (DMA command register & 1)
+      ;
+
+::
+
+  0x40000  -> DMA source address
+  addr+100 -> DMA destination address
+  100      -> DMA transfer count
+  3        -> DMA command register
+  while (DMA command register & 1)
+      ;

docs/specs/index.rst

@@ -25,3 +25,4 @@ guest hardware that is specific to QEMU.
    sev-guest-firmware
    fw_cfg
    vmw_pvscsi-spec
+   edu