diff options
Diffstat (limited to 'Radio/HW/BladeRF/include/bladeRF2.h')
-rw-r--r-- | Radio/HW/BladeRF/include/bladeRF2.h | 561 |
1 files changed, 561 insertions, 0 deletions
diff --git a/Radio/HW/BladeRF/include/bladeRF2.h b/Radio/HW/BladeRF/include/bladeRF2.h new file mode 100644 index 0000000..9de1f9e --- /dev/null +++ b/Radio/HW/BladeRF/include/bladeRF2.h @@ -0,0 +1,561 @@ +/** + * @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_ */ |