[dpdk-dev] [PATCH v3 06/18] fm10k/base: document ITR scale workaround in VF TDLEN register

[Wang Xiao W <xiao.w.wang@intel.com>]

Add comments which properly explain the undocumented use of bits in
TDLEN register prior to VF initializing it to the correct value. Note
that the mechanism is entirely software-defined and explain its purpose
to help reduce confusion in the future.

Signed-off-by: Wang Xiao W <xiao.w.wang@intel.com>
---
 drivers/net/fm10k/base/fm10k_pf.c   | 6 +++++-
 drivers/net/fm10k/base/fm10k_type.h | 9 +++++++++
 drivers/net/fm10k/base/fm10k_vf.c   | 9 +++++++++
 3 files changed, 23 insertions(+), 1 deletion(-)

diff --git a/drivers/net/fm10k/base/fm10k_pf.c b/drivers/net/fm10k/base/fm10k_pf.c
index 5b8c039..6de679e 100644
--- a/drivers/net/fm10k/base/fm10k_pf.c
+++ b/drivers/net/fm10k/base/fm10k_pf.c
@@ -958,7 +958,8 @@ STATIC s32 fm10k_iov_assign_default_mac_vlan_pf(struct fm10k_hw *hw,
 	FM10K_WRITE_REG(hw, FM10K_TDBAH(vf_q_idx), tdbah);
 
 	/* Provide the VF the ITR scale, using software-defined fields in TDLEN
-	 * to pass the information during VF initialization
+	 * to pass the information during VF initialization. See definition of
+	 * FM10K_TDLEN_ITR_SCALE_SHIFT for more details.
 	 */
 	FM10K_WRITE_REG(hw, FM10K_TDLEN(vf_q_idx), hw->mac.itr_scale <<
 						   FM10K_TDLEN_ITR_SCALE_SHIFT);
@@ -1095,6 +1096,9 @@ STATIC s32 fm10k_iov_reset_resources_pf(struct fm10k_hw *hw,
 	for (i = queues_per_pool; i--;) {
 		FM10K_WRITE_REG(hw, FM10K_TDBAL(vf_q_idx + i), tdbal);
 		FM10K_WRITE_REG(hw, FM10K_TDBAH(vf_q_idx + i), tdbah);
+		/* See definition of FM10K_TDLEN_ITR_SCALE_SHIFT for an
+		 * explanation of how TDLEN is used.
+		 */
 		FM10K_WRITE_REG(hw, FM10K_TDLEN(vf_q_idx + i),
 				hw->mac.itr_scale <<
 				FM10K_TDLEN_ITR_SCALE_SHIFT);
diff --git a/drivers/net/fm10k/base/fm10k_type.h b/drivers/net/fm10k/base/fm10k_type.h
index 4bc0d53..4ec18fb 100644
--- a/drivers/net/fm10k/base/fm10k_type.h
+++ b/drivers/net/fm10k/base/fm10k_type.h
@@ -350,6 +350,15 @@ struct fm10k_hw;
 #define FM10K_TDBAL(_n)		((0x40 * (_n)) + 0x8000)
 #define FM10K_TDBAH(_n)		((0x40 * (_n)) + 0x8001)
 #define FM10K_TDLEN(_n)		((0x40 * (_n)) + 0x8002)
+/* When fist initialized, VFs need to know the Interrupt Throttle Rate (ITR)
+ * scale which is based on the PCIe speed but the speed information in the PCI
+ * configuration space may not be accurate. The PF already knows the ITR scale
+ * but there is no defined method to pass that information from the PF to the
+ * VF. This is accomplished during VF initialization by temporarily co-opting
+ * the yet-to-be-used TDLEN register to have the PF store the ITR shift for
+ * the VF to retrieve before the VF needs to use the TDLEN register for its
+ * intended purpose, i.e. before the Tx resources are allocated.
+ */
 #define FM10K_TDLEN_ITR_SCALE_SHIFT		9
 #define FM10K_TDLEN_ITR_SCALE_MASK		0x00000E00
 #define FM10K_TDLEN_ITR_SCALE_GEN1		2
diff --git a/drivers/net/fm10k/base/fm10k_vf.c b/drivers/net/fm10k/base/fm10k_vf.c
index 9b10ee4..43eb081 100644
--- a/drivers/net/fm10k/base/fm10k_vf.c
+++ b/drivers/net/fm10k/base/fm10k_vf.c
@@ -74,6 +74,11 @@ STATIC s32 fm10k_stop_hw_vf(struct fm10k_hw *hw)
 		FM10K_WRITE_REG(hw, FM10K_TDBAH(i), bah);
 		FM10K_WRITE_REG(hw, FM10K_RDBAL(i), bal);
 		FM10K_WRITE_REG(hw, FM10K_RDBAH(i), bah);
+		/* Restore ITR scale in software-defined mechanism in TDLEN
+		 * for next VF initialization. See definition of
+		 * FM10K_TDLEN_ITR_SCALE_SHIFT for more details on the use of
+		 * TDLEN here.
+		 */
 		FM10K_WRITE_REG(hw, FM10K_TDLEN(i), tdlen);
 	}
 
@@ -157,6 +162,10 @@ STATIC s32 fm10k_init_hw_vf(struct fm10k_hw *hw)
 	/* fetch default VLAN and ITR scale */
 	hw->mac.default_vid = (FM10K_READ_REG(hw, FM10K_TXQCTL(0)) &
 			       FM10K_TXQCTL_VID_MASK) >> FM10K_TXQCTL_VID_SHIFT;
+	/* Read the ITR scale from TDLEN. See the definition of
+	 * FM10K_TDLEN_ITR_SCALE_SHIFT for more information about how TDLEN is
+	 * used here.
+	 */
 	hw->mac.itr_scale = (FM10K_READ_REG(hw, FM10K_TDLEN(0)) &
 			     FM10K_TDLEN_ITR_SCALE_MASK) >>
 			    FM10K_TDLEN_ITR_SCALE_SHIFT;
-- 
1.9.3