Functions
FFTC Higher Layer Functions
FFTC Higher Layer Data Structures & APIs

Functions

static Qmss_QueueHnd Fftc_setupCppiDesc (Fftc_CppiDescCfg *pCppiDescCfg)
static Qmss_QueueHnd Fftc_getFreeQ (Fftc_UserInfo *pFFTCUserInfo, uint32_t descSize, Cppi_DescType descType)
static void Fftc_cleanFreeQBuffers (Qmss_QueueHnd hQmssFreeQ, Qmss_QueueHnd hQmssGblFreeQ, uint32_t numBuffers, uint32_t bufferSize, uint32_t descSize)
static Qmss_QueueHnd Fftc_allocFreeQBuffers (Fftc_UserInfo *pFFTCUserInfo, uint32_t numBuffers, uint32_t bufferSize, Cppi_DescType descType, uint32_t descSize, int32_t *pNumAllocated, Qmss_QueueHnd *phGlblFreeQ)
static Fftc_TxQInfoFftc_txQueueOpen (Fftc_InstanceInfo *pFFTCInstInfo, Fftc_QueueId fftcTxQNum, Fftc_QLocalCfg *pFFTQCfg, uint8_t bSharedMode)
static Fftc_RetVal Fftc_txQueueClose (Fftc_TxQInfo *pFFTCTxQInfo)
static uint8_t Fftc_isValidFlow (Fftc_DrvHandle hFFTC, int8_t flowId)
static int32_t Fftc_getNextAvailRxObjId (uint8_t instNum)
uint32_t Fftc_getVersionID (void)
const char * Fftc_getVersionStr (void)
Fftc_RetVal Fftc_init (uint8_t instNum, Fftc_GlobalCfg *pFFTCGlobalCfg, Fftc_DeviceCfg *pFFTCDevCfg)
Fftc_RetVal Fftc_deInit (uint8_t instNum)
uint8_t Fftc_isInitialized (uint8_t instNum)
Fftc_DrvHandle Fftc_open (uint8_t instNum, Fftc_DrvCfg *pFFTCDrvCfg, Fftc_RetVal *pRetVal)
Fftc_RetVal Fftc_close (Fftc_DrvHandle hFFTC)
Fftc_LldObj * Fftc_getLLDObject (Fftc_DrvHandle hFFTC)
Fftc_TxHandle Fftc_txOpen (Fftc_DrvHandle hFFTC, Fftc_TxCfg *pFFTCTxCfg)
Fftc_RetVal Fftc_txClose (Fftc_TxHandle hFFTCTxInfo)
Fftc_RxHandle Fftc_rxOpen (Fftc_DrvHandle hFFTC, Fftc_RxCfg *pFFTCRxCfg)
Fftc_RetVal Fftc_rxClose (Fftc_RxHandle hFFTCRxInfo)
Fftc_RetVal Fftc_findFlowIdByQueueNumber (Fftc_DrvHandle hFFTC, uint32_t rxQueueNumber)
Fftc_RetVal Fftc_rxGetRxQueueNumber (Fftc_RxHandle hFFTCRxInfo)
Fftc_RetVal Fftc_rxGetFlowId (Fftc_RxHandle hFFTCRxInfo)
Fftc_RetVal Fftc_txGetRequestBuffer (Fftc_TxHandle hFFTCTxInfo, Fftc_BlockInfo *pDFTBlockSizeInfo, Fftc_QLocalCfg *pFFTCQConfig, uint32_t psInfoLen, uint8_t destnFlowId, uint16_t destnTagInfo, Fftc_RequestHandle *phFFTCRequest, uint8_t **ppReqDataBuffer, uint32_t *pMaxDataBufferLen)
Fftc_RetVal Fftc_txSubmitRequest (Fftc_TxHandle hFFTCTxInfo, Fftc_RequestHandle hRequestInfo, uint32_t reqBufferLen)
Fftc_RetVal Fftc_txFreeRequestBuffer (Fftc_TxHandle hFFTCTxInfo, Fftc_RequestHandle hRequestInfo)
Fftc_RetVal Fftc_rxProcessDesc (Fftc_RxHandle hFFTCRxInfo, Cppi_Desc *pCppiDesc, Fftc_ResultHandle *phResultInfo, uint8_t **ppResultBuffer, uint32_t *pResultBufferLen, uint8_t **ppPSInfo, uint32_t *pPSInfoLen, uint8_t *pFlowId, uint8_t *pSrcId, uint16_t *pDestnTagInfo)
Fftc_RetVal Fftc_rxGetResult (Fftc_RxHandle hFFTCRxInfo, Fftc_ResultHandle *phResultInfo, uint8_t **ppResultBuffer, uint32_t *pResultBufferLen, uint8_t **ppPSInfo, uint32_t *pPSInfoLen, uint8_t *pFlowId, uint8_t *pSrcId, uint16_t *pDestnTagInfo)
Fftc_RetVal Fftc_rxGetNumPendingResults (Fftc_RxHandle hFFTCRxInfo)
Fftc_RetVal Fftc_rxFreeResult (Fftc_RxHandle hFFTCRxInfo, Fftc_ResultHandle hResultInfo)
Fftc_RetVal Fftc_rxParseResult (Fftc_RxHandle hFFTCRxInfo, Fftc_ResultHandle hResultInfo, uint8_t *pResultBuffer, uint32_t resultBufferLen, Fftc_BlockInfo *pDFTBlockSizeInfo, uint8_t bSupressSideInfo, uint16_t cyclicPrefixAddNum, Fftc_Result *pFFTResult)
void Fftc_rxHiPriorityRxISR (Fftc_RxHandle hFFTCRxInfo)
Int32 Fftc_getDeviceAccumulatorConfig (uint8_t instNum, uint8_t *pAccChannelNum, uint16_t *pAccRxQNum)

Function Documentation

static Qmss_QueueHnd Fftc_allocFreeQBuffers ( Fftc_UserInfo pFFTCUserInfo,
uint32_t  numBuffers,
uint32_t  bufferSize,
Cppi_DescType  descType,
uint32_t  descSize,
int32_t *  pNumAllocated,
Qmss_QueueHnd *  phGlblFreeQ 
) [static]

============================================================================
Fftc_allocFreeQBuffers

