diff options
| -rw-r--r-- | host/docs/configuration.dox | 109 | ||||
| -rw-r--r-- | host/docs/devices.dox | 8 | ||||
| -rw-r--r-- | host/docs/general.dox | 34 | ||||
| -rw-r--r-- | host/docs/identification.dox | 20 | ||||
| -rw-r--r-- | host/docs/multiple.dox | 99 | ||||
| -rw-r--r-- | host/docs/transport.dox | 5 | ||||
| -rw-r--r-- | host/docs/usrp_e3x0.dox | 4 | ||||
| -rw-r--r-- | host/docs/usrp_x3x0.dox | 13 | ||||
| -rw-r--r-- | host/include/uhd/stream.hpp | 66 |
9 files changed, 306 insertions, 52 deletions
diff --git a/host/docs/configuration.dox b/host/docs/configuration.dox new file mode 100644 index 000000000..e16d1979e --- /dev/null +++ b/host/docs/configuration.dox @@ -0,0 +1,109 @@ +/*! \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 the configuration options you can pass as device +arguments. Also check out the individual device manuals for more information +and possible more options. + + 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), All embedded devices | 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, B2x0, B1x0, E3x0, E1x0 | master_clock_rate=16e6 + 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 + system_ref_rate | Reference Clock Rate in Hz | X3x0 | system_ref_rate=10e6 + + +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. + + 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 and E310 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 or an E300, 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 (see the manual for this struct and an in-depth +explanation of the individual components). + +*/ +// vim:ft=doxygen: diff --git a/host/docs/devices.dox b/host/docs/devices.dox index 295cd999f..a494302b1 100644 --- a/host/docs/devices.dox +++ b/host/docs/devices.dox @@ -2,8 +2,10 @@ ## General Usage Manuals -\li \subpage page_general "Notes on tuning, subdev specs, overflow/underflow, other miscellaneous topics" +\li \subpage page_general "Notes on tuning, overflow/underflow and other miscellaneous topics" \li \subpage page_identification +\li \subpage page_configuration +\li \subpage page_multiple \li \subpage page_images \li \subpage page_transport \li \subpage page_sync @@ -11,7 +13,7 @@ ## USRP N-Series Devices -\li \subpage page_usrp2 +\li \subpage page_usrp2 "USRP N2x0 Series" ## USRP B-Series Devices @@ -30,7 +32,7 @@ ## USRP Legacy Series -\li \subpage page_usrp2 +\li \ref page_usrp2 "USRP2 Series" ## Daughterboards diff --git a/host/docs/general.dox b/host/docs/general.dox index 1da284057..e4ffcfb6e 100644 --- a/host/docs/general.dox +++ b/host/docs/general.dox @@ -78,40 +78,6 @@ second). usrp->issue_stream_command(...); ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -\section general_subdev Specifying the Subdevice to Use - -A subdevice specification 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. - - B:AB - - -- OR -- - - B:A - - -- OR -- - - B:B - -\subsection general_subdev_slotnames USRP Family Motherboard Slot Names - -All USRP family motherboards have a first slot named **A:**. The USRP1, the X3x0 -and the B210 have two daughterboard subdevice slots, known as **A:** and **B:**. - -\subsection general_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 general_ounotes Overflow/Underflow Notes <b>Note:</b> The following overflow/underflow notes do not apply to USRP1, diff --git a/host/docs/identification.dox b/host/docs/identification.dox index 4ecb5c23d..7bacfea99 100644 --- a/host/docs/identification.dox +++ b/host/docs/identification.dox @@ -10,19 +10,23 @@ devices. Most UHD utility applications and examples have an `--args` parameter that takes a device address, which is expressed as a delimited string. -See device_addr.hpp for reference. +See uhd::device_addr_t for reference. + +Note that the device "address" can also take configuration options. +See \ref page_configuration for a list of those options. \subsection id_identifying_common Common device identifiers Every device has several ways of identifying it on the host system: -Identifier | Key | Notes | Example ------------|----------|-----------------------------------------------------------|--------------------------------- -Serial | serial | globally unique identifier | 12345678 -Address | addr | unique identifier on a network | 192.168.10.2 -Resource | resource | unique identifier for USRP RIO devices (over PCI Express) | RIO0 -Name | name | optional user-set identifier | my_usrp1 (User-defined value) -Type | type | hardware series identifier | usrp1, usrp2, b200, x300, ... +Identifier | Key | Notes | Example +------------------|----------|-----------------------------------------------------------|--------------------------------- +Serial # | serial | globally unique identifier | 12345678 +IP Address | addr | unique identifier on a network | 192.168.10.2 +Resource | resource | unique identifier for USRP RIO devices (over PCI Express) | RIO0 +Name | name | optional user-set identifier | my_usrp1 (User-defined value) +Type | type | hardware series identifier | usrp1, usrp2, b200, x300, ... +Vendor/Product ID | vid,pid | For USB devices. Both must be provided | vid=0x04b4,pid=0x8613 \subsection id_identifying_cmdline Device discovery via command line diff --git a/host/docs/multiple.dox b/host/docs/multiple.dox new file mode 100644 index 000000000..6a07ba8f5 --- /dev/null +++ b/host/docs/multiple.dox @@ -0,0 +1,99 @@ +/*! \page page_multiple Multiple USRP configurations + +\tableofcontents + +\section multiple_intro Introduction + +Some USRP devices are capable of being grouped to form a single, virtual device. +A single uhd::usrp::multi_usrp instantiation can control such a compound of devices. + +Currently, the following devices support this capability: + +- USRP2 / N2x0 Series +- X3x0 Series + +Note that only USRPs of the same type can be combined. + +\section multiple_setup Setting up devices + +A description of a multiple-USRP setup can be found on the respective device's manual pages. + +Addressing of a compound of devices is done by listing multiple addresses, e.g.: + + addr0=192.168.10.2,addr1=192.168.20.2 + +\section multiple_channumbers Channel and Device Numbering + +Assume we have combined 2 X310 USRPs into a single multi_usrp using the address string +given above, maybe using the following command: + +\code{.cpp} +uhd::device_addr_t args("addr0=192.168.10.2,addr1=192.168.20.2"); +uhd::usrp::multi_usrp::sptr usrp = uhd::usrp::multi_usrp::make(args); +\endcode +Some uhd::usrp::multi_usrp commands require passing a device index. This is simply +the index in the address list, so say we want to check the master clock rate on both +devices, this would be valid: +\code{.cpp} +double mcr0 = usrp->get_master_clock_rate(0); +double mcr1 = usrp->get_master_clock_rate(1); +\endcode + +Some methods default to applying to all devices, so the following command +would set the time on all devices to zero: +\code{.cpp} +usrp->set_time_next_pps(uhd::time_spec_t(0)); +\endcode + +So, device indexes run from 0 to N-1 where N is the number of devices. + +Channels are indexed in a similar way. Channel indexes run from 0 to M-1 where +M is the total number of channels on all devices. + +The number and order of channels per device depends on the subdev spec (see +also \ref config_subdev). In the current example, assume all the X310 USRPs +are using their standard configuration, and all have two daughterboards inside. + +In this case channels 0 and 1 map to slot A and B of the first USRP, respectively. +Channels 2 and 3 map to slots A and B of the second USRP, and so on. + +However, by changing the subdev spec on individual devices, this can change. +Say we have this unusual piece of code next: + +\code{.cpp} +usrp->set_rx_subdev_spec("A:0 B:0", 0); +usrp->set_rx_subdev_spec("A:0", 1); +usrp->set_rx_subdev_spec("B:0 A:0", 2); +\endcode + +The first device uses the default configuration. The second device artificially +disables slot B, giving this USRP a single channel only. The third device uses +both devices, but flips their order. + +Now, there's a total of 5 channels, mapped as: +- Channel 0: Slot A of Device 0 +- Channel 1: Slot B of Device 0 +- Channel 2: Slot A of Device 1 +- Channel 3: Slot A of Device 2 +- Channel 1: Slot B of Device 2 + +While valid, this kind of configuration is not recommended unless heavily +documented. It is usually simplest to call `set_rx_subdev_spec()` without +a device index, which will set the same subdev spec on all devices. +This assumes all devices have a similar daughterboard configuration + +\section multiple_mimo MIMO Operation + +When a multi-channel streamer is generated from a compound multi_usrp, and +a streamer with multiple channels is generated, MIMO operations is automatically +chosen. This means samples will be aligned between streams automatically. + +In order for this to work, all devices must use a common time and frequency +reference. This can be achieved in different ways, e.g. by daisy-chaining +devices (for a small number of X-Series devices), using the MIMO cable (when +only 2 N2x0 devices are used), or using a clock distribution system, e.g. an +OctoClock. See \ref page_sync and the individual device manuals on more details +on how to do this. + +*/ +// vim:ft=doxygen: diff --git a/host/docs/transport.dox b/host/docs/transport.dox index 942fa9509..eb7232f36 100644 --- a/host/docs/transport.dox +++ b/host/docs/transport.dox @@ -21,12 +21,15 @@ standard Berkeley sockets API using send()/recv(). \subsection transport_udp_params Transport parameters The following parameters can be used to alter the transport's default -behavior: +behavior (these options can be passed to a USRP device as arguments +at initialization time, see also \ref config_devaddr, or to a streamer, +see uhd::stream_args_t::args): - `recv_frame_size:` The size of a single receive buffer in bytes - `num_recv_frames:` The number of receive buffers to allocate - `send_frame_size:` The size of a single send buffer in bytes - `num_send_frames:` The number of send buffers to allocate +- `recv_buff_fullness:` The targetted fullness factor of the the buffer (typically around 90%) <b>Notes:</b> - `num_recv_frames` does not affect performance. diff --git a/host/docs/usrp_e3x0.dox b/host/docs/usrp_e3x0.dox index 289ea3410..ebe02627a 100644 --- a/host/docs/usrp_e3x0.dox +++ b/host/docs/usrp_e3x0.dox @@ -489,8 +489,8 @@ by pinging the USRP and making sure the LEDs start to blink. \subsection e3x0 Frequently Asked Questions - Communication - -# How do I enable X forwarding so I can run X apps on the e3x0?\n - In the file `/etc/ssh/sshd_config`, unmcomment the line `#X11Forwarding no` + -# How do I enable X forwarding so I can run X apps on the E3x0?<br> + In the file `/etc/ssh/sshd_config`, uncomment the line \#`X11Forwarding no` and change "no" to "yes". \section e3x0_apps Applications diff --git a/host/docs/usrp_x3x0.dox b/host/docs/usrp_x3x0.dox index 847efe74e..a9b31df57 100644 --- a/host/docs/usrp_x3x0.dox +++ b/host/docs/usrp_x3x0.dox @@ -378,6 +378,8 @@ Example: - Ethernet interface subnet mask: `255.255.255.0` - USRP-X Series device IPv4 address: `192.168.110.2` +If all devices are to be used in a compound, see also \ref page_multiple. + \subsection x3x0_setup_change_ip Change the USRP's IP address You may need to change the USRP's IP address for several reasons: @@ -436,6 +438,7 @@ Example device address string representation for 2 USRPs with IPv4 addresses **1 addr0=192.168.10.2, addr1=192.168.20.2 +See also \ref page_multiple. \section x3x0_comm_problems Communication Problems @@ -607,6 +610,16 @@ Further information on how to use Chipscope can be found in the Xilinx Chipscope \section x3x0_misc Miscellaneous +\subsection x3x0_misc_settings Configuring the device in an application + +During runtime, the device can be configured in several different ways. + +The following pages may shed some light: + +- \ref page_configuration +- uhd::stream_args_t +- \ref multiple_channumbers + \subsection x3x0_misc_multirx Multiple RX channels There are two complete DDC and DUC DSP chains in the FPGA. In the single channel case, diff --git a/host/include/uhd/stream.hpp b/host/include/uhd/stream.hpp index 75b097ded..ccf961aad 100644 --- a/host/include/uhd/stream.hpp +++ b/host/include/uhd/stream.hpp @@ -33,8 +33,25 @@ namespace uhd{ /*! * A struct of parameters to construct a streamer. * - * Note: - * Not all combinations of CPU and OTW format have conversion support. + * Here is an example of how a stream args object could be used in conjunction + * with uhd::device::get_rx_stream(): + * + * \code{.cpp} + * // 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. + * \endcode + * + * \b Note: Not all combinations of CPU and OTW format have conversion support. * You may however write and register your own conversion routines. */ struct UHD_API stream_args_t{ @@ -61,6 +78,8 @@ struct UHD_API stream_args_t{ * - f64 - double * - s16 - int16_t * - s8 - int8_t + * + * The CPU format can be chosen depending on what the application requires. */ std::string cpu_format; @@ -69,10 +88,18 @@ struct UHD_API stream_args_t{ * 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). */ std::string otw_format; @@ -101,17 +128,48 @@ struct UHD_API stream_args_t{ * 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 \ref page_transport can be set here. + * These options can be set either when creating the device (see also \ref config_devaddr), + * 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. */ device_addr_t args; /*! * The channels is a list of channel numbers. - * Leave this blank to default to channel 0. + * 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. + * Channel mapping depends on the front-end selection (see also \ref config_subdev). + * + * 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". */ std::vector<size_t> channels; }; |