[PULL 08/48] system: Document cpu_physical_memory_*() declarations

["Philippe Mathieu-Daudé" <philmd@oss.qualcomm.com>]

Document the following methods use the global address space
and discard success/failure access information:

     - cpu_physical_memory_read()
     - cpu_physical_memory_write()
     - cpu_physical_memory_map()
     - cpu_physical_memory_unmap()

Signed-off-by: Philippe Mathieu-Daudé <philmd@oss.qualcomm.com>
Reviewed-by: Richard Henderson <richard.henderson@linaro.org>
Message-Id: <20260616020839.19104-2-philmd@oss.qualcomm.com>
---
 docs/devel/loads-stores.rst | 10 +++++----
 include/exec/cpu-common.h   | 41 +++++++++++++++++++++++++++++++++++++
 2 files changed, 47 insertions(+), 4 deletions(-)

diff --git a/docs/devel/loads-stores.rst b/docs/devel/loads-stores.rst
index c719241a7f5..f2c66e44454 100644
--- a/docs/devel/loads-stores.rst
+++ b/docs/devel/loads-stores.rst
@@ -443,15 +443,17 @@ Regexes for git grep:
 ~~~~~~~~~~~~~~~~~~~~~~~~~
 
 These are convenience functions which are identical to
-``address_space_*`` but operate specifically on the system address space,
-always pass a ``MEMTXATTRS_UNSPECIFIED`` set of memory attributes and
-ignore whether the memory transaction succeeded or failed.
-For new code they are better avoided:
+``address_space_*`` but operate specifically on the legacy global
+``&address_space_memory`` address space (which might not be used by all
+machines), always pass a ``MEMTXATTRS_UNSPECIFIED`` set of memory attributes
+and ignore whether the memory transaction succeeded or failed. Expected
+users are hardware device models. For new code they are better avoided:
 
 * there is likely to be behaviour you need to model correctly for a
   failed read or write operation
 * a device should usually perform operations on its own AddressSpace
   rather than using the system address space
+* some machines do not use this global address space at all
 
 ``cpu_physical_memory_read``
 
diff --git a/include/exec/cpu-common.h b/include/exec/cpu-common.h
index 1eb28734601..9cd67d3ef9d 100644
--- a/include/exec/cpu-common.h
+++ b/include/exec/cpu-common.h
@@ -64,11 +64,52 @@ void cpu_address_space_init(CPUState *cpu, int asidx,
  */
 void cpu_destroy_address_spaces(CPUState *cpu);
 
+/**
+ * cpu_physical_memory_read: Read from the legacy global address space.
+ *
+ * This function access the legacy global #address_space_memory address
+ * space and does not say whether the operation succeeded or failed.
+ *
+ * @addr: address within the legacy global address space
+ * @buf: buffer with the data transferred
+ * @len: length of the data transferred
+ */
 void cpu_physical_memory_read(hwaddr addr, void *buf, hwaddr len);
+/**
+ * cpu_physical_memory_write: Write to the legacy global address space.
+ *
+ * This function access the legacy global #address_space_memory address
+ * space and does not say whether the operation succeeded or failed.
+ *
+ * @addr: address within the legacy global address space
+ * @buf: buffer with the data transferred
+ * @len: the number of bytes to write
+ */
 void cpu_physical_memory_write(hwaddr addr, const void *buf, hwaddr len);
+/**
+ * cpu_physical_memory_map: Map guest physical memory region into host virtual
+ *                          address.
+ *
+ * Map a memory region from the legacy global #address_space_memory address
+ * space. May return %NULL and set *@plen to zero(0), if resources needed to
+ * perform the mapping are exhausted.
+ *
+ * @addr: address within that address space
+ * @len: pointer to length of buffer; updated on return
+ * @is_write: whether the translation operation is for write
+ */
 void *cpu_physical_memory_map(hwaddr addr,
                               hwaddr *plen,
                               bool is_write);
+/**
+ * cpu_physical_memory_unmap: Unmaps a memory region previously mapped by
+ *                            cpu_physical_memory_map()
+ *
+ * @buffer: host pointer as returned by cpu_physical_memory_map()
+ * @len: buffer length as returned by cpu_physical_memory_map()
+ * @is_write: whether the translation operation is for write
+ * @access_len: amount of data actually transferred
+ */
 void cpu_physical_memory_unmap(void *buffer, hwaddr len,
                                bool is_write, hwaddr access_len);
 
-- 
2.53.0