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 */
55class ITrcSrcIndexCreator
56{
57public:
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 */
125