path: root/Radio/HW/BladeRF/include/bladeRF2.h

/**
 * @file bladeRF2.h
 *
 * @brief bladeRF2-specific API
 *
 * Copyright (C) 2013-2017 Nuand LLC
 *
 * This library is free software; you can redistribute it and/or
 * modify it under the terms of the GNU Lesser General Public
 * License as published by the Free Software Foundation; either
 * version 2.1 of the License, or (at your option) any later version.
 *
 * This library is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
 * Lesser General Public License for more details.
 *
 * You should have received a copy of the GNU Lesser General Public
 * License along with this library; if not, write to the Free Software
 * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301 USA
 */
#ifndef BLADERF2_H_
#define BLADERF2_H_

/**
 * @defgroup BLADERF2 bladeRF2-specific API
 *
 * These functions are thread-safe.
 *
 * @{
 */

/**
 * @defgroup FN_BLADERF2_BIAS_TEE Bias Tee Control
 *
 * @{
 */

/**
 * Get current bias tee state
 *
 * @param       dev     Device handle
 * @param[in]   ch      Channel
 * @param[out]  enable  True if bias tee active, false otherwise
 *
 * @return 0 on success, value from \ref RETCODES list on failure
 */
API_EXPORT
int CALL_CONV bladerf_get_bias_tee(struct bladerf *dev,
                                   bladerf_channel ch,
                                   bool *enable);

/**
 * Get current bias tee state
 *
 * @param       dev     Device handle
 * @param[in]   ch      Channel
 * @param[in]   enable  True to activate bias tee, false to deactivate
 *
 * @return 0 on success, value from \ref RETCODES list on failure
 */
API_EXPORT
int CALL_CONV bladerf_set_bias_tee(struct bladerf *dev,
                                   bladerf_channel ch,
                                   bool enable);

/** @} (End of FN_BLADERF2_BIAS_TEE) */

/**
 * @defgroup FN_BLADERF2_LOW_LEVEL Low-level accessors
 *
 * In most cases, higher-level routines should be used. These routines are only
 * intended to support development and testing.
 *
 * Use these routines with great care, and be sure to reference the relevant
 * schematics, data sheets, and source code (i.e., firmware and hdl).
 *
 * Be careful when mixing these calls with higher-level routines that manipulate
 * the same registers/settings.
 *
 * These functions are thread-safe.
 *
 * @{
 */

/**
 * @defgroup FN_BLADERF2_LOW_LEVEL_RFIC RF Integrated Circuit
 *
 * @{
 */

/**
 * Read a RFIC register
 *
 * @param       dev         Device handle
 * @param[in]   address     Register address
 * @param[out]  val         Register value
 *
 * @return 0 on success, value from \ref RETCODES list on failure
 */
API_EXPORT
int CALL_CONV bladerf_get_rfic_register(struct bladerf *dev,
                                        uint16_t address,
                                        uint8_t *val);
/**
 * Write a RFIC register
 *
 * @param       dev         Device handle
 * @param[in]   address     Register address
 * @param[in]   val         Value to write to register
 *
 * @return 0 on success, value from \ref RETCODES list on failure
 */
API_EXPORT
int CALL_CONV bladerf_set_rfic_register(struct bladerf *dev,
                                        uint16_t address,
                                        uint8_t val);

/**
 * Read the temperature from the RFIC
 *
 * @param       dev         Device handle
 * @param[out]  val         Temperature in degrees C
 *
 * @return 0 on success, value from \ref RETCODES list on failure
 */
API_EXPORT
int CALL_CONV bladerf_get_rfic_temperature(struct bladerf *dev, float *val);

/**
 * Read the RSSI for the selected channel from the RFIC
 *
 * @note  This is a relative value, not an absolute value. If an absolute
 *        value (e.g. in dBm) is desired, a calibration should be performed
 *        against a reference signal.
 *
 * @note  See `fpga_common/src/ad936x_params.c` for the RSSI control parameters.
 *
 * Reference: AD9361 Reference Manual UG-570
 *
 * @param       dev         Device handle
 * @param       ch          Channel to query
 * @param[out]  pre_rssi    Preamble RSSI in dB (first calculated RSSI result)
 * @param[out]  sym_rssi    Symbol RSSI in dB (most recent RSSI result)
 *
 * @return 0 on success, value from \ref RETCODES list on failure
 */
API_EXPORT
int CALL_CONV bladerf_get_rfic_rssi(struct bladerf *dev,
                                    bladerf_channel ch,
                                    int32_t *pre_rssi,
                                    int32_t *sym_rssi);

