uhd: Added sid_t

This is a data type to represent SIDs (stream IDs).
It includes setters and getters for all components of the
SID, converters to and from string and uint32 as well
as C++ streams.

2 files changed, 239 insertions, 0 deletions

diff --git a/host/include/uhd/types/CMakeLists.txt b/host/include/uhd/types/CMakeLists.txt
index 334f1b41b..66b8662a1 100644
--- a/host/include/uhd/types/CMakeLists.txt
+++ b/host/include/uhd/types/CMakeLists.txt
@@ -29,6 +29,7 @@ UHD_INSTALL(FILES
     ref_vector.hpp
     sensors.hpp
     serial.hpp
+    sid.hpp
     stream_cmd.hpp
     time_spec.hpp
     tune_request.hpp
diff --git a/host/include/uhd/types/sid.hpp b/host/include/uhd/types/sid.hpp
new file mode 100644
index 000000000..12f98ff97
--- /dev/null
+++ b/host/include/uhd/types/sid.hpp
@@ -0,0 +1,238 @@
+//
+// 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_TYPES_SID_HPP
+#define INCLUDED_UHD_TYPES_SID_HPP
+
+#include <uhd/config.hpp>
+#include <boost/cstdint.hpp>
+#include <boost/shared_ptr.hpp>
+#include <iostream>
+
+namespace uhd {
+    /*!
+     * \brief Represents a stream ID (SID).
+     *
+     * A stream ID (SID) is an identifier for data.
+     * It is a 32-Bit value which consistst of 16 Bits
+     * for the source address and 16 Bits for the destination
+     * address.
+     * Every address is split into two parts: The _address_, which
+     * identifies the device used, and the _endpoint_, which identifies
+     * a specific object inside the given device (e.g., a block).
+     * *Note:* In the case where there are several crossbars on a single
+     * device, each crossbar gets its own address.
+     * Both address and endpoint are 8 bits in length. If a 16-bit address
+     * is required, we use the combination of the 8-bit address and the 8-bit
+     * endpoint.
+     *
+     * \section sid_str_repr
+     *
+     * The string representation of a SID is of the form
+     *
+     *     2.3>0.6
+     *
+     * The '>' symbol shows the direction, so in this case,
+     * data is flowing from address 2.3 to 0.6.
+     *
+     * As a convention, ':' is used instead of '.' when giving the
+     * SID in hexadecimal numbers, and two characters are used for each
+     * address part. As an example, the following two SIDs are identical:
+     *
+     *     2.3>0.16 (decimal)
+     *     02:03>00:10 (hexadecimal)
+     *
+     * The format is:
+     *     SRC_ADDRESS.SRC_ENDPOINT>DST_ADDRESS.DST_ENDPOINT
+     *
+     *
+     * \section sid_block_ports
+     *
+     * In the special case where a block on a crossbar is addressed, the
+     * endpoint is further split up into two parts of four bits each: The
+     * first four bits specify the port number on the crossbar, whereas the
+     * lower four bits represent the *block port*. As an example, consider
+     * the following SID, given in hexadecimal:
+     *
+     *    00:10>02:A1
+     *
+     * In this example, assume data is flowing from the host computer to an
+     * X300. The crossbar address is 02. The endpoint is A1, which means we
+     * are accessing a block on crossbar port A (the tenth port), and are addressing
+     * block port 1.
+     *
+     */
+    class UHD_API sid_t
+    {
+    public:
+        //! Create an unset SID
+        sid_t();
+        //! Create a sid_t object from a 32-Bit SID value
+        sid_t(boost::uint32_t sid);
+        //! Create a sid_t object from its four components
+        sid_t(boost::uint8_t src_addr, boost::uint8_t src_ep, boost::uint8_t dst_addr, boost::uint8_t dst_ep);
+        //! Convert a string representation of a SID into its numerical representation
+        sid_t(const std::string &);
+
+        //! Return a decimal string representation of the SID.
+        std::string to_pp_string() const;
+        //! Return a hexadecimal string representation of the SID.
+        std::string to_pp_string_hex() const;
+
+        //! Returns true if this actually holds a valid SID
+        bool is_set() const { return _set; };
+
+        // Getters
+        //
+        //! Alias for get_sid()
+        UHD_INLINE boost::uint32_t get() const { return get_sid(); };
+        //! Returns a 32-Bit representation of the SID if set, or zero otherwise.
+        UHD_INLINE boost::uint32_t get_sid() const { return _set ? _sid : 0; };
+        //! Return the 16-bit source address of this SID
+        UHD_INLINE boost::uint32_t get_src() const {
+            return (_sid >> 16) & 0xFFFF;
+        }
+        //! Return the 16-bit destination address of this SID
+        UHD_INLINE boost::uint32_t get_dst() const {
+            return _sid & 0xFFFF;
+        }
+        //! Return 8-bit address of the source
+        UHD_INLINE boost::uint32_t get_src_addr() const {
+            return (get_src() >> 8) & 0xFF;
+        }
+        //! Return endpoint of the source
+        UHD_INLINE boost::uint32_t get_src_endpoint() const {
+            return get_src() & 0xFF;
+        }
+        //! Return crossbar port of the source
+        UHD_INLINE boost::uint32_t get_src_xbarport() const {
+            return (get_src_endpoint() >> 4) & 0xF;
+        }
+        //! Return block port of the source
+        UHD_INLINE boost::uint32_t get_src_blockport() const {
+            return (get_src_endpoint()) & 0xF;
+        }
+        //! Return 8-bit address of the destination
+        UHD_INLINE boost::uint32_t get_dst_addr() const {
+            return (get_dst() >> 8) & 0xFF;
+        }
+        //! Return endpoint of the destination
+        UHD_INLINE boost::uint32_t get_dst_endpoint() const {
+            return get_dst() & 0xFF;
+        }
+        //! Return crossbar port of the source
+        UHD_INLINE boost::uint32_t get_dst_xbarport() const {
+            return (get_dst_endpoint() >> 4) & 0xF;
+        }
+        //! Return block port of the source
+        UHD_INLINE boost::uint32_t get_dst_blockport() const {
+            return (get_dst_endpoint()) & 0xF;
+        }
+
+        // Setters
+
+        //! Alias for set_sid()
+        void set(boost::uint32_t new_sid) { set_sid(new_sid); };
+        //! Convert a string representation of a SID into a numerical one
+        // Throws uhd::value_error if the string is not a valid SID
+        // representation.
+        void set_from_str(const std::string &);
+        void set_sid(boost::uint32_t new_sid);
+        //! Set the source address of this SID
+        //  (the first 16 Bits)
+        void set_src(boost::uint32_t new_addr);
+        //! Set the destination address of this SID
+        //  (the last 16 Bits)
+        void set_dst(boost::uint32_t new_addr);
+        void set_src_addr(boost::uint32_t new_addr);
+        void set_src_endpoint(boost::uint32_t new_addr);
+        void set_dst_addr(boost::uint32_t new_addr);
+        void set_dst_endpoint(boost::uint32_t new_addr);
+        void set_dst_xbarport(boost::uint32_t new_xbarport);
+        void set_dst_blockport(boost::uint32_t new_blockport);
+
+        // Manipulators
+
+        //! Swaps dst and src address and returns the new SID.
+        sid_t reversed();
+
+        //! Swaps dst and src in-place.
+        void reverse();
+
+        // Overloaded operators
+
+        sid_t operator = (boost::uint32_t new_sid) {
+            set_sid(new_sid);
+            return *this;
+        }
+
+        sid_t operator = (sid_t &sid) {
+            set_sid(sid.get_sid());
+            return *this;
+        }
+
+        sid_t operator = (const std::string &sid_str) {
+            set_from_str(sid_str);
+            return *this;
+        }
+
+        bool operator == (const sid_t &sid) const {
+            return (not _set and not sid.is_set()) or (_sid == sid.get_sid());
+        }
+
+        bool operator == (boost::uint32_t sid) const {
+            return _set and _sid == sid;
+        }
+
+        bool operator == (const std::string &sid_str) const {
+            sid_t rhs(sid_str);
+            return *this == rhs;
+        }
+
+        // overloaded type casts are tricky, but for now we'll need them
+        // for backward compatibility. consider them deprecated.
+
+        //! If the SID is not set, always returns zero.
+        //  Use is_set() to check if the return value is valid.
+        operator boost::uint32_t() const {
+            return get();
+        }
+
+        operator bool() const {
+            return _set;
+        }
+
+    private:
+        boost::uint32_t _sid;
+        bool _set;
+    };
+
+    //! Stream output operator. Honors std::ios::hex.
+    UHD_INLINE std::ostream& operator<< (std::ostream& out, const sid_t &sid) {
+        std::ios_base::fmtflags ff = out.flags();
+        if (ff & std::ios::hex) {
+            out << sid.to_pp_string_hex();
+        } else {
+            out << sid.to_pp_string();
+        }
+        return out;
+    }
+
+} //namespace uhd
+
+#endif /* INCLUDED_UHD_TYPES_SID_HPP */
+// vim: sw=4 et: