1 Test Programs {#test_progs}
4 @brief A description of the test programs used with the library.
9 There are currently two test programs built alongside the library.
11 1. `trc_pkt_lister` : This test the C++ library by taking a trace "snapshot" directory as an input
12 and decodes all or a chosen set of trace sources from within the trace data buffers in the library. Command
13 line parameters allow the test program to be controlled.
15 2. `c_api_pkt_print_test` : This program tests the "C" API functions, using hardcoded tests
16 based on the same "snapshots" used for the C++ library. Limited user control for this program.
17 This can also run tests using the external test decoder to validate the external decoder API.
18 See [external_custom.md](@ref custom_decoders) for details.
20 These programs are both built at the same time as the library for the same set of platforms.
21 See [build_libs.md](@ref build_lib) for build details.
23 _Note:_ The programs above use the library's [core name mapper helper class] (@ref CoreArchProfileMap) to map
24 the name of the core into a profile / architecture pair that the library can use.
25 The snapshot definition must use one of the names recognised by this class or an error will occur.
27 Trace "Snapshot" directory.
28 ----------------------------
30 The `.\tests\snapshots` directory contains a number of trace snapshots used for testing the library.
31 Trace snapshots are dumps of captured binary trace data, CoreSight component configurations and memory
32 dumps to allow trace decode.
34 Snapshots are generated on ARM targets and can then be analysed offline. The snapshot format is available
35 in a separate document.
37 The `trc_pkt_lister` program.
38 -----------------------------
40 This will take a snapshot directory as an input, and list and/or decode all the trace packets for a
41 single source, for any currently supported protocol.
43 The output will be a list of discrete packets, generic output packets and any error messages
44 to file and/or screen as selected by the input command line options.
46 By default the program will list packets only (no decode), for the first discovered trace sink
47 (ETB, ETF, ETR) in the snapshot directory, with all streams output.
49 __Command Line Options__
53 - `-ss_dir <dir>` : Set the directory path to a trace snapshot.
54 - `-ss_verbose` : Verbose output when reading the snapshot.
58 - `-id <n>` : Set an ID to list (may be used multiple times) - default if no id set is for all IDs to be printed.
59 - `-src_name <name>` : List packets from a given snapshot source name (defaults to first source found).
60 - `-tpiu` : Input data is from a TPIU source that has TPIU FSYNC packets present.
61 - `-tpiu_hsync` : Input data is from a TPIU source that has both TPIU FSYNC and HSYNC packets present.
62 - `-decode` : Full decode of the packets from the trace snapshot (default is to list undecoded packets only.
63 - `-decode_only` : Does not list the undecoded packets, just the trace decode.
64 - `-o_raw_packed` : Output raw packed trace frames.
65 - `-o_raw_unpacked` : Output raw unpacked trace data per ID.
69 Default is to output to file and stdout. Setting any option overrides and limits to only
71 - `-logstdout` : output to stdout.
72 - `-logstderr` : output to stderr.
73 - `-logfile` : output to file using the default log file name.
74 - `-logfilename <name>` : change the name of the output log file.
77 __Test output examples__
79 Example command lines with short output excerpts.
81 *TC2, ETMv3 packet processor output, raw packet output.*
84 `trc_pkt_lister -ss_dir ..\..\..\snapshots\TC2 -o_raw_unpacked`
87 Frame Data; Index 17958; ID_DATA[0x11]; 16 04 c0 86 42 97 e1 c4
88 Idx:17945; ID:11; I_SYNC : Instruction Packet synchronisation.; (Periodic); Addr=0xc00416e2; S; ISA=Thumb2;
89 Idx:17961; ID:11; P_HDR : Atom P-header.; WEN; Cycles=1
90 Frame Data; Index 17968; ID_DATA[0x11]; ce af 90 80 80 00 a4 84 a0 84 a4 88
91 Idx:17962; ID:11; TIMESTAMP : Timestamp Value.; TS=0x82f9d13097 (562536984727)
92 Idx:17974; ID:11; P_HDR : Atom P-header.; WW; Cycles=2
93 Idx:17975; ID:11; P_HDR : Atom P-header.; WE; Cycles=1
94 Idx:17976; ID:11; P_HDR : Atom P-header.; W; Cycles=1
95 Idx:17977; ID:11; P_HDR : Atom P-header.; WE; Cycles=1
96 Idx:17978; ID:11; P_HDR : Atom P-header.; WW; Cycles=2
97 Idx:17979; ID:11; P_HDR : Atom P-header.; WEWE; Cycles=2
98 Frame Data; Index 17980; ID_DATA[0x10]; a0 82
99 Idx:17980; ID:10; P_HDR : Atom P-header.; W; Cycles=1
100 Idx:17981; ID:10; P_HDR : Atom P-header.; WEE; Cycles=1
101 Frame Data; Index 17984; ID_DATA[0x10]; b8 84 a4 88 a0 82
102 Idx:17984; ID:10; P_HDR : Atom P-header.; WWWWWWW; Cycles=7
103 Idx:17985; ID:10; P_HDR : Atom P-header.; WE; Cycles=1
104 Idx:17986; ID:10; P_HDR : Atom P-header.; WW; Cycles=2
105 Idx:17987; ID:10; P_HDR : Atom P-header.; WEWE; Cycles=2
106 Idx:17988; ID:10; P_HDR : Atom P-header.; W; Cycles=1
107 Idx:17989; ID:10; P_HDR : Atom P-header.; WEE; Cycles=1
110 *Juno - ETB_1 selected for STM packet output, raw packet output*
113 `trc_pkt_lister -ss_dir ..\..\..\snapshots\juno_r1_1 -o_raw_unpacked -src_name ETB_1`
116 Trace Packet Lister: CS Decode library testing
117 -----------------------------------------------
119 Trace Packet Lister : reading snapshot from path ..\..\..\snapshots\juno_r1_1
120 Using ETB_1 as trace source
121 Trace Packet Lister : STM Protocol on Trace ID 0x20
122 Frame Data; Index 0; ID_DATA[0x20]; ff ff ff ff ff ff ff ff ff ff 0f 0f 30 41
123 Idx:0; ID:20; ASYNC:Alignment synchronisation packet.
124 Idx:11; ID:20; VERSION:Version packet.; Ver=3
125 Frame Data; Index 16; ID_DATA[0x20]; f1 1a 00 00 00 30 10 af 01 00 00 10 03 f2 1a
126 Idx:13; ID:20; M8:Set current master.; Master=0x41
127 Idx:17; ID:20; D32M:32 bit data; with marker.; Data=0x10000000
128 Idx:22; ID:20; C8:Set current channel.; Chan=0x0001
129 Idx:23; ID:20; D32M:32 bit data; with marker.; Data=0x10000001
130 Idx:28; ID:20; C8:Set current channel.; Chan=0x0002
131 Frame Data; Index 32; ID_DATA[0x20]; 00 00 00 32 30 af 01 00 00 30 03 f4 1a 00 00
132 Idx:30; ID:20; D32M:32 bit data; with marker.; Data=0x10000002
133 Idx:36; ID:20; C8:Set current channel.; Chan=0x0003
134 Idx:37; ID:20; D32M:32 bit data; with marker.; Data=0x10000003
135 Idx:42; ID:20; C8:Set current channel.; Chan=0x0004
136 Frame Data; Index 48; ID_DATA[0x20]; 00 f4 ff ff ff ff ff ff ff ff ff ff f0 00 13
137 Idx:44; ID:20; D32M:32 bit data; with marker.; Data=0x10000004
138 Idx:50; ID:20; ASYNC:Alignment synchronisation packet.
139 Idx:61; ID:20; VERSION:Version packet.; Ver=3
142 *Juno - ETMv4 full trace decode + packet monitor, source trace ID 0x10 only.*
145 `trc_pkt_lister -ss_dir ..\..\..\snapshots\juno_r1_1 -decode -id 0x10`
149 Idx:17204; ID:10; [0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x80 ]; I_ASYNC : Alignment Synchronisation.
150 Idx:17218; ID:10; [0x01 0x01 0x00 ]; I_TRACE_INFO : Trace Info.; INFO=0x0
151 Idx:17221; ID:10; [0x9d 0x00 0x35 0x09 0x00 0xc0 0xff 0xff 0xff ]; I_ADDR_L_64IS0 : Address, Long, 64 bit, IS0.; Addr=0xFFFFFFC000096A00;
152 Idx:17230; ID:10; [0x04 ]; I_TRACE_ON : Trace On.
153 Idx:17232; ID:10; [0x85 0x00 0x35 0x09 0x00 0xc0 0xff 0xff 0xff 0xf1 0x00 0x00 0x00 0x00 0x00 ]; I_ADDR_CTXT_L_64IS0 : Address & Context, Long, 64 bit, IS0.; Addr=0xFFFFFFC000096A00; Ctxt: AArch64,EL1, NS; CID=0x00000000; VMID=0x0000;
154 Idx:17248; ID:10; [0xf7 ]; I_ATOM_F1 : Atom format 1.; E
155 Idx:17230; ID:10; OCSD_GEN_TRC_ELEM_TRACE_ON( [begin or filter])
156 Idx:17232; ID:10; OCSD_GEN_TRC_ELEM_PE_CONTEXT((ISA=A64) EL1N; 64-bit; VMID=0x0; CTXTID=0x0; )
157 Idx:17248; ID:10; OCSD_GEN_TRC_ELEM_INSTR_RANGE(exec range=0xffffffc000096a00:[0xffffffc000096a10] num_i(4) last_sz(4) (ISA=A64) E ISB )
158 Idx:17249; ID:10; [0x9d 0x30 0x25 0x59 0x00 0xc0 0xff 0xff 0xff ]; I_ADDR_L_64IS0 : Address, Long, 64 bit, IS0.; Addr=0xFFFFFFC000594AC0;
159 Idx:17258; ID:10; [0xf7 ]; I_ATOM_F1 : Atom format 1.; E
160 Idx:17258; ID:10; OCSD_GEN_TRC_ELEM_ADDR_NACC( 0xffffffc000594ac0 )
161 Idx:17259; ID:10; [0x95 0xd6 0x95 ]; I_ADDR_S_IS0 : Address, Short, IS0.; Addr=0xFFFFFFC000592B58 ~[0x12B58]
162 Idx:17262; ID:10; [0xf9 ]; I_ATOM_F3 : Atom format 3.; ENN
163 Idx:17262; ID:10; OCSD_GEN_TRC_ELEM_ADDR_NACC( 0xffffffc000592b58 )
164 Idx:17264; ID:10; [0xf7 ]; I_ATOM_F1 : Atom format 1.; E
165 Idx:17265; ID:10; [0x9a 0x32 0x62 0x5a 0x00 ]; I_ADDR_L_32IS0 : Address, Long, 32 bit, IS0.; Addr=0xFFFFFFC0005AC4C8;
166 Idx:17270; ID:10; [0xdb ]; I_ATOM_F2 : Atom format 2.; EE
167 Idx:17270; ID:10; OCSD_GEN_TRC_ELEM_ADDR_NACC( 0xffffffc0005ac4c8 )
168 Idx:17271; ID:10; [0x9a 0x62 0x52 0x0e 0x00 ]; I_ADDR_L_32IS0 : Address, Long, 32 bit, IS0.; Addr=0xFFFFFFC0000EA588;
169 Idx:17276; ID:10; [0xfc ]; I_ATOM_F3 : Atom format 3.; NNE
170 Idx:17276; ID:10; OCSD_GEN_TRC_ELEM_ADDR_NACC( 0xffffffc0000ea588 )
171 Idx:17277; ID:10; [0x9a 0x58 0x15 0x59 0x00 ]; I_ADDR_L_32IS0 : Address, Long, 32 bit, IS0.; Addr=0xFFFFFFC000592B60;
172 Idx:17283; ID:10; [0x06 0x1d ]; I_EXCEPT : Exception.; IRQ; Ret Addr Follows;
173 Idx:17285; ID:10; [0x95 0x59 ]; I_ADDR_S_IS0 : Address, Short, IS0.; Addr=0xFFFFFFC000592B64 ~[0x164]
174 Idx:17283; ID:10; OCSD_GEN_TRC_ELEM_ADDR_NACC( 0xffffffc000592b60 )
175 Idx:17283; ID:10; OCSD_GEN_TRC_ELEM_EXCEPTION(pref ret addr:0xffffffc000592b64; excep num (0x0e) )
176 Idx:17287; ID:10; [0x9a 0x20 0x19 0x08 0x00 ]; I_ADDR_L_32IS0 : Address, Long, 32 bit, IS0.; Addr=0xFFFFFFC000083280;
177 Idx:17292; ID:10; [0xfd ]; I_ATOM_F3 : Atom format 3.; ENE
178 Idx:17292; ID:10; OCSD_GEN_TRC_ELEM_INSTR_RANGE(exec range=0xffffffc000083280:[0xffffffc000083284] num_i(1) last_sz(4) (ISA=A64) E BR )
179 Idx:17292; ID:10; OCSD_GEN_TRC_ELEM_INSTR_RANGE(exec range=0xffffffc000083d40:[0xffffffc000083d9c] num_i(23) last_sz(4) (ISA=A64) N BR <cond>)
180 Idx:17292; ID:10; OCSD_GEN_TRC_ELEM_INSTR_RANGE(exec range=0xffffffc000083d9c:[0xffffffc000083dac] num_i(4) last_sz(4) (ISA=A64) E iBR b+link )
181 Idx:17293; ID:10; [0x95 0xf7 0x09 ]; I_ADDR_S_IS0 : Address, Short, IS0.; Addr=0xFFFFFFC0000813DC ~[0x13DC]
182 Idx:17297; ID:10; [0xdb ]; I_ATOM_F2 : Atom format 2.; EE
183 Idx:17297; ID:10; OCSD_GEN_TRC_ELEM_INSTR_RANGE(exec range=0xffffffc0000813dc:[0xffffffc0000813f0] num_i(5) last_sz(4) (ISA=A64) E BR b+link )
184 Idx:17297; ID:10; OCSD_GEN_TRC_ELEM_INSTR_RANGE(exec range=0xffffffc00008f2e0:[0xffffffc00008f2e4] num_i(1) last_sz(4) (ISA=A64) E iBR A64:ret )
185 Idx:17298; ID:10; [0x95 0x7e ]; I_ADDR_S_IS0 : Address, Short, IS0.; Addr=0xFFFFFFC0000813F8 ~[0x1F8]
186 Idx:17300; ID:10; [0xe0 ]; I_ATOM_F6 : Atom format 6.; EEEN
187 Idx:17300; ID:10; OCSD_GEN_TRC_ELEM_INSTR_RANGE(exec range=0xffffffc0000813f8:[0xffffffc00008140c] num_i(5) last_sz(4) (ISA=A64) E BR )
188 Idx:17300; ID:10; OCSD_GEN_TRC_ELEM_INSTR_RANGE(exec range=0xffffffc00008141c:[0xffffffc000081434] num_i(6) last_sz(4) (ISA=A64) E BR <cond>)
189 Idx:17300; ID:10; OCSD_GEN_TRC_ELEM_INSTR_RANGE(exec range=0xffffffc00008140c:[0xffffffc000081414] num_i(2) last_sz(4) (ISA=A64) E BR b+link )
190 Idx:17300; ID:10; OCSD_GEN_TRC_ELEM_ADDR_NACC( 0xffffffc000117cf0 )
194 The `c_api_pkt_print_test` program.
195 -----------------------------------
197 Program tests the C-API infrastructure, including as an option the external decoder support.
199 Limited to decoding trace from a single CoreSight ID. Uses the same "snapshots" as the C++ test program, but using hardcoded path values.
201 __Command Line Options__
203 By default the program will run the single CoreSight ID of 0x10 in packet processing output mode using the ETMv4 decoder on the Juno snapshot.
205 - `-id <n>` : Change the ID used for the test.
206 - `-etmv3` : Test the ETMv3 decoder - uses the TC2 snapshot.
207 - `-ptm` : Test the PTM decoder - uses the TC2 snapshot.
208 - `-stm` : Test the STM decoder - uses juno STM only snapshot.
209 - `-extern` : Use the 'echo_test' external decoder to test the custom decoder API.
210 - `-decode` : Output trace protocol packets and full decode generic packets.
211 - `-decode_only` : Output full decode generic packets only.