| USRP Hardware Driver and Device Manual Version: 4.10.0.0 UHD and USRP Manual |

Loading...
Searching...
No Matches
uhd::rx_streamer Class Referenceabstract

`#include <uhd/stream.hpp>`

Inheritance diagram for uhd::rx_streamer:

## Detailed Description

The RX streamer is the host interface to receiving samples. It represents the layer between the samples on the host and samples inside the device's receive DSP processing.

## Public Types
typedef std::shared_ptr< rx_streamer > | sptr
typedef ref_vector< void * > | buffs_type
| Typedef for a pointer to a single, or a collection of recv buffers.

## Public Member Functions
virtual | ~rx_streamer (void)
virtual size_t | get_num_channels (void) const =0
| Get the number of channels associated with this streamer.
virtual size_t | get_max_num_samps (void) const =0
| Get the max number of samples per buffer per packet.
virtual size_t | recv (const buffs_type &buffs, const size_t nsamps_per_buff, rx_metadata_t &metadata, const double timeout=0.1, const bool one_packet=false)=0
virtual void | issue_stream_cmd (const stream_cmd_t &stream_cmd)=0
virtual void | post_input_action (const std::shared_ptr< uhd::rfnoc::action_info > &action, const size_t port)=0

## Member Typedef Documentation

## ◆ buffs_type

typedef ref_vector<void*> uhd::rx_streamer::buffs_type

Typedef for a pointer to a single, or a collection of recv buffers.

## ◆ sptr

typedef std::shared_ptr<rx_streamer> uhd::rx_streamer::sptr

## Constructor & Destructor Documentation

## ◆ ~rx_streamer()

virtual uhd::rx_streamer::~rx_streamer | ( | void |  | ) |
| virtual

## Member Function Documentation

## ◆ get_max_num_samps()

virtual size_t uhd::rx_streamer::get_max_num_samps | ( | void |  | ) | const
| pure virtual

Get the max number of samples per buffer per packet.

## ◆ get_num_channels()

virtual size_t uhd::rx_streamer::get_num_channels | ( | void |  | ) | const
| pure virtual

Get the number of channels associated with this streamer.

## ◆ issue_stream_cmd()

virtual void uhd::rx_streamer::issue_stream_cmd | ( | const stream_cmd_t & | stream_cmd | ) |
| pure virtual

Issue a stream command to the usrp device. This tells the usrp to send samples into the host. See the documentation for stream_cmd_t for more info.

With multiple devices, the first stream command in a chain of commands should have a time spec in the near future and stream_now = false; to ensure that the packets can be aligned by their time specs.

Parameters

  stream_cmd | the stream command to issue

## ◆ post_input_action()

virtual void uhd::rx_streamer::post_input_action | ( | const std::shared_ptr< uhd::rfnoc::action_info > & | action,
|  | const size_t | port )
| pure virtual

Post an action to the input edge of the Streamer.

Parameters

  action | shared pointer to the corresponding action_info request
  port | the port to which to post the action

## ◆ recv()

virtual size_t uhd::rx_streamer::recv | ( | const buffs_type & | buffs,
|  | const size_t | nsamps_per_buff,
|  | rx_metadata_t & | metadata,
|  | const double | timeout = 0.1,
|  | const bool | one_packet = false )
| pure virtual

Receive buffers containing samples described by the metadata

This is the main streaming API call for receiving samples from any USRP. It will block and receive any incoming data from the device into the user-provided buffers (`buffs`) until one of the following conditions is met:

- The number of samples (or items) received equals `nsamps_per_buff`, i.e., the buffers have been completely filled. In this case, the return value of recv() equals `nsamps_per_buff`.
- An end-of-burst packet was received. When this is the case, recv() will immediately return, and assert the `end_of_burst` flag in the RX metadata.
- A timeout occurs, cf. Timeouts
- If `one_packet` is set, then it will return as soon as one single packet was received. It will attempt to return all the samples from the packet that was processed.
- A sequence error is detected (i.e., packets were dropped on the way to the host computer). In particular for Ethernet-based devices, this may occur if UDP packets get dropped. In this case, an error code is set in the metadata object.
- An invalid packet is received. `metadata.error_code` is set to `ERROR_CODE_BAD_PACKET`.
- For multi-channel streamers, if the streamer was not able to get time-aligned samples from every channel, it will eventually give up and set `metadata.error_code` to `ERROR_CODE_ALIGNMENT`.
- An overrun is detected. This is the case when the software is calling recv() too slowly, and the device or transport buffers are backing up. In this case, samples may be dropped and an overrun condition is reported via the RX metadata. Depending on the device and streaming mode, the hardware may continue to produce samples (e.g., in continuous streaming) or may pause/stop until reconfigured. However, recv() may not immediately return whan an overrun is detected; for more details, cf. Error Handling

Note that in many of these scenarios, the actual number of samples received is smaller than the number of samples requested. The precise number of samples that were received before the function returned is relayed as the return value of recv().

The `one_packet` option allows the user to guarantee that the call will return after a single packet has been processed. This may be useful to maintain packet boundaries in some cases.

# Fragmentation

If the buffer has insufficient space to hold all samples that were received in a single packet over-the-wire, then the buffer will be completely filled and the implementation will hold a pointer into the remaining portion of the packet. Subsequent calls will load from the remainder of the packet, and will flag the metadata to show that this is a fragment. The next call to receive, after the remainder becomes exhausted, will perform an over-the-wire receive as usual. See the rx metadata fragment flags and offset fields for details.

# Thread Safety

Note on threading: recv() is not thread-safe, to avoid locking overhead. The application calling recv() is responsible for making sure that not more than one thread can call recv() on the same streamer at the same time. If there are multiple streamers, receiving from different sources, then those may be called from different threads simultaneously.

# Error Handling

`metadata` is a value that is set inside this function (effectively, a return value), and should be checked for potential error codes (see rx_metadata_t::error_code_t).

The most common error code when something goes wrong is an overrun (also referred to as overflow: error_code_t::ERROR_CODE_OVERFLOW). This error code means that the device produced data faster than the application could read, and various buffers filled up leaving no more space for the device to write data to. Note that an overrun on the device will not immediately show up when calling recv(). Depending on the device implementation, there may be many more valid samples available before the device had to stop writing samples to the FIFO. Only when all valid samples are returned to the call site will the error code be set to "overrun". When this happens, all valid samples have been returned to application where recv() was called. If the device is streaming continuously, it will reset itself when the FIFO is cleared, and recv() can be called again to retrieve new, valid data.

# Timeouts

The recv() call has a timeout parameter. This parameter is used to limit the time the call will block. If no data is available within the timeout period, the call will return with an error code of error_code_t::ERROR_CODE_TIMEOUT. This is not necessarily an error condition, but can occur naturally, for example if the upstream source produces data in a bursty fashion.

An important fact about the timeout parameter is that it is not a total timeout value, but is applied to every single call within recv() that uses a timeout. This means that the total time recv() can block can be significantly larger than the timeout parameter passed to recv().

When the timeout is set to zero, recv() will attempt to return as fast as possible, to minimize latency. This is useful when the application polls for data in a busy loop. However, note that in this case, it is possible that the call will return with an error code of timeout, even though a different error condition occurred, but has not been fully processed. It is therefore not sufficient to call recv() with a timeout of zero to check for any outstanding error conditions.

# Calling recv() with nsamps_per_buff = 0

It is not forbidden to call recv() with nsamps_per_buff = 0, and this can be useful to retrieve metadata only. In this case, the call will still apply the timeout value internally (which means the recv() call will wait at least for the timeout value for any incoming data, even though it won't be processed). However, the call will never return an error code of ERROR_CODE_TIMEOUT, as no data is expected to be processed.

The following code snippet demonstrates how to call recv() with a zero number of samples to retrieve metadata only:

// Note: timeout > 0, and num_samps_expected > 0. In this example, we
// expect buffs to be filled.
int num_samps_rcvd = rx_streamer->recv(
buffs, num_samps_expected, metadata, timeout);
if (num_samps_rcvd < num_samps_expected &&
(metadata.error_code == error_code_t::ERROR_CODE_NONE ||
metadata.error_code == error_code_t::ERROR_CODE_TIMEOUT)) {
// If we reach this point, we assume that an error occurred, but we
// don't know what it was.
// Note the zero-value for nsamps_per_buff:
rx_streamer->recv(buffs, 0, metadata, timeout);
// Now metadata.error_code will contain the actual error code,
// if it was received within timeout.
}
uhd::rx_streamer
Definition stream.hpp:170
uhd::rx_streamer::recv
virtual size_t recv(const buffs_type &buffs, const size_t nsamps_per_buff, rx_metadata_t &metadata, const double timeout=0.1, const bool one_packet=false)=0

Parameters

  | buffs | a vector of writable memory to fill with samples
  | nsamps_per_buff | the size of each buffer in number of samples
  [out] | metadata | data to fill describing the buffer
  | timeout | the timeout in seconds to wait for a packet
  | one_packet | return after the first packet is received

Returns
  the number of samples received or 0 on error

The documentation for this class was generated from the following file:

- stream.hpp