[PATCH v2 1/4] dt-bindings: arm: ras: Introduce bindings for ARM RAS error sources

[Umang Chheda]

ARMv8 and later processors implement the RAS (Reliability,
Availability and Serviceability) extensions, exposing hardware
error records through a standardised register interface.

Add Device Tree bindings to describe RAS error sources.

Signed-off-by: Umang Chheda <umang.chheda@xxxxxxxxxxxxxxxx>
---
 .../bindings/arm/arm,ras-error-source.yaml    | 330 ++++++++++++++++++
 include/dt-bindings/arm/arm-ras.h             |  11 +
 2 files changed, 341 insertions(+)
 create mode 100644 Documentation/devicetree/bindings/arm/arm,ras-error-source.yaml
 create mode 100644 include/dt-bindings/arm/arm-ras.h

diff --git a/Documentation/devicetree/bindings/arm/arm,ras-error-source.yaml b/Documentation/devicetree/bindings/arm/arm,ras-error-source.yaml
new file mode 100644
index 000000000000..add7063a1a62
--- /dev/null
+++ b/Documentation/devicetree/bindings/arm/arm,ras-error-source.yaml
@@ -0,0 +1,330 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/arm/arm,ras-error-source.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: ARM RAS error source
+
+maintainers:
+  - Umang Chheda <umang.chheda@xxxxxxxxxxxxxxxx>
+
+description: |
+  ARMv8 and later processors implement the Reliability, Availability and
+  Serviceability (RAS) extensions.  Hardware blocks that support RAS expose
+  one or more error records through a standardised register interface.  Each
+  error record captures information about a detected hardware error (cache
+  ECC fault, TLB parity error, interconnect error, etc.) and can optionally
+  signal the OS via an interrupt.
+
+  Each DT node described by this binding represents one RAS error source —
+  a hardware block that exposes a set of error records.  Error records are
+  accessed either through system registers (for processor-local resources
+  such as L1/L2 caches and TLBs) or through a memory-mapped register window
+  (for shared or off-core resources such as L3 caches, SMMUs and GICs).
+
+properties:
+  compatible:
+    description:
+      Identifies the class of hardware block this error source belongs to.
+      arm,ras-processor covers processor error sources (cache, TLB, etc.).
+      arm,ras-smmu covers SMMU error sources.
+      arm,ras-gic covers GIC error sources.
+    enum:
+      - arm,ras-processor
+      - arm,ras-smmu
+      - arm,ras-gic
+
+  reg:
+    description:
+      Register windows for this error source.  When absent the error records
+      are accessed through system registers (ERRSELR_EL1 + ERX*_EL1).
+      When present, the first range is the primary error-record window;
+      additional named ranges are identified by reg-names.
+    minItems: 1
+    maxItems: 4
+
+  reg-names:
+    description:
+      Names for the optional additional register windows beyond the primary
+      error-record window.  err-group is the error group status register
+      window (ERRGSR).  fault-inject is the fault injection register window
+      (ERXPFG*).  irq-config is the interrupt routing configuration window.
+    minItems: 1
+    maxItems: 3
+    items:
+      enum:
+        - err-group
+        - fault-inject
+        - irq-config
+
+  interrupts:
+    description:
+      Interrupts signalled by this error source.  The first interrupt is the
+      Fault Handling Interrupt (FHI), fired when a corrected error counter
+      overflows or a deferred error is detected.  The optional second
+      interrupt is the Error Recovery Interrupt (ERI), fired when an
+      uncorrected recoverable error is detected.
+    minItems: 1
+    maxItems: 2
+
+  interrupt-names:
+    description:
+      Names identifying the interrupts.  "fhi" is the Fault Handling
+      Interrupt; "eri" is the optional Error Recovery Interrupt.
+    minItems: 1
+    maxItems: 2
+    items:
+      enum:
+        - fhi
+        - eri
+
+  arm,group-format:
+    description:
+      Page granularity of the memory-mapped error record group register
+      window.  Determines the ioremap size and the number of error group
+      status registers (ERRGSR) available.  Required when reg is present.
+      Use the ARM_RAS_GROUP_* constants from <dt-bindings/arm/arm-ras.h>.
+      0 (ARM_RAS_GROUP_4K) is a 4 KiB window with 1 ERRGSR supporting up
+      to 64 records.  1 (ARM_RAS_GROUP_16K) is 16 KiB with 4 ERRGSRs and
+      up to 256 records.  2 (ARM_RAS_GROUP_64K) is 64 KiB with 14 ERRGSRs
+      and up to 896 records.
+    $ref: /schemas/types.yaml#/definitions/uint32
+    enum: [0, 1, 2]
+
+  arm,num-records:
+    description:
+      Total number of error records in this error source, including both
+      implemented and unimplemented slots.
+    $ref: /schemas/types.yaml#/definitions/uint32
+    minimum: 1
+
+  arm,record-impl:
+    description:
+      Bitmap of implemented error records.  Bit N set to 1 means error
+      record N is present and active in this error source.  Bit N set to 0
+      means record N is not implemented and must be skipped.  The array
+      length must equal the number of ERRGSRs implied by arm,group-format
+      (1 element for 4K, 4 for 16K, 14 for 64K).  For system-register
+      nodes (no reg property) a single u64 element is used.
+    $ref: /schemas/types.yaml#/definitions/uint64-array
+    minItems: 1
+    maxItems: 14
+
+  arm,status-reporting:
+    description:
+      Bitmap indicating which implemented error records must be polled
+      directly by the OS.  Bit N set to 1 means record N does not report
+      through the ERRGSR and must be polled by reading its ERX_STATUS
+      register directly in the interrupt handler.  Bit N set to 0 means
+      record N reports its status through the ERRGSR and will be discovered
+      via the ERRGSR scan path.  For system-register nodes (no reg property)
+      there is no ERRGSR, so every implemented record must be polled
+      directly; arm,status-reporting must equal arm,record-impl for all
+      system-register nodes.  Array length as for arm,record-impl.
+    $ref: /schemas/types.yaml#/definitions/uint64-array
+    minItems: 1
+    maxItems: 14
+
+  arm,addressing-mode:
+    description:
+      Bitmap indicating the type of address reported in the error address
+      register (ERX_ADDR) for each error record.  Bit N set to 0 means
+      record N reports a System Physical Address (SPA) that the OS can use
+      directly.  Bit N set to 1 means record N reports a node-specific
+      Logical Address (LA) that requires platform-specific translation to
+      obtain a SPA.  Array length as for arm,record-impl.
+    $ref: /schemas/types.yaml#/definitions/uint64-array
+    minItems: 1
+    maxItems: 14
+
+  # Processor error source properties (arm,ras-processor only)
+
+  cache:
+    description:
+      Phandle to the cache node (L1, L2, or L3) that this processor error
+      source monitors.  The referenced node must have compatible = "cache"
+      and a cache-level property identifying the level in the hierarchy.
+    $ref: /schemas/types.yaml#/definitions/phandle
+
+  # SMMU error source properties (arm,ras-smmu only)
+
+  iommus:
+    description:
+      Phandle to the SMMU node that this error source monitors.
+    maxItems: 1
+
+  # GIC error source properties (arm,ras-gic only)
+
+  arm,gic-ref:
+    description:
+      Phandle to the GIC node that this error source monitors.
+    $ref: /schemas/types.yaml#/definitions/phandle
+
+required:
+  - compatible
+  - arm,num-records
+  - arm,record-impl
+  - arm,status-reporting
+
+allOf:
+  - if:
+      required:
+        - reg
+    then:
+      required:
+        - arm,group-format
+
+  - if:
+      properties:
+        compatible:
+          contains:
+            const: arm,ras-processor
+    then:
+      required:
+        - cache
+      properties:
+        cache: {}
+    else:
+      properties:
+        cache: false
+
+  - if:
+      properties:
+        compatible:
+          contains:
+            const: arm,ras-smmu
+    then:
+      required:
+        - iommus
+      properties:
+        iommus: {}
+    else:
+      properties:
+        iommus: false
+
+  - if:
+      properties:
+        compatible:
+          contains:
+            const: arm,ras-gic
+    then:
+      required:
+        - arm,gic-ref
+      properties:
+        arm,gic-ref: {}
+    else:
+      properties:
+        arm,gic-ref: false
+
+unevaluatedProperties: false
+
+examples:
+  - |
+    #include <dt-bindings/interrupt-controller/arm-gic.h>
+    #include <dt-bindings/arm/arm-ras.h>
+
+    / {
+        compatible = "qcom,sa8775p-ride", "qcom,sa8775p";
+        model = "Qualcomm Technologies, Inc. SA8775P RAS example";
+        #address-cells = <2>;
+        #size-cells = <2>;
+        interrupt-parent = <&intc>;
+
+        intc: interrupt-controller@17100000 {
+            compatible = "arm,gic-v3";
+            reg = <0x0 0x17100000 0x0 0x10000>,
+                  <0x0 0x17180000 0x0 0x100000>;
+            interrupt-controller;
+            #interrupt-cells = <3>;
+            #address-cells = <2>;
+            #size-cells = <2>;
+        };
+
+        cpus {
+            #address-cells = <2>;
+            #size-cells = <0>;
+
+            cpu0: cpu@0 {
+                device_type = "cpu";
+                compatible = "arm,armv8";
+                reg = <0x0 0x0>;
+                next-level-cache = <&l2_0>;
+
+                l2_0: l2-cache {
+                    compatible = "cache";
+                    cache-level = <2>;
+                    cache-unified;
+                    next-level-cache = <&l3_0>;
+
+                    l3_0: l3-cache {
+                        compatible = "cache";
+                        cache-level = <3>;
+                        cache-unified;
+                    };
+                };
+            };
+        };
+
+        /*
+         * Per-PE L1/L2 cache RAS error source.  System-register access,
+         * per-CPU PPI.  Record 0 is implemented (arm,record-impl bit 0
+         * set).  arm,status-reporting equals arm,record-impl because
+         * system-register nodes have no ERRGSR; record 0 must be polled.
+         */
+        ras-l1l2-0 {
+            compatible = "arm,ras-processor";
+            arm,num-records = <1>;
+            arm,record-impl = /bits/ 64 <0x1>;
+            arm,status-reporting = /bits/ 64 <0x1>;
+            cache = <&l2_0>;
+            interrupts = <GIC_PPI 0 IRQ_TYPE_LEVEL_HIGH>;
+            interrupt-names = "fhi";
+        };
+
+        ras-l3-cluster0 {
+            compatible = "arm,ras-processor";
+            arm,num-records = <2>;
+            arm,record-impl = /bits/ 64 <0x2>;
+            arm,status-reporting = /bits/ 64 <0x2>;
+            cache = <&l3_0>;
+            interrupts = <GIC_SPI 36 IRQ_TYPE_LEVEL_HIGH>;
+            interrupt-names = "fhi";
+        };
+    };
+
+  - |
+    #include <dt-bindings/interrupt-controller/arm-gic.h>
+    #include <dt-bindings/arm/arm-ras.h>
+
+    / {
+        compatible = "qcom,sa8775p-ride", "qcom,sa8775p";
+        model = "Qualcomm Technologies, Inc. SA8775P RAS example";
+        #address-cells = <2>;
+        #size-cells = <2>;
+        interrupt-parent = <&gic>;
+
+        /*
+         * GICv3 interrupt controller with RAS support.
+         */
+        gic: interrupt-controller@17b00000 {
+            compatible = "arm,gic-v3";
+            reg = <0x0 0x17b00000 0x0 0x10000>,
+                  <0x0 0x17b60000 0x0 0x100000>;
+            interrupt-controller;
+            #interrupt-cells = <3>;
+        };
+
+        ras-gic-dist@17a00000 {
+            compatible = "arm,ras-gic";
+            reg = <0x0 0x17a00000 0x0 0x10000>;
+            reg-names = "err-group";
+            arm,group-format = <ARM_RAS_GROUP_4K>;
+            arm,num-records = <1>;
+            arm,record-impl = /bits/ 64 <0x1>;
+            arm,status-reporting = /bits/ 64 <0x0>;
+            arm,gic-ref = <&gic>;
+            interrupts = <GIC_SPI 200 IRQ_TYPE_LEVEL_HIGH>;
+            interrupt-names = "fhi";
+        };
+    };
diff --git a/include/dt-bindings/arm/arm-ras.h b/include/dt-bindings/arm/arm-ras.h
new file mode 100644
index 000000000000..c2f4e1f8243e
--- /dev/null
+++ b/include/dt-bindings/arm/arm-ras.h
@@ -0,0 +1,11 @@
+/* SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) */
+
+#ifndef _DT_BINDINGS_ARM_RAS_H
+#define _DT_BINDINGS_ARM_RAS_H
+
+/* arm,group-format - error record group register window page size */
+#define ARM_RAS_GROUP_4K		0	/* 4 KiB,  1 ERRGSR  */
+#define ARM_RAS_GROUP_16K		1	/* 16 KiB, 4 ERRGSRs */
+#define ARM_RAS_GROUP_64K		2	/* 64 KiB, 14 ERRGSRs */
+
+#endif /* _DT_BINDINGS_ARM_RAS_H */
--
2.34.1