rfnoc: Improve comments regarding streaming and mgmt. code

This commit *only* touches comments in the code for RFNoC streaming,
link management and management portal.

3 files changed, 31 insertions, 4 deletions

diff --git a/host/lib/include/uhdlib/rfnoc/link_stream_manager.hpp b/host/lib/include/uhdlib/rfnoc/link_stream_manager.hpp
index 4357a2d58..d4e2aba46 100644
--- a/host/lib/include/uhdlib/rfnoc/link_stream_manager.hpp
+++ b/host/lib/include/uhdlib/rfnoc/link_stream_manager.hpp
@@ -40,12 +40,25 @@ public:
 
     /*! \brief Get the software device ID associated with this instance
      *
+     * For every link to a device, we create a unique device ID. For example,
+     * if there are two USRPs in the graph, each connected with a single
+     * Ethernet connection, there would be two link managers, and therefore also
+     * two device IDs on the host side.
+     * If we access a single USRP using two Ethernet connections, then we still
+     * have two link stream managers, each with its own unique device ID on the
+     * host side.
+     * The device IDs are allocated in the mb_iface associated with this device
+     * during discovery.
+     *
      * \return The software device ID associated with this instance
      */
     virtual device_id_t get_self_device_id() const = 0;
 
     /*! \brief Get the transport adapter ID associated with this instance
      *
+     * See also uhd::transport::adapter_id_t. For example, when using two
+     * separate Ethernet ports, there would be two adapter IDs.
+     *
      * \return The adapter ID associated with this instance
      */
     virtual uhd::transport::adapter_id_t get_adapter_id() const = 0;
diff --git a/host/lib/include/uhdlib/rfnoc/mgmt_portal.hpp b/host/lib/include/uhdlib/rfnoc/mgmt_portal.hpp
index 069ad9604..dcb93772b 100644
--- a/host/lib/include/uhdlib/rfnoc/mgmt_portal.hpp
+++ b/host/lib/include/uhdlib/rfnoc/mgmt_portal.hpp
@@ -19,7 +19,8 @@ namespace uhd { namespace rfnoc { namespace mgmt {
 //! A portal to perform low-level management operations from an endpoint
 //
 // This object provides an interface to send management commands from a software stream
-// endpoint. There must one instance of this object per software stream endpoint.
+// endpoint. There must one instance of this object per software stream endpoint
+// (i.e., every link_stream_manager owns one of these).
 // The management portal is capable of discovering all endpoints reachable from the
 // transport associated with it. It can then setup routes and configure stream endpoints
 // downstream.
diff --git a/host/lib/include/uhdlib/rfnoc/rfnoc_common.hpp b/host/lib/include/uhdlib/rfnoc/rfnoc_common.hpp
index 7b2900832..72b06fa46 100644
--- a/host/lib/include/uhdlib/rfnoc/rfnoc_common.hpp
+++ b/host/lib/include/uhdlib/rfnoc/rfnoc_common.hpp
@@ -9,18 +9,31 @@
 #include <uhd/rfnoc/defaults.hpp>
 #include <uhd/rfnoc/rfnoc_types.hpp>
 #include <memory>
+#include <utility>
 
 namespace uhd { namespace rfnoc {
 
-//----------------------------------------------
-// Types
-//----------------------------------------------
+//-----------------------------------------------------------------------------
+// Types that are private to UHD
+// (there are more in rfnoc_types.hpp that are public)
+//-----------------------------------------------------------------------------
 
 //! Device ID Type
+// Every USRP in the RFNoC graph will have *one* device_id. It is programmed
+// into the device during initialization through a non-RFNoC mechanism (e.g.,
+// via MPM or the ZPU).
 using device_id_t = uint16_t;
 //! Stream Endpoint Instance Number Type
+// These instance numbers are unique within a device (they are simply counted
+// up), but are not unique in a graph (every USRP will have its own set of SEPs).
 using sep_inst_t = uint16_t;
 //! Stream Endpoint Physical Address Type
+// This combination of device ID and SEP instance is unique in a graph. Note
+// that for the most part, we map an sep_addr_t to a sep_id_t. This limits us to
+// 2**16 combinations of device IDs and SEP instances, but that is more than
+// enough for all practical applications. We use sep_id_t when we need a compact
+// 16-bit address (e.g., in a CHDR header). We use a sep_addr_t when we need to
+// know which device this endpoint belongs to.
 using sep_addr_t = std::pair<device_id_t, sep_inst_t>;
 //! Stream Endpoint Physical Address Type (first = source, second = destination)
 using sep_addr_pair_t = std::pair<sep_addr_t, sep_addr_t>;