Documentation/devicetree/bindings/arm/coresight.txt

   1 * CoreSight Components:
   2
   3 CoreSight components are compliant with the ARM CoreSight architecture
   4 specification and can be connected in various topologies to suit a particular
   5 SoCs tracing needs. These trace components can generally be classified as
   6 sinks, links and sources. Trace data produced by one or more sources flows
   7 through the intermediate links connecting the source to the currently selected
   8 sink. Each CoreSight component device should use these properties to describe
   9 its hardware characteristcs.
  10
  11 * Required properties for all components *except* non-configurable replicators
  12   and non-configurable funnels:
  13
  14         * compatible: These have to be supplemented with "arm,primecell" as
  15           drivers are using the AMBA bus interface.  Possible values include:
  16                 - Embedded Trace Buffer (version 1.0):
  17                         "arm,coresight-etb10", "arm,primecell";
  18
  19                 - Trace Port Interface Unit:
  20                         "arm,coresight-tpiu", "arm,primecell";
  21
  22                 - Trace Memory Controller, used for Embedded Trace Buffer(ETB),
  23                   Embedded Trace FIFO(ETF) and Embedded Trace Router(ETR)
  24                   configuration.  The configuration mode (ETB, ETF, ETR) is
  25                   discovered at boot time when the device is probed.
  26                         "arm,coresight-tmc", "arm,primecell";
  27
  28                 - Trace Programmable Funnel:
  29                         "arm,coresight-dynamic-funnel", "arm,primecell";
  30                         "arm,coresight-funnel", "arm,primecell"; (OBSOLETE. For
  31                                 backward compatibility and will be removed)
  32
  33                 - Embedded Trace Macrocell (version 3.x) and
  34                                         Program Flow Trace Macrocell:
  35                         "arm,coresight-etm3x", "arm,primecell";
  36
  37                 - Embedded Trace Macrocell (version 4.x), with memory mapped access.
  38                         "arm,coresight-etm4x", "arm,primecell";
  39
  40                 - Embedded Trace Macrocell (version 4.x), with system register access only.
  41                         "arm,coresight-etm4x-sysreg";
  42
  43                 - Coresight programmable Replicator :
  44                         "arm,coresight-dynamic-replicator", "arm,primecell";
  45
  46                 - System Trace Macrocell:
  47                         "arm,coresight-stm", "arm,primecell"; [1]
  48                 - Coresight Address Translation Unit (CATU)
  49                         "arm,coresight-catu", "arm,primecell";
  50
  51                 - Coresight Cross Trigger Interface (CTI):
  52                         "arm,coresight-cti", "arm,primecell";
  53                         See coresight-cti.yaml for full CTI definitions.
  54
  55         * reg: physical base address and length of the register
  56           set(s) of the component.
  57
  58         * clocks: the clocks associated to this component.
  59
  60         * clock-names: the name of the clocks referenced by the code.
  61           Since we are using the AMBA framework, the name of the clock
  62           providing the interconnect should be "apb_pclk", and some
  63           coresight blocks also have an additional clock "atclk", which
  64           clocks the core of that coresight component. The latter clock
  65           is optional.
  66
  67         * port or ports: see "Graph bindings for Coresight" below.
  68
  69 * Additional required property for Embedded Trace Macrocell (version 3.x and
  70   version 4.x):
  71         * cpu: the cpu phandle this ETM/PTM is affined to. Do not
  72           assume it to default to CPU0 if omitted.
  73
  74 * Additional required properties for System Trace Macrocells (STM):
  75         * reg: along with the physical base address and length of the register
  76           set as described above, another entry is required to describe the
  77           mapping of the extended stimulus port area.
  78
  79         * reg-names: the only acceptable values are "stm-base" and
  80           "stm-stimulus-base", each corresponding to the areas defined in "reg".
  81
  82 * Required properties for Coresight Cross Trigger Interface (CTI)
  83         See coresight-cti.yaml for full CTI definitions.
  84
  85 * Required properties for devices that don't show up on the AMBA bus, such as
  86   non-configurable replicators and non-configurable funnels:
  87
  88         * compatible: Currently supported value is (note the absence of the
  89           AMBA markee):
  90                 - Coresight Non-configurable Replicator:
  91                         "arm,coresight-static-replicator";
  92                         "arm,coresight-replicator"; (OBSOLETE. For backward
  93                                 compatibility and will be removed)
  94
  95                 - Coresight Non-configurable Funnel:
  96                         "arm,coresight-static-funnel";
  97
  98         * port or ports: see "Graph bindings for Coresight" below.
  99
 100 * Optional properties for all components:
 101
 102         * arm,coresight-loses-context-with-cpu : boolean. Indicates that the
 103           hardware will lose register context on CPU power down (e.g. CPUIdle).
 104           An example of where this may be needed are systems which contain a
 105           coresight component and CPU in the same power domain. When the CPU
 106           powers down the coresight component also powers down and loses its
 107           context. This property is currently only used for the ETM 4.x driver.
 108
 109 * Optional properties for ETM/PTMs:
 110
 111         * arm,cp14: must be present if the system accesses ETM/PTM management
 112           registers via co-processor 14.
 113
 114         * qcom,skip-power-up: boolean. Indicates that an implementation can
 115           skip powering up the trace unit. TRCPDCR.PU does not have to be set
 116           on Qualcomm Technologies Inc. systems since ETMs are in the same power
 117           domain as their CPU cores. This property is required to identify such
 118           systems with hardware errata where the CPU watchdog counter is stopped
 119           when TRCPDCR.PU is set.
 120
 121 * Optional property for TMC:
 122
 123         * arm,buffer-size: size of contiguous buffer space for TMC ETR
 124           (embedded trace router). This property is obsolete. The buffer size
 125           can be configured dynamically via buffer_size property in sysfs.
 126
 127         * arm,scatter-gather: boolean. Indicates that the TMC-ETR can safely
 128           use the SG mode on this system.
 129
 130         * arm,max-burst-size: The maximum burst size initiated by TMC on the
 131           AXI master interface. The burst size can be in the range [0..15],
 132           the setting supports one data transfer per burst up to a maximum of
 133           16 data transfers per burst.
 134
 135 * Optional property for CATU :
 136         * interrupts : Exactly one SPI may be listed for reporting the address
 137           error
 138
 139 * Optional property for configurable replicators:
 140
 141         * qcom,replicator-loses-context: boolean. Indicates that the replicator
 142           will lose register context when AMBA clock is removed which is observed
 143           in some replicator designs.
 144
 145 Graph bindings for Coresight
 146 -------------------------------
 147
 148 Coresight components are interconnected to create a data path for the flow of
 149 trace data generated from the "sources" to their collection points "sink".
 150 Each coresight component must describe the "input" and "output" connections.
 151 The connections must be described via generic DT graph bindings as described
 152 by the "bindings/graph.txt", where each "port" along with an "endpoint"
 153 component represents a hardware port and the connection.
 154
 155  * All output ports must be listed inside a child node named "out-ports"
 156  * All input ports must be listed inside a child node named "in-ports".
 157  * Port address must match the hardware port number.
 158
 159 Example:
 160
 161 1. Sinks
 162         etb@20010000 {
 163                 compatible = "arm,coresight-etb10", "arm,primecell";
 164                 reg = <0 0x20010000 0 0x1000>;
 165
 166                 clocks = <&oscclk6a>;
 167                 clock-names = "apb_pclk";
 168                 in-ports {
 169                         port {
 170                                 etb_in_port: endpoint@0 {
 171                                         remote-endpoint = <&replicator_out_port0>;
 172                                 };
 173                         };
 174                 };
 175         };
 176
 177         tpiu@20030000 {
 178                 compatible = "arm,coresight-tpiu", "arm,primecell";
 179                 reg = <0 0x20030000 0 0x1000>;
 180
 181                 clocks = <&oscclk6a>;
 182                 clock-names = "apb_pclk";
 183                 in-ports {
 184                         port {
 185                                 tpiu_in_port: endpoint@0 {
 186                                         remote-endpoint = <&replicator_out_port1>;
 187                                 };
 188                         };
 189                 };
 190         };
 191
 192         etr@20070000 {
 193                 compatible = "arm,coresight-tmc", "arm,primecell";
 194                 reg = <0 0x20070000 0 0x1000>;
 195
 196                 clocks = <&oscclk6a>;
 197                 clock-names = "apb_pclk";
 198                 in-ports {
 199                         port {
 200                                 etr_in_port: endpoint {
 201                                         remote-endpoint = <&replicator2_out_port0>;
 202                                 };
 203                         };
 204                 };
 205
 206                 out-ports {
 207                         port {
 208                                 etr_out_port: endpoint {
 209                                         remote-endpoint = <&catu_in_port>;
 210                                 };
 211                         };
 212                 };
 213         };
 214
 215 2. Links
 216         replicator {
 217                 /* non-configurable replicators don't show up on the
 218                  * AMBA bus.  As such no need to add "arm,primecell".
 219                  */
 220                 compatible = "arm,coresight-static-replicator";
 221
 222                 out-ports {
 223                         #address-cells = <1>;
 224                         #size-cells = <0>;
 225
 226                         /* replicator output ports */
 227                         port@0 {
 228                                 reg = <0>;
 229                                 replicator_out_port0: endpoint {
 230                                         remote-endpoint = <&etb_in_port>;
 231                                 };
 232                         };
 233
 234                         port@1 {
 235                                 reg = <1>;
 236                                 replicator_out_port1: endpoint {
 237                                         remote-endpoint = <&tpiu_in_port>;
 238                                 };
 239                         };
 240                 };
 241
 242                 in-ports {
 243                         port {
 244                                 replicator_in_port0: endpoint {
 245                                         remote-endpoint = <&funnel_out_port0>;
 246                                 };
 247                         };
 248                 };
 249         };
 250
 251         funnel {
 252                 /*
 253                  * non-configurable funnel don't show up on the AMBA
 254                  * bus.  As such no need to add "arm,primecell".
 255                  */
 256                 compatible = "arm,coresight-static-funnel";
 257                 clocks = <&crg_ctrl HI3660_PCLK>;
 258                 clock-names = "apb_pclk";
 259
 260                 out-ports {
 261                         port {
 262                                 combo_funnel_out: endpoint {
 263                                         remote-endpoint = <&top_funnel_in>;
 264                                 };
 265                         };
 266                 };
 267
 268                 in-ports {
 269                         #address-cells = <1>;
 270                         #size-cells = <0>;
 271
 272                         port@0 {
 273                                 reg = <0>;
 274                                 combo_funnel_in0: endpoint {
 275                                         remote-endpoint = <&cluster0_etf_out>;
 276                                 };
 277                         };
 278
 279                         port@1 {
 280                                 reg = <1>;
 281                                 combo_funnel_in1: endpoint {
 282                                         remote-endpoint = <&cluster1_etf_out>;
 283                                 };
 284                         };
 285                 };
 286         };
 287
 288         funnel@20040000 {
 289                 compatible = "arm,coresight-dynamic-funnel", "arm,primecell";
 290                 reg = <0 0x20040000 0 0x1000>;
 291
 292                 clocks = <&oscclk6a>;
 293                 clock-names = "apb_pclk";
 294                 out-ports {
 295                         port {
 296                                 funnel_out_port0: endpoint {
 297                                         remote-endpoint =
 298                                                         <&replicator_in_port0>;
 299                                 };
 300                         };
 301                 };
 302
 303                 in-ports {
 304                         #address-cells = <1>;
 305                         #size-cells = <0>;
 306
 307                         port@0 {
 308                                 reg = <0>;
 309                                 funnel_in_port0: endpoint {
 310                                         remote-endpoint = <&ptm0_out_port>;
 311                                 };
 312                         };
 313
 314                         port@1 {
 315                                 reg = <1>;
 316                                 funnel_in_port1: endpoint {
 317                                         remote-endpoint = <&ptm1_out_port>;
 318                                 };
 319                         };
 320
 321                         port@2 {
 322                                 reg = <2>;
 323                                 funnel_in_port2: endpoint {
 324                                         remote-endpoint = <&etm0_out_port>;
 325                                 };
 326                         };
 327
 328                 };
 329         };
 330
 331 3. Sources
 332         ptm@2201c000 {
 333                 compatible = "arm,coresight-etm3x", "arm,primecell";
 334                 reg = <0 0x2201c000 0 0x1000>;
 335
 336                 cpu = <&cpu0>;
 337                 clocks = <&oscclk6a>;
 338                 clock-names = "apb_pclk";
 339                 out-ports {
 340                         port {
 341                                 ptm0_out_port: endpoint {
 342                                         remote-endpoint = <&funnel_in_port0>;
 343                                 };
 344                         };
 345                 };
 346         };
 347
 348         ptm@2201d000 {
 349                 compatible = "arm,coresight-etm3x", "arm,primecell";
 350                 reg = <0 0x2201d000 0 0x1000>;
 351
 352                 cpu = <&cpu1>;
 353                 clocks = <&oscclk6a>;
 354                 clock-names = "apb_pclk";
 355                 out-ports {
 356                         port {
 357                                 ptm1_out_port: endpoint {
 358                                         remote-endpoint = <&funnel_in_port1>;
 359                                 };
 360                         };
 361                 };
 362         };
 363
 364 4. STM
 365         stm@20100000 {
 366                 compatible = "arm,coresight-stm", "arm,primecell";
 367                 reg = <0 0x20100000 0 0x1000>,
 368                       <0 0x28000000 0 0x180000>;
 369                 reg-names = "stm-base", "stm-stimulus-base";
 370
 371                 clocks = <&soc_smc50mhz>;
 372                 clock-names = "apb_pclk";
 373                 out-ports {
 374                         port {
 375                                 stm_out_port: endpoint {
 376                                         remote-endpoint = <&main_funnel_in_port2>;
 377                                 };
 378                         };
 379                 };
 380         };
 381
 382 5. CATU
 383
 384         catu@207e0000 {
 385                 compatible = "arm,coresight-catu", "arm,primecell";
 386                 reg = <0 0x207e0000 0 0x1000>;
 387
 388                 clocks = <&oscclk6a>;
 389                 clock-names = "apb_pclk";
 390
 391                 interrupts = <GIC_SPI 4 IRQ_TYPE_LEVEL_HIGH>;
 392                 in-ports {
 393                         port {
 394                                 catu_in_port: endpoint {
 395                                         remote-endpoint = <&etr_out_port>;
 396                                 };
 397                         };
 398                 };
 399         };
 400
 401 [1]. There is currently two version of STM: STM32 and STM500.  Both
 402 have the same HW interface and as such don't need an explicit binding name.