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 */
  39
  40 #ifndef CONSPROD_CONTRACT_H_
  41 #define CONSPROD_CONTRACT_H_
  42
  43 #ifdef __cplusplus
  44 extern "C" {
  45 #endif
  46
  47
  48 #include <string.h>
  49 /* OSAL Includes */
  50 #include <ti/instrumentation/traceframework/contract_osal.h>
  51
  52 /** @addtogroup TRACEFRAMEWORK_SYMBOL
  53 @{
  54 */
  55
  56 /**
  57  * @brief   contract cache line size
  58  */
  59 #define  TF_CONTRACT_CACHE_LINEZ             128
  60
  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)
  66
  67 /**
  68  * @brief   Alignment for the tf_contract memory
  69  */
  70 #define  TF_CONTRACT_BUFS_ALIGN                 128
  71
  72 /**
  73  * @brief   Ring Buffer Alignment
  74  */
  75 #define TF_PRODUCER_LOGBUF_ALGIN                128
  76
  77 /**
  78  * @brief   Maximum number of Ring buffers supported in the ring
  79  */
  80 #define  TF_MAX_RING_BUFS_SUPPORT               1024
  81
  82
  83 /**
  84  * @brief   maximum consumers allowed per contract
  85  */
  86 #define  TF_MAX_CONSUMERS_PERCONTRACT             4
  87
  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  */
  94
  95 #define  TF_CONTRACT_OOB_SIZE_BYTES             TF_CONTRACT_CACHE_LINEZ
  96
  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  */
 101
 102 #define  TF_CONTRACT_NAME_SIZE_BYTES            TF_CONTRACT_CACHE_LINEZ
 103
 104
 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
 121
 122
 123 /**
 124 @}
 125 */
 126
 127 /** @addtogroup TRACEFRAMEWORK_ENUM
 128 @{
 129 */
 130
 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;
 143
 144
 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 {
 152
 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;
 161
 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;
 176
 177 /**
 178  * @brief Trace Framework Ring Buffer Address type
 179  */
 180 typedef enum {
 181
 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;
 187
 188 /**
 189  * @brief Trace Framework Contract Buffer Address type
 190  */
 191 typedef enum {
 192
 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;
 198
 199
 200 /**
 201 @}
 202 */
 203
 204 /** @addtogroup TRACEFRAMEWORK_DATASTRUCT
 205 @{
 206 */
 207
 208 /**
 209  * @brief   Contract handle
 210  */
 211 typedef void *  tf_contract_HANDLE;
 212
 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;
 237
 238
 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;
 248
 249
 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;
 268
 269
 270 /**
 271 @}
 272 */
 273
 274 /** @addtogroup TRACEFRAMEWORK_FUNCTIONS
 275 @{
 276 */
 277
 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);
 329
 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);
 349
 350
 351
 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);
 375
 376
 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);
 400
 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);
 423
 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);
 445
 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);
 466
 467 /**
 468 @}
 469 */
 470
 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);
 478
 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
 484
 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)
 504
 505
 506 #ifdef __cplusplus
 507 }
 508 #endif
 509
 510 #endif /* CONSPROD_CONTRACT_H_ */
 511
 512 /* Nothing past this point */
 513