diff options
Diffstat (limited to 'host/docs')
| -rw-r--r-- | host/docs/build.dox | 18 | ||||
| -rw-r--r-- | host/docs/dboards.dox | 4 | ||||
| -rw-r--r-- | host/docs/octoclock.dox | 31 | ||||
| -rw-r--r-- | host/docs/uhd.dox | 1 | ||||
| -rw-r--r-- | host/docs/usrp_b200.dox | 31 | ||||
| -rw-r--r-- | host/docs/usrp_e3x0.dox | 6 | ||||
| -rw-r--r-- | host/docs/usrp_x3x0_config.dox | 34 | ||||
| -rw-r--r-- | host/docs/vrt_chdr.dox | 83 |
8 files changed, 138 insertions, 70 deletions
diff --git a/host/docs/build.dox b/host/docs/build.dox index 1097ab5ab..f3fdf5aa6 100644 --- a/host/docs/build.dox +++ b/host/docs/build.dox @@ -11,7 +11,7 @@ package manager. <b>Mac OS X Notes:</b> Install the Xcode app to get the build tools (GCC and Make). -Use MacPorts to get the Boost and Cheetah dependencies. +Use MacPorts to get the Boost and Mako dependencies. Other dependencies can be downloaded as DMG installers from the web or installed via MacPorts. See the UHD OS X build instructions for more information: \ref build_instructions_osx @@ -57,22 +57,20 @@ Other compilers (or lower versions) may work, but are unsupported. ### Python -- **Purpose:** used by Cheetah and utility scripts +- **Purpose:** used by mako and utility scripts - **Minimum Version:** 2.6 - **Usage:** build time + runtime utility scripts (required) - **Download URL:** http://www.python.org/download/ -### Cheetah +### Mako - **Purpose:** source code generation -- **Minimum Version:** 2.0 +- **Minimum Version:** 0.5.0 - **Usage:** build time (required) -- **Download URL:** http://www.cheetahtemplate.org/download.html -- **Download URL (Windows installer):** http://feisley.com/python/cheetah/ +- **Download URL:** http://www.makotemplates.org/download.html **Alternative method:** -Install **setuptools**, and use the **easy_install** command to install Cheetah. -http://pypi.python.org/pypi/setuptools +You can use `pip` or `easy_install` to install Mako from PyPi. ### Doxygen @@ -96,7 +94,7 @@ or install msysGit from http://code.google.com/p/msysgit/downloads/list. You can install all the dependencies through the package manager: - sudo apt-get install libboost-all-dev libusb-1.0-0-dev python-cheetah doxygen python-docutils cmake + sudo apt-get install libboost-all-dev libusb-1.0-0-dev python-mako doxygen python-docutils cmake Your actual command may differ. @@ -104,7 +102,7 @@ Your actual command may differ. You can install all the dependencies through the package manager: - sudo yum -y install boost-devel libusb1-devel python-cheetah doxygen python-docutils cmake + sudo yum -y install boost-devel libusb1-devel python-mako doxygen python-docutils cmake Your actual command may differ. diff --git a/host/docs/dboards.dox b/host/docs/dboards.dox index 3d6866a42..812a3a09e 100644 --- a/host/docs/dboards.dox +++ b/host/docs/dboards.dox @@ -372,6 +372,10 @@ Sensors: - **rssi**: float for measured RSSI in dBm - **temperature**: float for measured temperature in degC +\subsection dboards_e300 E310 MIMO XCVR board + +Please refer to \ref e3x0_dboard_e310. + \subsection dboards_dbsrxmod DBSRX - Modifying for other boards that USRP1 Due to different clocking capabilities, the DBSRX will require diff --git a/host/docs/octoclock.dox b/host/docs/octoclock.dox index 45a12e93a..58d2b1f99 100644 --- a/host/docs/octoclock.dox +++ b/host/docs/octoclock.dox @@ -7,41 +7,24 @@ - Hardware Capabilities: - Fully integrated timing source with 8-Way distribution (10 MHz and 1 PPS) - User selection between internal GPSDO (when present) or external 10 MHz/1 PPS source + - Ethernet bootloader for easy firmware upgrade - Source detection with automatic switch over in case of failure or disconnect - Streaming GPS time and NMEA strings over Ethernet (OctoClock-G only) \section octoclock_load Loading Firmware onto the Octoclock -\subsection bootloader OctoClock bootloader - -If you purchased your OctoClock device before Ethernet functionality was introduced, or if your unit's -bootloader has somehow become corrupted, you must burn the bootloader onto the device before you can load -the primary firmware. - -To load the bootloader onto the OctoClock, two things are needed: - -- AVR programmer -- AVRdude software - -Connect the AVR programmer to J108, as specified on the <a href="http://files.ettus.com/schematics/octoclock/octoclock.pdf"> -schematics</a>. Once you verify that the programmer is properly connected, run the following commands to burn the firmware: +First, the OctoClock's bootloader needs to be loaded onto the device. Connect the AVR programmer to J108, as +specified on the <a href="http://files.ettus.com/schematics/octoclock/octoclock.pdf">schematics</a>. Once you +verify that the programmer is properly connected, run the following commands to load the bootloader: cd <install path>/share/uhd/images - avrdude -p atmega128 -c <programmer name> -P usb -U efuse:w:0xFF:m -U hfuse:w:0x80:m -U lfuse:w:0xFF:m -U flash:w:octoclock_bootloader.hex:i + avrdude -p atmega128 -c <programmer name> -P usb -U efuse:w:0xFF:m -U hfuse:w:0x80:m -U lfuse:w:0xEF:m -U flash:w:octoclock_r4_fw.hex:i + +When the bootloader is loaded, it will have a default IP address of `192.168.10.3`. \b Note: On Linux, `sudo avrdude ...` might be necessary to gain access to the programmer. -Once the bootloader has been burned, power-cycle your OctoClock device and refer to the below instructions on burning the OctoClock's -primary firmware. - -\subsection application Primary Octoclock firmware - -To load firmware onto the OctoClock, you must use the `octoclock_firmware_burner` utility, specifying the IP -address of the OctoClock device, as follows: - - octoclock_firmware_burner --addr=192.168.10.3 - \section octoclock_network Setting Up Networking \subsection host_interface Setting up the host interface diff --git a/host/docs/uhd.dox b/host/docs/uhd.dox index 949c710b1..fcd0a25b0 100644 --- a/host/docs/uhd.dox +++ b/host/docs/uhd.dox @@ -12,6 +12,7 @@ Some additional pages on developing UHD are also available here: \li \subpage page_coding \li \subpage page_converters \li \subpage page_stream +\li \subpage page_rtp */ // vim:ft=doxygen: diff --git a/host/docs/usrp_b200.dox b/host/docs/usrp_b200.dox index bd79c4470..1da7f2aee 100644 --- a/host/docs/usrp_b200.dox +++ b/host/docs/usrp_b200.dox @@ -38,15 +38,40 @@ images: The master clock rate feeds the RF frontends and the DSP chains. Users may select non-default clock rates to acheive integer decimations or -interpolations in the DSP chains. The default master clock rate defaults -to 32 MHz, but can be set to any rate between 5 MHz and 61.44 MHz. +interpolations in the DSP chains. The clock rate can be set to any value +between 5 MHz and 61.44 MHz (or 30.72 MHz for dual-channel mode). +Note that rates above 56 MHz are possible, but not recommended. The user can set the master clock rate through the usrp API call uhd::usrp::multi_usrp::set_master_clock_rate(), or the clock rate can be set through the -device arguments, which many applications take: : +device arguments, which many applications take: uhd_usrp_probe --args="master_clock_rate=52e6" +The property to control the master clock rate is a double value, called `tick_rate`. + +\subsection b200_auto_mcr Automatic Clock Rate Setting + +The default clock rate setting is to automatically set a clock rate +depending on the requested sampling rate. The automatic clock rate selection +is disabled when either `master_clock_rate` is given in the device initialization +arguments, or when uhd::usrp::multi_usrp::set_master_clock_rate() is called. + +Note that the master clock rate must be an integer multiple of the sampling +rate. If a master clock rate is chosen for which this condition does not +hold, a warning will be displayed and a different sampling rate is used internally. + +Nevertheless, there are multiple valid values for the master clock rate +for most sampling rates. The auto clock rate selection attempts to use +the largest possible clock rate as to enable as many half-band filters +as possible. Expert users might have cases where a more fine-grained +control over the resampling stages is required, in which case manually +selecting a master clock rate might be more suitable than the automatic +rate. + +The property to dis- or enable the auto tick rate is a boolean value, +`auto_tick_rate`. + \section b200_fe RF Frontend Notes The B200 features an integrated RF frontend. diff --git a/host/docs/usrp_e3x0.dox b/host/docs/usrp_e3x0.dox index a05914bba..ff03dedcd 100644 --- a/host/docs/usrp_e3x0.dox +++ b/host/docs/usrp_e3x0.dox @@ -188,9 +188,9 @@ builds) $ export MACHINE="ettus-e300" $ bitbake gnuradio-dev-image \endcode -When this completes, the files needed to create the sd card are in -`tmp-glibc/deploy/images/ettus-e300`. See \ref e3x0_upgrade_sd_card for instructions to write the image to your sd card. +When this completes, the files needed to create the SD card are in +`tmp-glibc/deploy/images/ettus-e300` -# Build the toolchain. \code{.sh} @@ -544,7 +544,7 @@ usrp->set_rx_subdev_spec("A:A A:B"); The following sensors are available for the USRP-E Series motherboards; they can be queried through the API. -- **fe_locked** - rx / tx frontend pll locked +- **fe_locked** - rx / tx frontend PLL locked - **temp** - processor temperature value - **gps_time** and **gps_locked** sensors are added when the GPS is found diff --git a/host/docs/usrp_x3x0_config.dox b/host/docs/usrp_x3x0_config.dox index 2ee449cc2..ed80c31de 100644 --- a/host/docs/usrp_x3x0_config.dox +++ b/host/docs/usrp_x3x0_config.dox @@ -320,38 +320,12 @@ Real-time scheduling is enabled via different methods depending on your application and operating system. In GNU Radio Companion, it can be turned on in each individual flowgraph. -\subsection x3x0cfg_hostpc_volk Building with ORC & Volk +\subsection x3x0cfg_hostpc_volk SIMD Acceleration Especially when running high-performance applications, processing -performance can be dramatically improved by SIMD instructions. UHD uses -ORC to provide SIMD capability, and GNU Radio includes a SIMD library -called "Volk". These should both be used to guarantee optimum -performance. - -\subsubsection x3x0cfg_hostpc_volk_orc Compiling UHD with ORC - -ORC, the <a href="http://code.entropywave.com/orc/">Oil Runtime Compiler</a>, -is a third-party compiler that UHD uses to create efficient SIMD code for -your particular computer. ORC is generally easily installed from your -OS's package manager. - -On Fedora: - - $ sudo yum update; sudo yum install orc-compiler orc-devel - -On Ubuntu: - - $ sudo apt-get update; sudo apt-get install liborc-<version> liborc-<version>-dev - -After installing ORC, when building UHD from source, you should see -"ORC" as one of the configured UHD components. - - -- ###################################################### - -- # UHD enabled components - -- ###################################################### - -- * LibUHD - <cut for brevity> - -- * ORC +performance can be dramatically improved by SIMD instructions. +GNU Radio includes a SIMD library +called "Volk", which should be used to guarantee optimum performance. \subsubsection x3x0cfg_hostpc_volk_volk Compiling GNURadio with Volk diff --git a/host/docs/vrt_chdr.dox b/host/docs/vrt_chdr.dox new file mode 100644 index 000000000..8ab177b21 --- /dev/null +++ b/host/docs/vrt_chdr.dox @@ -0,0 +1,83 @@ +/*! \page page_rtp Radio Transport Protocols + +\tableofcontents + +Radio transport protocols are used to exchange samples (or other items) between host and devices. +If one were to sniff Ethernet traffic between a USRP and a PC, the packets would conform to a +radio transport protocol. + +For USRP devices, two radio transport protocols are relevent: VRT (the VITA Radio Transport protocol) +and CVITA (compressed VITA), also known as CHDR. Generation-3 devices and the B200 use CHDR, the rest +use VRT. + +\section rtp_vrt VRT + +VRT is an open protocol defined by the VITA-49 standard. It was designed for interoperability, +and to allow different device types to work with different software stacks. + +VRT is a very verbose standard, and only a subset is implemented in UHD/USRPs. +The full standard is available from the VITA website: http://www.vita.com . + + +\section rtp_chdr CVITA (CHDR) + +For the third generation of Ettus devices, a new type transport protocol was designed. +It reduces the complexity of the original standard and uses a fixed-length 64-Bit header +for everything except the timestamp. Because this is a "compressed" form of VITA, it +was dubbed "Compressed VITA" (CVITA). The compressed header is called CHDR, which is why +the protocol is often called CHDR itself (pronounced like the cheese "cheddar"). + +By compressing all information into a 64-bit line, the header can efficiently be parsed +in newer FPGAs, where the common streaming protocol is 64-Bit AXI. The first line in a +packet already provides all necessary information to proceed. + +Some CHDR-specific functions can be found in: uhd::transport::vrt::chdr. + +The form of a CVITA packet is the following: + +Address (Bytes) | Length (Bytes) | Payload +----------------|----------------|---------------------------- +0 | 8 | Compressed Header (CHDR) +8 | 8 | Fractional Time (Optional!) +8/16 | - | Data + +If there is no timestamp present, the data starts at address 8, otherwise, it starts at 16. + +The 64 Bits in the compressed header have the following meaning: + +Bits | Meaning +-------|-------------------------------------------------- +63:62 | Packet Type +61 | Has fractional time stamp (1: Yes) +60 | End-of-burst or error flag +59:48 | 12-bit sequence number +47:32 | Total packet length in Bytes +31:0 | Stream ID (SID) + + +The packet type is determined mainly by the first two bits, although +the EOB or error flag are also taken into consideration: + +Bit 63 | Bit 62 | Bit 60 | Packet Type +-------|--------|--------|-------------- +0 | 0 | 0 | Data +0 | 0 | 1 | Data (End-of-burst) +0 | 1 | 0 | Flow Control +1 | 0 | 0 | Command Packet +1 | 1 | 0 | Command Response +1 | 1 | 1 | Command Response (Error) + +\section vrt_tools Tools + +For CHDR, we provide a Wireshark dissector under tools/chdr_dissector. It can be used +for Ethernet links as well as USB (e.g., for the B210). + +\section vrt_code Code + +Relevent code sections for the radio transport layer are: +* uhd::transport::vrt - Namespace for radio transport protocol related functions and definitions +* uhd::transport::vrt::chdr - Sub-namespace specifically for CVITA/CHDR +* uhd::sid_t - Datatype to represent SIDs + +*/ +// vim:ft=doxygen: |