aboutsummaryrefslogtreecommitdiff
path: root/doc
diff options
context:
space:
mode:
authordbrownell <dbrownell@b42882b7-edfa-0310-969c-e2dbd0fdcd60>2009-09-23 21:52:40 +0000
committerdbrownell <dbrownell@b42882b7-edfa-0310-969c-e2dbd0fdcd60>2009-09-23 21:52:40 +0000
commit22045fa6f28813f9e7b17c052f4c7a6c8355178d (patch)
tree4c02321d98f6b7ecba3b4ed7416f08be914ff289 /doc
parentd9ce8a2f60ece3b98a6d99b0e5aff8d4adef29fa (diff)
downloadriscv-openocd-22045fa6f28813f9e7b17c052f4c7a6c8355178d.zip
riscv-openocd-22045fa6f28813f9e7b17c052f4c7a6c8355178d.tar.gz
riscv-openocd-22045fa6f28813f9e7b17c052f4c7a6c8355178d.tar.bz2
When setting up an ETM, cache its ETM_CONFIG register. Then
only expose the registers which are actually present. They could be missing for two basic reasons: - This version might not support them at all; e.g. ETMv1.1 doesn't have some control/status registers. (My sample of ARM9 boards shows all with ETMv1.3 support, FWIW.) - The configuration on this chip may not populate as many registers as possible; e.g. only two data value comparators instead of eight. Includes a bugfix in the "etm info" command: only one of the two registers is missing on older silicon, so show the first one before bailing. Update ETM usage docs to explain that those registers need to be written to configure what is traced, and that some ETM configs are not yet handled. Also, give some examples of the kinds of constrained trace which could be arranged. git-svn-id: svn://svn.berlios.de/openocd/trunk@2752 b42882b7-edfa-0310-969c-e2dbd0fdcd60
Diffstat (limited to 'doc')
-rw-r--r--doc/openocd.texi40
1 files changed, 38 insertions, 2 deletions
diff --git a/doc/openocd.texi b/doc/openocd.texi
index 893d738..35c1b0d 100644
--- a/doc/openocd.texi
+++ b/doc/openocd.texi
@@ -4807,6 +4807,10 @@ analyse it in conjunction with the source code.
It's unclear how much of a common interface is shared
with the current XScale trace support, or should be
shared with eventual Nexus-style trace module support.
+At this writing (September 2009) only ARM7 and ARM9 support
+for ETM modules is available. The code should be able to
+work with some newer cores; but not all of them support
+this original style of JTAG access.
@end quotation
@subsection ETM Configuration
@@ -4823,8 +4827,10 @@ or @option{demultiplexted}.
The @var{clocking} must be @option{half} or @option{full}.
@quotation Note
-You can see the ETM registers using the @command{reg} command, although
-not all of those possible registers are present in every ETM.
+You can see the ETM registers using the @command{reg} command.
+Not all possible registers are present in every ETM.
+Most of the registers are write-only, and are used to configure
+what CPU activities are traced.
@end quotation
@end deffn
@@ -4867,6 +4873,36 @@ After setting up the ETM, you can use it to collect data.
That data can be exported to files for later analysis.
It can also be parsed with OpenOCD, for basic sanity checking.
+To configure what is being traced, you will need to write
+various trace registers using @command{reg ETM_*} commands.
+For the definitions of these registers, read ARM publication
+@emph{IHI 0014, ``Embedded Trace Macrocell, Architecture Specification''}.
+Be aware that most of the relevant registers are write-only,
+and that ETM resources are limited. There are only a handful
+of address comparators, data comparators, counters, and so on.
+
+Examples of scenarios you might arrange to trace include:
+
+@itemize
+@item Code flow within a function, @emph{excluding} subroutines
+it calls. Use address range comparators to enable tracing
+for instruction access within that function's body.
+@item Code flow within a function, @emph{including} subroutines
+it calls. Use the sequencer and address comparators to activate
+tracing on an ``entered function'' state, then deactivate it by
+exiting that state when the function's exit code is invoked.
+@item Code flow starting at the fifth invocation of a function,
+combining one of the above models with a counter.
+@item CPU data accesses to the registers for a particular device,
+using address range comparators and the ViewData logic.
+@item Such data accesses only during IRQ handling, combining the above
+model with sequencer triggers which on entry and exit to the IRQ handler.
+@item @emph{... more}
+@end itemize
+
+At this writing, September 2009, there are no Tcl utility
+procedures to help set up any common tracing scenarios.
+
@deffn Command {etm analyze}
Reads trace data into memory, if it wasn't already present.
Decodes and prints the data that was collected.