From 55070cd235bdb01b557233546d0bbdc0e4b62b8b Mon Sep 17 00:00:00 2001
From: Niklas Eiling <niklas.eiling@eonerc.rwth-aachen.de>
Date: Thu, 18 Apr 2024 10:32:00 +0200
Subject: [PATCH] fpga: improve comments for fastRead and fastWrite

Signed-off-by: Niklas Eiling <niklas.eiling@eonerc.rwth-aachen.de>
---
 fpga/include/villas/fpga/ips/dma.hpp | 6 ++++--
 fpga/lib/ips/dma.cpp                 | 2 +-
 lib/nodes/fpga.cpp                   | 6 ++++++
 3 files changed, 11 insertions(+), 3 deletions(-)

diff --git a/fpga/include/villas/fpga/ips/dma.hpp b/fpga/include/villas/fpga/ips/dma.hpp
index e35f7b309..f4175b0df 100644
--- a/fpga/include/villas/fpga/ips/dma.hpp
+++ b/fpga/include/villas/fpga/ips/dma.hpp
@@ -139,11 +139,13 @@ private:
 
   // When using SG: ringBdSize is the maximum number of BDs usable in the ring
   // Depending on alignment, the actual number of BDs usable can be smaller
+  // We use a single BD for transfers, because this way we can achieve the best
+  // latency. The AXI read cache in the FPGA also only supports a single BD.
+  // TODO: We could make this configurable in the future.
   static constexpr size_t requestedRingBdSize = 1;
   static constexpr size_t requestedRingBdSizeMemory =
       requestedRingBdSize * sizeof(XAxiDma_Bd);
-  uint32_t actualRingBdSize = 1; //XAxiDma_BdRingCntCalc(
-      //XAXIDMA_BD_MINIMUM_ALIGNMENT, requestedRingBdSizeMemory);
+  uint32_t actualRingBdSize = 1;
   std::shared_ptr<MemoryBlock> sgRing;
 };
 
diff --git a/fpga/lib/ips/dma.cpp b/fpga/lib/ips/dma.cpp
index 24e6d627a..1ba98d108 100644
--- a/fpga/lib/ips/dma.cpp
+++ b/fpga/lib/ips/dma.cpp
@@ -370,7 +370,7 @@ XAxiDma_Bd *Dma::writeScatterGatherSetupBd(const void *buf, size_t len) {
   return bd;
 }
 
-//Write a single message
+// Write a single message
 bool Dma::writeScatterGather(const void *buf, size_t len) {
   // buf is address from view of DMA controller
 
diff --git a/lib/nodes/fpga.cpp b/lib/nodes/fpga.cpp
index 4781f32f7..c365436e9 100644
--- a/lib/nodes/fpga.cpp
+++ b/lib/nodes/fpga.cpp
@@ -188,6 +188,9 @@ int FpgaNode::start() {
   return Node::start();
 }
 
+// We cannot modify the BD here, so writes are fixed length.
+// If fastWrite receives less signals than expected, the previous data
+// will be reused for the remaining signals
 int FpgaNode::fastWrite(Sample *smps[], unsigned cnt) {
   Sample *smp = smps[0];
 
@@ -222,6 +225,9 @@ int FpgaNode::fastWrite(Sample *smps[], unsigned cnt) {
   return 1;
 }
 
+// Because we cannot modify the BD here, reads are fixed length.
+// However, if we receive less data than expected, we will return only
+// what we have received. fastRead is thus capable of partial reads.
 int FpgaNode::fastRead(Sample *smps[], unsigned cnt) {
   Sample *smp = smps[0];
   auto mem = MemoryAccessor<float>(*blockRx);