Corstone-500: adding Corstone-500 documentationCORSTONE-500-2020.11.27

This commit provides Corstone-500 documentation.

Change-Id: Iea33a329b9428a14ab6ce89ecbd848b7dfd54eb3
Signed-off-by: Abdellatif El Khlifi <abdellatif.elkhlifi@arm.com>

6 files changed, 292 insertions, 2 deletions

diff --git a/docs/corstone500/change-log.rst b/docs/corstone500/change-log.rst
new file mode 100644
index 0000000..d352936
--- /dev/null
+++ b/docs/corstone500/change-log.rst
@@ -0,0 +1,49 @@
+Change Log
+==========
+
+This document contains a summary of the new features, changes and
+fixes in each release of Corstone-500.
+
+Version 2020.11.27
+------------------
+
+Features added
+~~~~~~~~~~~~~~
+
+None.
+
+Changes
+~~~~~~~
+- Branding CA5DS to Corstone-500.
+- Upgrading the kernel to v5.3.
+- Using Yocto meta-arm layers aligned with Yocto Gatesgarth.
+- Upgrading Trusted firmware A to v2.3 with a fix for the system timer issue.
+- Upgrading u-boot to 2020.07 with a fix for the generic timer MMIO access issue.
+
+Version 2020.03.06
+------------------
+
+Features added
+~~~~~~~~~~~~~~
+- Support for Snoop Control Unit and its device driver.
+- Support for Cortex-A5 DesignStart on MPS3 FPGA.
+
+Changes
+~~~~~~~
+- Changes to make the same software work on FPGA and FVP.
+- Changes to Linux kernel config to run from DRAM (DDR).
+
+Version 2019.09.16
+------------------
+
+Features added
+~~~~~~~~~~~~~~
+- Platform port of Cortex-A5 DesignStart including GICv1 changes.
+- Support for Arm v7 architecture in Trusted firmware A.
+- Support for non-LPAE mapping in Trusted firmware A.
+- Division functionality for cores that don't have divide hardware.
+- Support for mmio based generic timer in u-boot.
+
+--------------
+
+*Copyright (c) 2019-2020, Arm Limited. All rights reserved.*
diff --git a/docs/corstone500/release_notes.rst b/docs/corstone500/release_notes.rst
new file mode 100644
index 0000000..e6c0796
--- /dev/null
+++ b/docs/corstone500/release_notes.rst
@@ -0,0 +1,41 @@
+Release notes - 2020.11.27
+==========================
+
+.. section-numbering::
+    :suffix: .
+
+.. contents::
+
+
+Software Features
+-----------------
+The following is a summary of the key software features of the release:
+
+ - Linux kernel version 5.3.
+ - Trusted firmware A with Corstone-500 platform port.
+ - U-Boot changes with memory mapped timer support.
+ - Build and Packaging using Yocto poky-tiny distro.
+ - Detailed change log can be viewed here `Change Log <change-log.rst>`__.
+
+Hardware Features
+-----------------
+
+ - Memory mapped generic timer support.
+ - Generic interrupt controller (GIC) support.
+ - UART PL011.
+ - RTC.
+ - Snoop Control Unit.
+
+Platform Support
+----------------
+
+ - This Software release is tested on Fast Model Platform (FVP) with 4 cores.
+ - Supported Fast model version for this release is 11.12.59, Iris interface version 11.12.
+
+Support
+-------
+For support email: support-subsystem-iot@arm.com
+
+--------------
+
+*Copyright (c) 2019-2020, Arm Limited. All rights reserved.*
diff --git a/docs/corstone500/user-guide.rst b/docs/corstone500/user-guide.rst
new file mode 100644
index 0000000..bffc37c
--- /dev/null
+++ b/docs/corstone500/user-guide.rst
@@ -0,0 +1,165 @@
+User Guide
+==========
+
+.. section-numbering::
+    :suffix: .
+
+.. contents::
+
+Notice
+------
+The Corstone-500 software stack uses the `Yocto project <https://www.yoctoproject.org/>`__ to build
+a tiny Linux distribution. The yocto project relies on the
+`Bitbake <https://www.yoctoproject.org/docs/1.6/bitbake-user-manual/bitbake-user-manual.html>`__
+tool as its build tool.
+
+Prerequisites
+-------------
+These instructions assume your host PC is running Ubuntu Linux 18.04 LTS.
+The instructions in this document expects that you are using a bash shell.
+
+The following prerequisites must be available on the host system:
+ * chrpath
+ * gawk
+ * makeinfo
+ * openssl headers
+ * diffstat
+ * yocto
+
+To resolve these dependencies, run:
+
+::
+
+    sudo apt-get update
+    sudo apt-get install chrpath gawk texinfo libssl-dev diffstat wget git-core unzip gcc-multilib \
+     build-essential socat cpio python python3 python3-pip python3-pexpect xz-utils debianutils \
+     iputils-ping python3-git python3-jinja2 libegl1-mesa libsdl1.2-dev pylint3 xterm git-lfs openssl \
+     curl libncurses-dev libz-dev python-pip
+
+
+Provided components
+-------------------
+Within the Yocto project, each component included in the Corstone-500 software stack is specified as
+a `bitbake recipe <https://www.yoctoproject.org/docs/1.6/bitbake-user-manual/bitbake-user-manual.html#recipes>`__.
+The recipes specific to the Corstone-500 project may be located at:
+``<Corstone-500_workspace>/layers/meta-arm/``.
+
+Software
+########
+
+Trusted Firmware-A
+******************
+Based on `ARM Trusted Firmware-A <https://github.com/ARM-software/arm-trusted-firmware>`__.
+
++--------+----------------------------------------------------------------------------------------------------------------+
+| Recipe | <Corstone-500_workspace>/layers/meta-arm/meta-arm/recipes-bsp/trusted-firmware-a/trusted-firmware-a_2.3.bb     |
++--------+----------------------------------------------------------------------------------------------------------------+
+| Files  | * bl1.bin                                                                                                      |
++--------+----------------------------------------------------------------------------------------------------------------+
+
+U-Boot
+******
+Based on `U-Boot <git://git.denx.de/u-boot.git>`__.
+
++--------+----------------------------------------------------------------------------------------------------------------+
+| Recipe | <Corstone-500_workspace>/layers/openembedded-core/meta/recipes-bsp/u-boot/u-boot_2020.07.bb                    |
++--------+----------------------------------------------------------------------------------------------------------------+
+| Files  | * u-boot.bin                                                                                                   |
++--------+----------------------------------------------------------------------------------------------------------------+
+
+Linux
+*****
+The recipe responsible for building a version of Linux.
+The Linux distribution used is poky-tiny which is provided by the Yocto project.
+poky-tiny allows the generation of a small size linux distribution.
+
+`poky-tiny <https://wiki.yoctoproject.org/wiki/Poky-Tiny>`__
+
+The provided distribution is based on busybox and built using musl C library.
+
++--------+----------------------------------------------------------------------------------------------------------------+
+| Recipe | <Corstone-500_workspace>/layers/meta-arm/meta-arm-bsp/recipes-kernel/linux/linux-yocto_5.3.bb                  |
++--------+----------------------------------------------------------------------------------------------------------------+
+| Files  | * zImage                                                                                                       |
+|        | * arm-reference-image-corstone500.cpio.gz (rootfs)                                                             |
++--------+----------------------------------------------------------------------------------------------------------------+
+
+Run scripts
+###########
+
+Within ``<Corstone-500_workspace>/run-scripts/iot`` a number of convenience functions for testing the software
+stack may be found.
+Usage descriptions for the various scripts are provided in the following sections.
+
+
+Building the Software stack
+---------------------------
+Corstone-500 is a Bitbake based Yocto distro which uses bitbake commands to build the stack.
+In the top directory of the synced workspace (~/Corstone-500), run:
+
+::
+
+    export DISTRO="poky-tiny"
+    export MACHINE="corstone500"
+    source setup-environment
+
+By sourcing setup-environment, your current directory should now have switched to
+``<Corstone-500_workspace>/build-poky-tiny/``. If not, change the current directory to this path.
+Next, to build the stack, execute:
+
+::
+
+    bitbake arm-reference-image
+
+The initial clean build will be lengthy, given that all host utilities are to be built as well as
+the target images.
+This includes host executables (python, cmake, etc.) and the required toolchain(s).
+
+Once the build is successful, all images will be placed in the deploy directory
+``<Corstone-500_workspace>/build-poky-tiny/tmp-poky_tiny/deploy/images/corstone500`` folder.
+
+Everything apart from the BL1(ROM) binary is bundled into a single binary, the
+``arm-reference-image-corstone500.wic.nopt`` file.
+
+Running the software on FVP
+---------------------------
+An FVP (Fixed Virtual Platform) of the Corstone-500 platform must be available to execute the
+included run scripts.
+Also, ensure that the FVP has its dependencies met by executing the FVP:
+
+::
+
+./<Corstone-500 Model Binary>
+
+All dependencies are met if the FVP launches without any errors, presenting a graphical interface
+showing information about the current state of the FVP.
+
+The ``run_model.sh`` script in "<Corstone-500_workspace>/run-scripts/iot" folder will provide the previously built images as
+arguments to the FVP and launch the FVP.
+
+The iot folder structure is as follows:
+::
+
+    iot
+    |── run_model.sh
+    └── scripts
+        └── ...
+
+Execute the ``run_model.sh`` script:
+
+::
+
+       ./run_model.sh
+       usage: run_model.sh ${FVP executable path} [ -u ]
+         -u: Run unit test selector using pyIRIS
+          No additional argument: load and execute model
+
+When the script is executed, one terminal instance will be launched for the Cortex-A5 processing element.
+Once the FVP is executing, relevant memory contents of the .wic.nopt file are copied to their respective
+memory locations within the model, and the CPU is brought out of reset.
+
+The CPU will boot Linux and present a login prompt; login using the username ``root``.
+
+--------------
+
+*Copyright (c) 2019-2020, Arm Limited. All rights reserved.*
diff --git a/docs/user-guide.rst b/docs/user-guide.rst
index 6ae4414..66f75a1 100644
--- a/docs/user-guide.rst
+++ b/docs/user-guide.rst
@@ -62,6 +62,7 @@ The following platforms support different build systems
 
 * Corstone-700 : `Corstone-700 User guide <corstone-700/user-guide.rst>`__
 * Cortex A5 DesignStart : `Cortex A5 DesignStart User guide <ca5ds/user-guide.rst>`__
