diff options
author | Ruslan Bukin <br@FreeBSD.org> | 2023-03-27 15:14:10 +0000 |
---|---|---|
committer | Ruslan Bukin <br@FreeBSD.org> | 2023-03-27 15:23:28 +0000 |
commit | 974000f192f9f74654b8835361cf35e606a10a76 (patch) | |
tree | c3aabe2b3d219cca63f0b426a2098bcdf9e9ac65 /decoder/docs/prog_guide | |
parent | d7aa8d0a1f110421252d79f5acfb72d89187ad1f (diff) |
Diffstat (limited to 'decoder/docs/prog_guide')
-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 |
2 files changed, 76 insertions, 6 deletions
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 ### |