brief
This API creates a Tx/Rx object local free descriptor queue and attaches descriptors as per the number, size, type provided in the input parameters 'numBuffers', 'bufferSize', and 'descType' respectively. It also pre-allocates memory for the buffers on host descriptors and populates all applicable known fields. On successful completion, this API returns the handle to the Tx/Rx object's local free queue, number of descriptors successfully allocated and the application's free queue handle from which the descriptors were retrieved.

* API for internal use by the driver *

Parameters:
[in]pFFTCUserInfoFFTC driver handle obtained using Fftc_open () API.
[in]numBuffersNumber of descriptors that need to be allocated.
[in]bufferSizeSize of the buffer to be enqueued on the descriptors.
[in]descTypeCPPI descriptor type. Valid values are: Cppi_DescType_HOST, Cppi_DescType_MONOLITHIC.
[in]descSizeCPPI descriptor size.
[out]pNumAllocatedNumber of descriptors succesfully queued on this object's free queue.
[out]phGlblFreeQThe FFTC application's free queue handle from which the descriptors for this object have been allocated from.
Returns:
Qmss_QueueHnd
  • NULL - Error. Invalid input. No free descriptor queue allocated with buffers.
  • Valid Handle - Success. Valid CPPI free descriptor queue handle returned.
Precondition:

Fftc_open () must have been called to setup the driver and initialize applicaiton's set of free queues before calling this API.
Postcondition:

A Tx/Rx object's local free queue is created with descriptors and pre-allocated buffers. ============================================================================
static void Fftc_cleanFreeQBuffers ( Qmss_QueueHnd  hQmssFreeQ,
Qmss_QueueHnd  hQmssGblFreeQ,
uint32_t  numBuffers,
uint32_t  bufferSize,
uint32_t  descSize 
) [static]

============================================================================
Fftc_cleanFreeQBuffers

brief
This API cleans up a Tx/Rx object free descriptor queue created earlier using Fftc_allocFreeQBuffers () API. It detaches and frees any buffers if applicable, (buffers are freed only if descriptor is of host type) and finally restores the descriptor back to the application's global free queue provided.

* API for internal use by the driver *

Parameters:
[in]hQmssFreeQTx/Rx object free descriptor queue that needs to be de-allocated.
[in]hQmssGblFreeQApplication's global free queue to which the Rx/Tx object's clean descriptors must be returned to.
[in]numBuffersNumber of descriptors that need to be restored.
[in]bufferSizeSize of the buffer enqueued on the descriptors.
[in]descSizeCPPI descriptor size.
Returns:
None
Precondition:

Fftc_open () must have been called to setup the driver and initialize application's free queues. Also a Tx/Rx local free queue must have been successfully setup using Fftc_allocFreeQBuffers () API before this API is called.
Postcondition:

The Tx/Rx object local free queue 'hQmssFreeQ''s buffers are cleaned up, and all its descriptors are returned to the application's free queue corresponding to 'hQmssGblFreeQ'. ============================================================================

============================================================================
Fftc_close

brief
This API closes the FFTC driver instance opened earlier using a call to Fftc_open () API.

Currently, there exists no way to cleanly free the descriptors obtained during Fftc_open () API.

Parameters:
[in]hFFTCFFTC driver handle obtained using Fftc_open () API.
Returns:
Fftc_RetVal
  • FFTC_RETVAL_EBAD_HANDLE - Invalid input handle passed. Error.
  • FFTC_RETVAL_SUCCESS - Successfully closed the FFTC.
Precondition:

Fftc_open () must have been called to open the driver instance prior to calling this API. Also, all open Tx, Rx objects opened by an application must be closed by calling Fftc_txClose () and Fftc_rxClose () APIs before calling this API to ensure all associated memory is freed cleanly.
Postcondition:

Reference count decremented on the FFTC instance in the driver. ============================================================================
Fftc_RetVal Fftc_deInit ( uint8_t  instNum)

============================================================================
Fftc_deInit

brief
This API closes the FFTC peripheral instance opened earlier using Fftc_init () API. When all the applications using this FFTC instance have released it (reference count on the instance reaches zero), this API closes the FFTC CPDMA, closes the FFTC LLD and finally initiates a software reset on the FFTC engine to reset all its registers, and it's state machine. On success, it restores the FFTC peripheral state to 'unopened' state

If an application or driver would like to use any of the driver APIs again, it can do so only after calling Fftc_init() again.

Parameters:
[in]instNumFFTC peripheral instance number.
Returns:
Fftc_RetVal
  • FFTC_RETVAL_SUCCESS - Successfully closed the FFTC.
Precondition:

Fftc_init () must be called before calling this API.
Postcondition:

Reference count decremented on the FFTC instance in the driver. When reference count reaches zero, CPDMA is closed, all FFTC Tx queues closed and deallocated. FFTC engine software reset performed. ============================================================================
Fftc_RetVal Fftc_findFlowIdByQueueNumber ( Fftc_DrvHandle  hFFTC,
uint32_t  rxQueueNumber 
)

============================================================================
Fftc_findFlowIdByQueueNumber

brief
Given a Rx queue number, this API returns the corresponding flow Id associated from the driver's Rx object database.

Parameters:
[in]hFFTCFFTC driver handle obtained using Fftc_open () API. Specifies which FFTC instance to search for a match.
[in]rxQueueNumberRx queue number for which the flow Id lookup must be performed.
Returns:
Fftc_RetVal
  • <0 - Flow Id retrieval failed. Unable to find a flow for the Rx queue number and FFTC instance provided in the driver database.
  • >=0 - Success. Valid Flow Id returned.
Precondition:

A valid driver handle must be obtained using Fftc_open () API before calling this API.
Postcondition:

None. ============================================================================
Int32 Fftc_getDeviceAccumulatorConfig ( uint8_t  instNum,
uint8_t *  pAccChannelNum,
uint16_t *  pAccRxQNum 
)

============================================================================
Fftc_getDeviceAccumulatorConfig

brief
Given an FFTC instance number, this function retrieves any SoC specific QM accumulator configuration such as accumulator channel number, queue number to use for the FFTC interrupt setup by the driver.