+* Corstone-500 : `Corstone-500 User guide <corstone-500/user-guide.rst>`__
 * Total Compute(TC0) : `Total Compute User guide <tc0/user-guide.rst>`__
 
 For Other platforms:
@@ -90,6 +91,7 @@ The following platform user guides are maintained in this git repository:
 - `Neoverse(TM) N1 SDP <n1sdp/run-on-n1sdp.rst>`__
 - `Corstone-700 <corstone-700/user-guide.rst>`__
 - `Cortex A5 DesignStart User guide <ca5ds/user-guide.rst>`__
+- `Corstone-500 User guide <corstone-500/user-guide.rst>`__
 - `Juno Development Board User guide <juno/user-guide.rst>`__
 - `Armv8-A Base Platform FVP User guide <basefvp/user-guide.rst>`__
 - `System Guidance for Mobile, SGM-775 FVP User guide <sgm775/user-guide.rst>`__
diff --git a/readme.rst b/readme.rst
index 710346c..b89acd0 100644
--- a/readme.rst
+++ b/readme.rst
@@ -74,6 +74,7 @@ The following platforms are supported:
 - `TC2 <https://community.arm.com/developer/tools-software/oss-platforms/w/docs/227/tc2>`__
 - `Corstone-700 <https://community.arm.com/developer/tools-software/oss-platforms/w/docs/444/corstone-700>`__
 - `Cortex A5 DesignStart <https://community.arm.com/developer/tools-software/oss-platforms/w/docs/447/cortex-a5-designstart>`__
