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