[PATCH 2/6] nova-core: doc: Clarify sysmembar operations

[Joel Fernandes]

sysmembar is a critical operation that the GSP falcon needs to perform
in the reset sequence. Add some code comments to clarify.

Signed-off-by: Joel Fernandes <joelagnelf at nvidia.com>
---
 drivers/gpu/nova-core/gpu.rs  | 11 ++++++++++-
 drivers/gpu/nova-core/regs.rs |  2 ++
 2 files changed, 12 insertions(+), 1 deletion(-)

diff --git a/drivers/gpu/nova-core/gpu.rs b/drivers/gpu/nova-core/gpu.rs
index 4d03a0b11b64..61031bccb7d3 100644
--- a/drivers/gpu/nova-core/gpu.rs
+++ b/drivers/gpu/nova-core/gpu.rs
@@ -158,6 +158,9 @@ pub(crate) struct Gpu {
     /// MMIO mapping of PCI BAR 0
     bar: Devres<Bar0>,
     fw: Firmware,
+    /// A system memory page for sysmembar (A GPU-initiated hardware memory-barrier
+    /// operation that flushes all pending GPU-side memory writes that were done
+    /// through PCIE, to system memory).
     sysmem_flush: DmaObject,
     timer: Timer,
     bios: Vbios,
@@ -204,7 +207,13 @@ pub(crate) fn new(
         devinit::wait_gfw_boot_completion(&bar)
             .inspect_err(|_| pr_err!("GFW boot did not complete"))?;
 
-        // System memory page required for sysmembar to properly flush into system memory.
+        // System memory page required for sysmembar which is a GPU-initiated hardware
+        // memory-barrier operation that flushes all pending GPU-side memory writes that
+        // were done through PCIE, to system memory. It is required for Falcon to be reset
+        // as the reset operation involves a reset handshake. When the falcon acks the
+        // reset, it writes its acknowledgement into system memory, but for this write to
+        // be visible to the host, the falcon needs to do sysmembar to flush
+        // its writes and prevent the driver from timing out.
         let sysmem_flush = {
             let page = DmaObject::new(
                 pdev.as_ref(),
diff --git a/drivers/gpu/nova-core/regs.rs b/drivers/gpu/nova-core/regs.rs
index f4a6a382e83f..22906ab1a43a 100644
--- a/drivers/gpu/nova-core/regs.rs
+++ b/drivers/gpu/nova-core/regs.rs
@@ -37,6 +37,8 @@
 
 /* PFB */
 
+/// These two registers together hold the physical system memory address
+/// that is used by the GPU for perform sysmembar operation (see gpu.rs).
 register!(PfbNisoFlushSysmemAddr at 0x00100c10;
     31:0    adr_39_08 => as u32
 );
-- 
2.43.0