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 a number test programs built alongside the library. 10 11__Principle Test Programs__ 12 13- `trc_pkt_lister`: 14 15This tests the C++ library by taking a trace "snapshot" directory as an input and decodes all 16or a chosen set of trace sources from within the trace data buffers in the library. Command 17line parameters allow the test program to be controlled. 18 19Users may also run this program on their own trace snapshots to investigate or validate trace from their platforms. 20 21The program may be installed alongside the library onto linux systems, using `make install` from the library build 22directories. This will be installed alongside a `man` file containing relevant user options. 23 24- `c_api_pkt_print_test`: 25 26This program tests the "C" API functions, using hardcoded tests based on the same "snapshots" used 27for the C++ library. Limited user control for this program. 28 29This can also run tests using the external test decoder library to validate the external decoder API. 30See [external_custom.md](@ref custom_decoders) for details. 31 32__Development Utilities__ 33 34These are small utilities, primarily used during the development and test of the decoder library. 35 36- `mem-acc-test` : tests the memory accessor interfaces. 37- `mem-buffer-eg` : example using a memory buffer input to the library. 38- `frame-demux-test` : tests the library CoreSight Frame demux object. 39- `ocsd-perr` : quickly list the library error codes and descriptions. 40 41__Build and Install__ 42 43All the test programs are built at the same time as the library for the same set of platforms. 44See [build_libs.md](@ref build_lib) for build details. 45 46Only `trc_pkt_lister` will be installed alongside the library. 47 48 49Trace "Snapshot" directory. 50---------------------------- 51 52The `.\tests\snapshots` and `.\tests\snapshots-ete` directories contain a number of trace snapshots 53used for testing the library. 54 55Trace snapshots are dumps of captured binary trace data, CoreSight component configurations and memory 56dumps to allow trace decode. 57 58Snapshots are generated on ARM targets and can then be analysed offline. 59 60__Snapshot Specification__ 61 62The principal snapshot format is available in a separate document in 63`.\docs\specs\ARM Trace and Debug Snapshot file format 0v2.pdf`. 64 65The programs above use the library's [core name mapper helper class] (@ref CoreArchProfileMap) to map 66the name of the core into a profile / architecture pair that the library can use. 67 68The snapshot definition must use one of the names recognised by this class, or alternatively use an approved 69profile / architecture profile pattern string as defined below. 70 71There are extensions to this specification, reflecting recent architectural changes. 72 73**Dump File Section Space Format** 74 75The dump file section in device .ini files can define a memory space associated with the file. 76This is done using the `space` keyword. Omitting this keyword with cause the test programs to assume 77that the file applies to all memory spaces enccountered in the trace stream 78 79For complex systems, the same virtual addresses may have differing contents in differing memory spaces. 80The library has extended the memory space names defined in the current specification version to include 81new names for the Realm and Root memory spaces. 82 83Mappings of names to spaces is used as follows : 84 - `EL1S` : maps file to EL1 / EL0 secure states. 85 - `EL2S` : maps file to EL2 secure state. 86 - `EL3` : maps file to EL3 secure state. 87 - `EL1N` : maps file to EL1 / EL0 non-secure state. 88 - `EL2` or `EL2N` : maps file to EL2 non-secure state. 89 - `EL1R` : maps file to EL1 / EL0 Realm state. 90 - `EL2R` : maps file to EL2 Realm state. 91 - `ROOT` : maps file to Root state. 92 - `S` : maps file to all secure states. 93 - `N` : maps file to all non-secure states. 94 - `R` : maps file to all Realm states. 95 - `ANY` : maps file to all security states. This is default if the `space` keyword is omitted. 96 97 98e.g. - Dump section examples with differing memory space definitions. 99 100 - dump 1 & 2 overlap in address but are in different memory spaces. 101 - dump 1 & 3 cover the same memory space, but do not overlap in address. 102 - dump 4 covers all memory spaces but does not overlap in address with any of the other dumps. 103 104~~~~~~~~~~~~~~~~ 105[dump1] 106file=bindir_64ns/OTHERS_exec 107address=0x00060000 108length=0x21388 109space=N 110 111[dump2] 112file=bindir_64rt/OTHERS_exec 113address=0x00060000 114length=0x21388 115space=ROOT 116 117[dump3] 118file=bindir_64ns/VAL_NON_DET_CODE_exec 119address=0x00010000 120length=0x24bf4 121space=EL1N 122 123[dump4] 124file=bindir_64ns/TEST_NON_DET_CODE_exec 125address=0x00050000 126length=0x26c 127~~~~~~~~~~~~~~~~ 128 129**Profile / Architecture pattern string** 130 131Where a specific core name is not used - then a profile / architecture pattern string may be used. 132This enables trace generated on cores with names not in the library to be decoded by the test programs. 133 134Pattern strings can be of the form: 135 136`ARMvM[.m]-P` : 137 - ARMv : fixed prefix 138 - M : architecture major version number 7-9. 139 - .m : optional minor version number 140 - -P : profile type, one of -A, -R or -M 141 142 143e.g. `ARMv8.3-A` , `ARMv7-M` 144 145This format can be used for any ARMv7 / ARMv8 core - including ARM Cortex cores where the name is 146not one of those mapped in the library. 147 148 149`ARM-{aa|AA}64[-P]` : 150 - ARM- : fixed prefix 151 - aa64 or AA64 : indicator for aarch64 152 - -P : optional profile - one of -R or -M, if missing A profile is assumed. 153 154e.g. `ARM-aa64` , `ARM-AA64-R` 155 156This format can be used for all Arm v9 architecture cores. 157 158 159The `trc_pkt_lister` program. 160----------------------------- 161 162This will take a snapshot directory as an input, and lists and/or 163decodes all the trace packets from a given trace sink, for any source in 164that sink where the protocol is supported. 165 166The output will be a list of discrete packets, generic output packets and any error messages 167to file and/or screen as selected by the input command line options. 168 169By default the program will list packets only (no decode), for the first discovered trace sink 170(ETB, ETF, ETR) in the snapshot directory, with all source streams output. 171 172__Command Line Options__ 173 174*Snapshot selection* 175 176- `-ss_dir <dir>` : Set the directory path to a trace snapshot. 177- `-ss_verbose` : Verbose output when reading the snapshot. 178 179*Decode options* 180 181- `-id <n>` : Set an ID to list (may be used multiple times) - default if no id set is for all IDs to be printed. 182- `-src_name <name>` : List packets from a given snapshot source name - e.g ETB_0. (defaults to first source found). 183- `-multi_session` : Decode all buffers listed in snapshot under `buffers` key in `trace.ini`. Uses config of first 184 buffer to decode all. Ignored if `-src_name` is used. 185- `-dstream_format` : Input is DSTREAM framed. 186- `-tpiu` : Input data is from a TPIU source that has TPIU FSYNC packets present. 187- `-tpiu_hsync` : Input data is from a TPIU source that has both TPIU FSYNC and HSYNC packets present. 188- `-decode` : Full decode of the packets from the trace snapshot (default is to list undecoded packets only. 189- `-decode_only` : Does not list the undecoded packets, just the trace decode. 190- `-src_addr_n` : ETE protocol; Indicate skipped N atoms in source address packet ranges by breaking the decode 191 range into multiple ranges of N atoms. 192- `-o_raw_packed` : Output raw packed trace frames. 193- `-o_raw_unpacked` : Output raw unpacked trace data per ID. 194- `-stats` : Output packet processing statistics (if available). 195 196*Consistency Checks* 197 198- `-aa64_opcode_chk` : Check for correct AA64 opcodes (MSW != 0x0000) 199- `-direct_br_cond` : Check for N atoms on unconditional direct branches. 200- `-strict_br_cond` : Check for N atoms on all unconditional branches. 201- `-range_cont` : Check for address consistency between ranges after none taken branches. 202- `-halt_err` : Halt on packet/image errors - default is to reset and attempt to recover. 203 204*Output options* 205 206Default is to output to file and stdout. Setting any option overrides and limits to only 207the options set. 208- `-logstdout` : output to stdout. 209- `-logstderr` : output to stderr. 210- `-logfile` : output to file using the default log file name. 211- `-logfilename <name>` : change the name of the output log file. 212 213*Library Development options* 214 215Options that are only useful if developing or testing the OpenCSD library. 216 217- `-test_waits <N>` : Force wait from packet printer for N packets - test the wait/flush mechanisms for the decoder. 218- `-profile` : Mute logging output while profiling library performance. 219- `-macc_cache_disable` : Switch off caching on memory accessor. 220- `-macc_cache_p_size` : Set size of caching pages. 221- `-macc_cache_p_num` : Set number of caching pages. 222 223__Test output examples__ 224 225Example command lines with short output excerpts. 226 227*TC2, ETMv3 packet processor output, raw packet output.* 228 229Command line:- 230`trc_pkt_lister -ss_dir ..\..\..\snapshots\TC2 -o_raw_unpacked` 231 232~~~~~~~~~~~~~~~~ 233Frame Data; Index 17958; ID_DATA[0x11]; 16 04 c0 86 42 97 e1 c4 234Idx:17945; ID:11; I_SYNC : Instruction Packet synchronisation.; (Periodic); Addr=0xc00416e2; S; ISA=Thumb2; 235Idx:17961; ID:11; P_HDR : Atom P-header.; WEN; Cycles=1 236Frame Data; Index 17968; ID_DATA[0x11]; ce af 90 80 80 00 a4 84 a0 84 a4 88 237Idx:17962; ID:11; TIMESTAMP : Timestamp Value.; TS=0x82f9d13097 (562536984727) 238Idx:17974; ID:11; P_HDR : Atom P-header.; WW; Cycles=2 239Idx:17975; ID:11; P_HDR : Atom P-header.; WE; Cycles=1 240Idx:17976; ID:11; P_HDR : Atom P-header.; W; Cycles=1 241Idx:17977; ID:11; P_HDR : Atom P-header.; WE; Cycles=1 242Idx:17978; ID:11; P_HDR : Atom P-header.; WW; Cycles=2 243Idx:17979; ID:11; P_HDR : Atom P-header.; WEWE; Cycles=2 244Frame Data; Index 17980; ID_DATA[0x10]; a0 82 245Idx:17980; ID:10; P_HDR : Atom P-header.; W; Cycles=1 246Idx:17981; ID:10; P_HDR : Atom P-header.; WEE; Cycles=1 247Frame Data; Index 17984; ID_DATA[0x10]; b8 84 a4 88 a0 82 248Idx:17984; ID:10; P_HDR : Atom P-header.; WWWWWWW; Cycles=7 249Idx:17985; ID:10; P_HDR : Atom P-header.; WE; Cycles=1 250Idx:17986; ID:10; P_HDR : Atom P-header.; WW; Cycles=2 251Idx:17987; ID:10; P_HDR : Atom P-header.; WEWE; Cycles=2 252Idx:17988; ID:10; P_HDR : Atom P-header.; W; Cycles=1 253Idx:17989; ID:10; P_HDR : Atom P-header.; WEE; Cycles=1 254~~~~~~~~~~~~~~~~ 255 256*Juno - ETB_1 selected which contains STM source output, raw packet output* 257 258Command line:- 259`trc_pkt_lister -ss_dir ..\..\..\snapshots\juno_r1_1 -o_raw_unpacked -src_name ETB_1` 260 261~~~~~~~~~~~~~~~~ 262Trace Packet Lister: CS Decode library testing 263----------------------------------------------- 264 265Trace Packet Lister : reading snapshot from path ..\..\..\snapshots\juno_r1_1 266Using ETB_1 as trace source 267Trace Packet Lister : STM Protocol on Trace ID 0x20 268Frame Data; Index 0; ID_DATA[0x20]; ff ff ff ff ff ff ff ff ff ff 0f 0f 30 41 269Idx:0; ID:20; ASYNC:Alignment synchronisation packet. 270Idx:11; ID:20; VERSION:Version packet.; Ver=3 271Frame Data; Index 16; ID_DATA[0x20]; f1 1a 00 00 00 30 10 af 01 00 00 10 03 f2 1a 272Idx:13; ID:20; M8:Set current master.; Master=0x41 273Idx:17; ID:20; D32M:32 bit data; with marker.; Data=0x10000000 274Idx:22; ID:20; C8:Set current channel.; Chan=0x0001 275Idx:23; ID:20; D32M:32 bit data; with marker.; Data=0x10000001 276Idx:28; ID:20; C8:Set current channel.; Chan=0x0002 277Frame Data; Index 32; ID_DATA[0x20]; 00 00 00 32 30 af 01 00 00 30 03 f4 1a 00 00 278Idx:30; ID:20; D32M:32 bit data; with marker.; Data=0x10000002 279Idx:36; ID:20; C8:Set current channel.; Chan=0x0003 280Idx:37; ID:20; D32M:32 bit data; with marker.; Data=0x10000003 281Idx:42; ID:20; C8:Set current channel.; Chan=0x0004 282Frame Data; Index 48; ID_DATA[0x20]; 00 f4 ff ff ff ff ff ff ff ff ff ff f0 00 13 283Idx:44; ID:20; D32M:32 bit data; with marker.; Data=0x10000004 284Idx:50; ID:20; ASYNC:Alignment synchronisation packet. 285Idx:61; ID:20; VERSION:Version packet.; Ver=3 286~~~~~~~~~~~~~~~~ 287 288*Juno - ETMv4 full trace decode + packet monitor, source trace ID 0x10 only.* 289 290Command line:- 291`trc_pkt_lister -ss_dir ..\..\..\snapshots\juno_r1_1 -decode -id 0x10` 292 293~~~~~~~~~~~~~~~~ 294 295Idx:17204; ID:10; [0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x80 ]; I_ASYNC : Alignment Synchronisation. 296Idx:17218; ID:10; [0x01 0x01 0x00 ]; I_TRACE_INFO : Trace Info.; INFO=0x0 297Idx:17221; ID:10; [0x9d 0x00 0x35 0x09 0x00 0xc0 0xff 0xff 0xff ]; I_ADDR_L_64IS0 : Address, Long, 64 bit, IS0.; Addr=0xFFFFFFC000096A00; 298Idx:17230; ID:10; [0x04 ]; I_TRACE_ON : Trace On. 299Idx: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; 300Idx:17248; ID:10; [0xf7 ]; I_ATOM_F1 : Atom format 1.; E 301Idx:17230; ID:10; OCSD_GEN_TRC_ELEM_TRACE_ON( [begin or filter]) 302Idx:17232; ID:10; OCSD_GEN_TRC_ELEM_PE_CONTEXT((ISA=A64) EL1N; 64-bit; VMID=0x0; CTXTID=0x0; ) 303Idx:17248; ID:10; OCSD_GEN_TRC_ELEM_INSTR_RANGE(exec range=0xffffffc000096a00:[0xffffffc000096a10] num_i(4) last_sz(4) (ISA=A64) E ISB ) 304Idx:17249; ID:10; [0x9d 0x30 0x25 0x59 0x00 0xc0 0xff 0xff 0xff ]; I_ADDR_L_64IS0 : Address, Long, 64 bit, IS0.; Addr=0xFFFFFFC000594AC0; 305Idx:17258; ID:10; [0xf7 ]; I_ATOM_F1 : Atom format 1.; E 306Idx:17258; ID:10; OCSD_GEN_TRC_ELEM_ADDR_NACC( 0xffffffc000594ac0 ) 307Idx:17259; ID:10; [0x95 0xd6 0x95 ]; I_ADDR_S_IS0 : Address, Short, IS0.; Addr=0xFFFFFFC000592B58 ~[0x12B58] 308Idx:17262; ID:10; [0xf9 ]; I_ATOM_F3 : Atom format 3.; ENN 309Idx:17262; ID:10; OCSD_GEN_TRC_ELEM_ADDR_NACC( 0xffffffc000592b58 ) 310Idx:17264; ID:10; [0xf7 ]; I_ATOM_F1 : Atom format 1.; E 311Idx:17265; ID:10; [0x9a 0x32 0x62 0x5a 0x00 ]; I_ADDR_L_32IS0 : Address, Long, 32 bit, IS0.; Addr=0xFFFFFFC0005AC4C8; 312Idx:17270; ID:10; [0xdb ]; I_ATOM_F2 : Atom format 2.; EE 313Idx:17270; ID:10; OCSD_GEN_TRC_ELEM_ADDR_NACC( 0xffffffc0005ac4c8 ) 314Idx:17271; ID:10; [0x9a 0x62 0x52 0x0e 0x00 ]; I_ADDR_L_32IS0 : Address, Long, 32 bit, IS0.; Addr=0xFFFFFFC0000EA588; 315Idx:17276; ID:10; [0xfc ]; I_ATOM_F3 : Atom format 3.; NNE 316Idx:17276; ID:10; OCSD_GEN_TRC_ELEM_ADDR_NACC( 0xffffffc0000ea588 ) 317Idx:17277; ID:10; [0x9a 0x58 0x15 0x59 0x00 ]; I_ADDR_L_32IS0 : Address, Long, 32 bit, IS0.; Addr=0xFFFFFFC000592B60; 318Idx:17283; ID:10; [0x06 0x1d ]; I_EXCEPT : Exception.; IRQ; Ret Addr Follows; 319Idx:17285; ID:10; [0x95 0x59 ]; I_ADDR_S_IS0 : Address, Short, IS0.; Addr=0xFFFFFFC000592B64 ~[0x164] 320Idx:17283; ID:10; OCSD_GEN_TRC_ELEM_ADDR_NACC( 0xffffffc000592b60 ) 321Idx:17283; ID:10; OCSD_GEN_TRC_ELEM_EXCEPTION(pref ret addr:0xffffffc000592b64; excep num (0x0e) ) 322Idx:17287; ID:10; [0x9a 0x20 0x19 0x08 0x00 ]; I_ADDR_L_32IS0 : Address, Long, 32 bit, IS0.; Addr=0xFFFFFFC000083280; 323Idx:17292; ID:10; [0xfd ]; I_ATOM_F3 : Atom format 3.; ENE 324Idx:17292; ID:10; OCSD_GEN_TRC_ELEM_INSTR_RANGE(exec range=0xffffffc000083280:[0xffffffc000083284] num_i(1) last_sz(4) (ISA=A64) E BR ) 325Idx:17292; ID:10; OCSD_GEN_TRC_ELEM_INSTR_RANGE(exec range=0xffffffc000083d40:[0xffffffc000083d9c] num_i(23) last_sz(4) (ISA=A64) N BR <cond>) 326Idx: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 ) 327Idx:17293; ID:10; [0x95 0xf7 0x09 ]; I_ADDR_S_IS0 : Address, Short, IS0.; Addr=0xFFFFFFC0000813DC ~[0x13DC] 328Idx:17297; ID:10; [0xdb ]; I_ATOM_F2 : Atom format 2.; EE 329Idx: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 ) 330Idx: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 ) 331Idx:17298; ID:10; [0x95 0x7e ]; I_ADDR_S_IS0 : Address, Short, IS0.; Addr=0xFFFFFFC0000813F8 ~[0x1F8] 332Idx:17300; ID:10; [0xe0 ]; I_ATOM_F6 : Atom format 6.; EEEN 333Idx:17300; ID:10; OCSD_GEN_TRC_ELEM_INSTR_RANGE(exec range=0xffffffc0000813f8:[0xffffffc00008140c] num_i(5) last_sz(4) (ISA=A64) E BR ) 334Idx:17300; ID:10; OCSD_GEN_TRC_ELEM_INSTR_RANGE(exec range=0xffffffc00008141c:[0xffffffc000081434] num_i(6) last_sz(4) (ISA=A64) E BR <cond>) 335Idx: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 ) 336Idx:17300; ID:10; OCSD_GEN_TRC_ELEM_ADDR_NACC( 0xffffffc000117cf0 ) 337 338~~~~~~~~~~~~~~~~ 339 340The `c_api_pkt_print_test` program. 341----------------------------------- 342 343Program tests the C-API infrastructure, including as an option the external decoder support. 344 345Limited to decoding trace from a single CoreSight ID. Uses the same "snapshots" as the C++ test program, but using hardcoded path values. 346 347__Command Line Options__ 348 349By default the program will run the single CoreSight ID of 0x10 in packet processing output mode using the ETMv4 decoder on the Juno snapshot. 350 351- `-id <n>` : Change the ID used for the test. 352- `-etmv3` : Test the ETMv3 decoder - uses the TC2 snapshot. 353- `-ptm` : Test the PTM decoder - uses the TC2 snapshot. 354- `-stm` : Test the STM decoder - uses juno STM only snapshot. 355- `-extern` : Use the 'echo_test' external decoder to test the custom decoder API. 356- `-decode` : Output trace protocol packets and full decode generic packets. 357- `-decode_only` : Output full decode generic packets only. 358