ETB Library
Classes | Macros | Typedefs | Enumerations | Functions
ETBInterface.h File Reference
#include <stdint.h>

Go to the source code of this file.

Classes

struct  _DMAConfig
 DMA configuration structure. More...
 
struct  _DMAStatus
 DMA status structure. More...
 
struct  _ETBStatus
 ETB status structure definition. More...
 
struct  _ETBProperties
 ETB status structure definition. More...
 

Macros

#define ETBLIB_MAJOR_VERSION   (0x1)
 
#define ETBLIB_MINOR_VERSION   (0x16)
 
#define SYS_ETB   0xFF
 
#define ARM_ETB   0xAA
 

Typedefs

typedef enum _eETB_Error eETB_Error
 
typedef void(* ETB_errorCallback )(eETB_Error)
 
typedef enum _eETB_Mode eETB_Mode
 
typedef enum _eDMA_Mode eDMA_Mode
 
typedef enum _eCIC_Select eCIC_Select
 
typedef struct _DMAConfig DMAConfig
 DMA configuration structure. More...
 
typedef struct _DMAStatus DMAStatus
 DMA status structure. More...
 
typedef struct _ETBHandle_t ETBHandle
 
typedef ETBHandleETBHandle_Pntr
 
typedef struct _ETBStatus ETBStatus
 ETB status structure definition. More...
 
typedef struct _ETBProperties ETBProperties
 ETB status structure definition. More...
 

Enumerations

enum  _eETB_Error {
  eETB_Success = 0, eETB_Error_Bad_Param = -1, eETB_Error_Program = -2, eETB_Error_Cannot_Own = -3,
  eETB_Error_Cannot_Read = -4, eETB_Error_Cannot_Write = -5, eETB_Error_Psc_Enabling = -6, eETB_Overflow = -7,
  eETB_Underflow = -8
}
 
enum  _eETB_Mode { eETB_Circular = 0, eETB_TI_Mode = 1, eETB_Stop_Buffer = 2, eETB_TI_Mode_AND_Stop_Buffer = 3 }
 
enum  _eDMA_Mode { eDMA_Circular = 0, eDMA_Stop_Buffer = 1 }
 
enum  _eCIC_Select { eCIC_0, eCIC_1, eCIC_2, eCIC_3 }
 

Functions

eETB_Error ETB_open (ETB_errorCallback pErrCallBack, eETB_Mode mode, uint8_t coreID, ETBHandle **ppHandle, uint32_t *pETBSizeInWords)
 Open and initialize ETB. More...
 
eETB_Error ETB_gethandle (uint8_t coreID, ETBHandle **ppHandle)
 Get the handle of an ETBLib opened for the specified coreID. More...
 
eETB_Error ETB_enable (ETBHandle *pETBHandle, uint32_t triggerCount)
 
eETB_Error ETB_disable (ETBHandle *pETBHandle)
 
eETB_Error ETB_status (ETBHandle *pETBHandle, ETBStatus *status)
 
eETB_Error ETB_read (ETBHandle *pETBHandle, uint32_t *pBuffer, uint32_t bufferLength, uint32_t startWord, uint32_t requestSize, uint32_t *pRetSize)
 
eETB_Error ETB_close (ETBHandle *pETBHandle)
 
eETB_Error ETB_flush (ETBHandle *pHandle)
 
eETB_Error ETB_config_dma (ETBHandle *pHandle, const DMAConfig *pConfig)
 
eETB_Error ETB_flush_dma (ETBHandle *pHandle, DMAStatus *pStatus)
 
void ETB_setDmaStatus (ETBHandle *pHandle, DMAStatus *pStatus)
 
void ETB_getProperties (ETBProperties *pProperties)
 

Detailed Description

Version
1.7 Application Access to Embedded Trace Buffer.

This module allows users to program ETB debug hardware.

Macro Definition Documentation

#define ETBLIB_MAJOR_VERSION   (0x1)
ETBLIB_MAJOR_VERSION
ETBLib major revision. This number will be changed for API modifications.
#define ETBLIB_MINOR_VERSION   (0x16)
ETBLIB_MINOR_VERSION
ETBLib minor revision. This number will be changed for bug fixes.
#define SYS_ETB   0xFF
SYS_ETB
If the ETB is for System Trace (STM), or if a single ETB is shared by multiple cores, use SYS_ETB as a coreID.
#define ARM_ETB   0xAA
ARM_ETB
If the ETB is for ARM A15 Trace (PTM), use ARM_ETB as a coreID.

