dt-bindings: arm: Add MPAM MSC binding

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

            };

        };

    };

...