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
This commit is contained in:
Peter Maydell 2023-09-27 16:11:59 +01:00
parent 8472cc5dbe
commit 4df3f195ad
3 changed files with 54 additions and 32 deletions

View File

@ -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>

View File

@ -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)
;

View File

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