usrp.h

Go to the documentation of this file.

//
// Copyright 2015-2016 Ettus Research LLC
// Copyright 2018 Ettus Research, a National Instruments Company
//
// SPDX-License-Identifier: GPL-3.0-or-later
//

#pragma once

#include <uhd/config.h>
#include <uhd/error.h>
#include <uhd/types/metadata.h>
#include <uhd/types/ranges.h>
#include <uhd/types/sensors.h>
#include <uhd/types/string_vector.h>
#include <uhd/types/tune_request.h>
#include <uhd/types/tune_result.h>
#include <uhd/types/usrp_info.h>
#include <uhd/usrp/dboard_eeprom.h>
#include <uhd/usrp/mboard_eeprom.h>
#include <uhd/usrp/subdev_spec.h>
/* version.hpp is safe to include in C: */
#include <uhd/version.hpp> /* Provides UHD_VERSION */

#include <stdbool.h>
#include <stdint.h>
#include <stdlib.h>
#include <time.h>

typedef struct
{
    size_t bitwidth;
    bool readable;
    bool writable;
} uhd_usrp_register_info_t;

/*
 * Streamers
 */


typedef struct
{
    char* cpu_format;
    char* otw_format;
    char* args;
    size_t* channel_list;
    int n_channels;
} uhd_stream_args_t;


typedef enum {
    UHD_STREAM_MODE_START_CONTINUOUS = 97,
    UHD_STREAM_MODE_STOP_CONTINUOUS = 111,
    UHD_STREAM_MODE_NUM_SAMPS_AND_DONE = 100,
    UHD_STREAM_MODE_NUM_SAMPS_AND_MORE = 109
} uhd_stream_mode_t;


typedef struct
{
    uhd_stream_mode_t stream_mode;
    size_t num_samps;
    bool stream_now;
    int64_t time_spec_full_secs;
    double time_spec_frac_secs;
} uhd_stream_cmd_t;

struct uhd_rx_streamer;
struct uhd_tx_streamer;


typedef struct uhd_rx_streamer* uhd_rx_streamer_handle;


typedef struct uhd_tx_streamer* uhd_tx_streamer_handle;

#ifdef __cplusplus
extern "C" {
#endif

/*
 * RX Streamer
 */


UHD_API uhd_error uhd_rx_streamer_make(uhd_rx_streamer_handle* h);


UHD_API uhd_error uhd_rx_streamer_free(uhd_rx_streamer_handle* h);

UHD_API uhd_error uhd_rx_streamer_num_channels(
    uhd_rx_streamer_handle h, size_t* num_channels_out);

UHD_API uhd_error uhd_rx_streamer_max_num_samps(
    uhd_rx_streamer_handle h, size_t* max_num_samps_out);


UHD_API uhd_error uhd_rx_streamer_recv(uhd_rx_streamer_handle h,
    void** buffs,
    size_t samps_per_buff,
    uhd_rx_metadata_handle* md,
    double timeout,
    bool one_packet,
    size_t* items_recvd);


UHD_API uhd_error uhd_rx_streamer_issue_stream_cmd(
    uhd_rx_streamer_handle h, const uhd_stream_cmd_t* stream_cmd);


UHD_API uhd_error uhd_rx_streamer_last_error(
    uhd_rx_streamer_handle h, char* error_out, size_t strbuffer_len);

/*
 * TX Streamer
 */


UHD_API uhd_error uhd_tx_streamer_make(uhd_tx_streamer_handle* h);


UHD_API uhd_error uhd_tx_streamer_free(uhd_tx_streamer_handle* h);

UHD_API uhd_error uhd_tx_streamer_num_channels(
    uhd_tx_streamer_handle h, size_t* num_channels_out);

UHD_API uhd_error uhd_tx_streamer_max_num_samps(
    uhd_tx_streamer_handle h, size_t* max_num_samps_out);


UHD_API uhd_error uhd_tx_streamer_send(uhd_tx_streamer_handle h,
    const void** buffs,
    size_t samps_per_buff,
    uhd_tx_metadata_handle* md,
    double timeout,
    size_t* items_sent);


UHD_API uhd_error uhd_tx_streamer_recv_async_msg(
    uhd_tx_streamer_handle h, uhd_async_metadata_handle* md, double timeout, bool* valid);


UHD_API uhd_error uhd_tx_streamer_last_error(
    uhd_tx_streamer_handle h, char* error_out, size_t strbuffer_len);

#ifdef __cplusplus
}
#endif

