dfeequ
Vitis Drivers API Documentation
Overview

Data Structures

struct  XDfeEqu_Version
 Logicore version. More...
 
struct  XDfeEqu_Trigger
 Trigger configuration. More...
 
struct  XDfeEqu_TriggerCfg
 All IP triggers. More...
 
struct  XDfeEqu_ModelParameters
 Equalizer Filter model parameters structure. More...
 
struct  XDfeEqu_Cfg
 Configuration. More...
 
struct  XDfeEqu_Coefficients
 Equalizer Coefficients Structure. More...
 
struct  XDfeEqu_EqConfig
 Equalizer Configuration Structure. More...
 
struct  XDfeEqu_Status
 Equalizer Status. More...
 
struct  XDfeEqu_InterruptMask
 Event status and interrupt mask. More...
 
struct  XDfeEqu_Config
 Equalizer Config Structure. More...
 
struct  XDfeEqu
 Equalizer Structure. More...
 

Macros

#define XDFEEQU_TAP_MAX   (24U)
 Maximum tap value. More...
 
#define XDFEEQU_DRIVER_VERSION_MINOR   (6U)
 Driver's minor version number. More...
 
#define XDFEEQU_DRIVER_VERSION_MAJOR   (1U)
 Driver's major version number. More...
 
#define XDFEEQU_MAX_NUM_INSTANCES   (10U)
 Maximum number of driver instances running at the same time. More...
 
#define XST_SUCCESS   (0L)
 Success flag. More...
 
#define XST_FAILURE   (1L)
 Failure flag. More...
 
#define XDFEEQU_NODE_NAME_MAX_LENGTH   (50U)
 Node name maximum length. More...
 
#define XDFEEQU_ANT_NUM_MAX   (8U)
 Maximum anntena number. More...
 
#define XDFEEQU_CHANNEL_NUM   (8U)
 Maximum channel number. More...
 
#define XDFEEQU_MAX_NUMBER_OF_UNITS_COMPLEX   (0x3U)
 Complex units number. More...
 
#define XDFEEQU_MAX_NUMBER_OF_UNITS_REAL   (0x6U)
 Real units number. More...
 
#define XDFEEQU_NUM_COEFF   (24U)
 Maximum number of coefficents. More...
 
#define XDFEEQU_DATAPATH_MODE_REAL   (0U)
 Real mode. More...
 
#define XDFEEQU_DATAPATH_MODE_COMPLEX   (1U)
 Complex mode. More...
 
#define XDFEEQU_COMPATIBLE_STRING   "xlnx,xdfe-equalizer-1.0"
 Device name property. More...
 
#define XDFEEQU_PLATFORM_DEVICE_DIR   "/sys/bus/platform/devices/"
 Device location in a file system. More...
 
#define XDFEEQU_COMPATIBLE_PROPERTY   "compatible"
 Device tree property. More...
 
#define XDFEEQU_BUS_NAME   "platform"
 System bus name. More...
 
#define XDFEEQU_BASEADDR_PROPERTY   "reg"
 Base address property. More...
 
#define XDFEEQU_BASEADDR_SIZE   8U
 Base address bit-size. More...
 
#define XDFEEQU_COMPLEX_MODE_CFG   "xlnx,complex-mode"
 Complex mode enabled property. More...
 
#define XDFEEQU_COMPONENT_NAME_CFG   "xlnx,component-name"
 Component name property. More...
 
#define XDFEEQU_DATA_IWIDTH_CFG   "xlnx,data-iwidth"
 Data IWIDTH property. More...
 
#define XDFEEQU_DATA_OWIDTH_CFG   "xlnx,data-owidth"
 Data OWIDTH property. More...
 
#define XDFEEQU_MAX_SAMPLE_RATE_CFG   "xlnx,max-sample-rate"
 Sample rate property. More...
 
#define XDFEEQU_NUM_CHANNELS_CFG   "xlnx,num-channels"
 Number of channels property. More...
 
#define XDFEEQU_TUSER_WIDTH_CFG   "xlnx,tuser-width"
 Width of the TUSER bus. More...
 
#define XDFEEQU_USE_EMULATION_CFG   "xlnx,use-emulation"
 Use emulation property. More...
 

Enumerations

