Documentation/devicetree/bindings/iommu/riscv,iommu.yaml

# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
%YAML 1.2
---
$id: http://devicetree.org/schemas/iommu/riscv,iommu.yaml#
$schema: http://devicetree.org/meta-schemas/core.yaml#

title: RISC-V IOMMU Architecture Implementation

maintainers:
  - Tomasz Jeznach <tjeznach@rivosinc.com>

description: |
  The RISC-V IOMMU provides memory address translation and isolation for
  input and output devices, supporting per-device translation context,
  shared process address spaces including the ATS and PRI components of
  the PCIe specification, two stage address translation and MSI remapping.
  It supports identical translation table format to the RISC-V address
  translation tables with page level access and protection attributes.
  Hardware uses in-memory command and fault reporting queues with wired
  interrupt or MSI notifications.

  Visit https://github.com/riscv-non-isa/riscv-iommu for more details.

  For information on assigning RISC-V IOMMU to its peripheral devices,
  see generic IOMMU bindings.

properties:
  # For PCIe IOMMU hardware compatible property should contain the vendor
  # and device ID according to the PCI Bus Binding specification.
  # Since PCI provides built-in identification methods, compatible is not
  # actually required. For non-PCIe hardware implementations 'riscv,iommu'
  # should be specified along with 'reg' property providing MMIO location.
  compatible:
    oneOf:
      - items:
          - enum:
              - qemu,riscv-iommu
          - const: riscv,iommu
      - items:
          - enum:
              - pci1efd,edf1
          - const: riscv,pci-iommu

  reg:
    maxItems: 1
    description:
      For non-PCI devices this represents base address and size of for the
      IOMMU memory mapped registers interface.
      For PCI IOMMU hardware implementation this should represent an address
      of the IOMMU, as defined in the PCI Bus Binding reference.

  '#iommu-cells':
    const: 1
    description:
      The single cell describes the requester id emitted by a master to the
      IOMMU.

  interrupts:
    minItems: 1
    maxItems: 4
    description:
      Wired interrupt vectors available for RISC-V IOMMU to notify the
      RISC-V HARTS. The cause to interrupt vector is software defined
      using IVEC IOMMU register.

  msi-parent: true

  power-domains:
    maxItems: 1

required:
  - compatible
  - reg
  - '#iommu-cells'

additionalProperties: false

examples:
  - |+
    /* Example 1 (IOMMU device with wired interrupts) */
    #include <dt-bindings/interrupt-controller/irq.h>

    iommu1: iommu@1bccd000 {
        compatible = "qemu,riscv-iommu", "riscv,iommu";
        reg = <0x1bccd000 0x1000>;
        interrupt-parent = <&aplic_smode>;
        interrupts = <32 IRQ_TYPE_LEVEL_HIGH>,
                     <33 IRQ_TYPE_LEVEL_HIGH>,
                     <34 IRQ_TYPE_LEVEL_HIGH>,
                     <35 IRQ_TYPE_LEVEL_HIGH>;
        #iommu-cells = <1>;
    };

    /* Device with two IOMMU device IDs, 0 and 7 */
    master1 {
        iommus = <&iommu1 0>, <&iommu1 7>;
    };

  - |+
    /* Example 2 (IOMMU device with shared wired interrupt) */
    #include <dt-bindings/interrupt-controller/irq.h>

    iommu2: iommu@1bccd000 {
        compatible = "qemu,riscv-iommu", "riscv,iommu";
        reg = <0x1bccd000 0x1000>;
        interrupt-parent = <&aplic_smode>;
        interrupts = <32 IRQ_TYPE_LEVEL_HIGH>;
        #iommu-cells = <1>;
    };

  - |+
    /* Example 3 (IOMMU device with MSIs) */
    iommu3: iommu@1bcdd000 {
        compatible = "qemu,riscv-iommu", "riscv,iommu";
        reg = <0x1bccd000 0x1000>;
        msi-parent = <&imsics_smode>;
        #iommu-cells = <1>;
    };

  - |+
    /* Example 4 (IOMMU PCIe device with MSIs) */
    bus {
        #address-cells = <2>;
        #size-cells = <2>;

        pcie@30000000 {
            device_type = "pci";
            #address-cells = <3>;
            #size-cells = <2>;
            reg = <0x0 0x30000000  0x0 0x1000000>;
            ranges = <0x02000000 0x0 0x41000000  0x0 0x41000000  0x0 0x0f000000>;

            /*
             * The IOMMU manages all functions in this PCI domain except
             * itself. Omit BDF 00:01.0.
             */
            iommu-map = <0x0 &iommu0 0x0 0x8>,
                        <0x9 &iommu0 0x9 0xfff7>;

            /* The IOMMU programming interface uses slot 00:01.0 */
            iommu0: iommu@1,0 {
               compatible = "pci1efd,edf1", "riscv,pci-iommu";
               reg = <0x800 0 0 0 0>;
               #iommu-cells = <1>;
            };
        };
    };