Re: [PATCH v5 13/13] docs/specs: add riscv-iommu

[Alistair Francis]

On Wed, Jul 24, 2024 at 10:56 PM Daniel Henrique Barboza
<dbarboza@ventanamicro.com> wrote:
>
>
>
> On 7/19/24 6:34 AM, Alistair Francis wrote:
> > On Tue, Jul 9, 2024 at 3:37 AM Daniel Henrique Barboza
> > <dbarboza@ventanamicro.com> wrote:
> >>
> >> Add a simple guideline to use the existing RISC-V IOMMU support we just
> >> added.
> >>
> >> This doc will be updated once we add the riscv-iommu-sys device.
> >>
> >> Signed-off-by: Daniel Henrique Barboza <dbarboza@ventanamicro.com>
> >> ---
> >>   docs/specs/index.rst       |  1 +
> >>   docs/specs/riscv-iommu.rst | 55 ++++++++++++++++++++++++++++++++++++++
> >>   docs/system/riscv/virt.rst | 13 +++++++++
> >>   3 files changed, 69 insertions(+)
> >>   create mode 100644 docs/specs/riscv-iommu.rst
> >>
> >> diff --git a/docs/specs/index.rst b/docs/specs/index.rst
> >> index 1484e3e760..c68cd9ae6c 100644
> >> --- a/docs/specs/index.rst
> >> +++ b/docs/specs/index.rst
> >> @@ -33,3 +33,4 @@ guest hardware that is specific to QEMU.
> >>      virt-ctlr
> >>      vmcoreinfo
> >>      vmgenid
> >> +   riscv-iommu
> >> diff --git a/docs/specs/riscv-iommu.rst b/docs/specs/riscv-iommu.rst
> >> new file mode 100644
> >> index 0000000000..fa38ff7667
> >> --- /dev/null
> >> +++ b/docs/specs/riscv-iommu.rst
> >> @@ -0,0 +1,55 @@
> >> +.. _riscv-iommu:
> >> +
> >> +RISC-V IOMMU support for RISC-V machines
> >> +========================================
> >> +
> >> +QEMU implements a RISC-V IOMMU emulation based on the RISC-V IOMMU spec
> >> +version 1.0 [1].
> >> +
> >> +The emulation includes a PCI reference device, riscv-iommu-pci, that QEMU
> >> +RISC-V boards can use.  The 'virt' RISC-V machine is compatible with this
> >> +device.
> >> +
> >> +A platform device that implements the RISC-V IOMMU will be added in the
> >> +future.
> >> +
> >> +
> >> +riscv-iommu-pci reference device
> >> +--------------------------------
> >> +
> >> +This device implements the RISC-V IOMMU emulation as recommended by the 
> >> section
> >> +"Integrating an IOMMU as a PCIe device" of [1]: a PCI device with base 
> >> class 08h,
> >> +sub-class 06h and programming interface 00h.
> >> +
> >> +As a reference device it doesn't implement anything outside of the 
> >> specification,
> >> +so it uses a generic default PCI ID given by QEMU: 1b36:0014.
> >> +
> >> +To include the device in the 'virt' machine:
> >> +
> >> +.. code-block:: bash
> >> +
> >> +  $ qemu-system-riscv64 -M virt -device riscv-iommu-pci (...)
> >
> > We should add a sentence saying what this does. As in what should a
> > user expect after they have done this
>
> I suppose we can add a boilerplate sentence about what an IOMMU does, but 
> aside
> from that I'm not sure what to say about user expectation. If you're adding an
> IOMMU (or any device in QEMU) it's expected that the user has some idea of 
> what
> the device is supposed to do in the board and so on hehe

That's fair and I don't think we need to describe what an IOMMU does,
I more meant the fact it's attached via PCI.

We specifically say a "platform device will be added later" so I think
we should just be clear on what a PCI IOMMU is

Alistair