enum  XDfeEqu_StateId {
  XDFEEQU_STATE_NOT_READY = 0, XDFEEQU_STATE_READY, XDFEEQU_STATE_RESET, XDFEEQU_STATE_CONFIGURED,
  XDFEEQU_STATE_INITIALISED, XDFEEQU_STATE_OPERATIONAL
}
 

Functions

XDfeEquXDfeEqu_InstanceInit (const char *DeviceNodeName)
 API initialises one instance of an Equalizer driver. More...
 
void XDfeEqu_InstanceClose (XDfeEqu *InstancePtr)
 API closes the instance of an Equalizer driver and moves the state machine to a Not Ready state. More...
 
void XDfeEqu_Reset (XDfeEqu *InstancePtr)
 Resets Equalizer and puts block into a reset state. More...
 
void XDfeEqu_Configure (XDfeEqu *InstancePtr, XDfeEqu_Cfg *Cfg)
 Reads configuration from device tree/xparameters.h and IP registers. More...
 
void XDfeEqu_Initialize (XDfeEqu *InstancePtr, const XDfeEqu_EqConfig *Config)
 DFE Equalizer driver one time initialisation and moves the state machine to a Initialised state. More...
 
void XDfeEqu_Activate (XDfeEqu *InstancePtr, bool EnableLowPower)
 Activates channel Equalizer moves the state machine to an Activated state. More...
 
void XDfeEqu_Deactivate (XDfeEqu *InstancePtr)
 Deactivates Equalizer and moves the state machine to Initialised state. More...
 
XDfeEqu_StateId XDfeEqu_GetStateID (XDfeEqu *InstancePtr)
 Gets a state machine state id. More...
 
void XDfeEqu_Update (const XDfeEqu *InstancePtr, const XDfeEqu_EqConfig *Config)
 Updates Equalizer mode. More...
 
void XDfeEqu_GetTriggersCfg (const XDfeEqu *InstancePtr, XDfeEqu_TriggerCfg *TriggerCfg)
 Returns current trigger configuration. More...
 
void XDfeEqu_SetTriggersCfg (const XDfeEqu *InstancePtr, XDfeEqu_TriggerCfg *TriggerCfg)
 Sets trigger configuration. More...
 
void XDfeEqu_LoadCoefficients (const XDfeEqu *InstancePtr, u32 ChannelField, u32 Mode, u32 Shift, const XDfeEqu_Coefficients *EqCoeffs)
 Sets Equalizer filter coefficients in Real, Complex or Matrix mode. More...
 
void XDfeEqu_GetActiveSets (const XDfeEqu *InstancePtr, u32 *RealSet, u32 *ImagSet)
 Gets used coefficients settings. More...
 
void XDfeEqu_SetTUserDelay (const XDfeEqu *InstancePtr, u32 Delay)
 Sets the delay, which will be added to TUSER and TLAST (delay matched through the IP). More...
 
u32 XDfeEqu_GetTUserDelay (const XDfeEqu *InstancePtr)
 Reads the delay, which will be added to TUSER and TLAST (delay matched through the IP). More...
 
u32 XDfeEqu_GetTDataDelay (const XDfeEqu *InstancePtr, u32 Tap)
 Returns data latency + tap, where the tap is between 0 and 23 in real mode and between 0 and 11 in complex mode. More...
 
void XDfeEqu_GetVersions (const XDfeEqu *InstancePtr, XDfeEqu_Version *SwVersion, XDfeEqu_Version *HwVersion)
 This API gets the driver and HW design version. More...
 
void XDfeEqu_GetEventStatus (const XDfeEqu *InstancePtr, XDfeEqu_Status *Status)
 Gets event status. More...
 
void XDfeEqu_ClearEventStatus (const XDfeEqu *InstancePtr, const XDfeEqu_Status *Status)
 Clears Equalizer status. More...
 
void XDfeEqu_SetInterruptMask (const XDfeEqu *InstancePtr, const XDfeEqu_InterruptMask *InterruptMask)
 Enables an Equalizer status for channel ID. More...
 
void XDfeEqu_GetInterruptMask (const XDfeEqu *InstancePtr, XDfeEqu_InterruptMask *InterruptMask)
 Gets interrupt mask. More...
 
int XDfeEqu_SelfExample ()
 This function runs the DFE Equalizer device using the driver APIs. More...
 
