From nobody Wed Nov 5 09:02:11 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 1499438677643177.29210013086265; Fri, 7 Jul 2017 07:44:37 -0700 (PDT) Received: from localhost ([::1]:56887 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1dTUUl-0006k4-5o for importer@patchew.org; Fri, 07 Jul 2017 10:44:35 -0400 Received: from eggs.gnu.org ([2001:4830:134:3::10]:54429) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1dTUTP-0005qE-Mz for qemu-devel@nongnu.org; Fri, 07 Jul 2017 10:43:12 -0400 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1dTUTO-00042s-Ov for qemu-devel@nongnu.org; Fri, 07 Jul 2017 10:43:11 -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 1dTUTO-00040L-HI for qemu-devel@nongnu.org; Fri, 07 Jul 2017 10:43:10 -0400 Received: from pm215 by orth.archaic.org.uk with local (Exim 4.84_2) (envelope-from ) id 1dTUTD-0005sK-6Y; Fri, 07 Jul 2017 15:42:59 +0100 From: Peter Maydell To: qemu-devel@nongnu.org Date: Fri, 7 Jul 2017 15:42:47 +0100 Message-Id: <1499438577-7674-2-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 01/11] include/hw/boards.h: Document memory_region_allocate_system_memory() 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 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 --- 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" =20 +/** + * 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_me= mory() + * 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); --=20 2.7.4