trc_pkt_lister - Man Page

decodes captured CoreSight® trace from a trace snapshot directory.

trc_pkt_lister is a tool that takes a snapshot directory as an input, and lists and/or decodes all the trace packets from a given trace sink, for any source in that sink where the protocol is supported.

The output will be a list of discrete packets, generic output packets and any error messages to file and/or screen as selected by the input command line options.

By default the program will list packets only (no decode), for the first discovered trace sink (ETB, ETF, ETR) in the snapshot directory, with all source streams output.

Options

Snapshot selection

The program defaults to ./. if no -ss_dir option is given

-ss_dir <dir>: Set the directory path to a trace snapshot.
-ss_verbose: Verbose output when reading the snapshot.

Decode options

-id <n>: Set a trace ID to list (may be used multiple times). Default if no id set is for all IDs to be printed.
-src_name <name>: List packets from a given snapshot source name (defaults to first source found).
-multi_session: Decode all buffers listed in snapshot under buffers key in trace.ini.
Uses config of first buffer to decode all. Ignored if -src_name is used.
-dstream_format: Input is DSTREAM framed.
-tpiu: Input data is from a TPIU source that has TPIU FSYNC packets present.
-tpiu_hsync: Input data is from a TPIU source that has both TPIU FSYNC and HSYNC packets present.
-decode: Full decode of the packets from the trace snapshot (default is to list undecoded packets only).
-decode_only: Does not list the undecoded packets, just the trace decode.
-src_addr_n: In ETE protocol, indicate skipped N atoms in source address packet ranges by breaking the decode range into multiple ranges on N atoms.
-o_raw_packed: Output raw packed trace frames.
-o_raw_unpacked: Output raw unpacked trace data per ID.-
-stats: Output packet processing statistics (if available).

Consistency checks

-aa64_opcode_chk: Check for correct AA64 opcodes (MSW != 0x0000)
-direct_br_cond: Check for incorrect N atom on direct unconditional branches
-strict_br_cond: Strict conditional checks - look for incorrect N atom on all unconditional branches.
-range_cont: Range continuity checks - check next range after N atom is continuous.
-halt_err: Halt on bad packet error (default attempts to resync).

Output options

Default is to output to file and stdout. Setting any option overrides and limits to only the options set.

-logstdout: output to stdout.
-logstderr: output to stderr.
-logfile: output to file using the default log file name.
-logfilename <name>: change the name of the output log file.

Files

Trace Snapshot directory.

The ./tests/snapshots directory contains a number of trace snapshots used for testing the library. Trace snapshots are dumps of captured binary trace data, CoreSight component configurations and memory dumps to allow trace decode.

Snapshots are generated on ARM targets and can then be analysed offline. The snapshot format is available in a separate document.

Examples

Example command lines with short output excerpts.

TC2 : ETMv3 packet processor output, raw packet output.

Command line:
trc_pkt_lister -ss_dir ../../snapshots/TC2 -o_raw_unpacked

Output:

Frame Data; Index  17958; ID_DATA[0x11]; 16 04 c0 86 42 97 e1 c4 
Idx:17945; ID:11;	I_SYNC : Instruction Packet synchronisation.; (Periodic); Addr=0xc00
416e2; S;  ISA=Thumb2; 
Idx:17961; ID:11;	P_HDR : Atom P-header.; WEN; Cycles=1
Frame Data; Index  17968; ID_DATA[0x11]; ce af 90 80 80 00 a4 84 a0 84 a4 88 
Idx:17962; ID:11;	TIMESTAMP : Timestamp Value.; TS=0x82f9d13097 (562536984727) 
Idx:17974; ID:11;	P_HDR : Atom P-header.; WW; Cycles=2

Juno :
ETB_1 selected which contains STM source output, plus raw packet output

Command line: trc_pkt_lister -ss_dir ../../snapshots/juno_r1_1 -o_raw_unpacked -src_name ETB_1

Output

Trace Packet Lister : STM Protocol on Trace ID 0x20
Frame Data; Index      0; ID_DATA[0x20]; ff ff ff ff ff ff ff ff ff ff 0f 0f 30 41 
Idx:0; ID:20;	ASYNC:Alignment synchronisation packet.
Idx:11; ID:20;	VERSION:Version packet.; Ver=3
Frame Data; Index     16; ID_DATA[0x20]; f1 1a 00 00 00 30 10 af 01 00 00 10 03 f2 1a 
Idx:13; ID:20;	M8:Set current master.; Master=0x41
Idx:17; ID:20;	D32M:32 bit data; with marker.; Data=0x10000000
Idx:22; ID:20;	C8:Set current channel.; Chan=0x0001

Juno : ETMv4 full trace decode + packet monitor, source trace ID 0x10 only.

Command line:
trc_pkt_lister -ss_dir ../../snapshots/juno_r1_1 -decode -id 0x10