Parameters:
[in]instNumFFTC instance number for which the configuration needs to be retrieved.
[out]pAccChannelNumPointer to hold the accumulator channel returned by this function.
[out]pAccRxQNumPointer to hold the Rx queue number returned by this function.
Returns:
Int32 -1 - Error populating accumulator configuration. 0 - Success. Configuration successfully populated in output parameter handles.
Precondition:

None.
Postcondition:

SoC specific accumulator configuration returned. ============================================================================
static Qmss_QueueHnd Fftc_getFreeQ ( Fftc_UserInfo pFFTCUserInfo,
uint32_t  descSize,
Cppi_DescType  descType 
) [static]

============================================================================
Fftc_getFreeQ

brief
Given a descriptor type and size, this API searches the application's set of free queues (setup during driver open time) to find one matching fitting the parameters. This API assumes that all the free queues setup during driver open time were setup in the ascending order of the descriptor sizes.

* API for internal use by the driver *

Parameters:
[in]pFFTCUserInfoFFTC driver handle obtained using Fftc_open () API.
[in]descSizeSize of the descriptor to find.
[in]descTypeCPPI descriptor type. Valid values are: Cppi_DescType_HOST, Cppi_DescType_MONOLITHIC.
Returns:
Qmss_QueueHnd
  • NULL - Error. No matching free queue found in driver's setup.
  • Valid Handle - Success. Valid CPPI free queue handle returned.
Precondition:

Fftc_open () must have been called to setup the driver and initialize application's free queues before calling this API.
Postcondition:

Matching free queue handle is returned to the caller. ============================================================================
Fftc_LldObj* Fftc_getLLDObject ( Fftc_DrvHandle  hFFTC)

============================================================================
Fftc_getLLDObject

brief
This API returns the FFTC LLD object handle corresponding to the driver handle provided to this API.

Parameters:
[in]hFFTCFFTC driver handle obtained using Fftc_open () API.
Returns:
Fftc_LldObj*
  • NULL - Invalid input handle passed. Error.
  • >0 - FFTC LLD object handle returned.
Precondition:

Fftc_open () must have been called to open the driver instance prior to calling this API.
Postcondition:

None ============================================================================
static int32_t Fftc_getNextAvailRxObjId ( uint8_t  instNum) [static]

============================================================================
Fftc_getNextAvailRxObjId

brief
Given an FFTC peripheral instance number, this API searches through the instance's global Rx object info database to find the next available empty slot to store a new Rx object's info. Each slot in this global Rx object info database stores Rx object information that needs to be globally accessible, i.e., accessible from all cores of the device.

* API for internal use by the driver *

Parameters:
[in]instNumFFTC instance number from which an empty Rx object slot must be found.
Returns:
int32_t
  • <0 - Error finding an empty slot in the Rx object global database.
  • >=0 - Valid Rx object slot id from the database returned to store the new Rx object info.
Precondition:

Fftc_open () must have been called to initialize the driver before calling this API. Also a valid instance number must be specified to this API in 'instNum' parameter.
Postcondition:

None.
        ...

        // Get the next available Rx object slot from the database.
        if (Fftc_getNextAvailRxObjId (CSL_FFTC_A) < 0)
        {
            // Number of Rx objects created exceeds maximum allowed.
        }        

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

uint32_t Fftc_getVersionID ( void  )

============================================================================
Fftc_getVersionID

brief
This API returns the FFTC driver's version Id.

Returns:

uint32_t - Returns the FFTC driver version Id
Precondition:

None.
Postcondition:

None. ============================================================================
const char* Fftc_getVersionStr ( void  )

============================================================================
Fftc_getVersionStr

brief
This API returns the FFTC driver's version information in string format.

Returns:

const char* - Returns the FFTC driver build and version info in string format.
Precondition:

None.
Postcondition:

None. ============================================================================
Fftc_RetVal Fftc_init ( uint8_t  instNum,
Fftc_GlobalCfg pFFTCGlobalCfg,
Fftc_DeviceCfg pFFTCDevCfg 
)

============================================================================
Fftc_init

brief
This API initializes the FFTC driver state for the instance number provided in 'instNum' input parameter. As part of initialization, this API opens the FFTC CPDMA, opens the FFTC LLD, initializes the FFTC MMR with parameters provided in 'pFFTCGlobalCfg' and resets the driver's internal global state and all associated handles.

This API MUST be called ONLY once in the system and at system startup for any given FFTC peripheral instance before using any of the FFTC driver APIs.

Parameters:
[in]instNumFFTC peripheral instance number.
[in]pFFTCGlobalCfgHandle to FFTC Global Configuration structure.
[in]pFFTCDevCfgHandle to device specific configuration info.
Returns:
Fftc_RetVal
  • FFTC_RETVAL_EINVALID_PARAMS - Invalid instance number provided.
  • FFTC_RETVAL_EBAD_HANDLE - Invalid global configuration handle provided.
  • FFTC_RETVAL_EFAILURE - Error initializing driver for the FFTC instance requested.
  • FFTC_RETVAL_SUCCESS - FFTC instance initialized succesfully.
Precondition:

This API MUST be called only once during system startup.
Postcondition:

FFTC driver initialized for the instance specified. ============================================================================
uint8_t Fftc_isInitialized ( uint8_t  instNum)

============================================================================
Fftc_isInitialized

brief
Given an FFTC peripheral instance number, this API returns 1 to indicate that it is open and has been successfully setup, 0 otherwise.

Parameters:
[in]instNumFFTC peripheral instance number to check the status on.
Returns:
uint8_t
  • 1 - Driver setup and opened for the instance number passed.
  • 0 - Instance number invalid/not initialized.
Precondition:

None.
Postcondition:

None. ============================================================================
static uint8_t Fftc_isValidFlow ( Fftc_DrvHandle  hFFTC,
int8_t  flowId 
) [static]

============================================================================
Fftc_isValidFlow

brief
Given a FFTC driver handle and a flow id, this API searches through the driver's flow database to check if the flow Id specified is valid and active.

This API is used internally by the driver at Rx object open time in Fftc_rxOpen () API to ensure that flow requested is valid.

* API for internal use by the driver *

Parameters:
[in]hFFTCFFTC driver handle.
[in]flowIdFlow Id that needs to be validated
Returns:
uint8_t
  • 0 - No flow exists with the flow Id specified for the FFTC instance the driver handle uses.
  • 1 - Valid flow configuration. Found an active flow matching the flow Id specified.
