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         $ref: /schemas/types.yaml#/definitions/uint32-array
 144         minItems: 1
 145         maxItems: 32
 146         description:
 147           List of CTI trigger in signal numbers in use by a trig-conns node.
 148
 149       arm,trig-in-types:
 150         $ref: /schemas/types.yaml#/definitions/uint32-array
 151         minItems: 1
 152         maxItems: 32
 153         description:
 154           List of constants representing the types for the CTI trigger in
 155           signals. Types in this array match to the corresponding signal in the
 156           arm,trig-in-sigs array. If the -types array is smaller, or omitted
 157           completely, then the types will default to GEN_IO.
 158
 159       arm,trig-out-sigs:
 160         $ref: /schemas/types.yaml#/definitions/uint32-array
 161         minItems: 1
 162         maxItems: 32
 163         description:
 164           List of CTI trigger out signal numbers in use by a trig-conns node.
 165
 166       arm,trig-out-types:
 167         $ref: /schemas/types.yaml#/definitions/uint32-array
 168         minItems: 1
 169         maxItems: 32
 170         description:
 171           List of constants representing the types for the CTI trigger out
 172           signals. Types in this array match to the corresponding signal
 173           in the arm,trig-out-sigs array. If the "-types" array is smaller,
 174           or omitted completely, then the types will default to GEN_IO.
 175
 176       arm,trig-filters:
 177         $ref: /schemas/types.yaml#/definitions/uint32-array
 178         minItems: 1
 179         maxItems: 32
 180         description:
 181           List of CTI trigger out signals that will be blocked from becoming
 182           active, unless filtering is disabled on the driver.
 183
 184       arm,trig-conn-name:
 185         $ref: /schemas/types.yaml#/definitions/string
 186         description:
 187           Defines a connection name that will be displayed, if the cpu or
 188           arm,cs-dev-assoc properties are not being used in this connection.
 189           Principle use for CTI that are connected to non-CoreSight devices, or
 190           external IO.
 191
 192     anyOf:
 193       - required:
 194           - arm,trig-in-sigs
 195       - required:
 196           - arm,trig-out-sigs
 197     oneOf:
 198       - required:
 199           - arm,trig-conn-name
 200       - required:
 201           - cpu
 202       - required:
 203           - arm,cs-dev-assoc
 204     required:
 205       - reg
 206
 207 required:
 208   - compatible
 209   - reg
 210   - clocks
 211   - clock-names
 212
 213 if:
 214   properties:
 215     compatible:
 216       contains:
 217         const: arm,coresight-cti-v8-arch
 218
 219 then:
 220   required:
 221     - cpu
 222
 223 examples:
 224   # minimum CTI definition. DEVID register used to set number of triggers.
 225   - |
 226     cti@20020000 {
 227       compatible = "arm,coresight-cti", "arm,primecell";
 228       reg = <0x20020000 0x1000>;
 229
 230       clocks = <&soc_smc50mhz>;
 231       clock-names = "apb_pclk";
 232     };
 233   #  v8 architecturally defined CTI - CPU + ETM connections generated by the
 234   #  driver according to the v8 architecture specification.
 235   - |
 236     cti@859000 {
 237       compatible = "arm,coresight-cti-v8-arch", "arm,coresight-cti",
 238                    "arm,primecell";
 239       reg = <0x859000 0x1000>;
 240
 241       clocks = <&soc_smc50mhz>;
 242       clock-names = "apb_pclk";
 243
 244       cpu = <&CPU1>;
 245       arm,cs-dev-assoc = <&etm1>;
 246     };
 247   # Implementation defined CTI - CPU + ETM connections explicitly defined..
 248   # Shows use of type constants from dt-bindings/arm/coresight-cti-dt.h
 249   # #size-cells and #address-cells are required if trig-conns@ nodes present.
 250   - |
 251     #include <dt-bindings/arm/coresight-cti-dt.h>
 252
 253     cti@858000 {
 254       compatible = "arm,coresight-cti", "arm,primecell";
 255       reg = <0x858000 0x1000>;
 256
 257       clocks = <&soc_smc50mhz>;
 258       clock-names = "apb_pclk";
 259
 260       arm,cti-ctm-id = <1>;
 261
 262       #address-cells = <1>;
 263       #size-cells = <0>;
 264
 265       trig-conns@0 {
 266             reg = <0>;
 267             arm,trig-in-sigs = <4 5 6 7>;
 268             arm,trig-in-types = <ETM_EXTOUT
 269                                  ETM_EXTOUT
 270                                  ETM_EXTOUT
 271                                  ETM_EXTOUT>;
 272             arm,trig-out-sigs = <4 5 6 7>;
 273             arm,trig-out-types = <ETM_EXTIN
 274                                   ETM_EXTIN
 275                                   ETM_EXTIN
 276                                   ETM_EXTIN>;
 277             arm,cs-dev-assoc = <&etm0>;
 278       };
 279
 280       trig-conns@1 {
 281             reg = <1>;
 282             cpu = <&CPU0>;
 283             arm,trig-in-sigs = <0 1>;
 284             arm,trig-in-types = <PE_DBGTRIGGER
 285                                  PE_PMUIRQ>;
 286             arm,trig-out-sigs=<0 1 2 >;
 287             arm,trig-out-types = <PE_EDBGREQ
 288                                   PE_DBGRESTART
 289                                   PE_CTIIRQ>;
 290
 291             arm,trig-filters = <0>;
 292       };
 293     };
 294   # Implementation defined CTI - non CoreSight component connections.
 295   - |
 296     cti@20110000 {
 297       compatible = "arm,coresight-cti", "arm,primecell";
 298       reg = <0x20110000 0x1000>;
 299
 300       clocks = <&soc_smc50mhz>;
 301       clock-names = "apb_pclk";
 302
 303       #address-cells = <1>;
 304       #size-cells = <0>;
 305
 306       trig-conns@0 {
 307         reg = <0>;
 308         arm,trig-in-sigs=<0>;
 309         arm,trig-in-types=<GEN_INTREQ>;
 310         arm,trig-out-sigs=<0>;
 311         arm,trig-out-types=<GEN_HALTREQ>;
 312         arm,trig-conn-name = "sys_profiler";
 313       };
 314
 315       trig-conns@1 {
 316         reg = <1>;
 317         arm,trig-out-sigs=<2 3>;
 318         arm,trig-out-types=<GEN_HALTREQ GEN_RESTARTREQ>;
 319         arm,trig-conn-name = "watchdog";
 320       };
 321
 322       trig-conns@2 {
 323         reg = <2>;
 324         arm,trig-in-sigs=<1 6>;
 325         arm,trig-in-types=<GEN_HALTREQ GEN_RESTARTREQ>;
 326         arm,trig-conn-name = "g_counter";
 327       };
 328     };
 329
 330 ...