mirror of
https://github.com/yuzu-emu/unicorn.git
synced 2025-07-07 14:00:40 +00:00
include/hw/boards.h: Document memory_region_allocate_system_memory()
Add a documentation comment for memory_region_allocate_system_memory(). In particular, the reason for this function's existence and the requirement on board code to call it exactly once are non-obvious. Backports commit 09ad643823dcda0a86eddce1291c28d0ccb09a3b from qemu
This commit is contained in:
parent
fe4152c6a5
commit
3c2d3d8363
|
@ -25,6 +25,34 @@ struct QEMUMachine {
|
||||||
int minimum_page_bits;
|
int minimum_page_bits;
|
||||||
};
|
};
|
||||||
|
|
||||||
|
/**
|
||||||
|
* memory_region_allocate_system_memory - Allocate a board's main memory
|
||||||
|
* @mr: the #MemoryRegion to be initialized
|
||||||
|
* @owner: the object that tracks the region's reference count
|
||||||
|
* @name: name of the memory region
|
||||||
|
* @ram_size: size of the region in bytes
|
||||||
|
*
|
||||||
|
* This function allocates the main memory for a board model, and
|
||||||
|
* initializes @mr appropriately. It also arranges for the memory
|
||||||
|
* to be migrated (by calling vmstate_register_ram_global()).
|
||||||
|
*
|
||||||
|
* Memory allocated via this function will be backed with the memory
|
||||||
|
* backend the user provided using "-mem-path" or "-numa node,memdev=..."
|
||||||
|
* if appropriate; this is typically used to cause host huge pages to be
|
||||||
|
* used. This function should therefore be called by a board exactly once,
|
||||||
|
* for the primary or largest RAM area it implements.
|
||||||
|
*
|
||||||
|
* For boards where the major RAM is split into two parts in the memory
|
||||||
|
* map, you can deal with this by calling memory_region_allocate_system_memory()
|
||||||
|
* once to get a MemoryRegion with enough RAM for both parts, and then
|
||||||
|
* creating alias MemoryRegions via memory_region_init_alias() which
|
||||||
|
* alias into different parts of the RAM MemoryRegion and can be mapped
|
||||||
|
* into the memory map in the appropriate places.
|
||||||
|
*
|
||||||
|
* Smaller pieces of memory (display RAM, static RAMs, etc) don't need
|
||||||
|
* to be backed via the -mem-path memory backend and can simply
|
||||||
|
* be created via memory_region_init_ram().
|
||||||
|
*/
|
||||||
void memory_region_allocate_system_memory(MemoryRegion *mr, Object *owner,
|
void memory_region_allocate_system_memory(MemoryRegion *mr, Object *owner,
|
||||||
const char *name,
|
const char *name,
|
||||||
uint64_t ram_size);
|
uint64_t ram_size);
|
||||||
|
|
Loading…
Reference in a new issue