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

   1 # SPDX-License-Identifier: GPL-2.0-only or BSD-2-Clause
   2 # Copyright 2019 Linaro Ltd.
   3 %YAML 1.2
   4 ---
   5 $id: http://devicetree.org/schemas/arm/arm,coresight-cti.yaml#
   6 $schema: http://devicetree.org/meta-schemas/core.yaml#
   7
   8 title: ARM Coresight Cross Trigger Interface (CTI) device.
   9
  10 description: |
  11   The CoreSight Embedded Cross Trigger (ECT) consists of CTI devices connected
  12   to one or more CoreSight components and/or a CPU, with CTIs interconnected in
  13   a star topology via the Cross Trigger Matrix (CTM), which is not programmable.
  14   The ECT components are not part of the trace generation data path and are thus
  15   not part of the CoreSight graph.
  16
  17   The CTI component properties define the connections between the individual
  18   CTI and the components it is directly connected to, consisting of input and
  19   output hardware trigger signals. CTIs can have a maximum number of input and
  20   output hardware trigger signals (8 each for v1 CTI, 32 each for v2 CTI). The
  21   number is defined at design time, the maximum of each defined in the DEVID
  22   register.
  23
  24   CTIs are interconnected in a star topology via the CTM, using a number of
  25   programmable channels, usually 4, but again implementation defined and
  26   described in the DEVID register. The star topology is not required to be
  27   described in the bindings as the actual connections are software
  28   programmable.
  29
  30   In general the connections between CTI and components via the trigger signals
  31   are implementation defined, except when the CTI is connected to an ARM v8
  32   architecture core and optional ETM.
  33
  34   In this case the ARM v8 architecture defines the required signal connections
  35   between CTI and the CPU core and ETM if present. In the case of a v8
  36   architecturally connected CTI an additional compatible string is used to
  37   indicate this feature (arm,coresight-cti-v8-arch).
  38
  39   When CTI trigger connection information is unavailable then a minimal driver
  40   binding can be declared with no explicit trigger signals. This will result
  41   the driver detecting the maximum available triggers and channels from the
  42   DEVID register and make them all available for use as a single default
  43   connection. Any user / client application will require additional information
  44   on the connections between the CTI and other components for correct operation.
  45   This information might be found by enabling the Integration Test registers in
  46   the driver (set CONFIG_CORESIGHT_CTI_INTEGRATION_TEST in Kernel
  47   configuration). These registers may be used to explore the trigger connections
  48   between CTI and other CoreSight components.
  49
  50   Certain triggers between CoreSight devices and the CTI have specific types
  51   and usages. These can be defined along with the signal indexes with the
  52   constants defined in <dt-bindings/arm/coresight-cti-dt.h>
  53
  54   For example a CTI connected to a core will usually have a DBGREQ signal. This
  55   is defined in the binding as type PE_EDBGREQ. These types will appear in an
  56   optional array alongside the signal indexes. Omitting types will default all
  57   signals to GEN_IO.
  58
  59   Note that some hardware trigger signals can be connected to non-CoreSight
  60   components (e.g. UART etc) depending on hardware implementation.
  61
  62 maintainers:
  63   - Mike Leach <mike.leach@linaro.org>
  64
  65 allOf:
  66   - $ref: /schemas/arm/primecell.yaml#
  67
  68 # Need a custom select here or 'arm,primecell' will match on lots of nodes
  69 select:
  70   properties:
  71     compatible:
  72       contains:
  73         enum:
  74           - arm,coresight-cti
  75   required:
  76     - compatible
  77
  78 properties:
  79   $nodename:
  80     pattern: "^cti(@[0-9a-f]+)$"
  81   compatible:
  82     oneOf:
  83       - items:
  84           - const: arm,coresight-cti
  85           - const: arm,primecell
  86       - items:
  87           - const: arm,coresight-cti-v8-arch
  88           - const: arm,coresight-cti
  89           - const: arm,primecell
  90
  91   reg:
  92     maxItems: 1
  93
  94   cpu:
  95     $ref: /schemas/types.yaml#/definitions/phandle
  96     description:
  97       Handle to cpu this device is associated with. This must appear in the
  98       base cti node if compatible string arm,coresight-cti-v8-arch is used,
  99       or may appear in a trig-conns child node when appropriate.
 100
 101   power-domains:
 102     maxItems: 1
 103
 104   arm,cti-ctm-id:
 105     $ref: /schemas/types.yaml#/definitions/uint32
 106     description:
 107       Defines the CTM this CTI is connected to, in large systems with multiple
 108       separate CTI/CTM nets. Typically multi-socket systems where the CTM is
 109       propagated between sockets.
 110
 111   arm,cs-dev-assoc:
 112     $ref: /schemas/types.yaml#/definitions/phandle
 113     description:
 114       defines a phandle reference to an associated CoreSight trace device.
 115       When the associated trace device is enabled, then the respective CTI
 116       will be enabled. Use in a trig-conns node, or in CTI base node when
 117       compatible string arm,coresight-cti-v8-arch used. If the associated
 118       device has not been registered then the node name will be stored as
 119       the connection name for later resolution. If the associated device is
 120       not a CoreSight device or not registered then the node name will remain
 121       the connection name and automatic enabling will not occur.
 122
 123   # size cells and address cells required if trig-conns node present.
 124   "#size-cells":
 125     const: 0
 126
 127   "#address-cells":
 128     const: 1
 129
 130 patternProperties:
 131   '^trig-conns@([0-9]+)$':
 132     type: object
 133     description:
 134       A trigger connections child node which describes the trigger signals
 135       between this CTI and another hardware device. This device may be a CPU,
 136       CoreSight device, any other hardware device or simple external IO lines.
 137       The connection may have both input and output triggers, or only one or the
 138       other.
 139
 140     properties:
 141       reg:
 142         maxItems: 1
 143
 144       arm,trig-in-sigs:
 145         $ref: /schemas/types.yaml#/definitions/uint32-array
 146         minItems: 1
 147         maxItems: 32
 148         description:
 149           List of CTI trigger in signal numbers in use by a trig-conns node.
 150
 151       arm,trig-in-types:
 152         $ref: /schemas/types.yaml#/definitions/uint32-array
 153         minItems: 1
 154         maxItems: 32
 155         description:
 156           List of constants representing the types for the CTI trigger in
 157           signals. Types in this array match to the corresponding signal in the
 158           arm,trig-in-sigs array. If the -types array is smaller, or omitted
 159           completely, then the types will default to GEN_IO.
 160
 161       arm,trig-out-sigs:
 162         $ref: /schemas/types.yaml#/definitions/uint32-array
 163         minItems: 1
 164         maxItems: 32
 165         description:
 166           List of CTI trigger out signal numbers in use by a trig-conns node.
 167
 168       arm,trig-out-types:
 169         $ref: /schemas/types.yaml#/definitions/uint32-array
 170         minItems: 1
 171         maxItems: 32
 172         description:
 173           List of constants representing the types for the CTI trigger out
 174           signals. Types in this array match to the corresponding signal
 175           in the arm,trig-out-sigs array. If the "-types" array is smaller,
 176           or omitted completely, then the types will default to GEN_IO.
 177
 178       arm,trig-filters:
 179         $ref: /schemas/types.yaml#/definitions/uint32-array
 180         minItems: 1
 181         maxItems: 32
 182         description:
 183           List of CTI trigger out signals that will be blocked from becoming
 184           active, unless filtering is disabled on the driver.
 185
 186       arm,trig-conn-name:
 187         $ref: /schemas/types.yaml#/definitions/string
 188         description:
 189           Defines a connection name that will be displayed, if the cpu or
 190           arm,cs-dev-assoc properties are not being used in this connection.
 191           Principle use for CTI that are connected to non-CoreSight devices, or
 192           external IO.
 193
 194     anyOf:
 195       - required:
 196           - arm,trig-in-sigs
 197       - required:
 198           - arm,trig-out-sigs
 199     oneOf:
 200       - required:
 201           - arm,trig-conn-name
 202       - required:
 203           - cpu
 204       - required:
 205           - arm,cs-dev-assoc
 206     required:
 207       - reg
 208
 209 required:
 210   - compatible
 211   - reg
 212   - clocks
 213   - clock-names
 214
 215 if:
 216   properties:
 217     compatible:
 218       contains:
 219         const: arm,coresight-cti-v8-arch
 220
 221 then:
 222   required:
 223     - cpu
 224
 225 unevaluatedProperties: false
 226
 227 examples:
 228   # minimum CTI definition. DEVID register used to set number of triggers.
 229   - |
 230     cti@20020000 {
 231       compatible = "arm,coresight-cti", "arm,primecell";
 232       reg = <0x20020000 0x1000>;
 233
 234       clocks = <&soc_smc50mhz>;
 235       clock-names = "apb_pclk";
 236     };
 237   #  v8 architecturally defined CTI - CPU + ETM connections generated by the
 238   #  driver according to the v8 architecture specification.
 239   - |
 240     cti@859000 {
 241       compatible = "arm,coresight-cti-v8-arch", "arm,coresight-cti",
 242                    "arm,primecell";
 243       reg = <0x859000 0x1000>;
 244
 245       clocks = <&soc_smc50mhz>;
 246       clock-names = "apb_pclk";
 247
 248       cpu = <&CPU1>;
 249       arm,cs-dev-assoc = <&etm1>;
 250     };
 251   # Implementation defined CTI - CPU + ETM connections explicitly defined..
 252   # Shows use of type constants from dt-bindings/arm/coresight-cti-dt.h
 253   # #size-cells and #address-cells are required if trig-conns@ nodes present.
 254   - |
 255     #include <dt-bindings/arm/coresight-cti-dt.h>
 256
 257     cti@858000 {
 258       compatible = "arm,coresight-cti", "arm,primecell";
 259       reg = <0x858000 0x1000>;
 260
 261       clocks = <&soc_smc50mhz>;
 262       clock-names = "apb_pclk";
 263
 264       arm,cti-ctm-id = <1>;
 265
 266       #address-cells = <1>;
 267       #size-cells = <0>;
 268
 269       trig-conns@0 {
 270             reg = <0>;
 271             arm,trig-in-sigs = <4 5 6 7>;
 272             arm,trig-in-types = <ETM_EXTOUT
 273                                  ETM_EXTOUT
 274                                  ETM_EXTOUT
 275                                  ETM_EXTOUT>;
 276             arm,trig-out-sigs = <4 5 6 7>;
 277             arm,trig-out-types = <ETM_EXTIN
 278                                   ETM_EXTIN
 279                                   ETM_EXTIN
 280                                   ETM_EXTIN>;
 281             arm,cs-dev-assoc = <&etm0>;
 282       };
 283
 284       trig-conns@1 {
 285             reg = <1>;
 286             cpu = <&CPU0>;
 287             arm,trig-in-sigs = <0 1>;
 288             arm,trig-in-types = <PE_DBGTRIGGER
 289                                  PE_PMUIRQ>;
 290             arm,trig-out-sigs=<0 1 2 >;
 291             arm,trig-out-types = <PE_EDBGREQ
 292                                   PE_DBGRESTART
 293                                   PE_CTIIRQ>;
 294
 295             arm,trig-filters = <0>;
 296       };
 297     };
 298   # Implementation defined CTI - non CoreSight component connections.
 299   - |
 300     cti@20110000 {
 301       compatible = "arm,coresight-cti", "arm,primecell";
 302       reg = <0x20110000 0x1000>;
 303
 304       clocks = <&soc_smc50mhz>;
 305       clock-names = "apb_pclk";
 306
 307       #address-cells = <1>;
 308       #size-cells = <0>;
 309
 310       trig-conns@0 {
 311         reg = <0>;
 312         arm,trig-in-sigs=<0>;
 313         arm,trig-in-types=<GEN_INTREQ>;
 314         arm,trig-out-sigs=<0>;
 315         arm,trig-out-types=<GEN_HALTREQ>;
 316         arm,trig-conn-name = "sys_profiler";
 317       };
 318
 319       trig-conns@1 {
 320         reg = <1>;
 321         arm,trig-out-sigs=<2 3>;
 322         arm,trig-out-types=<GEN_HALTREQ GEN_RESTARTREQ>;
 323         arm,trig-conn-name = "watchdog";
 324       };
 325
 326       trig-conns@2 {
 327         reg = <2>;
 328         arm,trig-in-sigs=<1 6>;
 329         arm,trig-in-types=<GEN_HALTREQ GEN_RESTARTREQ>;
 330         arm,trig-conn-name = "g_counter";
 331       };
 332     };
 333
 334 ...