system: Document cpu_physical_memory_*() declarations
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>
Philippe Mathieu-Daudé committed
Jun 11, 2026 at 09:36 UTC
54ec3bf9da8e6c5fce170aed882e738ac229a67e
2 files changed
+47
-4
docs/devel/loads-stores.rst
+6
-4
@@ -443,15 +443,17 @@ Regexes for git grep:
443
~~~~~~~~~~~~~~~~~~~~~~~~~
444
445
These are convenience functions which are identical to
446
-``address_space_*`` but operate specifically on the system address space,
447
-always pass a ``MEMTXATTRS_UNSPECIFIED`` set of memory attributes and
448
-ignore whether the memory transaction succeeded or failed.
449
-For new code they are better avoided:
446
+``address_space_*`` but operate specifically on the legacy global
447
+``&address_space_memory`` address space (which might not be used by all
448
+machines), always pass a ``MEMTXATTRS_UNSPECIFIED`` set of memory attributes
449
+and ignore whether the memory transaction succeeded or failed. Expected
450
+users are hardware device models. For new code they are better avoided:
451
452
* there is likely to be behaviour you need to model correctly for a
453
failed read or write operation
454
* a device should usually perform operations on its own AddressSpace
455
rather than using the system address space
456
+* some machines do not use this global address space at all
457
458
``cpu_physical_memory_read``
459
include/exec/cpu-common.h
+41
@@ -64,11 +64,52 @@ void cpu_address_space_init(CPUState *cpu, int asidx,
64
*/
65
void cpu_destroy_address_spaces(CPUState *cpu);
66
67
+/**
68
+ * cpu_physical_memory_read: Read from the legacy global address space.
69
+ *
70
+ * This function access the legacy global #address_space_memory address
71
+ * space and does not say whether the operation succeeded or failed.
72
+ *
73
+ * @addr: address within the legacy global address space
74
+ * @buf: buffer with the data transferred
75
+ * @len: length of the data transferred
76
+ */
77
void cpu_physical_memory_read(hwaddr addr, void *buf, hwaddr len);
78
+/**
79
+ * cpu_physical_memory_write: Write to the legacy global address space.
80
+ *
81
+ * This function access the legacy global #address_space_memory address
82
+ * space and does not say whether the operation succeeded or failed.
83
+ *
84
+ * @addr: address within the legacy global address space
85
+ * @buf: buffer with the data transferred
86
+ * @len: the number of bytes to write
87
+ */
88
void cpu_physical_memory_write(hwaddr addr, const void *buf, hwaddr len);
89
+/**
90
+ * cpu_physical_memory_map: Map guest physical memory region into host virtual
91
+ * address.
92
+ *
93
+ * Map a memory region from the legacy global #address_space_memory address
94
+ * space. May return %NULL and set *@plen to zero(0), if resources needed to
95
+ * perform the mapping are exhausted.
96
+ *
97
+ * @addr: address within that address space
98
+ * @len: pointer to length of buffer; updated on return
99
+ * @is_write: whether the translation operation is for write
100
+ */
101
void *cpu_physical_memory_map(hwaddr addr,
102
hwaddr *plen,
103
bool is_write);
104
+/**
105
+ * cpu_physical_memory_unmap: Unmaps a memory region previously mapped by
106
+ * cpu_physical_memory_map()
107
+ *
108
+ * @buffer: host pointer as returned by cpu_physical_memory_map()
109
+ * @len: buffer length as returned by cpu_physical_memory_map()
110
+ * @is_write: whether the translation operation is for write
111
+ * @access_len: amount of data actually transferred
112
+ */
113
void cpu_physical_memory_unmap(void *buffer, hwaddr len,
114
bool is_write, hwaddr access_len);
115