From patchwork Sun Sep 15 14:51:53 2013 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Peter Maydell X-Patchwork-Id: 20317 Return-Path: X-Original-To: linaro@patches.linaro.org Delivered-To: linaro@patches.linaro.org Received: from mail-yh0-f69.google.com (mail-yh0-f69.google.com [209.85.213.69]) by ip-10-151-82-157.ec2.internal (Postfix) with ESMTPS id D0C76202C9 for ; Sun, 15 Sep 2013 14:52:02 +0000 (UTC) Received: by mail-yh0-f69.google.com with SMTP id c41sf3435295yho.4 for ; Sun, 15 Sep 2013 07:52:02 -0700 (PDT) X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20130820; h=x-gm-message-state:mime-version:delivered-to:from:to:cc:subject :date:message-id:x-original-sender:x-original-authentication-results :precedence:mailing-list:list-id:list-post:list-help:list-archive :list-unsubscribe; bh=NbDBWR9pS1CRo2Y5c7HVvt6SFXBRV7X19KOGL6kgTvU=; b=YVkVjMqxrGx07p61Fsqghafp0ara2x1Qe7l6hs58nk5Linp7WalfuXLDD3DMXPPzF1 AjEavaPQ6D/fpEfOPQcl1w2PrST+WaO501rTMvoSSuso9YxVMFdHUNdxdi1nD1FbOVr8 9M5QHBrPmnbuo6maHT2z7KIDghvylzCqjbYGhl3gfc2EoKe1iT6w/l+JuO+5FvIuh7yP ePLi9c9++GSM7STfd5rErQ6MhLJ6s/IkFvf3h0uq3vd5/jyNT7eIHb0o2+aVT77yu1mg dFDZ32UaG7EjUStrpN5Ai0g1o+uQzKXq5uJzRRq/Cdjma7PyMGV4ZN39Z5RVVlSzJcXs 82Lg== X-Gm-Message-State: ALoCoQkJda0MUDQ0ORA5nt1rkbVP9WCy60q7Q0WfIbN1Mc7vOoU0kGCyiuPLArmWese2paXl2ltY X-Received: by 10.236.80.42 with SMTP id j30mr8726386yhe.29.1379256722101; Sun, 15 Sep 2013 07:52:02 -0700 (PDT) MIME-Version: 1.0 X-BeenThere: patchwork-forward@linaro.org Received: by 10.49.38.130 with SMTP id g2ls1890045qek.99.gmail; Sun, 15 Sep 2013 07:52:02 -0700 (PDT) X-Received: by 10.52.113.99 with SMTP id ix3mr754288vdb.22.1379256722009; Sun, 15 Sep 2013 07:52:02 -0700 (PDT) Received: from mail-vb0-f52.google.com (mail-vb0-f52.google.com [209.85.212.52]) by mx.google.com with ESMTPS id gq10si5881547vdc.121.1969.12.31.16.00.00 (version=TLSv1 cipher=ECDHE-RSA-RC4-SHA bits=128/128); Sun, 15 Sep 2013 07:52:01 -0700 (PDT) Received-SPF: neutral (google.com: 209.85.212.52 is neither permitted nor denied by best guess record for domain of patch+caf_=patchwork-forward=linaro.org@linaro.org) client-ip=209.85.212.52; Received: by mail-vb0-f52.google.com with SMTP id f12so2108750vbg.25 for ; Sun, 15 Sep 2013 07:52:01 -0700 (PDT) X-Received: by 10.52.122.68 with SMTP id lq4mr18781544vdb.21.1379256721438; Sun, 15 Sep 2013 07:52:01 -0700 (PDT) X-Forwarded-To: patchwork-forward@linaro.org X-Forwarded-For: patch@linaro.org patchwork-forward@linaro.org Delivered-To: patches@linaro.org Received: by 10.220.174.196 with SMTP id u4csp53214vcz; Sun, 15 Sep 2013 07:52:00 -0700 (PDT) X-Received: by 10.180.72.195 with SMTP id f3mr9769561wiv.51.1379256720162; Sun, 15 Sep 2013 07:52:00 -0700 (PDT) Received: from mnementh.archaic.org.uk (1.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.d.1.0.0.b.8.0.1.0.0.2.ip6.arpa. [2001:8b0:1d0::1]) by mx.google.com with ESMTPS id ly5si4661978wjb.50.1969.12.31.16.00.00 (version=TLSv1.2 cipher=RC4-SHA bits=128/128); Sun, 15 Sep 2013 07:52:00 -0700 (PDT) Received-SPF: neutral (google.com: 2001:8b0:1d0::1 is neither permitted nor denied by best guess record for domain of pm215@archaic.org.uk) client-ip=2001:8b0:1d0::1; Received: from pm215 by mnementh.archaic.org.uk with local (Exim 4.80) (envelope-from ) id 1VLDg1-0003RK-8D; Sun, 15 Sep 2013 15:51:53 +0100 From: Peter Maydell To: qemu-devel@nongnu.org Cc: patches@linaro.org, "Michael S. Tsirkin" , Paolo Bonzini , Anthony Liguori Subject: [PATCH] docs/memory.txt: Clarify and expand priority/overlap documentation Date: Sun, 15 Sep 2013 15:51:53 +0100 Message-Id: <1379256713-13197-1-git-send-email-peter.maydell@linaro.org> X-Mailer: git-send-email 1.7.10.4 X-Removed-Original-Auth: Dkim didn't pass. X-Original-Sender: peter.maydell@linaro.org X-Original-Authentication-Results: mx.google.com; spf=neutral (google.com: 209.85.212.52 is neither permitted nor denied by best guess record for domain of patch+caf_=patchwork-forward=linaro.org@linaro.org) smtp.mail=patch+caf_=patchwork-forward=linaro.org@linaro.org Precedence: list Mailing-list: list patchwork-forward@linaro.org; contact patchwork-forward+owners@linaro.org List-ID: X-Google-Group-Id: 836684582541 List-Post: , List-Help: , List-Archive: List-Unsubscribe: , The documentation of how overlapping memory regions behave and how the priority system works was rather brief, and confusion about priorities seems to be quite common for developers trying to understand how the memory region system works, so expand and clarify it. This includes a worked example with overlaps, documentation of the behaviour when an overlapped container has "holes", and mention that it's valid for a region to have both MMIO callbacks and subregions (and how this interacts with priorities when it does). Signed-off-by: Peter Maydell --- docs/memory.txt | 48 +++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 47 insertions(+), 1 deletion(-) diff --git a/docs/memory.txt b/docs/memory.txt index feb9fe9..bd0ef6e 100644 --- a/docs/memory.txt +++ b/docs/memory.txt @@ -45,6 +45,10 @@ MemoryRegion): can overlay a subregion of RAM with MMIO or ROM, or a PCI controller that does not prevent card from claiming overlapping BARs. + It is valid for regions which are not "pure containers" to have subregions; + this means that any addresses within the container's region which are + not claimed by a subregion are handled by the container's MMIO callbacks. + - 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 @@ -81,6 +85,45 @@ allows the region to overlap any other region in the same container, and specifies a priority that allows the core to decide which of two regions at the same address are visible (highest wins). +If the higher priority region in an overlap is a container or alias, then +the lower priority region will appear in any "holes" that the higher priority +region has left by not mapping subregions to that area of its address range. +For example, suppose we have a container A of size 0x8000 with two subregions +B and C. B is a container mapped at 0x2000, size 0x4000, priority 1; C is +an MMIO region mapped at 0x0, size 0x6000, priority 2. B currently has two +of its own subregions: D of size 0x1000 at offset 0 and E of size 0x1000 at +offset 0x2000. As a diagram: + + 0 1000 2000 3000 4000 5000 6000 7000 8000 + |------|------|------|------|------|------|------|-------| + A: [ ] + C: [CCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCC] + B: [ ] + D: [DDDDD] + E: [EEEEE] + +The regions that will be seen within this address range then are: + [CCCCCCCCCCCC][DDDDD][CCCCC][EEEEE][CCCCC] + +Since B has higher priority than C, its subregions appear in the flat map +even where they overlap with C. In ranges where B has not mapped anything +C's region appears. + +If B had provided its own MMIO operations (ie it was not a pure container) +then these would be used for any addresses in its range not handled by +D or E, and the result would be: + [CCCCCCCCCCCC][DDDDD][BBBBB][EEEEE][BBBBB] + +Priority values are local to a container, because the priorities of two +regions are only compared when they are both children of the same container. +This means that the device in charge of the container (typically modelling +a bus or a memory controller) can use them to manage the interaction of +its child regions without any side effects on other parts of the system. +In the example above, the priorities of D and E are unimportant because +they do not overlap each other. It is the relative priority of B and C +that causes D and E to appear on top of C: D and E's priorities are never +compared against the priority of C. + Visibility ---------- The memory core uses the following rules to select a memory region when the @@ -93,8 +136,11 @@ guest accesses an address: - if the subregion is a leaf (RAM or MMIO), the search terminates - if the subregion is a container, the same algorithm is used within the subregion (after the address is adjusted by the subregion offset) - - if the subregion is an alias, the search is continues at the alias target + - if the subregion is an alias, the search is continued at the alias target (after the address is adjusted by the subregion offset and alias offset) + - if a recursive search within a container or alias subregion does not + find a match (because of a "hole" in the container's coverage of its + address range), we continue with the next subregion in priority order Example memory map ------------------