Commit 7ec55eb8 authored by David Brownell's avatar David Brownell Committed by Øyvind Harboe
Browse files

present CM3 Trace agenda

parent 94fa8fd3
+OpenOCD and CoreSight Tracing
+
Many recent ARM chips (Using e..g. Cortex-M3 and
Cortex-M4 cores) support CoreSight debug/trace.
This note sketches an approach currently planned for those cores
with OpenOCD.
This tracing data can help debug and tune ARM software, but not
all cores support tracing. Some support more extensive tracing
other cores with trace support +should be able to use the same
approach and maybe some of the same analysis code.
+the Cortex-M3 is assumed here to be the
+core in use, for simplicity and to reflect current OpenOCD users.
This note summarizes a software model to generate, collect, and
analyze such trace data . That is not fully implemented as of early
January 2011, +and thus is not *yet* usable.
+
+
+Some microcontroller cores support a low pin-count Single-wire trace,
with a mode where +trace data is emitted (usually to a UART. To use
this mode, +SWD must be in use.
+At this writing, OpenOCD SWD support is not yet complete either.
(There are also multi-wire trace ports requiring more complex debug
adapters than OpenOCD currently supports, and offering richer data.
+
+
+* ENABLING involves activating SWD and (single wire) trace.
+
+current expectations are that OpenOCD itself will handle enabling;
activating single wire trace involves a debug adapter interaction, and
collecting that trace data requires particular (re)wiring.
+
+* CONFIGURATION involves setting up ITM and/or ETM modules to emit the
+desired data from the Cortex core. (This might include dumping
+event counters printf-style messages; code profiling; and more. Not all
+cores offer the same trace capabilities.
+
+current expectations are that Tcl scripts will be used to configure these
+modules for the desired tracing, by direct writes to registers. In some
+cases (as with RTOS event tracking and similar messaging, this might
+be augmented or replaced by user code running on the ARM core.
+
+COLLECTION involves reading that trace data, probably through UART, and
+saving it in a useful format to analyse For now, deferred analysis modes
are assumed, not than real-time or interactive ones.
+
+
+current expectations are to to dump data in text using contrib/itmdump.c
+or derived tools, and to post-process it into reports. Such reports might
+include program messaging (such as application data streams via ITM, maybe
+using printf type messaging; code coverage analysis or so forth. Recent
+versions of CMSIS software reserve some ITM codespace for RTOS event
tracing and include ITM messaging support.
Clearly some of that data would be valuable for interactive debugging.
+
+Should someone get ambitious, GUI reports should be possible. GNU tools
+for simpler reports like gprof may be simpler to support at first.
+In any case, OpenOCD is not currently GUI-oriented. Accordingly, we now
+expect any such graphics to come from postprocessing.
measurments for RTOS event timings should also be easy to collect.
+Examples include context and message switch times, as well as times
for application interactions.
+
/*
* Copyright (C) 2010 by David Brownell
*
* This program is free software: you can redistribute it and/or modify
* it under the terms of the GNU General Public License as published by
* the Free Software Foundation, either version 3 of the License, or (at
* your option) any later version.
*
* This program is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
* GNU General Public License for more details.
*
* You should have received a copy of the GNU General Public License
* along with this program. If not, see <http://www.gnu.org/licenses/>.
*/
/*
* Simple utility to parse and dump ARM Cortex-M3 SWO trace output. Once the
* mechanisms work right, this information can be used for various purposes
* including profiling (particularly easy for flat PC-sample profiles) and
* for debugging.
*
* SWO is the Single Wire Output found on some ARM cores, most notably on the
* Cortex-M3. It combines data from several sources:
*
* - Software trace (ITM): so-called "printf-style" application messaging
* using "ITM stimulus ports"; and differential timestamps.
* - Hardware trace (DWT): for profiling counters and comparator matches.
* - TPIU may issue sync packets.
*
* The trace data format is defined in Appendix E, "Debug ITM and DWT packet
* protocol", of the ARMv7-M Architecture Reference Manual (DDI 0403C). It
* is a superset of the ITM data format from the Coresight TRM.
*
* The trace data has two encodings. The working assumption is that data
* gets into this program using the UART encoding.
*/
#include <errno.h>
#include <libgen.h>
#include <stdio.h>
#include <stdbool.h>
#include <string.h>
#include <unistd.h>
/* Example ITM trace word (0xWWXXYYZZ) parsing for task events, sent
* on port 31 (Reserved for "the" RTOS in CMSIS v1.30)
* WWXX: event code (0..3 pre-assigned, 4..15 reserved)
* YY: task priority
* ZZ: task number
*
* NOTE that this specific encoding could be space-optimized; and that
* trace data streams could also be history-sensitive.
*/
static void show_task(int port, unsigned data)
{
unsigned code = data >> 16;
char buf[16];
switch (code) {
case 0:
strcpy(buf, "run");
break;
case 1:
strcpy(buf, "block");
break;
case 2:
strcpy(buf, "create");
break;
case 3:
strcpy(buf, "destroy");
break;
/* 4..15 reserved for other infrastructure ops */
default:
sprintf(buf, "code %d", code);
break;
}
printf("TASK %d, pri %d: %s",
(data >> 0) & 0xff,
(data >> 8) & 0xff,
buf);
}
static void show_reserved(FILE *f, char *label, int c)
{
unsigned i;
printf("%s - %#02x", label, c);
for (i = 0; (c & 0x80) && i < 4; i++) {
c = fgetc(f);
if (c == EOF) {
printf("(ERROR %d - %s) ", errno, strerror(errno));
break;
}
printf(" %#02x", c);
}
printf("\n");
}
static bool read_varlen(FILE *f, int c, unsigned *value)
{
unsigned size;
unsigned char buf[4];
unsigned i;
*value = 0;
switch (c & 3) {
case 3:
size = 4;
break;
case 2:
size = 2;
break;
case 1:
size = 1;
break;
default:
printf("INVALID SIZE\n");
return false;
}
memset(buf, 0, sizeof buf);
if (fread(buf, 1, size, f) != size)
goto err;
*value = (buf[3] << 24)
+ (buf[2] << 16)
+ (buf[2] << 8)
+ (buf[0] << 0);
return true;
err:
printf("(ERROR %d - %s)\n", errno, strerror(errno));
return;
}
static void show_hard(FILE *f, int c)
{
unsigned type = c >> 3;
unsigned value;
unsigned size;
char *label;
printf("DWT - ", type);
if (!read_varlen(f, c, &value))
return;
printf("%#x", value);
switch (type) {
case 0: /* event counter wrapping */
printf("overflow %s%s%s%s%s%s",
(value & (1 << 5)) ? "cyc " : "",
(value & (1 << 4)) ? "fold " : "",
(value & (1 << 3)) ? "lsu " : "",
(value & (1 << 2)) ? "slp " : "",
(value & (1 << 1)) ? "exc " : "",
(value & (1 << 0)) ? "cpi " : "");
break;
case 1: /* exception tracing */
switch (value >> 12) {
case 1:
label = "entry to";
break;
case 2:
label = "exit from";
break;
case 3:
label = "return to";
break;
default:
label = "?";
break;
}
printf("%s exception %d", label, value & 0x1ff);
break;
case 2: /* PC sampling */
if (c == 0x15)
printf("PC - sleep");
else
printf("PC - %#08x", value);
break;
case 8: /* data tracing, pc value */
case 10:
case 12:
case 14:
printf("Data trace %d, PC %#08x", (c >> 4) & 3, value);
/* optionally followed by data value */
break;
case 9: /* data tracing, address offset */
case 11:
case 13:
case 15:
printf("Data trace %d, address offset %#04x",
(c >> 4) & 3, value);
/* always followed by data value */
break;
case 16 ... 23: /* data tracing, data value */
printf("Data trace %d, ", (c >> 4) & 3);
label = (c & 0x8) ? "write" : "read";
switch (c & 3) {
case 3:
printf("word %s, value %#08x", label, value);
break;
case 2:
printf("halfword %s, value %#04x", label, value);
break;
case 1:
printf("byte %s, value %#02x", label, value);
break;
}
break;
default:
printf("UNDEFINED");
break;
}
printf("\n");
return;
}
/*
* Table of SWIT (SoftWare InstrumentTation) message dump formats, for
* ITM port 0..31 application data.
*
* Eventually this should be customizable; all usage is application defined.
*
* REVISIT there can be up to 256 trace ports, via "ITM Extension" packets
*/
struct {
int port;
void (*show)(int port, unsigned data);
} format[] = {
{ .port = 31, .show = show_task, },
};
static void show_swit(FILE *f, int c)
{
unsigned size;
unsigned port = c >> 3;
unsigned char buf[4];
unsigned value = 0;
unsigned i;
printf("SWIT %u - ", port);
if (!read_varlen(f, c, &value))
return;
printf("%#08x", value);
for (i = 0; i <= sizeof(format) / sizeof(format[0]); i++) {
if (format[i].port == port) {
printf(", ");
format[i].show(port, value);
break;
}
}
printf("\n");
return;
err:
printf("(ERROR %d - %s)\n", errno, strerror(errno));
return;
}
static void show_timestamp(FILE *f, int c)
{
unsigned counter = 0;
char *label = "";
bool delayed = false;
printf("TIMESTAMP - ");
/* Format 2: header only */
if (!(c & 0x80)) {
switch (c) {
case 0: /* sync packet -- coding error! */
case 0x70: /* overflow -- ditto! */
printf("ERROR - %#02x\n", c);
break;
default:
/* synchronous to ITM */
counter = c >> 4;
goto done;
}
return;
}
/* Format 1: one to four bytes of data too */
switch (c) {
default:
label = ", reserved control\n";
break;
case 0xc:
/* synchronous to ITM */
break;
case 0xd:
label = ", timestamp delayed";
delayed = true;
break;
case 0xe:
label = ", packet delayed";
delayed = true;
break;
case 0xf:
label = ", packet and timetamp delayed";
delayed = true;
break;
}
c = fgetc(f);
if (c == EOF)
goto err;
counter = c & 0x7f;
if (!(c & 0x80))
goto done;
c = fgetc(f);
if (c == EOF)
goto err;
counter |= (c & 0x7f) << 7;
if (!(c & 0x80))
goto done;
c = fgetc(f);
if (c == EOF)
goto err;
counter |= (c & 0x7f) << 14;
if (!(c & 0x80))
goto done;
c = fgetc(f);
if (c == EOF)
goto err;
counter |= (c & 0x7f) << 21;
done:
/* REVISIT should we try to convert from delta values? */
printf("+%u%s\n", counter, label);
return;
err:
printf("(ERROR %d - %s) ", errno, strerror(errno));
goto done;
}
int main(int argc, char **argv)
{
FILE *f = stdin;
int c;
/* parse arguments */
while ((c = getopt(argc, argv, "f:")) != EOF) {
switch (c) {
case 'f':
/* e.g. from UART connected to /dev/ttyUSB0 */
f = fopen(optarg, "r");
if (!f) {
perror(optarg);
return 1;
}
break;
default:
usage:
fprintf(stderr, "usage: %s [-f input]",
basename(argv[0]));
return 1;
}
}
/* Parse data ... records have a header then data bytes.
* NOTE: we assume getc() deals in 8-bit bytes.
*/
bool overflow = false;
while ((c = getc(f)) != EOF) {
/* Sync packet ... 7 zeroes, 0x80 */
if (c == 0) {
int i;
for (i = 0; i < 6; i++) {
c = fgetc(f);
if (c == EOF)
break;
if (c != 0)
goto bad_sync;
}
c = fgetc(f);
if (c == 0x80) {
printf("SYNC\n");
continue;
}
bad_sync:
printf("BAD SYNC\n");
continue;
}
/* Overflow packet */
if (c == 0x70) {
/* REVISIT later, report just what overflowed!
* Timestamp and SWIT can happen. Non-ITM too?
*/
overflow = true;
printf("OVERFLOW ...\n");
continue;
}
overflow = false;
switch (c & 0x0f) {
case 0x00: /* Timestamp */
show_timestamp(f, c);
break;
case 0x04: /* "Reserved" */
show_reserved(f, "RESERVED", c);
break;
case 0x08: /* ITM Extension */
/* FIXME someday, handle these ... */
show_reserved(f, "ITM EXT", c);
break;
case 0x0c: /* DWT Extension */
show_reserved(f, "DWT EXT", c);
break;
default:
if (c & 4)
show_hard(f, c);
else
show_swit(f, c);
break;
}
}
return 0;
}
Supports Markdown
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment