Add TX Burst Functionality

[razorheadfx]

This adds TxStream::write_burst as a convenience function.

I reckon this requires some discussion since it is just a wrapper for setting the stream flags on the TxStream object for burst transmission and then calling writeStream and not a function included in the Soapy API in itself.

This also assumes the blocking behaviour of SoapyUHD (line 722 onward) also applies to all other drivers/plugins. Unfortunately I only have access to UHD devices and not enough time to go source diving in the other plugins right now to verify this.

[kevinmehall]

I would like to also add support for the functionality of theflags field on the streaming read/write API at some point, but I like the idea of a convenience function for bursts.

This also assumes the blocking behaviour of SoapyUHD (line 722 onward) also applies to all other drivers/plugins.

That "UHDSoapy" file adapts a UHD API caller to use a Soapy device and is not the other way around. So the presence of that loop implies that the Soapy API can't be relied on to transmit the entire buffer in one call. The code that would be used to drive a USRP from this library is "SoapyUHD".

As this is a convenience function, I think it would be reasonable to have a loop to ensure the entire buffer is written.

[kevinmehall]

activateStream for TX is a no-op in SoapyUHD, but from what I can tell, the stream must be active to send a burst on other drivers. On many drivers, activateStream is somewhat expensive (launching threads), so this should probably document that the stream needs to be active rather than activating and deactivating for every burst.

[razorheadfx]

Summing up for now

TODOs

• make the timespec on write_burst an option and update flags accordingly
• use local variable flags for burst convenience method and check them against error codes afther the SoapySDR_writeStream call returns
• remove SOAPY_SDR_TX and (optionally type alias SOAPY_SDR_TX and SOAPY_SDR_RX so they are indicated as something other than streamflags)
• add loop to write_burst to ensure entire buffer is tx'ed in one blocking call
• longterm: check flag handling in other soapy wrappers and come up with a proper soution for the flags

Did I miss anything?

[kevinmehall]

use local variable flags for burst convenience method and check them against error codes afther the SoapySDR_writeStream call returns

Not sure what you mean by the error handling part. The error codes are in the return value, not the flags param. None of the flags are documented as being returned by a write, though some drivers clear flags under various conditions.

Other than that, sounds good to me. Thanks!

longterm: check flag handling in other soapy wrappers and come up with a proper soution for the flags

I added some notes on the rest of the flags and RX bursts on a new issue #6.

[razorheadfx]

Updates and rebased onto the new master. Added a few debug helpers and updated docs. Also tested with a B210.

Any thoughts?

update: tested with x310 for these devices soapy writes the whole burst in one call.

[kevinmehall]

Looks good. I'll test with a LimeSDR and HackRF tomorrow to see how those assumptions hold.

[kevinmehall]

• Works on B200

• Works on HackRF, but requires activateStream, ignores the timestamps (as expected, no hardware support), and hits both of your debug!()s:

  write_burst: Expected reset flags (0), encountered flag code 6
  write_burst: Expected reset flags (0), encountered flag code 2
  write_burst: Expected reset flags (0), encountered flag code 2
  write_burst: Expected reset flags (0), encountered flag code 2
  write_burst: required 4 calls to write burst of length 500000

• Works on LimeSDR, but not super reliably. (LimeSDR TX has always been buggy for me) Requires activateStream and also requires the RX channel to have its sample rate set and stream activated for timestamps to work.

Test code

[kevinmehall]

Merged, but I redesigned the API with #6 in mind to separate the flags from the loop behavior:

pub fn write(
    &mut self,
    buffers: &[&[E]],
    at_ns: Option<i64>,
    end_burst: bool,
    timeout_us: i64
) -> Result<usize, Error>

pub fn write_all(
    &mut self,
    buffers: &[&[E]],
    at_ns: Option<i64>,
    end_burst: bool,
    timeout_us: i64
) -> Result<(), Error>

Your write_burst is write_all with end_burst set to true. Let me know what you think of that design.

Thanks!

[razorheadfx]

Not what I had in mind but definitely cleaner, considering it could be used for things other than burst. And its a lot rustier :+1: Thank you!