On 06/07/2017 05:18, Philippe Mathieu-Daudé wrote: > Hi Peter, Paolo, > > On 07/04/2017 02:02 PM, Peter Maydell wrote: >> 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. >> >> Signed-off-by: Peter Maydell <peter.mayd...@linaro.org> >> --- >> include/hw/boards.h | 28 ++++++++++++++++++++++++++++ >> 1 file changed, 28 insertions(+) >> >> diff --git a/include/hw/boards.h b/include/hw/boards.h >> index 76ce021..1bc5389 100644 >> --- a/include/hw/boards.h >> +++ b/include/hw/boards.h >> @@ -9,6 +9,34 @@ >> #include "qom/object.h" >> #include "qom/cpu.h" >> +/** >> + * 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 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, > > Using memory-backend-file objects one can use different mem-path. > > Maybe removing the global mem_path used by vl.c for "main memory" (which > is a memory-backend-file without naming it) this "exactly once" case can > be avoided.
It's already the case that you can use different mem-paths and different host node bindings, though you still have to associate one memory backend to each "-numa node" option (via "-numa node,memdev=..."). The function has to be called only once because it consumes all the "-m" and "-numa node,memdev=..." options. Paolo >> + * 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, >> const char *name, >> uint64_t ram_size); >>