Precondition:

Fftc_open () must have been called to initialize the driver before calling this API.
Postcondition:

None.
        ...

        // Validate the flow
        if (!Fftc_isValidFlow (hFFTC, 0))
        {
            // Error. Invalid flow specified.
        }        

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

Fftc_DrvHandle Fftc_open ( uint8_t  instNum,
Fftc_DrvCfg pFFTCDrvCfg,
Fftc_RetVal pRetVal 
)

============================================================================
Fftc_open

brief
This API opens the FFTC driver and sets up a pool of free descriptor queues for Rx, and Tx for this application as per the configuration specified in 'pFFTCDrvCfg'. The descriptors setup by this API are later used by the driver in setting up free descriptor queues for various Tx, Rx objects.

All the Tx, Rx descriptor configurations provided to this API in 'pFFTCDrvCfg->cppiFreeDescCfg' MUST be ordered in the ascending order of the descriptor sizes.

This API MUST be called by all FFTC driver users at least once to obtain an FFTC driver handle and setup all Tx, Rx descriptors required by it for FFT processing.

Parameters:
[in]instNumFFTC Instance number that the application would like to use.
[in]pFFTCDrvCfgHandle to FFTC driver configuration structure. Must contain descriptor configuration relevant for this application.
[out]pRetValPointer to hold the return value returned by this API. Following are the possible return values for this API:
  • FFTC_RETVAL_EINVALID_PARAMS - Invalid instance number/descriptor configuration provided.
  • FFTC_RETVAL_EBAD_HANDLE - Invalid driver configuration handle provided.
  • FFTC_RETVAL_ENO_MEM - Error allocating memory for driver's internal book-keeping data.
  • FFTC_RETVAL_SUCCESS - Successfully setup the descriptors.
Returns:
Fftc_DrvHandle
  • NULL - Error. Appropriate error code is returned in the output parameter 'pRetVal'.
  • >0 - Success. Valid FFTC driver handle is returned.
Precondition:

The 'pFFTCDrvCfg' driver configuration pointer MUST contain valid CPPI descriptor configuration consistent with the system setup.
Postcondition:

Application requested descriptors setup. ============================================================================

============================================================================
Fftc_rxClose

brief
This API closes the Rx object and closes the Rx flow and cleans up all associated handles. All pending FFTC results are dicarded for this Rx object.

Parameters:
[in]hFFTCRxInfoFFTC Rx object handle obtained using Fftc_rxOpen() API.
Returns:
Fftc_RetVal
  • FFTC_RETVAL_EBAD_HANDLE - FFTC Rx object close failed.
  • FFTC_RETVAL_SUCCESS - FFTC Rx object successfully closed.
Precondition:

Valid Rx object handle must be obtained using Fftc_rxOpen () API before calling this API.
Postcondition:

FFTC Rx object, Rx flow successfully closed and all pending FFTC results on the Rx object are dicarded. ============================================================================
Fftc_RetVal Fftc_rxFreeResult ( Fftc_RxHandle  hFFTCRxInfo,
Fftc_ResultHandle  hResultInfo 
)

============================================================================
Fftc_rxFreeResult

brief
Given a Rx object handle and result handle obtained from Fftc_rxGetResult () API, this API frees the result handle and restores the associated Rx descriptor back to its Rx Free descriptor queue. This API must be called by the application once its done processing the result, otherwise the driver could run out of result buffers eventually if none restored in time.

Parameters:
[in]hFFTCRxInfoRx handle obtained using Fftc_rxOpen () API.
[in]hResultInfoFFTC result handle obtained using Fftc_rxGetResult () API.
Returns:
Fftc_RetVal
  • FFTC_RETVAL_EBAD_HANDLE - Invalid input provided. Free failed.
  • FFTC_RETVAL_SUCCESS - Result free succeeded.
Precondition:

A valid result handle should have been obtained using Fftc_rxGetResult () before calling this API to free the result.
Postcondition:

The result buffers passed are freed up and restored to the Rx object's free descriptors. ============================================================================

============================================================================
Fftc_rxGetFlowId

brief
This API retrieves a given Rx object's Rx flow id number.

Parameters:
[in]hFFTCRxInfoFFTC Rx object handle obtained using Fftc_rxOpen() API.
Returns:
Fftc_RetVal
  • FFTC_RETVAL_EBAD_HANDLE - Flow Id value retrieval failed. Invalid Rx object handle passed.
  • >=0 - The Flow Id associated with the Rx object ranging between 0 and 7 (both inclusive).
Precondition:

Valid Rx object handle must be obtained using Fftc_rxOpen () API before calling this API.
Postcondition:

None. ============================================================================

============================================================================
Fftc_rxGetNumPendingResults

brief
Given a Rx object handle, this API retrieves the number of FFT results pending to be serviced by the application for it.

Parameters:
[in]hFFTCRxInfoRx handle obtained using Fftc_rxOpen () API.
Returns:
int32_t
  • FFTC_RETVAL_EBAD_HANDLE - Invalid input Rx handle provided.
  • >=0 - Number of pending results for this Rx object.
Precondition:

A valid Rx object handle must be obtained using Fftc_rxOpen () API before calling this API.
Postcondition:

Returns the number of FFT results available for this Rx object. ============================================================================
Fftc_RetVal Fftc_rxGetResult ( Fftc_RxHandle  hFFTCRxInfo,
Fftc_ResultHandle phResultInfo,
uint8_t **  ppResultBuffer,
uint32_t *  pResultBufferLen,
uint8_t **  ppPSInfo,
uint32_t *  pPSInfoLen,
uint8_t *  pFlowId,
uint8_t *  pSrcId,
uint16_t *  pDestnTagInfo 
)

============================================================================
Fftc_rxGetResult

brief
Given an Rx object handle, this API checks if there are any FFTC results available from the engine for its processing. If so, it does some basic validation on the result and returns a result handle, the FFT/IFFT raw result data buffer, its length, and any PS info found to the calling application. If no result found, this API either returns status to indicate the same or blocks on the result waiting for it to arrive depending on the Rx object's interrupt and Rx block mode configuration.