/****************************************************************************
 * Public Datatypes for USRP / streamer handling.
 ***************************************************************************/
struct uhd_usrp;

/*
 * See uhd::usrp::multi_usrp for more details.
 *
 * NOTE: You must pass this handle into uhd_usrp_make before using it.
 */
typedef struct uhd_usrp* uhd_usrp_handle;

/****************************************************************************
 * USRP Make / Free API calls
 ***************************************************************************/
#ifdef __cplusplus
extern "C" {
#endif


UHD_API uhd_error uhd_usrp_find(const char* args, uhd_string_vector_handle* strings_out);


UHD_API uhd_error uhd_usrp_make(uhd_usrp_handle* h, const char* args);


UHD_API uhd_error uhd_usrp_free(uhd_usrp_handle* h);

UHD_API uhd_error uhd_usrp_last_error(
    uhd_usrp_handle h, char* error_out, size_t strbuffer_len);

UHD_API uhd_error uhd_usrp_get_rx_stream(
    uhd_usrp_handle h, uhd_stream_args_t* stream_args, uhd_rx_streamer_handle h_out);

UHD_API uhd_error uhd_usrp_get_tx_stream(
    uhd_usrp_handle h, uhd_stream_args_t* stream_args, uhd_tx_streamer_handle h_out);

/****************************************************************************
 * multi_usrp API calls
 ***************************************************************************/


UHD_API uhd_error uhd_usrp_get_rx_info(
    uhd_usrp_handle h, size_t chan, uhd_usrp_rx_info_t* info_out);


UHD_API uhd_error uhd_usrp_get_tx_info(
    uhd_usrp_handle h, size_t chan, uhd_usrp_tx_info_t* info_out);

/****************************************************************************
 * Motherboard methods
 ***************************************************************************/


UHD_API uhd_error uhd_usrp_set_master_clock_rate(
    uhd_usrp_handle h, double rate, size_t mboard);


UHD_API uhd_error uhd_usrp_get_master_clock_rate(
    uhd_usrp_handle h, size_t mboard, double* clock_rate_out);


UHD_API uhd_error uhd_usrp_get_pp_string(
    uhd_usrp_handle h, char* pp_string_out, size_t strbuffer_len);


UHD_API uhd_error uhd_usrp_get_mboard_name(
    uhd_usrp_handle h, size_t mboard, char* mboard_name_out, size_t strbuffer_len);


UHD_API uhd_error uhd_usrp_get_time_now(
    uhd_usrp_handle h, size_t mboard, int64_t* full_secs_out, double* frac_secs_out);


UHD_API uhd_error uhd_usrp_get_time_last_pps(
    uhd_usrp_handle h, size_t mboard, int64_t* full_secs_out, double* frac_secs_out);


UHD_API uhd_error uhd_usrp_set_time_now(
    uhd_usrp_handle h, int64_t full_secs, double frac_secs, size_t mboard);


UHD_API uhd_error uhd_usrp_set_time_next_pps(
    uhd_usrp_handle h, int64_t full_secs, double frac_secs, size_t mboard);


UHD_API uhd_error uhd_usrp_set_time_unknown_pps(
    uhd_usrp_handle h, int64_t full_secs, double frac_secs);

UHD_API uhd_error uhd_usrp_get_time_synchronized(uhd_usrp_handle h, bool* result_out);


UHD_API uhd_error uhd_usrp_set_command_time(
    uhd_usrp_handle h, int64_t full_secs, double frac_secs, size_t mboard);

UHD_API uhd_error uhd_usrp_clear_command_time(uhd_usrp_handle h, size_t mboard);


UHD_API uhd_error uhd_usrp_set_time_source(
    uhd_usrp_handle h, const char* time_source, size_t mboard);


UHD_API uhd_error uhd_usrp_get_time_source(
    uhd_usrp_handle h, size_t mboard, char* time_source_out, size_t strbuffer_len);

UHD_API uhd_error uhd_usrp_get_time_sources(
    uhd_usrp_handle h, size_t mboard, uhd_string_vector_handle* time_sources_out);


UHD_API uhd_error uhd_usrp_set_clock_source(
    uhd_usrp_handle h, const char* clock_source, size_t mboard);


UHD_API uhd_error uhd_usrp_get_clock_source(
    uhd_usrp_handle h, size_t mboard, char* clock_source_out, size_t strbuffer_len);

UHD_API uhd_error uhd_usrp_get_clock_sources(
    uhd_usrp_handle h, size_t mboard, uhd_string_vector_handle* clock_sources_out);


UHD_API uhd_error uhd_usrp_set_clock_source_out(
    uhd_usrp_handle h, bool enb, size_t mboard);


UHD_API uhd_error uhd_usrp_set_time_source_out(
    uhd_usrp_handle h, bool enb, size_t mboard);

UHD_API uhd_error uhd_usrp_get_num_mboards(uhd_usrp_handle h, size_t* num_mboards_out);

UHD_API uhd_error uhd_usrp_get_mboard_sensor(uhd_usrp_handle h,
    const char* name,
    size_t mboard,
    uhd_sensor_value_handle* sensor_value_out);

UHD_API uhd_error uhd_usrp_get_mboard_sensor_names(
    uhd_usrp_handle h, size_t mboard, uhd_string_vector_handle* mboard_sensor_names_out);


UHD_API uhd_error uhd_usrp_set_user_register(
    uhd_usrp_handle h, uint8_t addr, uint32_t data, size_t mboard);

/****************************************************************************
 * EEPROM access methods
 ***************************************************************************/

UHD_API uhd_error uhd_usrp_get_mboard_eeprom(
    uhd_usrp_handle h, uhd_mboard_eeprom_handle mb_eeprom, size_t mboard);

UHD_API uhd_error uhd_usrp_set_mboard_eeprom(
    uhd_usrp_handle h, uhd_mboard_eeprom_handle mb_eeprom, size_t mboard);

UHD_API uhd_error uhd_usrp_get_dboard_eeprom(uhd_usrp_handle h,
    uhd_dboard_eeprom_handle db_eeprom,
    const char* unit,
    const char* slot,
    size_t mboard);

UHD_API uhd_error uhd_usrp_set_dboard_eeprom(uhd_usrp_handle h,
    uhd_dboard_eeprom_handle db_eeprom,
    const char* unit,
    const char* slot,
    size_t mboard);

/****************************************************************************
 * RX methods
 ***************************************************************************/


UHD_API uhd_error uhd_usrp_set_rx_subdev_spec(
    uhd_usrp_handle h, uhd_subdev_spec_handle subdev_spec, size_t mboard);

UHD_API uhd_error uhd_usrp_get_rx_subdev_spec(
    uhd_usrp_handle h, size_t mboard, uhd_subdev_spec_handle subdev_spec_out);

UHD_API uhd_error uhd_usrp_get_rx_num_channels(
    uhd_usrp_handle h, size_t* num_channels_out);

UHD_API uhd_error uhd_usrp_get_rx_subdev_name(
    uhd_usrp_handle h, size_t chan, char* rx_subdev_name_out, size_t strbuffer_len);

UHD_API uhd_error uhd_usrp_set_rx_rate(uhd_usrp_handle h, double rate, size_t chan);

UHD_API uhd_error uhd_usrp_get_rx_rate(uhd_usrp_handle h, size_t chan, double* rate_out);

UHD_API uhd_error uhd_usrp_get_rx_rates(
    uhd_usrp_handle h, size_t chan, uhd_meta_range_handle rates_out);

UHD_API uhd_error uhd_usrp_set_rx_freq(uhd_usrp_handle h,
    uhd_tune_request_t* tune_request,
    size_t chan,
    uhd_tune_result_t* tune_result);

UHD_API uhd_error uhd_usrp_get_rx_freq(uhd_usrp_handle h, size_t chan, double* freq_out);


UHD_API uhd_error uhd_usrp_get_rx_freq_range(
    uhd_usrp_handle h, size_t chan, uhd_meta_range_handle freq_range_out);

UHD_API uhd_error uhd_usrp_get_fe_rx_freq_range(
    uhd_usrp_handle h, size_t chan, uhd_meta_range_handle freq_range_out);

UHD_UNUSED(static const char* UHD_USRP_ALL_LOS) = "all";

/*
 * See uhd::usrp::multi_usrp::get_rx_lo_names() for more details.
 */
UHD_API uhd_error uhd_usrp_get_rx_lo_names(
    uhd_usrp_handle h, size_t chan, uhd_string_vector_handle* rx_lo_names_out);

/*
 * See uhd::usrp::multi_usrp::set_rx_lo_source() for more details.
 */
UHD_API uhd_error uhd_usrp_set_rx_lo_source(
    uhd_usrp_handle h, const char* src, const char* name, size_t chan);

UHD_API uhd_error uhd_usrp_get_rx_lo_source(uhd_usrp_handle h,
    const char* name,
    size_t chan,
    char* rx_lo_source_out,
    size_t strbuffer_len);

UHD_API uhd_error uhd_usrp_get_rx_lo_sources(uhd_usrp_handle h,
    const char* name,
    size_t chan,
    uhd_string_vector_handle* rx_lo_sources_out);

/*
 * See uhd::usrp::multi_usrp::set_rx_lo_enabled() for more details.
 */
UHD_API uhd_error uhd_usrp_set_rx_lo_export_enabled(
    uhd_usrp_handle h, bool enabled, const char* name, size_t chan);

UHD_API uhd_error uhd_usrp_get_rx_lo_export_enabled(
    uhd_usrp_handle h, const char* name, size_t chan, bool* result_out);

UHD_API uhd_error uhd_usrp_set_rx_lo_freq(uhd_usrp_handle h,
    double freq,
    const char* name,
    size_t chan,
    double* coerced_freq_out);

UHD_API uhd_error uhd_usrp_get_rx_lo_freq(
    uhd_usrp_handle h, const char* name, size_t chan, double* rx_lo_freq_out);

UHD_API uhd_error uhd_usrp_set_rx_gain(
    uhd_usrp_handle h, double gain, size_t chan, const char* gain_name);


UHD_API uhd_error uhd_usrp_set_normalized_rx_gain(
    uhd_usrp_handle h, double gain, size_t chan);


UHD_API uhd_error uhd_usrp_set_rx_agc(uhd_usrp_handle h, bool enable, size_t chan);

UHD_API uhd_error uhd_usrp_get_rx_gain(
    uhd_usrp_handle h, size_t chan, const char* gain_name, double* gain_out);


UHD_API uhd_error uhd_usrp_get_normalized_rx_gain(
    uhd_usrp_handle h, size_t chan, double* gain_out);

UHD_API uhd_error uhd_usrp_get_rx_gain_range(uhd_usrp_handle h,
    const char* name,
    size_t chan,
    uhd_meta_range_handle gain_range_out);

UHD_API uhd_error uhd_usrp_get_rx_gain_names(
    uhd_usrp_handle h, size_t chan, uhd_string_vector_handle* gain_names_out);

UHD_API uhd_error uhd_usrp_set_rx_antenna(
    uhd_usrp_handle h, const char* ant, size_t chan);

UHD_API uhd_error uhd_usrp_get_rx_antenna(
    uhd_usrp_handle h, size_t chan, char* ant_out, size_t strbuffer_len);

UHD_API uhd_error uhd_usrp_get_rx_antennas(
    uhd_usrp_handle h, size_t chan, uhd_string_vector_handle* antennas_out);

UHD_API uhd_error uhd_usrp_get_rx_sensor_names(
    uhd_usrp_handle h, size_t chan, uhd_string_vector_handle* sensor_names_out);

UHD_API uhd_error uhd_usrp_set_rx_bandwidth(
    uhd_usrp_handle h, double bandwidth, size_t chan);

UHD_API uhd_error uhd_usrp_get_rx_bandwidth(
    uhd_usrp_handle h, size_t chan, double* bandwidth_out);

UHD_API uhd_error uhd_usrp_get_rx_bandwidth_range(
    uhd_usrp_handle h, size_t chan, uhd_meta_range_handle bandwidth_range_out);

UHD_API uhd_error uhd_usrp_get_rx_sensor(uhd_usrp_handle h,
    const char* name,
    size_t chan,
    uhd_sensor_value_handle* sensor_value_out);


UHD_API uhd_error uhd_usrp_set_rx_dc_offset_enabled(
    uhd_usrp_handle h, bool enb, size_t chan);

UHD_API uhd_error uhd_usrp_set_rx_iq_balance_enabled(
    uhd_usrp_handle h, bool enb, size_t chan);

/****************************************************************************
 * TX methods
 ***************************************************************************/


UHD_API uhd_error uhd_usrp_set_tx_subdev_spec(
    uhd_usrp_handle h, uhd_subdev_spec_handle subdev_spec, size_t mboard);

UHD_API uhd_error uhd_usrp_get_tx_subdev_spec(
    uhd_usrp_handle h, size_t mboard, uhd_subdev_spec_handle subdev_spec_out);

UHD_API uhd_error uhd_usrp_get_tx_num_channels(
    uhd_usrp_handle h, size_t* num_channels_out);

UHD_API uhd_error uhd_usrp_get_tx_subdev_name(
    uhd_usrp_handle h, size_t chan, char* tx_subdev_name_out, size_t strbuffer_len);

UHD_API uhd_error uhd_usrp_set_tx_rate(uhd_usrp_handle h, double rate, size_t chan);

UHD_API uhd_error uhd_usrp_get_tx_rate(uhd_usrp_handle h, size_t chan, double* rate_out);

UHD_API uhd_error uhd_usrp_get_tx_rates(
    uhd_usrp_handle h, size_t chan, uhd_meta_range_handle rates_out);

UHD_API uhd_error uhd_usrp_set_tx_freq(uhd_usrp_handle h,
    uhd_tune_request_t* tune_request,
    size_t chan,
    uhd_tune_result_t* tune_result);

UHD_API uhd_error uhd_usrp_get_tx_freq(uhd_usrp_handle h, size_t chan, double* freq_out);


UHD_API uhd_error uhd_usrp_get_tx_freq_range(
    uhd_usrp_handle h, size_t chan, uhd_meta_range_handle freq_range_out);

UHD_API uhd_error uhd_usrp_get_fe_tx_freq_range(
    uhd_usrp_handle h, size_t chan, uhd_meta_range_handle freq_range_out);

/*
 * See uhd::usrp::multi_usrp::get_tx_lo_names() for more details.
 */
UHD_API uhd_error uhd_usrp_get_tx_lo_names(
    uhd_usrp_handle h, size_t chan, uhd_string_vector_handle* tx_lo_names_out);

/*
 * See uhd::usrp::multi_usrp::set_tx_lo_source() for more details.
 */
UHD_API uhd_error uhd_usrp_set_tx_lo_source(
    uhd_usrp_handle h, const char* src, const char* name, size_t chan);

UHD_API uhd_error uhd_usrp_get_tx_lo_source(uhd_usrp_handle h,
    const char* name,
    size_t chan,
    char* tx_lo_source_out,
    size_t strbuffer_len);

UHD_API uhd_error uhd_usrp_get_tx_lo_sources(uhd_usrp_handle h,
    const char* name,
    size_t chan,
    uhd_string_vector_handle* tx_lo_sources_out);

/*
 * See uhd::usrp::multi_usrp::set_tx_lo_enabled() for more details.
 */
UHD_API uhd_error uhd_usrp_set_tx_lo_export_enabled(
    uhd_usrp_handle h, bool enabled, const char* name, size_t chan);

UHD_API uhd_error uhd_usrp_get_tx_lo_export_enabled(
    uhd_usrp_handle h, const char* name, size_t chan, bool* result_out);

UHD_API uhd_error uhd_usrp_set_tx_lo_freq(uhd_usrp_handle h,
    double freq,
    const char* name,
    size_t chan,
    double* coerced_freq_out);

UHD_API uhd_error uhd_usrp_get_tx_lo_freq(
    uhd_usrp_handle h, const char* name, size_t chan, double* tx_lo_freq_out);

UHD_API uhd_error uhd_usrp_set_tx_gain(
    uhd_usrp_handle h, double gain, size_t chan, const char* gain_name);


UHD_API uhd_error uhd_usrp_set_normalized_tx_gain(
    uhd_usrp_handle h, double gain, size_t chan);

UHD_API uhd_error uhd_usrp_get_tx_gain_range(uhd_usrp_handle h,
    const char* name,
    size_t chan,
    uhd_meta_range_handle gain_range_out);

UHD_API uhd_error uhd_usrp_get_tx_gain(
    uhd_usrp_handle h, size_t chan, const char* gain_name, double* gain_out);


UHD_API uhd_error uhd_usrp_get_normalized_tx_gain(
    uhd_usrp_handle h, size_t chan, double* gain_out);

UHD_API uhd_error uhd_usrp_get_tx_gain_names(
    uhd_usrp_handle h, size_t chan, uhd_string_vector_handle* gain_names_out);

UHD_API uhd_error uhd_usrp_set_tx_antenna(
    uhd_usrp_handle h, const char* ant, size_t chan);

UHD_API uhd_error uhd_usrp_get_tx_antenna(
    uhd_usrp_handle h, size_t chan, char* ant_out, size_t strbuffer_len);

UHD_API uhd_error uhd_usrp_get_tx_antennas(
    uhd_usrp_handle h, size_t chan, uhd_string_vector_handle* antennas_out);

UHD_API uhd_error uhd_usrp_set_tx_bandwidth(
    uhd_usrp_handle h, double bandwidth, size_t chan);

UHD_API uhd_error uhd_usrp_get_tx_bandwidth(
    uhd_usrp_handle h, size_t chan, double* bandwidth_out);

UHD_API uhd_error uhd_usrp_get_tx_bandwidth_range(
    uhd_usrp_handle h, size_t chan, uhd_meta_range_handle bandwidth_range_out);

UHD_API uhd_error uhd_usrp_get_tx_sensor(uhd_usrp_handle h,
    const char* name,
    size_t chan,
    uhd_sensor_value_handle* sensor_value_out);

UHD_API uhd_error uhd_usrp_get_tx_sensor_names(
    uhd_usrp_handle h, size_t chan, uhd_string_vector_handle* sensor_names_out);

/****************************************************************************
 * GPIO methods
 ***************************************************************************/

UHD_API uhd_error uhd_usrp_get_gpio_banks(
    uhd_usrp_handle h, size_t mboard, uhd_string_vector_handle* gpio_banks_out);


UHD_API uhd_error uhd_usrp_set_gpio_attr(uhd_usrp_handle h,
    const char* bank,
    const char* attr,
    uint32_t value,
    uint32_t mask,
    size_t mboard);


UHD_API uhd_error uhd_usrp_get_gpio_attr(uhd_usrp_handle h,
    const char* bank,
    const char* attr,
    size_t mboard,
    uint32_t* attr_out);

#ifdef __cplusplus
}
#endif