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