Parameters:
[in]hFFTCRxInfoRx handle obtained using Fftc_rxOpen () API.
[out]phResultInfoPointer to FFTC result handle containing info that driver uses internally to process the result.
[out]ppResultBufferPointer to hold result data buffer pointer obtained from FFTC engine.
[out]pResultBufferLenPointer to result buffer length, i.e.,holds the number of bytes available to application in the result data buffer for parsing.
[out]ppPSInfoPointer to PS Info pointer obtained from FFTC engine result.
[out]pPSInfoLenPointer to PS Info length, i.e.,holds the number of bytes of PS info available for application to parse.
[out]pFlowIdFlow Id read from the descriptor's Source Tag lower order 8 bits.
[out]pSrcIdSource Id read from the descriptor's Source Tag higher order 8 bits.
[out]pDestnTagInfoDestination tag info read from the descriptor.
Returns:
Fftc_RetVal
  • FFTC_RETVAL_EBAD_HANDLE - Invalid input Rx object handle provided.
  • FFTC_RETVAL_ENO_RESULT - No FFT results available yet on the Rx queue.
  • FFTC_RETVAL_EFAILURE - Error. Cant process/save the result received.
  • FFTC_RETVAL_SUCCESS - Successfully retrieved result and stored in output parameter handles.
Precondition:

A valid Rx object handle must be obtained using Fftc_rxOpen () API before calling this API.
Postcondition:

If FFT/IFFT Result available, it is validated and handed over to application for further processing, otherwise appropriate status is returned. ============================================================================

============================================================================
Fftc_rxGetRxQueueNumber

brief
This API retrieves the given Rx object's Receive/Destination queue number. This API is especially useful if the application didnt specify a Rx Queue number during Fftc_rxOpen () API and would like to retrieve the queue number.

Parameters:
[in]hFFTCRxInfoFFTC Rx object handle obtained using Fftc_rxOpen() API.
Returns:
Fftc_RetVal
  • FFTC_RETVAL_EBAD_HANDLE - Rx Queue Number retrieval failed.
  • >=0 - The destination queue number associated with the Rx object's flow.
Precondition:

Valid Rx object handle must be obtained using Fftc_rxOpen () API before calling this API.
Postcondition:

None. ============================================================================
void Fftc_rxHiPriorityRxISR ( Fftc_RxHandle  hFFTCRxInfo)

============================================================================
Fftc_rxHiPriorityRxISR

brief
FFTC driver's high priority accumulation Interrupt Service Routine (ISR) for any given Rx object.

This API must be registered as the ISR handler if the Rx object was setup to use driver managed accumulator list configuration, i.e., In Fftc_rxOpen () API 'bUseInterrupts' to 1 and 'bManageAccumList' was set to 1.

This API when invoked on an interrupt, reads the High priority accumulator list registered by the driver and checks if any results are available for this Rx object. It enqueues the packets received to the Rx object's result queue for processing later by the application. If the Rx object was opened in "blocking" mode, then this API posts on the Rx object's semaphore to notify it of the result received.

Parameters:
[in]hFFTCRxInfoFFTC Rx object handle
Returns:
void
Precondition:

This function MUST be registered as the ISR handler for the system event id (lookup EVM specification for system event id) on the core on which the application wishes to receive results from FFTC driver using interrupts.
Postcondition:

Interrupt serviced. Results retrieved from the Rx object's high priority accumulator list. ============================================================================
Fftc_RxHandle Fftc_rxOpen ( Fftc_DrvHandle  hFFTC,
Fftc_RxCfg pFFTCRxCfg 
)

============================================================================
Fftc_rxOpen

brief
This API sets up a Rx object for the calling application. A Rx object is required by driver users to retreive FFT results from the engine using the driver APIs.

The Rx object configuration MUST be provided in the input parameter 'pFFTCRxCfg'.

This API creates a new Rx flow and sets up a Rx Free descriptor queue (FDQ) if requested, i.e., if 'useFlowId' parameter is set to -1 and driver is setup to manage Rx FDQ and create a flow by setting 'bManageRxFlowCfg' to 1 and specifying descriptor configuration in 'rxFlowCfg.drvCfg'. Alternatively, the application can choose to create the Rx FDQs required and setup the complete flow configuration in 'rxFlowCfg.fullCfg' and setting 'bManageRxFlowCfg' to 0. In this case, the driver doesnt do any Rx FDQ setup and uses the flow configuration specified as is to create a new flow.

Alternatively, the application can choose to share a single flow/Rx FDQ between 2 or more Rx objects. It can do so by specifying the flow Id it'd like to share in 'useFlowId' parameter. This API then doesnt create a new flow/Rx FDQ for this Rx object and ensures that the Rx properties for this object are inherited from the flow number specified.

An application can choose to either use High priority interrupts or polling for a Rx object. If interrupts are required, it can indicate the same by setting 'bUseInterrupts' to 1 and specifying the accumulator configuration in 'bManageAccumList' and 'accumCfg' parameters.

The application can also configure whether it wants its receive to be a blocking/non-blocking operation by indicating the same in 'bBlockOnResult' parameter.

On success, this API returns a valid, non-zero Rx oject handle and returns NULL otherwise to indicate an error.

Every application that wishes to receive FFT results using the driver API is expected to call this API to obtain a Rx object handle.

Parameters:
[in]hFFTCFFTC driver handle obtained using Fftc_open () API.
[in]pFFTCRxCfgInput structure that holds configuration for the Rx object.
Returns:
Fftc_RxHandle
  • NULL - Error. Invalid Rx object configuration.
  • Valid Rx handle - Success. FFTC Rx object, Rx queue successfully setup.
Precondition:

Valid FFTC driver handle must be obtained by calling Fftc_open () API by the application before calling this API. Valid Rx configuration must be specified in 'pFFTCRxCfg' structure as input to this API.
Postcondition:

A Rx queue, flow successfully setup with input configuration specified. The Rx object can now be used to retrieve results from the FFTC engine. ============================================================================
Fftc_RetVal Fftc_rxParseResult ( Fftc_RxHandle  hFFTCRxInfo,
Fftc_ResultHandle  hResultInfo,
uint8_t *  pResultBuffer,
uint32_t  resultBufferLen,
Fftc_BlockInfo pDFTBlockSizeInfo,
uint8_t  bSupressSideInfo,
uint16_t  cyclicPrefixAddNum,
Fftc_Result pFFTResult 
)

