Re: [Qemu-devel] [PATCH 1/3] include/hw/boards.h: Document memory_region_allocate_system_memory()

[Paolo Bonzini]

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

Re: [Qemu-devel] [PATCH 1/3] include/hw/boards.h: Document memory_region_allocate_system_memory()

[Philippe Mathieu-Daudé]

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

[Qemu-devel] [PATCH 1/3] include/hw/boards.h: Document memory_region_allocate_system_memory()

[Peter Maydell]

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 
---
 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,
+ * 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);
-- 
2.7.4