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

title: Qualcomm Technologies, Inc. (QTI) Memlat Driver

maintainers:
  - avajid@quicinc.com <quic_avajid@quicinc.com>
  - gurbaror@quicinc.com <quic_gurbaror@quicinc.com>

description: |
  The Qualcomm Technologies, Inc. (QTI) Memlat Driver monitors CPU performance
  counters to identify memory latency bound workloads and votes for DCVS HW
  (memory) frequencies based on the workload characteristics. This driver is a
  refactor of the arm-memlat-mon driver that was previously developed. An
  instance of qcom-memlat must be described in three levels of device nodes.
  The first level describes the parent node. The second level describes a memlat
  group which manages voting for a particular DCVS HW device (e.g. DDR). The
  third level describes a memlat monitor ("mon") which comprises of a list of
  CPUs whose configured performance counters are used to vote for a DCVS HW
  frequency for the memlat group that it is part of.

properties:
  compatible:
      const: qcom,memlat

  qcom,cyc-ev:
    $ref: /schemas/types.yaml#/definitions/uint32
    description:
      The cycle count event that this driver monitors. Defaults to 0x11 if not
      specified.

  qcom,inst-ev:
    $ref: /schemas/types.yaml#/definitions/uint32
    description:
      The instruction count event that this driver monitors. Defaults to 0x08
      if not specified.

  qcom,stall-ev:
    $ref: /schemas/types.yaml#/definitions/uint32
    description:
      The stall cycle event that this driver monitors. Assumes 100% stall if
      not specified.

  child-node:
    description: Second level nodes for memlat groups
    type: object
    properties:
      compatible:
          const: qcom,memlat-grp

      qcom,target-dev:
        $ref: /schemas/types.yaml#/definitions/phandle
        description:
          A phandle to the QTI DCVS HW device node that this
          node will be using for voting.

      qcom,miss-ev:
        $ref: /schemas/types.yaml#/definitions/uint32
        description:
          The cache miss event that this memlat group uses to measure memory
          latency sensitivity to this DCVS HW.

      qcom,sampling-path:
        $ref: /schemas/types.yaml#/definitions/phandle
        description:
          A phandle to the QTI DCVS PATH device node that the memlat sampling
          algorithm will use for voting. This property or the
          qcom,threadlat-path property is required.

      qcom,threadlat-path:
        $ref: /schemas/types.yaml#/definitions/phandle
        description:
          A phandle to the QTI DCVS PATH device node that the threadlat
          algorithm will use for voting. This property or the
          qcom,sampling-path property is required.

      qcom,access-ev:
        $ref: /schemas/types.yaml#/definitions/uint32
        description:
          The cache access event that this driver optionally monitors to
          calculate writeback percentage.

      qcom,wb-ev:
        $ref: /schemas/types.yaml#/definitions/uint32
        description:
          The cache writeback event that this driver optionally monitors to
          calculate writeback percentage.

    child-node:
      description: Third level nodes for memlat mons
      type: object
      properties:
        compatible:
            items: qcom,memlat-mon

        qcom,cpulist:
          $ref: /schemas/types.yaml#/definitions/phandle-array
          description: List of CPU phandles to be monitored by this mon.

        qcom,cpufreq-memfreq-tbl:
          $ref: /schemas/types.yaml#/definitions/uint32-array
          description:
            A mapping table of cpu frequency to a memory (i.e. DCVS HW)
            frequency (both in units of kHz). A phandle that contains this
            property may be provided instead (to share tables across nodes).
            A phandle must be used in conjunction with the optional
            "qcom,ddr-type" property to support multiple DDR types.

        qcom,sampling-enabled:
          type: boolean
          description:
            Used to determine if this mon should be used by the memlat sampling
            algorithm. One of the qcom,sampling-enabled, qcom,threadlat-enabled,
            or qcom,cpucp-enabled properties is required to be enabled.

        qcom,threadlat-enabled:
          type: boolean
          description:
            Used to determine if this mon should be used by the threadlat
            algorithm. One of the qcom,sampling-enabled, qcom,threadlat-enabled,
            or qcom,cpucp-enabled properties is required to be enabled.

        qcom,cpucp-enabled:
          type: boolean
          description:
            Used to determine if this mon should be used by the cpucp
            algorithm. One of the qcom,sampling-enabled, qcom,threadlat-enabled,
            or qcom,cpucp-enabled properties is required to be enabled.

        qcom,compute-mon:
          type: boolean
          description:
            Used to configure mon as a "compute" mon which means it monitors
            compute bound workloads.

        qcom,ddr-type:
          $ref: /schemas/types.yaml#/definitions/uint32
          description:
            Specifies the DDR type supported by the corresponding
            "qcom,cpufreq-memfreq-tbl" property.

      required:
        - compatible
        - qcom,cpulist
        - qcom,cpufreq-memfreq-tbl
        - qcom,sampling-enabled

    required:
      - compatible
      - qcom,target-dev
      - qcom,miss-ev
      - qcom,sampling-path

required:
  - compatible

examples:
  - |
    qcom_dcvs: qcom,dcvs {
      compatible = "qcom,dcvs";

      qcom_ddr_dcvs_hw: ddr {
        compatible = "qcom,dcvs-hw";

        ddr_dcvs_fp: fp {
          compatible = "qcom,dcvs-path";
        };
      };
    };

    silver_ddr_tbl: qcom,silver-ddr-tbl {
      ddr4-tbl {
        qcom,ddr-type = <7>;
        qcom,cpufreq-memfreq-tbl =
          <  300000  200000 >,
          <  691200  451000 >,
          < 1190400  547000 >,
          < 1459200  768000 >,
          < 1900800 1017000 >;
      };
      ddr5-tbl {
        qcom,ddr-type = <8>;
        qcom,cpufreq-memfreq-tbl =
          <  300000  200000 >,
          <  691200  451000 >,
          < 1190400  547000 >,
          < 1459200  768000 >,
          < 1900800 1555000 >;
      }
    };

    qcom_memlat: qcom,memlat {
      compatible = "qcom,memlat";

      memlat_ddr: ddr {
        compatible = "qcom,memlat-grp";
        qcom,target-dev = <&qcom_ddr_dcvs_hw>;
        qcom,sampling-path = <&ddr_dcvs_fp>;
        qcom,miss-ev = <0x1000>;
        silver_ddr_lat: silver {
          compatible = "qcom,memlat-mon";
          qcom,cpulist = <&CPU0 &CPU1 &CPU2 &CPU3>;
          qcom,cpufreq-memfreq-tbl = <&silver_ddr_tbl>;
          qcom,sampling-enabled;
        };
      };
    };