ETB Library
|
#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 ETBHandle * | ETBHandle_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) |
This module allows users to program ETB debug hardware.
#define ETBLIB_MAJOR_VERSION (0x1) |
#define ETBLIB_MINOR_VERSION (0x16) |
#define SYS_ETB 0xFF |
#define ARM_ETB 0xAA |
typedef enum _eETB_Error eETB_Error |
typedef void(* ETB_errorCallback)(eETB_Error) |
[in] | eETB_Error | error returned by calling routine. |
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 |
typedef enum _eDMA_Mode eDMA_Mode |
typedef enum _eCIC_Select eCIC_Select |
typedef struct _DMAConfig DMAConfig |
typedef struct _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 |
typedef ETBHandle* ETBHandle_Pntr |
typedef struct _ETBStatus ETBStatus |
typedef struct _ETBProperties ETBProperties |
enum _eETB_Error |
enum _eETB_Mode |
enum _eDMA_Mode |
enum _eCIC_Select |
eETB_Error ETB_open | ( | ETB_errorCallback | pErrCallBack, |
eETB_Mode | mode, | ||
uint8_t | coreID, | ||
ETBHandle ** | ppHandle, | ||
uint32_t * | pETBSizeInWords | ||
) |
[in] | pErrCallBack | is called if not NULL and this function returns any eETB_Error value other than eETB_Success. |
[in] | mode | is the mode in which ETB should be used. Most commonly it is eETB_Circular. |
[in] | coreID | core 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] | ppHandle | is 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] | pETBSizeInWords | contains size of ETB buffer in 32 bit words, if successfully opened. |
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.
eETB_Error ETB_gethandle | ( | uint8_t | coreID, |
ETBHandle ** | ppHandle | ||
) |
[in] | coreID | core 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] | ppHandle | is pointer to a ETBhandle pointer. |
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 | ||
) |
[in] | pETBHandle | ETB Handle pointer. |
[in] | triggerCount | is number of words written to ETB RAM following a trigger event. This is only used for ARM. Use 0 for DSP. |
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) |
[in] | pETBHandle | ETB Handle pointer. |
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 | ||
) |
[in] | pETBHandle | ETB Handle pointer. |
[out] | status | contains ETB status parameters. |
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 | ||
) |
[in] | pETBHandle | ETB Handle pointer. |
[in] | pBuffer | an allocated buffer pointer passed in that would contain ETB buffer on return. |
[in] | bufferLength | is the size of the allocated buffer in 32 bit long words unit. |
[in] | startWord | is 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] | requestSize | is the requested number of words to be read from the ETB. |
[out] | pRetSize | contains the actual number of read words and retured as part of pBuffer. |
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.
eETB_Error ETB_close | ( | ETBHandle * | pETBHandle) |
[in] | pETBHandle | ETB Handle pointer. |
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) |
[in] | pHandle | ETB Handle pointer. |
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 | ||
) |
[in] | pHandle | |
[in] | pConfig |
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.
eETB_Error ETB_flush_dma | ( | ETBHandle * | pHandle, |
DMAStatus * | pStatus | ||
) |
[in] | pHandle | |
[in] | pStatus |
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.
[in] | pHandle | |
[in] | pStatus |
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) |
[in] | pProperties |
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.