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:
ITrcSrcIndexCreator()58     ITrcSrcIndexCreator() {};   /**< Default constructor. */
~ITrcSrcIndexCreator()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 */
125