int XDfeEqu_PassThroughExample ()
 This function runs the DFE Equalizer device using the driver APIs. More...
 

Macro Definition Documentation

#define XDFEEQU_ANT_NUM_MAX   (8U)

Maximum anntena number.

#define XDFEEQU_BASEADDR_PROPERTY   "reg"

Base address property.

#define XDFEEQU_BASEADDR_SIZE   8U

Base address bit-size.

#define XDFEEQU_BUS_NAME   "platform"

System bus name.

#define XDFEEQU_CHANNEL_NUM   (8U)
#define XDFEEQU_COMPATIBLE_PROPERTY   "compatible"

Device tree property.

#define XDFEEQU_COMPATIBLE_STRING   "xlnx,xdfe-equalizer-1.0"

Device name property.

#define XDFEEQU_COMPLEX_MODE_CFG   "xlnx,complex-mode"

Complex mode enabled property.

#define XDFEEQU_COMPONENT_NAME_CFG   "xlnx,component-name"

Component name property.

#define XDFEEQU_DATA_IWIDTH_CFG   "xlnx,data-iwidth"

Data IWIDTH property.

#define XDFEEQU_DATA_OWIDTH_CFG   "xlnx,data-owidth"

Data OWIDTH property.

#define XDFEEQU_DATAPATH_MODE_COMPLEX   (1U)

Complex mode.

Referenced by XDfeEqu_LoadCoefficients(), and XDfeEqu_Update().

#define XDFEEQU_DATAPATH_MODE_REAL   (0U)

Real mode.

Referenced by XDfeEqu_Initialize(), and XDfeEqu_LoadCoefficients().

#define XDFEEQU_DRIVER_VERSION_MAJOR   (1U)

Driver's major version number.

Referenced by XDfeEqu_GetVersions().

#define XDFEEQU_DRIVER_VERSION_MINOR   (6U)

Driver's minor version number.

Referenced by XDfeEqu_GetVersions().

#define XDFEEQU_MAX_NUM_INSTANCES   (10U)

Maximum number of driver instances running at the same time.

#define XDFEEQU_MAX_NUMBER_OF_UNITS_COMPLEX   (0x3U)

Complex units number.

#define XDFEEQU_MAX_NUMBER_OF_UNITS_REAL   (0x6U)

Real units number.

#define XDFEEQU_MAX_SAMPLE_RATE_CFG   "xlnx,max-sample-rate"

Sample rate property.

#define XDFEEQU_NODE_NAME_MAX_LENGTH   (50U)

Node name maximum length.

Referenced by XDfeEqu_InstanceInit().

#define XDFEEQU_NUM_CHANNELS_CFG   "xlnx,num-channels"

Number of channels property.

#define XDFEEQU_NUM_COEFF   (24U)

Maximum number of coefficents.

Referenced by XDfeEqu_LoadCoefficients().

#define XDFEEQU_PLATFORM_DEVICE_DIR   "/sys/bus/platform/devices/"

Device location in a file system.

#define XDFEEQU_TAP_MAX   (24U)

Maximum tap value.

Referenced by XDfeEqu_GetTDataDelay().

#define XDFEEQU_TUSER_WIDTH_CFG   "xlnx,tuser-width"

Width of the TUSER bus.

#define XDFEEQU_USE_EMULATION_CFG   "xlnx,use-emulation"

Use emulation property.

#define XST_FAILURE   (1L)
#define XST_SUCCESS   (0L)

Enumeration Type Documentation

Enumerator
XDFEEQU_STATE_NOT_READY 

Not ready state.

XDFEEQU_STATE_READY 

Ready state.

XDFEEQU_STATE_RESET 

Reset state.

XDFEEQU_STATE_CONFIGURED 

Configured state.

XDFEEQU_STATE_INITIALISED 

Initialised state.

XDFEEQU_STATE_OPERATIONAL 

Operational state.

Function Documentation

void XDfeEqu_Activate ( XDfeEqu InstancePtr,
bool  EnableLowPower 
)

Activates channel Equalizer moves the state machine to an Activated state.

Parameters
InstancePtrPointer to the Equalizer instance.
EnableLowPowerFlag indicating low power.

