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
 191 How to use the tracer modules
 192 -----------------------------
 193
 194 There are two ways to use the Coresight framework: 1) using the perf cmd line
 195 tools and 2) interacting directly with the Coresight devices using the sysFS
 196 interface.  Preference is given to the former as using the sysFS interface
 197 requires a deep understanding of the Coresight HW.  The following sections
 198 provide details on using both methods.
 199
 200 1) Using the sysFS interface:
 201
 202 Before trace collection can start, a coresight sink needs to be identified.
 203 There is no limit on the amount of sinks (nor sources) that can be enabled at
 204 any given moment.  As a generic operation, all device pertaining to the sink
 205 class will have an "active" entry in sysfs:
 206
 207 root:/sys/bus/coresight/devices# ls
 208 replicator  20030000.tpiu    2201c000.ptm  2203c000.etm  2203e000.etm
 209 20010000.etb         20040000.funnel  2201d000.ptm  2203d000.etm
 210 root:/sys/bus/coresight/devices# ls 20010000.etb
 211 enable_sink  status  trigger_cntr
 212 root:/sys/bus/coresight/devices# echo 1 > 20010000.etb/enable_sink
 213 root:/sys/bus/coresight/devices# cat 20010000.etb/enable_sink
 214 1
 215 root:/sys/bus/coresight/devices#
 216
 217 At boot time the current etm3x driver will configure the first address
 218 comparator with "_stext" and "_etext", essentially tracing any instruction
 219 that falls within that range.  As such "enabling" a source will immediately
 220 trigger a trace capture:
 221
 222 root:/sys/bus/coresight/devices# echo 1 > 2201c000.ptm/enable_source
 223 root:/sys/bus/coresight/devices# cat 2201c000.ptm/enable_source
 224 1
 225 root:/sys/bus/coresight/devices# cat 20010000.etb/status
 226 Depth:          0x2000
 227 Status:         0x1
 228 RAM read ptr:   0x0
 229 RAM wrt ptr:    0x19d3   <----- The write pointer is moving
 230 Trigger cnt:    0x0
 231 Control:        0x1
 232 Flush status:   0x0
 233 Flush ctrl:     0x2001
 234 root:/sys/bus/coresight/devices#
 235
 236 Trace collection is stopped the same way:
 237
 238 root:/sys/bus/coresight/devices# echo 0 > 2201c000.ptm/enable_source
 239 root:/sys/bus/coresight/devices#
 240
 241 The content of the ETB buffer can be harvested directly from /dev:
 242
 243 root:/sys/bus/coresight/devices# dd if=/dev/20010000.etb \
 244 of=~/cstrace.bin
 245
 246 64+0 records in
 247 64+0 records out
 248 32768 bytes (33 kB) copied, 0.00125258 s, 26.2 MB/s
 249 root:/sys/bus/coresight/devices#
 250
 251 The file cstrace.bin can be decompressed using "ptm2human", DS-5 or Trace32.
 252
 253 Following is a DS-5 output of an experimental loop that increments a variable up
 254 to a certain value.  The example is simple and yet provides a glimpse of the
 255 wealth of possibilities that coresight provides.
 256
 257 Info                                    Tracing enabled
 258 Instruction     106378866       0x8026B53C      E52DE004        false   PUSH     {lr}
 259 Instruction     0       0x8026B540      E24DD00C        false   SUB      sp,sp,#0xc
 260 Instruction     0       0x8026B544      E3A03000        false   MOV      r3,#0
 261 Instruction     0       0x8026B548      E58D3004        false   STR      r3,[sp,#4]
 262 Instruction     0       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 Timestamp                                       Timestamp: 17106715833
 268 Instruction     319     0x8026B54C      E59D3004        false   LDR      r3,[sp,#4]
 269 Instruction     0       0x8026B550      E3530004        false   CMP      r3,#4
 270 Instruction     0       0x8026B554      E2833001        false   ADD      r3,r3,#1
 271 Instruction     0       0x8026B558      E58D3004        false   STR      r3,[sp,#4]
 272 Instruction     0       0x8026B55C      DAFFFFFA        true    BLE      {pc}-0x10 ; 0x8026b54c
 273 Instruction     9       0x8026B54C      E59D3004        false   LDR      r3,[sp,#4]
 274 Instruction     0       0x8026B550      E3530004        false   CMP      r3,#4
 275 Instruction     0       0x8026B554      E2833001        false   ADD      r3,r3,#1
 276 Instruction     0       0x8026B558      E58D3004        false   STR      r3,[sp,#4]
 277 Instruction     0       0x8026B55C      DAFFFFFA        true    BLE      {pc}-0x10 ; 0x8026b54c
 278 Instruction     7       0x8026B54C      E59D3004        false   LDR      r3,[sp,#4]
 279 Instruction     0       0x8026B550      E3530004        false   CMP      r3,#4
 280 Instruction     0       0x8026B554      E2833001        false   ADD      r3,r3,#1
 281 Instruction     0       0x8026B558      E58D3004        false   STR      r3,[sp,#4]
 282 Instruction     0       0x8026B55C      DAFFFFFA        true    BLE      {pc}-0x10 ; 0x8026b54c
 283 Instruction     7       0x8026B54C      E59D3004        false   LDR      r3,[sp,#4]
 284 Instruction     0       0x8026B550      E3530004        false   CMP      r3,#4
 285 Instruction     0       0x8026B554      E2833001        false   ADD      r3,r3,#1
 286 Instruction     0       0x8026B558      E58D3004        false   STR      r3,[sp,#4]
 287 Instruction     0       0x8026B55C      DAFFFFFA        true    BLE      {pc}-0x10 ; 0x8026b54c
 288 Instruction     10      0x8026B54C      E59D3004        false   LDR      r3,[sp,#4]
 289 Instruction     0       0x8026B550      E3530004        false   CMP      r3,#4
 290 Instruction     0       0x8026B554      E2833001        false   ADD      r3,r3,#1
 291 Instruction     0       0x8026B558      E58D3004        false   STR      r3,[sp,#4]
 292 Instruction     0       0x8026B55C      DAFFFFFA        true    BLE      {pc}-0x10 ; 0x8026b54c
 293 Instruction     6       0x8026B560      EE1D3F30        false   MRC      p15,#0x0,r3,c13,c0,#1
 294 Instruction     0       0x8026B564      E1A0100D        false   MOV      r1,sp
 295 Instruction     0       0x8026B568      E3C12D7F        false   BIC      r2,r1,#0x1fc0
 296 Instruction     0       0x8026B56C      E3C2203F        false   BIC      r2,r2,#0x3f
 297 Instruction     0       0x8026B570      E59D1004        false   LDR      r1,[sp,#4]
 298 Instruction     0       0x8026B574      E59F0010        false   LDR      r0,[pc,#16] ; [0x8026B58C] = 0x80550368
 299 Instruction     0       0x8026B578      E592200C        false   LDR      r2,[r2,#0xc]
 300 Instruction     0       0x8026B57C      E59221D0        false   LDR      r2,[r2,#0x1d0]
 301 Instruction     0       0x8026B580      EB07A4CF        true    BL       {pc}+0x1e9344 ; 0x804548c4
 302 Info                                    Tracing enabled
 303 Instruction     13570831        0x8026B584      E28DD00C        false   ADD      sp,sp,#0xc
 304 Instruction     0       0x8026B588      E8BD8000        true    LDM      sp!,{pc}
 305 Timestamp                                       Timestamp: 17107041535
 306
 307 2) Using perf framework:
 308
 309 Coresight tracers are represented using the Perf framework's Performance
 310 Monitoring Unit (PMU) abstraction.  As such the perf framework takes charge of
 311 controlling when tracing gets enabled based on when the process of interest is
 312 scheduled.  When configured in a system, Coresight PMUs will be listed when
 313 queried by the perf command line tool:
 314
 315         linaro@linaro-nano:~$ ./perf list pmu
 316
 317                 List of pre-defined events (to be used in -e):
 318
 319                 cs_etm//                                    [Kernel PMU event]
 320
 321         linaro@linaro-nano:~$
 322
 323 Regardless of the number of tracers available in a system (usually equal to the
 324 amount of processor cores), the "cs_etm" PMU will be listed only once.
 325
 326 A Coresight PMU works the same way as any other PMU, i.e the name of the PMU is
 327 listed along with configuration options within forward slashes '/'.  Since a
 328 Coresight system will typically have more than one sink, the name of the sink to
 329 work with needs to be specified as an event option.  Names for sink to choose
 330 from are listed in sysFS under ($SYSFS)/bus/coresight/devices:
 331
 332         root@linaro-nano:~# ls /sys/bus/coresight/devices/
 333                 20010000.etf   20040000.funnel  20100000.stm  22040000.etm
 334                 22140000.etm  230c0000.funnel  23240000.etm 20030000.tpiu
 335                 20070000.etr     20120000.replicator  220c0000.funnel
 336                 23040000.etm  23140000.etm     23340000.etm
 337
 338         root@linaro-nano:~# perf record -e cs_etm/@20070000.etr/u --per-thread program
 339
 340 The syntax within the forward slashes '/' is important.  The '@' character
 341 tells the parser that a sink is about to be specified and that this is the sink
 342 to use for the trace session.
 343
 344 More information on the above and other example on how to use Coresight with
 345 the perf tools can be found in the "HOWTO.md" file of the openCSD gitHub
 346 repository [3].
 347
 348 2.1) AutoFDO analysis using the perf tools:
 349
 350 perf can be used to record and analyze trace of programs.
 351
 352 Execution can be recorded using 'perf record' with the cs_etm event,
 353 specifying the name of the sink to record to, e.g:
 354
 355     perf record -e cs_etm/@20070000.etr/u --per-thread
 356
 357 The 'perf report' and 'perf script' commands can be used to analyze execution,
 358 synthesizing instruction and branch events from the instruction trace.
 359 'perf inject' can be used to replace the trace data with the synthesized events.
 360 The --itrace option controls the type and frequency of synthesized events
 361 (see perf documentation).
 362
 363 Note that only 64-bit programs are currently supported - further work is
 364 required to support instruction decode of 32-bit Arm programs.
 365
 366
 367 Generating coverage files for Feedback Directed Optimization: AutoFDO
 368 ---------------------------------------------------------------------
 369
 370 'perf inject' accepts the --itrace option in which case tracing data is
 371 removed and replaced with the synthesized events. e.g.
 372
 373         perf inject --itrace --strip -i perf.data -o perf.data.new
 374
 375 Below is an example of using ARM ETM for autoFDO.  It requires autofdo
 376 (https://github.com/google/autofdo) and gcc version 5.  The bubble
 377 sort example is from the AutoFDO tutorial (https://gcc.gnu.org/wiki/AutoFDO/Tutorial).
 378
 379         $ gcc-5 -O3 sort.c -o sort
 380         $ taskset -c 2 ./sort
 381         Bubble sorting array of 30000 elements
 382         5910 ms
 383
 384         $ perf record -e cs_etm/@20070000.etr/u --per-thread taskset -c 2 ./sort
 385         Bubble sorting array of 30000 elements
 386         12543 ms
 387         [ perf record: Woken up 35 times to write data ]
 388         [ perf record: Captured and wrote 69.640 MB perf.data ]
 389
 390         $ perf inject -i perf.data -o inj.data --itrace=il64 --strip
 391         $ create_gcov --binary=./sort --profile=inj.data --gcov=sort.gcov -gcov_version=1
 392         $ gcc-5 -O3 -fauto-profile=sort.gcov sort.c -o sort_autofdo
 393         $ taskset -c 2 ./sort_autofdo
 394         Bubble sorting array of 30000 elements
 395         5806 ms
 396
 397
 398 How to use the STM module
 399 -------------------------
 400
 401 Using the System Trace Macrocell module is the same as the tracers - the only
 402 difference is that clients are driving the trace capture rather
 403 than the program flow through the code.
 404
 405 As with any other CoreSight component, specifics about the STM tracer can be
 406 found in sysfs with more information on each entry being found in [1]:
 407
 408 root@genericarmv8:~# ls /sys/bus/coresight/devices/20100000.stm
 409 enable_source   hwevent_select  port_enable     subsystem       uevent
 410 hwevent_enable  mgmt            port_select     traceid
 411 root@genericarmv8:~#
 412
 413 Like any other source a sink needs to be identified and the STM enabled before
 414 being used:
 415
 416 root@genericarmv8:~# echo 1 > /sys/bus/coresight/devices/20010000.etf/enable_sink
 417 root@genericarmv8:~# echo 1 > /sys/bus/coresight/devices/20100000.stm/enable_source
 418
 419 From there user space applications can request and use channels using the devfs
 420 interface provided for that purpose by the generic STM API:
 421
 422 root@genericarmv8:~# ls -l /dev/20100000.stm
 423 crw-------    1 root     root       10,  61 Jan  3 18:11 /dev/20100000.stm
 424 root@genericarmv8:~#
 425
 426 Details on how to use the generic STM API can be found here [2].
 427
 428 [1]. Documentation/ABI/testing/sysfs-bus-coresight-devices-stm
 429 [2]. Documentation/trace/stm.rst
 430 [3]. https://github.com/Linaro/perf-opencsd