# SPDX-License-Identifier: GPL-2.0-only
%YAML 1.2
---
$id: http://devicetree.org/schemas/iommu/arm,smmu.yaml#
$schema: http://devicetree.org/meta-schemas/core.yaml#

title: ARM System MMU Architecture Implementation

maintainers:
  - Will Deacon <will@kernel.org>
  - Robin Murphy <Robin.Murphy@arm.com>

description: |+
  ARM SoCs may contain an implementation of the ARM System Memory
  Management Unit Architecture, which can be used to provide 1 or 2 stages
  of address translation to bus masters external to the CPU.

  The SMMU may also raise interrupts in response to various fault
  conditions.

properties:
  $nodename:
    pattern: "^iommu@[0-9a-f]*"
  compatible:
    oneOf:
      - description: Qcom SoCs implementing "arm,smmu-v2"
        items:
          - enum:
              - qcom,msm8996-smmu-v2
              - qcom,msm8998-smmu-v2
          - const: qcom,smmu-v2

      - description: Qcom SoCs implementing "arm,mmu-500"
        items:
          - enum:
              - qcom,qcm2290-smmu-500
              - qcom,sc7180-smmu-500
              - qcom,sc7280-smmu-500
              - qcom,sc8180x-smmu-500
              - qcom,sc8280xp-smmu-500
              - qcom,sdm845-smmu-500
              - qcom,sdx55-smmu-500
              - qcom,sdx65-smmu-500
              - qcom,sm6350-smmu-500
              - qcom,sm6375-smmu-500
              - qcom,sm8150-smmu-500
              - qcom,sm8250-smmu-500
              - qcom,sm8350-smmu-500
              - qcom,sm8450-smmu-500
          - const: arm,mmu-500
      - description: |
          Qcom SoCs implementing "qcom,qsmmu-v500", which is a arm,mmu-500
          based design with QCOM-designed TBUs and other custom features.

          "qcom,virt-smmu" is a subtype of "qcom,qsmmu-v500" which
          only supports access to the set of registers required by
          the arm specificiation. None of the additional registers
          normally present in qcom,qsmmu-v500 are supported
          currently.
        items:
          - enum:
              - qcom,qsmmu-v500
              - qcom,virt-smmu
      - description: Qcom Adreno GPUs implementing "arm,smmu-v2"
        items:
          - enum:
              - qcom,sc7180-smmu-v2
              - qcom,sdm845-smmu-v2
          - const: qcom,adreno-smmu
          - const: qcom,smmu-v2
      - description: Marvell SoCs implementing "arm,mmu-500"
        items:
          - const: marvell,ap806-smmu-500
          - const: arm,mmu-500
      - description: NVIDIA SoCs that require memory controller interaction
          and may program multiple ARM MMU-500s identically with the memory
          controller interleaving translations between multiple instances
          for improved performance.
        items:
          - enum:
              - nvidia,tegra186-smmu
              - nvidia,tegra194-smmu
              - nvidia,tegra234-smmu
          - const: nvidia,smmu-500
      - items:
          - const: arm,mmu-500
          - const: arm,smmu-v2
      - items:
          - enum:
              - arm,mmu-400
              - arm,mmu-401
          - const: arm,smmu-v1
      - enum:
          - arm,smmu-v1
          - arm,smmu-v2
          - arm,mmu-400
          - arm,mmu-401
          - arm,mmu-500
          - cavium,smmu-v2

  reg:
    minItems: 1
    maxItems: 2

  '#global-interrupts':
    description: The number of global interrupts exposed by the device.
    $ref: /schemas/types.yaml#/definitions/uint32
    minimum: 0
    maximum: 260   # 2 secure, 2 non-secure, and up to 256 perf counters

  '#iommu-cells':
    enum: [ 1, 2 ]
    description: |
      See Documentation/devicetree/bindings/iommu/iommu.txt for details. With a
      value of 1, each IOMMU specifier represents a distinct stream ID emitted
      by that device into the relevant SMMU.

      SMMUs with stream matching support and complex masters may use a value of
      2, where the second cell of the IOMMU specifier represents an SMR mask to
      combine with the ID in the first cell.  Care must be taken to ensure the
      set of matched IDs does not result in conflicts.

  interrupts:
    minItems: 1
    maxItems: 388   # 260 plus 128 contexts
    description: |
      Interrupt list, with the first #global-interrupts entries corresponding to
      the global interrupts and any following entries corresponding to context
      interrupts, specified in order of their indexing by the SMMU.

      For SMMUv2 implementations, there must be exactly one interrupt per
      context bank. In the case of a single, combined interrupt, it must be
      listed multiple times.

  dma-coherent:
    description: |
      Present if page table walks made by the SMMU are cache coherent with the
      CPU.

      NOTE: this only applies to the SMMU itself, not masters connected
      upstream of the SMMU.

  calxeda,smmu-secure-config-access:
    type: boolean
    description:
      Enable proper handling of buggy implementations that always use secure
      access to SMMU configuration registers. In this case non-secure aliases of
      secure registers have to be used during SMMU configuration.

  stream-match-mask:
    $ref: /schemas/types.yaml#/definitions/uint32
    description: |
      For SMMUs supporting stream matching and using #iommu-cells = <1>,
      specifies a mask of bits to ignore when matching stream IDs (e.g. this may
      be programmed into the SMRn.MASK field of every stream match register
      used). For cases where it is desirable to ignore some portion of every
      Stream ID (e.g. for certain MMU-500 configurations given globally unique
      input IDs). This property is not valid for SMMUs using stream indexing, or
      using stream matching with #iommu-cells = <2>, and may be ignored if
      present in such cases.

  clock-names:
    items:
      - const: bus
      - const: iface

  clocks:
    items:
      - description: bus clock required for downstream bus access and for the
          smmu ptw
      - description: interface clock required to access smmu's registers
          through the TCU's programming interface.

  power-domains:
    maxItems: 1

  nvidia,memory-controller:
    description: |
      A phandle to the memory controller on NVIDIA Tegra186 and later SoCs.
      The memory controller needs to be programmed with a mapping of memory
      client IDs to ARM SMMU stream IDs.

      If this property is absent, the mapping programmed by early firmware
      will be used and it is not guaranteed that IOMMU translations will be
      enabled for any given device.
    $ref: /schemas/types.yaml#/definitions/phandle

  qcom,fatal-asf:
    type: boolean
    description: |
      Enable BUG_ON for address size faults.  Some hardware requires special
      fixups to recover from address size faults.  Rather than applying the
      fixups just BUG since address size faults are due to a fundamental
      programming error from which we don't care about recovering anyways.

  qcom,skip-init:
    type: boolean
    description: |
      Disable resetting configuration for all context banks during device
      reset. This is useful for targets where some context banks are
      dedicated to other execution environments outside of Linux and those
      other EEs are programming their own stream match tables, SCTLR, etc.
      Without setting this option we will trample on their configuration.

  qcom,use-3-lvl-tables:
    type: boolean
    description: |
      Some hardware configurations may not be optimized for using a four
      level page table configuration. Set to use a three level page table
      instead.

  qcom,context-fault-retry:
    type: boolean
    description: |
      Retry iommu faults after a tlb invalidate, if stall-on-fault is enabled.

  qcom,actlr:
    $ref: '/schemas/types.yaml#/definitions/uint16-array'
    description: |
      An array of <sid mask actlr-setting>.
      Any sid X for which X&~mask==sid will be programmed with the
      given actlr-setting.

  qcom,disable-atos:
    type: boolean
    description: |
      Some hardware may not have full support for atos debugging in tandem
      with other features like power collapse.

  qcom,regulator-names:
    description: |
      List of strings to use with the (.*)-supply property.

  interconnects:
    items:
      - description: bus bandwidth request.

  qcom,active-only:
    type: boolean
    description: |
      Boolean property which denotes that interconnect votes should be
      maintained while the CPUSS is awake (active context). The absence of
      this property makes it so that interconnect votes will be maintained
      irrespective of the CPUSS' state (awake or asleep).

  qcom,num-context-banks-override:
    $ref: '/schemas/types.yaml#/definitions/uint32'
    description: |
      Optional integer. Should be set if the hypervisor virtualization is
      disabled for debugging purposes. When this is done, some context banks
      managed by hypervisor become visible to HLOS, but should not be accessed.
  qcom,num-smr-override:
    $ref: '/schemas/types.yaml#/definitions/uint32'
    description: |
      Optional integer. See qcom,num-context-banks-override.

  qcom,ignore-numpagendxb:
    type: boolean
    description: |
      Optional boolean. Indicates if numpagendxb should be ignored in
      determining the size of the global register address space and context
      bank address space. If qcom,ignore-numpagendxb, is supplied, we instead
      use the register space size supplied in the 'reg =' property to
      determine the locations of the various parts of the global and context
      bank address spaces.

  qcom,iommu-dma:
    description: |
      default
        Standard iommu translation behaviour. Calling iommu and DMA apis in
        atomic context is not allowed.
      bypass
        DMA APIs will use 1-to-1 translation between dma_addr and phys_addr.
      fastmap
        DMA APIs will run faster, but use several orders of magnitude more
        memory. Also allows using iommu and DMA apis in atomic context.
      atomic
        Allows using iommu and DMA apis in atomic context.
      disabled
        The iommu client is responsible for allocating an iommu domain.
    enum:
      - default
      - bypass
      - fastmap
      - atomic
      - disabled

  qcom,iommu-faults:
    $ref: '/schemas/types.yaml#/definitions/string-array'
    description: |
      default
        Any faults are treated as fatal errors.
      no-CFRE
        Iommu faults do not return an abort to the client hardware.
      non-fatal
        Iommu faults do not trigger a kernel panic.
      stall-disable
        Iommu faults do not stall the client while the fault interrupt is
        being handled.

  qcom,iommu-vmid:
    $ref: '/schemas/types.yaml#/definitions/uint32'
    description: |
      An identifier indicating the security state of the client.

  qcom,iommu-pagetable:
    $ref: '/schemas/types.yaml#/definitions/string-array'
    description: |
      default
        Pagetable coherency defaults to the coherency setting of the IOMMU
        device.
      coherent
        Pagetables are io-coherent.
      LLC
        Pagetables may be saved in the system cache. Should not be used if
        the IOMMU device is io-coherent.
      LLC_NWA
        Pagetables may be saved in the system cache is used, and
        write-allocate hint is disabled.

  qcom,iommu-earlymap:
    type: boolean
    description: |
      Support creating mappings in the page-table before Stage 1 translation
      is enabled.

  qcom,iommu-dma-addr-pool:
    $ref: '/schemas/types.yaml#/definitions/uint64-array'
    maxItems: 2
    description: |
      Indicates the range of addresses that the dma layer will use. Defaults
      to <0, SZ_4G> if not present.

  qcom,iommu-geometry:
    $ref: '/schemas/types.yaml#/definitions/uint64-array'
    maxItems: 2
    description: |
      Defaults to <0, SZ_4G> if not present. Indicates the available IOVA
      space when the qcom,iommu-dma property is set to "fastmap". The new
      space created will be a superset of the IOVA range which was created
      through the qcom,iommu-dma-addr-pool DT property.

  qcom,iommu-msi-size:
    $ref: '/schemas/types.yaml#/definitions/uint32'
    description: |
      Indicates the amount of space--in bytes--that must be reserved from
      the client's total IOVA space for mapping MSI registers when the
      qcom,iommu-dma property is set to "fastmap".

  qcom,iommu-defer-smr-config:
    type: boolean
    description: |
      Indicates that the SMRs for the client should not be programmed when the
      client device is attaching to the SMMU, but when the client's device
      driver requests it at a later point in time when the client is ready for
      DMA transfers.
  "#address-cells":
    const: 1
  "#size-cells":
    const: 1

