[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[Qemu-devel] [PATCH 01/11] include/hw/boards.h: Document memory_region_a
From: |
Peter Maydell |
Subject: |
[Qemu-devel] [PATCH 01/11] include/hw/boards.h: Document memory_region_allocate_system_memory() |
Date: |
Fri, 7 Jul 2017 15:42:47 +0100 |
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,
+ * 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
- [Qemu-devel] [PATCH 00/11] Make memory_region_init_ram() and friends handle migration, Peter Maydell, 2017/07/07
- [Qemu-devel] [PATCH 01/11] include/hw/boards.h: Document memory_region_allocate_system_memory(),
Peter Maydell <=
- [Qemu-devel] [PATCH 11/11] docs/devel/memory.txt: Add section about RAM migration, Peter Maydell, 2017/07/07
- [Qemu-devel] [PATCH 10/11] hw/display/qxl.c Use memory_region_init_ram(), Peter Maydell, 2017/07/07
- [Qemu-devel] [PATCH 09/11] hw/pci/pci.c: Use memory_region_init_rom(), Peter Maydell, 2017/07/07
- [Qemu-devel] [PATCH 08/11] hw/block/pflash_cfi01, pflash_cfi02: Use memory_region_init_rom_device(), Peter Maydell, 2017/07/07
- [Qemu-devel] [PATCH 06/11] scripts/coccinelle/memory-region-init-ram.cocci: New script, Peter Maydell, 2017/07/07
- [Qemu-devel] [PATCH 05/11] memory.h: Add memory_region_init_{ram, rom, rom_device}() handling migration, Peter Maydell, 2017/07/07
- [Qemu-devel] [PATCH 04/11] memory: Rename memory_region_init_rom() and _rom_device() to _nomigrate(), Peter Maydell, 2017/07/07
- [Qemu-devel] [PATCH 02/11] memory: Document that the RAM MR initializers do not handle migration, Peter Maydell, 2017/07/07