diff options
Diffstat (limited to 'decoder/docs')
| -rw-r--r-- | decoder/docs/build_libs.md | 8 | ||||
| -rw-r--r-- | decoder/docs/doxygen_config.dox | 5 | ||||
| -rw-r--r-- | decoder/docs/man/trc_pkt_lister.1 | 127 | ||||
| -rw-r--r-- | decoder/docs/prog_guide/prog_guide_generic_pkts.md | 58 | ||||
| -rw-r--r-- | decoder/docs/prog_guide/prog_guide_main.md | 24 | ||||
| -rw-r--r-- | decoder/docs/test_progs.md | 2 |
6 files changed, 215 insertions, 9 deletions
diff --git a/decoder/docs/build_libs.md b/decoder/docs/build_libs.md index dc7d85da9401..e3435a2a941c 100644 --- a/decoder/docs/build_libs.md +++ b/decoder/docs/build_libs.md @@ -18,7 +18,7 @@ Building the Library -------------------- The library and test programs are built from the library `./build/<platform>` directory, where -<platform> is either 'linux' or 'win-vs2015' +<platform> is either 'linux' or 'win-vs2015' / 'win-vs2022' See [`./docs/test_progs.md`](@ref test_progs) for further information on use of the test programs. @@ -86,6 +86,12 @@ The test programs are built to used the .so versions of the libraries. The test program build for `trc_pkt_lister` also builds an auxiliary library used by this program for test purposes only. This is the `libsnapshot_parser.a` library, delivered to the `./tests/lib/<tgt_dir>` directories. +**Note on Linux Build Directory Names** + +Due to tool limitations, the makefiles will not operate correctly if the path to the opencsd directories contains spaces. + +e.g. checking out the project into a directory such as ` /home/name/my opencsd/` will result in build failures. + __Installing on Linux__ The libraries can be installed on linux using the `make install` command. This will usually require root privileges. Installation will be the version in the `./lib/<tgt_dir>` directory, according to options chosen. diff --git a/decoder/docs/doxygen_config.dox b/decoder/docs/doxygen_config.dox index 3913d3ac5ea5..7590e47a7561 100644 --- a/decoder/docs/doxygen_config.dox +++ b/decoder/docs/doxygen_config.dox @@ -38,7 +38,7 @@ PROJECT_NAME = "OpenCSD - CoreSight Trace Decode Library" # could be handy for archiving the generated documentation or if some version # control system is used. -PROJECT_NUMBER = 0.14.2 +PROJECT_NUMBER = 1.4.0 # Using the PROJECT_BRIEF tag one can provide an optional one line description # for a project that appears at the top of each page and should give viewer a @@ -805,7 +805,8 @@ INPUT = ../include \ ./prog_guide \ ../include/opencsd \ ../include \ - ../tests/auto-fdo/autofdo.md + ../tests/auto-fdo/autofdo.md \ + ../include/opencsd/ete # This tag can be used to specify the character encoding of the source files # that doxygen parses. Internally doxygen uses the UTF-8 encoding. Doxygen uses diff --git a/decoder/docs/man/trc_pkt_lister.1 b/decoder/docs/man/trc_pkt_lister.1 new file mode 100644 index 000000000000..a2e26790d5f5 --- /dev/null +++ b/decoder/docs/man/trc_pkt_lister.1 @@ -0,0 +1,127 @@ +.\" Hey, EMACS: -*- nroff -*- +.TH TRC_PKT_LISTER 1 "2018-03-28" + +.SH NAME +trc_pkt_lister \- decodes captured CoreSight\*R trace +.SH SYNOPSIS +.RI trc_pkt_lister +[ \-ss_dir \fI<dir>\fP ] +[ -ss_verbose ] +[ \-id \fI<n>\fP ] +[ \-src_name \fI<name>\fP ] +[ \-decode ] +[ \-decode_only ] +[ \-src_addr_n ] +[ \-o_raw_packed ] +[ \-o_raw_unpacked ] +[ \-logstdout ] +[ \-logstderr ] +[ \-logfile ] +[ \-logfilename \fI<name>\fP ] +.br +.SH DESCRIPTION +.B trc_pkt_lister +is a tool that takes a snapshot directory as an input, and lists and/or +decodes all the trace packets for a single source, for any currently +supported protocol. +.PP +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. +.PP +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 streams output. +.SH OPTIONS +.SS Snapshot selection +The program defaults to \./ if no \-ss_dir option is given +.TP +.B \-ss\_dir <dir> +Set the directory path to a trace snapshot. +.TP +\fB\fC\-ss\_verbose\fR +Verbose output when reading the snapshot. +.SS Decode options +.TP +.B \-id <n> +Set an ID to list (may be used multiple times) \- default if no id set is for all IDs to be printed. +.TP +.B \-src\_name <name> +List packets from a given snapshot source name (defaults to first source found). +.TP +.B \-decode +Full decode of the packets from the trace snapshot (default is to list undecoded packets only. +.TP +.B \-decode_only +Does not list the undecoded packets, just the trace decode. +.TP +.B \-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. +.TP +.B \-o\_raw\_packed +Output raw packed trace frames. +.TP +.B \-o\_raw\_unpacked +Output raw unpacked trace data per ID. +.SS Output options +Default is to output to file and stdout. Setting any option overrides and limits to only +the options set. +.TP +.B \-logstdout +output to stdout. +.TP +.B \-logstderr +output to stderr. +.TP +.B \-logfile +output to file using the default log file name. +.TP +.B \-logfilename <name> +change the name of the output log file. +.SH FILES +.B Trace Snapshot directory. +.PP +The \fR./tests/snapshots\fP 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. +.PP +Snapshots are generated on ARM targets and can then be analysed +offline. The snapshot format is available in a separate document. +.SH EXAMPLE +Example command lines with short output excerpts. +.PP +.BI TC2 " ETMv3 packet processor output, raw packet output." +.br +Command line: +.br +.RI "trc\_pkt\_lister -ss\_dir ../../snapshots/TC2 -o_raw_unpacked" +.PP +Output: +.br +Frame Data; Index 17958; ID_DATA[0x11]; 16 04 c0 86 42 97 e1 c4 +.br +Idx:17945; ID:11; I_SYNC : Instruction Packet synchronisation.; (Periodic); Addr=0xc00 +416e2; S; ISA=Thumb2; +.br +Idx:17961; ID:11; P_HDR : Atom P-header.; WEN; Cycles=1 +.br +Frame Data; Index 17968; ID_DATA[0x11]; ce af 90 80 80 00 a4 84 a0 84 a4 88 +.br +Idx:17962; ID:11; TIMESTAMP : Timestamp Value.; TS=0x82f9d13097 (562536984727) +.br +Idx:17974; ID:11; P_HDR : Atom P-header.; WW; Cycles=2 +.PP +.BI Juno " ETB\_1 selected for STM packet output, raw packet output" +.br +Command line: +.br +.RI "trc\_pkt\_lister -ss\_dir ../../snapshots/juno_r1_1 -o\_raw\_unpacked -src\_name ETB\_1" +.PP +.BI Juno " ETMv4 full trace decode + packet monitor, source trace ID 0x10 only." +.br +Command line: +.br +.RI "trc\_pkt\_lister -ss\_dir ../../snapshots/juno\_r1\_1 -decode -id 0x10" + diff --git a/decoder/docs/prog_guide/prog_guide_generic_pkts.md b/decoder/docs/prog_guide/prog_guide_generic_pkts.md index e4d50b79fc80..aad15b847977 100644 --- a/decoder/docs/prog_guide/prog_guide_generic_pkts.md +++ b/decoder/docs/prog_guide/prog_guide_generic_pkts.md @@ -84,7 +84,11 @@ typedef struct _ocsd_generic_trace_elem { ocsd_swt_info_t sw_trace_info; /* software trace packet info */ uint32_t num_instr_range; /* number of instructions covered by range packet (for T32 this cannot be calculated from en-st/i_size) */ unsync_info_t unsync_eot_info; /* additional information for unsync / end-of-trace packets. */ - }; + trace_marker_payload_t sync_marker; /* marker element - sync later element to position in stream */ + trace_memtrans_t mem_trans; /* memory transaction packet - transaction event */ + trace_sw_ite_t sw_ite; /* PE sw instrumentation using FEAT_ITE */ + + }; const void *ptr_extended_data; /* pointer to extended data buffer (data trace, sw trace payload) / custom structure */ @@ -325,6 +329,58 @@ SW trace packets that have a payload will use the extended_data flag and pointer SW trace packets that include timestamp information will us the `has_ts` flag and fill in the timestamp value. +These packets are generated by memory writes to STM / ITM trace hardware. + +### OCSD_GEN_TRC_ELEM_SYNC_MARKER ### +__packet fields valid__: `sync_marker` + +Synchronisation marker - marks position in stream of an element that is output later. +e.g. a timestamp marker can be output to represent the correct position in the stream for a +timestamp packet the is output later. + +The `sync_marker` field has a structure as shown below. + +~~~{.c} +typedef enum _trace_sync_marker_t { + ELEM_MARKER_TS, /**< Marker for timestamp element */ +} trace_sync_marker_t; + +typedef struct _trace_marker_payload_t { + trace_sync_marker_t type; /**< type of sync marker */ + uint32_t value; /**< sync marker value - usage depends on type */ +} trace_marker_payload_t; +~~~ + +### OCSD_GEN_TRC_ELEM_MEMTRANS ### +__packet fields valid__: `mem_trans` + +Memory transaction elements may appear in the output stream, if they are not otherwise cancelled +by speculative trace packets. + +The memory transaction field has values as defined in the enum below:- + +~~~{.c} +typedef enum _memtrans_t { + OCSD_MEM_TRANS_TRACE_INIT,/* Trace started while PE in transactional state */ + OCSD_MEM_TRANS_START, /* Trace after this packet is part of a transactional memory sequence */ + OCSD_MEM_TRANS_COMMIT, /* Transactional memory sequence valid. */ + OCSD_MEM_TRANS_FAIL, /* Transactional memory sequence failed - operations since start of transaction have been unwound. */ +} trace_memtrans_t; +~~~ + +### OCSD_GEN_TRC_ELEM_INSTRUMENTATION ### +__packet fields valid__: `sw_ite` + +Software instrumentation packets generated by the PE `TRCIT` instruction (on cores with `FEAT_ITE`). + +The `sw_ite` structure has the fields defined below:- + +~~~{.c} +typedef struct _sw_ite_t { + uint8_t el; /* exception level for PE sw instrumentation instruction */ + uint64_t value; /* payload for PE sw instrumentation instruction */ +} trace_sw_ite_t; +~~~ ### OCSD_GEN_TRC_ELEM_CUSTOM ### __packet fields optional__: `extended_data -> ptr_extended_data`,_any others_ diff --git a/decoder/docs/prog_guide/prog_guide_main.md b/decoder/docs/prog_guide/prog_guide_main.md index 87afbf0225c6..9504bdc244d3 100644 --- a/decoder/docs/prog_guide/prog_guide_main.md +++ b/decoder/docs/prog_guide/prog_guide_main.md @@ -138,9 +138,17 @@ The error logger can be attached to an output logger - ocsdMsgLogger - which can error, or other error messages, out to screen or logging file. Errors can be filtered according to a severity rating, defined by @ref ocsd_err_severity_t. -The DecodeTree will use a default error logger from the library - with a message logger -that will output to `stderr`. Client applications can adjust the configuration of this error logger and -message logger, or provide their own configured error logger / message logger pair. +The DecodeTree can use a default error logger from the library - with a message logger that will output to `stderr`. + +Client applications can create and adjust the configuration of this error logger and message logger by getting and intialising + the logger. + +~~~{.cpp} + // ** Initialise default error logger. + DecodeTree::getDefaultErrorLogger()->initErrorLogger(verbosity,true); +~~~ + +Alternatively clients may provide their own configured error logger / message logger pair. The test program `trc_pkt_lister` provides a customised version of an `ocsdMsgLogger` / `ocsdDefaultErrorLogger` pair to ensure that messages and errors are logged to the screen and a file of its choice. This logger is eventually @@ -272,6 +280,7 @@ The different trace source types have different configuration structures, classe | protocol | config struct | class | name define | |:----------|:--------------------|:------------|:-----------------------------| +| __ETE__ | @ref ocsd_ete_cfg | ETEConfig | @ref OCSD_BUILTIN_DCD_ETE | | __ETMv4__ | @ref ocsd_etmv4_cfg | EtmV4Config | @ref OCSD_BUILTIN_DCD_ETMV4I | | __ETMv3__ | @ref ocsd_etmv3_cfg | EtmV3Config | @ref OCSD_BUILTIN_DCD_ETMV3 | | __PTM__ | @ref ocsd_ptm_cfg | PtmConfig | @ref OCSD_BUILTIN_DCD_PTM | @@ -300,15 +309,19 @@ types to be managed by a memory access mapper:- ~~~{.cpp} class DecodeTree { - ///... + // ... + ocsd_err_t createMemAccMapper(memacc_mapper_t type = MEMACC_MAP_GLOBAL); + // ... ocsd_err_t addBufferMemAcc(const ocsd_vaddr_t address, const ocsd_mem_space_acc_t mem_space, const uint8_t *p_mem_buffer, const uint32_t mem_length); ocsd_err_t addBinFileMemAcc(const ocsd_vaddr_t address, const ocsd_mem_space_acc_t mem_space, const std::string &filepath); ocsd_err_t addBinFileRegionMemAcc(const ocsd_file_mem_region_t *region_array, const int num_regions, const ocsd_mem_space_acc_t mem_space, const std::string &filepath); */ ocsd_err_t addCallbackMemAcc(const ocsd_vaddr_t st_address, const ocsd_vaddr_t en_address, const ocsd_mem_space_acc_t mem_space, Fn_MemAcc_CB p_cb_func, const void *p_context); - ///... + // ... } ~~~ +The `createMemAccMapper()` function must be called to create the mapper, before the `add...MemAcc()` calls are used. + It is further possible to differentiate between memory image access objects by the memory space for which they are valid. If it is known that a certain code image is present in secure EL3, then an image can be associated with the @ref ocsd_mem_space_acc_t type value @ref OCSD_MEM_SPACE_EL3, which will allow another image to be present at the same address but a different exception level. However, for the majority of systems, such detailed knowledge of the code is not available, or @@ -323,6 +336,7 @@ The C-API contains a similar set of calls to set up memory access objects:- OCSD_C_API ocsd_err_t ocsd_dt_add_callback_mem_acc(const dcd_tree_handle_t handle, const ocsd_vaddr_t st_address, const ocsd_vaddr_t en_address, const ocsd_mem_space_acc_t mem_space, Fn_MemAcc_CB p_cb_func, const void *p_context); ~~~ +Note that the C-API will automatically create a default mapper when the first memory access object is added. ### Adding the output callbacks ### diff --git a/decoder/docs/test_progs.md b/decoder/docs/test_progs.md index c02d02e96271..3af769244d0c 100644 --- a/decoder/docs/test_progs.md +++ b/decoder/docs/test_progs.md @@ -61,6 +61,8 @@ __Command Line Options__ - `-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` : 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. |