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     description:
  96       Handle to cpu this CTI is associated with.
  97
  98   power-domains:
  99     maxItems: 1
 100
 101   arm,cti-ctm-id:
 102     $ref: /schemas/types.yaml#/definitions/uint32
 103     description:
 104       Defines the CTM this CTI is connected to, in large systems with multiple
 105       separate CTI/CTM nets. Typically multi-socket systems where the CTM is
 106       propagated between sockets.
 107
 108   arm,cs-dev-assoc:
 109     $ref: /schemas/types.yaml#/definitions/phandle
 110     description:
 111       defines a phandle reference to an associated CoreSight trace device.
 112       When the associated trace device is enabled, then the respective CTI
 113       will be enabled. Use in CTI base node when compatible string
 114       arm,coresight-cti-v8-arch used. If the associated device has not been
 115       registered then the node name will be stored as the connection name for
 116       later resolution. If the associated device is not a CoreSight device or
 117       not registered then the node name will remain the connection name and
 118       automatic enabling will not occur.
 119
 120   # size cells and address cells required if trig-conns node present.
 121   "#size-cells":
 122     const: 0
 123
 124   "#address-cells":
 125     const: 1
 126
 127 patternProperties:
 128   '^trig-conns@([0-9]+)$':
 129     type: object
 130     additionalProperties: false
 131
 132     description:
 133       A trigger connections child node which describes the trigger signals
 134       between this CTI and another hardware device. This device may be a CPU,
 135       CoreSight device, any other hardware device or simple external IO lines.
 136       The connection may have both input and output triggers, or only one or the
 137       other.
 138
 139     properties:
 140       reg:
 141         maxItems: 1
 142
 143       cpu:
 144         description:
 145           Handle to cpu this trigger connection is associated with.
 146
 147       arm,cs-dev-assoc:
 148         $ref: /schemas/types.yaml#/definitions/phandle
 149         description:
 150           defines a phandle reference to an associated CoreSight trace device.
 151           When the associated trace device is enabled, then the respective CTI
 152           will be enabled. If the associated device has not been registered
 153           then the node name will be stored as the connection name for later
 154           resolution. If the associated device is not a CoreSight device or
 155           not registered then the node name will remain the connection name
 156           and automatic enabling will not occur.
 157
 158       arm,trig-in-sigs:
 159         $ref: /schemas/types.yaml#/definitions/uint32-array
 160         minItems: 1
 161         maxItems: 32
 162         description:
 163           List of CTI trigger in signal numbers in use by a trig-conns node.
 164
 165       arm,trig-in-types:
 166         $ref: /schemas/types.yaml#/definitions/uint32-array
 167         minItems: 1
 168         maxItems: 32
 169         description:
 170           List of constants representing the types for the CTI trigger in
 171           signals. Types in this array match to the corresponding signal in the
 172           arm,trig-in-sigs array. If the -types array is smaller, or omitted
 173           completely, then the types will default to GEN_IO.
 174
 175       arm,trig-out-sigs:
 176         $ref: /schemas/types.yaml#/definitions/uint32-array
 177         minItems: 1
 178         maxItems: 32
 179         description:
 180           List of CTI trigger out signal numbers in use by a trig-conns node.
 181
 182       arm,trig-out-types:
 183         $ref: /schemas/types.yaml#/definitions/uint32-array
 184         minItems: 1
 185         maxItems: 32
 186         description:
 187           List of constants representing the types for the CTI trigger out
 188           signals. Types in this array match to the corresponding signal
 189           in the arm,trig-out-sigs array. If the "-types" array is smaller,
 190           or omitted completely, then the types will default to GEN_IO.
 191
 192       arm,trig-filters:
 193         $ref: /schemas/types.yaml#/definitions/uint32-array
 194         minItems: 1
 195         maxItems: 32
 196         description:
 197           List of CTI trigger out signals that will be blocked from becoming
 198           active, unless filtering is disabled on the driver.
 199
 200       arm,trig-conn-name:
 201         $ref: /schemas/types.yaml#/definitions/string
 202         description:
 203           Defines a connection name that will be displayed, if the cpu or
 204           arm,cs-dev-assoc properties are not being used in this connection.
 205           Principle use for CTI that are connected to non-CoreSight devices, or
 206           external IO.
 207
 208     anyOf:
 209       - required:
 210           - arm,trig-in-sigs
 211       - required:
 212           - arm,trig-out-sigs
 213     oneOf:
 214       - required:
 215           - arm,trig-conn-name
 216       - required:
 217           - cpu
 218       - required:
 219           - arm,cs-dev-assoc
 220     required:
 221       - reg
 222
 223 required:
 224   - compatible
 225   - reg
 226   - clocks
 227   - clock-names
 228
 229 if:
 230   properties:
 231     compatible:
 232       contains:
 233         const: arm,coresight-cti-v8-arch
 234
 235 then:
 236   required:
 237     - cpu
 238
 239 unevaluatedProperties: false
 240
 241 examples:
 242   # minimum CTI definition. DEVID register used to set number of triggers.
 243   - |
 244     cti@20020000 {
 245       compatible = "arm,coresight-cti", "arm,primecell";
 246       reg = <0x20020000 0x1000>;
 247
 248       clocks = <&soc_smc50mhz>;
 249       clock-names = "apb_pclk";
 250     };
 251   #  v8 architecturally defined CTI - CPU + ETM connections generated by the
 252   #  driver according to the v8 architecture specification.
 253   - |
 254     cti@859000 {
 255       compatible = "arm,coresight-cti-v8-arch", "arm,coresight-cti",
 256                    "arm,primecell";
 257       reg = <0x859000 0x1000>;
 258
 259       clocks = <&soc_smc50mhz>;
 260       clock-names = "apb_pclk";
 261
 262       cpu = <&CPU1>;
 263       arm,cs-dev-assoc = <&etm1>;
 264     };
 265   # Implementation defined CTI - CPU + ETM connections explicitly defined..
 266   # Shows use of type constants from dt-bindings/arm/coresight-cti-dt.h
 267   # #size-cells and #address-cells are required if trig-conns@ nodes present.
 268   - |
 269     #include <dt-bindings/arm/coresight-cti-dt.h>
 270
 271     cti@858000 {
 272       compatible = "arm,coresight-cti", "arm,primecell";
 273       reg = <0x858000 0x1000>;
 274
 275       clocks = <&soc_smc50mhz>;
 276       clock-names = "apb_pclk";
 277
 278       arm,cti-ctm-id = <1>;
 279
 280       #address-cells = <1>;
 281       #size-cells = <0>;
 282
 283       trig-conns@0 {
 284             reg = <0>;
 285             arm,trig-in-sigs = <4 5 6 7>;
 286             arm,trig-in-types = <ETM_EXTOUT
 287                                  ETM_EXTOUT
 288                                  ETM_EXTOUT
 289                                  ETM_EXTOUT>;
 290             arm,trig-out-sigs = <4 5 6 7>;
 291             arm,trig-out-types = <ETM_EXTIN
 292                                   ETM_EXTIN
 293                                   ETM_EXTIN
 294                                   ETM_EXTIN>;
 295             arm,cs-dev-assoc = <&etm0>;
 296       };
 297
 298       trig-conns@1 {
 299             reg = <1>;
 300             cpu = <&CPU0>;
 301             arm,trig-in-sigs = <0 1>;
 302             arm,trig-in-types = <PE_DBGTRIGGER
 303                                  PE_PMUIRQ>;
 304             arm,trig-out-sigs = <0 1 2 >;
 305             arm,trig-out-types = <PE_EDBGREQ
 306                                   PE_DBGRESTART
 307                                   PE_CTIIRQ>;
 308
 309             arm,trig-filters = <0>;
 310       };
 311     };
 312   # Implementation defined CTI - non CoreSight component connections.
 313   - |
 314     cti@20110000 {
 315       compatible = "arm,coresight-cti", "arm,primecell";
 316       reg = <0x20110000 0x1000>;
 317
 318       clocks = <&soc_smc50mhz>;
 319       clock-names = "apb_pclk";
 320
 321       #address-cells = <1>;
 322       #size-cells = <0>;
 323
 324       trig-conns@0 {
 325         reg = <0>;
 326         arm,trig-in-sigs = <0>;
 327         arm,trig-in-types = <GEN_INTREQ>;
 328         arm,trig-out-sigs = <0>;
 329         arm,trig-out-types = <GEN_HALTREQ>;
 330         arm,trig-conn-name = "sys_profiler";
 331       };
 332
 333       trig-conns@1 {
 334         reg = <1>;
 335         arm,trig-out-sigs = <2 3>;
 336         arm,trig-out-types = <GEN_HALTREQ GEN_RESTARTREQ>;
 337         arm,trig-conn-name = "watchdog";
 338       };
 339
 340       trig-conns@2 {
 341         reg = <2>;
 342         arm,trig-in-sigs = <1 6>;
 343         arm,trig-in-types = <GEN_HALTREQ GEN_RESTARTREQ>;
 344         arm,trig-conn-name = "g_counter";
 345       };
 346     };
 347
 348 ...