Merge pull request #3 in PROCESSOR-SDK/traceframework from CATREQ-2702 to master
[keystone-rtos/traceframework.git] / trace_contract.h
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
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);
301     
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);
350     
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
508 #endif
510 #endif /* CONSPROD_CONTRACT_H_ */
512 /* Nothing past this point */