The existing bladerf_sync_rx() snippet in the libbladeRF API docs has
been replaced by a more complete snippet in libbladeRF/doc/examples.
From now on, major snippets and examples to be included in
Doxygen-generated documentation shall now be placed in the
libbladeRF/doc/examples directory, and must be buildable and testable.
The Doxygen "snippet" command to shall be used to include the relevant
code from the example program.
libbladeRF: [WIP] Use a simple delay to wait for TX samples in example
API support for timestamp metadata has been introduced. This is made
available when using the newly introduced BLADERF_FORMAT_SC16_Q11_META
format value.
When using the synchronous interface, metadata is exchanged between the
caller and the API via the updated bladerf_metadata structure. Users of
the asynchronous interface must currently manually manage the metadata
headers as desired, as documented in libbladeRF.h.
When using the BLADERF_FORMAT_SC16_Q11_META format in conjunction with
the synchronous interface, it is possible to retrieve the timestamp for
received samples and an indication of overrun. An RX operation may also
be scheduled for at a specific timestamp value the future. Similarly,
bursts of samples can be scheduled to be transmitted at a specific
timestamp value, or at the first available timestamp ("now").
A USB backend based atop of the Cypress CyAPI (which is based atop the
Cypress CyUSB3 driver) has been introduced. This is intended to provide
Windows users with an additional driver to use if they encounter issues
with their USB host controller and libusb.
To build and use this backend, the Cypress FX3 SDK must be installed and
the following CMake flags should be provided:
-DENABLE_BACKEND_CYAPI=Yes -DFX3_SDK_PATH=<path to SDK>
A modified cyusb3.inf is provided in host/drivers/windows/cyusb3. Upon
performing a build this inf file and the associated driver files from
the FX3 SDK will be copied into the "output" directory along with the
bladeRF.dll and bladeRF-cli.exe. To install the driver, point the
Windows driver update to this location and accept the warning about the
driver being unsigned; this occurs because the Cypress driver wasn't
signed with bladeRF VID/PID values.
The libbladeRF device string for this backend is: "cypress"
Many thanks go out to LazyDodo for all his efforts in spearheading the
development of this backend -- much of this code is either his doing or
is directly based upon his efforts.
This addresses issue #309. The XB-100 isn't currently supported via
libbladeRF. This support will come in the future, after the necessary
functionality is presented in the FPGA/firmware to expose this to the
host.
xb_attach() in xb.c was written in a way that would result in a
successful error code being reported when provided with an invalid or
unsupported expansion board type. This has been addressed, with some
cleanup to this function.
In making this change, it was noted that setting BLADERF_XB_NONE was
not disabling an attached expansion board. A FIXME was added here to
draw attention to this; I've registered an issue for this and will
assign it to the author of the XB code.
Top-level API functions now acquire a per-device "control lock" before
performing control, programming, and low-level access operations.
(Specifically, these are the functions that manipulate the device handle
and utilize the FX3 <-> FPGA UART.)
Synchronous data transfer functions now hold a per-device, per-module
"sync lock" to ensure these operations are carried out atomically. The
control lock is also held during sync configuration, as upcoming changes
to introduce metadata support will require flipping some config bits on
the FPGA during this operation.
Only these top-level functions shall acquire these locks; the core logic
code should be able to assume that locks are already acquired.
To alleviate confusion, functions that are *not* part of the API, and
therefore are safe to call within the core logic, are stripped of the
bladerf_ prefix.
Now that pthreads is a required dependency, use of the sync API is
is no longer marked optional in the libbladeRF build.
ENABLE_LIBBLADERF_SYNC and related items have been removed from the
CMake build.
Added the ability to read back the state of FW loopback from devices
running FW v1.7.1. While it is possible to enable FW loopback mode in
v1.7.0 firmware, libbladeRF will now enforce the v1.7.1 requirement so
it can correctly read back and report the FW mode.
bladerf_set_loopback() has also been updated to ensure that the
FW loopback is disabled when switching to an LMS loopback mode.
Corrected a samplerate equation calculation which helps determine how
many transfers should be outstanding over any timeout period at a
specific samplerate. The samplerate should always be greater than the
calculated number, not less than.
This commit introduces 1dB and 3dB rolloff point based filterbank selection.
bladerf_set_frequency() will set the appropriate filter based on frequency.
This is a vestige of earlier code. bladerf_expansion_attach() is the
function that performs the desired functionality.
As such bladerf_xb200_attach() has been made static and renamed in xb.c.
This was limited due to 3.72GHz being the maximum value show in the
LMS6002D programming guide's FREQSEL table. According to a response
on the limemicro-opensource Google group, we should be able to use
the same FREQSEL value from 3.72GHz - 3.8GHz.
Operations that open files (e.g., firmware flash, FPGA load) now
return BLADERF_ERR_NO_FILE instead of BLADERF_ERR_IO when a file not
found. This is intended to help differentiate between user-error in the
aforementioned operations and a device-failure.
This function now correctly handles the case where a caller specifies
NULL for the 'actual' parameter if (s)he does not wish to retrieve
the actual bandwidth set.
This fixes#245.
bladerf_backend_str() may be used to retrieve the string associated with
the <backend> portion of a device specifier string (for use with
bladerf_open()).
It is now possible to specify "*" to denote "any available backend":
bladeRF-cli -i -d "*:instance=0"
After further discussion, it was concluded that little benefit is gained
by providing byte interfaces to the SPI flash; users using this API were
already forced to be aware of page/eraseblock alignment, and would have
to be aware of the underlying flash memory map.
Therefore, the following API changes have been made:
- bladerf_erase_flash() now takes an erase_block number and an
erase_block count.
- bladerf_read_flash()/bladerf_write_flash() now take a page number,
and a page count.
- The unaligned flash read/write functions have been removed. If users
are going to be working at a low-level with flash, they'll likely
want to manage the read-modify-erase cycles themselves.
Internal to libbladeRF, these changes have been propagated down to the
backend interface. Although the flash on the current bladeRF is only
a 4 MiB part, the types have been kept as uint32_t, to accommodate
any future HW changes.
Performed cleanup and reorganization of flash-related code. The following
items have been changed in the libbladeRF API:
- Fixed "sector" vs "erase block" misnomer. While the SPI flash on the
bladeRF has "sectors", these are not the units actually being used
in the firmware to perform erase operations. As such, the API and
underlying code has been updated to perform erases in terms of the
"erase block" unit.
- Renamed bladerf_program_flash_unaligned() to
bladerf_write_flash_unaligned() for consistency.
- Flash-related API calls now only return 0 on success, or a
BLADERF_ERR_* value upon failure. They no longer return the number of
bytes read/written/erased. This is intended to be more consistent
with the rest of the API. The requested size of the read/erase/write
is guaranteed to be performed at requested size, so returning a byte
count merely complicates the API "contract" and offers no usefulness.
- To erase the FPGA stored in SPI flash for autoloading, a new
function, bladerf_erase_stored_fpga(), has been introduced. This
replaces the use of bladerf_flash_fpga(dev, "X").
Internally, the following changes have been made:
- All flash-related code has been moved to flash.c (e.g., from bladerf.c).
This is part of the ongoing effort to move logic out of bladerf.c and
into the associated module, with the intent of the bladerf.c
"API top-level" of only acquiring a per-device lock (in the future)
and delegate actions to the module implementations.
- Backend flash operations are now in units of erase blocks and pages,
to alleviate backend code needing to deal with conversions.
Removing the firmware loopback function in preference of adding an
enumerated type to the loopbacks.
NOTE: Currently the firmware loopback does not check for an appropriate
version before trying to set it. Caution should be used while using
this function for now.
To support cases where callbacks would need to block (which they can't),
the async stream implementation has been modified to support
bladerf_submit_stream_buffer(), which allows buffers to be submitted for
transfer outside of the callback functions.
There are some caveats to using this; the documentation has been updated
to note where care should be taken with lock acquisition.
Per the libusb documentation, the libusb async callbacks must be
executed atomically.
In half-duplex cases where one thread is sitting in a bladerf_stream()
call, this was a problem. However, in full-duplex cases, we can have
two threads, each calling a libusb handle_events fn, enter the callback
for a single module. This would result in:
- Buffers being passed to user callbacks in the wrong order
- Stream state and error conditions being corrupted
API documentation changes:
- Added min/max #defines for:
RXVGA1, RXVGA2, TXVGA1, TXVGA2, sample rate, bandwidth,
& frequency
- Documented ranges and error/clamping behavior for:
bladerf_set_sample_rate, bladerf_set_rational_sample_rate,
bladerf_set_correction, bladerf_set_txvga1, bladerf_set_txvga2,
bladerf_set_rxvga1, bladerf_set_rxvga2, bladerf_select_band,
Ensured the aforementioned functions clamp or return an error
for out-of-range input. The low-level functions have NOT been updated
for range checks. (e.g., bladerf_si5338_set_tx_freq).
The sync interface has been re-implemented atop the existing
asynchronous interface. This is currently opt-in and only enable when
pthreads support is enabled and available.
Some clarifications have been made in the API documentation,
specifically in the explanations of the various stream parameters.
The bladerf_set_transfer_timeout and bladerf_get_transfer_timeout have
been named more appropriately, as these control stream transfer
timeouts, as opposed to all transfers.