* [Qemu-devel] [PATCH] docs/memory.txt: Improve list of different memory regions
@ 2016-01-28 18:54 Peter Maydell
2016-02-08 16:30 ` Peter Maydell
2016-02-08 17:47 ` Paolo Bonzini
0 siblings, 2 replies; 3+ messages in thread
From: Peter Maydell @ 2016-01-28 18:54 UTC (permalink / raw)
To: qemu-devel; +Cc: Paolo Bonzini, Andrew Baumann, patches
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
^ permalink raw reply related [flat|nested] 3+ messages in thread
* Re: [Qemu-devel] [PATCH] docs/memory.txt: Improve list of different memory regions
2016-01-28 18:54 [Qemu-devel] [PATCH] docs/memory.txt: Improve list of different memory regions Peter Maydell
@ 2016-02-08 16:30 ` Peter Maydell
2016-02-08 17:47 ` Paolo Bonzini
1 sibling, 0 replies; 3+ messages in thread
From: Peter Maydell @ 2016-02-08 16:30 UTC (permalink / raw)
To: QEMU Developers; +Cc: Paolo Bonzini, Andrew Baumann, Patch Tracking
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
>
>
^ permalink raw reply [flat|nested] 3+ messages in thread
* Re: [Qemu-devel] [PATCH] docs/memory.txt: Improve list of different memory regions
2016-01-28 18:54 [Qemu-devel] [PATCH] docs/memory.txt: Improve list of different memory regions Peter Maydell
2016-02-08 16:30 ` Peter Maydell
@ 2016-02-08 17:47 ` Paolo Bonzini
1 sibling, 0 replies; 3+ messages in thread
From: Paolo Bonzini @ 2016-02-08 17:47 UTC (permalink / raw)
To: Peter Maydell, qemu-devel; +Cc: Andrew Baumann, patches
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
^ permalink raw reply [flat|nested] 3+ messages in thread
end of thread, other threads:[~2016-02-08 17:47 UTC | newest]
Thread overview: 3+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2016-01-28 18:54 [Qemu-devel] [PATCH] docs/memory.txt: Improve list of different memory regions Peter Maydell
2016-02-08 16:30 ` Peter Maydell
2016-02-08 17:47 ` Paolo Bonzini
This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.