| rfdc Vitis Drivers API Documentation

- Overview
- Data Structures
- APIs
- File List
- Examples

rfdc Documentation

The Xilinx� LogiCORE IP Zynq UltraScale+ RFSoC RF Data Converter IP core provides a configurable wrapper to allow the RF DAC and RF ADC blocks to be used in IP Integrator designs. Multiple tiles are available on each RFSoC and each tile can have a number of data converters (analog-to-digital (ADC) and digital-to-analog (DAC)). The RF ADCs can sample input frequencies up to 4 GHz at 4 GSPS with excellent noise spectral density. The RF DACs generate output carrier frequencies up to 4 GHz using the 2nd Nyquist zone with excellent noise spectral density at an update rate of 6.4 GSPS. The RF data converters also include power efficient digital down-converters (DDCs) and digital up-converters (DUCs) that include programmable interpolation and decimation, NCO and complex mixer. The DDCs and DUCs can also support dual-band operation. A maximum of 4 tiles are available on for DAC and ADC operations each. Each tile can have a maximum of 4 blocks/slices. This driver provides APIs to configure various functionalities. Similarly the driver provides APIs to read back configurations. Some of the features that the driver supports are: 1) Setting up and reading back fine mixer settings 2) Setting up and reading back coarse mixer settings 3) Reading back interpolation or decimation factors 4) Setting up and reading back QMC settings which include gain, phase etc 5) Setting up and reading back decoder mode settings 6) Setting up and reading back coarse delay settings All the APIs implemented in the driver provide appropriate range checks. An API has been provided for debug purpose which will dump all registers for a requested tile. Inline functions have also been provided to read back the parameters initially configured through the GUI.

