[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: [Qemu-devel] [PATCH v2] docs/memory.txt: Clarify and expand priority
From: |
Michael S. Tsirkin |
Subject: |
Re: [Qemu-devel] [PATCH v2] docs/memory.txt: Clarify and expand priority/overlap documentation |
Date: |
Tue, 15 Oct 2013 17:52:36 +0300 |
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 <address@hidden>
Thanks a lot for writing this!
Reviewed-by: Michael S. Tsirkin <address@hidden>
> ---
> 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