Update documentation

Updating MCC memory for new configurations of Corstone-300 FPGA.

Adding information about required Python packages and tools.

Adding information about run_platform.py script.

Change-Id: I7a542db364ebcb2a4524823aff4b8864f62a8ae5

2 files changed, 69 insertions, 38 deletions

diff --git a/README.md b/README.md
index 65fcaf9..e8281b3 100644
--- a/README.md
+++ b/README.md
@@ -10,9 +10,7 @@ agnostic software components are provided in the
 [core_software](https://git.mlplatform.org/ml/ethos-u/ethos-u-core-software.git)
 repository.
 
-# Targets
-
-## Arm(R) Corstone(TM)-300
+# Arm(R) Corstone(TM)-300
 
 The
 [Arm(R) Corstone(TM)-300](https://developer.arm.com/ip-products/subsystem/corstone/corstone-300)
@@ -21,39 +19,56 @@ virtual platform (FVP) of the Arm Corstone-300 including the Arm Ethos-U can be
 downloaded from the Ecosystem page at
 [developer.arm.com](https://developer.arm.com/tools-and-software/open-source-software/arm-platforms-software/arm-ecosystem-fvps).
 
-### Building
+## Building
 
-Building with default settings requires CMake for the configuration, make for
-building and Python 3 for helper scripts.
+Building core platform requires a recent version of CMake to be installed
+together with a compiler capable of cross compiling for Arm Cortex-M. There are
+sample toolchain files provided for Arm Clang and Arm GCC.
 
-Before the first time building, install the required Python modules.
+To run the helper scripts Python 3 is required with the packages listed in
+`requirements.txt`.
 
 ```
+$ pip install -U pip
 $ pip install -r requirements.txt
 ```
 
 The following commands will produce an elf file which can be run on the FVP.
 
 ```
-$ cmake -B build/corstone-300 targets/corstone-300
-$ cd build/corstone-300
-$ make
+$ cmake -B build targets/corstone-300
+$ cmake --build build
 ```
 
 It is also possible to build with a different toolchain.
 
 ```
-$ cmake -B build/corstone-300 targets/corstone-300 -DCMAKE_TOOLCHAIN_FILE=$PWD/cmake/toolchain/arm-none-eabi-gcc.cmake
-$ cd build/corstone-300
-$ make
+$ cmake -B build targets/corstone-300 -DCMAKE_TOOLCHAIN_FILE=$PWD/cmake/toolchain/arm-none-eabi-gcc.cmake
+$ cmake --build build
 ```
 
 Please see [README_WINDOWS.md](README_WINDOWS.md) for additional information
 regarding building on a Windows system.
 
-### Testing
+## run_platform.py
+
+There are many things to consider when deploying a network to an embedded
+system. Where should the data be placed, in SRAM, DRAM or flash? How is the
+performance affected if a fast or slower memory is used? Which Ethos-U
+performance counters should be enabled to measure the performance?
+
+The main purpose of `scripts/run_platform.py` is to document how to go from
+tflite to an application that can be run on a an embedded platform like
+Corstone-300. It also allows users to adjust some settings like memory
+configuration, timing adapter settings or which PMU events to monitor. Please
+refer to the help message for further details about which arguments that can be
+passed to the script.
+
+```
+$ scripts/run_platform.py --network-path <tflite>
+```
 
-#### Fixed Virtual Platform - Corstone-300
+## Corstone-300 FVP
 
 Assuming that the Corstone-300 FVP has been downloaded, installed and placed in
 the PATH variable. Then the software binaries can be tested like this.
@@ -68,7 +83,18 @@ this.
 ```
 $ FVP_Corstone_SSE-300_Ethos-U55 applications/freertos/freertos.elf
 ```
-#### MPS3 FPGA
+
+The Corstone-300 FVP allows some parameters to be modified, for example the
+number of Ethos-U MAC units can be configured with
+`-C ethosu.num_macs=<64|128|256|...>`. Please note that the network must be
+recompiled with Vela if the MAC configuration changes. Please also note that the
+set of valid MAC configuration is different for Ethos-U55 and Ethos-U65.
+
+```
+$ FVP_Corstone_SSE-300_Ethos-U55 -C ethosu.num_macs=256 applications/freertos/freertos.elf
+```
+
+## Corstone-300 MPS3 FPGA
 
 The files needed to get started for Corstone-300 can be found on
 [developer.arm.com](https://developer.arm.com/tools-and-software/development-boards/fpga-prototyping-boards/download-fpga-images).
@@ -76,43 +102,45 @@ The files needed to get started for Corstone-300 can be found on
 Follow the documentation in the downloaded archive to setup the board with the
 Corstone-300 FPGA bit files.
 
-The built files can then be ran by adapting the steps in chapter '10 Software',
+The built files can then be ran by adapting the steps in chapter *Software*,
 using the extracted binary files from the build process. This is needed for the
-bootloader on the FPGA to be able to load the memories.
+boot loader on the FPGA to be able to load the memories.
 
-1. Copy the binary files for the application in the fw/ folder to the board
-   <MPS3_dir>/Software folder, making sure the filename is max 8.3 characters
-   (i.e. 00000000.bin and 70000000.bin for the freertos application)
-2. Navigate to <MPS3_dir>MB/HBI0309C/AN547 and open the images.txt file in a
-   text editor
+1. Copy the binary files for the application in the `fw` folder to the board
+   `<MPS3_dir>/SOFTWARE` folder, making sure the filename is max 8 characters
+   long.
+2. Navigate to <MPS3_dir>MB/HBI0309C/<version> and open the images.txt file in a
+   text editor.
 3. Remove the lines under the '[IMAGES]' section and replace it with:
 
 ```
 TOTALIMAGES: 2
 
-IMAGE0ADDRESS: 0x02000000
+IMAGE0ADDRESS: 0x01000000
 IMAGE0UPDATE:  AUTO
-IMAGE0FILE:    \SOFTWARE\10000000.bin; sram binary
+IMAGE0FILE:    \SOFTWARE\10000000 ; ITCM secure
 
 IMAGE1ADDRESS: 0x0c000000
 IMAGE1UPDATE:  AUTO
-IMAGE1FILE:    \SOFTWARE\70000000.bin ; ddr binary
+IMAGE1FILE:    \SOFTWARE\70000000 ; DDR secure
 ```
 
-The mapping between the Cortex-M55 memory space and the addresse the FPGA MMC
-bootloader needs is found in section '9.6 MCC Memory mapping' of the
+The mapping between the Cortex-M55 address space and the addresses the FPGA MMC
+boot loader need can be found in section *MCC Memory mapping* of the
 documentation in the Corstone-300 FPGA archive. A part of the table is shown
-below:
+below.
 
- |  Cortex-M55   |  MMC Bootloader |
- |---------------|-----------------|
- |  0x00000000   |    0x00000000   |
- |  0x10000000   |    0x01000000   |
- |  0x60000000   |    0x08000000   |
- |  0x70000000   |    0x0C000000   |
+ | Cortex-M55  | MMC Bootloader | Name            |
+ |-------------|----------------|-----------------|
+ | 0x0000_0000 | 0x0000_0000    | ITCM non secure |
+ | 0x1000_0000 | 0x0100_0000    | ITCM secure     |
+ | 0x0100_0000 | 0x0200_0000    | SRAM non secure |
+ | 0x1100_0000 | 0x0300_0000    | SRAM secure     |
+ | 0x6000_0000 | 0x0800_0000    | DDR non secure  |
+ | 0x7000_0000 | 0x0c00_0000    | DDR secure      |
 
-The binary that the Cortex-M55 CPU expects at address 0x10000000 must therefor
-be written to 0x02000000.
+For example, the binary that the Cortex-M55 CPU expects at address 0x1000_0000
+must therefor be written by the MCC to 0x0100_0000.
 
 Power up the board with the PBON and the application output will be seen on the
 serial console.
@@ -190,7 +218,7 @@ semaphores for sleeping.
 
 ![Multi NPU](docs/multinpu.svg "Multi NPU sequence diagram")
 
-## Tradeoffs
+## Multi NPU tradeoffs
 
 A single Cortex-M is capable of driving multiple Ethos-U. What the optimal
 number of Ethos-U is, that is impossible to tell without knowing which network
diff --git a/requirements.txt b/requirements.txt
index 5e03a5c..db6ebfe 100644
--- a/requirements.txt
+++ b/requirements.txt
@@ -1,2 +1,5 @@
 numpy
+pillow
 pyelftools
+tensorflow
+ethos-u-vela