Merge pull request #3 in PROCESSOR-SDK/traceframework from CATREQ-2702 to master
[keystone-rtos/traceframework.git] / producer.h
1 /**\r
2  *   @file  producer.h\r
3  *\r
4  *   @brief   \r
5  *      This is a very slim ring producer framework library implementation.\r
6  *\r
7  *  ============================================================================\r
8  *  @n   (C) Copyright 2012, Texas Instruments, Inc.\r
9  * \r
10  *  Redistribution and use in source and binary forms, with or without \r
11  *  modification, are permitted provided that the following conditions \r
12  *  are met:\r
13  *\r
14  *    Redistributions of source code must retain the above copyright \r
15  *    notice, this list of conditions and the following disclaimer.\r
16  *\r
17  *    Redistributions in binary form must reproduce the above copyright\r
18  *    notice, this list of conditions and the following disclaimer in the \r
19  *    documentation and/or other materials provided with the   \r
20  *    distribution.\r
21  *\r
22  *    Neither the name of Texas Instruments Incorporated nor the names of\r
23  *    its contributors may be used to endorse or promote products derived\r
24  *    from this software without specific prior written permission.\r
25  *\r
26  *  THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS \r
27  *  "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT \r
28  *  LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR\r
29  *  A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT \r
30  *  OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, \r
31  *  SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT \r
32  *  LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,\r
33  *  DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY\r
34  *  THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT \r
35  *  (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE \r
36  *  OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.\r
37  *\r
38 */\r
39 \r
40 #ifndef __GEN_PRODUCER_H__\r
41 #define __GEN_PRODUCER_H__\r
42 \r
43 #ifdef __cplusplus\r
44 extern "C" {\r
45 #endif\r
46 \r
47 #include "ti/instrumentation/traceframework/trace_contract.h"\r
48 \r
49 /** @addtogroup TRACEFRAMEWORK_ENUM\r
50 @{\r
51 */\r
52 \r
53 /**\r
54  * @brief Producer Exception enumerations \r
55 */\r
56 typedef enum prodException\r
57 {\r
58   TF_PRODUCER_EXCEPTION_NOTIFY_FAIL = 0,\r
59   /**< Producer failed to write to the notify register address with the register mask  */   \r
60 \r
61   TF_PRODUCER_EXCEPTION_INVALID_NOTIFY  \r
62   /**< Invalid notify option is passed  */     \r
63 } tf_prodException_e;\r
64 \r
65 /**\r
66  * @brief Producer Status enumerations \r
67 */\r
68 typedef enum prodStatus \r
69 {\r
70   TF_PRODUCER_NO_AVAILABLE_CONTRACT = 0,\r
71   /**< There is no contract available for the producer  */ \r
72   \r
73   TF_PRODUCER_INVALID_CONTRACT_HANDLE,\r
74   /**< Invalid Contract handle is noticed in the producer */   \r
75 \r
76   TF_PRODUCER_INVALID_PRODID,\r
77   /**< Invalid producer Id is noticed  */   \r
78 \r
79   TF_PRODUCER_PROD_SUCCESS,\r
80   /**< Producer ended up with a successful operation */   \r
81 \r
82   TF_PRODUCER_MAX_SUPPORTED_CONSUMERS_REACHED,\r
83   /**< Producer reached maximum number of consumers */   \r
84 \r
85   TF_PRODUCER_PROD_FAIL,\r
86   /**< Producer ended up with an unsuccessful operation */   \r
87 \r
88   TF_PRODUCER_INVALID_HANDLE\r
89   /**< Invalid producer handle */   \r
90   \r
91 } tf_prodStatus_e;\r
92 \r
93 /**\r
94  * @brief   Producer types supported in trace framework\r
95  */\r
96 typedef enum {\r
97   TF_PRODUCER_TYPE_UIA     = 0x1<<0,\r
98   /**< used for creating UIA producer ID */ \r
99   TF_PRODUCER_TYPE_GEN     = 0x1<<1,\r
100   /**< used for creating General producer ID */  \r
101   TF_PRODUCER_TYPE_UIA_MINST = 0x1<<2,\r
102   /**< used for creating Multi-instance UIA producer ID */\r
103   TF_PRODUCER_TYPE_CUIA     = 0x1<<3\r
104   /**< used for creating CUIA producer ID */   \r
105 } tf_producerTypes_e;\r
106 \r
107 /**\r
108 @}\r
109 */\r
110 \r
111 /** @addtogroup TRACEFRAMEWORK_DATASTRUCT\r
112 @{\r
113 */\r
114 \r
115 \r
116 /**\r
117  * @brief   Producer handle\r
118  */\r
119 typedef void*  tf_producer_HANDLE;\r
120 \r
121 /**\r
122  * @brief   Producer State in Contract\r
123  */\r
124 typedef enum {\r
125   TF_PRODUCER_STATE_INVALID     = -1,\r
126   /**< Producer state is invalid  */ \r
127 \r
128   TF_PRODUCER_STATE_STREAMING     = 0,\r
129   /**< Producer is streaming the ring buffer information to the consumer */ \r
130   \r
131   TF_PRODUCER_STATE_FREE_RUNNING,\r
132   /**< Producer is in free run state */ \r
133 \r
134   TF_REQUEST_PRODUCER_STATE_FREEZING,  \r
135   /**< Producer got the request from consumer to freeze */      \r
136 \r
137   TF_PRODUCER_STATE_FROZEN\r
138   /**< Producer is in freeze state */    \r
139   \r
140 } tf_producerState_e;\r
141 \r
142 /**\r
143  * @brief   Producer Response States\r
144  */\r
145 typedef enum {\r
146 \r
147   TF_PRODUCER_RESPONSE_STATE_ACK_FREEZE_REQ = TF_PRODUCER_STATE_FROZEN\r
148   /**< Producer acknowledged consumers that it froze for the freeze request */  \r
149 } tf_producerResponseState_e;\r
150 \r
151 /**\r
152  * @brief   Producer Request States\r
153  */\r
154 typedef enum {\r
155   TF_PRODUCER_STATE_PROCESS_FREEZE_REQ = TF_REQUEST_PRODUCER_STATE_FREEZING\r
156   /**< Producer is processing freeze request */         \r
157 } tf_producerRequestState_e;\r
158 \r
159 \r
160 /**\r
161  * @brief Structure with producer config \r
162 */\r
163 typedef struct  prodConfig\r
164 {\r
165   char          name[128];\r
166   /**< name of the contract involving the producer */\r
167 \r
168   tf_contract_HANDLE   contract_handle;  \r
169   /**< contract handle to be associated with this producer ring */ \r
170 \r
171   uint8_t       oob_info[128];\r
172   /**< Out of Band information from the System */\r
173 \r
174   tf_producerTypes_e  prodType;\r
175   /**< producer type to be created */\r
176 \r
177   uint32_t  moduleId;\r
178   /**< producer unique moduleId from system */  \r
179 \r
180   void*     obj_handle;\r
181   /** object handle */\r
182 #ifdef TF_LINUX_USERSPACE  \r
183    uint32_t  crcApp16;\r
184    /**< CRC16 of the application, should be unique per application, supported only for ARM side producers  */  \r
185 #else\r
186    void            (*xchg_cb_fxn)(tf_producer_HANDLE phandle);\r
187    /**< buffer exchange call back function for application to trigger\r
188                    the notifications to the registered consumers by calling tf_prodNotifyConsumers() function (supported only for DSP side producers) */\r
189 #endif\r
190 \r
191 } tf_prodConfig_t;\r
192 \r
193 /**\r
194 @}\r
195 */\r
196 \r
197 /** @addtogroup TRACEFRAMEWORK_FUNCTIONS\r
198 @{\r
199 */\r
200 /**\r
201  * ============================================================================\r
202  *  @n@b tf_prodNotifyConsumers\r
203  *\r
204  *  @b  brief\r
205  *  @n  Each time a buffer exchange happens for that producer instance, the notifications needs to be \r
206  *        posted to all registered consumers for that producer.\r
207  *        This function identifies if there are any buffers in the ring buffer to be notified to the registered\r
208  *        consumers of that producer. \r
209  *        Few cases where this function can be called is in a background task  \r
210  *        or can be hooked to the buffer exchange done function for the producer where performance of the\r
211  *        buffer exchange is not so critical \r
212  *\r
213  *  @param[in]  pHandle\r
214  *      Pointer to the producer handle\r
215  *\r
216  *  @return\r
217  *      void\r
218  *\r
219  * =============================================================================\r
220  */\r
221 extern void tf_prodNotifyConsumers(tf_producer_HANDLE pHandle);\r
222 \r
223 /**\r
224  * ============================================================================\r
225  *  @n@b tf_prodUpdateConsumers\r
226  *\r
227  *  @b  brief\r
228  *  @n  The local producer instance would need to be synced to the footprints from the contract\r
229  *        This function can be called to syncrhonize the local producer instance to contrat.\r
230  *        @n Typical example of use: can be called periodically from a task/isr\r
231  *\r
232  *  @param[in]  p_handle\r
233  *      Pointer to the producer handle\r
234  *\r
235  *  @return\r
236  *      number of consumers in the producer contract\r
237  *\r
238  * =============================================================================\r
239  */\r
240 extern int32_t          tf_prodUpdateConsumers (tf_producer_HANDLE p_handle);\r
241 \r
242 /**\r
243  * ============================================================================\r
244  *  @n@b tf_prodDestroy\r
245  *\r
246  *  @b  brief\r
247  *  @n  frees up the producer instance created \r
248  *\r
249  *  @param[in]  pHandle\r
250  *      Pointer to the producer instance\r
251  *\r
252  *  @return\r
253  *      Status of the operation\r
254  *\r
255  * =============================================================================\r
256  */\r
257 extern tf_prodStatus_e  tf_prodDestroy(tf_producer_HANDLE pHandle);\r
258 \r
259 /**\r
260  * ============================================================================\r
261  *  @n@b tf_prodCreate\r
262  *\r
263  *  @b  brief\r
264  *  @n  Creates the local producer instance for a given contract\r
265  *\r
266  *  @param[in]  config\r
267  *      pointer to producer configuration information structure\r
268  *\r
269  *  @return\r
270  *      Handle to the producer \r
271  *\r
272  * =============================================================================\r
273  */\r
274 \r
275 extern tf_producer_HANDLE  tf_prodCreate(  tf_prodConfig_t   *config);\r
276 \r
277 /**\r
278  * ============================================================================\r
279  *  @n@b tf_prodGetCurBuf\r
280  *\r
281  *  @b  brief\r
282  *  @n  current ring buffer which producer is intended to write to.\r
283  *\r
284  *  @param[in]  pHandle\r
285  *      Producer Handle \r
286  *\r
287  *\r
288  *  @return\r
289  *      current buffer in use\r
290  *\r
291  * =============================================================================\r
292  */\r
293 \r
294 void* tf_prodGetCurBuf(tf_producer_HANDLE pHandle);\r
295 \r
296 /**\r
297  * ============================================================================\r
298  *  @n@b tf_prodBufExchange\r
299  *\r
300  *  @b  brief\r
301  *  @n  Implements the buffer exchange function interface for the LoggerStreamer  \r
302  *\r
303  *  @param[in]  pHandle\r
304  *      Producer Handle \r
305  *\r
306  *  @param[in]  full\r
307  *      filled log buffer \r
308  *\r
309  *  @return\r
310  *      next free log buffer \r
311  *\r
312  * =============================================================================\r
313  */\r
314 extern Ptr tf_prodBufExchange(tf_producer_HANDLE pHandle, uint8_t *full);\r
315 \r
316 /**\r
317  * ============================================================================\r
318  *  @n@b tf_prodSetOOBData\r
319  *\r
320  *  @b  brief\r
321  *  @n  sets the out of band (OOB) data from the application in the contract memory \r
322  *\r
323  *  @param[in]  cHandle\r
324  *      contract handle  \r
325  *\r
326  *  @param[in]  data\r
327  *      out of band (OOB) data  to be filled in the contrat memory\r
328  *\r
329  *  @return\r
330  *      void \r
331  *\r
332  * =============================================================================\r
333  */\r
334 \r
335 extern void tf_prodSetOOBData(tf_contract_HANDLE cHandle, uint8_t* data);\r
336 \r
337 /**\r
338  * ============================================================================\r
339  *  @n@b tf_prodGetOOBData\r
340  *\r
341  *  @b  brief\r
342  *  @n  Gets the out of band (OOB) data in the contract memory to the application\r
343  *\r
344  *  @param[in]  cHandle\r
345  *      contract handle  \r
346  *\r
347  *  @param[in]  data\r
348  *      out of band (OOB) data  read from the contrat memory\r
349  *\r
350  *  @return\r
351  *      void \r
352  *\r
353  * =============================================================================\r
354  */\r
355 \r
356 extern void tf_prodGetOOBData(tf_contract_HANDLE cHandle, uint8_t* data);\r
357 \r
358 /**\r
359  * ============================================================================\r
360  *  @n@b tf_prodGetContractHandle\r
361  *\r
362  *  @b  brief\r
363  *  @n  API to get the contract handle that is associated with the producer\r
364  *\r
365  *  @param[in]  pHandle\r
366  *      producer handle\r
367  *\r
368  *  @param[in]  contract_handle\r
369  *      Address of the contract handle to store\r
370  *  @return\r
371  *      Status of the operation\r
372  *\r
373  * =============================================================================\r
374  */\r
375 extern tf_prodStatus_e tf_prodGetContractHandle(tf_producer_HANDLE pHandle, tf_contract_HANDLE *contract_handle);\r
376 \r
377 /**\r
378 @}\r
379 */\r
380 \r
381 /* Below definitions are added for backwards compatibility */\r
382 #define GEN_NO_AVAILABLE_CONTRACT            TF_PRODUCER_NO_AVAILABLE_CONTRACT  \r
383 #define GEN_INVALID_CONTRACTHANDLE           TF_PRODUCER_INVALID_CONTRACT_HANDLE\r
384 #define GEN_INVALID_PRODID                   TF_PRODUCER_INVALID_PRODID\r
385 #define GEN_PROD_SUCCESS                     TF_PRODUCER_PROD_SUCCESS\r
386 #define GEN_MAX_SUPPORTED_CONSUMERS_REACHED  TF_PRODUCER_MAX_SUPPORTED_CONSUMERS_REACHED\r
387 #define GEN_PROD_FAIL                        TF_PRODUCER_PROD_FAIL\r
388 #define UIA_PROD_MAGIC_ID                    TF_PRODUCER_TYPE_UIA       \r
389 #define GEN_PROD_MAGIC_ID                    TF_PRODUCER_TYPE_GEN\r
390 #define UIA_MINST_PROD_MAGIC_ID              TF_PRODUCER_TYPE_UIA_MINST \r
391 #define CUIA_PROD_MAGIC_ID                   TF_PRODUCER_TYPE_CUIA\r
392 \r
393 #ifdef __cplusplus\r
394 }\r
395 #endif\r
396 \r
397 #endif /* __GEN_PRODUCER_H__ */\r
398 /* Nothing past this point */\r
399 \r