Documentation/devicetree/bindings/arm/arm,coresight-etm.yaml

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

title: Arm CoreSight Embedded Trace MacroCell

maintainers:
  - Mathieu Poirier <mathieu.poirier@linaro.org>
  - Mike Leach <mike.leach@linaro.org>
  - Leo Yan <leo.yan@linaro.org>
  - Suzuki K Poulose <suzuki.poulose@arm.com>

description: |
  CoreSight components are compliant with the ARM CoreSight architecture
  specification and can be connected in various topologies to suit a particular
  SoCs tracing needs. These trace components can generally be classified as
  sinks, links and sources. Trace data produced by one or more sources flows
  through the intermediate links connecting the source to the currently selected
  sink.

  The Embedded Trace Macrocell (ETM) is a real-time trace module providing
  instruction and data tracing of a processor.

select:
  properties:
    compatible:
      contains:
        enum:
          - arm,coresight-etm3x
          - arm,coresight-etm4x
          - arm,coresight-etm4x-sysreg
  required:
    - compatible

allOf:
  - if:
      not:
        properties:
          compatible:
            contains:
              const: arm,coresight-etm4x-sysreg
    then:
      $ref: /schemas/arm/primecell.yaml#
      required:
        - reg

properties:
  compatible:
    oneOf:
      - description:
          Embedded Trace Macrocell with memory mapped access.
        items:
          - enum:
              - arm,coresight-etm3x
              - arm,coresight-etm4x
          - const: arm,primecell
      - description:
          Embedded Trace Macrocell (version 4.x), with system register access only
        const: arm,coresight-etm4x-sysreg

  reg:
    maxItems: 1

  clocks:
    minItems: 1
    maxItems: 2

  clock-names:
    minItems: 1
    items:
      - const: apb_pclk
      - const: atclk

  arm,coresight-loses-context-with-cpu:
    type: boolean
    description:
      Indicates that the hardware will lose register context on CPU power down
      (e.g. CPUIdle). An example of where this may be needed are systems which
      contain a coresight component and CPU in the same power domain. When the
      CPU powers down the coresight component also powers down and loses its
      context.

  arm,cp14:
    type: boolean
    description:
      Must be present if the system accesses ETM/PTM management registers via
      co-processor 14.

  qcom,skip-power-up:
    type: boolean
    description:
      Indicates that an implementation can skip powering up the trace unit.
      TRCPDCR.PU does not have to be set on Qualcomm Technologies Inc. systems
      since ETMs are in the same power domain as their CPU cores. This property
      is required to identify such systems with hardware errata where the CPU
      watchdog counter is stopped when TRCPDCR.PU is set.

  cpu:
    description:
      phandle to the cpu this ETM is bound to.
    $ref: /schemas/types.yaml#/definitions/phandle

  out-ports:
    $ref: /schemas/graph.yaml#/properties/ports
    additionalProperties: false

    properties:
      port:
        description: Output connection from the ETM to CoreSight Trace bus.
        $ref: /schemas/graph.yaml#/properties/port

required:
  - compatible
  - clocks
  - clock-names
  - cpu
  - out-ports

unevaluatedProperties: false

examples:
  - |
    ptm@2201c000 {
        compatible = "arm,coresight-etm3x", "arm,primecell";
        reg = <0x2201c000 0x1000>;

        cpu = <&cpu0>;
        clocks = <&oscclk6a>;
        clock-names = "apb_pclk";
        out-ports {
            port {
                ptm0_out_port: endpoint {
                    remote-endpoint = <&funnel_in_port0>;
                };
            };
        };
    };

    ptm@2201d000 {
        compatible = "arm,coresight-etm3x", "arm,primecell";
        reg = <0x2201d000 0x1000>;

        cpu = <&cpu1>;
        clocks = <&oscclk6a>;
        clock-names = "apb_pclk";
        out-ports {
            port {
                ptm1_out_port: endpoint {
                    remote-endpoint = <&funnel_in_port1>;
                };
            };
        };
    };
...