Typedef Documentation

typedef enum _eETB_Error eETB_Error
eETB_Error
Common function return error enumeration.
typedef void(* ETB_errorCallback)(eETB_Error)
ETB_errorCallback
The callback function is called with the function's exit status. Note that this function is not exported by the interface, but is used as a parameter for calls.
Parameters
[in]eETB_Errorerror returned by calling routine.
Returns
void
Details:

This is a user provided callback normally used to centralize error handling and error is desired to be handled in a callback routine provided by the caller instead a return error code.

typedef enum _eETB_Mode eETB_Mode
eETB_Mode
Type of ETB mode. This is used to define ETB mode during an ETB_open call. This mode should be very carefully selected as per the actual ETB on chip.
typedef enum _eDMA_Mode eDMA_Mode
eDMA_Mode
Type of DMA mode. This is used to define the DMA mode during a DMA configuraion.
typedef enum _eCIC_Select eCIC_Select
eCIC_Select
The Chip-level Interrupt Controller number values.
typedef struct _DMAConfig DMAConfig
DMAConfig
typedef struct _DMAStatus DMAStatus
DMAStatus

This structure is populated in the ETB_flush_dma function to provide the address for the beginning of the circular buffer and the number of words that have been transferred into it. The buffer address and size that are provided in the DMA configuration structure is duplicated here to provide all of the information required to manage reading the circular buffer.

typedef struct _ETBHandle_t ETBHandle
ETBHandle
ETB Handle object. This is an incomplete structure, thus making the actual implementation private to the ETBLib.
ETBHandle_Pntr
Pointer to a ETB Handle object
typedef struct _ETBStatus ETBStatus
ETBStatus
typedef struct _ETBProperties ETBProperties
ETBCapability

Enumeration Type Documentation

eETB_Error
Common function return error enumeration.
Enumerator
eETB_Success 

Function completed successfully

eETB_Error_Bad_Param 

Error, method parameter error

eETB_Error_Program 

Error, Error programming hardware

eETB_Error_Cannot_Own 

Error, Error programming hardware, ownership cannot be taken

eETB_Error_Cannot_Read 

Error, Cannot read ETB as ETB is not in a readable state

eETB_Error_Cannot_Write 

Error, Cannot write ETB as ETB is not in a writabe state

eETB_Error_Psc_Enabling 

Error, Error programming hardware, Cannot enable PSC modules for ETB

eETB_Overflow 

Error, Read Overflow - TI Mode only

eETB_Underflow 

Error, Read Underflow - TI Mode only

enum _eETB_Mode
eETB_Mode
Type of ETB mode. This is used to define ETB mode during an ETB_open call. This mode should be very carefully selected as per the actual ETB on chip.
Enumerator
eETB_Circular 

Circular mode for ETB11, CSETB, TI ETB. Only circular buffer mode and can't be read while capturing

eETB_TI_Mode 

For TI-ETB implemetation, this is TI ETB mode (simultaneneous read/write) with a circular buffer mode For Keystone2 SYS ETB and CSSTM ETB, provides circular buffer mode with no support for simultaneneous read/write of ETB buffer

eETB_Stop_Buffer 

Stop on buffer full mode

eETB_TI_Mode_AND_Stop_Buffer 

For TI-ETB implemetation, this is TI ETB mode (simultaneneous read/write) with stop on buffer full mode For Keystone2 SYS ETB and CSSTM ETB, provides stop on buffer full mode with no support for simultaneneous read/write of ETB buffer

enum _eDMA_Mode
eDMA_Mode
Type of DMA mode. This is used to define the DMA mode during a DMA configuraion.
Enumerator
eDMA_Circular 

Circular mode

eDMA_Stop_Buffer 

Stop on buffer full mode

eCIC_Select
The Chip-level Interrupt Controller number values.

Function Documentation

