Merge pull request #3 in PROCESSOR-SDK/traceframework from CATREQ-2702 to master
[keystone-rtos/traceframework.git] / consumer.h
1 /**
2  *   @file  consumer.h
3  *
4  *   @brief   
5  *      This is a very slim consumer framework library implementation.
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 */
39  
40 #ifndef __CONSUMER_H__
41 #define __CONSUMER_H__
43 #ifdef __cplusplus
44 extern "C" {
45 #endif
47 /* CPPI include files */
48 #include <ti/instrumentation/traceframework/trace_contract.h>
50 /** @addtogroup TRACEFRAMEWORK_ENUM
51 @{
52 */
54 /**
55  * @brief Trace framework Producer-Consumer NOTIFY types 
56  */
57 typedef enum {
58   TF_CONSUMER_NOTIFY_VIA_REGMASK    = 0x0,
59   /**< Notify the consumer task in the application with IPC kind of mechanism */
60   TF_CONSUMER_NOTIFY_VIA_LOCCBK     = 0x1,
61   /**< notify the task using a local call back function */
62   TF_CONSUMER_NOTIFY_NONE           = 0x2,
63   /**< no notify method, consumers can have their own method to check for new buffers */
64   TF_CONSUMER_NOTIFY_VIA_LOCCBK2    = 0x3
65   /**< notify the task using a local call back2 function */  
66 } tf_notifyTypes_e;
68 /**
69  * @brief  Enumerations showing the consumer status
70  */
71 typedef enum consStatus 
72 {
73   TF_CONSUMER_NO_AVAILABLE_CONTRACT = 0,
74   /**< No avilable contract for the consumer */
75   TF_CONSUMER_INVALID_ARGUMENTS,
76   /**< Invalid arguments are passed for the consumer */
77   TF_CONSUMER_SUCCESS,
78   /**< Success in consumer operations */
79   TF_CONSUMER_FAIL,
80   /**< failure in consumer operations */
81   TF_CONSUMER_WAIT_ACK,
82   /**< Consumer is busy in the operation, waiting for the Ack */
83   TF_CONSUMER_ACK_RECIVED,
84   /**< Consumer got the ACK from the System */
85   TF_CONSUMER_NOTHING_TO_CONSUME,  
86   /**< nothing to consume in consumer operations */
87   TF_CONSUMER_INVALID_HANDLE,
88   /**< Invalid consumer handle is provided */
89   TF_CONSUMER_INVALID_CONTRACT_HANDLE
90   /**< Invalid contract handle is noticed in consumer instance */  
91 } tf_consStatus_e;
93 /**
94  * @brief  Enumerations showing the application send information to 
95  *         the traceframework library
96  */
97 typedef enum consAppSendRespStatus
98 {
99     TF_CONSUMER_APP_SEND_OK_WAIT_ACK,
100   /**< Application sent the passed buffer succesfully and frees up the buffer for the library during ACK */        
101     TF_CONSUMER_APP_SEND_OK_NO_WAIT_ACK,
102   /**< Application sent the passed buffer succesfully and frees up the buffer for the library immediately */            
103     TF_CONSUMER_APP_SEND_NOK_RETRY
104   /**< Application did not sent the passed buffer succesfully and would like to retry sometime later in time */            
105 }tf_consAppSendRespStatus_e;
107 /**
108 @}
109 */
111 /** @addtogroup TRACEFRAMEWORK_DATASTRUCT
112 @{
113 */
115 /**
116  * @brief   Consumer Handle
117  */
118 typedef void*  tf_cons_HANDLE;
120 /* re-define for consistancy */
121 #define  tf_consumer_HANDLE tf_cons_HANDLE
123 /**
124  * @brief Consumer Notify glue structure 
125  */
126 typedef struct consRegNotify
128   uint32_t                  reg_addr;
129   /**< register address e.g, IPCGR regisers for IPC communication*/
130   uint32_t                  reg_mask;
131   /**< register value to be written */
132 } tf_consRegNotify_t;
134 /**
135  * @brief Consumer Notify Structure (IPC kind or Local Call back 
136  */
137 typedef struct consNotify
139   uint32_t              notify_method;
140   /**< Notify method for the consumer */
141   union 
142   {
143     tf_consRegNotify_t     notify_reg; 
144         /** < notifications are expected to be done via Register masks, like IPCGRx */
145     int32_t                 (*notify_callbk)(uint32_t ringbuf_index);
146         /** < notifications are expected to be done via local call back function */
147     int32_t                 (*notify_callbk2)(tf_consumer_HANDLE loc_handle);   
148         /** < notifications are expected to be done via local call back function, added new parameter of local_handle */
149   } notifyScheme;
150 } tf_consNotify_t;
152 /**
153  * @brief Structure with consumer NetCp config 
154  */
155 typedef struct consConfig
157   tf_contract_HANDLE       contract_handle;
158   /**< contract handle to be used by the consumer */
159   tf_consNotify_t      consumer_notify;
160   /**< consumer notify information structure */
161   tf_consAppSendRespStatus_e   (*sendFxn)(uint32_t param, uint8_t* buf, uint32_t len);
162   /**< transport send function, sends the buffer using the transport
163     * Note: If sendFxn() function implementation decides to call tf_consAck() within, 
164     * it shall do this just before the return to avoid the recursion complications */
165   uint32_t            param;
166   /**< parameter value used by the application */       
167 } tf_consConfig_t;
169 /**
170 @}
171 */
173 /** @addtogroup TRACEFRAMEWORK_FUNCTIONS
174 @{
175 */
177 /**
178  * ============================================================================
179  *  @n@b tf_isThereToConsume
180  *
181  *  @b  brief
182  *  @n  Checks the consumer if there is anything to consume
183  *
184  *  @param[in]  cHandle
185  *      consumer handle
186  *
187  *  @return
188  *      Number of buffers to be consumed
189  *
190  * =============================================================================
191  */
192 extern uint32_t tf_isThereToConsume(tf_consumer_HANDLE cHandle);
193 extern uint32_t tf_isthere_to_consume (tf_consumer_HANDLE cHandle);
195 /**
196  * ============================================================================
197  *  @n@b tf_consProcess
198  *
199  *  @b  brief
200  *  @n  this triggers consumers to look into contract and see if there are any
201  *      new buffers available to ship to the transport
202  *
203  *  @param[in]  cHandle
204  *      Pointer to the consumer handle
205  *
206  *  @return
207  *      Status of the operation
208  *
209  * =============================================================================
210  */
212 extern tf_consStatus_e tf_consProcess(tf_consumer_HANDLE cHandle);
214 /**
215  * ============================================================================
216  *  @n@b tf_consAck
217  *
218  *  @b  brief
219  *  @n  This acknowledges the consumer buffer send and triggers the index advance
220  *
221  *  @param[in]  cHandle
222  *      Pointer to the consumer handle
223  *
224  *  @return
225  *      Status of the operation
226  *
227  * =============================================================================
228  */
230 extern tf_consStatus_e tf_consAck(tf_consumer_HANDLE cHandle);
232 /**
233  * ============================================================================
234  *  @n@b tf_consDestroy
235  *
236  *  @b  brief
237  *  @n  this clears the consumer attached to the contract
238  *
239  *  @param[in]  cHandle
240  *      Pointer to the consumer handle
241  *
242  *  @return
243  *      Status of the operation
244  *
245  * =============================================================================
246  */
248 extern tf_consStatus_e tf_consDestroy(tf_consumer_HANDLE cHandle);
250 /**
251  * ============================================================================
252  *  @n@b tf_consCreate
253  *
254  *  @b  brief
255  *  @n  Creates the consumer instance on the trace framework
256  *
257  *  @param[in]  config
258  *      consumer creation configuration
259  *
260  *  @return
261  *      Status of the operation
262  *
263  * =============================================================================
264  */
265 extern tf_consumer_HANDLE tf_consCreate(tf_consConfig_t   *config);
267 /**
268  * ============================================================================
269  *  @n@b tf_consumerForceFreezeProducer
270  *
271  *  @b  brief
272  *  @n  API to force freeze the produer to frozen state
273  *      Keeping the in the frozen state for producer triggers the same ring buffer
274  *      to be returned for the buffer exchange
275  *
276  *  @param[in]  cHandle
277  *      consumer handle
278  *
279  *  @return
280  *      Status of the operation
281  *
282  * =============================================================================
283  */
284 extern tf_consStatus_e tf_consumerForceFreezeProducer(tf_cons_HANDLE cHandle);
286 /**
287  * ============================================================================
288  *  @n@b tf_consumerGetContractHandle
289  *
290  *  @b  brief
291  *  @n  API to get the contract handle that is associated with the consumer
292  *
293  *  @param[in]  cHandle
294  *      consumer handle
295  *
296  *  @param[in]  contract_handle
297  *      Address of the contract handle to store
298  *  @return
299  *      Status of the operation
300  *
301  * =============================================================================
302  */
303 extern tf_consStatus_e tf_consumerGetContractHandle(tf_cons_HANDLE cHandle, tf_contract_HANDLE *contract_handle);
306 /**
307  * ============================================================================
308  *  @n@b tf_alignConsumer2FrozenProd
309  *
310  *  @b  brief
311  *  @n  API to align the internal data information on consumers when producer is responded
312  *      back as frozen. This API needs to be called first after we detect producer is frozen
313  *      before calling tf_consProcess API
314  *
315  *  @param[in]  cHandle
316  *      consumer handle
317  *
318  *  @return
319  *      Status of the operation
320  *
321  * =============================================================================
322  */
323 extern tf_consStatus_e tf_alignConsumer2FrozenProd(tf_consumer_HANDLE cHandle);
324 /**
325 @}
326 */
328 /* Below defines are added for backwards compatibility */
329 #define CONS_APP_SEND_OK_WAIT_ACK      TF_CONSUMER_APP_SEND_OK_WAIT_ACK
330 #define CONS_APP_SEND_OK_NO_WAIT_ACK   TF_CONSUMER_APP_SEND_OK_NO_WAIT_ACK
331 #define CONS_APP_SEND_NOK_RETRY        TF_CONSUMER_APP_SEND_NOK_RETRY
332 #define CONSUMER_NO_AVAILABLE_CONTRACT TF_CONSUMER_NO_AVAILABLE_CONTRACT
333 #define CONSUMER_INVALID_ARGUMENTS     TF_CONSUMER_INVALID_ARGUMENTS
334 #define CONSUMER_SUCCESS               TF_CONSUMER_SUCCESS
335 #define CONSUMER_FAIL                  TF_CONSUMER_FAIL
336 #define CONSUMER_WAIT_ACK              TF_CONSUMER_WAIT_ACK
337 #define CONSUMER_ACK_RECIVED           TF_CONSUMER_ACK_RECIVED
338 #define CONSUMER_NOTHING_TO_CONSUME    TF_CONSUMER_NOTHING_TO_CONSUME 
339 #define NOTIFY_VIA_REGMASK             TF_CONSUMER_NOTIFY_VIA_REGMASK   
340 #define NOTIFY_VIA_LOCCBK              TF_CONSUMER_NOTIFY_VIA_LOCCBK
341 #define NOTIFY_NONE                    TF_CONSUMER_NOTIFY_NONE
343 #ifdef __cplusplus
345 #endif
347 #endif /* __CONSUMER_H__ */