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