transport: Made CHDR-related routines separate from VRT

Our VRT routines have the option to switch, on the fly, between
VRLP and CHDR. This adds new CHDR-specific (un-)packers, which
can only work with CHDR.

1 files changed, 83 insertions, 0 deletions

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: