blob: 0a5c3290e7324f09ab01dac65f6825d22e35ea09 [file] [log] [blame]
Mathieu Poirier872234d2014-11-03 11:07:42 -07001 Coresight - HW Assisted Tracing on ARM
2 ======================================
3
4 Author: Mathieu Poirier <mathieu.poirier@linaro.org>
5 Date: September 11th, 2014
6
7Introduction
8------------
9
10Coresight is an umbrella of technologies allowing for the debugging of ARM
11based SoC. It includes solutions for JTAG and HW assisted tracing. This
12document is concerned with the latter.
13
14HW assisted tracing is becoming increasingly useful when dealing with systems
15that have many SoCs and other components like GPU and DMA engines. ARM has
16developed a HW assisted tracing solution by means of different components, each
Mathieu Poirierb29d5c12015-03-30 14:13:37 -060017being added to a design at synthesis time to cater to specific tracing needs.
Masanari Iidaf8b66fe2015-07-31 09:37:29 -060018Components are generally categorised as source, link and sinks and are
Mathieu Poirier872234d2014-11-03 11:07:42 -070019(usually) discovered using the AMBA bus.
20
21"Sources" generate a compressed stream representing the processor instruction
22path based on tracing scenarios as configured by users. From there the stream
23flows through the coresight system (via ATB bus) using links that are connecting
24the emanating source to a sink(s). Sinks serve as endpoints to the coresight
25implementation, either storing the compressed stream in a memory buffer or
26creating an interface to the outside world where data can be transferred to a
27host without fear of filling up the onboard coresight memory buffer.
28
29At 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 *****************************************************************<-|
Kaixu Xia7af87922015-01-26 09:22:21 -070049 *************************** AMBA Debug APB ************************
Mathieu Poirier872234d2014-11-03 11:07:42 -070050 *****************************************************************
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
Kaixu Xia7af87922015-01-26 09:22:21 -070082While on target configuration of the components is done via the APB bus,
Mathieu Poirier872234d2014-11-03 11:07:42 -070083all trace data are carried out-of-band on the ATB bus. The CTM provides
84a way to aggregate and distribute signals between CoreSight components.
85
86The coresight framework provides a central point to represent, configure and
87manage coresight devices on a platform. This first implementation centers on
88the basic tracing functionality, enabling components such ETM/PTM, funnel,
89replicator, TMC, TPIU and ETB. Future work will enable more
90intricate IP blocks such as STM and CTI.
91
92
93Acronyms and Classification
94---------------------------
95
96Acronyms:
97
98PTM: Program Trace Macrocell
99ETM: Embedded Trace Macrocell
100STM: System trace Macrocell
101ETB: Embedded Trace Buffer
102ITM: Instrumentation Trace Macrocell
103TPIU: Trace Port Interface Unit
104TMC-ETR: Trace Memory Controller, configured as Embedded Trace Router
105TMC-ETF: Trace Memory Controller, configured as Embedded Trace FIFO
106CTI: Cross Trigger Interface
107
108Classification:
109
110Source:
111 ETMv3.x ETMv4, PTMv1.0, PTMv1.1, STM, STM500, ITM
112Link:
113 Funnel, replicator (intelligent or not), TMC-ETR
114Sinks:
115 ETBv1.0, ETB1.1, TPIU, TMC-ETF
116Misc:
117 CTI
118
119
120Device Tree Bindings
121----------------------
122
123See Documentation/devicetree/bindings/arm/coresight.txt for details.
124
125As of this writing drivers for ITM, STMs and CTIs are not provided but are
126expected to be added as the solution matures.
127
128
129Framework and implementation
130----------------------------
131
132The coresight framework provides a central point to represent, configure and
133manage coresight devices on a platform. Any coresight compliant device can
134register with the framework for as long as they use the right APIs:
135
136struct coresight_device *coresight_register(struct coresight_desc *desc);
137void coresight_unregister(struct coresight_device *csdev);
138
139The registering function is taking a "struct coresight_device *csdev" and
140register the device with the core framework. The unregister function takes
Masanari Iidaf8b66fe2015-07-31 09:37:29 -0600141a reference to a "struct coresight_device", obtained at registration time.
Mathieu Poirier872234d2014-11-03 11:07:42 -0700142
143If everything goes well during the registration process the new devices will
144show up under /sys/bus/coresight/devices, as showns here for a TC2 platform:
145
146root:~# ls /sys/bus/coresight/devices/
147replicator 20030000.tpiu 2201c000.ptm 2203c000.etm 2203e000.etm
14820010000.etb 20040000.funnel 2201d000.ptm 2203d000.etm
149root:~#
150
151The functions take a "struct coresight_device", which looks like this:
152
153struct 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
163The "coresight_dev_type" identifies what the device is, i.e, source link or
164sink while the "coresight_dev_subtype" will characterise that type further.
165
166The "struct coresight_ops" is mandatory and will tell the framework how to
167perform base operations related to the components, each component having
168a different set of requirement. For that "struct coresight_ops_sink",
169"struct coresight_ops_link" and "struct coresight_ops_source" have been
170provided.
171
172The 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
176static int etm_probe(struct amba_device *adev, const struct amba_id *id)
177{
178 ...
179 ...
180 drvdata->dev = &adev->dev;
181 ...
182}
183
184Specific class of device (source, link, or sink) have generic operations
185that can be performed on them (see "struct coresight_ops"). The
186"**groups" is a list of sysfs entries pertaining to operations
187specific to that component only. "Implementation defined" customisations are
188expected to be accessed and controlled using those entries.
189
190Last but not least, "struct module *owner" is expected to be set to reflect
191the information carried in "THIS_MODULE".
192
193How to use
194----------
195
196Before trace collection can start, a coresight sink needs to be identify.
197There is no limit on the amount of sinks (nor sources) that can be enabled at
198any given moment. As a generic operation, all device pertaining to the sink
199class will have an "active" entry in sysfs:
200
201root:/sys/bus/coresight/devices# ls
202replicator 20030000.tpiu 2201c000.ptm 2203c000.etm 2203e000.etm
20320010000.etb 20040000.funnel 2201d000.ptm 2203d000.etm
204root:/sys/bus/coresight/devices# ls 20010000.etb
205enable_sink status trigger_cntr
206root:/sys/bus/coresight/devices# echo 1 > 20010000.etb/enable_sink
207root:/sys/bus/coresight/devices# cat 20010000.etb/enable_sink
2081
209root:/sys/bus/coresight/devices#
210
211At boot time the current etm3x driver will configure the first address
212comparator with "_stext" and "_etext", essentially tracing any instruction
213that falls within that range. As such "enabling" a source will immediately
214trigger a trace capture:
215
216root:/sys/bus/coresight/devices# echo 1 > 2201c000.ptm/enable_source
217root:/sys/bus/coresight/devices# cat 2201c000.ptm/enable_source
2181
219root:/sys/bus/coresight/devices# cat 20010000.etb/status
220Depth: 0x2000
221Status: 0x1
222RAM read ptr: 0x0
223RAM wrt ptr: 0x19d3 <----- The write pointer is moving
224Trigger cnt: 0x0
225Control: 0x1
226Flush status: 0x0
227Flush ctrl: 0x2001
228root:/sys/bus/coresight/devices#
229
230Trace collection is stopped the same way:
231
232root:/sys/bus/coresight/devices# echo 0 > 2201c000.ptm/enable_source
233root:/sys/bus/coresight/devices#
234
235The content of the ETB buffer can be harvested directly from /dev:
236
237root:/sys/bus/coresight/devices# dd if=/dev/20010000.etb \
238of=~/cstrace.bin
239
24064+0 records in
24164+0 records out
24232768 bytes (33 kB) copied, 0.00125258 s, 26.2 MB/s
243root:/sys/bus/coresight/devices#
244
245The file cstrace.bin can be decompressed using "ptm2human", DS-5 or Trace32.
246
247Following is a DS-5 output of an experimental loop that increments a variable up
248to a certain value. The example is simple and yet provides a glimpse of the
249wealth of possibilities that coresight provides.
250
251Info Tracing enabled
252Instruction 106378866 0x8026B53C E52DE004 false PUSH {lr}
253Instruction 0 0x8026B540 E24DD00C false SUB sp,sp,#0xc
254Instruction 0 0x8026B544 E3A03000 false MOV r3,#0
255Instruction 0 0x8026B548 E58D3004 false STR r3,[sp,#4]
256Instruction 0 0x8026B54C E59D3004 false LDR r3,[sp,#4]
257Instruction 0 0x8026B550 E3530004 false CMP r3,#4
258Instruction 0 0x8026B554 E2833001 false ADD r3,r3,#1
259Instruction 0 0x8026B558 E58D3004 false STR r3,[sp,#4]
260Instruction 0 0x8026B55C DAFFFFFA true BLE {pc}-0x10 ; 0x8026b54c
261Timestamp Timestamp: 17106715833
262Instruction 319 0x8026B54C E59D3004 false LDR r3,[sp,#4]
263Instruction 0 0x8026B550 E3530004 false CMP r3,#4
264Instruction 0 0x8026B554 E2833001 false ADD r3,r3,#1
265Instruction 0 0x8026B558 E58D3004 false STR r3,[sp,#4]
266Instruction 0 0x8026B55C DAFFFFFA true BLE {pc}-0x10 ; 0x8026b54c
267Instruction 9 0x8026B54C E59D3004 false LDR r3,[sp,#4]
268Instruction 0 0x8026B550 E3530004 false CMP r3,#4
269Instruction 0 0x8026B554 E2833001 false ADD r3,r3,#1
270Instruction 0 0x8026B558 E58D3004 false STR r3,[sp,#4]
271Instruction 0 0x8026B55C DAFFFFFA true BLE {pc}-0x10 ; 0x8026b54c
272Instruction 7 0x8026B54C E59D3004 false LDR r3,[sp,#4]
273Instruction 0 0x8026B550 E3530004 false CMP r3,#4
274Instruction 0 0x8026B554 E2833001 false ADD r3,r3,#1
275Instruction 0 0x8026B558 E58D3004 false STR r3,[sp,#4]
276Instruction 0 0x8026B55C DAFFFFFA true BLE {pc}-0x10 ; 0x8026b54c
277Instruction 7 0x8026B54C E59D3004 false LDR r3,[sp,#4]
278Instruction 0 0x8026B550 E3530004 false CMP r3,#4
279Instruction 0 0x8026B554 E2833001 false ADD r3,r3,#1
280Instruction 0 0x8026B558 E58D3004 false STR r3,[sp,#4]
281Instruction 0 0x8026B55C DAFFFFFA true BLE {pc}-0x10 ; 0x8026b54c
282Instruction 10 0x8026B54C E59D3004 false LDR r3,[sp,#4]
283Instruction 0 0x8026B550 E3530004 false CMP r3,#4
284Instruction 0 0x8026B554 E2833001 false ADD r3,r3,#1
285Instruction 0 0x8026B558 E58D3004 false STR r3,[sp,#4]
286Instruction 0 0x8026B55C DAFFFFFA true BLE {pc}-0x10 ; 0x8026b54c
287Instruction 6 0x8026B560 EE1D3F30 false MRC p15,#0x0,r3,c13,c0,#1
288Instruction 0 0x8026B564 E1A0100D false MOV r1,sp
289Instruction 0 0x8026B568 E3C12D7F false BIC r2,r1,#0x1fc0
290Instruction 0 0x8026B56C E3C2203F false BIC r2,r2,#0x3f
291Instruction 0 0x8026B570 E59D1004 false LDR r1,[sp,#4]
292Instruction 0 0x8026B574 E59F0010 false LDR r0,[pc,#16] ; [0x8026B58C] = 0x80550368
293Instruction 0 0x8026B578 E592200C false LDR r2,[r2,#0xc]
294Instruction 0 0x8026B57C E59221D0 false LDR r2,[r2,#0x1d0]
295Instruction 0 0x8026B580 EB07A4CF true BL {pc}+0x1e9344 ; 0x804548c4
296Info Tracing enabled
297Instruction 13570831 0x8026B584 E28DD00C false ADD sp,sp,#0xc
298Instruction 0 0x8026B588 E8BD8000 true LDM sp!,{pc}
299Timestamp Timestamp: 17107041535