/*! \page page_configuration Configuring Devices and Streamers

\section config_devaddr Device Configuration through address string

The address string for a device is mainly used to identify a device
(see also \ref page_identification), but it can also be used to propagate
settings to the device.

As an example, say you run `rx_samples_to_file` with the following settings:

    $ rx_samples_to_file --args type=b200,master_clock_rate=16e6

This will first use the `type` flag to search your system for connected B200
or B210 devices, as described on \ref page_identification. Once it has found
one of these, it will connect to it and pass the `master_clock_rate=16e6` option
to the device initialization (in this case, it will set the master clock rate
to 16 MHz as described on \ref b200_mcr).

The following table lists common configuration options you can pass as device
arguments. Also check out the individual device manuals for more information
and possible more options, as individual devices may have more specialized
options available not listed here.

 Key                 | Description                                                                  | Supported Devices | Example Value
---------------------|------------------------------------------------------------------------------|-------------------|---------------------
 blank_eeprom        | *Caution!* Having this key will erase the EEPROM and can damage your device! | X3x0              | blank_eeprom=1
 fpga                | Provide alternative FPGA bitfile                                             | All USB Devices, X3x0 (PCIe only), E310, E1x0 | fpga=/path/to/bitfile.bit
 fw                  | Provide alternative firmware                                                 | All USB Devices, X3x0 | fw=/path/to/fw.bin
 ignore-cal-file     | Ignores existing device calibration files                                    | All Devices with cal-file support| See \ref ignore_cal_file
 master_clock_rate   | Master Clock Rate in Hz                                                      | X3x0, X4x0, B2x0, B1x0, E3xx, E1x0, N3xx | master_clock_rate=16e6
 dboard_clock_rate   | Daughterboard clock rate in Hz                                               | X3x0               | dboard_clock_rate=50e6
 system_ref_rate     | Frequency of external reference in Hz                                        | X3x0               | system_ref_rate=11.52e6
 mcr                 | Override master clock rate settings (see \ref usrp1_hw_extclk)               | USRP1              | mcr=52e6
 niusrprpc_port      | RPC Port for NI USRP RIO                                                     | X3x0               | niusrprpc_port=5445
 self_cal_adc_delay  | Run ADC transfer delay self-calibration.                                     | X3x0               | self_cal_adc_delay=1
 ext_adc_self_test   | Run an extended ADC self test (more than the usual)                          | X3x0               | ext_adc_self_test=1
 recover_mb_eeprom   | Disable version checks. Can damage hardware. Only recommended for recovering devices with corrupted EEPROMs. | X3x0 | recover_mb_eeprom=1
 serialize_init      | Force serial initialization of motherboards (default is parallel)            | X3x0, all MPM devices | serialize_init=1
 force_reinit        | Force reinitialization of device                                             | N3x0, X4x0         | force_reinit=1
 force_mtu           | Skip MTU detection and use this value instead. Warning: can cause issues if MTU value is not valid! | X3x0, E3x0, N3x0, X4x0 | force_mtu=8000

Notes:
- The `force_mtu` argument is only recommended in rare cases where
  auto-detection of the MTU fails because of a restrictive network
  configuration. Note that it is generally preferable to set a per-link MTU
  using the `mtu` stream argument (see \ref page_transport for details).

In addition, many of the streaming-related options can be set per-device at configuration time.
See \ref config_stream_args and \ref page_transport for more details.

\section config_subdev Specifying the Subdevice

A subdevice specification (or "subdev spec") string for USRP family devices is composed of:

    <motherboard slot name>:<daughterboard frontend name>

Ex: The subdev spec markup string to select a WBX on slot B.

    B:0

Ex: The subdev spec markup string to select a BasicRX on slot B (on USRP2/N200 devices only).

    B:AB

    -- OR --

    B:A

    -- OR --

    B:B

A subdev spec can consist of multiple strings if a motherboard has the option
for more than one radio device. In the X300, you may have an SBX in slot A and
a CBX in slot B. Both of these daughterboards have one frontend ("0"), so the
subdev spec to configure both these radio channels would look like this:

    A:0 B:0

The individual subdev specs are separated by spaces. On some devices, such as the
X300 or the B200, it is possible to swap these to hint that slot B should be the
first radio ("channel 0") and slot A should be the second radio ("channel 1"):

    B:0 A:0

On devices with more than one radio, setting the subdev spec to a single value
declares that the other radio is not used. In a configuration with multiple USRPs,
this means that this device will only be assigned a single channel.

Note that a subdev spec string always only pertains to a *single* USRP, even if
multiple USRPs are configured to run together. For such a configuration, you set
a subdev spec string for every device individually.

\subsection config_subdev_slotnames USRP Family Motherboard Slot Names

All USRP family motherboards have a first slot named **A:**. The USRP1 and X3x0
have two daughterboard subdevice slots, known as **A:** and **B:**.

The B210 series have a different configuration, since their two radios
are logically connected to the same "daughterboard" (which is in reality the
integrated AD9361), but different frontends.
To select both radios on a B200, use this string:

    A:A A:B

\subsection config_subdev_default USRP Family Motherboard Slot Names

\subsection config_subdev_dbnames Daughterboard Frontend Names

Daughterboard frontend names can be used to specify which signal path is
used from a daughterboard. Most daughterboards have only one frontend `:0`.
A few daughterboards (Basic, LF and TVRX2) have multiple
frontend names available. The frontend names are documented in \ref page_dboards.

\section config_stream_args Streaming Arguments (Stream Args)

When initializing a streamer using `uhd::device::get_tx_stream()` and/or
`uhd::device::get_rx_stream()`, you must specify a `uhd::stream_args_t` object
to configure the streamers. See the manual for this struct and an in-depth
explanation of the individual components.

The `uhd::stream_args_t` object consists of four components:

-   The CPU data format (`cpu_format`)
-   The over-the-wire data format (`otw_format`)
-   A collection of implementation-specific key/value pairs used to pass
    additional information to the streamers (`args`)
-   A list of channel numbers for setting channel mapping (`channels`)

\subsection config_stream_args_cpu_format CPU Data Format Specification

The CPU data format is a string that describes the format of the sample data
in host memory. When the client application calls `recv()` on an instance of
`uhd::rx_streamer` or `send()` on an instance of `uhd::tx_streamer`, the
samples are returned or expected to be provided in this format. The client
application is free to choose whichever CPU data format best meets its
particular needs.

Conversions for the following CPU formats have been implemented:

String | Corresponding C++ type    | Notes
-------|---------------------------|--------------------------------------------
`fc64` | `std::complex<double>`    | Complex-valued double-precision data
`fc32` | `std::complex<float>`     | Complex-valued single-precision data
`sc16` | `std::complex<int16_t>`   | Complex-valued signed 16-bit integer data
`sc8`  | `std::complex<int8_t>`    | Complex-valued signed 8-bit integer data
`f32`  | `float`                   | Single-precision data
`s16`  | `int16_t`                 | Signed 16-bit integer data
`s8`   | `int8_t`                  | Signed 8-bit integer data

\subsection config_stream_args_otw_format Over-the-wire Data Format Specification

The over-the-wire (OTW) data format is a string that describes the format of
the sample data as it is carried across the transport to and from the RFNoC
stream endpoint associated with the stream. 

The table below shows which OTW formats are supported by each device.
String | Supporting Devices                        | 
-------|-------------------------------------------|
`fc32` | `B2xx`                                    |
`sc16` | `B2xx, N2xx, N3xx, E3xx, X3xx, X4xx`      |
`sc12` | `B2xx`                                    |
`sc8`  | `B2xx, N2xx`                              |

Note that the in-tree RFNoC blocks that are provided with UHD only support sc16 for complex-valued data.

The following over-the-wire
formats are supported. In the following, data carried over the wire for each
format is denoted by the data type (`i8`, `i16`, etc.), which part of the
sample is represented (`I` for in-phase portion, `Q` for quadrature portion,
or `R` for a real value), and the sample index in square brackets.

- `sc16`
<table><tr><td> `i16 Q[n]` </td><td> `i16 I[n]`</td><td> `i16 Q[n+1]`</td><td> `i16 I[n+1]`</td> ... </td></tr></table>
- `sc8`
<table><tr><td> `i8 Q[n+1]` </td><td> `i8 I[n+1]` </td><td> `i8 Q[n]` </td><td> `i8 I[n]` </td><td> `i8 Q[n+3]` </td><td> `i8 I[n+3]` </td><td> `i8 Q[n+2]` </td><td> `i8 I[n+2]` </td><td> ... </td></tr></table>
- `sc12`
- `s16`
<table><tr><td> `i16 R[n+1]` </td><td> `i16 R[n]` </td><td> `i16 R[n+3]` </td><td> `i16 R[n+2]` </td><td> ... </td></tr></table>
- `s8`
<table><tr><td> `i8 R[n+3]` </td><td> `i8 R[n+2]` </td><td> `i8 R[n+1]` </td><td> `i8 R[n]` </td><td> `i8 R[n+7]` </td><td> `i8 R[n+6]` </td><td> ... </td></tr></table>

As UHD will convert samples between the CPU and over-the-wire data formats
automatically, setting the OTW format should, in theory, be transparent to
the application. However, changing the OTW format can have side effects.
For example, using an OTW format with fewer bits (`sc8` vs. `sc16`, for
instance) reduces the load on the data link and allows more bandwidth, but
also reduces the dynamic range of the data and increases quantization noise.

\subsection config_stream_args_args Additional Stream Arguments

Additional implementation-dependent stream arguments may be provided as
key/value pairs to a streamer via the `args` parameter. These settings control
the behavior of the stream under various conditions.  Note that the value
specified for the key should be in string format, e.g.

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.cpp}
my_stream_args.args["spp"] = std::to_string(10000);
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

The following parameters are supported:

- `spp`: The `spp` (samples per packet) option controls the size of receive
  packets. When not specified, the packets are always the maximum frame
  size that can pass through the graph given the MTU (maximum transmission
  unit). Using a smaller value for `spp` may reduce packet latency through
  a graph.
- `underflow_policy` (applies to B100, B2xx and N2xx devices only): This option
  controls how the TX DSP should recover from an underflow condition.
  The following options are supported:
  - `next_burst`: The DSP will drop incoming packets until a new burst has
    started.
  - `next_packet`: The DSP will begin transmitting again upon reception of
    the next packet.
  - `wait`: (B2xx and N2xx only) The DSP will not transmit until reset.
- `fullscale`: (applies to B100, B2xx and N2xx devices only) This option
  specifies the full-scale amplitude when using floats. By default, the
  fullscale amplitude with floating point values is 1.0. Clients can scale the
  samples on the host to the expected input and/or output range of their
  application by changing this value.
- `peak`: (applies to B100, B2xx and N2xx devices only) This option specifies
  a fractional sample level to calculate when scaling using the `sc8`
  over-the-wire format. When using `sc8` samples over the wire, samples must
  be scaled both on the host and in the device to satisfy dynamic range needs.
  The peak value specifies a fraction of the maximum sample level (1.0 =
  100%). Set peak to the maximum sample level divided by the full scale
  level to ensure optimum dynamic range.
- `noclear` (applies to B100 and N2xx only)
- `port` and `addr` (N2xx only) These settings specify an alternate receiver
  streamer destination.
- `streamer` Specify the type of streamer to use.  "replay_buffered" (applies
  to RFNoC enabled devices with a Replay block in the FPGA image) Adds data
  buffering in DRAM using the Replay block for TX streamers when using the
  multi_usrp API.
- `throttle` Specify the throttle of the streamer in order to limit its rate.
  This is for RFNoC-compatible devices starting in UHD 4.5. It is set as a
  ratio in the range (0, 1] or a percentage in the range (0%, 100%]. For
  example, use `100%` or `1.0` for maximum rate, and `50%` or `0.5` for half
  the maximum rate. Note that other factors may affect the actual rate, such
  as the rate of the source or the speed supported by the transport.
- `transmit_policy` Specify transmit policy of TX streamer (RFNoC devices
  only). When set to `stop_on_seq_error` the TX streamer requires an FPGA
  image that supports this mode. If supported, the FPGA will be instructed
  to stop processing sample if a sequence error is detected. The send call
  of the TX streamer will exit ASAP an return the so far transmitted samples.
  This might be more then the downstream blocks have processed. Before restart
  the transmission it is up to the user logic to decide which samples might
  need to be resend. The TX streamer send call will automatically reset
  the FPGA state to reenable transmission. Note this mode is only useful
  for non time critical transmission (e.g. sending samples to the replay
  block).
- `mtu` (applies to RFNoC devices only): Overrides the MTU value for this
  streamer, ignoring limits from the underlying link.


\subsubsection config_stream_args_transport Transport-related Stream Arguments

The following arguments that alter the behavior of the underlying transport
are normally passed to the USRP device as initialization-time arguments
(see \ref config_devaddr):

- `num_send_frames`
- `num_recv_frames`
- `send_frame_size`
- `recv_frame_size`
- `send_buff_size`
- `recv_buff_size`

However, for MPMD-based and X3x0 devices, these parameters may also be
specified in the stream arguments. When one of these parameters is passed
via the stream arguments, they override any value specified in the device
arguments. See \ref page_transport for more information on the meaning of
these parameters and their default values.


\subsection config_stream_args_channels Channels

The `uhd::stream_args_t` object allows the specification of a list of
channel numbers mapping device channels to the stream. When left unset, the
stream defaults to channel 0 (i.e., single-channel operation). For a multi-
channel application, this list specifies the mapping of device channels to
the data in the stream. Channel mapping also depends on the front-end
selection (see also \ref config_subdev).

Consider an X300 with two daughterboards and a subdev spec of
`A:0 B:0`. This means the device has two channels available. Here are some
simple examples of channel mappings with subdev specs:

- Setting `stream_args.channels = {0, 1}` configures time-aligned streaming
  from both channels. The first channel in the stream will be mapped to first
  subdev spec (`A:0`) and the second channel will be mapped to the mapped to
  the second subdev spec (`B:0`).
- Switching the channel indices (e.g., `stream_args.channels = {1, 0}`)
  results in the switching of the order of the channels in the stream. The
  first channel of the stream is mapped to the second subdev spec while the
  second channel of the stream is mapped to the first subdev spec.
- If only a single channel is specified (e.g., `stream_args.channels = {1}`),
  the stream will only consist of a single channel of data from the second
  subdev spec. 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`.

\section config_mpm Device Configuration through MPM configuration files

For more detail on how MPM is configured, see also \ref configfiles_usrps_mpm.

The following key/value pairs are understood:

 Key                 | Description                                                                  | Supported Devices | Example Value
---------------------|------------------------------------------------------------------------------|-------------------|---------------------
 enable_gps          | Enable/disable power to the GPSDO (can be overridden by UHD on E320).        | N3xx, E320        | enable_gps=0
 enable_fp_gpio      | Enable/disable power to the front-panel GPIOs.                               | N3xx, E320        | enable_fp_gpio=0
 skip_boot_init      | Don't init the device during MPM boot, but on the first UHD run.             | N3xx              | skip_boot_init=1
 clock_source        | Default clock source for this device (can be overridden by UHD).             | N3xx, E320, E31x  | clock_source=external
 time_source         | Default time source for this device (can be overridden by UHD).              | N3xx, E320, E31x  | time_source=external
 rx_lo_source        | Default source for the RX LO (can be overridden by UHD).                     | N310              | rx_lo_source=external
 tx_lo_source        | Default source for the TX LO (can be overridden by UHD).                     | N310              | tx_lo_source=external
 pps_export          | Default PPS export value (can be overridden by UHD).                         | N3xx              | pps_export=0
 forward_eth         | Set forwarding policy for Ethernet packets                                   | N3xx              | forward_eth=1
 forward_bcast       | Set forwarding policy for broadcast packets                                  | N3xx              | forward_bcast=1
 no_reload_fpga      | Don't load an idle image after session terminates                            | E31x              | no_reload_fpga=1
 master_clock_rate   | Default master clock rate (can be overridden by UHD)                         | N3xx, E320, E31x  | master_clock_rate=1e6

*/
// vim:ft=doxygen:
