1 /**
2 * @file trace_contract.h
3 *
4 * @brief
5 * This has defintions and implementations for the contract between producers and consumers.
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 CONSPROD_CONTRACT_H_
41 #define CONSPROD_CONTRACT_H_
43 #ifdef __cplusplus
44 extern "C" {
45 #endif
48 #include <string.h>
49 /* OSAL Includes */
50 #include <ti/instrumentation/traceframework/contract_osal.h>
52 /** @addtogroup TRACEFRAMEWORK_SYMBOL
53 @{
54 */
56 /**
57 * @brief contract cache line size
58 */
59 #define TF_CONTRACT_CACHE_LINEZ 128
61 /**
62 * @brief contract memory size requirements
63 * contract has 12 cache lines
64 */
65 #define TF_CONTRACT_SIZE_BYTES (TF_CONTRACT_CACHE_LINEZ * 12)
67 /**
68 * @brief Alignment for the tf_contract memory
69 */
70 #define TF_CONTRACT_BUFS_ALIGN 128
72 /**
73 * @brief Ring Buffer Alignment
74 */
75 #define TF_PRODUCER_LOGBUF_ALGIN 128
77 /**
78 * @brief Maximum number of Ring buffers supported in the ring
79 */
80 #define TF_MAX_RING_BUFS_SUPPORT 1024
83 /**
84 * @brief maximum consumers allowed per contract
85 */
86 #define TF_MAX_CONSUMERS_PERCONTRACT 4
88 /**
89 * @brief number of bytes allocated for the Out of Band information
90 * Out of band information is really for the application to keep some information in the traceframework contract
91 * and retrive it from either producer/consumers as it is. Traceframework does not alter any information
92 * stored in
93 */
95 #define TF_CONTRACT_OOB_SIZE_BYTES TF_CONTRACT_CACHE_LINEZ
97 /**
98 * @brief number of bytes allocated for the name of the contract (applicable only for contract version 1)
99 * since contract version 2 does not handle name within traceframework
100 */
102 #define TF_CONTRACT_NAME_SIZE_BYTES TF_CONTRACT_CACHE_LINEZ
105 /**
106 * @defgroup tfCtrlBitMap Trace Framework Control Bit map Definitions
107 * @ingroup TRACEFRAMEWORK_API
108 * @{
109 *
110 * @name TraceFramework Control Bit Map Definitions
111 *
112 * Bitmap definition of the ctrlBitMap in @ref tf_StartCfg_t.
113 */
114 /*@{*/
115 /**
116 * @def tf_CONTRACT_BLK_ADDR_TYPE
117 * Control Info -- 0: The contract block (version 1) base is physical address
118 * 1: The contract block (version 1) base is virtual address
119 */
120 #define tf_CONTRACT_BLK_ADDR_TYPE 0x0001
123 /**
124 @}
125 */
127 /** @addtogroup TRACEFRAMEWORK_ENUM
128 @{
129 */
131 /**
132 * @brief Contract State added here
133 * When contracts are newly created, they are marked Available and
134 * as and when the contracts are used between producers and consumer
135 * instances, they would be marked as not available.
136 */
137 typedef enum {
138 TF_CONTRACT_AVAILABLE = 0x55555555,
139 /**< tf_contract slot is available */
140 TF_CONTRACT_NOT_AVAILABLE = 0x0
141 /**< tf_contract slot is not available */
142 }tf_contractState_e;
145 /**
146 * @brief Contract Versions added here
147 * Contract Version number signifies the set of APIs to be used
148 * There are few APIs marked in the traceframework functions, which are
149 * deprecated for contract version 1.
150 */
151 typedef enum {
153 TF_CONTRACT_VERSION_2 = 0x66666666,
154 /**< trace framework contract version 2 (no named contracts and they can be created as and when needed */
155 TF_CONTRACT_VERSION_1 = 0x0,
156 /**< trace framework contract version 1 (Legacy mode, all system contracts are named, and they are initialized
157 and created at one time and declared as AVAILABLE) */
158 TF_CONTRACT_VERSION_UNKNOWN = 0xf05d
159 /**< Unknown Contract Version which Trace Framework can not understand */
160 }tf_contractVersion_e;
162 /**
163 * @brief Contract Types added here
164 * Trace framework can support multiple contract types such as
165 * 1. Contracts having streaming producer always ( can have 4 consumers maximum)
166 * 2. Contracts having stream/freeze producer (supports only one consumer per contract)
167 */
168 typedef enum {
169 TF_CONTRACT_DSP_ARM = 0,
170 /**< tf_contract between DSP and ARM, where ARM has consumer for DSP producer */
171 TF_CONTRACT_STREAM_FREEZE_PRODUCER = TF_CONTRACT_DSP_ARM,
172 /**< tf_contract has stream/freeze producer, this is same as DSP ARM contract, kept for backwards compatibility */
173 TF_CONTRACT_ARM_ARM = 1
174 /**< tf_contract between ARM and ARM, where ARM has both producer and consumers */
175 }tf_contractType_e;
177 /**
178 * @brief Trace Framework Ring Buffer Address type
179 */
180 typedef enum {
182 TF_CONTRACT_RING_BUF_PHYSICAL_ADDR = 0,
183 /**< trace framework contract ring buffer address configured is physical memory */
184 TF_CONTRACT_RING_BUF_NOT_PHYSICAL_ADDR = 1
185 /**< trace framework contract ring buffer address configured is not physical memory */
186 }tf_ringBufAddrType_e;
188 /**
189 * @brief Trace Framework Contract Buffer Address type
190 */
191 typedef enum {
193 TF_CONTRACT_BUF_PHYSICAL_ADDR = 0,
194 /**< trace framework contract buffer address configured is physical memory */
195 TF_CONTRACT_BUF_NOT_PHYSICAL_ADDR = 1
196 /**< trace framework contract buffer address configured is not physical memory */
197 }tf_contractBufAddrType_e;
200 /**
201 @}
202 */
204 /** @addtogroup TRACEFRAMEWORK_DATASTRUCT
205 @{
206 */
208 /**
209 * @brief Contract handle
210 */
211 typedef void * tf_contract_HANDLE;
213 /**
214 * @brief Contract Create Configuration Structure
215 */
216 typedef struct tf_contractConfig
217 {
218 void* tf_contract_start_addr;
219 /**< Contract start address */
220 uint32_t num_contracts;
221 /**< Number of Contracts in the system */
222 void* ringbuf_start_addr;
223 /**< ringbuffer start address */
224 uint32_t num_ringbufs;
225 /**< Number of ring buffers in the tf_contract */
226 uint32_t ringbuf_size;
227 /**< size of each ring buffer */
228 tf_ringBufAddrType_e ring_base_type;
229 /**< is the ring buffer base address configured physical ? */
230 tf_contractBufAddrType_e contract_base_type;
231 /**< is the contract base virtual or physical */
232 tf_contractType_e contractType;
233 /**< type of the contract to be created */
234 int32_t producer_state;
235 /**< Initial state of the producer to begin with */
236 } tf_contractConfig_t;
239 /**
240 * @brief trace framework start configuration structure (to support multi-instance and legacy features)
241 */
242 typedef struct {
243 void* instPoolBaseAddr; /**< Base address of the global shared memory pool from which global
244 LLD instance & channel instance memory is allocated */
245 uint32_t instPoolSize; /**< Pool size of the global shared memory */
246 uint32_t ctrlBitMap; /**< Control bit map @ref tfCtrlBitMap */
247 } tf_StartCfg_t;
250 /**
251 * @brief get trace framework contract information interface structure
252 */
253 typedef struct {
254 tf_contractType_e contractType; /**< contract type */
255 uint32_t num_consumers; /**< total number of current consumers registered in the contract */
256 uint32_t overrun_count; /**< producer's over run count on the ring buffers */
257 uint32_t rb_wrap_flag; /**< Contract ring buffer wrap around or not */
258 uint32_t contractState; /**< tf_contract state */
259 uint32_t contractVersion; /**< tf_contract version */
260 uint32_t consumerAppRetryCount[TF_MAX_CONSUMERS_PERCONTRACT]; /**< number of times consumer application send function could not consume buffers */
261 uint8_t* ringbuffer_base; /**< ring buffer base for the tf_contract */
262 uint32_t num_ringbuf; /**< number of ring buffers */
263 uint32_t ringbuffer_size; /**< ring buffer size */
264 tf_ringBufAddrType_e ring_base_type; /**< is the ring buffer base address configured virtual Or physical @ref tf_ringBufAddrType_e */
265 uint32_t producer_index; /** < producer current index in the ring buffer */
266 uint32_t producer_current_state; /**< producer state */
267 } tf_contractGetInfo_t;
270 /**
271 @}
272 */
274 /** @addtogroup TRACEFRAMEWORK_FUNCTIONS
275 @{
276 */
278 /**
279 * ============================================================================
280 * @n@b tf_contractInit
281 *
282 * @b brief
283 * @n initializes the tf_contract as avilable for producer/consumer
284 * @n@b WARNING: @n - deprecated with contract version TRACE_CONTRACT_VERSION_2
285 * @n This is the very first API that needs to be called by an one time entity
286 * to initialze all the contract memory that system can use and declare them
287 * as available
288 *
289 * @param[in] tf_contract_base
290 * Pointer to the base address of the tf_contract array
291 *
292 * @param[in] num
293 * number of tf_contract buffers
294 *
295 * @return
296 * none
297 *
298 * =============================================================================
299 */
300 void tf_contractInit(void* tf_contract_base, uint32_t num);
302 /**
303 * ============================================================================
304 * @n@b tf_contractCreate
305 *
306 * @b brief
307 * @n sets up initial values for producer/consumer
308 * @n@b WARNING: @n- deprecated with contract version TRACE_CONTRACT_VERSION_2
309 * @n Since the contracts are required to be created sequentially in memory,
310 * there needs to be a protection in the API call to make sure no two
311 * contracts are created in the same slot. This is accomplished with an
312 * OSAL call out TF_CONTRACT_osalEnter() function, which blocks this function
313 * if being used to create a contract from multi core environment.
314 *
315 * @param[in] tf_contractConfig
316 * tf_contract configuration structure - needs knowledge about the contract
317 * base address, number of contracts in the system, ring buffer size, ring
318 * buffer start address and number of ring buffers.
319 *
320 * @param[in] name
321 * Pointer to the name of the tf_contract
322 *
323 * @return
324 * Trace Framework Contract Handle
325 *
326 * =============================================================================
327 */
328 tf_contract_HANDLE tf_contractCreate(tf_contractConfig_t tf_contractConfig, char* name);
330 /**
331 * ============================================================================
332 * @n@b tf_newContract
333 *
334 * @b brief
335 * @n API added to create the contract between producer/consumer instances
336 * This API is applicable for the contract version TRACE_CONTRACT_VERSION_2
337 * Application needs to maintain any names associated with this contract handle
338 * outside traceframework
339 *
340 * @param[in] tf_contractConfig
341 * tf_contract configuration structure
342 *
343 * @return
344 * Contract Handle
345 *
346 * =============================================================================
347 */
348 tf_contract_HANDLE tf_newContract(tf_contractConfig_t tf_contractConfig);
352 /**
353 * ============================================================================
354 * @n@b tf_contractFind
355 *
356 * @b brief
357 * @n finds the tf_contract based on the name
358 * @n@b WARNING: @n - deprecated with contract version TRACE_CONTRACT_VERSION_2
359 *
360 * @param[in] tf_contract_start_addr
361 * tf_contract start address
362 *
363 * @param[in] num_contracts
364 * number of contracts in the system
365 *
366 * @param[in] name
367 * Pointer to the name of the tf_contract
368 *
369 * @return
370 * Contract Handle
371 *
372 * =============================================================================
373 */
374 tf_contract_HANDLE tf_contractFind (void* tf_contract_start_addr, uint32_t num_contracts, char* name);
377 /**
378 * ============================================================================
379 * @n@b tf_getOverRunCount
380 *
381 * @b brief
382 * @n Gets the cumulative count of how many times the ring is overrun resulting in same
383 * last filled buffer
384 *
385 * Application Requriments:
386 * Application need to save the current overrun count in some context memory for that
387 * contract handle
388 * Application needs to compare the latest cumulative overrun count retuned by the
389 * above API with earlier sampled value to decide the congestion.
390 *
391 * @param[in] contract_handle
392 * contract handle
393 *
394 * @return
395 * Returns the cumulative count of how many times the ring is overrun resulting in same last filled buffer
396 *
397 * =============================================================================
398 */
399 uint32_t tf_getOverRunCount(tf_contract_HANDLE contract_handle);
401 /**
402 * ============================================================================
403 * @n@b tf_isLogInfoNextBuf
404 *
405 * @b brief
406 * @n Gets the flag to indicate if the logging information starts from first buffer
407 * or next buffer
408 *
409 * Application Requirements:
410 * Application would need to create valid contract handle before calling this function
411 * @param[in] contract_handle
412 * contract handle
413 *
414 * @return
415 * Returns the flag to indicate if the wrap around happened in the ring buffer
416 * during the production. If this flag is set, indicates the wrap around hence
417 * the logger information needs to be read from next buffer, otherwise it needs
418 * to be read from first ring buffer.
419 *
420 * =============================================================================
421 */
422 uint32_t tf_isLogInfoNextBuf (tf_contract_HANDLE contract_handle);
424 /**
425 * ============================================================================
426 * @n@b tf_contractGetInfo
427 *
428 * @b brief
429 * @n gets contract information details
430 *
431 * Application Requirements:
432 * Application would need to create valid contract handle before calling this function
433 * @param[in] handle
434 * trace framework contract handle
435 *
436 * @param[in] info
437 * contract information returned
438 *
439 * @return
440 * none
441 *
442 * =============================================================================
443 */
444 void tf_contractGetInfo(tf_contract_HANDLE handle, tf_contractGetInfo_t* info);
446 /**
447 * ============================================================================
448 * @n@b tf_systemCfg
449 *
450 * @b brief
451 * @n starts the system with start configurations
452 *
453 * Application Requirements:
454 * Application would need to call this API once per process/core with proper startCfg arguments
455 * before Contract Create, Produer Create and Consumer Create functions
456 *
457 * @param[in] startCfg
458 * start configuration structure
459 *
460 * @return
461 * none
462 *
463 * =============================================================================
464 */
465 void tf_systemCfg (tf_StartCfg_t *startCfg);
467 /**
468 @}
469 */
471 /* Define below function alias names for backward compatibility */
472 tf_contract_HANDLE TF_CONTRACT_CREATE(tf_contractConfig_t tf_contractConfig, char* name);
473 void TF_CONTRACT_INIT(void* tf_contract_base, uint32_t num);
474 tf_contract_HANDLE TF_NEW_CONTRACT(tf_contractConfig_t tf_contractConfig);
475 tf_contract_HANDLE TF_CONTRACT_FIND (void* tf_contract_start_addr, uint32_t num_contracts, char* name);
476 uint32_t tf_get_overrun_count(tf_contract_HANDLE contract_handle);
477 uint32_t tf_is_logInfo_next_buf(tf_contract_HANDLE handle);
479 /* below is kept for backwards compatibility */
480 #define TRACE_CONTRACT_VERSION_2 TF_CONTRACT_VERSION_2
481 #define TRACE_CONTRACT_VERSION_1 TF_CONTRACT_VERSION_1
482 #define TRACE_CONTRACT_AVAILABLE TF_CONTRACT_AVAILABLE
483 #define TRACE_CONTRACT_NOT_AVAILABLE TF_CONTRACT_NOT_AVAILABLE
485 /* Local Errno for Trace Framework */
486 #define TF_ERRNO_BASE -128
487 #define TF_ERRNO_NO_CONTRACT_FOUND (TF_ERRNO_BASE + 1)
488 #define TF_ERRNO_ALL_CONTRACTS_FULL (TF_ERRNO_NO_CONTRACT_FOUND + 1)
489 #define TF_ERRNO_CONSUMER_ALLOC_FAIL (TF_ERRNO_ALL_CONTRACTS_FULL + 1)
490 #define TF_ERRNO_CONSUMER_INVALID_CONFIG_PARAMS (TF_ERRNO_CONSUMER_ALLOC_FAIL + 1)
491 #define TF_ERRNO_NULL_RING_BUFFER_FOUND (TF_ERRNO_CONSUMER_INVALID_CONFIG_PARAMS + 1)
492 #define TF_ERRNO_MAX_RING_BUFFER_REACHED (TF_ERRNO_NULL_RING_BUFFER_FOUND + 1)
493 #define TF_ERRNO_INVALID_CONSUMER_HANDLE (TF_ERRNO_MAX_RING_BUFFER_REACHED + 1)
494 #define TF_ERRNO_INVALID_PRODUCER_HANDLE (TF_ERRNO_INVALID_CONSUMER_HANDLE + 1)
495 #define TF_ERRNO_MAX_NUM_CONSUMERS_REACHED (TF_ERRNO_INVALID_PRODUCER_HANDLE + 1)
496 #define TF_ERRNO_UNEXPECTED_NUM_CONSUMERS (TF_ERRNO_MAX_NUM_CONSUMERS_REACHED + 1)
497 #define TF_ERRNO_PRODUCER_ALLOC_FAIL (TF_ERRNO_UNEXPECTED_NUM_CONSUMERS + 1)
498 #define TF_ERRNO_INVALID_CONTRACT_HANDLE (TF_ERRNO_PRODUCER_ALLOC_FAIL + 1)
499 #define TF_ERRNO_INVALID_CONTRACT_ELEMENTS (TF_ERRNO_INVALID_CONTRACT_HANDLE + 1)
500 #define TF_ERRNO_SYNC_LOCK_ERROR_HANDLE (TF_ERRNO_INVALID_CONTRACT_ELEMENTS + 1)
501 #define TF_ERRNO_SYNC_LOCK_ERROR_USER_ID (TF_ERRNO_SYNC_LOCK_ERROR_HANDLE + 1)
502 #define TF_ERRNO_SYNC_LOCK_ERROR_DBL_LOCK (TF_ERRNO_SYNC_LOCK_ERROR_USER_ID + 1)
503 #define TF_ERRNO_SYNC_LOCK_ERROR_DBL_UNLOCK (TF_ERRNO_SYNC_LOCK_ERROR_DBL_LOCK + 1)
506 #ifdef __cplusplus
507 }
508 #endif
510 #endif /* CONSPROD_CONTRACT_H_ */
512 /* Nothing past this point */