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
As stated in the API documentation, control calls must only be executed
in one context at a time. A lock has been added to ensure this in the
test_sync program
Changes include:
- Serial # printed in `flash_image` output
- Help text fixes and improvements
- Additional parameter range checks
- Minor source tree reorganization
- Windows: Fixed reading binary files in for transmission
- Added libc version check to determine if -lrt is required
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).
When starting an RX stream, the first N buffers, where N is the number
of transfers, will be submitted when the bladerf_stream() call is made.
Therefore, it is incorrect to clear IN_FLIGHT status; this will result in an
assertion firing in the RX callback.
After looking into this, it's become clear that the sync interface does
not correctly handle the situation where the underlying async stream
starts up. Issue #229 has been opened to further track the associated
defect and resolution.
When restarting a stream, we assume in-flight buffers are lost. These
must be marked empty so they can be re-used.
Also in this commit:
- Cleaned up unnecessary unlock, relock, unlock
- Fixed return value check of pthread_cond_timedwait
Note that this version introduces some reverse-incompatible changes
with respect to v0.13.z and earlier.
Changes Include:
- Removal of bladerf_rx and bladerf_tx functions
- Addition of a new synchronous interface that operates atop the
asynchronous interface.
- Renaming of stream transfer timeout functions
A friendly reminder - the v0.y.z series is officially "unstable."
Some further reverse-incompatible changes are expected to be made as
metadata support is integrated into libbladeRF. It is recommended to
avoid accessing/modifying metadata structures for the time being, as
these are subject to change.
The following items were missing from the changes introduced in commit
28ed798ce9:
- Add common/include/osx directory to libbladeRF include path
- Add common/osx/src/clock_gettime.c to libbladeRF build
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.
No need to use dummy variable with bladerf_init_stream as of commit
3e89a44f66.
Reduced default sample rate to 1 Msps to avoid timeouts on Hi-speed
connections.
BUILD_DOCUMENATION is now a top-level switch to turn on/off doc generation.
When BUILD_DOCUMENTATION=ON, individual components may be turned ON/OFF.
These default to the state of ${BUILD_DOCUMENTATION}.
- BUILD_LIBBLADERF_DOCUMENTATION (libbladeRF Doxygen docs)
- BUILD_BLADERF_CLI_DOCUMENTATION (bladeRF-cli man page)
- BUILD_BLADERF_FLASH_DOCUMENTATION (bladeRF-flash man page)
Moved LMS VGA range checks out of bladeRF.c into lms.c.
Replaced RXVGA1 calculations with lookup tables. (h/t to LazyDodo for
the suggestion.)
Corrected RXVGA1 enable/disable. Previously we were just setting the
bias current to 0, but it turns out there's an actual bit for this in
reserved register 0x7d.