Functions
Trace Framework Functions
Trace Framework Control Bit map Definitions

Functions

uint32_t tf_isThereToConsume (tf_consumer_HANDLE cHandle)
tf_consStatus_e tf_consProcess (tf_consumer_HANDLE cHandle)
tf_consStatus_e tf_consAck (tf_consumer_HANDLE cHandle)
tf_consStatus_e tf_consDestroy (tf_consumer_HANDLE cHandle)
tf_consumer_HANDLE tf_consCreate (tf_consConfig_t config)
tf_consStatus_e tf_consumerForceFreezeProducer (tf_cons_HANDLE cHandle)
tf_consStatus_e tf_consumerGetContractHandle (tf_cons_HANDLE cHandle, tf_contract_HANDLE *contract_handle)
tf_consStatus_e tf_alignConsumer2FrozenProd (tf_consumer_HANDLE cHandle)
void tf_prodNotifyConsumers (tf_producer_HANDLE pHandle)
int32_t tf_prodUpdateConsumers (tf_producer_HANDLE p_handle)
tf_prodStatus_e tf_prodDestroy (tf_producer_HANDLE pHandle)
tf_producer_HANDLE tf_prodCreate (tf_prodConfig_t config)
void * tf_prodGetCurBuf (tf_producer_HANDLE pHandle)
Ptr tf_prodBufExchange (tf_producer_HANDLE pHandle, uint8_t *full)
void tf_prodSetOOBData (tf_contract_HANDLE cHandle, uint8_t *data)
void tf_prodGetOOBData (tf_contract_HANDLE cHandle, uint8_t *data)
tf_prodStatus_e tf_prodGetContractHandle (tf_producer_HANDLE pHandle, tf_contract_HANDLE *contract_handle)
void tf_contractInit (void *tf_contract_base, uint32_t num)
tf_contract_HANDLE tf_contractCreate (tf_contractConfig_t tf_contractConfig, char *name)
tf_contract_HANDLE tf_newContract (tf_contractConfig_t tf_contractConfig)
tf_contract_HANDLE tf_contractFind (void *tf_contract_start_addr, uint32_t num_contracts, char *name)
uint32_t tf_getOverRunCount (tf_contract_HANDLE contract_handle)
uint32_t tf_isLogInfoNextBuf (tf_contract_HANDLE contract_handle)
void tf_contractGetInfo (tf_contract_HANDLE handle, tf_contractGetInfo_t *info)
void tf_systemCfg (tf_StartCfg_t *startCfg)
tf_consStatus_e tf_consumerSetProducerState (tf_cons_HANDLE cHandle, tf_producerState_e state)
tf_producerState_e tf_consumerGetProducerState (tf_cons_HANDLE cHandle)

Function Documentation

tf_consStatus_e tf_alignConsumer2FrozenProd ( tf_consumer_HANDLE  cHandle)

============================================================================
tf_alignConsumer2FrozenProd

brief
API to align the internal data information on consumers when producer is responded back as frozen. This API needs to be called first after we detect producer is frozen before calling tf_consProcess API

Parameters:
[in]cHandleconsumer handle
Returns:
Status of the operation

=============================================================================

tf_consStatus_e tf_consAck ( tf_consumer_HANDLE  cHandle)

============================================================================
tf_consAck

brief
This acknowledges the consumer buffer send and triggers the index advance

Parameters:
[in]cHandlePointer to the consumer handle
Returns:
Status of the operation

=============================================================================

tf_consumer_HANDLE tf_consCreate ( tf_consConfig_t  config)

============================================================================
tf_consCreate

brief
Creates the consumer instance on the trace framework

Parameters:
[in]configconsumer creation configuration
Returns:
Status of the operation

=============================================================================

tf_consStatus_e tf_consDestroy ( tf_consumer_HANDLE  cHandle)

============================================================================
tf_consDestroy

brief
this clears the consumer attached to the contract

Parameters:
[in]cHandlePointer to the consumer handle
Returns:
Status of the operation

=============================================================================

tf_consStatus_e tf_consProcess ( tf_consumer_HANDLE  cHandle)

