uhd::stream_args_t Struct Reference

#include <uhd/stream.hpp>

Public Member Functions
	stream_args_t (const std::string &cpu="", const std::string &otw="")
	Convenience constructor for streamer args. More...

Public Attributes
std::string	cpu_format
std::string	otw_format
device_addr_t	args
std::vector< size_t >	channels

Detailed Description

A struct of parameters to construct a streamer.

Here is an example of how a stream args object could be used in conjunction with uhd::device::get_rx_stream():

// 1. Create the stream args object and initialize the data formats to fc32 and sc16:
uhd::stream_args_t stream_args("fc32", "sc16");
// 2. Set the channel list, we want 3 streamers coming from channels
//    0, 1 and 2, in that order:
stream_args.channels = boost::assign::list_of(0)(1)(2);
// 3. Set optional args:
stream_args.args["spp"] = "200"; // 200 samples per packet
// Now use these args to create an rx streamer:
// (We assume that usrp is a valid uhd::usrp::multi_usrp)
uhd::rx_streamer::sptr rx_stream = usrp->get_rx_stream(stream_args);
// Now, any calls to rx_stream must provide a vector of 3 buffers,
// one per channel.

Note: Not all combinations of CPU and OTW format have conversion support. You may however write and register your own conversion routines.

Constructor & Destructor Documentation

stream_args_t()

uhd::stream_args_t::stream_args_t ( const std::string &  cpu = "", const std::string &  otw = ""  )

inline

Convenience constructor for streamer args.

Member Data Documentation

args

device_addr_t uhd::stream_args_t::args

The args parameter is used to pass arbitrary key/value pairs. Possible keys used by args (depends on implementation):

• fullscale: specifies the full-scale amplitude when using floats. By default, the fullscale amplitude under floating point is 1.0. Set the "fullscale" to scale the samples in the host to the expected input range and/or output range of your application.
• peak: specifies a fractional sample level to calculate scaling with the sc8 wire format. When using sc8 samples over the wire, the device must scale samples (both on the host and in the device) to satisfy the dynamic range needs. The peak value specifies a fraction of the maximum sample level (1.0 = 100%). Set peak to max_sample_level/full_scale_level to ensure optimum dynamic range.
• underflow_policy: how the TX DSP should recover from underflow. Possible options are "next_burst" or "next_packet". In the "next_burst" mode, the DSP drops incoming packets until a new burst is started. In the "next_packet" mode, the DSP starts transmitting again at the next packet.
• spp: (samples per packet) controls the size of RX packets. When not specified, the packets are always maximum frame size. Users should specify this option to request smaller than default packets, probably with the intention of reducing packet latency.
• noclear: Used by tx_dsp_core_200 and rx_dsp_core_200

The following are not implemented, but are listed for conceptual purposes:

• function: magnitude or phase/magnitude
• units: numeric units like counts or dBm

In addition, all the transport-related options explained on Transport Notes can be set here. These options can be set either when creating the device (see also Device Configuration through address string), or when creating the streamer (when the options are given both times, the stream args take precedence):

• recv_frame_size
• send_frame_size
• num_recv_frames
• num_send_frames
• ups_per_sec
• ups_per_fifo
• recv_buff_fullness

Other options are device-specific:

• port, addr: Alternative receiver streamer destination.

channels

std::vector<size_t> uhd::stream_args_t::channels

The channels is a list of channel numbers. Leave this blank to default to channel 0 (single-channel application). Set channels for a multi-channel application. Channel mapping depends on the front-end selection (see also Specifying the Subdevice).

A very simple example is an X300 with two daughterboards and a subdev spec of A:0 B:0. This means the device has two channels available.

Setting stream_args.channels = (0, 1) therefore configures MIMO streaming from both channels. By switching the channel indexes, stream_args.channels = (1, 0), the channels are switched and the first channel of the USRP is mapped to the second channel in the application.

If only a single channel is used for streaming, stream_args.channels = (1,) would only select a single channel (in this case, the second one). When streaming a single channel from the B-side radio of a USRP, this is a more versatile solution than setting the subdev globally to "B:0".

cpu_format

std::string uhd::stream_args_t::cpu_format

The CPU format is a string that describes the format of host memory. Conversions for the following CPU formats have been implemented:

• fc64 - complex<double>
• fc32 - complex<float>
• sc16 - complex<int16_t>
• sc8 - complex<int8_t>

The following are not implemented, but are listed to demonstrate naming convention:

• f32 - float
• f64 - double
• s16 - int16_t
• s8 - int8_t

The CPU format can be chosen depending on what the application requires.

otw_format

std::string uhd::stream_args_t::otw_format

The OTW format is a string that describes the format over-the-wire. The following over-the-wire formats have been implemented:

• sc16 - Q16 I16
• sc8 - Q8_1 I8_1 Q8_0 I8_0
• sc12 (Only some devices)

The following are not implemented, but are listed to demonstrate naming convention:

• s16 - R16_1 R16_0
• s8 - R8_3 R8_2 R8_1 R8_0

Setting the OTW ("over-the-wire") format is, in theory, transparent to the application, but changing this can have some side effects. Using less bits for example (e.g. when going from otw_format sc16 to sc8) will reduce the dynamic range, and increases quantization noise. On the other hand, it reduces the load on the data link and thus allows more bandwidth (a USRP N210 can work with 25 MHz bandwidth for 16-Bit complex samples, and 50 MHz for 8-Bit complex samples).

---

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

• include/uhd/stream.hpp