Message ID | 1499187763-8211-2-git-send-email-peter.maydell@linaro.org |
---|---|
State | New |
Headers | show |
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.maydell@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. > + * 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); >
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.maydell@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); >>
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, + * 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);
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.maydell@linaro.org> --- include/hw/boards.h | 28 ++++++++++++++++++++++++++++ 1 file changed, 28 insertions(+)