patternProperties:
  ".*-supply$":
    description: |
      Phandle of the regulator that should be powered on during SMMU register
      access. (.*) is a string from the qcom,regulator-names property.
  ".*qtb@[0-9a-f]+":
    type: object
    properties:
      compatible:
        description: |
          The qcom,qsmmu-v500 device implements a number of register regions
          containing debug functionality. Each register region maps to a
          separate tbu from the arm mmu-500 implementation.
          "qcom,qtb500" can be used in conjunction with "qcom,qsmmuv500-tbu",
          as the QTB500 is an implementation of a TBU with different features
          enhancements than a regular TBU.
        items:
          - enum:
              - qcom,qtb500
              - qcom,qsmmuv500-tbu
      reg:
        minItems: 1
      qcom,stream-id-range:
        $ref: '/schemas/types.yaml#/definitions/uint32-array'
        description: |
          Pair of values describing the smallest supported stream-id
          and the size of the entire set.
      qcom,iova-width:
        $ref: '/schemas/types.yaml#/definitions/uint32'
        description: |
          The maximum number of bits that a TBU can support for IOVAs.
      qcom,opt-out-tbu-halting:
        type: boolean
        description: |
          Allow certain TBUs to opt-out from being halted for the ATOS
          operation to proceed. Halting certain TBUs would cause considerable
          impact to the system such as deadlocks on demand. Such TBUs can be
          opted out to be halted from software. Should always be set for pcie.
      interconnects:
        items:
          - description: bus bandwidth request.
      qcom,num-qtb-ports:
        $ref: '/schemas/types.yaml#/definitions/uint32'
        description: |
          Specifies the number of ports that a QTB has for incoming
          transactions.

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

