From mboxrd@z Thu Jan 1 00:00:00 1970 Received: from eggs.gnu.org ([2001:4830:134:3::10]:54725) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1VW6iC-0007WY-Od for qemu-devel@nongnu.org; Tue, 15 Oct 2013 11:39:14 -0400 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1VW6i7-0000tJ-RR for qemu-devel@nongnu.org; Tue, 15 Oct 2013 11:39:08 -0400 Received: from mx1.redhat.com ([209.132.183.28]:46291) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1VW6i7-0000t9-Is for qemu-devel@nongnu.org; Tue, 15 Oct 2013 11:39:03 -0400 Date: Tue, 15 Oct 2013 17:52:36 +0300 From: "Michael S. Tsirkin" Message-ID: <20131015145236.GB7841@redhat.com> References: <1381848154-31602-1-git-send-email-peter.maydell@linaro.org> MIME-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Disposition: inline In-Reply-To: <1381848154-31602-1-git-send-email-peter.maydell@linaro.org> Subject: Re: [Qemu-devel] [PATCH v2] docs/memory.txt: Clarify and expand priority/overlap documentation List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , To: Peter Maydell Cc: qemu-devel@nongnu.org, Anthony Liguori , patches@linaro.org On Tue, Oct 15, 2013 at 03:42:34PM +0100, Peter Maydell wrote: > 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 Thanks a lot for writing this! Reviewed-by: Michael S. Tsirkin > --- > Changes v1->v2: various minor improvements as per review comments > from MST and subsequent discussion. > > docs/memory.txt | 64 +++++++++++++++++++++++++++++++++++++++++++++++++++++++-- > 1 file changed, 62 insertions(+), 2 deletions(-) > > diff --git a/docs/memory.txt b/docs/memory.txt > index feb9fe9..4035a20 100644 > --- a/docs/memory.txt > +++ b/docs/memory.txt > @@ -52,6 +52,15 @@ MemoryRegion): > hole". Aliases may point to any type of region, including other aliases, > but an alias may not point back to itself, directly or indirectly. > > +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 > +will act like a container, except that any addresses within the container's > +region which are not claimed by any subregion are handled by the > +container itself (ie by its MMIO callbacks or RAM backing). However > +it is generally possible to achieve the same effect with a pure container > +one of whose subregions is a low priority "background" region covering > +the whole address range; this is often clearer and is preferred. > +Subregions cannot be added to an alias region. > > Region names > ------------ > @@ -81,6 +90,49 @@ 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. > +(This applies recursively -- if the subregions are themselves containers or > +aliases that leave holes then the lower priority region will appear in these > +holes too.) > + > +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 > @@ -90,11 +142,19 @@ guest accesses an address: > descending priority order > - if the address lies outside the region offset/size, the subregion is > discarded > - - if the subregion is a leaf (RAM or MMIO), the search terminates > + - if the subregion is a leaf (RAM or MMIO), the search terminates, returning > + this leaf region > - 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), then if this is a container with its own MMIO or RAM > + backing the search terminates, returning the container itself. Otherwise > + we continue with the next subregion in priority order > +- if none of the subregions match the address then the search terminates > + with no match found > > Example memory map > ------------------ > -- > 1.7.11.4