+- `Corstone-500 <https://community.arm.com/developer/tools-software/oss-platforms/w/docs/615/corstone-500>`__
 - `Total Compute(TC0) <https://community.arm.com/developer/tools-software/oss-platforms/w/docs/total-compute>`__
 
 The following platforms are also supported, but currently require users to
diff --git a/sync_workspace.py b/sync_workspace.py
index e98c3b3..a32d22b 100755
--- a/sync_workspace.py
+++ b/sync_workspace.py
@@ -1,7 +1,7 @@
 #!/usr/bin/env python3
 
 """
- " Copyright (c) 2019, Arm Limited. All rights reserved.
+ " Copyright (c) 2019-2020, Arm Limited. All rights reserved.
  " Author: Ash Wilding <ash.wilding@arm.com>
  "
  " SPDX-License-Identifier: BSD-3-Clause
@@ -604,6 +604,32 @@ ARMPLATDB = {
           "fw.platsw", # Hide it from final configuration summary
         ],
       },
+
+      ### Corstone-500
+      "500": {
+        "name": "Corstone-500",
+        "pdir": "corstone500",
+        "mrel": "???",
+        "tagkey": "CORSTONE-500",
+        "knowntag": "{tagkey}-2020.11.27",
+        "build": "yocto",
+        "docs": "docs/{pdir}",
+        "platsw": {
+          "manifest": "{pdir}.xml",
+        },
+        "k": "null",
+        "fs": "null",
+        "fw": [
+          "fw.platsw",
+        ],
+        "pb": "null",
+        "includes": [
+          "oc.tfa", "oc.uboot", "oc.pokytiny",
+        ],
+        "excludes": [
+          "fw.platsw", # Hide it from final configuration summary
+        ],
+      },
     },
 
     ### DesignStart
@@ -642,7 +668,7 @@ ARMPLATDB = {
     "all": [
       "p.board.juno.64b", "p.board.juno.legacy", "p.board.tc2",
       "p.fvp.v8a.base.64b", "p.fvp.v8a.base.legacy", "p.fvp.v8a.fndn.64b",
-      "p.fvp.sg.m.775", "p.board.n1sdp", "p.corstone.700", "p.ds.a5",
+      "p.fvp.sg.m.775", "p.board.n1sdp", "p.corstone.700", "p.ds.a5", "p.corstone.500",
     ],
   },
 
@@ -1072,6 +1098,12 @@ ARMPLATDB = {
       "priority": 60,
     },
 
+     ### Poky-Tiny Linux
+     "pokytiny": {
+       "name": "Poky-Tiny Linux distribution",
+       "priority": 60,
+     },
+
     ### CMSIS
     "cmsis": {
       "name": "Arm CMSIS",