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

docs/devel/memory.rst

@@ -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)