Improved documentation in main code and test program.
Added the include/common directory to the files scanned by doxygen.
Signed-off-by: Mike Leach mike.leach@linaro.org --- decoder/docs/doxygen_config.dox | 3 +- decoder/include/c_api/ocsd_c_api_deprc_fn.h | 58 ++++- decoder/include/common/ocsd_dcd_tree.h | 261 +++++++++++++++++++--- decoder/include/common/ocsd_dcd_tree_elem.h | 24 +- decoder/include/common/trc_cs_config.h | 8 +- decoder/include/common/trc_pkt_proc_base.h | 53 +++-- decoder/include/interfaces/trc_abs_typed_base_i.h | 5 +- decoder/include/ocsd_if_types.h | 8 +- decoder/include/opencsd.h | 3 - decoder/include/ptm/trc_cmp_cfg_ptm.h | 4 +- decoder/include/trc_gen_elem_types.h | 4 +- decoder/tests/source/c_api_pkt_print_test.c | 9 +- decoder/tests/source/gen_elem_printer.h | 2 +- 13 files changed, 372 insertions(+), 70 deletions(-)
diff --git a/decoder/docs/doxygen_config.dox b/decoder/docs/doxygen_config.dox index bdb24f0..d6b1666 100644 --- a/decoder/docs/doxygen_config.dox +++ b/decoder/docs/doxygen_config.dox @@ -773,7 +773,8 @@ INPUT = ../include \ ../include/mem_acc \ ../../README.md \ . \ - ../../HOWTO.md + ../../HOWTO.md \ + ../include/common
# 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/include/c_api/ocsd_c_api_deprc_fn.h b/decoder/include/c_api/ocsd_c_api_deprc_fn.h index 7c74987..463f4af 100644 --- a/decoder/include/c_api/ocsd_c_api_deprc_fn.h +++ b/decoder/include/c_api/ocsd_c_api_deprc_fn.h @@ -35,9 +35,63 @@ #ifndef ARM_OCSD_C_API_DEPRC_FN_H_INCLUDED #define ARM_OCSD_C_API_DEPRC_FN_H_INCLUDED
-/** @name Deprecated C-API functions +/** @defgroup depr_lib_c_api OpenCSD Library : Deprecated "C" API functions and types + + @brief "C" API functions and types that have been deprecated after API changes. + + Retained for regression testing for a few library versions + Will be removed completely in a later library version + + To use these functions define the macro OPENCSD_INC_DEPRECATED_API @{*/
+/** function pointer type for ETMv4 instruction packet processor output, packet analyser/decoder input */ +typedef ocsd_datapath_resp_t (* FnEtmv4IPacketDataIn)(const void *p_context, const ocsd_datapath_op_t op, const ocsd_trc_index_t index_sop, const ocsd_etmv4_i_pkt *p_packet_in); + +/** function pointer type for ETMv4 instruction packet processor monitor output, raw packet monitor / display input */ +typedef void (* FnEtmv4IPktMonDataIn)( const void *p_context, + const ocsd_datapath_op_t op, + const ocsd_trc_index_t index_sop, + const ocsd_etmv4_i_pkt *p_packet_in, + const uint32_t size, + const uint8_t *p_data); + +/** function pointer type for ETMv3 packet processor output, packet analyser/decoder input */ +typedef ocsd_datapath_resp_t (* FnEtmv3PacketDataIn)(const void *p_context, const ocsd_datapath_op_t op, const ocsd_trc_index_t index_sop, const ocsd_etmv3_pkt *p_packet_in); + +/** function pointer type for ETMv3 packet processor monitor output, raw packet monitor / display input */ +typedef void (* FnEtmv3PktMonDataIn)( const void *p_context, + const ocsd_datapath_op_t op, + const ocsd_trc_index_t index_sop, + const ocsd_etmv3_pkt *p_packet_in, + const uint32_t size, + const uint8_t *p_data); + + +/** function pointer type for PTM packet processor output, packet analyser/decoder input */ +typedef ocsd_datapath_resp_t (* FnPtmPacketDataIn)(const void *p_context, const ocsd_datapath_op_t op, const ocsd_trc_index_t index_sop, const ocsd_ptm_pkt *p_packet_in); + +/** function pointer type for PTM packet processor monitor output, raw packet monitor / display input */ +typedef void (* FnPtmPktMonDataIn)( const void *p_context, + const ocsd_datapath_op_t op, + const ocsd_trc_index_t index_sop, + const ocsd_ptm_pkt *p_packet_in, + const uint32_t size, + const uint8_t *p_data); + + +/** function pointer type for STM packet processor output, packet analyser/decoder input */ +typedef ocsd_datapath_resp_t (* FnStmPacketDataIn)(const void *p_context, const ocsd_datapath_op_t op, const ocsd_trc_index_t index_sop, const ocsd_stm_pkt *p_packet_in); + +/** function pointer type for STM packet processor monitor output, raw packet monitor / display input */ +typedef void (* FnStmPktMonDataIn)( const void *p_context, + const ocsd_datapath_op_t op, + const ocsd_trc_index_t index_sop, + const ocsd_stm_pkt *p_packet_in, + const uint32_t size, + const uint8_t *p_data); + + /*---------------------- ETMv4 Trace ----------------------------------------------------------------------------------*/ /*! * Create an ETMv4 instruction trace packet processor only for the supplied configuration. @@ -95,7 +149,7 @@ OCSD_C_API ocsd_err_t ocsd_dt_create_etmv3_pkt_proc(const dcd_tree_handle_t hand * Uses the output function set in ocsd_dt_set_gen_elem_outfn() as the output sink. * * @param handle : Handle to decode tree. - * @param *etmv4_cfg : pointer to valid Etmv4 configuration structure. + * @param *etmv3_cfg : pointer to valid Etmv4 configuration structure. * * @return ocsd_err_t : Library error code - RCDTL_OK if successful. */ diff --git a/decoder/include/common/ocsd_dcd_tree.h b/decoder/include/common/ocsd_dcd_tree.h index 0461eef..1ab5fbc 100644 --- a/decoder/include/common/ocsd_dcd_tree.h +++ b/decoder/include/common/ocsd_dcd_tree.h @@ -40,7 +40,7 @@ #include <list>
#include "opencsd.h" - +#include "ocsd_dcd_tree_elem.h"
/** @defgroup dcd_tree OpenCSD Library : Trace Decode Tree. @brief Create a multi source decode tree for a single trace capture buffer. @@ -50,8 +50,6 @@
@{*/
-#include "ocsd_dcd_tree_elem.h" - /*! * @class DecodeTree * @brief Class to manage the decoding of data from a single trace sink . @@ -63,11 +61,13 @@ class DecodeTree : public ITrcDataIn { public: - DecodeTree(); - ~DecodeTree(); +/** @name Creation and Destruction +@{*/ + DecodeTree(); //!< default constructor + ~DecodeTree(); //!< default destructor
/*! - * Create a decode tree. + * @brief Create a decode tree. * Automatically creates a trace frame deformatter if required and a default error log component. * * @param src_type : Data stream source type, can be CoreSight frame formatted trace, or single demuxed trace data stream, @@ -77,10 +77,15 @@ public: */ static DecodeTree *CreateDecodeTree(const ocsd_dcd_tree_src_t src_type, const uint32_t formatterCfgFlags);
- /** Destroy a decode tree */ + /** @brief Destroy a decode tree */ static void DestroyDecodeTree(DecodeTree *p_dcd_tree);
- /** The library default error logger */ +/** @}*/ + + +/** @name Error Logging +@{*/ + /** @brief The library default error logger */ static ocsdDefaultErrorLogger* getDefaultErrorLogger() { return &s_error_logger; };
/** the current error logging interface in use */ @@ -89,8 +94,15 @@ public: /** set an alternate error logging interface. */ static void setAlternateErrorLogger(ITraceErrorLog *p_error_logger);
- /** decode tree implements the data in interface : ITrcDataIn . - Captured trace data is passed to the deformatter and decoders via this method. +/** @}*/ + + +/** @name Trace Data Path +@{*/ + /** @brief Trace Data input interface (ITrcDataIn) + + Decode tree implements the data in interface : ITrcDataIn . + Captured raw trace data is passed into the deformatter and decoders via this method. */ virtual ocsd_datapath_resp_t TraceDataIn( const ocsd_datapath_op_t op, const ocsd_trc_index_t index, @@ -98,43 +110,242 @@ public: const uint8_t *pDataBlock, uint32_t *numBytesProcessed);
- /*! Create a decoder by registered name */ + /*! + * @brief Decoded Trace output. + * + * Client trace analysis program attaches a generic trace element interface to + * receive the output from the trace decode operations. + * + * @param *i_gen_trace_elem : Pointer to the interface. + */ + void setGenTraceElemOutI(ITrcGenElemIn *i_gen_trace_elem); + + /*! @brief Return the connected generic element interface */ + ITrcGenElemIn *getGenTraceElemOutI() const { return m_i_gen_elem_out; }; + +/** @}*/ + +/** @name Decoder Management +@{*/ + + /*! + * Creates a decoder that is registered with the library under the supplied name. + * createFlags determine if a full packet processor / packet decoder pair or + * packet processor only is created. + * Uses the supplied configuration structure. + * + * @param &decoderName : registered name of decoder + * @param createFlags : Decoder creation options. + * @param *pConfig : Pointer to a valid configuration structure for the named decoder. + * + * @return ocsd_err_t : Library error code or OCSD_OK if successful. + */ ocsd_err_t createDecoder(const std::string &decoderName, const int createFlags, const CSConfig *pConfig);
- /* remove a decoder / packet processor attached to an ID - allows another decoder to be substituted. */ + /* */ + /*! + * Remove a decoder / packet processor attached to an Trace ID output on the frame de-mux. + * + * Once removed another decoder can be created that has a CSConfig using that ID. + * + * @param CSID : Trace ID to remove. + * + * @return ocsd_err_t : Library error code or OCSD_OK if successful. + */ ocsd_err_t removeDecoder(const uint8_t CSID);
- /* set key interfaces - attach / replace on any existing tree components? */ + +/* get decoder elements currently in use */ + + /*! + * Find a decode tree element associated with a specific CoreSight trace ID. * + */ + DecodeTreeElement *getDecoderElement(const uint8_t CSID) const; + /* iterate decoder elements */ + + /*! + * Decode tree iteration. Return the first tree element 0 if no elements avaiable. + * + * @param &elemID : CoreSight Trace ID associated with this element + */ + DecodeTreeElement *getFirstElement(uint8_t &elemID); + /*! + * Return the next tree element - or 0 if no futher elements avaiable. + * + * @param &elemID : CoreSight Trace ID associated with this element + */ + DecodeTreeElement *getNextElement(uint8_t &elemID); + +/* set key interfaces - attach / replace on any existing tree components */ + + /*! + * Set an ARM instruction opcode decoder. + * + * @param *i_instr_decode : Pointer to the interface. + */ void setInstrDecoder(IInstrDecode *i_instr_decode); + /*! + * Set a target memory access interface - used to access program image memory for instruction + * trace decode. + * + * @param *i_mem_access : Pointer to the interface. + */ void setMemAccessI(ITargetMemAccess *i_mem_access); - void setGenTraceElemOutI(ITrcGenElemIn *i_gen_trace_elem);
- /* create mapper within the decode tree - also allows direct manipulation of the mapper object to set up custom arrangements of accessors. */ + +/** @}*/ + +/** @name Memory Access Mapper + + A memory mapper is used to organise a collection of memory accessor objects that contain the + memory images for different areas of traced instruction memory. These areas could be the executed + program and a set of loaded .so libraries for example - each of which would have code sections in + different memory locations. + + A memory accessor represents a snapshot of an area of memory as it appeared during trace capture, + for a given memory space. Memory spaces are described by the ocsd_mem_space_acc_t enum. The most + general memory space is OCSD_MEM_SPACE_ANY. This represents memory that can be secure or none-secure, + available at any exception level. + + The memory mapper will not allow two accessors to overlap in the same memory space. + + The trace decdoer will access memory with a memory space parameter that represents the current core + state - the mapper will find the closest memory space match for the address. + + e.g. if the core is accessing secure EL3, then the most specialised matching space will be accessed. + If an EL3 space matches that will be used, otherwise the any secure, and finally _ANY. + + It is no necessary for clients to register memory accessors for all spaces - _ANY will be sufficient + in many cases. + + +@{*/ + + /* */ + /*! + * This creates a memory mapper within the decode tree. + * + * @param type : defaults to MEMACC_MAP_GLOBAL (only type available at present) + * + * @return ocsd_err_t : Library error code or OCSD_OK if successful. + */ ocsd_err_t createMemAccMapper(memacc_mapper_t type = MEMACC_MAP_GLOBAL); + + /*! + * Get a pointer to the memory mapper. Allows a client to add memory accessors directly to the mapper. + * @return TrcMemAccMapper : Pointer to the mapper. + */ TrcMemAccMapper *getMemAccMapper() const { return m_default_mapper; }; + + /*! + * Set an external mapper rather than create a mapper in the decode tree. + * Setting this will also destroy any internal mapper that was previously created. + * + * @param pMapper : pointer to the mapper to add. + */ void setExternMemAccMapper(TrcMemAccMapper * pMapper); + + /*! + * Return true if a mapper has been set (internal or external + */ const bool hasMemAccMapper() const { return (bool)(m_default_mapper != 0); }; - void logMappedRanges();
- /* create and destroy accessor types - all using global CSID value - on default accessor */ + void logMappedRanges(); //!< Log the mapped memory ranges to the default message logger. + +/** @}*/ + +/** @name Memory Accessors + A memory accessor represents a snapshot of an area of memory as it appeared during trace capture. + + Memory spaces represent either common global memory, or Secure / none-secure and EL specific spaces. + +@{*/ + + /*! + * Creates a memory accessor for a memory block in the supplied buffer and adds to the current mapper. + * + * @param address : Start address for the memory block in the memory map. + * @param mem_space : Memory space + * @param *p_mem_buffer : start of the buffer. + * @param mem_length : length of the buffer. + * + * @return ocsd_err_t : Library error code or OCSD_OK if successful. + */ 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); + + /*! + * Creates a memory accessor for a memory block supplied as a contiguous binary data file, and adds to the current mapper. + * + * @param address : Start address for the memory block in the memory map. + * @param mem_space : Memory space + * @param &filepath : Path to the binary data file + * + * @return ocsd_err_t : Library error code or OCSD_OK if successful. + */ ocsd_err_t addBinFileMemAcc(const ocsd_vaddr_t address, const ocsd_mem_space_acc_t mem_space, const std::string &filepath); + + /*! + * Creates a memory accessor for a memory block supplied as a one or more memory regions in a binary file. + * Region structures are created that describe the memory start address, the offset within the binary file + * for that address, and the length of the region. This accessor can be used to point to the code section + * in a program file for example. + * + * @param *region_array : array of valid memory regions in the file. + * @param num_regions : number of regions + * @param mem_space : Memory space + * @param &filepath : Path to the binary data file + * + * @return ocsd_err_t : Library error code or OCSD_OK if successful. + */ 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); + + /*! + * This memory accessor allows the client to supply a callback function for the region + * defined by the start and end addresses. This can be used to supply a custom memory accessor, + * or to directly access memory if the decode is running live on a target system. + * + * @param st_address : start address of region. + * @param en_address : end address of region. + * @param mem_space : Memory space + * @param p_cb_func : Callback function + * @param *p_context : client supplied context information + * + * @return ocsd_err_t : Library error code or OCSD_OK if successful. + */ 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); + + /*! + * Remove the memory accessor from the map, that begins at the given address, for the memory space provided. + * + * @param address : Start address of the memory accessor. + * @param mem_space : Memory space for the memory accessor. + * + * @return ocsd_err_t : Library error code or OCSD_OK if successful. + */ ocsd_err_t removeMemAccByAddress(const ocsd_vaddr_t address, const ocsd_mem_space_acc_t mem_space);
- /* get decoder elements currently in use */ - DecodeTreeElement *getDecoderElement(const uint8_t CSID) const; - /* iterate decoder elements */ - DecodeTreeElement *getFirstElement(uint8_t &elemID); - DecodeTreeElement *getNextElement(uint8_t &elemID); +/** @}*/
+/** @name CoreSight Trace Frame De-mux +@{*/ + + //! Get the Trace Frame de-mux. TraceFormatterFrameDecoder *getFrameDeformatter() const { return m_frame_deformatter_root; }; - ITrcGenElemIn *getGenTraceElemOutI() const { return m_i_gen_elem_out; };
- /* ID filtering - sets the output filter on the trace deformatter. No effect if no decoder attached for the ID */ + + /*! @brief ID filtering - sets the output filter on the trace deformatter. + + Only supplied IDs will be decoded. + + No effect if no decoder attached for the ID + + @param ids : Vector of CS Trace IDs + */ ocsd_err_t setIDFilter(std::vector<uint8_t> &ids); // only supplied IDs will be decoded - ocsd_err_t clearIDFilter(); // remove filter, all IDs will be decoded + + ocsd_err_t clearIDFilter(); //!< remove filter, all IDs will be decoded + +/** @}*/
private: bool initialise(const ocsd_dcd_tree_src_t type, uint32_t formatterCfgFlags); diff --git a/decoder/include/common/ocsd_dcd_tree_elem.h b/decoder/include/common/ocsd_dcd_tree_elem.h index 82c2159..2b609fb 100644 --- a/decoder/include/common/ocsd_dcd_tree_elem.h +++ b/decoder/include/common/ocsd_dcd_tree_elem.h @@ -38,29 +38,32 @@ #include "common/ocsd_dcd_mngr_i.h" #include "common/trc_component.h"
-/** @class decoder_elements - * @brief Decode tree element base structure. - * @addtogroup dcd_tree +/** @addtogroup dcd_tree +@{*/ + +/*! @struct _decoder_elements + * @brief Decode tree element base structure. * * Element describes the protocol supported for this element and * contains pointers to the decoder manager interface and component handle. - * */ typedef struct _decoder_elements { - std::string dcd_name; - TraceComponent *dcd_handle; - IDecoderMngr *dcd_mngr; - ocsd_trace_protocol_t protocol; + std::string dcd_name; //!< Registered name of the decoder + TraceComponent *dcd_handle; //!< handle to the decoder object + IDecoderMngr *dcd_mngr; //!< pointer to the decoder manager interface for the decodcer + ocsd_trace_protocol_t protocol;//!< protocol type bool created; /**< decode tree created this element (destroy it on tree destruction) */ } decoder_element;
/*! * @class DecodeTreeElement * @brief Decode tree element - * @addtogroup dcd_tree * - * + * Decoder tree elements are references to individual decoders in the tree. + * These allow iteration of all decoders in the tree to perform common operations. + * + * The DecodeTree contains a list of elements. */ class DecodeTreeElement : protected decoder_element { @@ -103,6 +106,7 @@ inline void DecodeTreeElement::DestroyElem() dcd_mngr->destroyDecoder(dcd_handle); }
+/** @}*/ #endif // ARM_OCSD_DCD_TREE_ELEM_H_INCLUDED
/* End of File ocsd_dcd_tree_elem.h */ diff --git a/decoder/include/common/trc_cs_config.h b/decoder/include/common/trc_cs_config.h index 58398f7..9b2c130 100644 --- a/decoder/include/common/trc_cs_config.h +++ b/decoder/include/common/trc_cs_config.h @@ -35,8 +35,12 @@ * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. */
+/** @addtogroup ocsd_protocol_cfg +@{*/ + /*! - * @class CSConfig : Base class for configuration data on CoreSight trace component. + * @class CSConfig + * @brief Base class for configuration data on CoreSight trace component. * * Defines common access functionality, common to all components. * (e.g. trace ID). @@ -51,6 +55,8 @@ public: virtual const uint8_t getTraceID() const = 0; //!< CoreSight Trace ID for this device. };
+/** @}*/ + #endif // ARM_TRC_CS_CONFIG_H_INCLUDED
/* End of File trc_cs_config.h */ \ No newline at end of file diff --git a/decoder/include/common/trc_pkt_proc_base.h b/decoder/include/common/trc_pkt_proc_base.h index 86ad690..f09ad61 100644 --- a/decoder/include/common/trc_pkt_proc_base.h +++ b/decoder/include/common/trc_pkt_proc_base.h @@ -45,13 +45,22 @@ #include "comp_attach_pt_t.h"
/** @defgroup ocsd_pkt_proc OpenCSD Library : Packet Processors. - @brief Classes providing Protocol Packet Processing capability.
Packet processors take an incoming byte stream and convert into discrete packets for the required trace protocol. @{*/
+ + +/*! + * @class TrcPktProcI + * @brief Base Packet processing interface + * + * Defines the packet processing methods that protocol specific processors must + * implement. + * + */ class TrcPktProcI : public TraceComponent, public ITrcDataIn { public: @@ -59,7 +68,8 @@ public: TrcPktProcI(const char *component_name, int instIDNum); virtual ~TrcPktProcI() {};
- /* generic trace data input interface */ + /** Trace byte data input interface - from ITrcDataIn. + */ virtual ocsd_datapath_resp_t TraceDataIn( const ocsd_datapath_op_t op, const ocsd_trc_index_t index, const uint32_t dataBlockSize, @@ -69,15 +79,18 @@ public: protected:
/* implementation packet processing interface */ + + /*! @brief Implementation function for the OCSD_OP_DATA operation */ virtual ocsd_datapath_resp_t processData( const ocsd_trc_index_t index, const uint32_t dataBlockSize, const uint8_t *pDataBlock, uint32_t *numBytesProcessed) = 0; - virtual ocsd_datapath_resp_t onEOT() = 0; - virtual ocsd_datapath_resp_t onReset() = 0; - virtual ocsd_datapath_resp_t onFlush() = 0; - virtual ocsd_err_t onProtocolConfig() = 0; - virtual const bool isBadPacket() const = 0; // check if the current packet is an error / bad packet + + virtual ocsd_datapath_resp_t onEOT() = 0; //!< Implementation function for the OCSD_OP_EOT operation + virtual ocsd_datapath_resp_t onReset() = 0; //!< Implementation function for the OCSD_OP_RESET operation + virtual ocsd_datapath_resp_t onFlush() = 0; //!< Implementation function for the OCSD_OP_FLUSH operation + virtual ocsd_err_t onProtocolConfig() = 0; //!< Called when the configuration object is passed to the decoder. + virtual const bool isBadPacket() const = 0; //!< check if the current packet is an error / bad packet };
inline TrcPktProcI::TrcPktProcI(const char *component_name) : @@ -95,15 +108,15 @@ inline TrcPktProcI::TrcPktProcI(const char *component_name, int instIDNum) : * @brief Packet Processor base class. Provides common infrastructure and interconnections for packet processors. * * The class is a templated base class. - * P - this is the packet object class. - * Pt - this is the packet type class. - * Pc - this is the packet configuration class. + * - P - this is the packet object class. + * - Pt - this is the packet type class. + * - Pc - this is the packet configuration class. * * implementations will provide concrete classes for each of these to operate under the common infrastructures. * The base provides the trace data in (ITrcDataIn) interface and operates on the incoming operation type. * - * Implementions override the 'onFn()' and data process functions, with the base class ensuring consistent - * ordering of operations. + * Implementions override the 'onFn()' and data process functions defined in TrcPktProcI, + * with the base class ensuring consistent ordering of operations. * */ template <class P, class Pt, class Pc> @@ -114,7 +127,11 @@ public: TrcPktProcBase(const char *component_name, int instIDNum); virtual ~TrcPktProcBase();
- /* generic trace data input interface */ + /** Byte trace data input interface defined in ITrcDataIn + + The base class implementation processes the operation to call the + interface functions on TrcPktProcI. + */ virtual ocsd_datapath_resp_t TraceDataIn( const ocsd_datapath_op_t op, const ocsd_trc_index_t index, const uint32_t dataBlockSize, @@ -122,14 +139,20 @@ public: uint32_t *numBytesProcessed);
- /* component attachment points */ +/* component attachment points */ + + //! Attachement point for the protocol packet output componentAttachPt<IPktDataIn<P>> *getPacketOutAttachPt() { return &m_pkt_out_i; }; + //! Attachment point for the protocol packet monitor componentAttachPt<IPktRawDataMon<P>> *getRawPacketMonAttachPt() { return &m_pkt_raw_mon_i; };
+ //! Attachment point for a packet indexer componentAttachPt<ITrcPktIndexer<Pt>> *getTraceIDIndexerAttachPt() { return &m_pkt_indexer_i; };
- /* protocol configuration */ +/* protocol configuration */ + //!< Set the protocol specific configuration for the decoder. virtual ocsd_err_t setProtocolConfig(const Pc *config); + //!< Get the configuration for the decoder. virtual const Pc *getProtocolConfig() const { return m_config; };
protected: diff --git a/decoder/include/interfaces/trc_abs_typed_base_i.h b/decoder/include/interfaces/trc_abs_typed_base_i.h index 034ecd3..0db6077 100644 --- a/decoder/include/interfaces/trc_abs_typed_base_i.h +++ b/decoder/include/interfaces/trc_abs_typed_base_i.h @@ -37,13 +37,14 @@ #define ARM_TRC_ABS_TYPED_BASE_I_H_INCLUDED
/*! - * @class ITrcTypedBase : Abstract base class to for interfaces templated types. + * @class ITrcTypedBase + * @brief Abstract base class to for interfaces templated types. * * This class is used as an abstract base for any interfaces that are specialised using * template<> types. * * Designed to allow interface objects to be passed through generic interfaces into type - * specific templated implmentation handlers. + * specific templated implmentation handlers and converted/checked using RTTI. */ class ITrcTypedBase { diff --git a/decoder/include/ocsd_if_types.h b/decoder/include/ocsd_if_types.h index f026d4e..f581499 100644 --- a/decoder/include/ocsd_if_types.h +++ b/decoder/include/ocsd_if_types.h @@ -511,7 +511,7 @@ typedef enum _ocsd_trace_protocol_t { OCSD_PROTOCOL_BUILTIN_END, /**< Invalid protocol - built-in protocol types end marker */
/* Custom / external decoders */ - OCSD_PROTOCOL_CUSTOM_0 = 100, + OCSD_PROTOCOL_CUSTOM_0 = 100, /**< Values from this onwards are assigned to external registered decoders */ OCSD_PROTOCOL_CUSTOM_1, OCSD_PROTOCOL_CUSTOM_2, OCSD_PROTOCOL_CUSTOM_3, @@ -525,9 +525,11 @@ typedef enum _ocsd_trace_protocol_t { OCSD_PROTOCOL_END /**< Invalid protocol - protocol types end marker */ } ocsd_trace_protocol_t;
-#define OCSD_PROTOCOL_IS_BUILTIN(P) ((P > OCSD_PROTOCOL_UNKNOWN) && (P < OCSD_PROTOCOL_BUILTIN_END)) -#define OCSD_PROTOCOL_IS_CUSTOM(P) ((P > OCSD_PROTOCOL_CUSTOM_0) && (P < OCSD_PROTOCOL_END )) +/** Test if protocol type is a library built-in decoder */ +#define OCSD_PROTOCOL_IS_BUILTIN(P) ((P > OCSD_PROTOCOL_UNKNOWN) && (P < OCSD_PROTOCOL_BUILTIN_END))
+/** Test if protocol type is a custom external registered decoder */ +#define OCSD_PROTOCOL_IS_CUSTOM(P) ((P > OCSD_PROTOCOL_CUSTOM_0) && (P < OCSD_PROTOCOL_END ))
/** @}*/
diff --git a/decoder/include/opencsd.h b/decoder/include/opencsd.h index 9ae283b..ad6e2d2 100644 --- a/decoder/include/opencsd.h +++ b/decoder/include/opencsd.h @@ -50,9 +50,6 @@ #include "interfaces/trc_pkt_raw_in_i.h" #include "interfaces/trc_tgt_mem_access_i.h"
-/* TBD : include the indexers and reader interfaces in here when implmented. */ - - /* protocol base classes and generic elements */ #include "common/ocsd_version.h" #include "common/ocsd_error.h" diff --git a/decoder/include/ptm/trc_cmp_cfg_ptm.h b/decoder/include/ptm/trc_cmp_cfg_ptm.h index 5a4dae2..e086aae 100644 --- a/decoder/include/ptm/trc_cmp_cfg_ptm.h +++ b/decoder/include/ptm/trc_cmp_cfg_ptm.h @@ -39,9 +39,9 @@ #include "trc_pkt_types_ptm.h" #include "common/trc_cs_config.h"
-/** @defgroup ocsd_protocol_cfg OpenCSD Library : Protcol Generator Configuration. +/** @defgroup ocsd_protocol_cfg OpenCSD Library : Trace Source Protocol Configuration.
- @brief Classes describing the trace capture time configuration of the protocol generators. + @brief Classes describing the trace capture time configuration of the trace source hardware.
Protocol configuration represents the trace capture time settings for the CoreSight hardware component generating the trace. The packet processors and packet decoders require this configuration diff --git a/decoder/include/trc_gen_elem_types.h b/decoder/include/trc_gen_elem_types.h index a274eb8..3f3108e 100644 --- a/decoder/include/trc_gen_elem_types.h +++ b/decoder/include/trc_gen_elem_types.h @@ -92,7 +92,7 @@ typedef struct _ocsd_generic_trace_elem { ocsd_instr_type last_i_type; /**< Last instruction type if instruction execution range */ ocsd_instr_subtype last_i_subtype; /**< sub type for last instruction in range */
- // per element flags + //! per element flags struct { uint32_t last_instr_exec:1; /**< 1 if last instruction in range was executed; */ uint32_t has_cc:1; /**< 1 if this packet has a valid cycle count included (e.g. cycle count included as part of instruction range packet, always 1 for pure cycle count packet.*/ @@ -101,7 +101,7 @@ typedef struct _ocsd_generic_trace_elem { uint32_t excep_data_marker:1; /**< 1 if the exception entry packet is a data push marker only, with no address information (used typically in v7M trace for marking data pushed onto stack) */ };
- // packet specific payloads + //! packet specific payloads union { uint32_t exception_number; /**< exception number for exception type packets */ trace_event_t trace_event; /**< Trace event - trigger etc */ diff --git a/decoder/tests/source/c_api_pkt_print_test.c b/decoder/tests/source/c_api_pkt_print_test.c index 5448331..28863b5 100644 --- a/decoder/tests/source/c_api_pkt_print_test.c +++ b/decoder/tests/source/c_api_pkt_print_test.c @@ -42,7 +42,9 @@ * * The test source can be set from the command line, but will default to the * ETMv4 trace for trace ID 0x10 on the juno r1-1 test snapshot. - * This example uses the updated C-API functionality from library version 0v004 onwards. + * This example uses the updated C-API functionality from library version 0.4.0 onwards. + * Test values are hardcoded from the same values in the snapshots as we do not + * explicitly read the snapshot metadata in this example program. */
#include <stdio.h> @@ -62,7 +64,7 @@ const char *default_path_to_snapshot = "../../../snapshots/juno_r1_1/"; const char *tc2_snapshot = "../../../snapshots/TC2/"; #endif
-/* trace data and memory file dump names */ +/* trace data and memory file dump names and values - taken from snapshot metadata */ const char *trace_data_filename = "cstrace.bin"; const char *stmtrace_data_filename = "cstraceitm.bin"; const char *memory_dump_filename = "kernel_dump.bin"; @@ -324,7 +326,6 @@ ocsd_datapath_resp_t packet_handler(void *context, const ocsd_datapath_op_t op,
switch(op) { - default: break; case OCSD_OP_DATA: sprintf(packet_str,"Idx:%ld; ", index_sop); offset = strlen(packet_str); @@ -352,6 +353,8 @@ ocsd_datapath_resp_t packet_handler(void *context, const ocsd_datapath_op_t op, sprintf(packet_str,"**** END OF TRACE ****\n"); ocsd_def_errlog_msgout(packet_str); break; + + default: break; }
return resp; diff --git a/decoder/tests/source/gen_elem_printer.h b/decoder/tests/source/gen_elem_printer.h index 2ab2e47..f3e9717 100644 --- a/decoder/tests/source/gen_elem_printer.h +++ b/decoder/tests/source/gen_elem_printer.h @@ -1,6 +1,6 @@ /* * \file gen_elem_printer.h - * \brief OpenCSD : + * \brief OpenCSD : Generic element printer class. * * \copyright Copyright (c) 2015, ARM Limited. All Rights Reserved. */