Documentation/trace/coresight.txt

   1                 Coresight - HW Assisted Tracing on ARM
   2                 ======================================
   3
   4    Author:   Mathieu Poirier <mathieu.poirier@linaro.org>
   5    Date:     September 11th, 2014
   6
   7 Introduction
   8 ------------
   9
  10 Coresight is an umbrella of technologies allowing for the debugging of ARM
  11 based SoC.  It includes solutions for JTAG and HW assisted tracing.  This
  12 document is concerned with the latter.
  13
  14 HW assisted tracing is becoming increasingly useful when dealing with systems
  15 that have many SoCs and other components like GPU and DMA engines.  ARM has
  16 developed a HW assisted tracing solution by means of different components, each
  17 being added to a design at synthesis time to cater to specific tracing needs.
  18 Components are generally categorised as source, link and sinks and are
  19 (usually) discovered using the AMBA bus.
  20
  21 "Sources" generate a compressed stream representing the processor instruction
  22 path based on tracing scenarios as configured by users.  From there the stream
  23 flows through the coresight system (via ATB bus) using links that are connecting
  24 the emanating source to a sink(s).  Sinks serve as endpoints to the coresight
  25 implementation, either storing the compressed stream in a memory buffer or
  26 creating an interface to the outside world where data can be transferred to a
  27 host without fear of filling up the onboard coresight memory buffer.
  28
  29 At typical coresight system would look like this:
  30
  31   *****************************************************************
  32  **************************** AMBA AXI  ****************************===||
  33   *****************************************************************    ||
  34         ^                    ^                            |            ||
  35         |                    |                            *            **
  36      0000000    :::::     0000000    :::::    :::::    @@@@@@@    ||||||||||||
  37      0 CPU 0<-->: C :     0 CPU 0<-->: C :    : C :    @ STM @    || System ||
  38   |->0000000    : T :  |->0000000    : T :    : T :<--->@@@@@     || Memory ||
  39   |  #######<-->: I :  |  #######<-->: I :    : I :      @@@<-|   ||||||||||||
  40   |  # ETM #    :::::  |  # PTM #    :::::    :::::       @   |
  41   |   #####      ^ ^   |   #####      ^ !      ^ !        .   |   |||||||||
  42   | |->###       | !   | |->###       | !      | !        .   |   || DAP ||
  43   | |   #        | !   | |   #        | !      | !        .   |   |||||||||
  44   | |   .        | !   | |   .        | !      | !        .   |      |  |
  45   | |   .        | !   | |   .        | !      | !        .   |      |  *
  46   | |   .        | !   | |   .        | !      | !        .   |      | SWD/
  47   | |   .        | !   | |   .        | !      | !        .   |      | JTAG
  48   *****************************************************************<-|
  49  *************************** AMBA Debug APB ************************
  50   *****************************************************************
  51    |    .          !         .          !        !        .    |
  52    |    .          *         .          *        *        .    |
  53   *****************************************************************
  54  ******************** Cross Trigger Matrix (CTM) *******************
  55   *****************************************************************
  56    |    .     ^              .                            .    |
  57    |    *     !              *                            *    |
  58   *****************************************************************
  59  ****************** AMBA Advanced Trace Bus (ATB) ******************
  60   *****************************************************************
  61    |          !                        ===============         |
  62    |          *                         ===== F =====<---------|
  63    |   :::::::::                         ==== U ====
  64    |-->:: CTI ::<!!                       === N ===
  65    |   :::::::::  !                        == N ==
  66    |    ^         *                        == E ==
  67    |    !  &&&&&&&&&       IIIIIII         == L ==
  68    |------>&& ETB &&<......II     I        =======
  69    |    !  &&&&&&&&&       II     I           .
  70    |    !                    I     I          .
  71    |    !                    I REP I<..........
  72    |    !                    I     I
  73    |    !!>&&&&&&&&&       II     I           *Source: ARM ltd.
  74    |------>& TPIU  &<......II    I            DAP = Debug Access Port
  75            &&&&&&&&&       IIIIIII            ETM = Embedded Trace Macrocell
  76                ;                              PTM = Program Trace Macrocell
  77                ;                              CTI = Cross Trigger Interface
  78                *                              ETB = Embedded Trace Buffer
  79           To trace port                       TPIU= Trace Port Interface Unit
  80                                               SWD = Serial Wire Debug
  81
  82 While on target configuration of the components is done via the APB bus,
  83 all trace data are carried out-of-band on the ATB bus.  The CTM provides
  84 a way to aggregate and distribute signals between CoreSight components.
  85
  86 The coresight framework provides a central point to represent, configure and
  87 manage coresight devices on a platform.  This first implementation centers on
  88 the basic tracing functionality, enabling components such ETM/PTM, funnel,
  89 replicator, TMC, TPIU and ETB.  Future work will enable more
  90 intricate IP blocks such as STM and CTI.
  91
  92
  93 Acronyms and Classification
  94 ---------------------------
  95
  96 Acronyms:
  97
  98 PTM:     Program Trace Macrocell
  99 ETM:     Embedded Trace Macrocell
 100 STM:     System trace Macrocell
 101 ETB:     Embedded Trace Buffer
 102 ITM:     Instrumentation Trace Macrocell
 103 TPIU:    Trace Port Interface Unit
 104 TMC-ETR: Trace Memory Controller, configured as Embedded Trace Router
 105 TMC-ETF: Trace Memory Controller, configured as Embedded Trace FIFO
 106 CTI:     Cross Trigger Interface
 107
 108 Classification:
 109
 110 Source:
 111    ETMv3.x ETMv4, PTMv1.0, PTMv1.1, STM, STM500, ITM
 112 Link:
 113    Funnel, replicator (intelligent or not), TMC-ETR
 114 Sinks:
 115    ETBv1.0, ETB1.1, TPIU, TMC-ETF
 116 Misc:
 117    CTI
 118
 119
 120 Device Tree Bindings
 121 ----------------------
 122
 123 See Documentation/devicetree/bindings/arm/coresight.txt for details.
 124
 125 As of this writing drivers for ITM, STMs and CTIs are not provided but are
 126 expected to be added as the solution matures.
 127
 128
 129 Framework and implementation
 130 ----------------------------
 131
 132 The coresight framework provides a central point to represent, configure and
 133 manage coresight devices on a platform.  Any coresight compliant device can
 134 register with the framework for as long as they use the right APIs:
 135
 136 struct coresight_device *coresight_register(struct coresight_desc *desc);
 137 void coresight_unregister(struct coresight_device *csdev);
 138
 139 The registering function is taking a "struct coresight_device *csdev" and
 140 register the device with the core framework.  The unregister function takes
 141 a reference to a "struct coresight_device", obtained at registration time.
 142
 143 If everything goes well during the registration process the new devices will
 144 show up under /sys/bus/coresight/devices, as showns here for a TC2 platform:
 145
 146 root:~# ls /sys/bus/coresight/devices/
 147 replicator  20030000.tpiu    2201c000.ptm  2203c000.etm  2203e000.etm
 148 20010000.etb         20040000.funnel  2201d000.ptm  2203d000.etm
 149 root:~#
 150
 151 The functions take a "struct coresight_device", which looks like this:
 152
 153 struct coresight_desc {
 154         enum coresight_dev_type type;
 155         struct coresight_dev_subtype subtype;
 156         const struct coresight_ops *ops;
 157         struct coresight_platform_data *pdata;
 158         struct device *dev;
 159         const struct attribute_group **groups;
 160 };
 161
 162
 163 The "coresight_dev_type" identifies what the device is, i.e, source link or
 164 sink while the "coresight_dev_subtype" will characterise that type further.
 165
 166 The "struct coresight_ops" is mandatory and will tell the framework how to
 167 perform base operations related to the components, each component having
 168 a different set of requirement.  For that "struct coresight_ops_sink",
 169 "struct coresight_ops_link" and "struct coresight_ops_source" have been
 170 provided.
 171
 172 The next field, "struct coresight_platform_data *pdata" is acquired by calling
 173 "of_get_coresight_platform_data()", as part of the driver's _probe routine and
 174 "struct device *dev" gets the device reference embedded in the "amba_device":
 175
 176 static int etm_probe(struct amba_device *adev, const struct amba_id *id)
 177 {
 178  ...
 179  ...
 180  drvdata->dev = &adev->dev;
 181  ...
 182 }
 183
 184 Specific class of device (source, link, or sink) have generic operations
 185 that can be performed on them (see "struct coresight_ops").  The
 186 "**groups" is a list of sysfs entries pertaining to operations
 187 specific to that component only.  "Implementation defined" customisations are
 188 expected to be accessed and controlled using those entries.
 189
 190 Last but not least, "struct module *owner" is expected to be set to reflect
 191 the information carried in "THIS_MODULE".
 192
 193 How to use the tracer modules
 194 -----------------------------
 195
 196 Before trace collection can start, a coresight sink needs to be identify.
 197 There is no limit on the amount of sinks (nor sources) that can be enabled at
 198 any given moment.  As a generic operation, all device pertaining to the sink
 199 class will have an "active" entry in sysfs:
 200
 201 root:/sys/bus/coresight/devices# ls
 202 replicator  20030000.tpiu    2201c000.ptm  2203c000.etm  2203e000.etm
 203 20010000.etb         20040000.funnel  2201d000.ptm  2203d000.etm
 204 root:/sys/bus/coresight/devices# ls 20010000.etb
 205 enable_sink  status  trigger_cntr
 206 root:/sys/bus/coresight/devices# echo 1 > 20010000.etb/enable_sink
 207 root:/sys/bus/coresight/devices# cat 20010000.etb/enable_sink
 208 1
 209 root:/sys/bus/coresight/devices#
 210
 211 At boot time the current etm3x driver will configure the first address
 212 comparator with "_stext" and "_etext", essentially tracing any instruction
 213 that falls within that range.  As such "enabling" a source will immediately
 214 trigger a trace capture:
 215
 216 root:/sys/bus/coresight/devices# echo 1 > 2201c000.ptm/enable_source
 217 root:/sys/bus/coresight/devices# cat 2201c000.ptm/enable_source
 218 1
 219 root:/sys/bus/coresight/devices# cat 20010000.etb/status
 220 Depth:          0x2000
 221 Status:         0x1
 222 RAM read ptr:   0x0
 223 RAM wrt ptr:    0x19d3   <----- The write pointer is moving
 224 Trigger cnt:    0x0
 225 Control:        0x1
 226 Flush status:   0x0
 227 Flush ctrl:     0x2001
 228 root:/sys/bus/coresight/devices#
 229
 230 Trace collection is stopped the same way:
 231
 232 root:/sys/bus/coresight/devices# echo 0 > 2201c000.ptm/enable_source
 233 root:/sys/bus/coresight/devices#
 234
 235 The content of the ETB buffer can be harvested directly from /dev:
 236
 237 root:/sys/bus/coresight/devices# dd if=/dev/20010000.etb \
 238 of=~/cstrace.bin
 239
 240 64+0 records in
 241 64+0 records out
 242 32768 bytes (33 kB) copied, 0.00125258 s, 26.2 MB/s
 243 root:/sys/bus/coresight/devices#
 244
 245 The file cstrace.bin can be decompressed using "ptm2human", DS-5 or Trace32.
 246
 247 Following is a DS-5 output of an experimental loop that increments a variable up
 248 to a certain value.  The example is simple and yet provides a glimpse of the
 249 wealth of possibilities that coresight provides.
 250
 251 Info                                    Tracing enabled
 252 Instruction     106378866       0x8026B53C      E52DE004        false   PUSH     {lr}
 253 Instruction     0       0x8026B540      E24DD00C        false   SUB      sp,sp,#0xc
 254 Instruction     0       0x8026B544      E3A03000        false   MOV      r3,#0
 255 Instruction     0       0x8026B548      E58D3004        false   STR      r3,[sp,#4]
 256 Instruction     0       0x8026B54C      E59D3004        false   LDR      r3,[sp,#4]
 257 Instruction     0       0x8026B550      E3530004        false   CMP      r3,#4
 258 Instruction     0       0x8026B554      E2833001        false   ADD      r3,r3,#1
 259 Instruction     0       0x8026B558      E58D3004        false   STR      r3,[sp,#4]
 260 Instruction     0       0x8026B55C      DAFFFFFA        true    BLE      {pc}-0x10 ; 0x8026b54c
 261 Timestamp                                       Timestamp: 17106715833
 262 Instruction     319     0x8026B54C      E59D3004        false   LDR      r3,[sp,#4]
 263 Instruction     0       0x8026B550      E3530004        false   CMP      r3,#4
 264 Instruction     0       0x8026B554      E2833001        false   ADD      r3,r3,#1
 265 Instruction     0       0x8026B558      E58D3004        false   STR      r3,[sp,#4]
 266 Instruction     0       0x8026B55C      DAFFFFFA        true    BLE      {pc}-0x10 ; 0x8026b54c
 267 Instruction     9       0x8026B54C      E59D3004        false   LDR      r3,[sp,#4]
 268 Instruction     0       0x8026B550      E3530004        false   CMP      r3,#4
 269 Instruction     0       0x8026B554      E2833001        false   ADD      r3,r3,#1
 270 Instruction     0       0x8026B558      E58D3004        false   STR      r3,[sp,#4]
 271 Instruction     0       0x8026B55C      DAFFFFFA        true    BLE      {pc}-0x10 ; 0x8026b54c
 272 Instruction     7       0x8026B54C      E59D3004        false   LDR      r3,[sp,#4]
 273 Instruction     0       0x8026B550      E3530004        false   CMP      r3,#4
 274 Instruction     0       0x8026B554      E2833001        false   ADD      r3,r3,#1
 275 Instruction     0       0x8026B558      E58D3004        false   STR      r3,[sp,#4]
 276 Instruction     0       0x8026B55C      DAFFFFFA        true    BLE      {pc}-0x10 ; 0x8026b54c
 277 Instruction     7       0x8026B54C      E59D3004        false   LDR      r3,[sp,#4]
 278 Instruction     0       0x8026B550      E3530004        false   CMP      r3,#4
 279 Instruction     0       0x8026B554      E2833001        false   ADD      r3,r3,#1
 280 Instruction     0       0x8026B558      E58D3004        false   STR      r3,[sp,#4]
 281 Instruction     0       0x8026B55C      DAFFFFFA        true    BLE      {pc}-0x10 ; 0x8026b54c
 282 Instruction     10      0x8026B54C      E59D3004        false   LDR      r3,[sp,#4]
 283 Instruction     0       0x8026B550      E3530004        false   CMP      r3,#4
 284 Instruction     0       0x8026B554      E2833001        false   ADD      r3,r3,#1
 285 Instruction     0       0x8026B558      E58D3004        false   STR      r3,[sp,#4]
 286 Instruction     0       0x8026B55C      DAFFFFFA        true    BLE      {pc}-0x10 ; 0x8026b54c
 287 Instruction     6       0x8026B560      EE1D3F30        false   MRC      p15,#0x0,r3,c13,c0,#1
 288 Instruction     0       0x8026B564      E1A0100D        false   MOV      r1,sp
 289 Instruction     0       0x8026B568      E3C12D7F        false   BIC      r2,r1,#0x1fc0
 290 Instruction     0       0x8026B56C      E3C2203F        false   BIC      r2,r2,#0x3f
 291 Instruction     0       0x8026B570      E59D1004        false   LDR      r1,[sp,#4]
 292 Instruction     0       0x8026B574      E59F0010        false   LDR      r0,[pc,#16] ; [0x8026B58C] = 0x80550368
 293 Instruction     0       0x8026B578      E592200C        false   LDR      r2,[r2,#0xc]
 294 Instruction     0       0x8026B57C      E59221D0        false   LDR      r2,[r2,#0x1d0]
 295 Instruction     0       0x8026B580      EB07A4CF        true    BL       {pc}+0x1e9344 ; 0x804548c4
 296 Info                                    Tracing enabled
 297 Instruction     13570831        0x8026B584      E28DD00C        false   ADD      sp,sp,#0xc
 298 Instruction     0       0x8026B588      E8BD8000        true    LDM      sp!,{pc}
 299 Timestamp                                       Timestamp: 17107041535
 300
 301 How to use the STM module
 302 -------------------------
 303
 304 Using the System Trace Macrocell module is the same as the tracers - the only
 305 difference is that clients are driving the trace capture rather
 306 than the program flow through the code.
 307
 308 As with any other CoreSight component, specifics about the STM tracer can be
 309 found in sysfs with more information on each entry being found in [1]:
 310
 311 root@genericarmv8:~# ls /sys/bus/coresight/devices/20100000.stm
 312 enable_source   hwevent_select  port_enable     subsystem       uevent
 313 hwevent_enable  mgmt            port_select     traceid
 314 root@genericarmv8:~#
 315
 316 Like any other source a sink needs to be identified and the STM enabled before
 317 being used:
 318
 319 root@genericarmv8:~# echo 1 > /sys/bus/coresight/devices/20010000.etf/enable_sink
 320 root@genericarmv8:~# echo 1 > /sys/bus/coresight/devices/20100000.stm/enable_source
 321
 322 From there user space applications can request and use channels using the devfs
 323 interface provided for that purpose by the generic STM API:
 324
 325 root@genericarmv8:~# ls -l /dev/20100000.stm
 326 crw-------    1 root     root       10,  61 Jan  3 18:11 /dev/20100000.stm
 327 root@genericarmv8:~#
 328
 329 Details on how to use the generic STM API can be found here [2].
 330
 331 [1]. Documentation/ABI/testing/sysfs-bus-coresight-devices-stm
 332 [2]. Documentation/trace/stm.txt