This introduces a behavioural change in recv() (for RFNoC devices; older
devices are unaffected).
The behavioural changes depend on the way recv() was called:
- nsamps_per_buff > 0, timeout == 0: This is the busy-loop, or polling
use case. This is typically done in application that require best-case
latency.
- OLD CODE: Before this change, the streamer would artificially
increase the timeout value to 1ms (in order to increase the chance
of catching an overrun or late error).
- NEW CODE: After this change, the timeout of 0 is applied everywhere.
This means that if a timeout occurs while calling recv(), it is not
sufficient to call recv() again with a zero-timeout, zero-nsamps
value (see next case) to detect what error occurred.
- nsamps_per_buff == 0, timeout == 0: Within niuhd, this was used to
determine the error code if a regular call to recv() failed to
receive all expected samples. The assumption was that calling recv()
ones with these values (all zero) would suffice to figure out what the
problem was (i.e., if an overrun or other error had occurred). However,
this behaviour was never documented or declared to be valid!
- OLD CODE: In the old code, the timeout was artifically increased to
1ms, even if we would never process any packets. This was used to
force a short "sleep" of the recv call, which would increase the
chance that outstanding errors (overruns or lates) would be made
available to the recv() thread. However, if a timeout would occur,
then we would report back ERROR_CODE_NONE to the user, because they
were requesting zero samples anyway.
- NEW CODE: After the change, the timeout is not increased to 1ms any
longer, but the timeout-scrubbing behaviour is retained. Because we
don't artificially let the thread sleep, there is increased risk
of missing outstanding errors. If the intention was to always catch
those, call recv() with a non-zero timeout!
- nsamps_per_buff == 0, timeout > 0: This should be the right call to
"catch" any outstanding errors (overruns, lates) with an arbitrary
amount of waiting time.
- OLD CODE: Ironically, before this change, the code would fix the
timeout to 1ms, even if a bigger timeout was requested.
- NEW CODE: The desired timeout is applied, even though no packets
will be processed. This allows the call site, if they don't care
about latency, to increase the sleep duration to a safe margin.
- nsamps_per_buff > 0, timeout > 0: This is the normal streaming case,
and this remains unchanged.
On top of the changes to the RX streaming behaviour for RFNoC devices,
the documentation for recv() was made more detailed to better explain
the contract around recv().
Some background:
- In a2f10eed, a change was made to bump the minimum timeout to 1ms to
increase the chance that errors are propagated back the call site.
However, there was never a guarantee in the UHD API that recv() with
zero samples, zero timeout would return all errors.
- This change had the effect that recv() would return with
ERROR_CODE_TIMEOUT if nothing was available, which is also undesired.
So in 0382a1c, a change was made to fix the timeout to 1ms for
nsamps_per_buff == 0, regardless of the desired timeout.
This became possible with the new dependency on C++17, which added std::
gcm() and std::lcm(). The standard library has some advantages over our
version (e.g., constexpr) but most importantly, it allows us to remove
the (version dependent!) Boost dependency in math.hpp.
This breaks the public API: `uhd::math::{gcd,lcm}` were defined in the
public header uhd/utils/math.hpp.
- images: update manifest
- uhd: update changelog and version string
- debian: update changelog and installer version
Signed-off-by: Steven Koo <steven.koo@ni.com>
Recently, we released UHD v4.1.0.1, which addressed some bugs that found
their way into the UHD v4.1.0.0 release. While the changes that
addressed those bugs were made in the master branch, they were
cherry-picked into the UHD-4.1 branch, and the v4.1.0.1 release was made
from that branch. However, the version, manifest, and changelogs were
updated only in the UHD-4.1 branch, not in master. The effect of that is
that the current master (a.k.a. the absolute latest, perhaps unstable,
use-at-your-own-risk code) branch's version, manifest, and changelogs
still reflect the v4.1.0.0 release. Furthermore, the UHD documentation
refers to the manifest file in the master branch as the way to get (at
least) the most recent filesystem and FPGA artifacts. Not updating the
manifest in master renders that documentation inaccurate.
This commit updates those details in master to reflect the latest
v4.1.0.1 release artifacts, and updates the version of master to
4.2.0-git.
