Files

524 lines
21 KiB
C
Executable File

/**
* \file talise.h
* \brief Contains top level Talise related function prototypes for
* talise.c
*
* Talise API version: 3.5.0.2
*
* Copyright 2015-2017 Analog Devices Inc.
* Released under the AD9378-AD9379 API license, for more information see the "LICENSE.txt" file in this zip file.
*/
#ifndef TALISE_H_
#define TALISE_H_
#ifdef __cplusplus
extern "C" {
#endif
#include "talise_types.h"
/****************************************************************************
* Initialization functions
****************************************************************************
*/
/**
* \brief Performs a Hardware Initialization for Talise Device.
*
* This API shall call the ADI HAL function ADIHAL_openHw for
* Talise Hardware initialization. This HAL function initializes all the external
* hardware blocks required in the operation of the Talise device.
* This API will also set the HAL timeout limit for the HAL driver as per API
* requirements.
*
* \pre This function may be called after device->devHalInfo has been initialized with
* user values
*
* \dep_begin
* \dep{device->devHalInfo}
* \dep_end
*
* \param device Pointer to Talise device data structure. taliseDevice_t member
* devHalInfo shall be initialized with all the required information to initialize
* external Hardware required for Talise operation for example
* power, pull ups, SPI master etc
*
* \retval TALACT_ERR_CHECK_PARAM Recovery action for bad parameter check
* \retval TALACT_ERR_CHECK_TIMER Recovery action for timer time-out check required
* \retval TALACT_ERR_RESET_SPI Recovery action for SPI reset required
* \retval TALACT_ERR_RESET_GPIO Recovery action for user GPIO reset required
* \retval TALACT_NO_ACTION Function completed successfully, no action required
*/
uint32_t TALISE_openHw(taliseDevice_t *device);
/**
* \brief Performs a hardware shutdown for Talise Device.
*
* This API shall call the ADI HAL function ADIHAL_closeHw for
* Talise Hardware shutdown. This HAL function shuts down all the external
* hardware blocks required in the operation of the Talise device.
*
* \pre This function may be called any time after device->devHalInfo has been
* initialized with user values
*
* \dep_begin
* \dep{device->devHalInfo}
* \dep_end
*
* \param device Pointer to Talise device data structure. taliseDevice_t member
* devHalInfo shall be initialized with all the required information to initialize
* supporting Hardware for Talise operation for example
* power, pull ups, SPI master etc
*
* \retval TALACT_ERR_CHECK_PARAM Recovery action for bad parameter check
* \retval TALACT_ERR_CHECK_TIMER Recovery action for timer time-out check required
* \retval TALACT_ERR_RESET_SPI Recovery action for SPI reset required
* \retval TALACT_ERR_RESET_GPIO Recovery action for user GPIO reset required
* \retval TALACT_NO_ACTION Function completed successfully, no action required
*/
uint32_t TALISE_closeHw(taliseDevice_t *device);
/**
* \brief Performs a hard reset on the TALISE DUT (Toggles RESETB pin on device)
*
* Toggles the Talise devices RESETB pin. Only resets the device with
* the SPI chip select indicated in the device->spiSettings structure.
*
* \pre This function may be called any time after device->devHalInfo has been
* initialized with user values
*
* \dep_begin
* \dep{device->devHalInfo}
* \dep_end
*
* \param device Pointer to Talise device data structure containing settings
*
* \retval TALACT_WARN_RESET_LOG Recovery action for log reset
* \retval TALACT_WARN_RESET_GPIO Recovery action to warn user a GPIO reset may be required
* \retval TALACT_ERR_RESET_GPIO Recovery action for user GPIO reset required
* \retval TALACT_NO_ACTION Function completed successfully, no action required
*/
uint32_t TALISE_resetDevice(taliseDevice_t *device);
/**
* \brief Initializes the Talise device based on the desired device settings.
*
* This function initializes the Talise device, setting up the CLKPLL, digital clocks,
* JESD204b settings, FIR Filters, digital filtering. It does not load the ARM
* or perform any of the ARM init calibrations. It also sets the Rx Manual gain indexes and
* TxAttenuation settings to the initial values found in the device data structure. It leaves the
* Talise in a state ready for multichip sync (which can bring up the JESD204 links), the
* ARM to be loaded, and the init calibrations run.
*
* \pre This function is the very first API to be called by the user to configure the device
* after all dependent data structures have been initialized
*
* \dep_begin
* \dep{device (all members)}
* \dep{init (all members)}
* \dep_end
*
* \param device Pointer to Talise device data structure
* \param init Pointer to Talise initialization settings structures
*
* \retval TALACT_WARN_RESET_LOG Recovery action for log reset
* \retval TALACT_ERR_CHECK_PARAM Recovery action for bad parameter check
* \retval TALACT_ERR_RESET_SPI Recovery action for SPI reset required
* \retval TALACT_NO_ACTION Function completed successfully, no action required
*/
uint32_t TALISE_initialize(taliseDevice_t *device, taliseInit_t *init);
/**
* \brief API To safely Shutdown Talise
*
* The User should call this function to safely shutdown Talise Device.
* The function performs a hardware reset to reset the Talise Device into a safe
* state for shutdown or re-initialization.
*
* \pre This function may be called at any time but not before device->devHalInfo
* has been configured with user device settings
*
* \dep_begin
* \dep{device->devHalInfo}
* \dep_end
*
* \retval TALACT_NO_ACTION Function completed successfully, no action required
*/
uint32_t TALISE_shutdown(taliseDevice_t *device);
/**
* \brief Reads back the multi-chip sync status
*
* This function returns the status of the Talise MCS state machine via the mcsStatus pointer.
* The 4 LSBs of the uint8_t value at mcsStatus represent the sync status
* of JESD, Digital Clocks, CLK PLL and Device Clock divider.
* mcsStatus | bit Description
* -----------|--------------------------------------------------------
* [0] | MCS JESD SYSREF Status
* [1] | MCS Digital Clocks Sync Status
* [2] | MCS CLKPLL SDM Sync Status
* [3] | MCS Device Clock divider Sync Status
*
* A bit value of 1 indicates that the sync occured
* A bit value of 0 indicates that the sync has not occured.
*
*
* \pre This function can be called any time after the device has been initialized and PLL lock status has
* been verified.
*
* \dep_begin
* \dep{device->devHalInfo}
* \dep_end
*
* \param device is a pointer to the device settings structure
* \param mcsStatus Returns the mcsStatus word described in the table above.
*
* \retval TALACT_WARN_RESET_LOG Recovery action for log reset
* \retval TALACT_ERR_CHECK_PARAM Recovery action for bad parameter check
* \retval TALACT_ERR_RESET_SPI Recovery action for SPI reset required
* \retval TALACT_NO_ACTION Function completed successfully, no action required
*/
uint32_t TALISE_getMultiChipSyncStatus(taliseDevice_t *device, uint8_t *mcsStatus);
/**
* \brief Sets up the chip for multichip sync, and cleans up after MCS.
*
* When working with multiple transceivers or even only one transceiver that
* requires deterministic latency between the Tx and observation and or main
* Rx JESD204B data path, Multichip sync is necessary. This function should
* be run after all transceivers have finished the TALISE_initialize(),
* and before TALISE_initArm().
*
* When the enableMcs parameter = 1, this function will reset the MCS state
* machine in the Talise device. Calling the function again, will reset
* the state machine and expect the MCS sequence to start over.
*
* When the enableMcs parameter = 0, the MCS state machine is not changed,
* allowing the user to read back the MCS status in the mcsStatus parameter.
*
* Typical sequence:
* 1) Initialize all Talise devices in system using TALISE_initialize()
* 2) Run TALISE_enableMultichipSync with enableMcs = 1
* 3) Send at least 3 SYSREF pulses, and verify mcsStatus is set for each
* MCS step
* 4) Run TALISE_enableMultichipSync with enableMcs = 0 and verify mcsStatus
* returns a x0B (CLKPLL in interger mode), or x0F (CLKPLL in fractional
* mode).
* 5) Continue with init sequnece ...Run initARM, loadArm, etc
*
* mcsStatus | bit Description
* -----------|--------------------------------------------------------
* [0] | MCS JESD SYSREF Status (1 = sync occurred)
* [1] | MCS Digital Clocks Sync Status (1 = sync occurred)
* [2] | MCS CLKPLL SDM Sync Status (1 = sync occurred)
* [3] | MCS Device Clock divider Sync Status (1 = sync occurred)
*
* \pre This function is called after the device has been initialized and PLL lock status has
* been verified
*
* \dep_begin
* \dep{device->devHalInfo}
* \dep_end
*
* \param device is a pointer to the device settings structure
* \param enableMcs =1 will enable/reset the MCS state machine
* \param mcsStatus optional parameter, if pointer is not null, the function will return the mcsStatus word described in the table above.
*
* \retval TALACT_WARN_RESET_LOG Recovery action for log reset
* \retval TALACT_ERR_CHECK_PARAM Recovery action for bad parameter check
* \retval TALACT_ERR_RESET_SPI Recovery action for SPI reset required
* \retval TALACT_NO_ACTION Function completed successfully, no action required
*/
uint32_t TALISE_enableMultichipSync(taliseDevice_t *device, uint8_t enableMcs, uint8_t *mcsStatus);
/****************************************************************************
* Runtime functions
****************************************************************************
*/
/****************************************************************************
* Helper functions
****************************************************************************
*/
/**
* \brief Configures one or more FIR filters in the device
*
* The device stores up to 5 FIR filter banks (2Rx | 2Obs Rx | Loopback & 2Tx).
* Rx filters can have 24, 48, or 72 taps.
* Tx filters can have 20, 40, 60, or 80 taps.
*
* The function is not called directly. It is called as a part of the TALISE_initialize() function.
* The function could be used to change A FIR filter later, but would require calibrations to be rerun.
*
* \pre This function is called during device initialization
*
* \dep_begin
* \dep{device->devHalInfo}
* \dep_end
*
* \param device Pointer to the Talise data structure
* \param filterToProgram Name of the desired filter to program
* \param firFilter Pointer to the filter to write into the device
*
* \retval TALACT_WARN_RESET_LOG Recovery action for log reset
* \retval TALACT_ERR_CHECK_PARAM Recovery action for bad parameter check
* \retval TALACT_ERR_RESET_SPI Recovery action for SPI reset required
* \retval TALACT_NO_ACTION Function completed successfully, no action required
*/
uint32_t TALISE_programFir(taliseDevice_t *device, talisefirName_t filterToProgram, taliseFir_t *firFilter);
/**
* \brief Calculates high speed digital clocks used in the Talise device
*
* This is a helper function called in TALISE_initialize() to calculate the internal
* digital clocks in Talise for use throughout other API functions. The calculated
* values are stored in the Talise API device structure with other other run-time state
* information for the API.
*
* \pre This function is private and is not called directly by the user.
*
* \dep_begin
* \dep{device->devHalInfo}
* \dep_end
*
* \param device Structure pointer to the Talise device data structure containing settings
* \param digClocks Pointer to the Talise digital clocks initialization data structure
*
* \retval TALACT_WARN_RESET_LOG Recovery action for log reset
* \retval TALACT_ERR_CHECK_PARAM Recovery action for bad parameter check
* \retval TALACT_NO_ACTION Function completed successfully, no action required
*/
uint32_t TALISE_calculateDigitalClocks(taliseDevice_t *device, taliseDigClocks_t *digClocks);
/**
* \brief Verifies the init structure profiles are valid combinations
*
* This function checks that the Rx/Tx/ORx profiles have valid clock rates in
* order to operate together. Rx/Tx and ORx share a common high speed digital
* clock. If an invalid combination of profiles is detected, an error will be
* returned. If a profile in the init structure is unused, the user should zero
* out all members of that particular profile structure. If a Rx/Tx/ORx profile
* has an IQ rate = 0, it is assumed that the profile is disabled.
*
* \pre This function is private and is not called directly by the user.
*
* This function uses TALISE_verifyTxProfile(), TALISE_verifyRxProfile(), and
* TALISE_verifyOrxProfile() as helper functions.
*
* \dep_begin
* \dep{device->devStateInfo}
* \dep{init-> (most members)}
* \dep_end
*
* \param device Structure pointer to Talise device data structure
* \param init Pointer to Talise initialization settings structures
*
* \retval TALACT_ERR_CHECK_PARAM Recovery action for bad parameter check
* \retval TALACT_NO_ACTION Function completed successfully, no action required
*/
uint32_t TALISE_verifyProfiles(taliseDevice_t *device, taliseInit_t *init);
/**
* \brief Sets the Talise device SPI settings (3wire/4wire, MSBFirst, etc).
*
* This function will use the settings in the passed spi structure parameter
* to set SPI stream mode, address auto increment direction, MSBFirst/LSBfirst,
* and 3wire/4wire mode for the Talise SPI controller. The Talise device
* always uses SPI MODE 0 (CPHA=0, CPOL=0) and a 16-bit instruction word.
*
* \pre This function is a helper function and does not need to be called
* directly by the user.
*
* \dep_begin
* \dep{device->devHalInfo}
* \dep{init->spiSettings->MSBFirst}
* \dep{init->spiSettings->enSpiStreaming}
* \dep{init->spiSettings->autoIncAddrUp}
* \dep{init->spiSettings->fourWireMode}
* \dep_end
*
* \param device Structure pointer to Talise device data structure
* \param spi Pointer to Talise SPI controller settings - not platform hardware SPI settings
*
* \retval TALACT_WARN_RESET_LOG Recovery action for log reset
* \retval TALACT_ERR_RESET_SPI Recovery action for SPI reset required
* \retval TALACT_NO_ACTION Function completed successfully, no action required
*/
uint32_t TALISE_setSpiSettings(taliseDevice_t *device, taliseSpiSettings_t *spi);
/**
* \brief Verifies whether the existing SPI settings work.
*
* This function checks the SPI settings set through TALISE_setSpiSettings for
* correct functionality. The function performs the following function:
*
* 1. Reads readonly register to check SPI read operation.
* 2. Writes scratchpad register with 10110110, reads back the data
* 3. Writes scratchpad register with 01001001, reads back the data
*
* The function performs the above operation on registers at the lower end of
* the register address space, and on the upper end of the register address
* space.
*
* \pre This function is a helper function and does not need to be called
* directly by the user. This function is called automatically at
* the end of TALISE_setSpiSettings()
*
* \dep_begin
* \dep{device->devHalInfo}
* \dep_end
*
* \param device Structure pointer to Talise device data structure
*
* \retval TALACT_WARN_RESET_LOG Recovery action for log reset
* \retval TALACT_ERR_RESET_SPI Recovery action for SPI reset required
* \retval TALACT_ERR_RESET_FULL Recovery action for full chip reset required
* \retval TALACT_NO_ACTION Function completed successfully, no action required
*/
uint32_t TALISE_verifySpiReadWrite (taliseDevice_t *device);
/**
* \brief Sets the CLKPLL output frequency
*
* This function updates the Synth and Loop filter settings based on a VCO
* frequency LUT. The VCO frequency break points for the Synth LUT can be
* found in an array called vcoFreqArrayMhz.
*
* \pre This function is private and is not called directly by the user.
*
* \dep_begin
* \dep{device->devHalInfo}
* \dep_end
*
* \param device Structure pointer to the TALISE data structure
* \param clockSettings pointer to clock setting structure holding information about CLKPLL configuration
*
* \retval TALACT_WARN_RESET_LOG Recovery action for log reset
* \retval TALACT_ERR_CHECK_PARAM Recovery action for bad parameter check
* \retval TALACT_ERR_RESET_SPI Recovery action for SPI reset required
* \retval TALACT_ERR_CHECK_TIMER Recovery action for bad wait timer check
* \retval TALACT_NO_ACTION Function completed successfully, no action required
*/
uint32_t TALISE_initDigitalClocks(taliseDevice_t *device, taliseDigClocks_t *clockSettings);
/****************************************************************************
* Debug functions
****************************************************************************
*/
/**
* \brief Sets the digital Tx PFIR SYNC clock divider.
*
* This function is a helper function. It is called automatically in
* TALISE_initialize() and should not need to be called by the BBIC.
*
* This function sets the digital clock divider that is used to synchronize the
* Tx PFIR each time the Tx channel power up. The Sync clock must
* be set to the FIRs (output clock / 2) or slower.
*
* \dep_begin
* \dep{device->devHalInfo}
* \dep_end
*
* \param device Structure pointer to the Talise data structure containing settings
* \param txProfile txProfile settings
*
* \retval TALACT_NO_ACTION Function completed successfully
* \retval TALACT_ERR_CHECK_PARAM Recovery action for bad parameter check
* \retval TALACT_ERR_RESET_SPI Recovery action for SPI reset required
*/
uint32_t TALISE_setTxPfirSyncClk(taliseDevice_t *device, taliseTxProfile_t *txProfile);
/**
* \brief Sets the digital Rx PFIR SYNC clock divider.
*
* This function is a helper function. It is called automatically in
* TALISE_initialize() and should not need to be called by the BBIC.
*
* This function sets the digital clock divider that is used to synchronize the
* Rx/ORx PFIRs each time the channels power up. The Sync clock must
* be set to the slowest of Rx/ORx PFIR (output clock / 2).
*
* \dep_begin
* \dep{device->devHalInfo}
* \dep_end
*
* \param device Structure pointer to the Talise data structure containing settings
* \param rxProfile rxProfile settings
* \param orxProfile orxProfile settings
*
* \retval TALACT_NO_ACTION Function completed successfully
* \retval TALACT_ERR_CHECK_PARAM Recovery action for bad parameter check
* \retval TALACT_ERR_RESET_SPI Recovery action for SPI reset required
*/
uint32_t TALISE_setRxPfirSyncClk(taliseDevice_t *device, taliseRxProfile_t *rxProfile, taliseORxProfile_t *orxProfile);
/**
* \brief Get API version number
*
* This function reads back the version number of the API
*
* \param device Pointer to the Talise data structure
* \param siVer A pointer to the current silicon version number.
* \param majorVer A pointer to the current major version number.
* \param minorVer A pointer to the current minor version number.
* \param buildVer A pointer to the current build version number.
*
* \retval TALACT_WARN_RESET_LOG recovery action for log reset
* \retval TALACT_ERR_CHECK_PARAM recovery action for bad parameter check
* \retval TALACT_NO_ACTION function completed successfully, no action required *
*/
uint32_t TALISE_getApiVersion (taliseDevice_t *device, uint32_t *siVer, uint32_t *majorVer, uint32_t *minorVer, uint32_t *buildVer);
/**
* \brief Reads back the silicon revision for the Talise Device
*
* revision's bit | Description
* ----------------|-----------------
* 3:0 | minor revision
* 7:4 | major revision
*
* \dep_begin
* \dep{device->devHalInfo}
* \dep_end
*
* \param device Structure pointer to the Talise data structure containing settings
* \param revision Return value of the Talise silicon revision in hex where
upper nibble (4 bits) indicates the major revision and the lower nibble
indicates the minor revision.
*
* \retval TALACT_WARN_RESET_LOG recovery action for log reset
* \retval TALACT_ERR_CHECK_PARAM recovery action for bad parameter check
* \retval TALACT_NO_ACTION function completed successfully, no action required *
*/
uint32_t TALISE_getDeviceRev(taliseDevice_t *device, uint8_t *revision);
/**
* \brief Reads back the Product ID for the Talise Device
*
* productId | Description
* ------------|---------------
* 1 | AD9379 (TDD device)
* 2 | AD9378-1 (Rx Only Device)
* 3 | AD9378-2 (Tx /ORx Device)
*
* \dep_begin
* \dep{device->devHalInfo}
* \dep_end
*
* \param device Structure pointer to the Talise data structure containing settings
* \param productId Return value of the Talise product Id
*
* \retval TALACT_WARN_RESET_LOG recovery action for log reset
* \retval TALACT_ERR_CHECK_PARAM recovery action for bad parameter check
* \retval TALACT_NO_ACTION function completed successfully, no action required *
*/
uint32_t TALISE_getProductId(taliseDevice_t *device, uint8_t *productId);
#ifdef __cplusplus
}
#endif
#endif /* TALISE_H_ */