[PATCH v2 2/7] 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  | 12 +++++++++---
 drivers/gpu/nova-core/regs.rs |  2 ++
 2 files changed, 11 insertions(+), 3 deletions(-)

diff --git a/drivers/gpu/nova-core/gpu.rs b/drivers/gpu/nova-core/gpu.rs
index a46768d18ac3..9bd73755c466 100644
--- a/drivers/gpu/nova-core/gpu.rs
+++ b/drivers/gpu/nova-core/gpu.rs
@@ -169,8 +169,8 @@ pub(crate) struct Gpu {
     /// MMIO mapping of PCI BAR 0
     bar: Devres<Bar0>,
     fw: Firmware,
-    // System memory page required for flushing all pending GPU-side memory writes done through
-    // PCIE into system memory.
+    /// System memory page required for flushing all pending GPU-side memory writes done through
+    /// PCIE into system memory, via sysmembar (A GPU-initiated HW memory-barrier operation).
     sysmem_flush: DmaObject,
 }
 
@@ -215,7 +215,13 @@ pub(crate) fn new(
         devinit::wait_gfw_boot_completion(&bar)
             .inspect_err(|_| dev_err!(pdev.as_ref(), "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(), kernel::bindings::PAGE_SIZE)?;
 
diff --git a/drivers/gpu/nova-core/regs.rs b/drivers/gpu/nova-core/regs.rs
index a2b506883654..dcac7ab4619f 100644
--- a/drivers/gpu/nova-core/regs.rs
+++ b/drivers/gpu/nova-core/regs.rs
@@ -52,6 +52,8 @@ pub(crate) fn chipset(self) -> Result<Chipset, Error> {
 
 /* PFB */
 
+// These two registers together hold the physical system memory address
+// that is used by the GPU for perform sysmembar operation (see [`crate::gpu`]).
 register!(NV_PFB_NISO_FLUSH_SYSMEM_ADDR @ 0x00100c10 {
     31:0    adr_39_08 as u32;
 });
-- 
2.43.0