References XDfeEqu::StateId, XDFEEQU_STATE_INITIALISED, and XDFEEQU_STATE_OPERATIONAL.

Referenced by XDfeEqu_PassThroughExample(), and XDfeEqu_SelfExample().

void XDfeEqu_ClearEventStatus ( const XDfeEqu InstancePtr,
const XDfeEqu_Status Status 
)

Clears Equalizer status.

The channel status will be cleared for any IStatus or QStatus not equal 0.

Parameters
InstancePtrPointer to the Equalizer instance.
StatusEqualizer status container.
Note
The Status registers are only present for a given channel when it is present in the configured IP. The number of channels present is given by CONFIG.NUM_CHANNELS.

References XDfeEqu_Status::IStatus, XDfeEqu_Status::QStatus, and XDFEEQU_CHANNEL_NUM.

void XDfeEqu_Configure ( XDfeEqu InstancePtr,
XDfeEqu_Cfg Cfg 
)
void XDfeEqu_Deactivate ( XDfeEqu InstancePtr)

Deactivates Equalizer and moves the state machine to Initialised state.

Parameters
InstancePtrPointer to the Equalizer instance.

References XDfeEqu::StateId, XDFEEQU_STATE_INITIALISED, and XDFEEQU_STATE_OPERATIONAL.

Referenced by XDfeEqu_PassThroughExample(), and XDfeEqu_SelfExample().

void XDfeEqu_GetActiveSets ( const XDfeEqu InstancePtr,
u32 *  RealSet,
u32 *  ImagSet 
)

Gets used coefficients settings.

Parameters
InstancePtrPointer to the Equalizer instance.
RealSetPointer to a real value.
ImagSetPointer to an imaginary value.

References XDfeEqu::StateId, and XDFEEQU_STATE_OPERATIONAL.

void XDfeEqu_GetEventStatus ( const XDfeEqu InstancePtr,
XDfeEqu_Status Status 
)

Gets event status.

Parameters
InstancePtrPointer to the Equalizer instance.
StatusEqualizer status container.

References XDfeEqu_Status::IStatus, XDfeEqu_Status::QStatus, and XDFEEQU_CHANNEL_NUM.

void XDfeEqu_GetInterruptMask ( const XDfeEqu InstancePtr,
XDfeEqu_InterruptMask InterruptMask 
)

Gets interrupt mask.

Parameters
InstancePtrPointer to the Equalizer instance.
InterruptMaskEqualizer interrupt mask container.

References XDfeEqu_InterruptMask::Mask, and XDFEEQU_CHANNEL_NUM.

XDfeEqu_StateId XDfeEqu_GetStateID ( XDfeEqu InstancePtr)

Gets a state machine state id.

Parameters
InstancePtrPointer to the Equalizer instance.
Returns
State machine StateID

References XDfeEqu::StateId.

u32 XDfeEqu_GetTDataDelay ( const XDfeEqu InstancePtr,
u32  Tap 
)

Returns data latency + tap, where the tap is between 0 and 23 in real mode and between 0 and 11 in complex mode.

Parameters
InstancePtrPointer to the Equalizer instance.
TapTap value.
Returns
Data latency value.

References XDFEEQU_TAP_MAX.

void XDfeEqu_GetTriggersCfg ( const XDfeEqu InstancePtr,
XDfeEqu_TriggerCfg TriggerCfg 
)

Returns current trigger configuration.

Parameters
InstancePtrPointer to the Equalizer instance.
TriggerCfgTrigger configuration container.

References XDfeEqu_TriggerCfg::Activate, XDfeEqu_TriggerCfg::LowPower, XDfeEqu_Trigger::Mode, XDfeEqu::StateId, XDfeEqu_Trigger::StateOutput, XDfeEqu_Trigger::TriggerEnable, XDfeEqu_Trigger::TUSERBit, XDfeEqu_Trigger::TuserEdgeLevel, XDfeEqu_TriggerCfg::Update, and XDFEEQU_STATE_NOT_READY.

u32 XDfeEqu_GetTUserDelay ( const XDfeEqu InstancePtr)

Reads the delay, which will be added to TUSER and TLAST (delay matched through the IP).

Parameters
InstancePtrPointer to the Equalizer instance.
Returns
Delay value
void XDfeEqu_GetVersions ( const XDfeEqu InstancePtr,
XDfeEqu_Version SwVersion,
XDfeEqu_Version HwVersion 
)

