contrib/opencsd/decoder/include/interfaces/trc_indexer_src_i.h

   1 /*
   2  * \file       trc_indexer_src_i.h
   3  * \brief      OpenCSD :
   4  *
   5  * \copyright  Copyright (c) 2015, ARM Limited. All Rights Reserved.
   6  */
   7
   8
   9 /*
  10  * Redistribution and use in source and binary forms, with or without modification,
  11  * are permitted provided that the following conditions are met:
  12  *
  13  * 1. Redistributions of source code must retain the above copyright notice,
  14  * this list of conditions and the following disclaimer.
  15  *
  16  * 2. Redistributions in binary form must reproduce the above copyright notice,
  17  * this list of conditions and the following disclaimer in the documentation
  18  * and/or other materials provided with the distribution.
  19  *
  20  * 3. Neither the name of the copyright holder nor the names of its contributors
  21  * may be used to endorse or promote products derived from this software without
  22  * specific prior written permission.
  23  *
  24  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS 'AS IS' AND
  25  * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
  26  * WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
  27  * IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT,
  28  * INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
  29  * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
  30  * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
  31  * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
  32  * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
  33  * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  34  */
  35
  36
  37 #ifndef ARM_TRC_INDEXER_SRC_I_H_INCLUDED
  38 #define ARM_TRC_INDEXER_SRC_I_H_INCLUDED
  39
  40 #include <vector>
  41 #include "opencsd/ocsd_if_types.h"
  42
  43 /*!
  44  * @class ITrcSrcIndexCreator
  45  *
  46  * @brief Interface class to index the frame formatted trace stream
  47  *
  48  * @ingroup ocsd_interfaces
  49  *
  50  * This indexer creates an index of trace IDs present in the frame formatted trace stream.
  51  * It will also index any trigger point markers indicated in the frame format.
  52  *
  53  * Indexing is optional at runtime. Indexes can be saved and re-used.
  54  */
  55 class ITrcSrcIndexCreator
  56 {
  57 public:
  58     ITrcSrcIndexCreator() {};   /**< Default constructor. */
  59     virtual ~ITrcSrcIndexCreator() {};  /**< Default destructor. */
  60
  61     /*!
  62      * The size of block that the indexer will split trace into - this is effectively the
  63      * index granularity. The indexing will indicate if an indexed element - e.g. a source
  64      * ID - is present in the block. Smaller granularity will mean a larger index but more
  65      * resolution in IDs and event positions.
  66      *
  67      * Block sizes will be power of 2 aligned, not less 256 bytes (16 frames).
  68      * Indexer will choose block size based on total trace size and desired granularity.
  69      *
  70      * @return uint32_t : Size of indexing block.
  71      */
  72     virtual const uint32_t IndexBlockSize() const;
  73
  74     /*!
  75      * Index a single ID
  76      *
  77      * @param src_idx : trace index of source ID
  78      * @param ID : The source ID.
  79      *
  80      * @return virtual ocsd_err_t  : OCSD_OK if successful.
  81      */
  82     virtual ocsd_err_t TrcIDIndex(const ocsd_trc_index_t src_idx, const uint8_t ID) = 0;
  83
  84     /*!
  85      * Index a set of IDs in a block.
  86      * Block is assumed to be one of size IndexBlockSize()
  87      *
  88      * May be used by the deformatter to collate IDs and reduce indexing calls.
  89      * May be used by hardware capture source that has its own index of IDs, to transfer
  90      * indexing information into the decoder indexer.
  91      *
  92      * @param src_idx_start : Index of start of block.
  93      * @param IDs : IDs within the block.
  94      *
  95      * @return virtual ocsd_err_t  : OCSD_OK if successful.
  96      */
  97     virtual ocsd_err_t TrcIDBlockMap(const ocsd_trc_index_t src_idx_start, const std::vector<uint8_t> IDs) = 0;
  98
  99     /*!
 100      * The CoreSight frame format can use a reserved ID to indicate trigger or other
 101      * events programmed into the trace protocol generator.
 102      * This call indexes these events.
 103      *
 104      * @param src_idx : trace index of the event.
 105      * @param event_type : type of event.
 106      *
 107      * @return ocsd_err_t  : OCSD_OK if indexed correctly,  OCSD_ERR_INVALID_PARAM_VAL if incorrect value used.
 108      */
 109     virtual ocsd_err_t TrcEventIndex(const ocsd_trc_index_t src_idx, const int event_type) = 0;
 110
 111
 112     /*!
 113      * When the frame formatter is using frame syncs (typically TPIU output captured on off chip capture
 114      * device), this index call notes the position of these elements.
 115      *
 116      * @param src_idx : trace index of sync point.
 117      */
 118     virtual void TrcSyncIndex(const ocsd_trc_index_t src_idx);
 119
 120 };
 121
 122 #endif // ARM_TRC_INDEXER_SRC_I_H_INCLUDED
 123
 124 /* End of File trc_indexer_src_i.h */