Rust side will based on MemoryRegionSection to origanize non-overlapping
memory "region" abstractions. So it's necessary to provide a translation
variant helper to return the MemoryRegionSection directly.

Additionally, refine and complete the documentations for translation
helpers.

Signed-off-by: Zhao Liu <zhao1.liu@intel.com>
---
 include/system/memory.h | 68 +++++++++++++++++++++++++++++++++++------
 system/physmem.c        | 22 ++++++++++---
 2 files changed, 77 insertions(+), 13 deletions(-)

diff --git a/include/system/memory.h b/include/system/memory.h
index f492e1fc78bf..eab69e15e10f 100644
--- a/include/system/memory.h
+++ b/include/system/memory.h
@@ -3053,24 +3053,74 @@ void address_space_cache_destroy(MemoryRegionCache *cache);
 IOMMUTLBEntry address_space_get_iotlb_entry(AddressSpace *as, hwaddr addr,
                                             bool is_write, MemTxAttrs attrs);
 
-/* address_space_translate: translate an address range into an address space
- * into a MemoryRegion and an address range into that section.  Should be
+/**
+ * flatview_translate_section: translate an guest physical address range
+ * to the corresponding MemoryRegionSection in Flatview. Should be
  * called from an RCU critical section, to avoid that the last reference
- * to the returned region disappears after address_space_translate returns.
- *
- * @fv: #FlatView to be accessed
- * @addr: address within that address space
- * @xlat: pointer to address within the returned memory region section's
- * #MemoryRegion.
- * @len: pointer to length
+ * to the memory region (pointed by returned section) disappears after
+ * flatview_translate_section returns.
+ *
+ * @fv: the flat view to be accessed.
+ * @addr: the address to be translated in above address space.
+ * @xlat: the translated address offset within the returned section's
+ *        #MemoryRegion.
+ * @len: pointer to length, and it will be changed to valid read/write
+ *       length of the translated address after this function returns.
  * @is_write: indicates the transfer direction
  * @attrs: memory attributes
+ *
+ * Returns:
+ * The #MemoryRegionSection that contains the translated address
+ */
+MemoryRegionSection *flatview_translate_section(FlatView *fv, hwaddr addr,
+                                                hwaddr *xlat, hwaddr *len,
+                                                bool is_write, MemTxAttrs attrs);
+
+/**
+ * flatview_translate: translate an guest physical address range
+ * to the corresponding MemoryRegionSection in Flatview. Should be
+ * called from an RCU critical section, to avoid that the last reference
+ * to the returned memory region disappears after flatview_translate
+ * returns.
+ *
+ * This function is the variant of flatview_translate_section(), with the
+ * difference that it returns the MemoryRegion contained in the
+ * MemoryRegionSection.
+ *
+ * @fv: the flat view to be accessed.
+ * @addr: the address to be translated in above address space.
+ * @xlat: the translated address offset within memory region.
+ * @len: pointer to length, and it will be changed to valid read/write
+ *       length of the translated address after this function returns.
+ * @is_write: whether the translation operation is for write.
+ * @attrs: memory transaction attributes.
+ *
+ * Returns:
+ * The #MemoryRegion that contains the translated address.
  */
 MemoryRegion *flatview_translate(FlatView *fv,
                                  hwaddr addr, hwaddr *xlat,
                                  hwaddr *len, bool is_write,
                                  MemTxAttrs attrs);
 
+/**
+ * address_space_translate: translate an guest physical address range
+ * to the corresponding MemoryRegionSection in Flatview. Should be
+ * called from an RCU critical section, to avoid that the last reference
+ * to the returned memory region disappears after flatview_translate
+ * returns.
+ *
+ * This function is the variant of flatview_translate(), with the difference
+ * that it accesses the AddressSpace which contains FlatView.
+ *
+ * @as: #AddressSpace to be accessed
+ * @addr: the address to be translated in above address space.
+ * @xlat: the translated address offset within memory region.
+ * @len: pointer to length, and it will be changed to valid read/write
+ *       length of the translated address after this function returns.
+ * @is_write: whether the translation operation is for write.
+ * @attrs: memory transaction attributes.
+ */
 static inline MemoryRegion *address_space_translate(AddressSpace *as,
                                                     hwaddr addr, hwaddr *xlat,
                                                     hwaddr *len, bool is_write,
diff --git a/system/physmem.c b/system/physmem.c
index 4af29ea2168e..d2106d0ffa87 100644
--- a/system/physmem.c
+++ b/system/physmem.c
@@ -559,9 +559,9 @@ iotlb_fail:
 }
 
 /* Called from RCU critical section */
-MemoryRegion *flatview_translate(FlatView *fv, hwaddr addr, hwaddr *xlat,
-                                 hwaddr *plen, bool is_write,
-                                 MemTxAttrs attrs)
+MemoryRegionSection *flatview_translate_section(FlatView *fv, hwaddr addr,
+                                                hwaddr *xlat, hwaddr *plen,
+                                                bool is_write, MemTxAttrs attrs)
 {
     MemoryRegion *mr;
     MemoryRegionSection *section;
@@ -577,7 +577,21 @@ MemoryRegion *flatview_translate(FlatView *fv, hwaddr addr, hwaddr *xlat,
         *plen = MIN(page, *plen);
     }
 
-    return mr;
+    return section;
+}
+
+/* Called from RCU critical section */
+MemoryRegion *flatview_translate(FlatView *fv, hwaddr addr, hwaddr *xlat,
+                                 hwaddr *plen, bool is_write,
+                                 MemTxAttrs attrs)
+{
+    MemoryRegionSection *section;
+
+    /* This can be MMIO, so setup MMIO bit. */
+    section = flatview_translate_section(fv, addr, xlat, plen,
+                                         is_write, attrs);
+
+    return section->mr;
 }
 
 #ifdef CONFIG_TCG
-- 
2.34.1