friedkiwi/qemu
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

system: Document cpu_physical_memory_*() declarations

Browse Source 
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>
This commit is contained in:
Philippe Mathieu-Daudé
2026-06-11 09:36:57 +02:00
parent 77293ecc95
commit 54ec3bf9da
2 changed files with 47 additions and 4 deletions
Download Patch File Download Diff File Expand all files Collapse all files

10
docs/devel/loads-stores.rst
View File

@@ -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``

41
include/exec/cpu-common.h
View File

@@ -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);