docs: Convert memory.txt to rst format

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>
Reviewed-by: Richard Henderson <richard.henderson@linaro.org>
Reviewed-by: Cleber Rosa <crosa@redhat.com>
Message-id: 20190305172139.32662-3-peter.maydell@linaro.org
Message-id: 20190228145624.24885-3-peter.maydell@linaro.org
This commit is contained in:
Peter Maydell 2019-03-07 14:26:44 +00:00
parent 0defa86ca3
commit 859cdc01a0
1 changed files with 70 additions and 58 deletions

View File

@ -1,3 +1,4 @@
==============
The memory API
==============
@ -98,6 +99,7 @@ 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()
@ -105,18 +107,22 @@ migrated:
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()
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()
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,7 +234,8 @@ offset 0x2000. As a diagram:
D: [DDDDD]
E: [EEEEE]
The regions that will be seen within this address range then are:
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
@ -237,7 +244,8 @@ 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:
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
@ -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,12 +279,15 @@ 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)