aboutsummaryrefslogtreecommitdiff
path: root/docs/devel
diff options
context:
space:
mode:
authorPeter Maydell <peter.maydell@linaro.org>2017-07-07 15:42:57 +0100
committerPeter Maydell <peter.maydell@linaro.org>2017-07-14 17:59:42 +0100
commit2286468faceccb54a102e66331a40f7ab45f412c (patch)
tree6f5dcfdc69e96661b3560ef81a90f25267b95549 /docs/devel
parentce66d778cd7d2dc446b3676d32a70c38a07de554 (diff)
docs/devel/memory.txt: Add section about RAM migration
Add a section to docs/devel/memory.txt about migration of the backing memory for RAM regions. Signed-off-by: Peter Maydell <peter.maydell@linaro.org> Reviewed-by: Paolo Bonzini <pbonzini@redhat.com> Message-id: 1499438577-7674-12-git-send-email-peter.maydell@linaro.org
Diffstat (limited to 'docs/devel')
-rw-r--r--docs/devel/memory.txt31
1 files changed, 31 insertions, 0 deletions
diff --git a/docs/devel/memory.txt b/docs/devel/memory.txt
index 811b1bd3c5..8ed810f8b9 100644
--- a/docs/devel/memory.txt
+++ b/docs/devel/memory.txt
@@ -91,6 +91,37 @@ one of whose subregions is a low priority "background" region covering
the whole address range; this is often clearer and is preferred.
Subregions cannot be added to an alias region.
+Migration
+---------
+
+Where the memory region is backed by host memory (RAM, ROM and
+ROM device memory region types), this host memory needs to be
+copied to the destination on migration. These APIs which allocate
+the host memory for you will also register the memory so it is
+migrated:
+ - memory_region_init_ram()
+ - memory_region_init_rom()
+ - memory_region_init_rom_device()
+
+For most devices and boards this is the correct thing. If you
+have a special case where you need to manage the migration of
+the backing memory yourself, you can call the functions:
+ - memory_region_init_ram_nomigrate()
+ - memory_region_init_rom_nomigrate()
+ - memory_region_init_rom_device_nomigrate()
+which only initialize the MemoryRegion and leave handling
+migration to the caller.
+
+The functions:
+ - memory_region_init_resizeable_ram()
+ - memory_region_init_ram_from_file()
+ - memory_region_init_ram_from_fd()
+ - memory_region_init_ram_ptr()
+ - memory_region_init_ram_device_ptr()
+are for special cases only, and so they do not automatically
+register the backing memory for migration; the caller must
+manage migration if necessary.
+
Region names
------------