linux-kernel/linux-7.2.3/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:
      - description: Platform (non-PCIe) IOMMU implementations
        items:
          - enum:
              - qemu,riscv-iommu
              - tenstorrent,riscv-iommu
          - const: riscv,iommu
      - description: PCIe IOMMU implementations
        items:
          - enum:
              - pci1efd,edf1
          - const: riscv,pci-iommu

  reg:
    minItems: 1
    items:
      - description:
          For non-PCI devices, base address and size of the IOMMU memory
          mapped registers interface. For PCI IOMMU hardware
          implementation, an address of the IOMMU, as defined in the PCI
          Bus Binding reference.
      - description:
          Region containing platform specific MMRs for machine-mode
          configuration, such as PMA and PMP registers.

  reg-names:
    minItems: 1
    items:
      - const: base
      - const: machine

  '#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

allOf:
  - if:
      properties:
        compatible:
          contains:
            enum:
              - tenstorrent,riscv-iommu
    then:
      properties:
        reg:
          minItems: 2
        reg-names:
          minItems: 2
    else:
      properties:
        reg:
          maxItems: 1
        reg-names:
          maxItems: 1

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>;
            };
        };
    };

  - |+
    /* Example 5 (Tenstorrent IOMMU device with MSIs) */
    iommu5: iommu@d2020000 {
        compatible = "tenstorrent,riscv-iommu", "riscv,iommu";
        reg = <0xd2020000 0x10000>, <0xaa000000 0x10000>;
        reg-names = "base", "machine";
        msi-parent = <&imsics_smode>;
        #iommu-cells = <1>;
    };