This API gets the driver and HW design version.

Parameters
SwVersionDriver version number.
HwVersionHW version number.

References XDfeEqu_Version::Major, XDfeEqu_Version::Minor, XDfeEqu_Version::Patch, XDfeEqu_Version::Revision, XDfeEqu::StateId, XDFEEQU_DRIVER_VERSION_MAJOR, XDFEEQU_DRIVER_VERSION_MINOR, and XDFEEQU_STATE_NOT_READY.

Referenced by XDfeEqu_PassThroughExample(), and XDfeEqu_SelfExample().

void XDfeEqu_Initialize ( XDfeEqu InstancePtr,
const XDfeEqu_EqConfig Config 
)

DFE Equalizer driver one time initialisation and moves the state machine to a Initialised state.

Parameters
InstancePtrPointer to the Equalizer instance.
ConfigConfiguration data container.

References XDfeEqu_EqConfig::DatapathMode, XDfeEqu_Trigger::Mode, XDfeEqu::StateId, XDfeEqu_Trigger::TriggerEnable, XDFEEQU_DATAPATH_MODE_REAL, XDFEEQU_STATE_CONFIGURED, and XDFEEQU_STATE_INITIALISED.

Referenced by XDfeEqu_PassThroughExample(), and XDfeEqu_SelfExample().

void XDfeEqu_InstanceClose ( XDfeEqu InstancePtr)

API closes the instance of an Equalizer driver and moves the state machine to a Not Ready state.

Parameters
InstancePtrPointer to the Equalizer instance.

References XDfeEqu::Device, XDfeEqu::NodeName, XDfeEqu::StateId, and XDFEEQU_STATE_NOT_READY.

Referenced by XDfeEqu_PassThroughExample(), and XDfeEqu_SelfExample().

XDfeEqu * XDfeEqu_InstanceInit ( const char *  DeviceNodeName)

API initialises one instance of an Equalizer driver.

Traverse "/sys/bus/platform/device" directory (in Linux), to find registered EQU device with the name DeviceNodeName. The first available slot in the instances array XDfeEqu_Equalizer[] will be taken as a DeviceNodeName object. On success it moves the state machine to a Ready state, while on failure stays in a Not Ready state.

Parameters
DeviceNodeNameDevice node name.
Returns
  • Pointer to the instance if successful.
  • NULL on error.

References XDfeEqu::Device, XDfeEqu::NodeName, XDfeEqu::StateId, XDFEEQU_NODE_NAME_MAX_LENGTH, XDFEEQU_STATE_NOT_READY, XDFEEQU_STATE_READY, XST_FAILURE, and XST_SUCCESS.

Referenced by XDfeEqu_PassThroughExample(), and XDfeEqu_SelfExample().

void XDfeEqu_LoadCoefficients ( const XDfeEqu InstancePtr,
u32  ChannelField,
u32  Mode,
u32  Shift,
const XDfeEqu_Coefficients EqCoeffs 
)

Sets Equalizer filter coefficients in Real, Complex or Matrix mode.

Parameters
InstancePtrPointer to the Equalizer instance.
ChannelFieldFlag in which bits indicate the channel is enabled.
ModeEqualizer mode.
ShiftCoefficient shift value.
EqCoeffsEqualizer coefficients container.

References XDfeEqu_Coefficients::Num, XDfeEqu_Coefficients::Set, XDfeEqu::StateId, XDFEEQU_DATAPATH_MODE_COMPLEX, XDFEEQU_DATAPATH_MODE_REAL, XDFEEQU_NUM_COEFF, and XDFEEQU_STATE_OPERATIONAL.

Referenced by XDfeEqu_PassThroughExample().

int XDfeEqu_PassThroughExample ( )

This function runs the DFE Equalizer device using the driver APIs.

This function does the following tasks:

  • Create and system initialize the device driver instance.
  • Read SW and HW version numbers.
  • Reset the device.
  • Configure the device.
  • Initialize the device.
  • Set the triggers
  • Activate the device.
  • Load an equalizer coefficients.
  • DeActivate the device.
Returns
  • XST_SUCCESS if the example has completed successfully.
  • XST_FAILURE if the example has failed.//! [testexample2]