============================================================================
Fftc_rxParseResult

brief
Given a FFT result handle obtained from Fftc_rxGetResult () API or a valid CPPI descriptor received from FFTC engine containing result, the Rx object handle, and associated request settings, this API parses the result buffer associated with result handle and compiles a per block result buffer, error status and other relevant information for easy interpretation by the application.

Parameters:
[in]hFFTCRxInfoRx handle obtained using Fftc_rxOpen () API.
[in]hResultInfoFFTC result handle obtained using Fftc_rxGetResult () API or valid CPPI descriptor handle containing FFT
[in]pResultBufferResult data buffer pointer obtained from FFTC engine.
[in]resultBufferLenResult buffer length.
[in]pDFTBlockSizeInfoDFT block size list configuration structure. Specifies the number of DFT blocks in the FFTC request, size of each DFT block and whether all blocks are of the same size/not.
[in]bSupressSideInfoIndicates if side band information should be read from the result.
[in]cyclicPrefixAddNumCyclic Prefix addition length value if cyclic prefix addition was requested on Tx.
[out]pFFTResultOutput result structure that will be filled in by this API on successful parsing of the result.
Returns:
Fftc_RetVal
  • FFTC_RETVAL_EBAD_HANDLE - Bad Result/Rx object handles provided.
  • FFTC_RETVAL_EFAILURE - Result parse failed. The result buffer length obtained is not same as what is expected.
  • FFTC_RETVAL_EINV_DESTID_RESULT - Invalid result. Flow Id in result doesnt match the Rx object's flow Id.
  • FFTC_RETVAL_SUCCESS - Successfully parsed the result and filled it in output param structure 'pFFTResult'.
Precondition:

A valid result obtained using Fftc_rxGetResult () API or a valid result descriptor obtained by the application from its ISR must be passed to this API.

Appropriate request settings used on Tx must be provided here to this API for it to parse the result correctly.

The output param pointer 'pFFTResult' should be a valid pointer and must have been allocated memory by the application before calling this API.

Postcondition:

The output param structure 'pFFTResult' is filled with the formatted result and error status. ============================================================================
Fftc_RetVal Fftc_rxProcessDesc ( Fftc_RxHandle  hFFTCRxInfo,
Cppi_Desc *  pCppiDesc,
Fftc_ResultHandle phResultInfo,
uint8_t **  ppResultBuffer,
uint32_t *  pResultBufferLen,
uint8_t **  ppPSInfo,
uint32_t *  pPSInfoLen,
uint8_t *  pFlowId,
uint8_t *  pSrcId,
uint16_t *  pDestnTagInfo 
)

============================================================================
Fftc_rxProcessDesc

brief
This API can be used to retrieve the various result information from the result descriptor received from the engine.

Parameters:
[in]hFFTCRxInfoRx handle obtained using Fftc_rxOpen () API.
[in]pCppiDescRx descriptor containing the result that needs to be processed by this API.
[out]phResultInfoPointer to FFTC result handle containing Rx descriptor handle.
[out]ppResultBufferPointer to hold result data buffer pointer obtained from FFTC engine.
[out]pResultBufferLenPointer to result buffer length, i.e.,holds the number of bytes available to application in the result data buffer for parsing.
[out]ppPSInfoPointer to PS Info pointer obtained from FFTC engine result.
[out]pPSInfoLenPointer to PS Info length, i.e.,holds the number of bytes of PS info available for application to parse.
[out]pFlowIdFlow Id read from the descriptor's Source Tag lower order 8 bits.
[out]pSrcIdSource Id read from the descriptor's Source Tag higher order 8 bits.
[out]pDestnTagInfoDestination tag info read from the descriptor.
Returns:
Fftc_RetVal
  • FFTC_RETVAL_EBAD_HANDLE - Bad input Handle provided.
  • FFTC_RETVAL_SUCCESS - Success.
Precondition:

A valid CPPI descriptor handle must be sent to this API. ============================================================================
static Qmss_QueueHnd Fftc_setupCppiDesc ( Fftc_CppiDescCfg pCppiDescCfg) [static]

============================================================================
Fftc_setupCppiDesc

brief
This API sets up a free queue for the application and populates it with some pre-initialized CPPI descriptors from a given memory region. Once a memory region is formatted into descriptors as per input specified here, it cannot be reformatted to a different param set. Hence, this API must be called to setup only global free queues that can be shared by various application threads using this driver.

* API for internal use by the driver *

Parameters:
[in]pCppiDescCfgHandle to initial CPPI descriptor configuration structure.
Returns:
Qmss_QueueHnd
  • NULL - Error. Invalid descriptor configuration provided.
  • Valid Handle - Success.Valid CPPI free queue handle returned
Precondition:

The input configuration structure handle passed 'pCppiDescCfg' must hold valid configuration for this API to succeed.
Postcondition:

Specified CPPI memory region is formatted as per input into various descriptors and populated on next available QMSS free queue. ============================================================================

============================================================================
Fftc_txClose

brief
This API closes the Tx object and frees any descriptors and buffers allocated. It also decrements the reference count on the Tx queue this object uses. When the reference count on the queue reaches zero, the Tx queue is closed.

Parameters:
[in]hFFTCTxInfoFFTC Tx handle obtained using Fftc_txOpen() API.
Returns:
Fftc_RetVal
  • FFTC_RETVAL_EBAD_HANDLE - Error. Invalid input passed.
  • FFTC_RETVAL_SUCCESS - Success. FFTC Tx object closed.
Precondition:

A valid Tx handle also must be obtained using Fftc_txOpen () before calling this API.
Postcondition:

FFTC Tx object successfully closed and any Tx free descriptors, buffers allocated for the object are cleaned up. The Tx queue is closed if reference count on it reaches zero. ============================================================================

============================================================================
Fftc_txFreeRequestBuffer

brief
This API frees a request buffer obtained earlier by the application using Fftc_txGetRequestBuffer () API. This API must be called if a request submission failed, i.e., Fftc_txSubmitRequest () API returned an error. This API discards the request settings and restores the descriptor, and buffer back to the Tx objects's Free descriptor queue for a future use.