/**
 * Read the CTRL_OUT pins from the RFIC
 *
 * @note  See AD9361 Reference Manual UG-570's "Control Output" chapter for
 *        complete information about this feature.
 *
 * @see   bladerf_set_rfic_register()
 *
 * @param      dev       Device handle
 * @param[out] ctrl_out  Pointer for storing the retrieved value
 *
 * @return 0 on success, value from \ref RETCODES list on failure
 */
API_EXPORT
int CALL_CONV bladerf_get_rfic_ctrl_out(struct bladerf *dev, uint8_t *ctrl_out);

/**
 * RFIC RX FIR filter choices
 */
typedef enum {
    BLADERF_RFIC_RXFIR_BYPASS = 0, /**< No filter */
    BLADERF_RFIC_RXFIR_CUSTOM,     /**< Custom FIR filter (currently unused) */
    BLADERF_RFIC_RXFIR_DEC1,       /**< Decimate by 1 (default) */
    BLADERF_RFIC_RXFIR_DEC2,       /**< Decimate by 2 */
    BLADERF_RFIC_RXFIR_DEC4,       /**< Decimate by 4 */
} bladerf_rfic_rxfir;

/** Default RFIC RX FIR filter */
#define BLADERF_RFIC_RXFIR_DEFAULT BLADERF_RFIC_RXFIR_DEC1

/**
 * RFIC TX FIR filter choices
 */
typedef enum {
    BLADERF_RFIC_TXFIR_BYPASS = 0, /**< No filter (default) */
    BLADERF_RFIC_TXFIR_CUSTOM,     /**< Custom FIR filter (currently unused) */
    BLADERF_RFIC_TXFIR_INT1,       /**< Interpolate by 1 */
    BLADERF_RFIC_TXFIR_INT2,       /**< Interpolate by 2 */
    BLADERF_RFIC_TXFIR_INT4,       /**< Interpolate by 4 */
} bladerf_rfic_txfir;

/** Default RFIC TX FIR filter */
#define BLADERF_RFIC_TXFIR_DEFAULT BLADERF_RFIC_TXFIR_BYPASS

/**
 * Get the current status of the RX FIR filter on the RFIC.
 *
 * @param   dev     Device handle
 * @param   rxfir   RX FIR selection
 *
 * @note  See `fpga_common/src/ad936x_params.c` for FIR parameters.
 *
 * @return 0 on success, value from \ref RETCODES list on failure
 */
API_EXPORT
int CALL_CONV bladerf_get_rfic_rx_fir(struct bladerf *dev,
                                      bladerf_rfic_rxfir *rxfir);

/**
 * Set the RX FIR filter on the RFIC.
 *
 * @param   dev     Device handle
 * @param   rxfir   RX FIR selection
 *
 * @note  See `fpga_common/src/ad936x_params.c` for FIR parameters.
 *
 * @return 0 on success, value from \ref RETCODES list on failure
 */
API_EXPORT
int CALL_CONV bladerf_set_rfic_rx_fir(struct bladerf *dev,
                                      bladerf_rfic_rxfir rxfir);

/**
 * Get the current status of the TX FIR filter on the RFIC.
 *
 * @param   dev     Device handle
 * @param   txfir   TX FIR selection
 *
 * @note  See `fpga_common/src/ad936x_params.c` for FIR parameters.
 *
 * @return 0 on success, value from \ref RETCODES list on failure
 */
API_EXPORT
int CALL_CONV bladerf_get_rfic_tx_fir(struct bladerf *dev,
                                      bladerf_rfic_txfir *txfir);

/**
 * Set the TX FIR filter on the RFIC.
 *
 * @param   dev     Device handle
 * @param   txfir   TX FIR selection
 *
 * @note  See `fpga_common/src/ad936x_params.c` for FIR parameters.
 *
 * @return 0 on success, value from \ref RETCODES list on failure
 */
API_EXPORT
int CALL_CONV bladerf_set_rfic_tx_fir(struct bladerf *dev,
                                      bladerf_rfic_txfir txfir);

/** @} (End of FN_BLADERF2_LOW_LEVEL_RFIC) */

/**
 * @defgroup FN_BLADERF2_LOW_LEVEL_PLL Phase Detector/Freq. Synth Control
 *
 * Reference:
 * http://www.analog.com/media/en/technical-documentation/data-sheets/ADF4002.pdf
 *
 * @{
 */

/**
 * Fetch the lock state of the Phase Detector/Frequency Synthesizer
 *
 * @param       dev         Device handle
 * @param[out]  locked      True if locked, False otherwise
 *
 * @return 0 on success, value from \ref RETCODES list on failure
 */
API_EXPORT
int CALL_CONV bladerf_get_pll_lock_state(struct bladerf *dev, bool *locked);

/**
 * Fetch the state of the Phase Detector/Frequency Synthesizer
 *
 * @param       dev         Device handle
 * @param[out]  enabled     True if enabled, False otherwise
 *
 * @return 0 on success, value from \ref RETCODES list on failure
 */
