boards: arm: mps2_an521: Clarify memory map

Attempts to clarify the memory map on the MPS2 AN521, showing how
the 4MB code region and 4MB SRAM region are partitioned across the
various board targets.

Signed-off-by: Kevin Townsend <kevin.townsend@linaro.org>

boards/arm/mps2_an521/doc/index.rst

@@ -42,7 +42,7 @@ both Secure and Non-Secure firmware images may be built.
 The BOARD options are summarized below:
 
 +----------------------+-------------------------------------------------------+
-|   BOARD              | Description                                           |
+| BOARD                | Description                                           |
 +======================+=======================================================+
 | mps2_an521           | For building Secure (or Secure-only) firmware on CPU0 |
 +----------------------+-------------------------------------------------------+
@@ -51,21 +51,65 @@ The BOARD options are summarized below:
 | mps2_an521_remote    | For building firmware on CPU1                         |
 +----------------------+-------------------------------------------------------+
 
+Memory Partitioning
+===================
+
+The AN521 has 4MB allocated for code space, and 4MB for SRAM. These memory
+regions are shared across both cores, and are aliased in both secure and
+non-secure regions, where the secure memory alias has an offset of
+0x10000000 relative to non-secure.
+
+The following memory map and partitioning schemes are used by default, where
+the offset value is the offset from the base of the 4MB code or SRAM block,
+ignoring the S/NS alias difference.
+
++-------------------+-----+----------------+----------------+------------+
+| Board             | CPU | Code (Offset)  | SRAM (Offset)  | S/NS Alias |
++===================+=====+================+================+============+
+| mps2_an521        | 0   | 4MB (0)        | 4MB (0)        | S          |
++-------------------+-----+----------------+----------------+------------+
+| mps2_an521_ns     | 0   | 512KB (1MB)    | 512KB (1MB)    | NS         |
++-------------------+-----+----------------+----------------+------------+
+| mps2_an521_remote | 1   | 468KB (3628KB) | 512KB (1.5MB)  | NS         |
++-------------------+-----+----------------+----------------+------------+
+
+The ``mps2_an521_ns`` board target is intended to be used with TF-M, with the
+Zephyr memory map matching the AN521 memory map defined upstream in TF-M. TF-M
+boots the secure processing environment before initialising Zephyr in the
+non-secure processing environment. The non-secure Zephyr image is offset to
+make room for the secure bootloader, and the secure firmware (TF-M), resulting
+in a starting address of 0x00100000. SRAM begins with a 1MB offset at
+0x28100000.
+
+The ``mps2_an521_remote`` board target is setup for the second core on the
+AN521, using the final 468KB code memory in the 4MB code block. This value
+is chosen to maintain compatibility with TF-M, which marks that final 468KB
+code region as ``Unused``. Code memory thus starts with an offset of
+3628KB (address 0x0038B000), and sram starts with an offset of 1.5MB
+(address 0x28180000).
+
+This memory map enables the two alternative board targets to be used together
+if required, at the cost of reducing the amount of code memory available on
+the second core to the worst-case scenario from TF-M.
+
+When using one of the alternative board targets (``mps2_an521_ns`` or
+``mps2_an521_remote``), care needs to be taken with the amount of code or
+SRAM memory used on the primary board target (``mps2_an521``) since there is
+some overlap in the memory maps.
 
 Hardware
 ********
 
 ARM MPS2+ AN521 provides the following hardware components:
 
-
-
 - Dual core ARM Cortex-M33
 - Soft Macro Model (SMM) implementation of SSE-200 subsystem
 - Memory
 
-  - 16MB internal memory SRAM
+  - 4MB of code memory (SSRAM1)
+  - 4MB of SRAM (SSRAM2 and SSRAM3)
+  - 16MB of parallel SRAM (PSRAM, non-secure only)
   - 8KB of NVM code
-  - 224MB code memory
 
 - Debug