diff --git a/host/libraries/libbladeRF/doc/doxygen/mainpage.dox b/host/libraries/libbladeRF/doc/doxygen/mainpage.dox index 609b02f6..b7ca939c 100644 --- a/host/libraries/libbladeRF/doc/doxygen/mainpage.dox +++ b/host/libraries/libbladeRF/doc/doxygen/mainpage.dox @@ -27,13 +27,13 @@ accessible knowledge base of common questions and answers to be developed. Bugs, both in libbladeRF and this documentation, may be reported on the GitHub issue tracker -@attention libbladeRF 2.0.0 introduces breaking changes to the parameter lists +@attention libbladeRF 2.0 introduces breaking changes to the parameter lists for bladerf_get_frequency(), bladerf_stream(), and bladerf_sync_config(). @attention Existing code using these functions @b must be updated to be compatible with this version. See the - \ref relnotes_2_0_0_api_freq_uint64 and - \ref relnotes_2_0_0_api_stream sections of the \ref relnotes_2_0_0 + \ref relnotes_2_0_api_freq_uint64 and + \ref relnotes_2_0_api_stream sections of the \ref relnotes_2_0 document for guidance.
@@ -85,7 +85,7 @@ libbladeRF provides the ability to: The API Sections page presents a complete list of of the libbladeRF API sections, including the aforementioned items. -The \ref relnotes_2_0_0 page summarizes the new features and changes in +The \ref relnotes_2_0 page summarizes the new features and changes in the second major release of libbladeRF. The following pages provide examples and more detailed usage information: diff --git a/host/libraries/libbladeRF/doc/doxygen/relnotes_2_0.dox b/host/libraries/libbladeRF/doc/doxygen/relnotes_2_0.dox new file mode 100644 index 00000000..fd9ed7c2 --- /dev/null +++ b/host/libraries/libbladeRF/doc/doxygen/relnotes_2_0.dox @@ -0,0 +1,760 @@ +/** + +\page relnotes_2_0 libbladeRF 2.0 Release Notes + +@attention libbladeRF 2.0 introduces breaking changes to the parameter lists + for bladerf_get_frequency(), bladerf_stream(), and + bladerf_sync_config(). +@attention Existing code using these functions @b must be updated to be + compatible with this version. See the + \ref relnotes_2_0_api_freq_uint64 and + \ref relnotes_2_0_api_stream sections for guidance. +@attention Additionally, if you use bladerf_get_gain() and/or + bladerf_set_gain(), be aware that the gain range for these functions + has shifted. See \ref relnotes_2_0_api_gain for guidance. + +This document describes many of the changes in libbladeRF 2.0, our latest major +version increment that features significant changes. This release adds support +for the bladeRF 2.0 Micro, and improves the API for all bladeRF products. This +is also the first release with bindings for the Python programming language. + +We are very excited to release this library alongside the new bladeRF Micro. +libbladeRF 2.0 began as a fork of the bladeRF codebase. Across the FPGA, +firmware, and host software trees, we added 95,000+ lines (and deleted 18,000+) +to the bladeRF codebase, in more than 600 commits. + +In case you experience any bugs or missing features, please use our issue +tracker at https://github.com/Nuand/bladeRF/issues to report any problems +you encounter with this release. Also, visit our forums at +https://nuand.com/forums/ to discuss this release with other bladeRF users. + +\tableofcontents + +\section relnotes_2_0_api Significant changes to the libbladeRF API + +We attempted to minimize the changes required to make existing applications +work with libbladeRF 2.0. However, the nature of this project required some +changes to the API. Many of the changes can be transparently handled by +compilers. However, applications will generally need to be recompiled and +relinked to work with this version. + +Each topic has a table describing the affected functions, the importance +of this change, and the recommended action. Please see +\ref relnotes_2_0_ref_nomenclature for definitions of the words used in the +"Importance" column. + +\subsection relnotes_2_0_api_freq_uint64 RF frequencies are now uint64_t + +In libbladeRF 1.x, RF frequencies were specified as 32-bit `unsigned int`. To +support the wider frequency range of the bladeRF Micro, frequencies are now +specified as `uint64_t`, which is typedef'd as ::bladerf_frequency. + + + + + + + + + + + + + + + + +
Required actions
API ComponentImportanceAction
bladerf_get_frequency()Required + The `frequency` parameter is now a pointer to a ::bladerf_frequency. + + \warning Applications using this function must be modified to pass in + the correct type. +
bladerf_set_frequency() + Required for full compatibility + + \note This action is required to use RF frequencies above ~4 GHz. + + The `frequency` parameter is now of type ::bladerf_frequency. + + \note Compilers will generally implicitly cast `unsigned int` to + ::bladerf_frequency, but frequencies above `UINT32_MAX` will not + be available. +
bladerf_select_band()
bladerf_schedule_retune()
+ +\remarks +\li Don't be alarmed if there is a small discrepancy (a few Hz) in the value + returned by bladerf_get_frequency(), compared to what was requested by + bladerf_set_frequency(). +\li Do check bladerf_get_frequency_range() \em before using + bladerf_set_frequency() on a given device/channel. +\li Do check bladerf_get_frequency() \em after doing bladerf_set_frequency(), + to verify that the expected frequency was achieved. +\li Do expect bladerf_get_frequency() to return values larger than `UINT32_MAX`. +\li Do use the ::bladerf_frequency type when possible. + +\subsection relnotes_2_0_api_stream Streaming API changes for MIMO + +The data transfer APIs were expanded to support MIMO (multiple-input, +multiple-output). This capability is used to transmit or receive samples via +multiple RF ports simultaneously. + + + + + + + + + + + + + + + + + + + + + + +
Required actions
API ComponentImportanceAction
bladerf_sync_config()Required + The `bladerf_module` argument has been replaced with + \ref bladerf_channel_layout. + + Replace `BLADERF_MODULE_RX` with \ref BLADERF_RX_X1, and + `BLADERF_MODULE_TX` with \ref BLADERF_TX_X1. + + \warning Applications using these functions must be modified to pass + in the correct type. + + \note Existing `bladerf_module` values are valid for SISO applications, + but an explicit cast is usually required: +``` +void configure_module_sync(bladerf_module module) { + // ... + status = bladerf_sync_config(dev, (bladerf_channel_layout)module, format, num_buffers, buffer_size, num_transfers, stream_timeout); + // ... +} +``` +
bladerf_stream()
bladerf_get_timestamp()Optional + The `bladerf_module` argument has been replaced with + \ref bladerf_direction. + + Replace `BLADERF_MODULE_RX` with \ref BLADERF_RX, and + `BLADERF_MODULE_TX` with \ref BLADERF_TX. + + \note Existing `bladerf_module` values are still valid, and a cast + should not be necessary. +
bladerf_set_stream_timeout()
bladerf_get_stream_timeout()
bladerf_sync_tx()Informational + The `samples` parameter is now a pointer to a `const`, to enforce + safety. This should not impact user code. +
+ +\remarks +\li Don't use the `BLADERF_MODULE_RX` and `BLADERF_MODULE_TX` values. +\li Do feel free to re-implement bladerf_interleave_stream_buffer() and/or + bladerf_deinterleave_stream_buffer() in a more efficient fashion. These + are convenience functions written for clarity and portability, not + performance. + +\see \ref relnotes_2_0_ref_channels +\see \ref BLADERF_FORMAT_SC16_Q11 describes the sample interleaving format. +\see bladerf_interleave_stream_buffer() - Interleaves contiguous blocks of + samples in preparation for MIMO TX. +\see bladerf_deinterleave_stream_buffer() - Deinterleaves samples into + contiguous blocks after MIMO RX. +\see bladerf_get_channel_count() - Get the number of RX or TX channels + supported by the given device. + +\subsection relnotes_2_0_api_channel bladerf_module replaced by bladerf_channel + +In libbladeRF 1.x, `bladerf_module` was an enum with two valid choices: +`BLADERF_MODULE_RX` and `BLADERF_MODULE_TX`. To support MIMO, this enum has +been replaced with \ref bladerf_channel, and a pair of convenience macros have +been defined to specify channels: BLADERF_CHANNEL_RX(ch) and +BLADERF_CHANNEL_TX(ch). + +For backwards compatibility, `bladerf_module` is a typedef of +\ref bladerf_channel, and the `BLADERF_MODULE_RX` and `BLADERF_MODULE_TX` +identifiers are now macros for BLADERF_CHANNEL_RX(0) and BLADERF_CHANNEL_TX(0) +respectively. + +Note that some `bladerf_module` instances have been replaced with +\ref bladerf_direction and \ref bladerf_channel_layout depending on context. +See the \ref relnotes_2_0_api_stream section elsewhere in this document. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Required actions
API ComponentImportanceAction
bladerf_enable_module() + Required for full compatibility + + \note This action is required to fully support devices with multiple + channels. Without these changes, only the first channel will be + available for use. + + Replace `bladerf_module` with \ref bladerf_channel. + + Replace `BLADERF_MODULE_RX` with BLADERF_CHANNEL_RX(0), or + generally, BLADERF_CHANNEL_RX(channel_number) + + Replace `BLADERF_MODULE_TX` with BLADERF_CHANNEL_TX(0), or + generally, BLADERF_CHANNEL_TX(channel_number) +
bladerf_set_gain()
bladerf_set_gain_mode()
bladerf_get_gain_mode()
bladerf_set_sample_rate()
bladerf_set_rational_sample_rate()
bladerf_get_sample_rate()
bladerf_get_rational_sample_rate()
bladerf_set_bandwidth()
bladerf_get_bandwidth()
bladerf_set_lpf_mode()
bladerf_get_lpf_mode()
bladerf_select_band()
bladerf_set_frequency()
bladerf_schedule_retune()
bladerf_cancel_scheduled_retunes()
bladerf_get_frequency()
bladerf_get_quick_tune()
bladerf_trigger_init()
bladerf_set_correction()
bladerf_get_correction()
bladerf_xb200_set_filterbank()
bladerf_xb200_get_filterbank()
bladerf_xb200_set_path()
bladerf_xb200_get_path()
bladerf_read_trigger()
bladerf_write_trigger()
+ +\remarks +\li Don't use `BLADERF_MODULE_RX` or `BLADERF_MODULE_TX`. +\li Don't assume the number of channels available. +\li Do always check bladerf_get_channel_count() to determine how many channels + are available in a given direction. +\li Do use the BLADERF_CHANNEL_RX(channel) and BLADERF_CHANNEL_TX(channel) + convenience macros. + +\see \ref relnotes_2_0_ref_channels +\see bladerf_get_channel_count() - Get the number of RX or TX channels + supported by the given device. + +\subsection relnotes_2_0_api_range Defined BLADERF_*_{MAX,MIN,etc} constants replaced by bladerf_get_*_range functions + +The precompiler constants for supported minimum/maximum values have been +deprecated and replaced with a set of context-aware functions. The old +constants will be removed in a later release. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Required actions
API ComponentImportanceAction
BLADERF_RXVGA1_GAIN_MIN + Required for full compatibility + + \note This action is required for proper functioning of new bladeRF + models. The old constants are only valid for the original + bladeRF, and are not valid for other models. + + Use bladerf_get_gain_stage_range() to retrieve the range of allowable + gains for a specific gain stage. + + \see bladerf_get_gain() and bladerf_set_gain() +
BLADERF_RXVGA1_GAIN_MAX
BLADERF_RXVGA2_GAIN_MIN
BLADERF_RXVGA2_GAIN_MAX
BLADERF_TXVGA1_GAIN_MIN
BLADERF_TXVGA1_GAIN_MAX
BLADERF_TXVGA2_GAIN_MIN
BLADERF_TXVGA2_GAIN_MAX
BLADERF_LNA_GAIN_MID_DB
BLADERF_LNA_GAIN_MAX_DB
BLADERF_SAMPLERATE_MIN + Use bladerf_get_sample_rate_range() to retrieve the range of allowable + sample rates for a given channel. +
BLADERF_SAMPLERATE_REC_MAX
BLADERF_BANDWIDTH_MIN + Use bladerf_get_bandwidth_range() to retrieve the supported range of + bandwidths for a given channel. +
BLADERF_BANDWIDTH_MAX
BLADERF_FREQUENCY_MIN_XB200 + Use bladerf_get_frequency_range() to retrieve the supported range of + frequencies for a given channel. + + \note The range will vary depending on the particular hardware + configuration, such as if a XB-200 is attached. +
BLADERF_FREQUENCY_MIN
BLADERF_FREQUENCY_MAX
+ +An example use of bladerf_get_frequency_range(): + +\code{.c} +bool is_frequency_within_range(struct bladerf *dev, bladerf_channel channel, bladerf_frequency frequency) +{ + int status; + struct bladerf_range range; + + status = bladerf_get_frequency_range(dev, channel, &range); + if (status < 0) { + // error case + } + + return ((frequency / range.scale) >= range.min && (frequency / range.scale) <= range.max); +} +\endcode + +\remarks +\li Don't use the legacy `BLADERF_*_{MIN,MAX}` defines or any hardcoded values + derived from them. +\li Don't assume that the ranges will remain constant throughout operation, + or that they are the same for all channels. +\li Don't hardcode ranges, or guess them based on the board model. +\li Do remember that the ranges can change depending on configuration, e.g. + bladerf_get_gain_range() may return different values for an RX channel + depending on the configured center frequency. +\li Do call `bladerf_get_*_range()` every time you need to know -- don't + cache it! +\li Do test to ensure user-supplied values are valid before using them, when + possible. +\li Do handle \ref BLADERF_ERR_RANGE errors when setting values, especially if + you don't check for validity first. The library will only return this if + it is not sensible to clamp the value to be within range, e.g. with + bladerf_set_sample_rate(). + +\see bladerf_get_gain_stages() - Get a list of available gain stages. +\see bladerf_set_gain() - Set overall system gain. +\see bladerf_get_gain() - Get overall system gain. + +\subsection relnotes_2_0_api_gain bladerf_{get,set}_gain range standardization + +Previously, the ranges used by bladerf_get_gain() and bladerf_set_gain() were +somewhat arbitrary, with a value of 0 being the minimum possible gain, and the +maximum possible gain being the sum of the max gain for all gain stages. + +To allow the same gain settings to produce similar results on all bladeRF +models, we've adjusted the gain ranges for these two functions to define 60 dB +as the maximum available gain on RX, and roughly +0 dBm output power on TX. + + + + + + + + + + +
Required actions
API ComponentImportanceAction
bladerf_set_gain() + Required for full compatibility + + \note This change affects the meaning of the values passed to/from + these functions, and the impact should be reviewed to avoid + unexpected results. + + 60 dB is now defined as: + \li RX channels: Maximum RX Gain + \li TX channels: +0 dBm TX power (CW, approximate) +
bladerf_get_gain()
+ +\note Individual gain stages (bladerf_set_gain_stage() and + bladerf_get_gain_stage()) still expect raw hardware-specific values. + +\note The TX Gain is \em not calibrated, and the actual output power will vary + from board to board, frequency to frequency, and even between different + output ports on the same board. Applications requiring precise control + of TX power should consider calibration. + +\see \ref relnotes_2_0_feats_gc_proportioning + +\subsection relnotes_2_0_api_typedefs Common parameter types now have typedefs + +For semantic clarity, common parameter types now have typedefs. + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Required actions
API ComponentImportanceAction
bladerf_set_frequency()Required + The declarations for these functions were changed to use defined + types. No changes are immediately necessary, with the exception of + ::bladerf_frequency. + + The new types are: + + \li ::bladerf_gain (gain value in dB; `int`) + \li ::bladerf_sample_rate (sample rate in samples per second; + `unsigned int`) + \li ::bladerf_bandwidth (bandwidth in Hz; `unsigned int`) + \li ::bladerf_frequency (center frequency in Hz; now `uint64_t`, + was `uint32_t`) + \li ::bladerf_timestamp (timestamp in ticks; `uint64_t`) + \li ::bladerf_correction_value (correction value in arbitrary units; + `int16_t`) + + \see \ref relnotes_2_0_api_freq_uint64 +
bladerf_get_frequency()
bladerf_schedule_retune()
bladerf_select_band()
bladerf_set_gain()Optional
bladerf_get_gain()
bladerf_set_gain_stage()
bladerf_get_gain_stage()
bladerf_set_sample_rate()
bladerf_get_sample_rate()
bladerf_set_bandwidth()
bladerf_get_bandwidth()
bladerf_set_correction()
bladerf_get_correction()
bladerf_get_timestamp()
struct bladerf_metadata
+ +\todo +Issue #577: +Using `printf()` with a ::bladerf_frequency or ::bladerf_timestamp currently +require knowing that they are actually `uint64_t`, e.g. +`printf("the frequency is %" PRIu64 " Hz\n", freq);`. + +\section relnotes_2_0_feats New features + +\subsection relnotes_2_0_feats_platform Multiple platform support + +We reorganized libbladeRF to easily support multiple hardware platforms. You +will find a new directory tree, `host/libraries/libbladeRF/src/board/`, +containing subdirectories for each supported platform (currently `bladerf1/` for +the LMS6002D-based bladeRF family, and `bladerf2/` for the AD9361-based bladeRF +Micro family). + +Likewise, product-specific API calls have been moved into two new header files: +bladeRF1.h and bladeRF2.h. Functions which apply to all boards remain in +libbladeRF.h. + +\see Refer to bladeRF1.h and bladeRF2.h for a list of affected functions. + +\note Using API calls specified in bladeRF1.h or bladeRF2.h is not recommended + for most use cases. They are provided for backwards compatibility and + low-level hardware control, and are subject to change. + +We also rearranged a number of source files into subdirectories of +`host/libraries/libbladeRF/src/`. In addition to the pre-existing `backend/`, +you'll also find `board/` (product-specific code), `driver/` (device drivers), +`expansion/` (expansion board drivers), `helpers/` (helpful utility functions), +and `streaming/` (sample streaming code). + +\subsection relnotes_2_0_feats_gc Gain control improvements + +The original manual gain control functionality in libbladeRF was very low-level +and hardware-specific, and requires significant knowledge of the underlying +RF module to adjust. As such, new gain control methods have been introduced +to the API, and the following functions are now deprecated: + +\li bladerf_set_lna_gain() and bladerf_get_lna_gain() +\li bladerf_set_rxvga1() and bladerf_get_rxvga1() +\li bladerf_set_rxvga2() and bladerf_get_rxvga2() +\li bladerf_set_txvga1() and bladerf_get_txvga1() +\li bladerf_set_txvga2() and bladerf_get_txvga2() + +Instead, applications should use one of approaches described below. + +\subsubsection relnotes_2_0_feats_gc_agc Automatic Gain Control (AGC) + +Automatic gain control is available for RX channels, starting with +libbladeRF v1.9.0 +and +FPGA v0.7.0. +AGC continually adjusts the system's gain to ensure the received signal has a +high dynamic range, while avoiding clipping. + +\li bladerf_get_gain_modes() reports the available gain modes on a channel +\li bladerf_get_gain_mode() reports the current gain mode for a channel +\li bladerf_set_gain_mode() sets the gain mode for a channel + +As of this writing, the available gain modes are: + +\li bladeRF: \b ::BLADERF_GAIN_AUTOMATIC (default), ::BLADERF_GAIN_MANUAL +\li bladeRF Micro: ::BLADERF_GAIN_MGC, ::BLADERF_GAIN_FASTATTACK_AGC, + \b ::BLADERF_GAIN_SLOWATTACK_AGC (default), + ::BLADERF_GAIN_HYBRID_AGC + +\note bladerf_get_gain_mode() and bladerf_set_gain_mode() will return + ::BLADERF_ERR_UNSUPPORTED for TX channels. + +\code{.c} +void agc_example(struct bladerf *dev, bladerf_channel channel) +{ + int i, status; + const struct bladerf_gain_modes *modes = NULL; + bladerf_gain_mode mode; + + // What gain modes are available? + status = bladerf_get_gain_modes(dev, channel, &modes); + if (status < 0) { + // error case + } + + for (i = 0; i < status; ++i) { + printf("enum %d is gain mode %s\n", modes[i]->mode, modes[i]->name); + } + + // Get current gain mode + status = bladerf_get_gain_mode(dev, channel, &mode); + if (status < 0) { + // error case + } + + printf("current gain mode: %d\n", mode); + + // Enable AGC + mode = BLADERF_GAIN_AUTOMATIC; + status = bladerf_set_gain_mode(dev, channel, mode); + if (status < 0) { + // error case + } +} +\endcode + +\subsubsection relnotes_2_0_feats_gc_proportioning System gain proportioning + +In previous versions, setting the gain required careful proportioning of gain +between LNAs and VGAs. To reduce the implementation burden, an overall gain may +now be specified, and the RFIC's gain stages will be set appropriately. + +\li bladerf_get_gain_range() reports the allowable values for a channel's gain +\li bladerf_get_gain() reports the current overall gain for a channel +\li bladerf_set_gain() sets the overall gain for a channel + +The gain scales are defined such that a 60 dB gain on a TX channel is +\em approximately 0 dBm CW output, and a 60 dB gain on a RX channel is the +maximum available amplification. + +\note bladerf_set_gain() may be unavailable or may not operate as expected if + \ref relnotes_2_0_feats_gc_agc is enabled, or if the channel + is not currently enabled. + +\note The range returned by bladerf_get_gain_range() may vary depending on the + selected center frequency. + +\code{.c} +void gain_example(struct bladerf *dev, bladerf_channel channel, int gain) +{ + int old_gain, status; + const struct bladerf_range *range = NULL; + + // What is the valid range? + status = bladerf_get_gain_range(dev, channel, &range); + if (status < 0) { + // error case + } + + // What is the current gain? + status = bladerf_get_gain(dev, channel, &old_gain); + if (status < 0) { + // error case + }; + + printf("Channel %d current gain: %4d dB (Range: [%g, %g])\n", + channel, old_gain, range->min * range->scale, range->max * range->scale); + + // Set the new gain value + status = bladerf_set_gain(dev, channel, gain); + if (status < 0) { + // error case + }; +} + +... + +gain_example(dev, BLADERF_CHANNEL_TX(0), 60); // set 60 dB TX gain (~ 0 dBm) +gain_example(dev, BLADERF_CHANNEL_RX(0), 60); // set 60 dB RX gain (max) +\endcode + +\see bladerf_get_rfic_rssi() - query received signal strength from the RFIC. + +\subsubsection relnotes_2_0_feats_gc_manual Individual gain stage control + +Advanced implementations that need to directly configure the gain stages may +use the following family of functions: + +\li bladerf_get_gain_stages() reports the gain stages on a given channel +\li bladerf_get_gain_stage_range() reports the range of allowable values for a + given gain stage +\li bladerf_get_gain_stage() reports the current value for a gain stage +\li bladerf_set_gain_stage() sets the gain for a given gain stage + +\note The values set here will be reflected in bladerf_get_gain(), but using + bladerf_set_gain() will override any individual gain stage settings on + a particular channel. + +\note bladerf_set_gain_stage() may be unavailable or may not operate as + expected if \ref relnotes_2_0_feats_gc_agc is enabled, or if + the channel is not currently enabled. + +\note The range returned by bladerf_get_gain_stage_range() may vary depending + on the selected center frequency. + +\subsection relnotes_2_0_feats_hw New hardware features + +libbladeRF 2.0 includes support for new hardware features on the bladeRF Micro. + +\subsubsection relnotes_2_0_feats_hw_biastee Bias tees + +The bias tees apply a +5 VDC bias to the SMA connectors, which may be used +for powering active antennas or inline amplifiers. + +\warning Enabling the bias tee on one channel enables it for all channels in + that direction; e.g. enabling RX1 will enable both RX1 and RX2 + simultaneously. Use caution if there are multiple devices attached + to the bladeRF Micro. + +\see bladerf_get_bias_tee() and bladerf_set_bias_tee() + +\subsubsection relnotes_2_0_feats_hw_clock Clock references and controls + +An external frequency reference may be connected to the J95 U.FL connector +("REFIN") to discipline the onboard VCTCXO. By default, this port expects +10 MHz, but it can be configured for reference frequencies between 5 MHz and +300 MHz. + +\see bladerf_get_pll_enable(), bladerf_set_pll_enable() - enabling the PLL +\see bladerf_get_pll_lock_state() - verifying PLL lock +\see bladerf_get_pll_refclk_range(), bladerf_get_pll_refclk(), + bladerf_set_pll_refclk() - configure reference clock frequency + +Alternatively, a 38.4 MHz clock may be provided into the CLKIN port. + +\see bladerf_get_clock_select(), bladerf_set_clock_select() - select between + internal and external (J93) clock + +There is also a CLKOUT port, which can provide a buffered 38.4 MHz system clock +output. + +\see bladerf_get_clock_output(), bladerf_set_clock_output() - enable or disable + clock output (J92) + +\subsubsection relnotes_2_0_feats_hw_power Power status + +Functions are provided to determine how the board is currently being powered, +what the bus voltage is, and what the system current and power draws are. + +\see bladerf_get_power_source() - query how the board is currently powered +\see bladerf_get_pmic_register() - get bus voltage, load current, load power + +\subsubsection relnotes_2_0_feats_hw_temperature RFIC temperature + +The RFIC has an onboard temperature sensor, which may be useful for +environmental monitoring, or for determining if the RFIC's synthesizers should +be re-tuned after a significant temperature shift. + +\see bladerf_get_rfic_temperature() + +\section relnotes_2_0_ref Further information + +\subsection relnotes_2_0_ref_channels What is a channel? + +In the bladeRF architecture, a channel is a single, unidirectional RF path. +There is a 1:1 mapping between a ::bladerf_channel and a physical RF port. + +On the original bladeRF, there are two channels available: + +\li BLADERF_CHANNEL_RX(0) == J53 "RX" +\li BLADERF_CHANNEL_TX(0) == J54 "TX" + +On the bladeRF Micro, there are four channels available: + +\li BLADERF_CHANNEL_RX(0) == J1 "RX1" +\li BLADERF_CHANNEL_RX(1) == J3 "RX2" + +\li BLADERF_CHANNEL_TX(0) == J2 "TX1" +\li BLADERF_CHANNEL_TX(1) == J4 "TX2" + +Generally speaking, you will want to apply settings to a specific channel. + +Note that some groups of channels may share some settings on some hardware: for +example, if you bladerf_set_frequency() on a bladeRF Micro's +BLADERF_CHANNEL_RX(0), it will also change the frequency of +BLADERF_CHANNEL_RX(1), because both RX ports share the same local oscillator. + +There are some functions which always apply to all the RX channels or all the +TX channels. These accept a ::bladerf_direction argument: + +\li bladerf_get_channel_count() +\li bladerf_get_timestamp() +\li bladerf_set_stream_timeout() +\li bladerf_get_stream_timeout() + +Finally, there are two functions which accept a ::bladerf_channel_layout. +This specifies two things: the direction (RX vs TX), and the number of channels +interleaved in the sample buffers (currently 1 or 2). + +\li bladerf_sync_config() +\li bladerf_stream() + +\subsection relnotes_2_0_ref_nomenclature Definitions for "Importance" + + + + + + + + + + + + + + + + + + + +
WordMeaning
Required + This change must be performed to build code against libbladeRF 2.0. + Compile errors will result if you fail to do so. +
Required for full compatibility + This change is not required for building, but some functionality may + be missing or unavailable with some devices. + + A Note will be included to describe the impact of not making this + change. +
Optional + This change is optional, but recommended for clarity and/or future + compatibility. +
Informational + This is an informational item, and no action is necessary or expected. +
+ +*/ diff --git a/host/libraries/libbladeRF/doc/doxygen/relnotes_2_0_0.dox b/host/libraries/libbladeRF/doc/doxygen/relnotes_2_0_0.dox deleted file mode 100644 index 68e71989..00000000 --- a/host/libraries/libbladeRF/doc/doxygen/relnotes_2_0_0.dox +++ /dev/null @@ -1,497 +0,0 @@ -/** - -\page relnotes_2_0_0 libbladeRF 2.0.0 Release Notes - -This page describes many of the changes in libbladeRF 2.0.0, our first major -version increment in more than three years. This release adds support for the -bladeRF Micro, and improves the API for all bladeRF products. This is also the -first release with bindings for the Python programming language. - -@attention libbladeRF 2.0.0 introduces breaking changes to the parameter lists - for bladerf_get_frequency(), bladerf_stream(), and - bladerf_sync_config(). -@attention Existing code using these functions @b must be updated to be - compatible with this version. See the - \ref relnotes_2_0_0_api_freq_uint64 and - \ref relnotes_2_0_0_api_stream sections for guidance. - -We are very excited to release this library alongside the new bladeRF Micro. -libbladeRF 2.0.0 began as a fork of the bladeRF codebase in February 2017. -Across the FPGA, firmware, and host software trees, four engineers added -95,000+ lines (and deleted 18,000+) to the bladeRF codebase, in more than 600 -commits. - -Inevitably, there will be bugs or missing features. Please use our issue -tracker at https://github.com/Nuand/bladeRF/issues to report any problems -you encounter with this release. Also, visit our forums at -https://nuand.com/forums/ to discuss this release with other bladeRF users. - -\tableofcontents - -\section relnotes_2_0_0_api Significant changes to the libbladeRF API - -We attempted to minimize the changes required to make existing applications -work with libbladeRF 2.x. However, the nature of this project required some -changes to the API. - -Many of the changes can be transparently handled by compilers. However, -applications will generally need to be recompiled and relinked to work with -this version. - -\subsection relnotes_2_0_0_api_freq_uint64 Tuning frequencies are now uint64_t - -In libbladeRF 1.x, RF frequencies were specified as 32-bit `unsigned int`. To -support the wider frequency range of the bladeRF Micro, frequencies are now -specified as `uint64_t`, which is typedef'd as `bladerf_frequency`. - - - - - - - - - - - - - - - - -
Required actions
API ComponentImportanceAction
bladerf_get_frequency()Required - The `frequency` parameter is now of type `bladerf_frequency*`. - - \warning Applications using this function must be modified to pass in - the correct type. -
bladerf_set_frequency()Minor - The `frequency` parameter is now of type `bladerf_frequency`. - - \note Compilers will generally implicitly cast `unsigned int` to - `bladerf_frequency`. -
bladerf_select_band()
bladerf_schedule_retune()
- -\subsection relnotes_2_0_0_api_stream MIMO support in streaming API - -The data transfer APIs were expanded to support MIMO (multiple-input, -multiple-output). This capability is used to transmit or receive samples via -multiple RF ports simultaneously. - - - - - - - - - - - - - - - - - - - - - -
Required actions
API ComponentImportanceAction
bladerf_sync_config()Required - The `bladerf_module` argument has been replaced with - \ref bladerf_channel_layout. - - Replace `BLADERF_MODULE_RX` with \ref BLADERF_RX_X1, and - `BLADERF_MODULE_TX` with \ref BLADERF_TX_X1. - - \warning Applications using these functions must be modified to pass - in the correct type. - - \note Existing `bladerf_module` values are valid for SISO applications, - but an explicit cast is required: -``` -void configure_module_sync(bladerf_module module) { - // ... - status = bladerf_sync_config(dev, (bladerf_channel_layout)module, format, num_buffers, buffer_size, num_transfers, stream_timeout); - // ... -} -``` -
bladerf_stream()
bladerf_get_timestamp()Minor - The `bladerf_module` argument has been replaced with - \ref bladerf_direction. - - Replace `BLADERF_MODULE_RX` with \ref BLADERF_RX, and - `BLADERF_MODULE_TX` with \ref BLADERF_TX. - - \note Existing `bladerf_module` values are still valid, and a cast - should not be necessary. -
bladerf_set_stream_timeout()
bladerf_get_stream_timeout()
bladerf_sync_tx() - The `samples` parameter is now a pointer to a `const`. - - This should not impact user code. -
- -\see \ref BLADERF_FORMAT_SC16_Q11 describes the sample interleaving format. -\see bladerf_interleave_stream_buffer() - Interleaves contiguous blocks of - samples in preparation for MIMO TX. -\see bladerf_deinterleave_stream_buffer() - Deinterleaves samples into - contiguous blocks after MIMO RX. -\see bladerf_get_channel_count() - Get the number of RX or TX channels - supported by the given device. - -\subsection relnotes_2_0_0_api_channel bladerf_channel replaces bladerf_module - -In libbladeRF 1.x, `bladerf_module` was an enum with two valid choices: -`BLADERF_MODULE_RX` and `BLADERF_MODULE_TX`. To support MIMO, this enum has -been replaced with \ref bladerf_channel, and a pair of convenience macros have -been defined to specify channels: BLADERF_CHANNEL_RX(ch) and -BLADERF_CHANNEL_TX(ch). - -For backwards compatibility, `bladerf_module` is a typedef of -\ref bladerf_channel, and the `BLADERF_MODULE_RX` and `BLADERF_MODULE_TX` -identifiers are now macros for BLADERF_CHANNEL_RX(0) and BLADERF_CHANNEL_TX(0) -respectively. - -Note that some `bladerf_module` instances have been replaced with -\ref bladerf_direction and \ref bladerf_channel_layout depending on context. -See the \ref api_stream section elsewhere in this document. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Required actions
API ComponentImportanceAction
bladerf_enable_module()Required for MIMO support, optional otherwise - Replace `bladerf_module` with \ref bladerf_channel. - - Replace `BLADERF_MODULE_RX` with `BLADERF_CHANNEL_RX(0)`, or - generally, `BLADERF_CHANNEL_RX(channel_number)` - - Replace `BLADERF_MODULE_TX` with `BLADERF_CHANNEL_TX(0)`, or - generally, `BLADERF_CHANNEL_TX(channel_number)` -
bladerf_set_gain()
bladerf_set_gain_mode()
bladerf_get_gain_mode()
bladerf_set_sample_rate()
bladerf_set_rational_sample_rate()
bladerf_get_sample_rate()
bladerf_get_rational_sample_rate()
bladerf_set_bandwidth()
bladerf_get_bandwidth()
bladerf_set_lpf_mode()
bladerf_get_lpf_mode()
bladerf_select_band()
bladerf_set_frequency()
bladerf_schedule_retune()
bladerf_cancel_scheduled_retunes()
bladerf_get_frequency()
bladerf_get_quick_tune()
bladerf_trigger_init()
bladerf_set_correction()
bladerf_get_correction()
bladerf_xb200_set_filterbank()
bladerf_xb200_get_filterbank()
bladerf_xb200_set_path()
bladerf_xb200_get_path()
bladerf_read_trigger()
bladerf_write_trigger()
- -\see bladerf_get_channel_count() - Get the number of RX or TX channels - supported by the given device. - -\subsection relnotes_2_0_0_api_range bladerf_get_*_range functions replace #define'd constants - -The `#define`'d constants for supported minimum/maximum values have been -deprecated and replaced with a set of context-aware functions. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Required actions
API ComponentImportanceAction
BLADERF_RXVGA1_GAIN_MINRequired for complete bladeRF Micro compatibility - Use bladerf_get_gain_stage_range() to retrieve the range of allowable - gains for a specific gain stage. This should be called after setting - the frequency with bladerf_set_frequency(). -
BLADERF_RXVGA1_GAIN_MAX
BLADERF_RXVGA2_GAIN_MIN
BLADERF_RXVGA2_GAIN_MAX
BLADERF_TXVGA1_GAIN_MIN
BLADERF_TXVGA1_GAIN_MAX
BLADERF_TXVGA2_GAIN_MIN
BLADERF_TXVGA2_GAIN_MAX
BLADERF_LNA_GAIN_MID_DB
BLADERF_LNA_GAIN_MAX_DB
BLADERF_SAMPLERATE_MIN - Use bladerf_get_sample_rate_range() to retrieve the range of allowable - sample rates for a given channel. -
BLADERF_SAMPLERATE_REC_MAX
BLADERF_BANDWIDTH_MIN - Use bladerf_get_bandwidth_range() to retrieve the supported range of - bandwidths for a given channel. -
BLADERF_BANDWIDTH_MAX
BLADERF_FREQUENCY_MIN_XB200 - Use bladerf_get_frequency_range() to retrieve the supported range of - frequencies for a given channel. - - \note This will vary depending on the particular hardware configuration - (such as if a XB-200 is attached). -
BLADERF_FREQUENCY_MIN
BLADERF_FREQUENCY_MAX
- -An example use of bladerf_get_frequency_range(): - -\code{.c} -bool is_frequency_within_range(struct bladerf *dev, bladerf_channel channel, bladerf_frequency frequency) -{ - int status; - struct bladerf_range range; - - status = bladerf_get_frequency_range(dev, channel, &range); - if (status < 0) { - // error case - } - - return ((frequency / range.scale) >= range.min && (frequency / range.scale) <= range.max); -} -\endcode - -\see bladerf_get_gain_stages() - Get a list of available gain stages. -\see bladerf_set_gain() - Set overall system gain. -\see bladerf_get_gain() - Get overall system gain. - -\subsection relnotes_2_0_0_api_typedefs New type definitions for parameters - -The following types are now defined: - -\li ::bladerf_gain (gain value in dB; `int`) -\li ::bladerf_sample_rate (sample rate in samples per second; `unsigned int`) -\li ::bladerf_bandwidth (bandwidth in Hz; `unsigned int`) -\li ::bladerf_frequency (center frequency in Hz; `uint64_t`) -\li ::bladerf_timestamp (timestamp in ticks; `uint64_t`) -\li ::bladerf_correction_value (correction value in arbitrary units; `int16_t`) - -With the exception of ::bladerf_frequency, none of the underlying types changed -from libbladeRF 1.x.x and no changes are strictly necessary. However, the -declarations changed for the following functions: - -\li bladerf_set_gain() -\li bladerf_get_gain() -\li bladerf_set_gain_stage() -\li bladerf_get_gain_stage() -\li bladerf_set_sample_rate() -\li bladerf_get_sample_rate() -\li bladerf_set_bandwidth() -\li bladerf_get_bandwidth() -\li bladerf_select_band() -\li bladerf_set_frequency() -\li bladerf_get_frequency() -\li bladerf_schedule_retune() -\li bladerf_set_correction() -\li bladerf_get_correction() -\li bladerf_get_timestamp() - -As well as: - -\li struct bladerf_metadata - -\section relnotes_2_0_0_feats New features - -\subsection relnotes_2_0_0_feats_platform Multiple platform support - -We reorganized libbladeRF to easily support multiple hardware platforms. You -will find a new directory tree, `host/libraries/libbladeRF/src/board/`, -containing subdirectories for each supported platform (currently `bladerf1/` for -the LMS6002D-based bladeRF family, and `bladerf2/` for the AD9361-based bladeRF -Micro family). - -Likewise, product-specific API calls have been moved into two new header files: -bladeRF1.h and bladeRF2.h. Functions which apply to all boards remain in -libbladeRF.h. - -\see Refer to bladeRF1.h and bladeRF2.h for a list of affected functions. - -\note Using API calls specified in bladeRF1.h or bladeRF2.h is not recommended - for most use cases. They are provided for backwards compatibility and - low-level hardware control, and are subject to change. - -We also rearranged a number of source files into subdirectories of -`host/libraries/libbladeRF/src/`. In addition to the pre-existing `backend/`, -you'll also find `board/` (product-specific code), `driver/` (device drivers), -`expansion/` (expansion board drivers), `helpers/` (helpful utility functions), -and `streaming/` (sample streaming code). - -\subsection relnotes_2_0_0_feats_gc Gain control improvements - -The original manual gain control functionality in libbladeRF is very low-level -and hardware-specific, and requires significant knowledge of the underlying -RF module to adjust. As such, new gain control methods have been introduced -to the API, and the following functions are now deprecated: - -\li bladerf_set_lna_gain() and bladerf_get_lna_gain() -\li bladerf_set_rxvga1() and bladerf_get_rxvga1() -\li bladerf_set_rxvga2() and bladerf_get_rxvga2() -\li bladerf_set_txvga1() and bladerf_get_txvga1() -\li bladerf_set_txvga2() and bladerf_get_txvga2() - -Instead, applications should use one of the following approaches: - -\subsubsection relnotes_2_0_0_feats_gc_agc Automatic Gain Control (AGC) - -Automatic gain control is available for RX channels, starting with -libbladeRF v1.9.0 -and -FPGA v0.7.0. -AGC continually adjusts the system's gain to ensure the received signal has a -high dynamic range, while avoiding clipping. - -\li bladerf_get_gain_modes() reports the available gain modes on a channel -\li bladerf_get_gain_mode() reports the current gain mode for a channel -\li bladerf_set_gain_mode() sets the gain mode for a channel - -As of this writing, the available gain modes are: - -\li bladeRF: \b ::BLADERF_GAIN_AUTOMATIC (default), ::BLADERF_GAIN_MANUAL -\li bladeRF Micro: ::BLADERF_GAIN_MGC, ::BLADERF_GAIN_FASTATTACK_AGC, - \b ::BLADERF_GAIN_SLOWATTACK_AGC (default), - ::BLADERF_GAIN_HYBRID_AGC - -\note bladerf_get_gain_mode() and bladerf_set_gain_mode() will return - ::BLADERF_ERR_UNSUPPORTED for TX channels. - -\code{.c} -void agc_example(struct bladerf *dev, bladerf_channel channel) -{ - int i, status; - const struct bladerf_gain_modes *modes = NULL; - bladerf_gain_mode mode; - - // What gain modes are available? - status = bladerf_get_gain_modes(dev, channel, &modes); - if (status < 0) { - // error case - } - - for (i = 0; i < status; ++i) { - printf("enum %d is gain mode %s\n", modes[i]->mode, modes[i]->name); - } - - // Get current gain mode - status = bladerf_get_gain_mode(dev, channel, &mode); - if (status < 0) { - // error case - } - - printf("current gain mode: %d\n", mode); - - // Enable AGC - mode = BLADERF_GAIN_AUTOMATIC; - status = bladerf_set_gain_mode(dev, channel, mode); - if (status < 0) { - // error case - } -} -\endcode - -\subsubsection relnotes_2_0_0_feats_gc_auto System gain proportioning - -In previous versions, setting the gain required careful proportioning of gain -between LNAs and VGAs. To reduce the implementation burden, an overall gain may -now be specified, and the RFIC's gain stages will be set appropriately. - -\li bladerf_get_gain_range() reports the allowable values for a channel's gain -\li bladerf_get_gain() reports the current overall gain for a channel -\li bladerf_set_gain() sets the overall gain for a channel - -The gain scales are defined such that a 60 dB gain on a TX channel is -\em approximately 0 dBm CW output, and a 60 dB gain on a RX channel is the -maximum available amplification. - -\note bladerf_set_gain() may be unavailable or may not operate as expected if - \ref relnotes_2_0_0_feats_gc_agc is enabled, or if the channel - is not currently enabled. - -\note The range returned by bladerf_get_gain_range() may vary depending on the - selected center frequency. - -\code{.c} -void gain_example(struct bladerf *dev, bladerf_channel channel, int gain) -{ - int old_gain, status; - const struct bladerf_range *range = NULL; - - // What is the valid range? - status = bladerf_get_gain_range(dev, channel, &range); - if (status < 0) { - // error case - } - - // What is the current gain? - status = bladerf_get_gain(dev, channel, &old_gain); - if (status < 0) { - // error case - }; - - printf("Channel %d current gain: %4d dB (Range: [%g, %g])\n", - channel, old_gain, range->min * range->scale, range->max * range->scale); - - // Set the new gain value - status = bladerf_set_gain(dev, channel, gain); - if (status < 0) { - // error case - }; -} - -... - -gain_example(dev, BLADERF_CHANNEL_TX(0), 60); // set 60 dB TX gain (~ 0 dBm) -gain_example(dev, BLADERF_CHANNEL_RX(0), 60); // set 60 dB RX gain (max) -\endcode - -\subsubsection relnotes_2_0_0_feats_gc_manual Individual gain stage control - -Advanced implementations that need to directly configure the gain stages may -use the following family of functions: - -\li bladerf_get_gain_stages() reports the gain stages on a given channel -\li bladerf_get_gain_stage_range() reports the range of allowable values for a - given gain stage -\li bladerf_get_gain_stage() reports the current value for a gain stage -\li bladerf_set_gain_stage() sets the gain for a given gain stage - -\note The values set here will be reflected in bladerf_get_gain(), but using - bladerf_set_gain() will override any individual gain stage settings on - a particular channel. - -\note bladerf_set_gain_stage() may be unavailable or may not operate as - expected if \ref relnotes_2_0_0_feats_gc_agc is enabled, or if - the channel is not currently enabled. - -\note The range returned by bladerf_get_gain_stage_range() may vary depending - on the selected center frequency. - -\subsection relnotes_2_0_0_feats_mimo MIMO - -\subsection relnotes_2_0_0_feats_python Python bindings - -*/ diff --git a/host/libraries/libbladeRF/include/libbladeRF.h b/host/libraries/libbladeRF/include/libbladeRF.h index df6468ab..253b5b84 100644 --- a/host/libraries/libbladeRF/include/libbladeRF.h +++ b/host/libraries/libbladeRF/include/libbladeRF.h @@ -2337,7 +2337,7 @@ int CALL_CONV bladerf_enable_module(struct bladerf *dev, * * @param dev Device handle * @param[in] dir Stream direction - * @param[out] value Coarse timestamp value + * @param[out] timestamp Coarse timestamp value * * @return 0 on success, value from \ref RETCODES list on failure */