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

title: Arm Memory System Resource Partitioning and Monitoring (MPAM)

description: |
  The Arm MPAM specification can be found here:

  https://developer.arm.com/documentation/ddi0598/latest

maintainers:
  - Rob Herring <robh@kernel.org>

properties:
  compatible:
    items:
      - const: arm,mpam-msc                   # Further details are discoverable
      - const: arm,mpam-memory-controller-msc

  reg:
    maxItems: 1
    description: A memory region containing registers as defined in the MPAM
      specification.

  interrupts:
    minItems: 1
    items:
      - description: error (optional)
      - description: overflow (optional, only for monitoring)

  interrupt-names:
    oneOf:
      - items:
          - enum: [ error, overflow ]
      - items:
          - const: error
          - const: overflow

  arm,not-ready-us:
    description: The maximum time in microseconds for monitoring data to be
      accurate after a settings change. For more information, see the
      Not-Ready (NRDY) bit description in the MPAM specification.

  numa-node-id: true # see NUMA binding

  '#address-cells':
    const: 1

  '#size-cells':
    const: 0

patternProperties:
  '^ris@[0-9a-f]$':
    type: object
    additionalProperties: false
    description: |
      RIS nodes for each RIS in an MSC. These nodes are required for each RIS
      implementing known MPAM controls

    properties:
      compatible:
        enum:
            # Bulk storage for cache
          - arm,mpam-cache
            # Memory bandwidth
          - arm,mpam-memory

      reg:
        minimum: 0
        maximum: 0xf

      cpus:
        $ref: '/schemas/types.yaml#/definitions/phandle-array'
        description:
          Phandle(s) to the CPU node(s) this RIS belongs to. By default, the parent
          device's affinity is used.

      arm,mpam-device:
        $ref: '/schemas/types.yaml#/definitions/phandle'
        description:
          By default, the MPAM enabled device associated with a RIS is the MSC's
          parent node. It is possible for each RIS to be associated with different
          devices in which case 'arm,mpam-device' should be used.

    required:
      - compatible
      - reg

required:
  - compatible
  - reg

dependencies:
  interrupts: [ interrupt-names ]

additionalProperties: false

examples:
  - |
    /*
    cpus {
        cpu@0 {
            next-level-cache = <&L2_0>;
        };
        cpu@100 {
            next-level-cache = <&L2_1>;
        };
    };
    */
    L2_0: cache-controller-0 {
        compatible = "cache";
        cache-level = <2>;
        cache-unified;
        next-level-cache = <&L3>;

    };

    L2_1: cache-controller-1 {
        compatible = "cache";
        cache-level = <2>;
        cache-unified;
        next-level-cache = <&L3>;

    };

    L3: cache-controller@30000000 {
        compatible = "arm,dsu-l3-cache", "cache";
        cache-level = <3>;
        cache-unified;

        ranges = <0x0 0x30000000 0x800000>;
        #address-cells = <1>;
        #size-cells = <1>;

        msc@10000 {
            compatible = "arm,mpam-msc";

            /* CPU affinity implied by parent cache node's  */
            reg = <0x10000 0x2000>;
            interrupts = <1>, <2>;
            interrupt-names = "error", "overflow";
            arm,not-ready-us = <1>;
        };
    };

    mem: memory-controller@20000 {
        compatible = "foo,a-memory-controller";
        reg = <0x20000 0x1000>;

        #address-cells = <1>;
        #size-cells = <1>;
        ranges;

        msc@21000 {
            compatible = "arm,mpam-memory-controller-msc", "arm,mpam-msc";
            reg = <0x21000 0x1000>;
            interrupts = <3>;
            interrupt-names = "error";
            arm,not-ready-us = <1>;
            numa-node-id = <1>;
        };
    };

    iommu@40000 {
        reg = <0x40000 0x1000>;

        ranges;
        #address-cells = <1>;
        #size-cells = <1>;

        msc@41000 {
            compatible = "arm,mpam-msc";
            reg = <0 0x1000>;
            interrupts = <5>, <6>;
            interrupt-names = "error", "overflow";
            arm,not-ready-us = <1>;

            #address-cells = <1>;
            #size-cells = <0>;

            ris@2 {
                compatible = "arm,mpam-cache";
                reg = <0>;
                // TODO: How to map to device(s)?
            };
        };
    };

    msc@80000 {
        compatible = "foo,a-standalone-msc";
        reg = <0x80000 0x1000>;

        clocks = <&clks 123>;

        ranges;
        #address-cells = <1>;
        #size-cells = <1>;

        msc@10000 {
            compatible = "arm,mpam-msc";

            reg = <0x10000 0x2000>;
            interrupts = <7>;
            interrupt-names = "overflow";
            arm,not-ready-us = <1>;

            #address-cells = <1>;
            #size-cells = <0>;

            ris@0 {
                compatible = "arm,mpam-cache";
                reg = <0>;
                arm,mpam-device = <&L2_0>;
            };

            ris@1 {
                compatible = "arm,mpam-memory";
                reg = <1>;
                arm,mpam-device = <&mem>;
            };
        };
    };

...