============================================================================
tf_consProcess

brief
this triggers consumers to look into contract and see if there are any new buffers available to ship to the transport

Parameters:
[in]cHandlePointer to the consumer handle
Returns:
Status of the operation

=============================================================================

============================================================================
tf_consumerForceFreezeProducer

brief
API to force freeze the produer to frozen state Keeping the in the frozen state for producer triggers the same ring buffer to be returned for the buffer exchange

Parameters:
[in]cHandleconsumer handle
Returns:
Status of the operation

=============================================================================

============================================================================
tf_consumerGetContractHandle

brief
API to get the contract handle that is associated with the consumer

Parameters:
[in]cHandleconsumer handle
[in]contract_handleAddress of the contract handle to store
Returns:
Status of the operation

=============================================================================

============================================================================
tf_consumerGetProducerState

brief
API to sample the current producer state

Parameters:
[in]cHandleconsumer handle
Returns:
Current sampled producer state in the contract

=============================================================================

============================================================================
tf_consumerSetProducerState

brief
API to set the producer state to either streaming, free run or freeze

Parameters:
[in]cHandleconsumer handle
[in]stateintended producer state change
Returns:
Status of the operation

=============================================================================

tf_contract_HANDLE tf_contractCreate ( tf_contractConfig_t  tf_contractConfig,
char *  name 
)

============================================================================
tf_contractCreate

brief
sets up initial values for producer/consumer
WARNING:
- deprecated with contract version TRACE_CONTRACT_VERSION_2
Since the contracts are required to be created sequentially in memory, there needs to be a protection in the API call to make sure no two contracts are created in the same slot. This is accomplished with an OSAL call out TF_CONTRACT_osalEnter() function, which blocks this function if being used to create a contract from multi core environment.

Parameters:
[in]tf_contractConfigtf_contract configuration structure - needs knowledge about the contract base address, number of contracts in the system, ring buffer size, ring buffer start address and number of ring buffers.
[in]namePointer to the name of the tf_contract
Returns:
Trace Framework Contract Handle

=============================================================================

tf_contract_HANDLE tf_contractFind ( void *  tf_contract_start_addr,
uint32_t  num_contracts,
char *  name 
)

============================================================================
tf_contractFind

brief
finds the tf_contract based on the name
WARNING:
- deprecated with contract version TRACE_CONTRACT_VERSION_2

Parameters:
[in]tf_contract_start_addrtf_contract start address
[in]num_contractsnumber of contracts in the system
[in]namePointer to the name of the tf_contract
Returns:
Contract Handle

=============================================================================

============================================================================
tf_contractGetInfo

brief
gets contract information details

Application Requirements: Application would need to create valid contract handle before calling this function

Parameters:
[in]handletrace framework contract handle
[in]infocontract information returned
Returns:
none

=============================================================================

void tf_contractInit ( void *  tf_contract_base,
uint32_t  num 
)

============================================================================
tf_contractInit

brief
initializes the tf_contract as avilable for producer/consumer
WARNING:
- deprecated with contract version TRACE_CONTRACT_VERSION_2
This is the very first API that needs to be called by an one time entity to initialze all the contract memory that system can use and declare them as available

Parameters:
[in]tf_contract_basePointer to the base address of the tf_contract array
[in]numnumber of tf_contract buffers
Returns:
none

=============================================================================

uint32_t tf_getOverRunCount ( tf_contract_HANDLE  contract_handle)

============================================================================
tf_getOverRunCount

brief
Gets the cumulative count of how many times the ring is overrun resulting in same last filled buffer

Application Requriments: Application need to save the current overrun count in some context memory for that contract handle Application needs to compare the latest cumulative overrun count retuned by the above API with earlier sampled value to decide the congestion.

Parameters:
[in]contract_handlecontract handle
Returns:
Returns the cumulative count of how many times the ring is overrun resulting in same last filled buffer

=============================================================================

uint32_t tf_isLogInfoNextBuf ( tf_contract_HANDLE  contract_handle)

============================================================================
tf_isLogInfoNextBuf

brief
Gets the flag to indicate if the logging information starts from first buffer or next buffer