API_EXPORT
int CALL_CONV bladerf_get_pll_enable(struct bladerf *dev, bool *enabled);

/**
 * Enable the Phase Detector/Frequency Synthesizer
 *
 * Enabling this disables the VCTCXO trimmer DAC, and vice versa.
 *
 * @param       dev         Device handle
 * @param[in]   enable      True to enable, False otherwise
 *
 * @return 0 on success, value from \ref RETCODES list on failure
 */
API_EXPORT
int CALL_CONV bladerf_set_pll_enable(struct bladerf *dev, bool enable);

/**
 * Get the valid range of frequencies for the reference clock input
 *
 * @param       dev         Device handle
 * @param[out]  range       Reference clock frequency range
 *
 * @return 0 on success, value from \ref RETCODES list on failure
 */
API_EXPORT
int CALL_CONV bladerf_get_pll_refclk_range(struct bladerf *dev,
                                           const struct bladerf_range **range);

/**
 * Get the currently-configured frequency for the reference clock
 * input.
 *
 * @param       dev         Device handle
 * @param[out]  frequency   Reference clock frequency
 *
 * @return 0 on success, value from \ref RETCODES list on failure
 */
API_EXPORT
int CALL_CONV bladerf_get_pll_refclk(struct bladerf *dev, uint64_t *frequency);

/**
 * Set the expected frequency for the reference clock input.
 *
 * @param       dev         Device handle
 * @param[in]   frequency   Reference clock frequency
 *
 * @return 0 on success, value from \ref RETCODES list on failure
 */
API_EXPORT
int CALL_CONV bladerf_set_pll_refclk(struct bladerf *dev, uint64_t frequency);

/**
 * Read value from Phase Detector/Frequency Synthesizer
 *
 * The `address` is interpreted as the control bits (DB1 and DB0) used to write
 * to a specific latch.
 *
 * @param       dev         Device handle
 * @param[in]   address     Latch address
 * @param[out]  val         Value to read from
 *
 * @return 0 on success, value from \ref RETCODES list on failure
 */
API_EXPORT
int CALL_CONV bladerf_get_pll_register(struct bladerf *dev,
                                       uint8_t address,
                                       uint32_t *val);

/**
 * Write value to Phase Detector/Frequency Synthesizer
 *
 * The `address` is interpreted as the control bits (DB1 and DB0) used to write
 * to a specific latch.  These bits are masked out in `val`
 *
 * @param       dev         Device handle
 * @param[in]   address     Latch address
 * @param[in]   val         Value to write to
 *
 * @return 0 on success, value from \ref RETCODES list on failure
 */
API_EXPORT
int CALL_CONV bladerf_set_pll_register(struct bladerf *dev,
                                       uint8_t address,
                                       uint32_t val);

/** @} (End of FN_BLADERF2_LOW_LEVEL_PLL) */

/**
 * @defgroup FN_BLADERF2_LOW_LEVEL_POWER_SOURCE Power Multiplexer
 *
 * @{
 */

/**
 * Power sources
 */
typedef enum {
    BLADERF_UNKNOWN,    /**< Unknown; manual observation may be required */
    BLADERF_PS_DC,      /**< DC Barrel Plug */
    BLADERF_PS_USB_VBUS /**< USB Bus */
} bladerf_power_sources;

/**
 * Get the active power source reported by the power multiplexer
 *
 * Reference: http://www.ti.com/product/TPS2115A
 *
 * @param       dev     Device handle
 * @param[out]  val     Value read from power multiplexer
 *
 * @return 0 on success, value from \ref RETCODES list on failure
 */
API_EXPORT
int CALL_CONV bladerf_get_power_source(struct bladerf *dev,
                                       bladerf_power_sources *val);

/** @} (End of FN_BLADERF2_LOW_LEVEL_POWER_SOURCE) */

/**
 * @defgroup FN_BLADERF2_LOW_LEVEL_CLOCK_BUFFER Clock Buffer
 *
 * @{
 */

/**
 * @defgroup FN_BLADERF2_LOW_LEVEL_CLOCK_BUFFER_SELECT Clock input selection
 *
 * @{
 */

/**
 * Available clock sources
 */
typedef enum {
    CLOCK_SELECT_ONBOARD, /**< Use onboard VCTCXO */
    CLOCK_SELECT_EXTERNAL /**< Use external clock input */
} bladerf_clock_select;

/**
 * Get the selected clock source
 *
 * Reference: https://www.silabs.com/documents/public/data-sheets/Si53304.pdf
 *
 * @param       dev     Device handle
 * @param[out]  sel     Clock input source currently in use
 *
 * @return 0 on success, value from \ref RETCODES list on failure
 */
