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