There are plans to add more features, e.g. Support for multi band, PLL configurations etc.

    MODIFICATION HISTORY:

    Ver   Who    Date     Changes

    1.0   sk     05/16/17 Initial release
    2.0   sk     08/09/17 Fixed coarse Mixer configuration settings
                          CR# 977266, 977872.
                          Return error for Slice Event on 4G ADC Block.
                          Corrected Interrupt Macro names and values.
                 08/16/17 Add support for SYSREF and PL event sources.
                 08/18/17 Add API to enable and disable FIFO.
                 08/23/17 Add API to configure Nyquist zone.
                 08/30/17 Add additional info to BlockStatus.
                 08/30/17 Add support for Coarse Mixer BYPASS mode.
                 08/31/17 Removed Tile Reset Assert and Deassert.
                 09/07/17 Add support for negative NCO freq.
                 09/15/17 Fixed NCO freq precision issue.
                 09/15/17 Fixed Immediate Event source issue and also
                          updated the Immediate Macro value to 0.
    2.1   sk     09/15/17 Remove Libmetal library dependency for MB.
                 09/18/17 Add API to clear the interrupts.
          sk     09/21/17 Add BAREMETAL compiler flag option
                          for Baremetal.
          sk     09/21/17 Add support for Over voltage and Over
                          Range interrupts.
          sk     09/22/17 Add s64 typedef for Linux.
          sk     09/24/17 Fixed Get_Tile/BlockBaseAddr always
                          giving ADC related address.
          sk     09/25/17 Modified XRFdc_GetBlockStatus API to give
                          correct information and also updates the
                          description for Vector Param in intr handler
                          Add API to get Output current and removed
                          GetTermVoltage and GetOutputCurr inline functions.
    2.2   sk     10/05/17 Fixed XRFdc_GetNoOfADCBlocks API for 4GSPS.
                          Enable the decoder clock based on decoder mode.
                          Add API to get the current FIFO status.
                          Updated XRFdc_DumpRegs API for better readability
                          of output register dump.
                          Add support for 4GSPS CoarseMixer frequency.
                 10/11/17 Modify float types to double to increase precision.
                 10/12/17 Update BlockStatus API to give current status.
                          In BYPASS mode, input datatype can be Real or IQ
                          hence checked both while reading the mixer mode.
                 10/17/17 Fixed Set Threshold API Issue.
    2.2   sk     10/18/17 Add support for FIFO and DATA overflow interrupt
    2.3   sk     11/06/17 Fixed PhaseOffset truncation issue.
                          Provide user configurability for FineMixerScale.
                 11/08/17 Return error for DAC R2C mode and ADC C2R mode.
                 11/10/17 Corrected FIFO and DATA Interrupt masks.
                 11/20/17 Fixed StartUp, Shutdown and Reset API for Tile_Id -1.
                 11/20/17 Remove unwanted ADC block checks in 4GSPS mode.
    3.0   sk     12/11/17 Added DDC and DUC support.
                 12/13/17 Add CoarseMixMode field in Mixer_Settings structure.
                 12/15/17 Add support to switch calibration modes.
                 12/15/17 Add support for mixer frequencies > Fs/2 and < -Fs/2.
          sg     13/01/18 Added PLL and external clock switch support
                          Added API to get PLL lock status.
                          Added API to get clock source.
          sk     01/18/18 Add API to get driver version.
    3.1   jm     01/24/18 Add Multi-tile sync support.
          sk     01/25/18 Updated Set and Get Interpolation/Decimation factor
                          API's to consider the actual factor value.
    3.2   sk     02/02/18 Add API's to configure inverse-sinc.
          sk     02/27/18 Add API's to configure Multiband.
          sk     03/09/18 Update PLL structure in XRFdc_DynamicPLLConfig API.
          sk     03/09/18 Update ADC and DAC datatypes in Mixer API and use
                          input datatype for ADC in threshold and QMC APIs.
          sk     03/09/18 Removed FIFO disable check in DDC and DUC APIs.
          sk     03/09/18 Add support for Marker event source for DAC block.
          jm     03/12/18 Fixed DAC latency calculation in MTS.
          jm     03/12/18 Added support for reloading DTC scans.
          jm     03/12/18 Add option to configure sysref capture after MTS.
          sk     03/22/18 Updated PLL settings based on latest IP values.
    4.0   sk     04/09/18 Added API to enable/disable the sysref.
          sk     04/09/18 Updated max VCO to 13108MHz to support max DAC
                          sample rate of 6.554MHz.
          rk     04/17/18 Adjust calculated latency by sysref period, where doing
                          so results in closer alignment to the target latency.
          sk     04/17/18 Corrected Set/Get MixerSettings API description for
                          FineMixerScale parameter.
          sk     04/19/18 Enable VCO Auto selection while configuring the clock.
          sk     04/24/18 Add API to get PLL Configurations.
          sk     04/24/18 Add API to get the Link Coupling mode.
          sk     04/28/18 Implement timeouts for PLL Lock, Startup and shutdown.
          sk     05/30/18 Removed CalibrationMode check for DAC.
          sk     06/05/18 Updated minimum Ref clock value to 102.40625MHz.
    5.0   sk     06/25/18 Update DAC min sampling rate to 500MHz and also update
                          VCO Range, PLL_DIVIDER and PLL_FPDIV ranges.
                          Update PLL structure with calculated sampling rate.
          sk     06/25/18 Add XRFdc_GetFabClkOutDiv() API to read fabric clk div.
                          Add Inline APIs XRFdc_CheckBlockEnabled(),
                          XRFdc_CheckTileEnabled().
          sk     07/06/18 Add support to dump HSCOM regs in XRFdc_DumpRegs() API
          sk     07/12/18 Fixed Multiband crossbar settings in C2C mode.
          sk     07/19/18 Add MixerType member to MixerSettings structure and
                          Update Mixer Settings APIs to consider the MixerType
                          variable.
          sk     07/19/18 Add XRFdc_GetMultibandConfig() API to read Multiband
                          configuration.
          sk     07/20/18 Update the APIs to check the corresponding section
                          (Digital/Analog)enable/disable.
          sk     07/26/18 Fixed Doxygen, coverity warnings.
          sk     08/03/18 Fixed MISRAC warnings.
          sk     08/24/18 Move mixer related APIs to xrfdc_mixer.c file.
                          Define asserts for Linux, Re-arranged XRFdc_RestartIPSM,
                          XRFdc_CfgInitialize() and XRFdc_MultiBand()  APIs.
                          Reorganize the code to improve readability and
                          optimization.
          mus    08/17/18 Removed structure paddings from XRFdc_Config structure.
                          It has been done to have 1:1 mapping between
                          XRFdc_Config structure and device tree property
                          "param-list", over linux platform.
          sk     09/24/18 Update powerup-state value based on PLL mode in
                          XRFdc_DynamicPLLConfig() API.
          sk     10/10/18 Check for DigitalPath enable in XRFdc_GetNyquistZone()
                          and XRFdc_GetCalibrationMode() APIs for Multiband.
          sk     10/13/18 Add support to read the REFCLKDIV param from design.
                          Update XRFdc_SetPLLConfig() API to support range of
                          REF_CLK_DIV values(1 to 4).
                          Add XRFDC_MIXER_MODE_R2R option to support BYPASS mode
                          for Real input.
    5.1   cog    01/29/19 Replace structure reference ADC checks with
                          function.
          cog    01/29/19 Added XRFdc_SetDither() and XRFdc_GetDither() APIs.
          cog    01/29/19 Rename DataType for mixer input to MixerInputDataType
                          for readability.
          cog    01/29/19 Refactoring of interpolation and decimation APIs and
                          changed fabric rate for decimation X8 for non-high speed ADCs.
          cog    01/29/19 New inline functions to determine max & min sampling rates.
    6.0   cog    02/17/19 Added Inverse-Sinc Second Nyquist Zone Support
          cog    02/17/19 Added new clock Distribution functionality.
          cog    02/17/19 Refactored to improve delay balancing in clock
                          distribution.
          cog    02/17/19 Added delay calculation & metal log messages.
          cog    02/17/19 Added Intratile clock settings.
          cog    02/17/19 XRFdc_GetPLLConfig() now uses register values to get the
                          PLL configuration for new IPs and is no longer static.
          cog    02/17/19 Refactoring of interpolation and decimation APIs and
                          changed fabric rate for decimation X8 for non-high speed ADCs.
          cog    02/17/19 Added XRFdc_SetIMRPassMode() and XRFdc_SetIMRPassMode() APIs
          cog    02/17/19 Added XRFdc_SetDACMode() and XRFdc_GetDACMode() APIs
          cog    02/17/19   Added XRFdc_SetSignalDetector() and XRFdc_GetSignalDetector() APIs
          cog    02/17/19 Added XRFdc_DisableCoefficientsOverride(), XRFdc_SetCalCoefficients
                          and XRFdc_GetCalCoefficients APIs.
          cog    02/19/19 New definitions for clock detection.
    6.0   cog    02/20/19   Added handling for new ADC common mode over/under
                          voltage interrupts.
          cog    02/20/19   XRFdc_GetIntrStatus now populates a pointer with the
                          status and returns an error code.
          cog          02/20/19     XRFdc_IntrClr, XRFdc_IntrDisable and XRFdc_IntrEnable
                          now return error codes.
          cog    02/21/19 Added XRFdc_SetCalFreeze() and XRFdc_GetCalFreeze() APIs
          cog    04/15/19 Rename XRFdc_SetDACMode() and XRFdc_GetDACMode() APIs to
                          XRFdc_SetDataPathMode() and XRFdc_GetDataPathMode() respectively.
    7.0   cog    05/13/19 Formatting changes.
          cog    05/13/19 Added new bock MACROs.
          cog    05/13/19 XRFdc_CheckTileEnabled(), XRFdc_IsDACBlockEnabled(),
                          XRFdc_IsADCBlockEnabled(), XRFdc_IsDACDigitalPathEnabled() &
                          XRFdc_IsADCDigitalPathEnabled() APIs now derive answer from
                          DRP rather than context structure.
          cog    06/12/19 Fixed issue where positive NCO frequencies were not being
                          set correctly.
          cog    07/14/19 Added new off mode for mixers (both mixers off).
          cog    07/16/19 The powerup state is not necessary to be checked for the
                          tile/block/digital path enabled functions and had potential
                          to cause lockout.
          cog    07/16/19 Added XRFdc_SetDACOpCurr() API.
          cog    07/18/19 Added XRFdc_S/GetDigitalStepAttenuator() APIs.
          cog    07/25/19 Added new XRFdc_RegisterMetal() API to register RFDC with Libmetal.
          cog    07/25/19 Moved XRFDC_PLL_LOCK_DLY_CNT macro from source file.
          cog    07/26/19 Added new XRFdc_S/GetLegacyCompatibilityMode() APIs.
          cog    07/29/19 Added XRFdc_GetEnabledInterrupts() API.
          cog    08/02/19 Formatting changes and added a MACRO for the IP generation.
          cog    09/01/19 Changed the MACRO for turning off the mixer.
          cog    09/01/19 XRFdc_CheckTileEnabled(), XRFdc_IsDACBlockEnabled(),
                          XRFdc_IsADCBlockEnabled(), XRFdc_IsDACDigitalPathEnabled() &
                          XRFdc_IsADCDigitalPathEnabled() APIs now get answer from
                          context structure.
          cog    09/01/19 Rename new XRFdc_S/GetLegacyCompatibilityMode() APIs to
                          XRFdc_S/GetDACCompMode().
          cog    09/01/19 Rename XRFdc_S/GetDigitalStepAttenuator() APIs to XRFdc_S/GetDSA().
                          Also, add new XRFdc_DSA_Settings structure.
          cog    09/12/19 Swapped MIXER_TYPE_OFF and MIXER_TYPE_DISABLED macros.
          cog    09/18/19 Minumum output divider is now 1 for Gen 3 devices.
          cog    09/18/19 Changed clock distribution macros, also removed prototype for a function
                          that is now static.
          cog    10/02/19 Added macros for the clock divider.
          cog    10/02/19 Added macro for fabric rate of 16.
          cog    10/02/19 Added macros for new VCO ranges.
    7.1   cog    11/14/19 Increased ADC fabric read rate to 12 words per cycle for Gen 3 devices.
          cog    11/15/19 Added macros for calibration mode support for Gen 3 devices.
          cog    11/28/19 Datapath mode macros have been changed to reflect the new functionality.
          cog    01/08/20 Added programmable hysteresis counters for ADC signal detector.
          cog    01/23/20 Calibration modes for Gen 3 were inverted.
    8.0   cog    02/10/20 Updated addtogroup and added s16 typedef.
          cog    02/10/20 Added Silicon revison to dirver structures to allow discrimation
                          between engineering sample & production silicon.
          cog    02/17/20 Driver now gets tile/path enables from the bitfile.
          cog    02/20/20 Added macros for Clock Gater handling.
          cog    03/05/20 IMR datapath modes require the frequency word to be doubled.
          cog    03/20/20 Updated PowerState masks for Gen 3 Devices.
    8.1   cog    06/24/20 Upversion.
          cog    06/24/20 Expand range of DSA for production Si.
          cog    06/24/20 Expand range of VOP for production Si.
          cog    06/24/20 MB config is now read from bitstream.
          cog    06/24/20 Added observation FIFO and decimation functionality.
          cog    06/24/20 Added channel powerdon functionality.
          cog    06/24/20 Refactor to functionaize the FIFO width setting.
          cog    08/04/20 Added multiband macros.
          cog    09/08/20 The Four LSBs of the BLDR Bias Current should be the same as the
                          four LSBs of the CS Gain.
          cog    09/28/20 Change XRFdc_IsHighSpeedADC to accomodate 43dr parts.
          cog    10/05/20 Change shutdown end state for Gen 3 Quad ADCs to reduce power
                          consumption.
          cog    10/14/20 Get I and Q data now supports warm bitstream swap.
    9.0   cog    11/25/20 Upversion.
    10.0  cog    11/26/20 Refactor and split files.
          cog    11/27/20 Added functionality for 6xdr devices.
          cog    12/02/20 Supplied FS was being saved rather than actual FS when
                          setting PLL.
          cog    12/04/20 Reduce scope of non user interface macros.
          cog    01/05/21 Signal detector on/off counters needed to be flipped.
          cog    01/05/21 Second signal detector removed.
          cog    01/06/21 Added DAC data scaler APIs.
          cog    01/11/21 Tuning for autocalibration.
          cog    02/10/21 Added custom startup API.
          cog    03/08/21 MTS now scans reference tile first. This has required a
                          change to the prototype of XRFdc_MultiConverter_Init.
          cog    03/12/21 Tweaks for improved calibration performance.
          cog    05/05/21 Fixed issue where driver was attempting to start ADC 3
                          for DFE variants.
          cog    05/05/21 Rename the MAX/MIN macros to avoid potential conflicts.
    11.0  cog    05/31/21 Upversion.
          cog    07/12/21 Simplified clock distribution user interface.
          cog    08/18/21 Disallow VOP for DC coupled DACs.
    11.1  cog    11/16/21 Upversion.
          cog    11/26/21 Header file clean up, this fixes a C++ compilation issue.
          cog    11/26/21 Pack all structs for RAFT compatibility.
          cog    12/06/21 Rearrange XRFdc_Distribution_Settings.
          cog    01/18/22 Added safety checks.
    12.0  cog    10/26/22 Added API XRFdc_GetCoupling(), this gets the ADC or
                          DAC coupling.
          cog    01/07/23 Added VOP support for DC coupled DACs and removed VOP
                          support for ES1 Parts.
    12.1  cog    07/04/23 Add support for SDT.
          cog    07/14/23 Fix issues with SDT flow.
          cog    07/27/23 Add NCO frequency to config structures.
    12.3  cog    07/09/24 Corrected GEN3 maximum ADC VCO frequency.