Application Requirements: Application would need to create valid contract handle before calling this function

Parameters:
[in]contract_handlecontract handle
Returns:
Returns the flag to indicate if the wrap around happened in the ring buffer during the production. If this flag is set, indicates the wrap around hence the logger information needs to be read from next buffer, otherwise it needs to be read from first ring buffer.

=============================================================================

uint32_t tf_isThereToConsume ( tf_consumer_HANDLE  cHandle)

============================================================================
tf_isThereToConsume

brief
Checks the consumer if there is anything to consume

Parameters:
[in]cHandleconsumer handle
Returns:
Number of buffers to be consumed

=============================================================================

============================================================================
tf_newContract

brief
API added to create the contract between producer/consumer instances This API is applicable for the contract version TRACE_CONTRACT_VERSION_2 Application needs to maintain any names associated with this contract handle outside traceframework

Parameters:
[in]tf_contractConfigtf_contract configuration structure
Returns:
Contract Handle

=============================================================================

Ptr tf_prodBufExchange ( tf_producer_HANDLE  pHandle,
uint8_t *  full 
)

============================================================================
tf_prodBufExchange

brief
Implements the buffer exchange function interface for the LoggerStreamer

Parameters:
[in]pHandleProducer Handle
[in]fullfilled log buffer
Returns:
next free log buffer

=============================================================================

============================================================================
tf_prodCreate

brief
Creates the local producer instance for a given contract

Parameters:
[in]configproducer configuration information
Returns:
Handle to the producer

=============================================================================

============================================================================
tf_prodDestroy

brief
frees up the producer instance created

Parameters:
[in]pHandlePointer to the producer instance
Returns:
Status of the operation

=============================================================================

============================================================================
tf_prodGetContractHandle

brief
API to get the contract handle that is associated with the producer

Parameters:
[in]pHandleproducer handle
[in]contract_handleAddress of the contract handle to store
Returns:
Status of the operation

=============================================================================

============================================================================
tf_prodGetCurBuf

brief
current ring buffer which producer is intended to write to.

Parameters:
[in]pHandleProducer Handle
Returns:
current buffer in use

=============================================================================

void tf_prodGetOOBData ( tf_contract_HANDLE  cHandle,
uint8_t *  data 
)

============================================================================
tf_prodGetOOBData

brief
Gets the out of band (OOB) data in the contract memory to the application

Parameters:
[in]cHandlecontract handle
[in]dataout of band (OOB) data read from the contrat memory
Returns:
void

=============================================================================

============================================================================
tf_prodNotifyConsumers

brief
Each time a buffer exchange happens for that producer instance, the notifications needs to be posted to all registered consumers for that producer. This function identifies if there are any buffers in the ring buffer to be notified to the registered consumers of that producer. Few cases where this function can be called is in a background task or can be hooked to the buffer exchange done function for the producer where performance of the buffer exchange is not so critical

Parameters:
[in]pHandlePointer to the producer handle
Returns:
void

=============================================================================

void tf_prodSetOOBData ( tf_contract_HANDLE  cHandle,
uint8_t *  data 
)

============================================================================
tf_prodSetOOBData

brief
sets the out of band (OOB) data from the application in the contract memory

Parameters:
[in]cHandlecontract handle
[in]dataout of band (OOB) data to be filled in the contrat memory
Returns:
void

=============================================================================

============================================================================
tf_prodUpdateConsumers

brief
The local producer instance would need to be synced to the footprints from the contract This function can be called to syncrhonize the local producer instance to contrat.
Typical example of use: can be called periodically from a task/isr

Parameters:
[in]p_handlePointer to the producer handle
Returns:
number of consumers in the producer contract

=============================================================================

void tf_systemCfg ( tf_StartCfg_t startCfg)

============================================================================
tf_systemCfg

brief
starts the system with start configurations

Application Requirements: Application would need to call this API once per process/core with proper startCfg arguments before Contract Create, Produer Create and Consumer Create functions

Parameters:
[in]startCfgstart configuration structure
Returns:
none

=============================================================================


Copyright 2014, Texas Instruments Incorporated