References XDfeEqu_TriggerCfg::Activate, XDfeEqu_Coefficients::Coefficients, XDfeEqu_EqConfig::DatapathMode, XDfeEqu_Version::Major, XDfeEqu_Version::Minor, XDfeEqu_Trigger::Mode, XDfeEqu_Version::Patch, XDfeEqu_Version::Revision, XDfeEqu_Trigger::TUSERBit, XDfeEqu_Trigger::TuserEdgeLevel, XDfeEqu_TriggerCfg::Update, XDfeEqu_Activate(), XDfeEqu_Configure(), XDfeEqu_Deactivate(), XDfeEqu_GetVersions(), XDfeEqu_Initialize(), XDfeEqu_InstanceClose(), XDfeEqu_InstanceInit(), XDfeEqu_LoadCoefficients(), XDfeEqu_Reset(), XDfeEqu_SetTriggersCfg(), XST_FAILURE, and XST_SUCCESS.

Referenced by main().

void XDfeEqu_Reset ( XDfeEqu InstancePtr)

Resets Equalizer and puts block into a reset state.

Parameters
InstancePtrPointer to the Equalizer instance.

References XDfeEqu::StateId, XDFEEQU_STATE_NOT_READY, and XDFEEQU_STATE_RESET.

Referenced by XDfeEqu_PassThroughExample(), and XDfeEqu_SelfExample().

int XDfeEqu_SelfExample ( )

This function runs the DFE Equalizer device using the driver APIs.

This function does the following tasks:

  • Create and system initialize the device driver instance.
  • Read SW and HW version numbers.
  • Reset the device.
  • Configure the device.
  • Initialize the device.
  • Activate the device.
  • DeActivate the device.
Returns
  • XST_SUCCESS if the example has completed successfully.
  • XST_FAILURE if the example has failed.//! [testexample1]

References XDfeEqu_EqConfig::DatapathMode, XDfeEqu_Version::Major, XDfeEqu_Version::Minor, XDfeEqu_Version::Patch, XDfeEqu_Version::Revision, XDfeEqu_Activate(), XDfeEqu_Configure(), XDfeEqu_Deactivate(), XDfeEqu_GetVersions(), XDfeEqu_Initialize(), XDfeEqu_InstanceClose(), XDfeEqu_InstanceInit(), XDfeEqu_Reset(), XST_FAILURE, and XST_SUCCESS.

Referenced by main().

void XDfeEqu_SetInterruptMask ( const XDfeEqu InstancePtr,
const XDfeEqu_InterruptMask InterruptMask 
)

Enables an Equalizer status for channel ID.

Parameters
InstancePtrPointer to the Equalizer instance.
InterruptMaskEqualizer interrupt mask container.
Note
The Status Mask registers are only present for a given channel when it is present in the configured IP. The number of channels present is given by CONFIG.NUM_CHANNELS.

References XDfeEqu_InterruptMask::Mask, and XDFEEQU_CHANNEL_NUM.

void XDfeEqu_SetTriggersCfg ( const XDfeEqu InstancePtr,
XDfeEqu_TriggerCfg TriggerCfg 
)
void XDfeEqu_SetTUserDelay ( const XDfeEqu InstancePtr,
u32  Delay 
)

Sets the delay, which will be added to TUSER and TLAST (delay matched through the IP).

Parameters
InstancePtrPointer to the Equalizer instance.
DelayRequested delay variable.

References XDfeEqu::StateId, and XDFEEQU_STATE_INITIALISED.

void XDfeEqu_Update ( const XDfeEqu InstancePtr,
const XDfeEqu_EqConfig Config 
)

Updates Equalizer mode.

Config.DatapathMode defines real or complex Equalizer mode. Config.RealDatapathSet and Config.ImDatapathSet defines which coefficient set to be used in real or complex mode. Config.Flush = 1 instructs to flush the buffers.

Parameters
InstancePtrPointer to the Equalizer instance.
Configconfiguration container.

References XDfeEqu_EqConfig::DatapathMode, XDfeEqu_EqConfig::Flush, XDfeEqu_EqConfig::ImDatapathSet, XDfeEqu_EqConfig::RealDatapathSet, and XDFEEQU_DATAPATH_MODE_COMPLEX.