additionalProperties: false

allOf:
  - if:
      properties:
        compatible:
          contains:
            enum:
              - nvidia,tegra186-smmu
              - nvidia,tegra194-smmu
              - nvidia,tegra234-smmu
    then:
      properties:
        reg:
          minItems: 1
          maxItems: 2

      # The reference to the memory controller is required to ensure that the
      # memory client to stream ID mapping can be done synchronously with the
      # IOMMU attachment.
      required:
        - nvidia,memory-controller
    else:
      properties:
        reg:
          maxItems: 1

examples:
  - |+
    /* SMMU with stream matching or stream indexing */
    smmu1: iommu@ba5e0000 {
            compatible = "arm,smmu-v1";
            reg = <0xba5e0000 0x10000>;
            #global-interrupts = <2>;
            interrupts = <0 32 4>,
                         <0 33 4>,
                         <0 34 4>, /* This is the first context interrupt */
                         <0 35 4>,
                         <0 36 4>,
                         <0 37 4>;
            #iommu-cells = <1>;
    };

    /* device with two stream IDs, 0 and 7 */
    master1 {
            iommus = <&smmu1 0>,
                     <&smmu1 7>;
    };


    /* SMMU with stream matching */
    smmu2: iommu@ba5f0000 {
            compatible = "arm,smmu-v1";
            reg = <0xba5f0000 0x10000>;
            #global-interrupts = <2>;
            interrupts = <0 38 4>,
                         <0 39 4>,
                         <0 40 4>, /* This is the first context interrupt */
                         <0 41 4>,
                         <0 42 4>,
                         <0 43 4>;
            #iommu-cells = <2>;
    };

    /* device with stream IDs 0 and 7 */
    master2 {
            iommus = <&smmu2 0 0>,
                     <&smmu2 7 0>;
    };

    /* device with stream IDs 1, 17, 33 and 49 */
    master3 {
            iommus = <&smmu2 1 0x30>;
    };


    /* ARM MMU-500 with 10-bit stream ID input configuration */
    smmu3: iommu@ba600000 {
            compatible = "arm,mmu-500", "arm,smmu-v2";
            reg = <0xba600000 0x10000>;
            #global-interrupts = <2>;
            interrupts = <0 44 4>,
                         <0 45 4>,
                         <0 46 4>, /* This is the first context interrupt */
                         <0 47 4>,
                         <0 48 4>,
                         <0 49 4>;
            #iommu-cells = <1>;
            /* always ignore appended 5-bit TBU number */
            stream-match-mask = <0x7c00>;
    };

    bus {
            /* bus whose child devices emit one unique 10-bit stream
               ID each, but may master through multiple SMMU TBUs */
            iommu-map = <0 &smmu3 0 0x400>;


    };

  - |+
    /* Qcom's arm,smmu-v2 implementation */
    #include <dt-bindings/interrupt-controller/arm-gic.h>
    #include <dt-bindings/interrupt-controller/irq.h>
    smmu4: iommu@d00000 {
      compatible = "qcom,msm8996-smmu-v2", "qcom,smmu-v2";
      reg = <0xd00000 0x10000>;

      #global-interrupts = <1>;
      interrupts = <GIC_SPI 73 IRQ_TYPE_LEVEL_HIGH>,
             <GIC_SPI 320 IRQ_TYPE_LEVEL_HIGH>,
             <GIC_SPI 321 IRQ_TYPE_LEVEL_HIGH>;
      #iommu-cells = <1>;
      power-domains = <&mmcc 0>;

      clocks = <&mmcc 123>,
        <&mmcc 124>;
      clock-names = "bus", "iface";
    };
  - |+
    iommu@d00000 {
      compatible = "qcom,qsmmu-v500";
      reg = <0xd00000 0x10000>;
      #global-interrupts = <1>;
      interrupts = <0 73 0>,
                   <0 73 0>;
      #iommu-cells = <1>;
      #address-cells = <1>;
      #size-cells = <1>;
      qtb@1000 {
        compatible = "qcom,qsmmuv500-tbu";
        reg = <0x1000 0x1000>;
        qcom,stream-id-range = <0x800 0x400>;
        qcom,iova-width = <36>;
        qcom,num-qtb-ports = <1>;
        interconnects = <&system_noc 0 &mc_virt 1>;
      };
    };
