Merge pull request #3 in PROCESSOR-SDK/traceframework from CATREQ-2702 to master
[keystone-rtos/traceframework.git] / traceframework.h
1 /**
2  *   @file  traceframework.h
3  *
4  *   @brief   
5  *      This has all necessary include files needed for the appliation to include to trace framework.
6  *
7  *  ============================================================================
8  *  @n   (C) Copyright 2012, Texas Instruments, Inc.
9  * 
10  *  Redistribution and use in source and binary forms, with or without 
11  *  modification, are permitted provided that the following conditions 
12  *  are met:
13  *
14  *    Redistributions of source code must retain the above copyright 
15  *    notice, this list of conditions and the following disclaimer.
16  *
17  *    Redistributions in binary form must reproduce the above copyright
18  *    notice, this list of conditions and the following disclaimer in the 
19  *    documentation and/or other materials provided with the   
20  *    distribution.
21  *
22  *    Neither the name of Texas Instruments Incorporated nor the names of
23  *    its contributors may be used to endorse or promote products derived
24  *    from this software without specific prior written permission.
25  *
26  *  THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS 
27  *  "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT 
28  *  LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
29  *  A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT 
30  *  OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, 
31  *  SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT 
32  *  LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
33  *  DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
34  *  THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 
35  *  (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE 
36  *  OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
37  *
38 */
40 #ifndef __TRACEFRAMEWORK_H_
41 #define __TRACEFRAMEWORK_H_
43 #ifdef __cplusplus
44 extern "C" {
45 #endif
47 /** 
48  * @mainpage  Trace Framework
49  *
50  * Trace framework is a framework which binds producer and consumers via
51  * a contract memory (shared memory between producers and consumers)
52  *
53  * @section Introduction Introduction
54  *
55  * In a multicore environment there would be data generated by a producer and would need
56  * to be consumed by multiple consumers.
57  * Example: UIA log information to be consumed by ARM and System Analyzer.
58  * The framework mentioned in this document is intended to provide a general framework
59  * for a system information source (producer) to provide data to multiple consumers in the
60  * system. 
61  * This needs some kind of synchronization between consumers and producer providing the
62  * information data.
63  * The synchronization is done via the contract memory.
64  * Producer populates the Ring buffer and ring consumers consume the ring buffer and send
65  * the data to external actual consumers (like System Analyzer in CCS).
66  * Each core can have multiple consumer Instances and Producer Instances. Each Producer
67  * instance would be tied to a ring buffer and many consumer instances can consume data
68  * from a ring buffer. Every consumer needs to have its own channel to send the data out,
69  * which triggers the draining of the ring buffer
70  *
71  * @section General_Framework General Framework
72  *
73  * @subsection Ring_Producer Ring Producer
74  *
75  * The ring producer produces the trace/log information in a ring buffer and notifies the
76  * consumers hooked to that ring when the ring buffers are ready. The producer fills up the
77  * information in the ring buffer sequentially, servicing the slowest possible consumer for
78  * that ring. So, a slowest consumer in the system can potentially make the fast consumers
79  * to drop messages.
80  * The producers and consumers handshake through a shared memory region called as \93Contract Memory\94.
81  *
82  * @subsection Ring_Consumer Ring Consumer
83  * 
84  * The ring consumer reads the ring buffer from the producer and outputs it to the
85  * appropriate transport channel. The consumer updates the necessary control messages to
86  * the producer via the Contract.
87  *
88  * @subsection Ring_Contract Contract
89  *
90  * Contract is a shared memory area between the producer and multiple consumers. 
91  * Traceframework supports two contract versions.
92  * - Contract Version 1: All the contracts in the system are in one contiguous big chunk of the memory. Either DSP or ARM needs to 
93  * create that contiguous pool and needs to initialize it via trace framework provided APIs. 
94  *   - @ref tf_contractInit - to initialize the contract memory pool
95  *   - @ref tf_contractCreate - to create the named contract 
96  *   - @ref tf_contractFind - to find the contract by name in producer/consumer functions. 
97  * Please note that the contracts created under this version are named contracts. Traceframework internally handles the name of the contracts.
98  *   - Limitations:
99  *      - Requires big chunk of contiguous memory
100  *      - When ARM initializes the Contract Pool (concept of virtual memory), DSPs do not get to know the physical base address of the contract
101  * of the contracts. Hence every contract created under version 1 
102  * - Contract Version 2: Handling of name within the contracts are removed. The association of name to the contract handle needs to be done
103  * outside traceframework library. There is no need to pre-allocate the big contract chunk of memory. Contracts can be created as and when needed
104  * on either DSP or ARM using the below traceframework provided APIs.
105  *   - @ref tf_newContract - to initialize, create the new contract
106  *   
107  * @verbatim
108          The layout for the contract memory is as below.
109           
110      +-------+----------------------------------------------------------------------------------------------------------------+
111      | Line1 |   Contract name (128 Bytes)                                                                                    |
112      +-------+-----------------+--------------------+-------------------+-------------------+--------------+------------------+
113      | Line2 | Type (4 bytes)  | Contract Version   | Ring Buf Base     | Num of Ring Bufs  | Ring Buf Size| Padding          |
114      |       |                 | (4 Bytes)          | (4 bytes)         | (4 Bytes)         |  (4 bytes)   | (112Bytes)       |
115      +-------+-----------------+--------------------+-------------------+-------------------+--------------+------------------+
116      | Line3 | producer current|                                                                                              |
117      |       | index (4 bytes) | Padding (124 bytes)                                                                          |
118      +-------+-----------------+----------------------------------------------------------------------------------------------+
119      | Line4 | global last free|                                                                                              |
120      |       | index (4bytes)  | Padding (124 bytes)                                                                          |
121      +-------+-----------------+----------------------------------------------------------------------------------------------+
122      | Line5 | Number of Consu |                                                                                              |
123      |       | -ers (4 bytes)  | Padding (124 bytes)                                                                          |
124      +-------+-----------------+--------------------+-------------------+--------------------+--------------------------------+
125      | Line6 | Cons1MagicID    | Cons1_last_free    | Cons1_Notify Reg  | Cons1 Notfy Method | Cons1 Local CallBk| Padding for|
126      |       | (4 bytes)       | Buf Index (4 Bytes)| Mask (4 bytes)    | (4 Bytes)          | Function (4 Bytes)| 104 bytes  |
127      +-------+-----------------+--------------------+-------------------+--------------------+--------------------------------+
128      | Line7 | Cons2MagicID    | Cons2_last_free    | Cons2_Notify Reg  | Cons2 Notfy Method | Cons2 Local CallBk| Padding for|
129      |       | (4 bytes)       | Buf Index (4 Bytes)| Mask (4 bytes)    | (4 Bytes)          | Function (4 Bytes)| 104 bytes  |
130      +-------+-----------------+--------------------+-------------------+--------------------+--------------------------------+
131      | Line8 | Cons3MagicID    | Cons3_last_free    | Cons3_Notify Reg  | Cons3 Notfy Method | Cons3 Local CallBk| Padding for|
132      |       | (4 bytes)       | Buf Index (4 Bytes)| Mask (4 bytes)    | (4 Bytes)          | Function (4 Bytes)| 104 bytes  |
133      +-------+-----------------+--------------------+-------------------+--------------------+--------------------------------+
134      | Line9 | Cons4MagicID    | Cons4_last_free    | Cons4_Notify Reg  | Cons4 Notfy Method | Cons4 Local CallBk| Padding for|
135      |       | (4 bytes)       | Buf Index (4 Bytes)| Mask (4 bytes)    | (4 Bytes)          | Function (4 Bytes)| 104 bytes  |
136      +-------+-----------------+--------------------+-------------------+--------------------+--------------------------------+
137      | Line10|   Out of Band data Information (128 Bytes)                                                                     |
138      +-------+----------------------------------------------------------------------------------------------------------------+
140  Contract Name Field
141     Line 1 in the contract is reserved for the name of the contract. This filed is applicable only for Contract version 1.
142     Few examples of the contract name are,
143     1. UIA_CONTRACT_CORE0,
144     2. UIA_CONTRACT_CORE1,
145     3. UIA_CONTRACT_CORE2,
146     4. UIA_CONTRACT_CORE3.
148  Producer Information Fields
149     Line 2 through line 9 information is used by the ring producer to fill up the ring buffers
150     and to notify the attached consumers in the ring. The contract supports maximum of 4
151     consumers to be attached simultaneously to the ring.
153  Consumer Information Fields
154     Line 2 through to line 5 is used by every consumer to get the information about the
155     current index in the ring buffer where the producer is filling up. Every consumer in the
156     contract has its own dedicated Cache line information updated each time the ring buffer is
157     consumed. The dedicated consumer information is read by other consumers on the
158     contract which influences the producer\92s head index to fill up the ring buffer.
160  Limitations
161     1. The contract and ring buffers need to be aligned to cache boundary and to be
162         placed under shared memory.
163     2. Producer ring needs to be created first before any consumers are instantiated for
164         the ring.
165     3. Every Consumer instance needs to have dedicated unique transport channel.
166     4. Every producer for the ring needs to be notified for any new consumer in the
167         contract.
168   @endverbatim
169  *
170  * @subsection Assumptions Assumptions
171  * - The contract memory is always located in a shared memory for all the cores.
172  * - The elements in the contract memory are cache line aligned.
173  * 
174  * @subsection Rebuilding Rebuilding the Libraries
175  * Please follow the below steps to rebuild the libraries 
176  * - for DSP side
177  *   - Setup the build environment (sample environment setting is provided as in pdk build environment)
178  *   - cd "\ti\pdk_##_1_00_##_##\packages"
179  *   - gmake -C ti / instrumentation / traceframework LIBDIR=./lib clean
180  *   - gmake -C ti / instrumentation / traceframework LIBDIR=./lib all
181  * - for ARM side
182  *   - cd "\ti\pdk_##_1_00_##_##\packages"
183  *   - export DEVICE=device (e.g., k2h)
184  *   - export CROSS_TOOL_INSTALL_PATH=\<croos_tool_install_path\> (e.g., /opt/linaro-2013.03/bin)
185  *   - export CROSS_TOOL_PRFX= \<cross_tool_prefix\> (e.g., for linaro 2013.03 arm-linux-gnueabihf-)
186  *   - export CUIA_INSTALL_DIR=\<where cuia install can be found\> (e.g., devkit base path or actual cuia install location like $HOME/cuia_1_00_00_13)
187  *   - export PDK_INSTALL_PATH=\<current_working_directory\>
188  *   - make -C ti/instrumentation/traceframework -f makefile_armv7 clean all
189  */
191 #include <string.h>
192 /* OSAL Includes */
193 #include <ti/instrumentation/traceframework/contract_osal.h>
194 #include <ti/instrumentation/traceframework/consumer_osal.h>
195 #include <ti/instrumentation/traceframework/producer_osal.h>
197 /* Producer/Consumer Library includes */
198 #include <ti/instrumentation/traceframework/trace_contract.h>
199 #include <ti/instrumentation/traceframework/producer.h>
200 #include <ti/instrumentation/traceframework/consumer.h>
202 /**
203 @defgroup TRACEFRAMEWORK_SYMBOL  Trace Framework Symbols
204 @ingroup TRACEFRAMEWORK_API
205 */
207 /**
208 @defgroup TRACEFRAMEWORK_ENUM  Trace Framework Enumerations
209 @ingroup TRACEFRAMEWORK_API
210 */
212 /**
213 @defgroup TRACEFRAMEWORK_DATASTRUCT  Trace Framework Data Structures
214 @ingroup TRACEFRAMEWORK_API
215 */
217 /**
218 @defgroup TRACEFRAMEWORK_FUNCTIONS  Trace Framework Functions
219 @ingroup TRACEFRAMEWORK_API
220 */
222 /**
223 @defgroup TRACEFRAMEWORK_UIA_FUNCTIONS  Trace Framework Functions (UIA, for DSP side only)
224 @ingroup TRACEFRAMEWORK_API
225 */
227 /**
228 @defgroup TRACEFRAMEWORK_CUIA_FUNCTIONS  Trace Framework Functions (CUIA, for ARM side only)
229 @ingroup TRACEFRAMEWORK_API
230 */
232 /**
233 @defgroup TRACEFRAMEWORK_OSAL  Trace Framework Operating System Abstraction Layer (OSAL) Functions 
234 @ingroup TRACEFRAMEWORK_API
235 */
237 /** @addtogroup TRACEFRAMEWORK_FUNCTIONS
238 @{
239 */
241 /**
242  * ============================================================================
243  *  @n@b tf_consumerSetProducerState
244  *
245  *  @b  brief
246  *  @n  API to set the producer state to either streaming, free run or freeze
247  *
248  *  @param[in]  cHandle
249  *      consumer handle
250  *  @param[in]  state
251  *      intended producer state change
252  *
253  *  @return
254  *      Status of the operation
255  *
256  * =============================================================================
257  */
258 extern tf_consStatus_e tf_consumerSetProducerState(tf_cons_HANDLE cHandle, tf_producerState_e state);
260 /**
261  * ============================================================================
262  *  @n@b tf_consumerGetProducerState
263  *
264  *  @b  brief
265  *  @n  API to sample the current producer state
266  *
267  *  @param[in]  cHandle
268  *      consumer handle
269  *
270  *  @return
271  *      Current sampled producer state in the contract
272  *
273  * =============================================================================
274  */
275 extern tf_producerState_e tf_consumerGetProducerState(tf_cons_HANDLE cHandle);
276 /**
277 @}
278 */
280 /**   
281  *  @page appendix1 Traceframework Contract Types
282  *
283  *  Trace framework supports basically two kinds of contract types. One type, where the contract that is created by DSP and 
284  *  the other type where the contract is created by ARM. Here is the table showing the required contract type creates for an
285  *  use case.
286  * 
287  *    +--------------------------------------------------------------------------------------------------------------------------+
288  *    | Contract Type                                 |   Comments                                                               |
289  *    +-----------------------------------------------+--------------------------------------------------------------------------+
290  *    |  TF_CONTRACT_DSP_ARM/                         | The contract is created by DSP side and hence has only DSP side producer |
291  *    |  TF_CONTRACT_STREAM_FREEZE_PRODUCER           | ARM can only have consumers associated with this contract. This type can |
292  *    |                                               | have DSP consumers also                                                  |
293  *    |-----------------------------------------------+--------------------------------------------------------------------------+
294  *    |  TF_CONTRACT_ARM_ARM                          | The contract is natively created by ARM, hence does not support DSP      |
295  *    |                                               | producers or DSP consumers. Both Producers and Consumers need to be in   |
296  *    |                                               | ARM                                                                      |
297  *    |--------------------------------------------------------------------------------------------------------------------------+
298  *  @ref tf_contractType_e
299  *
300  */
302 #ifdef __cplusplus
304 #endif
306 #endif /* __TRACEFRAMEWORK_H_ */
307 /* Nothing past this point */