From patchwork Tue Feb 9 12:13:48 2016 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Paolo Bonzini X-Patchwork-Id: 8261031 Return-Path: X-Original-To: patchwork-qemu-devel@patchwork.kernel.org Delivered-To: patchwork-parsemail@patchwork2.web.kernel.org Received: from mail.kernel.org (mail.kernel.org [198.145.29.136]) by patchwork2.web.kernel.org (Postfix) with ESMTP id 3CD73BEEE5 for ; Tue, 9 Feb 2016 12:18:48 +0000 (UTC) Received: from mail.kernel.org (localhost [127.0.0.1]) by mail.kernel.org (Postfix) with ESMTP id 88F962022D for ; Tue, 9 Feb 2016 12:18:47 +0000 (UTC) Received: from lists.gnu.org (lists.gnu.org [208.118.235.17]) (using TLSv1 with cipher AES256-SHA (256/256 bits)) (No client certificate requested) by mail.kernel.org (Postfix) with ESMTPS id 8761D2026C for ; Tue, 9 Feb 2016 12:18:46 +0000 (UTC) Received: from localhost ([::1]:55087 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1aT7Fl-0007R8-HC for patchwork-qemu-devel@patchwork.kernel.org; Tue, 09 Feb 2016 07:18:45 -0500 Received: from eggs.gnu.org ([2001:4830:134:3::10]:45916) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1aT7BJ-0000QC-Rt for qemu-devel@nongnu.org; Tue, 09 Feb 2016 07:14:10 -0500 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1aT7BG-000452-MQ for qemu-devel@nongnu.org; Tue, 09 Feb 2016 07:14:09 -0500 Received: from mx1.redhat.com ([209.132.183.28]:52564) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1aT7BG-00044n-9i for qemu-devel@nongnu.org; Tue, 09 Feb 2016 07:14:06 -0500 Received: from int-mx11.intmail.prod.int.phx2.redhat.com (int-mx11.intmail.prod.int.phx2.redhat.com [10.5.11.24]) by mx1.redhat.com (Postfix) with ESMTPS id 0BBA0C0C2352; Tue, 9 Feb 2016 12:14:06 +0000 (UTC) Received: from donizetti.redhat.com (ovpn-112-47.ams2.redhat.com [10.36.112.47]) by int-mx11.intmail.prod.int.phx2.redhat.com (8.14.4/8.14.4) with ESMTP id u19CDqF6027208; Tue, 9 Feb 2016 07:14:04 -0500 From: Paolo Bonzini To: qemu-devel@nongnu.org Date: Tue, 9 Feb 2016 13:13:48 +0100 Message-Id: <1455020031-8268-4-git-send-email-pbonzini@redhat.com> In-Reply-To: <1455020031-8268-1-git-send-email-pbonzini@redhat.com> References: <1455020031-8268-1-git-send-email-pbonzini@redhat.com> X-Scanned-By: MIMEDefang 2.68 on 10.5.11.24 X-detected-operating-system: by eggs.gnu.org: GNU/Linux 3.x X-Received-From: 209.132.183.28 Cc: Peter Maydell Subject: [Qemu-devel] [PULL 29/32] docs/memory.txt: Improve list of different memory regions X-BeenThere: qemu-devel@nongnu.org X-Mailman-Version: 2.1.14 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: qemu-devel-bounces+patchwork-qemu-devel=patchwork.kernel.org@nongnu.org Sender: qemu-devel-bounces+patchwork-qemu-devel=patchwork.kernel.org@nongnu.org X-Spam-Status: No, score=-6.9 required=5.0 tests=BAYES_00, RCVD_IN_DNSWL_HI, UNPARSEABLE_RELAY autolearn=unavailable version=3.3.1 X-Spam-Checker-Version: SpamAssassin 3.3.1 (2010-03-16) on mail.kernel.org X-Virus-Scanned: ClamAV using ClamSMTP From: Peter Maydell Improve the part of the memory region documentation which describes the various different kinds of memory region: * add the missing types ROM, IOMMU and reservation * mention the functions used to initialize each type, as a hint for finding the API docs and examples of use Signed-off-by: Peter Maydell Message-Id: <1454007297-3971-1-git-send-email-peter.maydell@linaro.org> Signed-off-by: Paolo Bonzini --- docs/memory.txt | 26 +++++++++++++++++++++++++- 1 file changed, 25 insertions(+), 1 deletion(-) diff --git a/docs/memory.txt b/docs/memory.txt index 2ceb348..8745f76 100644 --- a/docs/memory.txt +++ b/docs/memory.txt @@ -26,14 +26,28 @@ These represent memory as seen from the CPU or a device's viewpoint. Types of regions ---------------- -There are four types of memory regions (all represented by a single C type +There are multiple types of memory regions (all represented by a single C type MemoryRegion): - RAM: a RAM region is simply a range of host memory that can be made available to the guest. + You typically initialize these with memory_region_init_ram(). Some special + purposes require the variants memory_region_init_resizeable_ram(), + memory_region_init_ram_from_file(), or memory_region_init_ram_ptr(). - MMIO: a range of guest memory that is implemented by host callbacks; each read or write causes a callback to be called on the host. + You initialize these with memory_region_io(), passing it a MemoryRegionOps + structure describing the callbacks. + +- ROM: a ROM memory region works like RAM for reads (directly accessing + a region of host memory), but like MMIO for writes (invoking a callback). + You initialize these with memory_region_init_rom_device(). + +- IOMMU region: an IOMMU region translates addresses of accesses made to it + and forwards them to some other target memory region. As the name suggests, + these are only needed for modelling an IOMMU, not for simple devices. + You initialize these with memory_region_init_iommu(). - container: a container simply includes other memory regions, each at a different offset. Containers are useful for grouping several regions @@ -45,12 +59,22 @@ MemoryRegion): can overlay a subregion of RAM with MMIO or ROM, or a PCI controller that does not prevent card from claiming overlapping BARs. + You initialize a pure container with memory_region_init(). + - alias: a subsection of another region. Aliases allow a region to be split apart into discontiguous regions. Examples of uses are memory banks used when the guest address space is smaller than the amount of RAM addressed, or a memory controller that splits main memory to expose a "PCI hole". Aliases may point to any type of region, including other aliases, but an alias may not point back to itself, directly or indirectly. + You initialize these with memory_region_init_alias(). + +- reservation region: a reservation region is primarily for debugging. + It claims I/O space that is not supposed to be handled by QEMU itself. + The typical use is to track parts of the address space which will be + handled by the host kernel when KVM is enabled. + You initialize these with memory_region_init_reservation(), or by + passing a NULL callback parameter to memory_region_init_io(). It is valid to add subregions to a region which is not a pure container (that is, to an MMIO, RAM or ROM region). This means that the region