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

[Krzysztof Kozlowski]

On Mon, Jul 20, 2026 at 01:49:51PM +0530, Umang Chheda wrote:
> 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>

A nit, subject: drop second/last, redundant "bindings for". The
"dt-bindings" prefix is already stating that these are bindings.
See also:
https://elixir.bootlin.com/linux/v7.1-rc7/source/Documentation/devicetree/bindings/submitting-patches.rst#L23

> ---
>  .../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

Filename should resemble compatible, so "arm,ras.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: {}


What is with this syntax. There is no such style, drop.


> +    else:
> +      properties:
> +        iommus: false
> +
> +  - if:
> +      properties:
> +        compatible:
> +          contains:
> +            const: arm,ras-gic
> +    then:
> +      required:
> +        - arm,gic-ref
> +      properties:
> +        arm,gic-ref: {}

Drop. This is not an object, but phandle.

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

Drop, irrelevant.

> +
> +        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;
> +                    };
> +                };
> +            };
> +        };

Drop all the nodes above, irrelevant.

> +
> +        /*
> +         * 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 {

Node names should be generic. See also an explanation and list of
examples (not exhaustive) in DT specification:
https://devicetree-specification.readthedocs.io/en/latest/chapter2-devicetree-basics.html#generic-names-recommendation
If you cannot find a name matching your device, please check in kernel
sources for similar cases or you can grow the spec (via pull request to
DT spec repo).

Choose some generic name, but l1l2 does not sound like one.

> +            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";

I had impression we agreed all this is part of actual CPU/GIC/cache node
or its subnode.

Keeping it separate does not feel right, if cache is the source of error reporting.

> +        };
> +
> +        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

Filename must match binding or compatible.

> @@ -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

Best regards,
Krzysztof