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