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__
  42
  43 #ifdef __cplusplus
  44 extern "C" {
  45 #endif
  46
  47 /* CPPI include files */
  48 #include <ti/instrumentation/traceframework/trace_contract.h>
  49
  50 /** @addtogroup TRACEFRAMEWORK_ENUM
  51 @{
  52 */
  53
  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;
  67
  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;
  92
  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;
 106
 107 /**
 108 @}
 109 */
 110
 111 /** @addtogroup TRACEFRAMEWORK_DATASTRUCT
 112 @{
 113 */
 114
 115 /**
 116  * @brief   Consumer Handle
 117  */
 118 typedef void*  tf_cons_HANDLE;
 119
 120 /* re-define for consistancy */
 121 #define  tf_consumer_HANDLE tf_cons_HANDLE
 122
 123 /**
 124  * @brief Consumer Notify glue structure
 125  */
 126 typedef struct consRegNotify
 127 {
 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;
 133
 134 /**
 135  * @brief Consumer Notify Structure (IPC kind or Local Call back
 136  */
 137 typedef struct consNotify
 138 {
 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;
 151
 152 /**
 153  * @brief Structure with consumer NetCp config
 154  */
 155 typedef struct consConfig
 156 {
 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;
 168
 169 /**
 170 @}
 171 */
 172
 173 /** @addtogroup TRACEFRAMEWORK_FUNCTIONS
 174 @{
 175 */
 176
 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);
 194
 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  */
 211
 212 extern tf_consStatus_e tf_consProcess(tf_consumer_HANDLE cHandle);
 213
 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  */
 229
 230 extern tf_consStatus_e tf_consAck(tf_consumer_HANDLE cHandle);
 231
 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  */
 247
 248 extern tf_consStatus_e tf_consDestroy(tf_consumer_HANDLE cHandle);
 249
 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);
 266
 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);
 285
 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);
 304
 305
 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 */
 327
 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
 342
 343 #ifdef __cplusplus
 344 }
 345 #endif
 346
 347 #endif /* __CONSUMER_H__ */
 348
 349