[RFC 14/26] memory: Expose interfaces about Flatview reference count to Rust side

[Zhao Liu <zhao1.liu@intel.com>]

Expose the following interfaces in include/system/memory.h without
`inline`:

* address_space_to_flatview
* flatview_ref
* flatview_unref

Then Rust side could generate related bindings.

In addtion, add documentations for these 3 interface.

Signed-off-by: Zhao Liu <zhao1.liu@intel.com>
---
 include/system/memory.h  | 69 +++++++++++++++++++++++++++++++++++++---
 system/memory-internal.h |  1 -
 system/memory.c          |  7 +++-
 3 files changed, 71 insertions(+), 6 deletions(-)

diff --git a/include/system/memory.h b/include/system/memory.h
index e2cd6ed12614..4b9a2f528d86 100644
--- a/include/system/memory.h
+++ b/include/system/memory.h
@@ -1203,10 +1203,71 @@ struct FlatView {
     MemoryRegion *root;
 };
 
-static inline FlatView *address_space_to_flatview(AddressSpace *as)
-{
-    return qatomic_rcu_read(&as->current_map);
-}
+/**
+ * address_space_to_flatview: Get a transient RCU-protected pointer to
+ * the current FlatView.
+ *
+ * @as: The #AddressSpace to be accessed.
+ *
+ * This function retrieves a pointer to the current #FlatView for the
+ * given #AddressSpace.
+ *
+ * Note: This is a low-level, RCU-based accessor. It DOES NOT increment
+ * the FlatView's reference count. The returned pointer is only
+ * guaranteed to be valid within an RCU read-side critical section.
+ *
+ * Difference from address_space_get_flatview():
+ *
+ * For address_space_to_flatview() (this function), it is a lightweight
+ * "peek" operation. It is fast but unsafe for long-term use. Use it
+ * only for very short-lived access where performance is critical.
+ *
+ * For address_space_get_flatview(), it acquires a "strong" reference
+ * by safely incrementing the reference count. The returned pointer is
+ * stable and can be used for long-lived operations, even outside an
+ * RCU lock. It is the safer and generally preferred method, but it
+ * MUST be paired with a call to flatview_unref() after the use of
+ * #FlatView.
+ *
+ * Returns:
+ * A transient pointer to the current #FlatView, valid only under RCU
+ * protection.
+ */
+FlatView *address_space_to_flatview(AddressSpace *as);
+
+/**
+ * flatview_ref: Atomically increment the reference count of #FlatView.
+ *
+ * @view: The #FlatView whose reference count is to be incremented.
+ *
+ * This function attempts to atomically increment the reference count
+ * of the given @view. This operation is conditional and will only
+ * succeed if the current reference count is non-zero.
+ *
+ * A non-zero reference count indicates that the FlatView is live and
+ * in use. If the reference count is already zero, it indicates that the
+ * FlatView is being deinitialized, and no new references can be
+ * acquired.
+ *
+ * Returns:
+ * 'true' if the reference count was successfully incremented (i.e., it
+ * was non-zero before the call).
+ * 'false' if the reference count was already zero and could not be
+ * incremented.
+ */
+bool flatview_ref(FlatView *view);
+
+/**
+ * flatview_unref: Atomically decrement the reference count of
+ * #FlatView.
+ *
+ * @view: The #FlatView to be unreferenced.
+ *
+ * This function atomically decrements the reference count of the given
+ * @view. When the reference count drops to zero, #FlatView will be
+ * destroied via RCU.
+ */
+void flatview_unref(FlatView *view);
 
 /**
  * typedef flatview_cb: callback for flatview_for_each_range()
diff --git a/system/memory-internal.h b/system/memory-internal.h
index 46f758fa7e47..b0870a6359c3 100644
--- a/system/memory-internal.h
+++ b/system/memory-internal.h
@@ -26,7 +26,6 @@ static inline AddressSpaceDispatch *address_space_to_dispatch(AddressSpace *as)
 }
 
 FlatView *address_space_get_flatview(AddressSpace *as);
-void flatview_unref(FlatView *view);
 
 extern const MemoryRegionOps unassigned_mem_ops;
 
diff --git a/system/memory.c b/system/memory.c
index 56465479406f..2a749081fb50 100644
--- a/system/memory.c
+++ b/system/memory.c
@@ -304,7 +304,7 @@ static void flatview_destroy(FlatView *view)
     g_free(view);
 }
 
-static bool flatview_ref(FlatView *view)
+bool flatview_ref(FlatView *view)
 {
     return qatomic_fetch_inc_nonzero(&view->ref) > 0;
 }
@@ -818,6 +818,11 @@ static void address_space_add_del_ioeventfds(AddressSpace *as,
     }
 }
 
+FlatView *address_space_to_flatview(AddressSpace *as)
+{
+    return qatomic_rcu_read(&as->current_map);
+}
+
 FlatView *address_space_get_flatview(AddressSpace *as)
 {
     FlatView *view;
-- 
2.34.1