Documentation/devicetree/bindings/net/qcom,ipa.yaml

# SPDX-License-Identifier: GPL-2.0 OR BSD-2-Clause
%YAML 1.2
---
$id: http://devicetree.org/schemas/net/qcom,ipa.yaml#
$schema: http://devicetree.org/meta-schemas/core.yaml#

title: Qualcomm IP Accelerator (IPA)

maintainers:
  - Alex Elder <elder@kernel.org>

description:
  This binding describes the Qualcomm IPA.  The IPA is capable of offloading
  certain network processing tasks (e.g. filtering, routing, and NAT) from
  the main processor.

  The IPA sits between multiple independent "execution environments,"
  including the Application Processor (AP) and the modem.  The IPA presents
  a Generic Software Interface (GSI) to each execution environment.
  The GSI is an integral part of the IPA, but it is logically isolated
  and has a distinct interrupt and a separately-defined address space.

  See also soc/qcom/qcom,smp2p.txt and interconnect/interconnect.txt.  See
  iommu/iommu.txt and iommu/arm,smmu.yaml for more information about SMMU
  bindings.


  - |
    --------             ---------
    |      |             |       |
    |  AP  +<---.   .----+ Modem |
    |      +--. |   | .->+       |
    |      |  | |   | |  |       |
    --------  | |   | |  ---------
              v |   v |
            --+-+---+-+--
            |    GSI    |
            |-----------|
            |           |
            |    IPA    |
            |           |
            -------------

properties:
  compatible:
    enum:
      - qcom,msm8998-ipa
      - qcom,sc7180-ipa
      - qcom,sc7280-ipa
      - qcom,sdm845-ipa
      - qcom,sdx55-ipa
      - qcom,sm8350-ipa

  reg:
    items:
      - description: IPA registers
      - description: IPA shared memory
      - description: GSI registers

  reg-names:
    items:
      - const: ipa-reg
      - const: ipa-shared
      - const: gsi

  iommus:
    minItems: 1
    maxItems: 2

  clocks:
    maxItems: 1

  clock-names:
    const: core

  interrupts:
    items:
      - description: IPA interrupt (hardware IRQ)
      - description: GSI interrupt (hardware IRQ)
      - description: Modem clock query interrupt (smp2p interrupt)
      - description: Modem setup ready interrupt (smp2p interrupt)

  interrupt-names:
    items:
      - const: ipa
      - const: gsi
      - const: ipa-clock-query
      - const: ipa-setup-ready

  interconnects:
    oneOf:
      - items:
          - description: Path leading to system memory
          - description: Path between the AP and IPA config space
      - items:
          - description: Path leading to system memory
          - description: Path leading to internal memory
          - description: Path between the AP and IPA config space

  interconnect-names:
    oneOf:
      - items:
          - const: memory
          - const: config
      - items:
          - const: memory
          - const: imem
          - const: config

  qcom,smem-states:
    $ref: /schemas/types.yaml#/definitions/phandle-array
    description: State bits used in by the AP to signal the modem.
    items:
      - description: Whether the "ipa-clock-enabled" state bit is valid
      - description: Whether the IPA clock is enabled (if valid)

  qcom,smem-state-names:
    description: The names of the state bits used for SMP2P output
    items:
      - const: ipa-clock-enabled-valid
      - const: ipa-clock-enabled

  modem-init:
    type: boolean
    description:
      If present, it indicates that the modem is responsible for
      performing early IPA initialization, including loading and
      validating firwmare used by the GSI.

  memory-region:
    maxItems: 1
    description:
      If present, a phandle for a reserved memory area that holds
      the firmware passed to Trust Zone for authentication.  Required
      when Trust Zone (not the modem) performs early initialization.

  firmware-name:
    $ref: /schemas/types.yaml#/definitions/string
    description:
      If present, name (or relative path) of the file within the
      firmware search path containing the firmware image used when
      initializing IPA hardware.  Optional, and only used when
      Trust Zone performs early initialization.

required:
  - compatible
  - iommus
  - reg
  - clocks
  - interrupts
  - interconnects
  - qcom,smem-states

# Either modem-init is present, or memory-region must be present.
oneOf:
  - required:
      - modem-init
  - required:
      - memory-region

# If memory-region is present, firmware-name may optionally be present.
# But if modem-init is present, firmware-name must not be present.
if:
  required:
    - modem-init
then:
  not:
    required:
      - firmware-name

additionalProperties: false

examples:
  - |
        #include <dt-bindings/interrupt-controller/arm-gic.h>
        #include <dt-bindings/clock/qcom,rpmh.h>
        #include <dt-bindings/interconnect/qcom,sdm845.h>

        smp2p-mpss {
                compatible = "qcom,smp2p";
                ipa_smp2p_out: ipa-ap-to-modem {
                        qcom,entry-name = "ipa";
                        #qcom,smem-state-cells = <1>;
                };

                ipa_smp2p_in: ipa-modem-to-ap {
                        qcom,entry-name = "ipa";
                        interrupt-controller;
                        #interrupt-cells = <2>;
                };
        };
        ipa@1e40000 {
                compatible = "qcom,sdm845-ipa";

                modem-init;

                iommus = <&apps_smmu 0x720 0x3>;
                reg = <0x1e40000 0x7000>,
                        <0x1e47000 0x2000>,
                        <0x1e04000 0x2c000>;
                reg-names = "ipa-reg",
                            "ipa-shared",
                            "gsi";

                interrupts-extended = <&intc GIC_SPI 311 IRQ_TYPE_EDGE_RISING>,
                                      <&intc GIC_SPI 432 IRQ_TYPE_LEVEL_HIGH>,
                                      <&ipa_smp2p_in 0 IRQ_TYPE_EDGE_RISING>,
                                      <&ipa_smp2p_in 1 IRQ_TYPE_EDGE_RISING>;
                interrupt-names = "ipa",
                                  "gsi",
                                  "ipa-clock-query",
                                  "ipa-setup-ready";

                clocks = <&rpmhcc RPMH_IPA_CLK>;
                clock-names = "core";

                interconnects =
                        <&rsc_hlos MASTER_IPA &rsc_hlos SLAVE_EBI1>,
                        <&rsc_hlos MASTER_IPA &rsc_hlos SLAVE_IMEM>,
                        <&rsc_hlos MASTER_APPSS_PROC &rsc_hlos SLAVE_IPA_CFG>;
                interconnect-names = "memory",
                                     "imem",
                                     "config";

                qcom,smem-states = <&ipa_smp2p_out 0>,
                                   <&ipa_smp2p_out 1>;
                qcom,smem-state-names = "ipa-clock-enabled-valid",
                                        "ipa-clock-enabled";
        };