From: Peter Maydell <peter.maydell@linaro.org>
To: qemu-devel@nongnu.org
Subject: [PULL 09/33] docs/specs/edu: Convert to rST
Date: Thu, 2 Nov 2023 17:38:11 +0000 [thread overview]
Message-ID: <20231102173835.609985-10-peter.maydell@linaro.org> (raw)
In-Reply-To: <20231102173835.609985-1-peter.maydell@linaro.org>
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 | 1 +
docs/specs/{edu.txt => edu.rst} | 84 ++++++++++++++++++++-------------
docs/specs/index.rst | 1 +
3 files changed, 54 insertions(+), 32 deletions(-)
rename docs/specs/{edu.txt => edu.rst} (64%)
diff --git a/MAINTAINERS b/MAINTAINERS
index 73ec940bea0..8e10bd085ff 100644
--- a/MAINTAINERS
+++ b/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>
diff --git a/docs/specs/edu.txt b/docs/specs/edu.rst
similarity index 64%
rename from docs/specs/edu.txt
rename to docs/specs/edu.rst
index 08763108099..ae72737dbb4 100644
--- a/docs/specs/edu.txt
+++ b/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:
- -device edu[,dma_mask=mask]
+Command line switches
+---------------------
- 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
-size == 8 for the rest.
+Only ``size == 4`` accesses are allowed for addresses ``< 0x80``.
+``size == 4`` or ``size == 8`` for the rest.
-0x00 (RO) : identification (0xRRrr00edu)
- RR -- major version
- rr -- minor version
+0x00 (RO) : identification
+ Value is in the form ``0xRRrr00edu`` where:
+ - ``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
- 0x01 -- computing factorial (RO)
- 0x80 -- raise interrupt after finishing factorial computation
+0x20 (RW) : status register
+ Bitwise OR of:
+
+ 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
- 0x01 -- start transfer
- 0x02 -- direction (0: from RAM to EDU, 1: from EDU to RAM)
- 0x04 -- raise interrupt 0x100 after finishing the DMA
+0x98 (RW) : DMA command register
+ Bitwise OR of:
+
+ 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':
-addr -> DMA source address
-0x40000 -> DMA destination address
-100 -> DMA transfer count
-1 -> DMA command register
-while (DMA command register & 1)
- ;
+PCI address ``addr``:
-0x40000 -> DMA source address
-addr+100 -> DMA destination address
-100 -> DMA transfer count
-3 -> DMA command register
-while (DMA command register & 1)
- ;
+::
+
+ 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
+ 3 -> DMA command register
+ while (DMA command register & 1)
+ ;
diff --git a/docs/specs/index.rst b/docs/specs/index.rst
index d23efbe2480..30a0cf3d47e 100644
--- a/docs/specs/index.rst
+++ b/docs/specs/index.rst
@@ -25,3 +25,4 @@ guest hardware that is specific to QEMU.
sev-guest-firmware
fw_cfg
vmw_pvscsi-spec
+ edu
--
2.34.1
next prev parent reply other threads:[~2023-11-02 17:40 UTC|newest]
Thread overview: 35+ messages / expand[flat|nested] mbox.gz Atom feed top
2023-11-02 17:38 [PULL 00/33] target-arm queue Peter Maydell
2023-11-02 17:38 ` [PULL 01/33] linux-user/elfload: Add missing arm64 hwcap values Peter Maydell
2023-11-02 17:38 ` [PULL 02/33] hw/input/stellaris_input: Rename to stellaris_gamepad Peter Maydell
2023-11-02 17:38 ` [PULL 03/33] hw/input/stellaris_gamepad: Rename structs to our usual convention Peter Maydell
2023-11-02 17:38 ` [PULL 04/33] qdev: Add qdev_prop_set_array() Peter Maydell
2023-11-02 17:38 ` [PULL 05/33] hw/input/stellaris_gamepad: Remove StellarisGamepadButton struct Peter Maydell
2023-11-02 17:38 ` [PULL 06/33] hw/input/stellaris_input: Convert to qdev Peter Maydell
2023-11-02 17:38 ` [PULL 07/33] hw/input/stellaris_gamepad: Convert to qemu_input_handler_register() Peter Maydell
2023-11-02 17:38 ` [PULL 08/33] docs/specs/vmw_pvscsi-spec: Convert to rST Peter Maydell
2023-11-02 17:38 ` Peter Maydell [this message]
2023-11-02 17:38 ` [PULL 10/33] docs/specs/ivshmem-spec: " Peter Maydell
2023-11-02 17:38 ` [PULL 11/33] docs/specs/pvpanic: " Peter Maydell
2023-11-02 17:38 ` [PULL 12/33] docs/specs/standard-vga: " Peter Maydell
2023-11-02 17:38 ` [PULL 13/33] docs/specs/virt-ctlr: " Peter Maydell
2023-11-02 17:38 ` [PULL 14/33] docs/specs/vmcoreinfo: " Peter Maydell
2023-11-02 17:38 ` [PULL 15/33] docs/specs/vmgenid: " Peter Maydell
2023-11-02 17:38 ` [PULL 16/33] MAINTAINERS: Make sure that gicv3_internal.h is covered, too Peter Maydell
2023-11-02 17:38 ` [PULL 17/33] hw/arm/pxa2xx_gpio: Pass CPU using QOM link property Peter Maydell
2023-11-02 17:38 ` [PULL 18/33] hw/watchdog/wdt_imx2: Trace MMIO access Peter Maydell
2023-11-02 17:38 ` [PULL 19/33] hw/watchdog/wdt_imx2: Trace timer activity Peter Maydell
2023-11-02 17:38 ` [PULL 20/33] hw/misc/imx7_snvs: Trace MMIO access Peter Maydell
2023-11-02 17:38 ` [PULL 21/33] hw/misc/imx6_ccm: Convert DPRINTF to trace events Peter Maydell
2023-11-02 17:38 ` [PULL 22/33] hw/i2c/pm_smbus: " Peter Maydell
2023-11-02 17:38 ` [PULL 23/33] target/arm: Enable FEAT_MOPS insns in user-mode emulation Peter Maydell
2023-11-02 17:38 ` [PULL 24/33] linux-user: Report AArch64 hwcap2 fields above bit 31 Peter Maydell
2023-11-02 17:38 ` [PULL 25/33] target/arm: Make FEAT_MOPS SET* insns handle Xs == XZR correctly Peter Maydell
2023-11-02 17:38 ` [PULL 26/33] target/arm: Fix SVE STR increment Peter Maydell
2023-11-02 17:38 ` [PULL 27/33] hw/char/stm32f2xx_usart: Extract common IRQ update code to update_irq() Peter Maydell
2023-11-02 17:38 ` [PULL 28/33] hw/char/stm32f2xx_usart: Update IRQ when DR is written Peter Maydell
2023-11-02 17:38 ` [PULL 29/33] hw/char/stm32f2xx_usart: Add more definitions for CR1 register Peter Maydell
2023-11-02 17:38 ` [PULL 30/33] target/arm: Correctly propagate stage 1 BTI guarded bit in a two-stage walk Peter Maydell
2023-11-02 17:38 ` [PULL 31/33] hw/misc: Introduce AMD/Xilix Versal TRNG device Peter Maydell
2023-11-02 17:38 ` [PULL 32/33] hw/arm: xlnx-versal-virt: Add AMD/Xilinx " Peter Maydell
2023-11-02 17:38 ` [PULL 33/33] tests/qtest: Introduce tests for AMD/Xilinx Versal " Peter Maydell
2023-11-03 3:24 ` [PULL 00/33] target-arm queue Stefan Hajnoczi
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=20231102173835.609985-10-peter.maydell@linaro.org \
--to=peter.maydell@linaro.org \
--cc=qemu-devel@nongnu.org \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.