include/hw/boards.h: Document memory_region_allocate_system_memory()

#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" 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,

                                          const char *name,

                                          uint64_t ram_size);