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.

3 files changed, 188 insertions, 3 deletions

diff --git a/host/include/uhd/transport/CMakeLists.txt b/host/include/uhd/transport/CMakeLists.txt
index 2118674c6..623c179e9 100644
--- a/host/include/uhd/transport/CMakeLists.txt
+++ b/host/include/uhd/transport/CMakeLists.txt
@@ -1,5 +1,5 @@
 #
-# Copyright 2010-2013 Ettus Research LLC
+# Copyright 2010-2014 Ettus Research LLC
 #
 # This program is free software: you can redistribute it and/or modify
 # it under the terms of the GNU General Public License as published by
@@ -15,11 +15,11 @@
 # along with this program.  If not, see <http://www.gnu.org/licenses/>.
 #
 
-
 UHD_INSTALL(FILES
     bounded_buffer.hpp
     bounded_buffer.ipp
     buffer_pool.hpp
+    chdr.hpp
     if_addrs.hpp
     udp_constants.hpp
     udp_simple.hpp
diff --git a/host/include/uhd/transport/chdr.hpp b/host/include/uhd/transport/chdr.hpp
new file mode 100644
index 000000000..5e8cd58a9
--- /dev/null
+++ b/host/include/uhd/transport/chdr.hpp
@@ -0,0 +1,113 @@
+//
+// Copyright 2014 Ettus Research LLC
+//
+// This program is free software: you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+//
+// This program is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License
+// along with this program.  If not, see <http://www.gnu.org/licenses/>.
+//
+
+#ifndef INCLUDED_UHD_TRANSPORT_CHDR_HPP
+#define INCLUDED_UHD_TRANSPORT_CHDR_HPP
+
+#include <uhd/transport/vrt_if_packet.hpp>
+
+namespace uhd{ namespace transport{ namespace vrt{
+
+/*! \brief CVITA/CHDR related function
+ *
+ * See \ref rtp_chdr for details on the CVITA/CHDR protocol.
+ *
+ * All packers take the host format into account. Choose the _le functions
+ * if the transport uses little endian format (e.g. PCIe) and the _be
+ * functions if the transport uses big endian format (e.g. Ethernet).
+ *
+ * Note 1: All packers assume there to be enough space at the address
+ * provided by \p packet_buff. See also \ref vrt_pack_contract.
+ *
+ * Note 2: All these packers assume the following options without checking them:
+ * - `if_packet_info.link_type == LINK_TYPE_CHDR`
+ * - `if_packet_info.has_cid == false`
+ * - `if_packet_info.has_sid == true`
+ * - `if_packet_info.has_tsi == false`
+ * - `if_packet_info.has_tlr == false`
+ * This relaxes some of \ref vrt_pack_contract, but adds the additional
+ * constraint that the input data must be CHDR.
+ *
+ * In the unpacker, these values will be set accordingly.
+ */
+namespace chdr{
+
+    //! The maximum number of 64-bit words in a CVITA header
+    static const size_t max_if_hdr_words64 = 2; // CHDR + tsf (fractional timestamp)
+
+    /*!
+     * Pack a CHDR header from metadata (big endian format).
+     *
+     * See \ref vrt_pack_contract, but `link_type` is assumed to be
+     * `LINK_TYPE_CHDR`.
+     *
+     * \param packet_buff memory to write the packed vrt header
+     * \param if_packet_info the if packet info (read/write)
+     */
+    UHD_API void if_hdr_pack_be(
+        boost::uint32_t *packet_buff,
+        if_packet_info_t &if_packet_info
+    );
+
+    /*!
+     * Unpack a CHDR header to metadata (big endian format).
+     *
+     * See \ref vrt_unpack_contract, but `link_type` is assumed to be
+     * `LINK_TYPE_CHDR`.
+     *
+     * \param packet_buff memory to read the packed vrt header
+     * \param if_packet_info the if packet info (read/write)
+     */
+    UHD_API void if_hdr_unpack_be(
+        const boost::uint32_t *packet_buff,
+        if_packet_info_t &if_packet_info
+    );
+
+    /*!
+     * Pack a CHDR header from metadata (little endian format).
+     *
+     * See \ref vrt_pack_contract, but `link_type` is assumed to be
+     * `LINK_TYPE_CHDR`.
+     *
+     * \param packet_buff memory to write the packed vrt header
+     * \param if_packet_info the if packet info (read/write)
+     */
+    UHD_API void if_hdr_pack_le(
+        boost::uint32_t *packet_buff,
+        if_packet_info_t &if_packet_info
+    );
+
+    /*!
+     * Unpack a CHDR header to metadata (little endian format).
+     *
+     * See \ref vrt_unpack_contract, but `link_type` is assumed to be
+     * `LINK_TYPE_CHDR`.
+     *
+     * \param packet_buff memory to read the packed vrt header
+     * \param if_packet_info the if packet info (read/write)
+     */
+    UHD_API void if_hdr_unpack_le(
+        const boost::uint32_t *packet_buff,
+        if_packet_info_t &if_packet_info
+    );
+
+} //namespace chdr
+
+}}} //namespace uhd::transport::vrt
+
+#endif /* INCLUDED_UHD_TRANSPORT_CHDR_HPP */
+
diff --git a/host/include/uhd/transport/vrt_if_packet.hpp b/host/include/uhd/transport/vrt_if_packet.hpp
index d16892281..8bc65cdf1 100644
--- a/host/include/uhd/transport/vrt_if_packet.hpp
+++ b/host/include/uhd/transport/vrt_if_packet.hpp
@@ -1,5 +1,5 @@
 //
-// Copyright 2010-2013 Ettus Research LLC
+// Copyright 2010-2014 Ettus Research LLC
 //
 // This program is free software: you can redistribute it and/or modify
 // it under the terms of the GNU General Public License as published by
@@ -52,9 +52,18 @@ namespace vrt{
         //packet type
         enum packet_type_t
         {
+            // VRT language:
             PACKET_TYPE_DATA      = 0x0,
             PACKET_TYPE_IF_EXT    = 0x1,
             PACKET_TYPE_CONTEXT   = 0x2, //extension context: has_sid = true
+
+            // CVITA language:
+            //PACKET_TYPE_DATA      = 0x0, // Data
+            PACKET_TYPE_FC        = 0x1, // Flow control
+            PACKET_TYPE_ACK       = 0x1, // Flow control (ack)
+            PACKET_TYPE_CMD       = 0x2, // Command
+            PACKET_TYPE_RESP      = 0x3, // Command response
+            PACKET_TYPE_ERROR     = 0x3, // Command response: Error (the EOB bit is raised in this case)
         } packet_type;
 
         //size fields
@@ -65,18 +74,46 @@ namespace vrt{
 
         //header fields
         size_t packet_count;
+        //! Asserted for start- or end-of-burst
         bool sob, eob;
+        //! This is asserted for command responses that are errors (CHDR only)
+        bool error;
 
         //optional fields
+        //! Stream ID (SID). See uhd::sid_t
         bool has_sid; boost::uint32_t sid;
+        //! Class ID.
         bool has_cid; boost::uint64_t cid;
+        //! Integer timestamp
         bool has_tsi; boost::uint32_t tsi;
+        //! Fractional timestamp
         bool has_tsf; boost::uint64_t tsf;
+        //! Trailer
         bool has_tlr; boost::uint32_t tlr;
     };
 
     /*!
      * Pack a vrt header from metadata (big endian format).
+     *
+     * \section vrt_pack_contract Packing contract
+     *
+     * \subsection Requirements:
+     * - packet_buff points to a valid address space with enough space to write
+     *   the entire buffer, regardless of its length. At the very least, it must
+     *   be able to hold an entire header.
+     * - `if_packet_info` has the following members set to correct values:
+     *   - `has_*` members all set accordingly
+     *   - For every true `has_*` member, the corresponding variable holds a valid
+     *     value (e.g. if `has_sid` is true, `sid` contains a valid SID)
+     *   - `num_payload_bytes` and `num_payload_words32` are both set to the correct values
+     *
+     * \subsection Result:
+     * - `packet_buff` now points to a valid header that can be sent over the transport
+     *   without further modification
+     * - The following members on `if_packet_info` are set:
+     *   - `num_header_words32`
+     *   - `num_packet_words32`
+     *
      * \param packet_buff memory to write the packed vrt header
      * \param if_packet_info the if packet info (read/write)
      */
@@ -87,6 +124,34 @@ namespace vrt{
 
     /*!
      * Unpack a vrt header to metadata (big endian format).
+     *
+     * \section vrt_unpack_contract Unpacking contract
+     *
+     * \subsection Requirements
+     * - `packet_buff` points to a readable address space with a
+     *   CHDR packet, starting at the header. `packet_buff[0]` *must* always
+     *   point to a valid first word of the header. This implies that num_packet_words32
+     *   must be at least 1.
+     * - `if_packet_info` has the following members set to correct values:
+     *   - `num_packet_words32`. This means all values `packet_buff[0]`
+     *     through `packet_buff[if_packet_info.num_packet_words32-1]` are
+     *     readable words from this packet.
+     *   - `link_type`
+     *
+     * \subsection Result
+     * - `if_packet_info` now has the following values set to correct values:
+     *   - `packet_type`
+     *   - `num_payload_bytes`
+     *   - `num_payload_words32`
+     *   - `num_header_words32`
+     *   - `has_*`
+     *   - `sob`, `eob`, `error`, `cid`, `sid` (if applicable)
+     *   - `tsf`, `tsi` (if applicable)
+     *
+     * \subsection Exceptions
+     * - If the header is invalid, but the requirements are still met,
+     *   will throw a uhd::value_error.
+     *
      * \param packet_buff memory to read the packed vrt header
      * \param if_packet_info the if packet info (read/write)
      */
@@ -97,6 +162,9 @@ namespace vrt{
 
     /*!
      * Pack a vrt header from metadata (little endian format).
+     *
+     * See \ref vrt_pack_contract.
+     *
      * \param packet_buff memory to write the packed vrt header
      * \param if_packet_info the if packet info (read/write)
      */
@@ -107,6 +175,9 @@ namespace vrt{
 
     /*!
      * Unpack a vrt header to metadata (little endian format).
+     *
+     * See \ref vrt_unpack_contract.
+     *
      * \param packet_buff memory to read the packed vrt header
      * \param if_packet_info the if packet info (read/write)
      */
@@ -124,6 +195,7 @@ namespace vrt{
         num_packet_words32(0),
         packet_count(0),
         sob(false), eob(false),
+        error(false),
         has_sid(false), sid(0),
         has_cid(false), cid(0),
         has_tsi(false), tsi(0),