tcl/board: Add config for the Amazon Kindle 2 and DX
[openocd.git] / contrib / coresight-trace.txt
1 +OpenOCD and CoreSight Tracing
2 +
3 Many recent ARM chips  (Using e..g. Cortex-M3 and
4 Cortex-M4 cores) support CoreSight debug/trace.
5 This note sketches an approach currently planned for those cores
6 with OpenOCD.
7
8  This tracing data can help debug and tune ARM software, but not
9 all cores support tracing.  Some support more extensive tracing
10 other cores with trace support +should be able to use the same
11 approach and maybe some of the same analysis code.
12
13 +the Cortex-M3 is assumed here to be the
14 +core in use, for simplicity and to reflect current OpenOCD users.
15
16
17 This note summarizes a software model to generate, collect, and
18 analyze such trace data .  That is not fully implemented as of early
19 January 2011, +and thus is not *yet* usable.
20 +
21 +
22 +Some microcontroller cores support a low pin-count Single-wire trace,
23 with a mode where +trace data is emitted (usually to a UART.  To use
24 this mode, +SWD must be in use.
25 +At this writing, OpenOCD SWD support is not yet complete either.
26
27 (There are also multi-wire trace ports requiring more complex debug
28 adapters than OpenOCD currently supports, and offering richer data.
29 +
30 +
31 +* ENABLING involves activating  SWD and (single wire) trace.
32 +
33 +current expectations are that OpenOCD itself will handle enabling;
34 activating single wire trace involves a debug adapter interaction, and
35 collecting that trace data requires particular (re)wiring.
36 +
37 +* CONFIGURATION involves setting up ITM  and/or ETM modules to emit the
38 +desired data from the Cortex core.  (This might include dumping
39 +event counters printf-style messages; code profiling; and more.  Not all
40 +cores offer the same trace capabilities.
41 +
42 +current expectations are that Tcl scripts will be used to configure these
43 +modules for the desired tracing, by direct writes to registers.  In some
44 +cases (as with RTOS event tracking and similar messaging, this might
45 +be  augmented or replaced by user code running on the ARM core.
46 +
47 +COLLECTION involves reading that trace data, probably through UART, and
48 +saving it in a useful format to analyse  For now, deferred analysis modes
49 are assumed, not than real-time or interactive ones.
50 +
51 +
52 +current expectations are to to dump data in text using contrib/itmdump.c
53 +or derived tools, and to post-process it into reports.  Such reports might
54 +include program messaging (such as application data streams via ITM, maybe
55 +using printf type messaging; code coverage analysis or so forth.  Recent
56 +versions of CMSIS software reserve some ITM codespace for RTOS  event
57 tracing and include ITM messaging support.
58 Clearly some of that data would be valuable for interactive debugging.
59 +
60 +Should someone get ambitious, GUI reports should be possible.  GNU tools
61 +for simpler reports like gprof may be simpler to support at first.
62 +In any case, OpenOCD is not currently GUI-oriented.  Accordingly, we now
63 +expect any such graphics to come from postprocessing.
64
65  measurments for RTOS event timings should also be easy to collect.
66 +Examples include context and message switch times, as well as times
67 for application interactions.
68 +