From: Peter Maydell <peter.maydell@linaro.org>
To: qemu-devel@nongnu.org
Cc: "Philippe Mathieu-Daudé" <philmd@redhat.com>,
"Alex Bennée" <alex.bennee@linaro.org>,
"Aleksandar Markovic" <amarkovic@wavecomp.com>
Subject: [Qemu-devel] [PATCH v3 02/12] docs: Convert memory.txt to rst format
Date: Tue, 5 Mar 2019 17:21:29 +0000 [thread overview]
Message-ID: <20190305172139.32662-3-peter.maydell@linaro.org> (raw)
In-Reply-To: <20190305172139.32662-1-peter.maydell@linaro.org>
Convert the memory API documentation from plain text
to restructured text format.
This is a very minimal conversion: all I had to change
was to mark up the ASCII art parts as Sphinx expects
for 'literal blocks', and fix up the bulleted lists
(Sphinx expects no leading space before the bullet, and
wants a blank line before after any list).
Signed-off-by: Peter Maydell <peter.maydell@linaro.org>
Reviewed-by: Alex Bennée <alex.bennee@linaro.org>
Acked-by: Aleksandar Markovic <amarkovic@wavecomp.com>
Message-id: 20190228145624.24885-3-peter.maydell@linaro.org
---
docs/devel/{memory.txt => memory.rst} | 128 ++++++++++++++------------
1 file changed, 70 insertions(+), 58 deletions(-)
rename docs/devel/{memory.txt => memory.rst} (85%)
diff --git a/docs/devel/memory.txt b/docs/devel/memory.rst
similarity index 85%
rename from docs/devel/memory.txt
rename to docs/devel/memory.rst
index 42577e1d860..b6a4c37ea5e 100644
--- a/docs/devel/memory.txt
+++ b/docs/devel/memory.rst
@@ -1,19 +1,20 @@
+==============
The memory API
==============
The memory API models the memory and I/O buses and controllers of a QEMU
machine. It attempts to allow modelling of:
- - ordinary RAM
- - memory-mapped I/O (MMIO)
- - memory controllers that can dynamically reroute physical memory regions
- to different destinations
+- ordinary RAM
+- memory-mapped I/O (MMIO)
+- memory controllers that can dynamically reroute physical memory regions
+ to different destinations
The memory model provides support for
- - tracking RAM changes by the guest
- - setting up coalesced memory for kvm
- - setting up ioeventfd regions for kvm
+- tracking RAM changes by the guest
+- setting up coalesced memory for kvm
+- setting up ioeventfd regions for kvm
Memory is modelled as an acyclic graph of MemoryRegion objects. Sinks
(leaves) are RAM and MMIO regions, while other nodes represent
@@ -98,25 +99,30 @@ ROM device memory region types), this host memory needs to be
copied to the destination on migration. These APIs which allocate
the host memory for you will also register the memory so it is
migrated:
- - memory_region_init_ram()
- - memory_region_init_rom()
- - memory_region_init_rom_device()
+
+- memory_region_init_ram()
+- memory_region_init_rom()
+- memory_region_init_rom_device()
For most devices and boards this is the correct thing. If you
have a special case where you need to manage the migration of
the backing memory yourself, you can call the functions:
- - memory_region_init_ram_nomigrate()
- - memory_region_init_rom_nomigrate()
- - memory_region_init_rom_device_nomigrate()
+
+- memory_region_init_ram_nomigrate()
+- memory_region_init_rom_nomigrate()
+- memory_region_init_rom_device_nomigrate()
+
which only initialize the MemoryRegion and leave handling
migration to the caller.
The functions:
- - memory_region_init_resizeable_ram()
- - memory_region_init_ram_from_file()
- - memory_region_init_ram_from_fd()
- - memory_region_init_ram_ptr()
- - memory_region_init_ram_device_ptr()
+
+- memory_region_init_resizeable_ram()
+- memory_region_init_ram_from_file()
+- memory_region_init_ram_from_fd()
+- memory_region_init_ram_ptr()
+- memory_region_init_ram_device_ptr()
+
are for special cases only, and so they do not automatically
register the backing memory for migration; the caller must
manage migration if necessary.
@@ -218,7 +224,7 @@ 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 2; C is
an MMIO region mapped at 0x0, size 0x6000, priority 1. 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:
+offset 0x2000. As a diagram::
0 1000 2000 3000 4000 5000 6000 7000 8000
|------|------|------|------|------|------|------|------|
@@ -228,8 +234,9 @@ offset 0x2000. As a diagram:
D: [DDDDD]
E: [EEEEE]
-The regions that will be seen within this address range then are:
- [CCCCCCCCCCCC][DDDDD][CCCCC][EEEEE][CCCCC]
+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
@@ -237,8 +244,9 @@ 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]
+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.
@@ -257,6 +265,7 @@ guest accesses an address:
- all direct subregions of the root region are matched against the address, in
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, returning
@@ -270,36 +279,39 @@ guest accesses an address:
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
------------------
-system_memory: container@0-2^48-1
- |
- +---- lomem: alias@0-0xdfffffff ---> #ram (0-0xdfffffff)
- |
- +---- himem: alias@0x100000000-0x11fffffff ---> #ram (0xe0000000-0xffffffff)
- |
- +---- vga-window: alias@0xa0000-0xbffff ---> #pci (0xa0000-0xbffff)
- | (prio 1)
- |
- +---- pci-hole: alias@0xe0000000-0xffffffff ---> #pci (0xe0000000-0xffffffff)
+::
-pci (0-2^32-1)
- |
- +--- vga-area: container@0xa0000-0xbffff
- | |
- | +--- alias@0x00000-0x7fff ---> #vram (0x010000-0x017fff)
- | |
- | +--- alias@0x08000-0xffff ---> #vram (0x020000-0x027fff)
- |
- +---- vram: ram@0xe1000000-0xe1ffffff
- |
- +---- vga-mmio: mmio@0xe2000000-0xe200ffff
+ system_memory: container@0-2^48-1
+ |
+ +---- lomem: alias@0-0xdfffffff ---> #ram (0-0xdfffffff)
+ |
+ +---- himem: alias@0x100000000-0x11fffffff ---> #ram (0xe0000000-0xffffffff)
+ |
+ +---- vga-window: alias@0xa0000-0xbffff ---> #pci (0xa0000-0xbffff)
+ | (prio 1)
+ |
+ +---- pci-hole: alias@0xe0000000-0xffffffff ---> #pci (0xe0000000-0xffffffff)
-ram: ram@0x00000000-0xffffffff
+ pci (0-2^32-1)
+ |
+ +--- vga-area: container@0xa0000-0xbffff
+ | |
+ | +--- alias@0x00000-0x7fff ---> #vram (0x010000-0x017fff)
+ | |
+ | +--- alias@0x08000-0xffff ---> #vram (0x020000-0x027fff)
+ |
+ +---- vram: ram@0xe1000000-0xe1ffffff
+ |
+ +---- vga-mmio: mmio@0xe2000000-0xe200ffff
+
+ ram: ram@0x00000000-0xffffffff
This is a (simplified) PC memory map. The 4GB RAM block is mapped into the
system address space via two aliases: "lomem" is a 1:1 mapping of the first
@@ -336,16 +348,16 @@ rather than completing successfully; those devices can use the
In addition various constraints can be supplied to control how these
callbacks are called:
- - .valid.min_access_size, .valid.max_access_size define the access sizes
- (in bytes) which the device accepts; accesses outside this range will
- have device and bus specific behaviour (ignored, or machine check)
- - .valid.unaligned specifies that the *device being modelled* supports
- unaligned accesses; if false, unaligned accesses will invoke the
- appropriate bus or CPU specific behaviour.
- - .impl.min_access_size, .impl.max_access_size define the access sizes
- (in bytes) supported by the *implementation*; other access sizes will be
- emulated using the ones available. For example a 4-byte write will be
- emulated using four 1-byte writes, if .impl.max_access_size = 1.
- - .impl.unaligned specifies that the *implementation* supports unaligned
- accesses; if false, unaligned accesses will be emulated by two aligned
- accesses.
+- .valid.min_access_size, .valid.max_access_size define the access sizes
+ (in bytes) which the device accepts; accesses outside this range will
+ have device and bus specific behaviour (ignored, or machine check)
+- .valid.unaligned specifies that the *device being modelled* supports
+ unaligned accesses; if false, unaligned accesses will invoke the
+ appropriate bus or CPU specific behaviour.
+- .impl.min_access_size, .impl.max_access_size define the access sizes
+ (in bytes) supported by the *implementation*; other access sizes will be
+ emulated using the ones available. For example a 4-byte write will be
+ emulated using four 1-byte writes, if .impl.max_access_size = 1.
+- .impl.unaligned specifies that the *implementation* supports unaligned
+ accesses; if false, unaligned accesses will be emulated by two aligned
+ accesses.
--
2.20.1
next prev parent reply other threads:[~2019-03-05 17:21 UTC|newest]
Thread overview: 44+ messages / expand[flat|nested] mbox.gz Atom feed top
2019-03-05 17:21 [Qemu-devel] [PATCH v3 00/12] Enable build and install of our rST docs Peter Maydell
2019-03-05 17:21 ` [Qemu-devel] [PATCH v3 01/12] docs/cpu-hotplug.rst: Fix rST markup issues Peter Maydell
2019-03-05 22:34 ` Richard Henderson
2019-03-07 0:04 ` Cleber Rosa
2019-03-07 9:47 ` Peter Maydell
2019-03-07 11:15 ` Cleber Rosa
2019-03-05 17:21 ` Peter Maydell [this message]
2019-03-05 22:40 ` [Qemu-devel] [PATCH v3 02/12] docs: Convert memory.txt to rst format Richard Henderson
2019-03-07 0:11 ` Cleber Rosa
2019-03-05 17:21 ` [Qemu-devel] [PATCH v3 03/12] docs: Commit initial files from sphinx-quickstart Peter Maydell
2019-03-05 22:36 ` Richard Henderson
2019-03-05 17:21 ` [Qemu-devel] [PATCH v3 04/12] docs/conf.py: Disable unused _static directory Peter Maydell
2019-03-05 22:36 ` Richard Henderson
2019-03-05 17:21 ` [Qemu-devel] [PATCH v3 05/12] docs/conf.py: Configure the 'alabaster' theme Peter Maydell
2019-03-05 17:21 ` [Qemu-devel] [PATCH v3 06/12] docs/conf.py: Don't include rST sources in HTML build Peter Maydell
2019-03-05 22:42 ` Richard Henderson
2019-03-05 17:21 ` [Qemu-devel] [PATCH v3 07/12] docs/conf.py: Disable option warnings Peter Maydell
2019-03-05 22:42 ` Richard Henderson
2019-03-05 17:21 ` [Qemu-devel] [PATCH v3 08/12] docs: Provide separate conf.py for each manual we want Peter Maydell
2019-03-07 1:40 ` Cleber Rosa
2019-03-07 9:49 ` Peter Maydell
2019-03-07 12:14 ` Cleber Rosa
2019-03-07 12:29 ` Peter Maydell
2019-03-07 13:18 ` Cleber Rosa
2019-03-07 13:30 ` Peter Maydell
2019-03-07 13:41 ` Cleber Rosa
2019-03-07 13:46 ` Peter Maydell
2019-03-05 17:21 ` [Qemu-devel] [PATCH v3 09/12] Makefile, configure: Support building rST documentation Peter Maydell
2019-03-05 22:45 ` Richard Henderson
[not found] ` <92ffba93-e486-647a-01ef-86180fb2cbb2@redhat.com>
2019-04-01 7:58 ` Peter Maydell
2019-04-01 12:51 ` Eric Blake
2019-03-05 17:21 ` [Qemu-devel] [PATCH v3 10/12] Makefile: Abstract out "identify the pkgversion" code Peter Maydell
2019-03-05 22:33 ` Richard Henderson
2019-03-05 17:21 ` [Qemu-devel] [PATCH v3 11/12] docs/conf.py: Don't hard-code QEMU version Peter Maydell
2019-03-05 22:46 ` Richard Henderson
2019-03-05 17:21 ` [Qemu-devel] [PATCH v3 12/12] MAINTAINERS: Add entry for Sphinx documentation infrastructure Peter Maydell
2019-03-05 18:08 ` Philippe Mathieu-Daudé
2019-03-05 22:47 ` Richard Henderson
2019-03-05 17:44 ` [Qemu-devel] [PATCH v3 00/12] Enable build and install of our rST docs no-reply
2019-03-05 18:17 ` no-reply
2019-03-06 1:28 ` no-reply
2019-03-06 1:32 ` no-reply
2019-03-07 0:10 ` no-reply
2019-03-07 0:15 ` no-reply
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=20190305172139.32662-3-peter.maydell@linaro.org \
--to=peter.maydell@linaro.org \
--cc=alex.bennee@linaro.org \
--cc=amarkovic@wavecomp.com \
--cc=philmd@redhat.com \
--cc=qemu-devel@nongnu.org \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
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.