eETB_Error ETB_open ( ETB_errorCallback  pErrCallBack,
eETB_Mode  mode,
uint8_t  coreID,
ETBHandle **  ppHandle,
uint32_t *  pETBSizeInWords 
)
ETB_open
Parameters
[in]pErrCallBackis called if not NULL and this function returns any eETB_Error value other than eETB_Success.
[in]modeis the mode in which ETB should be used. Most commonly it is eETB_Circular.
[in]coreIDcore ID (0,1,2....) for a device with homogeneous DSPs or CPUs and each core has a dedicated ETB. For example, TCI6488 utilizes 0,1 or 2 for this parameter. For device with a single core/ETB combination, 0 is used. If the ETB is for System Trace (STM), or if a single ETB is shared by multiple cores, use SYS_ETB as a coreID.
[out]ppHandleis pointer to a ETBhandle pointer, the pointer is allocated by the ETBLib so caller should not allocate the pointer. This should be passed back to "ETB_close()" call, once done.
[out]pETBSizeInWordscontains size of ETB buffer in 32 bit words, if successfully opened.
Returns
eETB_Error.
Details:

This function must be the first ETBLib function called to initialize ETB module access. All other ETBLib fiunctions will return eETB_Error_Program if ETB_open has not been called. If the initialization process is successful a handle pointer that is core specific (not library instance specific) is returned.

Note
Note: ETBLib provides a static allocation of handle memory in the ETBLib_ExtMem data section, allowing the handle memory to be shared between cores. The user must link ETBLib_ExtMem to shared memory to enable handle sharing between cores. In this case ETB_open would be called once from the core A, and then ETB_gethandle called from core B to get the shared handle. All other ETBLib functions can then be called from core B. ETB_open must be called with a NULL ETB_errorCallback, unless the callback function is shared between cores. No synchronization between cores is provided within ETBLib.
eETB_Error ETB_gethandle ( uint8_t  coreID,
ETBHandle **  ppHandle 
)
ETB_gethandle
Parameters
[in]coreIDcore ID (0,1,2....) for a device with homogeneous DSPs or CPUs and each core has a dedicated ETB. For example, TCI6488 utilizes 0,1 or 2 for this parameter. For device with a single core/ETB combination, 0 is used. If the ETB is for System Trace (STM), or if a single ETB is shared by multiple cores, use SYS_ETB as a coreID.
[out]ppHandleis pointer to a ETBhandle pointer.
Returns
eETB_Error.
Details:

If ETBLib is already opened for the specified coreID, the handle pointer is returned. The return value is eETB_Error_Program, if ETBLib has not been opened for the specified core.

eETB_Error ETB_enable ( ETBHandle pETBHandle,
uint32_t  triggerCount 
)
ETB_enable
Enable ETB to start capturing data.
Parameters
[in]pETBHandleETB Handle pointer.
[in]triggerCountis number of words written to ETB RAM following a trigger event. This is only used for ARM. Use 0 for DSP.
Returns
eETB_Error.
Details:

This function enables ETB. As soon as ETB is enabled, it starts capturing trace data. The ETB should be enabled after trace export, clocks and data trace formatter (if applicable) has been programmed.

eETB_Error ETB_disable ( ETBHandle pETBHandle)
ETB_disable
Disable ETB to stop capturing data.
Parameters
[in]pETBHandleETB Handle pointer.
Returns
eETB_Error.
Details:

This function disables ETB. As soon as ETB is disabled, it stops capturing trace data. A CoreSight ETB is ready to be read once it is disabled. A TI ETB in TI_ETB mode does not need to be disabled before reading out the ETB contents.

eETB_Error ETB_status ( ETBHandle pETBHandle,
ETBStatus status 
)
ETB_status
Function to check the ETB status to check if it is ready to be read.
Parameters
[in]pETBHandleETB Handle pointer.
[out]statuscontains ETB status parameters.
Returns
eETB_Error.
Details:

This function provides information ETB state. Before making a call to ETB_read , it is expected to call this method to get the state of the ETB.

eETB_Error ETB_read ( ETBHandle pETBHandle,
uint32_t *  pBuffer,
uint32_t  bufferLength,
uint32_t  startWord,
uint32_t  requestSize,
uint32_t *  pRetSize 
)
ETB_read
Function to read out ETB RAM contents.
Parameters
[in]pETBHandleETB Handle pointer.
[in]pBufferan allocated buffer pointer passed in that would contain ETB buffer on return.
[in]bufferLengthis the size of the allocated buffer in 32 bit long words unit.
[in]startWordis the index (0 based) of the ETB word to start reading. ETB_canread() provides number of available words. Use 0 for reading from a valid start of buffer.
[in]requestSizeis the requested number of words to be read from the ETB.
[out]pRetSizecontains the actual number of read words and retured as part of pBuffer.
Returns
eETB_Error.
Details:

