From a5c0234bb2754f5248e67929a34c843dbe039da5 Mon Sep 17 00:00:00 2001 From: Peter Maydell Date: Fri, 7 Jul 2017 15:42:48 +0100 Subject: [PATCH] memory: Document that the RAM MR initializers do not handle migration The various functions for initializing RAM MemoryRegions do not do anything to cause the data in the MemoryRegion to be migrated. Note in their documentation comments that this is the responsibility of the caller. (We will shortly add a new function that *does* do this for you.) Signed-off-by: Peter Maydell Reviewed-by: Paolo Bonzini Message-id: 1499438577-7674-3-git-send-email-peter.maydell@linaro.org --- include/exec/memory.h | 19 +++++++++++++++++++ 1 file changed, 19 insertions(+) diff --git a/include/exec/memory.h b/include/exec/memory.h index b7966014fe..a506e84efe 100644 --- a/include/exec/memory.h +++ b/include/exec/memory.h @@ -429,6 +429,9 @@ void memory_region_init_io(MemoryRegion *mr, * must be unique within any device * @size: size of the region. * @errp: pointer to Error*, to store an error if it happens. + * + * Note that this function does not do anything to cause the data in the + * RAM memory region to be migrated; that is the responsibility of the caller. */ void memory_region_init_ram(MemoryRegion *mr, struct Object *owner, @@ -451,6 +454,9 @@ void memory_region_init_ram(MemoryRegion *mr, * @max_size: max size of the region. * @resized: callback to notify owner about used size change. * @errp: pointer to Error*, to store an error if it happens. + * + * Note that this function does not do anything to cause the data in the + * RAM memory region to be migrated; that is the responsibility of the caller. */ void memory_region_init_resizeable_ram(MemoryRegion *mr, struct Object *owner, @@ -474,6 +480,9 @@ void memory_region_init_resizeable_ram(MemoryRegion *mr, * @share: %true if memory must be mmaped with the MAP_SHARED flag * @path: the path in which to allocate the RAM. * @errp: pointer to Error*, to store an error if it happens. + * + * Note that this function does not do anything to cause the data in the + * RAM memory region to be migrated; that is the responsibility of the caller. */ void memory_region_init_ram_from_file(MemoryRegion *mr, struct Object *owner, @@ -494,6 +503,9 @@ void memory_region_init_ram_from_file(MemoryRegion *mr, * @share: %true if memory must be mmaped with the MAP_SHARED flag * @fd: the fd to mmap. * @errp: pointer to Error*, to store an error if it happens. + * + * Note that this function does not do anything to cause the data in the + * RAM memory region to be migrated; that is the responsibility of the caller. */ void memory_region_init_ram_from_fd(MemoryRegion *mr, struct Object *owner, @@ -515,6 +527,9 @@ void memory_region_init_ram_from_fd(MemoryRegion *mr, * must be unique within any device * @size: size of the region. * @ptr: memory to be mapped; must contain at least @size bytes. + * + * Note that this function does not do anything to cause the data in the + * RAM memory region to be migrated; that is the responsibility of the caller. */ void memory_region_init_ram_ptr(MemoryRegion *mr, struct Object *owner, @@ -539,6 +554,10 @@ void memory_region_init_ram_ptr(MemoryRegion *mr, * @name: the name of the region. * @size: size of the region. * @ptr: memory to be mapped; must contain at least @size bytes. + * + * Note that this function does not do anything to cause the data in the + * RAM memory region to be migrated; that is the responsibility of the caller. + * (For RAM device memory regions, migrating the contents rarely makes sense.) */ void memory_region_init_ram_device_ptr(MemoryRegion *mr, struct Object *owner,