Commit 63bc4b8d authored by Xueliang Zhong's avatar Xueliang Zhong
Browse files

corstone1000: add documentation for corstone1000



This commit adds documentation for corstone1000 on MPS3 FPGA.
Signed-off-by: Xueliang Zhong's avatarXueliang Zhong <xueliang.zhong@arm.com>
parent db45558e
......@@ -4,11 +4,28 @@ Change Log
This document contains a summary of the new features, changes and
fixes in each release of Corstone-1000 software stack.
Version 2021.12.15
------------------
Features added
~~~~~~~~~~~~~~
- Enabling Corstone1000 FPGA support on:
- Linux 5.10
- OP-TEE 3.14
- Trusted Firmware-A 2.5
- Trusted Firmware-M 1.5
- Building and running psa-arch-tests
- Adding openamp support in SE proxy SP
- OP-TEE: adding smm-gateway partition
- U-Boot: introducing Arm FF-A and MM support
Version 2021.10.29
------------------
Features added
~~~~~~~~~~~~~~
- Enabling Corstone1000 FVP support on:
- Linux 5.10
- OP-TEE 3.14
......
......@@ -3,6 +3,41 @@
.. contents::
Release notes - 2021.12.15
==========================
Software Features
------------------
The following components are present in the release:
- Yocto version Honister
- Linux kernel version 5.10
- U-Boot 2021.07
- OP-TEE version 3.14
- Trusted Firmware-A 2.5
- Trusted Firmware-M 1.5
- OpenAMP 347397decaa43372fc4d00f965640ebde042966d
- Trusted Services a365a04f937b9b76ebb2e0eeade226f208cbc0d2
Platform Support
----------------
- This software release is tested on Corstone1000 FPGA version AN550_v1
- 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
---------------------------
- The following tests only work on Corstone1000 FPGA: ACS tests (SCT, FWTS,
BSA), manual capsule update test, Linux distro install and boot, and
psa-arch-tests.
- Only the manual capsule update from UEFI shell is supported on FPGA.
- Due to flash size limitation and to support A/B banks,the wic image provided
by the user should be smaller than 15MB.
- The failures in PSA Arch Crypto Test are known limitations with crypto
library. It requires further investigation. The user can refer to `PSA Arch Crypto Test Failure Analysis In TF-M V1.5 Release <https://developer.trustedfirmware.org/w/tf_m/release/psa_arch_crypto_test_failure_analysis_in_tf-m_v1.5_release/>`__
for the reason for each failing test.
Release notes - 2021.10.29
==========================
......@@ -28,7 +63,6 @@ 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
- When booting Corstone1000 image on FVP on Windows, if autoboot stops due to some characters mistakenly added by telnet, the user needs to type 'boot' and hit enter to continue booting.
Support
-------
......
......@@ -29,7 +29,7 @@ The following prerequisites must be available on the host system. To resolve the
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
pylint3 xterm zstd liblz4-tool picocom
Provided components
-------------------
......@@ -37,9 +37,10 @@ Within the Yocto project, each component included in the Corstone-1000 software
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``.
The Yocto machine config files for the Corstone-1000 FVP and FPGA are:
- ``<_workspace>/meta-arm/meta-arm-bsp/conf/machine/include/corstone1000.inc``
- ``<_workspace>/meta-arm/meta-arm-bsp/conf/machine/corstone1000-fvp.conf``
- ``<_workspace>/meta-arm/meta-arm-bsp/conf/machine/corstone1000-mps3.conf``
Software for Host
......@@ -49,31 +50,31 @@ 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 |
+----------+----------------------------------------------------------------------------------------------------------+
+----------+---------------------------------------------------------------------------------------------------+
| bbappend | <_workspace>/meta-arm/meta-arm-bsp/recipes-bsp/trusted-firmware-a/trusted-firmware-a_2.5.bbappend |
+----------+---------------------------------------------------------------------------------------------------+
| Recipe | <_workspace>/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 |
+----------+-------------------------------------------------------------------------------------------+
+----------+------------------------------------------------------------------------------------+
| bbappend | <_workspace>/meta-arm/meta-arm-bsp/recipes-security/optee/optee-os_3.14.0.bbappend |
+----------+------------------------------------------------------------------------------------+
| Recipe | <_workspace>/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 |
+----------+--------------------------------------------------------------------------------+
+----------+---------------------------------------------------------------------+
| bbappend | <_workspace>/meta-arm/meta-arm/recipes-bsp/u-boot/u-boot_%.bbappend |
+----------+---------------------------------------------------------------------+
| Recipe | <_workspace>/poky/meta/recipes-bsp/u-boot/u-boot_2021.07.bb |
+----------+---------------------------------------------------------------------+
Linux
*****
......@@ -88,72 +89,327 @@ recipe responsible for building a tiny version of linux is listed below.
+-----------+----------------------------------------------------------------------------------------------+
| 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 |
| defconfig | <_workspace>/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 |
+----------+--------------------------------------------------------------------------------------------------------+
+----------+-------------------------------------------------------------------------------------------------+
| bbappend | <_workspace>/meta-arm/meta-arm-bsp/recipes-bsp/trusted-firmware-m/trusted-firmware-m_%.bbappend |
+----------+-------------------------------------------------------------------------------------------------+
| Recipe | <_workspace>/meta-arm/meta-arm/recipes-bsp/trusted-firmware-m/trusted-firmware-m_1.4.0.bb |
+----------+-------------------------------------------------------------------------------------------------+
Building the Software stack
The TF-M version has been bumped to 1.5, however the
trusted-firmware-m_1.4.0.bb recipe file is used.
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:
commands to build the stack. To install kas tool, 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.
sudo pip3 install kas
In the top directory of the workspace ``<_workspace>``, run:
::
git clone https://git.yoctoproject.org/git/meta-arm -b CORSTONE1000-2021.11.03
wget -c https://raw.githubusercontent.com/siemens/kas/master/kas-container
chmod +x kas-container
./kas-container build meta-arm/kas/corstone1000-fvp.yml
git clone https://git.yoctoproject.org/git/meta-arm -b CORSTONE1000-2021.12.15
To build corstone1000 image for MPS3 FPGA, run:
::
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).
kas shell meta-arm/kas/corstone1000-mps3.yml
bitbake corstone1000-image
Once the build is successful, all output binaries will be placed in the
``<_workspace>/build/tmp/deploy/images/corstone1000-fvp/`` folder.
Alternatively, to build corstone1000 image for FVP, run:
::
kas shell meta-arm/kas/corstone1000-fvp.yml
bitbake corstone1000-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 output binaries will be placed in the following folders:
- ``<_workspace>/build/tmp/deploy/images/corstone1000-fvp/`` folder for FVP build;
- ``<_workspace>/build/tmp/deploy/images/corstone1000-mps3/`` folder for FPGA build.
Everything apart from the ROM firmware is bundled into a single binary, the
``corstone1000-image-corstone1000-fvp.wic.nopt`` file.
``corstone1000-image-corstone1000-{mps3,fvp}.wic.nopt`` file. The ROM firmware is the
``bl1.bin`` 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``
- The flash image: ``<_workspace>/build/tmp/deploy/images/corstone1000-fvp/corstone1000-image-corstone1000-fvp.wic.nopt``
The output binaries used by FPGA are the following:
- The ROM firmware: ``<_workspace>/build/tmp/deploy/images/corstone1000-mps3/bl1.bin``
- The flash image: ``<_workspace>/build/tmp/deploy/images/corstone1000-mps3/corstone1000-image-corstone1000-mps3.wic.nopt``
Flash the firmware image on FPGA
--------------------------------
The Arm MPS3 FPGA image will be available soon. Please contact support@arm.com if you have any questions.
The directory structure of the FPGA bundle is shown below.
::
Boardfiles
├── MB
│   ├── BRD_LOG.TXT
│   ├── HBI0309B
│   │   ├── AN550
│   │   │   ├── AN550_v1.bit
│   │   │   ├── an550_v1.txt
│   │   │   └── images.txt
│   │   ├── board.txt
│   │   └── mbb_v210.ebf
│   └── HBI0309C
│   ├── AN550
│   │   ├── AN550_v1.bit
│   │   ├── an550_v1.txt
│   │   └── images.txt
│   ├── board.txt
│   └── mbb_v210.ebf
├── SOFTWARE
│   ├── ES0.bin
│   ├── SE.bin
│   └── an550_st.axf
└── config.txt
Depending upon the MPS3 board version (printed on the MPS3 board) you should update the images.txt file
(in corresponding HBI0309x folder) so that the file points to the images under SOFTWARE directory.
Here is an example
::
;************************************************
; Preload port mapping *
;************************************************
; PORT 0 & ADDRESS: 0x00_0000_0000 QSPI Flash (XNVM) (32MB)
; PORT 0 & ADDRESS: 0x00_8000_0000 OCVM (DDR4 2GB)
; PORT 1 Secure Enclave (M0+) ROM (64KB)
; PORT 2 External System 0 (M3) Code RAM (256KB)
; PORT 3 Secure Enclave OTP memory (8KB)
; PORT 4 CVM (4MB)
;************************************************
[IMAGES]
TOTALIMAGES: 2 ;Number of Images (Max: 32)
IMAGE0PORT: 1
IMAGE0ADDRESS: 0x00_0000_0000
IMAGE0UPDATE: RAM
IMAGE0FILE: \SOFTWARE\bl1.bin
IMAGE1PORT: 0
IMAGE1ADDRESS: 0x00_00010_0000
IMAGE1UPDATE: AUTOQSPI
IMAGE1FILE: \SOFTWARE\cs1000.bin
OUTPUT_DIR = ``<_workspace>/build/tmp/deploy/images/corstone1000-mps3``
1. Copy ``bl1.bin`` from OUTPUT_DIR directory to SOFTWARE directory of the FPGA bundle.
2. Copy ``corstone1000-image-corstone1000-mps3.wic.nopt`` from OUTPUT_DIR directory to SOFTWARE
directory of the FPGA bundle and rename the wic image to ``cs1000.bin``.
**NOTE:** Renaming of the images are required because MCC firmware has
limitation of 8 characters before .(dot) and 3 characters after .(dot).
Now, copy the entire folder to board's SDCard and reboot the board.
Running the software on FPGA
----------------------------
On the host machine, open 3 minicom sessions. In case of Linux machine it will
be ttyUSB0, ttyUSB1, ttyUSB2 and it might be different on Window machine.
- ttyUSB0 for MCC, OP-TEE and Secure Partition
- ttyUSB1 for Boot Processor (Cortex-M0+)
- ttyUSB2 for Host Processor (Cortex-A35)
Run following commands to open minicom sessions on Linux:
::
sudo picocom -b 115200 /dev/ttyUSB0 # in one terminal
sudo picocom -b 115200 /dev/ttyUSB1 # in another terminal
sudo picocom -b 115200 /dev/ttyUSB2 # in another terminal.
Once the system is booted complete, you should see console
logs on the minicom sessions. Once the HOST(Cortex-A35) is
booted completely, user can login to the shell using
**"root"** login.
Running test applications (applicable to FPGA only)
----------------------------------------------------------
Run SystemReady-IR ACS tests
############################
First, the user should prepare a USB stick with ACS image. Provided the USB
device is sda, run the following commands to prepare the ACS image in USB
stick:
::
wget https://github.com/ARM-software/arm-systemready/raw/main/IR/prebuilt_images/v21.09_1.0/ir_acs_live_image.img.xz
unxz ir_acs_live_image.img.xz
sudo dd if=ir_acs_live_image.img of=/dev/sda iflag=direct oflag=direct bs=1M status=progress; sync
Once the USB stick with ACS image is prepared, the user should make sure that
ensure that only the USB stick with the ACS image is connected to the board,
and then boot the board. U-Boot should be able to boot the grub bootloader from
the 1st partition and if grub is not interrupted, tests are executed
automatically in the following sequence:
- SCT
- UEFI BSA
- FWTS
- BSA Linux
The results can be fetched from the ``acs_results`` partition of the USB stick.
Manual capsule update test
##########################
The following steps describe running manual capsule update with the ``direct``
method.
First, the user should prepare a USB stick with ACS image (see above). Then,
download edk2 and generate capsule file:
::
git clone https://github.com/tianocore/edk2.git
edk2/BaseTools/BinWrappers/PosixLike/GenerateCapsule -e -o \
cs1k_cap --fw-version 1 --lsv 0 --guid \
e2bb9c06-70e9-4b14-97a3-5a7913176e3f --verbose --update-image-index \
0 --verbose <binary_file>
The <binary_file> here should be a wic image. And this input binary file
(capsule) should be less than 15 MB.
Based on the user's requirement, the user can change the firmware version
number given to --fw-version option (the version number needs to be >= 1).
Place the generated ``cs1k_cap`` file in the root directory of the boot partition in
the USB stick. Note: As we are running the direct method, the ``cs1k_cap`` file should
not be under the EFI/UpdateCapsule directory as this may or may not trigger the
on disk method.
Boot the board and reach u-boot shell. Run the EFI Shell. In the EFI Shell, run:
::
FS0:
EFI/BOOT/app/CapsuleApp.efi cs1k_cap
Linux distro install and boot
#############################
To test Linux distro install and boot, the user should prepare two empty USB sticks.
Download one of following Linux distro images:
- Debian installer image: https://cdimage.debian.org/cdimage/weekly-builds/arm64/iso-dvd/
- OpenSUSE Tumbleweed installer image: http://download.opensuse.org/ports/aarch64/tumbleweed/iso/
- The user should look for a DVD Snapshot like openSUSE-Tumbleweed-DVD-aarch64-Snapshot20211125-Media.iso
Once the .iso file is downloaded, the .iso file needs to be flashed to your USB drive.
In the given example here, we assume the USB device is /dev/sdb (the user
should use `lsblk` command to confirm). Be cautious here and don't confuse your
host PC's own hard drive with the USB drive. Then copy the contents of an iso
file into the first USB stick, run:
::
sudo dd if=/path/to/iso_file of=/dev/sdb iflag=direct oflag=direct status=progress bs=1M; sync;
Boot the MSP3 board with the first USB stick connected. Open following minicom sessions:
::
sudo picocom -b 115200 /dev/ttyUSB0 # in one terminal
sudo picocom -b 115200 /dev/ttyUSB2 # in another terminal.
Press <Ctrl+x>.
Now plug in the second USB stick, the distro installation process will start.
**NOTE:** Due to the performance limitation of Corstone1000 MPS3 FPGA, the
distro installation process can take up to 24 hours to complete.
Once installation is complete, unplug the first USB stick and reboot the board.
After successfully installing and booting the Linux distro, the user should see
a login prompt:
::
debian login:
Login with the username root.
Run psa-arch-test
#################
The user should make sure there is no USB stick connected to the board. Power
on the board and boot the board to Linux. Then, the user should follow the
steps below to run the psa_arch_tests.
As a reference for the user's test results, the psa-arch-test report for `Corstone1000 software (CORSTONE1000-2021.12.15) <https://git.yoctoproject.org/meta-arm/tag/?h=CORSTONE1000-2021.12.15>`__
can be found in `here <https://gitlab.arm.com/arm-reference-solutions/arm-reference-solutions-test-report/-/tree/master/embedded-a/corstone1000>`__.
First, create a file containing SE_PROXY_SP UUID. Run:
::
echo 46bb39d1-b4d9-45b5-88ff-040027dab249 > sp_uuid_list.txt
Then, load FFA driver module into Linux kernel. Run:
::
load_ffa_debugfs.sh .
Then, check whether the FFA driver loaded correctly by using the following command:
::
cat /proc/modules | grep arm_ffa_user
The output should be:
::
arm_ffa_user 16384 - - Live 0xffffffc0084b0000 (O)
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:
Now, run the PSA arch tests with follow commands:
::
cd meta-arm-image && git checkout CORSTONE-1000-2021.10.26 && cd -
cd run-scripts && git checkout CORSTONE-1000-2021.10.26 && cd -
psa-iat-api-test
psa-crypto-api-test
psa-its-api-test
psa-ps-api-test
Running the software on FVP
---------------------------
......
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