Parameters:
[in]hFFTCTxInfoTx object handle obtained using Fftc_txOpen () API.
[in]hRequestInfoRequest handle obtained using Fftc_txSubmitRequest () API. Contains all the request settings and descriptor info.
Returns:
Fftc_RetVal
  • FFTC_RETVAL_EBAD_HANDLE - Bad input Handle provided.
  • FFTC_RETVAL_SUCCESS - Request handle and descriptor freed successfully.
Precondition:

A valid Tx object handle must be obtained using Fftc_txOpen () before calling this API. This API can be called to free a request buffer obtained earlier using Fftc_txGetRequestBuffer () API. ============================================================================
Fftc_RetVal Fftc_txGetRequestBuffer ( Fftc_TxHandle  hFFTCTxInfo,
Fftc_BlockInfo pDFTBlockSizeInfo,
Fftc_QLocalCfg pFFTCQConfig,
uint32_t  psInfoLen,
uint8_t  destnFlowId,
uint16_t  destnTagInfo,
Fftc_RequestHandle phFFTCRequest,
uint8_t **  ppReqDataBuffer,
uint32_t *  pMaxDataBufferLen 
)

============================================================================
Fftc_txGetRequestBuffer

brief
This API provides the calling application with an empty pre-allocated data buffer that it can use to fill in the FFTC request data and any Protocol Specific (PS) Information that it would like to pass to the receiver.

This API also returns an FFTC request handle (CPPI Descriptor) containing the request settings that the application would have to pass when submitting the FFT request using Fftc_txSubmitRequest () API.

This API prepares a Tx descriptor for request submission. It formulates an FFTC control header based on the parameters provided and attaches it to the data buffer.

This API MUST be called only if the Tx object was setup such that the driver manages the request buffers.

Parameters:
[in]hFFTCTxInfoTx object handle obtained using Fftc_txOpen () API.
[in]pDFTBlockSizeInfoDFT block size list configuration structure. Specifies the number of DFT blocks in the FFTC request, size of each DFT block and whether all blocks are of the same size/not.
[in]pFFTCQConfigFFTC Queue local configuration input. This needs to be provided if the FFTC Tx queue needs to be re-configured with a new set of FFT parameters for request processing. This parameter MUST always be specified if using the Tx queue in "shared" mode, otherwise MUST be set to NULL.
[in]psInfoLenThe length of PS information being added to the request in bytes. FFTC engine hardware allows upto only 16 bytes of PS info. Care must be taken by the application that the PS info never exceeds this length. This can be set to 0 if no PS Pass through info is to be passed to receiver.
[in]destnFlowIdFlow Id to use for the result corresponding to this packet. Specifies the Rx flow/FDQ to use and the Rx queue where the result for this packet must be placed.
[in]destnTagInfoDestination Tag Info. Will be put in the Destination Tag of the Tx descriptor. If Rx flow configured appropriately, this field is copied to Result (rx) descriptor.Can be used by the application to its discretion to track the packet.
[out]phFFTCRequestFFTC request handle. Contains Tx request descriptor.
[out]ppReqDataBufferPointer to data buffer pointer that the application can use to fill in FFTC request data and PS info. The driver expects that the application fills the buffer in the following order: PS info if any followed by the request data.
[out]pMaxDataBufferLenPointer that holds data buffer length, i.e.,holds the number of bytes available to application in the data buffer to fill in any Protocol specific info (PS info) and FFT request data.

Note: The application MUST always fill the data buffer in the following order: Protocol specific pass through info (PS Info) if any available then followed by the actual FFT request blocks.

If the default Rx queue number used in setting up 'destnFlowId' is different from the Rx queue to which the result must be sent. The Queue configuration must be modified accordingly to use the correct queue number.

Returns:
Fftc_RetVal
  • FFTC_RETVAL_EBAD_HANDLE - Get Request buffer failed. Bad Tx Handle provided.
  • FFTC_RETVAL_EINVALID_PARAMS - Error. Invalid configuration parameters provided.
  • FFTC_RETVAL_ENO_MEM - Error. No more free descriptors available for this Tx object.
  • FFTC_RETVAL_EFAILURE - Error adding the FFTC control header to the descriptor.
  • FFTC_RETVAL_SUCCESS - Valid request data buffer, length and request handle returned. API succeeded.
Precondition:

Fftc_txOpen () must be called before calling this API. This API can be called to obtain a free request buffer only if free request descriptors and buffers were allocated during Fftc_txOpen() API (by setting 'bManageReqBuffers' of 'pFFTCTxCfg' to 1) ============================================================================
Fftc_TxHandle Fftc_txOpen ( Fftc_DrvHandle  hFFTC,
Fftc_TxCfg pFFTCTxCfg 
)

============================================================================
Fftc_txOpen

brief
This API sets up a transmit object for the calling application. A transmit object must be setup by any application that wishes to submit FFT requests using the driver.

Given an FFTC Transmit queue number using which the FFT requests must be submitted, and the Tx descriptor configuration to use for submitting the requests, this API opens the FFTC transmit queue if not already open and initializes it with the queue configuration provided, sets up the Tx free descriptors and buffers if requested and returns a Tx object handle that can be used by the application to submit FFT requests.

The Tx object configuration MUST be provided in the input parameter 'pFFTCTxCfg'. If the field 'bManageReqBuffers' of this structure is set to 1, this API pre-allocates (Tx) request buffers and descriptors according to the parameters 'descType', 'cppiNumDesc', 'bufferSize' and holds enough space for specifying 128 DFT block sizes. It also reserves space for DFT size list configuration based on parameters 'bEnableDftSizeListCfg' and 'maxDftSizeListLen'.

The pre-allocated request buffers can then be obtained by application using Fftc_txGetRequestBuffer () API, and can be used to hold the FFT/IFFT request data block. This eliminates the need for the application to do separate buffer allocations on data path and the buffer management is then entirely done by the FFTC driver.

This API opens the FFTC Tx queue and initializes it with the configuration provided in the input parameter when the API is called for the first time for a given FFTC transmit queue number. On all future calls the queue configuration is omitted.

This API ensures that no two Tx objects for any given FFTC instance use mixed size DFT configuration at the same time.

On success, this API returns a valid, non-zero Tx handle and NULL otherwise to indicate an error.

