From d5c6a6a5699520e8c84f73c1674cb8f3b6028152 Mon Sep 17 00:00:00 2001
From: Martin Braun <martin.braun@ettus.com>
Date: Thu, 12 May 2022 12:48:54 +0200
Subject: rfnoc: Improve comments regarding streaming and mgmt. code

This commit *only* touches comments in the code for RFNoC streaming,
link management and management portal.
---
 host/include/uhd/rfnoc/chdr_types.hpp     |  3 +++
 host/include/uhd/rfnoc/rfnoc_types.hpp    | 12 +++++++++---
 host/include/uhd/transport/adapter_id.hpp |  3 +++
 3 files changed, 15 insertions(+), 3 deletions(-)

(limited to 'host/include')

diff --git a/host/include/uhd/rfnoc/chdr_types.hpp b/host/include/uhd/rfnoc/chdr_types.hpp
index e6c5e3912..f4acee28b 100644
--- a/host/include/uhd/rfnoc/chdr_types.hpp
+++ b/host/include/uhd/rfnoc/chdr_types.hpp
@@ -610,6 +610,9 @@ class UHD_API mgmt_op_t
 {
 public:
     // Operation code
+    // Note that a management packet has 8 bits available for op codes. The
+    // values for these enums are used to construct the packets, so these values
+    // must match the values in rfnoc_chdr_internal_utils.vh.
     enum op_code_t {
         //! Do nothing
         MGMT_OP_NOP = 0,
diff --git a/host/include/uhd/rfnoc/rfnoc_types.hpp b/host/include/uhd/rfnoc/rfnoc_types.hpp
index 123bf82f1..ebf8a08ad 100644
--- a/host/include/uhd/rfnoc/rfnoc_types.hpp
+++ b/host/include/uhd/rfnoc/rfnoc_types.hpp
@@ -11,9 +11,9 @@
 
 namespace uhd { namespace rfnoc {
 
-//----------------------------------------------
-// Types
-//----------------------------------------------
+//-----------------------------------------------------------------------------
+// Types (note: internal types are defined in rfnoc_common.hpp)
+//-----------------------------------------------------------------------------
 
 //! Type that indicates the CHDR Width in bits
 enum chdr_w_t { CHDR_W_64 = 0, CHDR_W_128 = 1, CHDR_W_256 = 2, CHDR_W_512 = 3 };
@@ -50,6 +50,12 @@ constexpr size_t chdr_w_to_bits(chdr_w_t chdr_w)
 }
 
 //! Stream Endpoint ID Type
+// Stream endpoints within a graph are unique. They are assigned dynamically
+// during runtime when needed. Stream endpoints exist both in the host as well
+// as in the devices. See also sep_addr_t. The value of any sep_id_t is
+// meaningless, it provides no information on where the SEP is physically
+// located. In comments and variables, it is often abbreviated as "EPID"
+// ("endpoint ID").
 using sep_id_t = uint16_t;
 
 }} // namespace uhd::rfnoc
diff --git a/host/include/uhd/transport/adapter_id.hpp b/host/include/uhd/transport/adapter_id.hpp
index 8f8c40aa1..5859147e3 100644
--- a/host/include/uhd/transport/adapter_id.hpp
+++ b/host/include/uhd/transport/adapter_id.hpp
@@ -11,6 +11,9 @@
 namespace uhd { namespace transport {
 
 //! Host transport adapter ID
+// The adapter ID is a unique identifier for the physical connection. For example,
+// if the UHD session is using two separate Ethernet cables, each plugged into
+// its own Ethernet port, then there would be two adapter IDs available (0 and 1).
 using adapter_id_t = size_t;
 //! NULL/unassigned host transport adapter ID
 static const adapter_id_t NULL_ADAPTER_ID = 0;
-- 
cgit v1.2.3