[Qemu-devel] [PATCH] docs/memory.txt: Improve list of different memory regions

[Qemu-devel] [PATCH] docs/memory.txt: Improve list of different memory regions

[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 <peter.maydell@linaro.org>
---
 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
-- 
1.9.1

Re: [Qemu-devel] [PATCH] docs/memory.txt: Improve list of different memory regions

[Peter Maydell]

Ping?

thanks
-- PMM

On 28 January 2016 at 18:54, Peter Maydell <peter.maydell@linaro.org> wrote:
> 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 <peter.maydell@linaro.org>
> ---
>  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
> --
> 1.9.1
>
>

Re: [Qemu-devel] [PATCH] docs/memory.txt: Improve list of different memory regions

[Paolo Bonzini]

On 28/01/2016 19:54, Peter Maydell wrote:
> 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 <peter.maydell@linaro.org>
> ---
>  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
> 

Sorry, this missed today's pull request.  The patch is a fine
improvement, feel free to apply it directly.

Paolo