Every application that wishes to submit FFT requests is expected to call this API to obtain a Tx object handle.

Parameters:
[in]hFFTCFFTC driver handle obtained using Fftc_open () API.
[in]pFFTCTxCfgInput structure that holds configuration for the Tx object.
Returns:
Fftc_TxHandle
  • NULL - Error. Invalid Tx object configuration.
  • Valid Tx handle - Success.
Precondition:

Valid FFTC driver handle must be obtained by calling Fftc_open () API by the application before calling this API. Valid Tx configuration must be specified in 'pFFTCTxCfg' structure as input to this API.
Postcondition:

FFTC Tx queue open and setup if this API being called for first time for a given Tx queue number. Tx descriptors, buffers allocated as per input specified. Tx object is ready for use to submit FFT requests to the engine. ============================================================================
static Fftc_RetVal Fftc_txQueueClose ( Fftc_TxQInfo pFFTCTxQInfo) [static]

============================================================================
Fftc_txQueueClose

brief
This API decrements the reference count on the transmit queue handle provided and when the reference count reaches zero, i.e., when no application thread/flow is no longer using this transmit queue handle it frees up the FFTC transmit queue handle and all associated configuration. If an application wishes to use the transmit queue, it would have to do so by opening the FFTC transmit queue with appropriate configuration using the API Fftc_txQueueOpen ().

Parameters:
[in]pFFTCTxQInfoHandle to the transmit queue obtained using Fftc_txQueueOpen () API.
Returns:
Fftc_RetVal
  • FFTC_RETVAL_EBAD_HANDLE - Invalid transmit queue handle provided.
  • FFTC_RETVAL_SUCCESS - Succesfully closed the queue.
Precondition:

Fftc_txQueueOpen () must have been called succesfully to setup the FFTC transmit queue before calling this API.
Postcondition:

Reference counter on the queue handle decremented. If reference counter reaches zero, queue configuration cleaned up and all associated CPPI handles released. ============================================================================
static Fftc_TxQInfo* Fftc_txQueueOpen ( Fftc_InstanceInfo pFFTCInstInfo,
Fftc_QueueId  fftcTxQNum,
Fftc_QLocalCfg pFFTQCfg,
uint8_t  bSharedMode 
) [static]

============================================================================
Fftc_txQueueOpen

brief
If not already open, this API sets up the FFTC Transmit queue corresponding to the queue number specified in 'fftcTxQNum' (valid values 0-3) and the FFTC instance specified by 'pFFTCInstInfo' handle. If open already, the queue configuration is skipped.

As part of the queue configuration this API opens the CPPI queue, a Tx channel for it and also configures its FFTC Queue local registers.

The driver allows an FFTC queue to be opened in 2 modes, "shared" / "dedicated" modes; When opened in 'shared' mode by setting 'bSharedMode' to 1, multiple applications could share the same Tx queue to submit FFT requests to the engine. However, if the queue is opened in 'dedicated' mode by setting 'bSharedMode' to 0, then the driver ensures that no other application except the one that has opened it can use the queue for FFT processing.

If the queue had already been opened earlier and in 'shared' mode, then a call to this API simply increments it's reference count and returns the handle to the opened queue without modifying its configuration. A call to this API on an already open queue in 'dedicated' mode returns an error.

Parameters:
[in]pFFTCInstInfoFFTC instance information handle.
[in]fftcTxQNumFFTC Transmit queue number for which the setup needs to be performed. Valid values are between 0-3.
[in]pFFTQCfgConfiguration structure that holds the settings for various FFTC Queue local configuration registers.
[in]bSharedModeWhen this flag is set to 0, the driver ensures that no other thread/application uses the same FFTC transmit queue and also puts additional checks to ensure that the configuration for this queue cannot be overridden using CPPI packets on the data path. When set to 1, the queue is opened in shared mode and its configuration can be changed using CPPI packets by multiple applications.
Returns:
Fftc_TxQInfo*
  • NULL - Tx queue setup failed as per input provided.
  • Valid Handle - Success. Valid Tx queue handle returned.
Precondition:

Fftc_open () API must have been called to initialize the driver's global state before calling this API.
Postcondition:

FFTC Queue Local Configuration registers for the queue 'fftcTxQNum' are configured according to values specified in 'pFFTQCfg' structure and the corresponding CPPI channels and queues are opened too if called for the first time. Reference counter for the queue is incremented to keep track of all the application threads using this queue. ============================================================================
Fftc_RetVal Fftc_txSubmitRequest ( Fftc_TxHandle  hFFTCTxInfo,
Fftc_RequestHandle  hRequestInfo,
uint32_t  reqBufferLen 
)

============================================================================
Fftc_txSubmitRequest

brief
Given a Tx object handle, the request handle obtained from Fftc_txGetRequestBuffer() API, and the FFT request data buffer length, this API submits the FFT request to the hardware to do its processing. This API assumes that the data buffer length provided to this API doesnt exceed the maximum length returned by the Fftc_txGetRequestBuffer() API.

Alternatively, this API can be used also to submit Tx descriptors built by the application.

Parameters:
[in]hFFTCTxInfoTx handle obtained using Fftc_txOpen () API.
[in]hRequestInfoFFTC request handle obtained from Fftc_txGetRequestBuffer () API or Tx CPPI descriptor built by the application containing request data.
[in]reqBufferLenFFT Request data length. If data buffer was obtained using Fftc_txGetRequestBuffer () API, this must contain the actual length of buffer used not including the PS info length if PS in SOP. This and PS info length put together must not exceed the maximum buffer length obtained from Fftc_txGetRequestBuffer () API. In case of application managed descriptor, i.e., if descriptor was not built using Fftc_txGetRequestBuffer () API and built by application, then this must contain the descriptor length.
Returns:
Fftc_RetVal
  • FFTC_RETVAL_EBAD_HANDLE - Invalid input handles provided. FFTC Submit Request failed.
  • FFTC_RETVAL_SUCCESS - Successfully submitted the request.
Precondition:

A valid Tx object handle must be obtained using Fftc_txOpen (), and a valid request buffer handle obtained using Fftc_txGetRequestBuffer () API or any valid Tx CPPI descriptor handle must be sent to this API.
Postcondition:

FFTC Request submitted.

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


Copyright 2014, Texas Instruments Incorporated