From: Peter Maydell Date: Wed, 27 Sep 2023 15:11:59 +0000 (+0100) Subject: docs/specs/edu: Convert to rST X-Git-Url: http://git.maquefel.me/?a=commitdiff_plain;h=4df3f195ad8bfe9b444578c8b7b6af5d4492e44c;p=qemu.git docs/specs/edu: Convert to rST Convert docs/specs/edu.txt to rST format. Signed-off-by: Peter Maydell Reviewed-by: Thomas Huth Message-id: 20230927151205.70930-3-peter.maydell@linaro.org --- diff --git a/MAINTAINERS b/MAINTAINERS index 73ec940bea..8e10bd085f 100644 --- a/MAINTAINERS +++ b/MAINTAINERS @@ -1882,6 +1882,7 @@ EDU M: Jiri Slaby S: Maintained F: hw/misc/edu.c +F: docs/specs/edu.rst IDE M: John Snow diff --git a/docs/specs/edu.rst b/docs/specs/edu.rst new file mode 100644 index 0000000000..ae72737dbb --- /dev/null +++ b/docs/specs/edu.rst @@ -0,0 +1,135 @@ + +EDU device +========== + +.. + Copyright (c) 2014-2015 Jiri Slaby + + 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 +University. Students are given this virtual device and are expected to write a +driver with I/Os, IRQs, DMAs and such. + +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]`` + ``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. + +PCI specs +--------- + +PCI ID: + ``1234:11e8`` + +PCI Region 0: + I/O memory, 1 MB in size. Users are supposed to communicate with the card + through this memory. + +MMIO area spec +-------------- + +Only ``size == 4`` accesses are allowed for addresses ``< 0x80``. +``size == 4`` or ``size == 8`` for the rest. + +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). + +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 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 + register below). + +0x60 (WO) : interrupt raise register + Raise an interrupt. The value will be put to the interrupt status + register (using bitwise OR). + +0x64 (WO) : interrupt acknowledge register + Clear an interrupt. The value will be cleared from the interrupt + status register. This needs to be done from the ISR to stop + generating interrupts. + +0x80 (RW) : DMA source address + Where to perform the DMA from. + +0x88 (RW) : DMA destination address + Where to perform the DMA to. + +0x90 (RW) : DMA transfer count + The size of the area to perform the DMA on. + +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. + +The device supports both INTx and MSI interrupt. By default, INTx is +used. Even if the driver disabled INTx and only uses MSI, it still +needs to update the acknowledge register at the end of the IRQ handler +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) + ; + +:: + + 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/edu.txt b/docs/specs/edu.txt deleted file mode 100644 index 0876310809..0000000000 --- a/docs/specs/edu.txt +++ /dev/null @@ -1,115 +0,0 @@ - -EDU device -========== - -Copyright (c) 2014-2015 Jiri Slaby - -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 -University. Students are given this virtual device and are expected to write a -driver with I/Os, IRQs, DMAs and such. - -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] - - 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. - -PCI specs ---------- - -PCI ID: 1234:11e8 - -PCI Region 0: - I/O memory, 1 MB in size. Users are supposed to communicate with the card - through this memory. - -MMIO area spec --------------- - -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 - -0x04 (RW) : card liveness check - 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 - -0x24 (RO) : interrupt status register - It contains values which raised the interrupt (see interrupt raise - register below). - -0x60 (WO) : interrupt raise register - Raise an interrupt. The value will be put to the interrupt status - register (using bitwise OR). - -0x64 (WO) : interrupt acknowledge register - Clear an interrupt. The value will be cleared from the interrupt - status register. This needs to be done from the ISR to stop - generating interrupts. - -0x80 (RW) : DMA source address - Where to perform the DMA from. - -0x88 (RW) : DMA destination address - Where to perform the DMA to. - -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 - -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. - -The device supports both INTx and MSI interrupt. By default, INTx is -used. Even if the driver disabled INTx and only uses MSI, it still -needs to update the acknowledge register at the end of the IRQ handler -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) - ; - -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 d23efbe248..30a0cf3d47 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