Commit f382016e authored by Xueliang Zhong's avatar Xueliang Zhong
Browse files

corstone1000: add documentation for corstone1000


Signed-off-by: Xueliang Zhong's avatarXueliang Zhong <xueliang.zhong@arm.com>
parent ddd2e3a7
Change Log
==========
This document contains a summary of the new features, changes and
fixes in each release of Corstone-1000 software stack.
Version 2021.10.29
------------------
Features added
~~~~~~~~~~~~~~
- Enabling Corstone1000 FVP support on:
- Linux 5.10
- OP-TEE 3.14
- Trusted Firmware-A 2.5
- Trusted Firmware-M 1.4
- Linux kernel: enabling EFI, adding FF-A debugfs driver, integrating ARM_FFA_TRANSPORT.
- U-Boot: Extending EFI support
- python3-imgtool: adding recipe for Trusted-firmware-m
- python3-imgtool: adding the Yocto recipe used in signing host images (based on MCUBOOT format)
Changes
~~~~~~~
--------------
*Copyright (c) 2021, Arm Limited. All rights reserved.*
.. section-numbering::
:suffix: .
.. contents::
Release notes - 2021.10.29
==========================
Software Features
------------------
This initial release of Corstone-1000 supports booting Linux on the Cortex-A35
and TF-M/MCUBOOT in the Secure Enclave. The following components are present in
the release:
- Linux kernel version 5.10
- U-Boot 2021.07
- OP-TEE version 3.14
- Trusted Firmware-A 2.5
- Trusted Firmware-M 1.4
Platform Support
----------------
- This Software release is tested on Corstone1000 Fast Model platform (FVP) version 11.16.21
https://developer.arm.com/tools-and-software/open-source-software/arm-platforms-software/arm-ecosystem-fvps
Known Issues or Limitations
---------------------------
- No software support for external system(Cortex M3)
- No communication established between A35 and M0+
- Very basic functionality of booting Secure Enclave, Trusted Firmware-A , OP-TEE , u-boot and Linux are performed
Support
-------
For support email: support-subsystem-iot@arm.com
--------------
*Copyright (c) 2021, Arm Limited. All rights reserved.*
User Guide
==========
.. section-numbering::
:suffix: .
.. contents::
Notice
------
The Corstone-1000 software stack uses the `Yocto project <https://www.yoctoproject.org/>`__ to build
a tiny Linux distribution suitable for the Corstone-1000 platform. The yocto project relies on the
`Bitbake <https://www.yoctoproject.org/docs/3.1/bitbake-user-manual/bitbake-user-manual.html>`__
tool as its build tool. Please see `Yocto mega manual <https://www.yoctoproject.org/docs/latest/mega-manual/mega-manual.html>`__
for more information.
Prerequisites
-------------
These instructions assume your host PC is running Ubuntu Linux 18.04 LTS, with
at least 32GB of free disk space and 16GB of RAM as minimum requirement. The
following instructions expect that you are using a bash shell.
The following prerequisites must be available on the host system. To resolve these dependencies, run:
::
sudo apt-get update
sudo apt-get install gawk wget git-core diffstat unzip texinfo gcc-multilib \
build-essential chrpath socat cpio python3 python3-pip python3-pexpect \
xz-utils debianutils iputils-ping python3-git python3-jinja2 libegl1-mesa libsdl1.2-dev \
pylint3 xterm zstd liblz4-tool docker.io
Provided components
-------------------
Within the Yocto project, each component included in the Corstone-1000 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-1000 BSP is located at:
``<_workspace>/meta-arm/meta-arm-bsp/``.
The Yocto machine config files for the Corstone-1000 FVP are:
``<_workspace>/meta-arm/meta-arm-bsp/conf/machine/include/corstone1000.inc``.
``<_workspace>/meta-arm/meta-arm-bsp/conf/machine/corstone1000-fvp.conf``.
Software for Host
#################
Trusted Firmware-A
******************
Based on `Trusted Firmware-A <https://git.trustedfirmware.org/TF-A/trusted-firmware-a.git>`__
+----------+----------------------------------------------------------------------------------------------------------+
| bbappend | <_workspace>/layers/meta-arm/meta-arm-bsp/recipes-bsp/trusted-firmware-a/trusted-firmware-a_2.5.bbappend |
+----------+----------------------------------------------------------------------------------------------------------+
| Recipe | <_workspace>/layers/meta-arm/meta-arm/recipes-bsp/trusted-firmware-a/trusted-firmware-a_2.5.bb |
+----------+----------------------------------------------------------------------------------------------------------+
OP-TEE
******
Based on `OP-TEE <https://git.trustedfirmware.org/OP-TEE/optee_os.git>`__
+----------+-------------------------------------------------------------------------------------------+
| bbappend | <_workspace>/layers/meta-arm/meta-arm-bsp/recipes-security/optee/optee-os_3.14.0.bbappend |
+----------+-------------------------------------------------------------------------------------------+
| Recipe | <_workspace>/layers/meta-arm/meta-arm/recipes-security/optee/optee-os_3.14.0.bb |
+----------+-------------------------------------------------------------------------------------------+
U-Boot
******
Based on `U-Boot <git://git.denx.de/u-boot.git>`__
+----------+--------------------------------------------------------------------------------+
| bbappend | <_workspace>/layers/meta-arm/meta-arm-bsp/recipes-bsp/u-boot/u-boot_%.bbappend |
+----------+--------------------------------------------------------------------------------+
| Recipe | <_workspace>/poky/meta/recipes-bsp/u-boot/u-boot_2021.07.bb |
+----------+--------------------------------------------------------------------------------+
Linux
*****
The distro is based on the `poky-tiny <https://wiki.yoctoproject.org/wiki/Poky-Tiny>`__
distribution which is a Linux distribution stripped down to a minimal configuration.
The provided distribution is based on busybox and built using muslibc. The
recipe responsible for building a tiny version of linux is listed below.
+-----------+----------------------------------------------------------------------------------------------+
| bbappend | <_workspace>/meta-arm/meta-arm-bsp/recipes-kernel/linux/linux-yocto_%.bbappend |
+-----------+----------------------------------------------------------------------------------------------+
| Recipe | <_workspace>/poky/meta/recipes-kernel/linux/linux-yocto_5.10.bb |
+-----------+----------------------------------------------------------------------------------------------+
| defconfig | <_workspace>/layers/meta-arm/meta-arm-bsp/recipes-kernel/linux/files/corstone1000/defconfig |
+-----------+----------------------------------------------------------------------------------------------+
Software for Boot Processor (a.k.a Secure Enclave)
##################################################
Based on `Trusted Firmware-M <https://git.trustedfirmware.org/TF-M/trusted-firmware-m.git>`__
+----------+--------------------------------------------------------------------------------------------------------+
| bbappend | <_workspace>/layers/meta-arm/meta-arm-bsp/recipes-bsp/trusted-firmware-m/trusted-firmware-m_%.bbappend |
+----------+--------------------------------------------------------------------------------------------------------+
| Recipe | <_workspace>/layers/meta-arm/meta-arm/recipes-bsp/trusted-firmware-m/trusted-firmware-m_1.4.0.bb |
+----------+--------------------------------------------------------------------------------------------------------+
Building the Software stack
---------------------------
Create a new folder that will be your workspace and will henceforth be referred
to as ``<_workspace>`` in these instructions. To create the folder, run:
::
mkdir <_workspace>
cd <_workspace>
Corstone-1000 is a Bitbake based Yocto distro which uses kas and bitbake
commands to build the stack. The kas-container tool requires docker. To
configure docker environment correctly, the user should have sudo access on the
system and should add the current user to the docker group, run:
::
sudo groupadd docker
sudo usermod -aG docker $USER
Note that the change to groups is not immediately applied, the user should
logout/login or restart the machine after executing above commands.
In the top directory of the workspace ``<_workspace>``, run:
::
git clone https://git.yoctoproject.org/git/meta-arm
cd meta-arm && git checkout 8b82d1230d6d5f79c74fc09332abc4a729e1c43d && cd -
wget -c https://raw.githubusercontent.com/siemens/kas/master/kas-container
chmod +x kas-container
./kas-container build meta-arm/kas/corstone1000-fvp.yml
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 output binaries will be placed in the
``<_workspace>/build/tmp/deploy/images/corstone1000-fvp/`` folder.
Everything apart from the ROM firmware is bundled into a single binary, the
``corstone1000-image-corstone1000-fvp.wic.nopt`` file.
The output binaries used by FVP are the following:
- The ROM firmware: ``<_workspace>/build/tmp/deploy/images/corstone1000-fvp/bl1.bin``
- The flash image: ``corstone1000-image-corstone1000-fvp.wic.nopt``
For ``<_workspace>/meta-arm-image`` and ``<_workspace>/run-scripts``, the user
should use the ``CORSTONE-1000-2021.10.26`` tag along with the Corstone-1000
software stack. To achieve this, in ``<_workspace>`` folder run:
::
cd meta-arm-image && git checkout CORSTONE-1000-2021.10.26 && cd -
cd run-scripts && git checkout CORSTONE-1000-2021.10.26 && cd -
Running the software on FVP
---------------------------
An FVP (Fixed Virtual Platform) of the Corstone-1000 platform must be available to execute the
included run script.
The fixed virtual platform (FVP) version 11.16.21 can be downloaded from the
`Arm Ecosystem FVPs`_ page. On this page, navigate to "Corstone IoT FVPs"
section to download the Corstone1000 platform FVP installer. Follow the
instructions of the installer and setup the FVP.
The run-scripts structure is as below:
::
run-scripts
|── corstone1000
└── run_model.sh
|── ...
Ensure that the FVP has its dependencies met by executing the FVP from its installation folder:
``./<Corstone-1000 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 "<_workspace>/run-scripts/corstone1000/" folder runs the FVP with
the previously built images as arguments. Execute the ``run_model.sh`` script:
::
./run_model.sh ${FVP installation path/<Corstone-1000 FVP Binary>}
When the script is executed, three terminal instances will be launched, one for the boot processor
(aka Secure Enclave) processing element and two for the Host processing element. Once the FVP is
executing, the Boot Processor will start to boot, wherein the relevant memory contents of the .wic
file are copied to their respective memory locations within the model, enforce firewall policies
on memories and peripherals and then, bring the host out of reset.
The host will boot trusted-firmware-a, OP-TEE, U-Boot and then Linux, and present a login prompt
(FVP host_terminal_0):
::
corstone1000-fvp login:
Login using the username root.
--------------
*Copyright (c) 2021, Arm Limited. All rights reserved.*
.. _Arm Ecosystem FVPs: https://developer.arm.com/tools-and-software/open-source-software/arm-platforms-software/arm-ecosystem-fvps
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment