From nobody Wed Nov 5 09:13:51 2025 Delivered-To: importer@patchew.org Received-SPF: pass (zoho.com: domain of gnu.org designates 208.118.235.17 as permitted sender) client-ip=208.118.235.17; envelope-from=qemu-devel-bounces+importer=patchew.org@nongnu.org; helo=lists.gnu.org; Authentication-Results: mx.zohomail.com; spf=pass (zoho.com: domain of gnu.org designates 208.118.235.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org Return-Path: Received: from lists.gnu.org (lists.gnu.org [208.118.235.17]) by mx.zohomail.com with SMTPS id 1499438681466958.6401446591287; Fri, 7 Jul 2017 07:44:41 -0700 (PDT) Received: from localhost ([::1]:56888 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1dTUUo-0006nk-79 for importer@patchew.org; Fri, 07 Jul 2017 10:44:38 -0400 Received: from eggs.gnu.org ([2001:4830:134:3::10]:54441) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1dTUTQ-0005qF-Ce for qemu-devel@nongnu.org; Fri, 07 Jul 2017 10:43:13 -0400 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1dTUTP-00043L-I9 for qemu-devel@nongnu.org; Fri, 07 Jul 2017 10:43:12 -0400 Received: from orth.archaic.org.uk ([2001:8b0:1d0::2]:37441) by eggs.gnu.org with esmtps (TLS1.0:RSA_AES_128_CBC_SHA1:16) (Exim 4.71) (envelope-from ) id 1dTUTP-00040L-Az for qemu-devel@nongnu.org; Fri, 07 Jul 2017 10:43:11 -0400 Received: from pm215 by orth.archaic.org.uk with local (Exim 4.84_2) (envelope-from ) id 1dTUTJ-0005w4-A1; Fri, 07 Jul 2017 15:43:05 +0100 From: Peter Maydell To: qemu-devel@nongnu.org Date: Fri, 7 Jul 2017 15:42:57 +0100 Message-Id: <1499438577-7674-12-git-send-email-peter.maydell@linaro.org> X-Mailer: git-send-email 2.7.4 In-Reply-To: <1499438577-7674-1-git-send-email-peter.maydell@linaro.org> References: <1499438577-7674-1-git-send-email-peter.maydell@linaro.org> X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.2.x-3.x [generic] X-Received-From: 2001:8b0:1d0::2 Subject: [Qemu-devel] [PATCH 11/11] docs/devel/memory.txt: Add section about RAM migration X-BeenThere: qemu-devel@nongnu.org X-Mailman-Version: 2.1.21 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Cc: Marcel Apfelbaum , Paolo Bonzini , Igor Mammedov , Eduardo Habkost , patches@linaro.org Errors-To: qemu-devel-bounces+importer=patchew.org@nongnu.org Sender: "Qemu-devel" X-ZohoMail: RSF_0 Z_629925259 SPT_0 Content-Transfer-Encoding: quoted-printable MIME-Version: 1.0 Content-Type: text/plain; charset="utf-8" Add a section to docs/devel/memory.txt about migration of the backing memory for RAM regions. Signed-off-by: Peter Maydell --- docs/devel/memory.txt | 31 +++++++++++++++++++++++++++++++ 1 file changed, 31 insertions(+) diff --git a/docs/devel/memory.txt b/docs/devel/memory.txt index 811b1bd..8ed810f 100644 --- a/docs/devel/memory.txt +++ b/docs/devel/memory.txt @@ -91,6 +91,37 @@ one of whose subregions is a low priority "background" r= egion covering the whole address range; this is often clearer and is preferred. Subregions cannot be added to an alias region. =20 +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 ------------ =20 --=20 2.7.4