API_EXPORT
int CALL_CONV bladerf_get_clock_select(struct bladerf *dev,
                                       bladerf_clock_select *sel);

/**
 * Set the clock source
 *
 * Reference: https://www.silabs.com/documents/public/data-sheets/Si53304.pdf
 *
 * @param       dev     Device handle
 * @param[in]   sel     Clock input source to use
 *
 * @return 0 on success, value from \ref RETCODES list on failure
 */
API_EXPORT
int CALL_CONV bladerf_set_clock_select(struct bladerf *dev,
                                       bladerf_clock_select sel);

/** @} (End of FN_BLADERF2_LOW_LEVEL_CLOCK_BUFFER_SELECT) */

/**
 * @defgroup FN_BLADERF2_LOW_LEVEL_CLOCK_BUFFER_OUTPUT Clock output control
 *
 * @{
 */

/**
 * Get the current state of the clock output
 *
 * @param       dev     Device handle
 * @param[out]  state   Clock output state
 *
 * @return 0 on success, value from \ref RETCODES list on failure
 */
API_EXPORT
int CALL_CONV bladerf_get_clock_output(struct bladerf *dev, bool *state);

/**
 * Set the clock output (enable/disable)
 *
 * @param       dev     Device handle
 * @param[in]   enable  Clock output enable
 *
 * @return 0 on success, value from \ref RETCODES list on failure
 */
API_EXPORT
int CALL_CONV bladerf_set_clock_output(struct bladerf *dev, bool enable);

/** @} (End of FN_BLADERF2_LOW_LEVEL_CLOCK_BUFFER_OUTPUT) */

/** @} (End of FN_BLADERF2_LOW_LEVEL_CLOCK_BUFFER) */

/**
 * @defgroup FN_BLADERF2_LOW_LEVEL_PMIC Power Monitoring
 *
 * @{
 */

/**
 * Register identifiers for PMIC
 */
typedef enum {
    BLADERF_PMIC_CONFIGURATION, /**< Configuration register (uint16_t) */
    BLADERF_PMIC_VOLTAGE_SHUNT, /**< Shunt voltage (float) */
    BLADERF_PMIC_VOLTAGE_BUS,   /**< Bus voltage (float) */
    BLADERF_PMIC_POWER,         /**< Load power (float) */
    BLADERF_PMIC_CURRENT,       /**< Load current (float) */
    BLADERF_PMIC_CALIBRATION,   /**< Calibration (uint16_t) */
} bladerf_pmic_register;

/**
 * Read value from Power Monitor IC
 *
 * Reference: http://www.ti.com/product/INA219
 *
 * @param       dev     Device handle
 * @param[in]   reg     Register to read from
 * @param[out]  val     Value read from PMIC
 *
 * @return 0 on success, value from \ref RETCODES list on failure
 */
API_EXPORT
int CALL_CONV bladerf_get_pmic_register(struct bladerf *dev,
                                        bladerf_pmic_register reg,
                                        void *val);

/** @} (End of FN_BLADERF2_LOW_LEVEL_PMIC) */

/**
 * @defgroup FN_BLADERF2_LOW_LEVEL_RF_SWITCHING RF Switching Control
 *
 * @{
 */

/**
 * RF switch configuration structure
 */
typedef struct {
    uint32_t tx1_rfic_port; /**< Active TX1 output from RFIC */
    uint32_t tx1_spdt_port; /**< RF switch configuration for the TX1 path */
    uint32_t tx2_rfic_port; /**< Active TX2 output from RFIC */
    uint32_t tx2_spdt_port; /**< RF switch configuration for the TX2 path */
    uint32_t rx1_rfic_port; /**< Active RX1 input to RFIC */
    uint32_t rx1_spdt_port; /**< RF switch configuration for the RX1 path */
    uint32_t rx2_rfic_port; /**< Active RX2 input to RFIC */
    uint32_t rx2_spdt_port; /**< RF switch configuration for the RX2 path */
} bladerf_rf_switch_config;

/**
 * Read the current RF switching configuration from the bladeRF hardware.
 *
 * Queries both the RFIC and the RF switch and passes back a
 * bladerf_rf_switch_config stucture.
 *
 * @param       dev     Device handle
 * @param[out]  config  Switch configuration struct
 *
 * @return 0 on success, value from \ref RETCODES list on failure
 */
API_EXPORT
int CALL_CONV bladerf_get_rf_switch_config(struct bladerf *dev,
                                           bladerf_rf_switch_config *config);

/** @} (End of FN_BLADERF2_LOW_LEVEL_RF_SWITCHING) */

/** @} (End of FN_BLADERF2_LOW_LEVEL) */

/** @} (End of BLADERF2) */

#endif /* BLADERF2_H_ */