This function reads ETB contents, if the ETB can be read. Caller of this function is responsible to allocate and deallocate the buffer. If the request size is more than available ETB words and the buffer size is at least the request size, request sise is returned. If the buffer is NULL or allocated size is less than the requested words, an error is returned.

Note
If using the DMA drain buffer, ETB_flush_dma MUST be called before using this read function.
eETB_Error ETB_close ( ETBHandle pETBHandle)
ETB_close
Function to close the ETB and relese ETB handle pointer.
Parameters
[in]pETBHandleETB Handle pointer.
Returns
eETB_Error
Details:

This function should be the last call made once your are done with the ETB. After closing th ETB, ETB_open call is requuired before ETB can be used again.

eETB_Error ETB_flush ( ETBHandle pHandle)
ETB_flush
Flush the ETB.
Parameters
[in]pHandleETB Handle pointer.
Returns
eETB_Error.
Details:

This function flushes the ETB input buffer and ADTF. If you have temporarily stopped trace export with TEND, the flush will provide the end of the current trace packet, avoiding the "insufficient data" error when decoding.

If DSP Core-ETB is configured in EDMA mode, the ADTF is both flushed and stopped by ETB_flush(). If DSP Core-ETB is configured in non-EDMA mode, only the ADTF is flushed by ETB_flush(). In this case the ADTF is stopped in the ETB_disable function. If System ETB is configured either in EDMA or non-EDMA mode, STM data is flushed to the ETB by ETB_flush().

This function is only valid if the library has been opened in TI mode. Note that if you are not in TI mode the ETB_disable function performs the flush operation.

Note: When the ETB is configured in EDMA mode, ETB_flush() must be called prior to ETB_flush_dma().

eETB_Error ETB_config_dma ( ETBHandle pHandle,
const DMAConfig pConfig 
)
ETB_config_dma
Configure the DMA used to interface with the ETB.
Parameters
[in]pHandle
[in]pConfig
Returns
eETB_Error.
Details:

This function is passed a configuration structure that is used to setup the EDMA3 to transfer data written into the ETB to a location in memory. The ETB half-full and full interrupts are used as system events to start each transaction. The interrupts are routed from the ETB through the chip-level INTCx (interrupt controller) to an input event in the EDMA3. Two DMA channels are required, one for clearing the INTCx system interrupt status register, and the second for transferring data from the ETB to the drain buffer in memory.

ETB_open must be called before this configuration function with the option eETB_TI_Mode. Any other option will cause this function to return in error.

Note
The application is responsible for all DMA channel and parameter RAM mapping and configuration.
eETB_Error ETB_flush_dma ( ETBHandle pHandle,
DMAStatus pStatus 
)
ETB_flush_dma
Configure a DMA transfer to flush remaining words in ETB to memory buffer.
Parameters
[in]pHandle
[in]pStatus
Returns
eETB_Error.
Details:

This function is used to copy any remaining information in the ETB that has not reached the half-full or full mark in the buffer. Status information is populated in the DMAStatus structure that can be used to manage collecting information from the drain buffer in memory.

The DMA drain functions will only use a multiple of half of the the ETB size. If the number of words that is passed as part of the DMA configuration is not a multiple of half the ETB size, the DMA status value in the handle will get set to the number of words that are actually being used.

Note
The application must have stopped all tracing and ETB_flush function must be called before this function.
void ETB_setDmaStatus ( ETBHandle pHandle,
DMAStatus pStatus 
)
ETB_setDmaStatus
Set the DMAStatus structure used by the DMA library functions.
Parameters
[in]pHandle
[in]pStatus
Details:

When using the DMA drain functionality with multiple DMA buffers, this function is required to set the correct status parameters before making dependent API calls such as ETB_read.

void ETB_getProperties ( ETBProperties pProperties)
ETB_getProperties
Set the properties(capabilties supported) by the ETB.
Parameters
[in]pProperties
Details:

This API can be used by the application to determine the capabilities supported by ETB of a particular device. For example: The Application can determine whether ETB-DMA extension is supported or not.