diff options
Diffstat (limited to 'meta-arm/meta-arm-bsp/documentation/corstone1000/user-guide.rst')
| -rw-r--r-- | meta-arm/meta-arm-bsp/documentation/corstone1000/user-guide.rst | 518 |
1 files changed, 343 insertions, 175 deletions
diff --git a/meta-arm/meta-arm-bsp/documentation/corstone1000/user-guide.rst b/meta-arm/meta-arm-bsp/documentation/corstone1000/user-guide.rst index e173f244b4..a5ccb31382 100644 --- a/meta-arm/meta-arm-bsp/documentation/corstone1000/user-guide.rst +++ b/meta-arm/meta-arm-bsp/documentation/corstone1000/user-guide.rst @@ -1,5 +1,5 @@ .. - # Copyright (c) 2022, Arm Limited. + # Copyright (c) 2022-2023, Arm Limited. # # SPDX-License-Identifier: MIT @@ -15,21 +15,35 @@ The Yocto Project relies on the `Bitbake <https://docs.yoctoproject.org/bitbake. tool as its build tool. Please see `Yocto Project documentation <https://docs.yoctoproject.org/>`__ for more information. - Prerequisites ------------- -These instructions assume your host PC is running Ubuntu Linux 18.04 or 20.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. All the paths stated in this document are absolute paths. -The following prerequisites must be available on the host system. To resolve these dependencies, run: +This guide assumes that your host PC is running Ubuntu 20.04 LTS, with at least +32GB of free disk space and 16GB of RAM as minimum requirement. -:: +The following prerequisites must be available on the host system: + +- Git 1.8.3.1 or greater +- tar 1.28 or greater +- Python 3.8.0 or greater. +- gcc 8.0 or greater. +- GNU make 4.0 or greater + +Please follow the steps described in the Yocto mega manual: + +- `Compatible Linux Distribution <https://docs.yoctoproject.org/singleindex.html#compatible-linux-distribution>`__ +- `Build Host Packages <https://docs.yoctoproject.org/singleindex.html#build-host-packages>`__ + +Targets +------- - 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 libegl1-mesa libsdl1.2-dev \ - xterm zstd liblz4-tool picocom - sudo apt-get upgrade libstdc++6 +- `Arm Corstone-1000 Ecosystem FVP (Fixed Virtual Platform) <https://developer.arm.com/downloads/-/arm-ecosystem-fvps>`__ +- `Arm Corstone-1000 for MPS3 <https://developer.arm.com/documentation/dai0550/latest/>`__ + +Yocto stable branch +------------------- + +Corstone-1000 software stack is built on top of Yocto mickledore. Provided components ------------------- @@ -44,6 +58,8 @@ The Yocto machine config files for the Corstone-1000 FVP and FPGA targets are: - ``<_workspace>/meta-arm/meta-arm-bsp/conf/machine/corstone1000-fvp.conf`` - ``<_workspace>/meta-arm/meta-arm-bsp/conf/machine/corstone1000-mps3.conf`` +**NOTE:** All the paths stated in this document are absolute paths. + ***************** Software for Host ***************** @@ -52,50 +68,52 @@ Trusted Firmware-A ================== Based on `Trusted Firmware-A <https://git.trustedfirmware.org/TF-A/trusted-firmware-a.git>`__ -+----------+---------------------------------------------------------------------------------------------------+ -| bbappend | <_workspace>/meta-arm/meta-arm-bsp/recipes-bsp/trusted-firmware-a/trusted-firmware-a_2.7.bbappend | -+----------+---------------------------------------------------------------------------------------------------+ -| Recipe | <_workspace>/meta-arm/meta-arm/recipes-bsp/trusted-firmware-a/trusted-firmware-a_2.7.bb | -+----------+---------------------------------------------------------------------------------------------------+ ++----------+-----------------------------------------------------------------------------------------------------+ +| bbappend | <_workspace>/meta-arm/meta-arm-bsp/recipes-bsp/trusted-firmware-a/trusted-firmware-a_2.8.%.bbappend | ++----------+-----------------------------------------------------------------------------------------------------+ +| Recipe | <_workspace>/meta-arm/meta-arm/recipes-bsp/trusted-firmware-a/trusted-firmware-a_2.8.0.bb | ++----------+-----------------------------------------------------------------------------------------------------+ OP-TEE ====== Based on `OP-TEE <https://git.trustedfirmware.org/OP-TEE/optee_os.git>`__ +----------+------------------------------------------------------------------------------------+ -| bbappend | <_workspace>/meta-arm/meta-arm-bsp/recipes-security/optee/optee-os_3.18.0.bbappend | +| bbappend | <_workspace>/meta-arm/meta-arm-bsp/recipes-security/optee/optee-os_3.20.0.bbappend | +----------+------------------------------------------------------------------------------------+ -| Recipe | <_workspace>/meta-arm/meta-arm/recipes-security/optee/optee-os_3.18.0.bb | +| Recipe | <_workspace>/meta-arm/meta-arm/recipes-security/optee/optee-os_3.20.0.bb | +----------+------------------------------------------------------------------------------------+ U-Boot -======= -Based on `U-Boot <https://gitlab.com/u-boot>`__ +====== +Based on `U-Boot repo`_ -+----------+---------------------------------------------------------------------+ -| bbappend | <_workspace>/meta-arm/meta-arm/recipes-bsp/u-boot/u-boot_%.bbappend | -+----------+---------------------------------------------------------------------+ -| Recipe | <_workspace>/poky/meta/recipes-bsp/u-boot/u-boot_2022.07.bb | -+----------+---------------------------------------------------------------------+ ++----------+-------------------------------------------------------------------------+ +| bbappend | <_workspace>/meta-arm/meta-arm/recipes-bsp/u-boot/u-boot_%.bbappend | ++----------+-------------------------------------------------------------------------+ +| bbappend | <_workspace>/meta-arm/meta-arm-bsp/recipes-bsp/u-boot/u-boot_%.bbappend | ++----------+-------------------------------------------------------------------------+ +| Recipe | <_workspace>/poky/meta/recipes-bsp/u-boot/u-boot_2023.01.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 +The provided distribution is based on busybox and built using musl libc. 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.19.bb | +| Recipe | <_workspace>/poky/meta/recipes-kernel/linux/linux-yocto_6.1.bb | +-----------+----------------------------------------------------------------------------------------------+ | defconfig | <_workspace>/meta-arm/meta-arm-bsp/recipes-kernel/linux/files/corstone1000/defconfig | +-----------+----------------------------------------------------------------------------------------------+ External System Tests -======================= +===================== Based on `Corstone-1000/applications <https://git.gitlab.arm.com/arm-reference-solutions/corstone1000/applications>`__ +------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ @@ -109,15 +127,15 @@ 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>/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.6.0.bb | -+----------+-------------------------------------------------------------------------------------------------+ ++----------+-----------------------------------------------------------------------------------------------------+ +| bbappend | <_workspace>/meta-arm/meta-arm-bsp/recipes-bsp/trusted-firmware-m/trusted-firmware-m_1.7.%.bbappend | ++----------+-----------------------------------------------------------------------------------------------------+ +| Recipe | <_workspace>/meta-arm/meta-arm/recipes-bsp/trusted-firmware-m/trusted-firmware-m_1.7.0.bb | ++----------+-----------------------------------------------------------------------------------------------------+ -************************************************** +******************************** Software for the External System -************************************************** +******************************** RTX ==== @@ -150,7 +168,7 @@ In the top directory of the workspace ``<_workspace>``, run: :: - git clone https://git.yoctoproject.org/git/meta-arm -b CORSTONE1000-2022.11.23 + git clone https://git.yoctoproject.org/git/meta-arm -b CORSTONE1000-2023.06 To build a Corstone-1000 image for MPS3 FPGA, run: @@ -173,46 +191,47 @@ Once the build is successful, all output binaries will be placed in the followin - ``<_workspace>/build/tmp/deploy/images/corstone1000-mps3/`` folder for FPGA build. Everything apart from the Secure Enclave ROM firmware and External System firmware, is bundled into a single binary, the -``corstone1000-image-corstone1000-{mps3,fvp}.wic.nopt`` file. +``corstone1000-image-corstone1000-{mps3,fvp}.wic`` file. The output binaries run in the Corstone-1000 platform are the following: - The Secure Enclave ROM firmware: ``<_workspace>/build/tmp/deploy/images/corstone1000-{mps3,fvp}/bl1.bin`` - The External System firmware: ``<_workspace>/build/tmp/deploy/images/corstone1000-{mps3,fvp}/es_flashfw.bin`` - - The flash image: ``<_workspace>/build/tmp/deploy/images/corstone1000-{mps3,fvp}/corstone1000-image-corstone1000-{mps3,fvp}.wic.nopt`` + - The flash image: ``<_workspace>/build/tmp/deploy/images/corstone1000-{mps3,fvp}/corstone1000-image-corstone1000-{mps3,fvp}.wic`` Flash the firmware image on FPGA -------------------------------- -The user should download the FPGA bit file image ``AN550: Arm® Corstone™-1000 for MPS3 Version 1`` +The user should download the FPGA bit file image ``AN550: Arm® Corstone™-1000 for MPS3 Version 2.0`` from `this link <https://developer.arm.com/tools-and-software/development-boards/fpga-prototyping-boards/download-fpga-images>`__ -and under the section ``Arm® Corstone™-1000 for MPS3``. +and under the section ``Arm® Corstone™-1000 for MPS3``. The download is available after logging in. 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 + Boardfiles + ├── config.txt + ├── MB + │ ├── BRD_LOG.TXT + │ ├── HBI0309B + │ │ ├── AN550 + │ │ │ ├── AN550_v2.bit + │ │ │ ├── an550_v2.txt + │ │ │ └── images.txt + │ │ ├── board.txt + │ │ └── mbb_v210.ebf + │ └── HBI0309C + │ ├── AN550 + │ │ ├── AN550_v2.bit + │ │ ├── an550_v2.txt + │ │ └── images.txt + │ ├── board.txt + │ └── mbb_v210.ebf + └── SOFTWARE + ├── an550_st.axf + ├── bl1.bin + ├── cs1000.bin + └── ES0.bin Depending upon the MPS3 board version (printed on the MPS3 board) you should update the images.txt file (in corresponding HBI0309x folder. Boardfiles/MB/HBI0309<board_revision>/AN550/images.txt) so that the file points to the images under SOFTWARE directory. @@ -242,7 +261,7 @@ stack can be seen below; IMAGE0FILE: \SOFTWARE\bl1.bin IMAGE1PORT: 0 - IMAGE1ADDRESS: 0x00_0010_0000 + IMAGE1ADDRESS: 0x00_0000_0000 IMAGE1UPDATE: AUTOQSPI IMAGE1FILE: \SOFTWARE\cs1000.bin @@ -256,10 +275,9 @@ 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 ``es_flashfw.bin`` from OUTPUT_DIR directory to SOFTWARE directory of the FPGA bundle and rename the binary to ``es0.bin``. -3. Copy ``corstone1000-image-corstone1000-mps3.wic.nopt`` from OUTPUT_DIR directory to SOFTWARE - directory of the FPGA bundle and rename the wic.nopt image to ``cs1000.bin``. +3. Copy ``corstone1000-image-corstone1000-mps3.wic`` 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). @@ -274,7 +292,7 @@ be ttyUSB0, ttyUSB1, ttyUSB2, ttyUSB3 and it might be different on Windows machi - ttyUSB0 for MCC, OP-TEE and Secure Partition - ttyUSB1 for Boot Processor (Cortex-M0+) - ttyUSB2 for Host Processor (Cortex-A35) - - ttyUSB3 for External System Processor (Cortex-M3) + - ttyUSB3 for External System Processor (Cortex-M3) Run following commands to open serial port terminals on Linux: @@ -285,12 +303,26 @@ Run following commands to open serial port terminals on Linux: sudo picocom -b 115200 /dev/ttyUSB2 # in another terminal. sudo picocom -b 115200 /dev/ttyUSB3 # in another terminal. +**NOTE:** The MPS3 expects an ethernet cable to be plugged in, otherwise it will +wait for the network for a considerable amount of time, printing the following +logs: + +:: + + Generic PHY 40100000.ethernet-ffffffff:01: attached PHY driver (mii_bus:phy_addr=40100000.ethernet-ffffffff:01, irq=POLL) + smsc911x 40100000.ethernet eth0: SMSC911x/921x identified at 0xffffffc008e50000, IRQ: 17 + Waiting up to 100 more seconds for network. + Once the system boot is completed, you should see console logs on the serial port terminals. Once the HOST(Cortex-A35) is booted completely, user can login to the shell using **"root"** login. -If system does not boot and only the ttyUSB1 logs are visible, please follow the steps in `Clean Secure Flash Before Testing (applicable to FPGA only)`_ under `SystemReady-IR tests`_ section. The previous image used in FPGA (MPS3) might have filled the Secure Flash completely. The best practice is to clean the secure flash in this case. +If system does not boot and only the ttyUSB1 logs are visible, please follow the +steps in `Clean Secure Flash Before Testing (applicable to FPGA only)`_ under +`SystemReady-IR tests`_ section. The previous image used in FPGA (MPS3) might +have filled the Secure Flash completely. The best practice is to clean the +secure flash in this case. Running the software on FVP @@ -321,7 +353,7 @@ To run the FVP using the runfvp command, please run the following command: 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.nopt +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. @@ -337,11 +369,11 @@ Login using the username root. The External System can be released out of reset on demand using the systems-comms-tests command. SystemReady-IR tests -------------------------- +-------------------- -********************* +************* Testing steps -********************* +************* **NOTE**: Running the SystemReady-IR tests described below requires the user to work with USB sticks. In our testing, not all USB stick models work well with @@ -359,7 +391,7 @@ erase the SecureEnclave flash cleanly and prepare a clean board environment for the testing. Clean Secure Flash Before Testing (applicable to FPGA only) -================================================================== +=========================================================== To prepare a clean board environment with clean secure flash for the testing, the user should prepare an image that erases the secure flash cleanly during @@ -368,17 +400,17 @@ boot. Run following commands to build such image. :: cd <_workspace> - git clone https://git.yoctoproject.org/git/meta-arm -b CORSTONE1000-2022.11.23 - git clone https://git.gitlab.arm.com/arm-reference-solutions/systemready-patch.git -b CORSTONE1000-2022.11.23 - cp -f systemready-patch/embedded-a/corstone1000/erase_flash/0001-arm-bsp-trusted-firmware-m-corstone1000-Clean-Secure.patch meta-arm + git clone https://git.yoctoproject.org/git/meta-arm -b CORSTONE1000-2023.06 + git clone https://git.gitlab.arm.com/arm-reference-solutions/systemready-patch.git -b CORSTONE1000-2023.06 + cp -f systemready-patch/embedded-a/corstone1000/erase_flash/0001-embedded-a-corstone1000-clean-secure-flash.patch meta-arm cd meta-arm - git apply 0001-arm-bsp-trusted-firmware-m-corstone1000-Clean-Secure.patch + git apply 0001-embedded-a-corstone1000-clean-secure-flash.patch cd .. kas build meta-arm/kas/corstone1000-mps3.yml Replace the bl1.bin and cs1000.bin files on the SD card with following files: - 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 + - The flash image: <_workspace>/build/tmp/deploy/images/corstone1000-mps3/corstone1000-image-corstone1000-mps3.wic Now reboot the board. This step erases the Corstone-1000 SecureEnclave flash completely, the user should expect following message from TF-M log (can be seen @@ -394,10 +426,16 @@ Then the user should follow "Building the software stack" to build a clean software stack and flash the FPGA as normal. And continue the testing. Run SystemReady-IR ACS tests -============================= +============================ + +Architecture Compliance Suite (ACS) is used to ensure architectural compliance +across different implementations of the architecture. Arm Enterprise ACS +includes a set of examples of the invariant behaviors that are provided by a +set of specifications for enterprise systems (For example: SBSA, SBBR, etc.), +so that implementers can verify if these behaviours have been interpreted correctly. ACS image contains two partitions. BOOT partition and RESULT partition. -Following packages are under BOOT partition +Following test suites and bootable applications are under BOOT partition: * SCT * FWTS @@ -406,12 +444,30 @@ Following packages are under BOOT partition * grub * uefi manual capsule application +BOOT partition contains the following: + +:: + + ├── EFI + │ └── BOOT + │ ├── app + │ ├── bbr + │ ├── bootaa64.efi + │ ├── bsa + │ ├── debug + │ ├── Shell.efi + │ └── startup.nsh + ├── grub + ├── grub.cfg + ├── Image + └── ramdisk-busybox.img + RESULT partition is used to store the test results. -PLEASE MAKE SURE THAT THE RESULT PARTITION IS EMPTY BEFORE YOU START THE TESTING. OTHERWISE THE TEST RESULTS +**NOTE**: PLEASE MAKE SURE THAT THE RESULT PARTITION IS EMPTY BEFORE YOU START THE TESTING. OTHERWISE THE TEST RESULTS WILL NOT BE CONSISTENT FPGA instructions for ACS image -================================ +=============================== This section describes how the user can build and run Architecture Compliance Suite (ACS) tests on Corstone-1000. @@ -449,10 +505,11 @@ 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. -The FPGA will reset multiple times during the test, and it might take approx. 24-36 hours to finish the test. At the end of test, the FPGA host terminal will halt showing a shell prompt. Once test is finished the result can be copied following above instructions. +The FPGA will reset multiple times during the test, and it might take approx. 24-36 hours to finish the test. + FVP instructions for ACS image and run -============================================ +====================================== Download ACS image from: - ``https://gitlab.arm.com/systemready/acs/arm-systemready/-/tree/linux-5.17-rc7/IR/prebuilt_images/v22.04_1.0-Linux-v5.17-rc7`` @@ -487,7 +544,7 @@ Once test is finished, the FVP can be stoped, and result can be copied following instructions. Common to FVP and FPGA -=========================== +====================== U-Boot should be able to boot the grub bootloader from the 1st partition and if grub is not interrupted, tests are executed @@ -496,14 +553,13 @@ automatically in the following sequence: - SCT - UEFI BSA - FWTS - - BSA Linux The results can be fetched from the ``acs_results`` folder in the RESULT partition of the USB stick (FPGA) / SD Card (FVP). ##################################################### Manual capsule update and ESRT checks ---------------------------------------------------------------------- +------------------------------------- The following section describes running manual capsule update with the ``direct`` method. @@ -518,63 +574,86 @@ incorrect capsule (corrupted or outdated) which fails to boot to the host softwa Check the "Run SystemReady-IR ACS tests" section above to download and unpack the ACS image file - ``ir_acs_live_image.img.xz`` -Download edk2 under <_workspace> : +Download edk2 under <_workspace>: :: git clone https://github.com/tianocore/edk2.git + cd edk2 + git checkout f2188fe5d1553ad1896e27b2514d2f8d0308da8a -********************* -Generating Capsules -********************* +Download systemready-patch repo under <_workspace>: +:: -The capsule binary size (wic.nopt file) should be less than 15 MB. + git clone https://git.gitlab.arm.com/arm-reference-solutions/systemready-patch.git -b CORSTONE1000-2023.06 -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). +******************* +Generating Capsules +******************* Generating FPGA Capsules ======================== :: - <_workspace>/edk2/BaseTools/BinWrappers/PosixLike/GenerateCapsule -e -o \ - cs1k_cap_mps3_v5 --fw-version 5 --lsv 0 --guid \ - e2bb9c06-70e9-4b14-97a3-5a7913176e3f --verbose --update-image-index \ - 0 --verbose <_workspace>/build/tmp/deploy/images/corstone1000-mps3/corstone1000-image-corstone1000-mps3.wic.nopt + cd <_workspace>/build/tmp/deploy/images/corstone1000-mps3/ + sh <_workspace>/systemready-patch/embedded-a/corstone1000/capsule_gen/capsule_gen.sh -d mps3 + +This will generate a file called "corstone1000_image.nopt" which will be used to +generate a UEFI capsule. :: - <_workspace>/edk2/BaseTools/BinWrappers/PosixLike/GenerateCapsule -e -o \ - cs1k_cap_mps3_v6 --fw-version 6 --lsv 0 --guid \ - e2bb9c06-70e9-4b14-97a3-5a7913176e3f --verbose --update-image-index \ - 0 --verbose <_workspace>/build/tmp/deploy/images/corstone1000-mps3/corstone1000-image-corstone1000-mps3.wic.nopt + cd <_workspace> + edk2/BaseTools/BinWrappers/PosixLike/GenerateCapsule -e -o cs1k_cap_mps3_v6 --fw-version 6 \ + --lsv 0 --guid e2bb9c06-70e9-4b14-97a3-5a7913176e3f --verbose --update-image-index 0 \ + --verbose build/tmp/deploy/images/corstone1000-mps3/corstone1000_image.nopt + + edk2/BaseTools/BinWrappers/PosixLike/GenerateCapsule -e -o cs1k_cap_mps3_v5 --fw-version 5 \ + --lsv 0 --guid e2bb9c06-70e9-4b14-97a3-5a7913176e3f --verbose --update-image-index 0 \ + --verbose build/tmp/deploy/images/corstone1000-mps3/corstone1000_image.nopt Generating FVP Capsules -======================== +======================= :: - <_workspace>/edk2/BaseTools/BinWrappers/PosixLike/GenerateCapsule -e -o \ - cs1k_cap_fvp_v6 --fw-version 6 --lsv 0 --guid \ - e2bb9c06-70e9-4b14-97a3-5a7913176e3f --verbose --update-image-index \ - 0 --verbose <_workspace>/build/tmp/deploy/images/corstone1000-fvp/corstone1000-image-corstone1000-fvp.wic.nopt + cd <_workspace>/build/tmp/deploy/images/corstone1000-fvp/ + sh <_workspace>/systemready-patch/embedded-a/corstone1000/capsule_gen/capsule_gen.sh -d fvp + +This will generate a file called "corstone1000_image.nopt" which will be used to +generate a UEFI capsule. + :: - <_workspace>/edk2/BaseTools/BinWrappers/PosixLike/GenerateCapsule -e -o \ - cs1k_cap_fvp_v5 --fw-version 5 --lsv 0 --guid \ - e2bb9c06-70e9-4b14-97a3-5a7913176e3f --verbose --update-image-index \ - 0 --verbose <_workspace>/build/tmp/deploy/images/corstone1000-fvp/corstone1000-image-corstone1000-fvp.wic.nopt + cd <_workspace> + edk2/BaseTools/BinWrappers/PosixLike/GenerateCapsule -e -o cs1k_cap_fvp_v6 \ + --fw-version 6 --lsv 0 --guid e2bb9c06-70e9-4b14-97a3-5a7913176e3f --verbose --update-image-index \ + 0 --verbose build/tmp/deploy/images/corstone1000-fvp/corstone1000_image.nopt -********************* + edk2/BaseTools/BinWrappers/PosixLike/GenerateCapsule -e -o cs1k_cap_fvp_v5 --fw-version 5 \ + --lsv 0 --guid e2bb9c06-70e9-4b14-97a3-5a7913176e3f --verbose --update-image-index \ + 0 --verbose build/tmp/deploy/images/corstone1000-fvp/corstone1000_image.nopt + + +Common Notes for FVP and FPGA +============================= + +The capsule binary size (wic file) 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). + + +**************** Copying Capsules -********************* +**************** Copying the FPGA capsules ========================= -The user should prepare a USB stick as explained in ACS image section (see above). +The user should prepare a USB stick as explained in ACS image section `FPGA instructions for ACS image`_. Place the generated ``cs1k_cap`` files 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 @@ -612,7 +691,7 @@ Then, unmount the IR image: **NOTE:** -Size of first partition in the image file is calculated in the following way. The data is +The size of first partition in the image file is calculated in the following way. The data is just an example and might vary with different ir_acs_live_image.img files. :: @@ -632,21 +711,21 @@ During this section we will be using the capsule with the higher version (cs1k_c and the capsule with the lower version (cs1k_cap_<fvp/mps3>_v5) for the negative scenario. Running the FVP with the IR prebuilt image -============================================== +========================================== Run the FVP with the IR prebuilt image: :: - <_workspace>/meta-arm/scripts/runfvp --terminals=xterm <_workspace>/build/tmp/deploy/images/corstone1000-fvp/corstone1000-image-corstone1000-fvp.fvpconf -- -C "board.msd_mmc.p_mmc_file ${<path-to-img>/ir_acs_live_image.img}" + <_workspace>/meta-arm/scripts/runfvp --terminals=xterm <_workspace>/build/tmp/deploy/images/corstone1000-fvp/corstone1000-image-corstone1000-fvp.fvpconf -- -C "board.msd_mmc.p_mmc_file=${<path-to-img>/ir_acs_live_image.img}" Running the FPGA with the IR prebuilt image -============================================== +=========================================== Insert the prepared USB stick then Power cycle the MPS3 board. Executing capsule update for FVP and FPGA -============================================== +========================================= Reach u-boot then interrupt the boot to reach the EFI shell. @@ -687,14 +766,14 @@ Then, reboot manually: Shell> reset FPGA: Select Corstone-1000 Linux kernel boot -============================================== +============================================ Remove the USB stick before u-boot is reached so the Corstone-1000 kernel will be detected and used for booting. **NOTE:** Otherwise, the execution ends up in the ACS live image. FVP: Select Corstone-1000 Linux kernel boot -============================================== +=========================================== Interrupt the u-boot shell. @@ -708,15 +787,14 @@ Run the following commands in order to run the Corstone-1000 Linux kernel and be :: - $ run retrieve_kernel_load_addr $ unzip $kernel_addr 0x90000000 $ loadm 0x90000000 $kernel_addr_r 0xf00000 $ bootefi $kernel_addr_r $fdtcontroladdr -*********************** +********************* Capsule update status -*********************** +********************* Positive scenario ================= @@ -733,7 +811,8 @@ correctly. SysTick_Handler: counted = 30, expiring on = 360 ... metadata_write: success: active = 1, previous = 0 - accept_full_capsule: exit: fwu state is changed to regular + flash_full_capsule: exit + corstone1000_fwu_flash_image: exit: ret = 0 ... @@ -775,15 +854,19 @@ see appropriate logs in the secure enclave terminal. ... uefi_capsule_retrieve_images: image 0 at 0xa0000070, size=15654928 uefi_capsule_retrieve_images: exit - flash_full_capsule: enter: image = 0x0xa0000070, size = 15654928, version = 10 + flash_full_capsule: enter: image = 0x0xa0000070, size = 7764541, version = 5 ERROR: flash_full_capsule: version error private_metadata_write: enter: boot_index = 1 private_metadata_write: success fmp_set_image_info:133 Enter FMP image update: image id = 0 - FMP image update: status = 1version=11 last_attempt_version=10. + FMP image update: status = 1version=6 last_attempt_version=5. fmp_set_image_info:157 Exit. corstone1000_fwu_flash_image: exit: ret = -1 + fmp_get_image_info:232 Enter + pack_image_info:207 ImageInfo size = 105, ImageName size = 34, ImageVersionName + size = 36 + fmp_get_image_info:236 Exit ... @@ -825,54 +908,96 @@ In the Linux command-line run the following: lowest_supported_fw_ver: 0 Linux distros tests ----------------------------------- +------------------- -*************************************************************************************** -Debian/OpenSUSE install and boot (applicable to FPGA only) -*************************************************************************************** +************************************************************* +Debian install and boot preparation (applicable to FPGA only) +************************************************************* + +There is a known issue in the `Shim 15.7 <https://salsa.debian.org/efi-team/shim/-/tree/upstream/15.7?ref_type=tags>`__ +provided with the Debian installer image (see below). This bug causes a fatal +error when attempting to boot media installer for Debian, and it resets the MPS3 before installation starts. +A patch to be applied to the Corstone-1000 stack (only applicable when +installing Debian) is provided to +`Skip the Shim <https://gitlab.arm.com/arm-reference-solutions/systemready-patch/-/blob/CORSTONE1000-2023.06/embedded-a/corstone1000/shim/0001-arm-bsp-u-boot-corstone1000-Skip-the-shim-by-booting.patch>`__. +This patch makes U-Boot automatically bypass the Shim and run grub and allows +the user to proceed with a normal installation. If at the moment of reading this +document the problem is solved in the Shim, the user is encouraged to try the +corresponding new installer image. Otherwise, please apply the patch as +indicated by the instructions listed below. These instructions assume that the +user has already built the stack by following the build steps of this +documentation. -To test Linux distro install and boot, the user should prepare two empty USB sticks (minimum size should be 4GB and formatted with FAT32). +:: + + cd <_workspace> + git clone https://git.gitlab.arm.com/arm-reference-solutions/systemready-patch.git -b CORSTONE1000-2023.06 + cp -f systemready-patch/embedded-a/corstone1000/shim/0001-arm-bsp-u-boot-corstone1000-Skip-the-shim-by-booting.patch meta-arm + cd meta-arm + git am 0001-arm-bsp-u-boot-corstone1000-Skip-the-shim-by-booting.patch + cd .. + kas shell meta-arm/kas/corstone1000-mps3.yml -c="bitbake u-boot trusted-firmware-a corstone1000-image -c cleansstate; bitbake corstone1000-image" + +Please update the cs1000.bin on the SD card with the newly generated wic file. + +************************************************* +Debian/openSUSE install (applicable to FPGA only) +************************************************* + +To test Linux distro install and boot, the user should prepare two empty USB +sticks (minimum size should be 4GB and formatted with FAT32). 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-Snapshot<date>-Media.iso + - `Debian 12.0.0 installer image <https://cdimage.debian.org/debian-cd/current/arm64/iso-dvd/debian-12.0.0-arm64-DVD-1.iso>`__ + - `OpenSUSE Tumbleweed installer image <http://download.opensuse.org/ports/aarch64/tumbleweed/iso/>`__ -Once the .iso file is downloaded, the .iso file needs to be flashed to your USB drive. +**NOTE:** For OpenSUSE Tumbleweed, the user should look for a DVD Snapshot like +openSUSE-Tumbleweed-DVD-aarch64-Snapshot<date>-Media.iso -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: +Once the iso file is downloaded, the iso file needs to be flashed to your USB +drive. This can be done with your development machine. + +In the example given below, we assume the USB device is ``/dev/sdb`` (the user +should use the `lsblk` command to confirm). + +**NOTE:** Please don't confuse your host PC's own hard drive with the USB drive. +Then, copy the contents of the iso file into the first USB stick by running the +following command in the development machine: :: 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: +Unplug the first USB stick from the development machine and connect it to the +MSP3 board. At this moment, only the first USB stick should be connected. Open +the following picocom sessions in your development machine: :: sudo picocom -b 115200 /dev/ttyUSB0 # in one terminal sudo picocom -b 115200 /dev/ttyUSB2 # in another terminal. -Now plug in the second USB stick (once installation screen is visible), the distro installation process will start. The installation prompt can be seen in ttyUSB2. If installer does not start, please try to reboot the board with both USB sticks connected and repeat the process. +When the installation screen is visible in ttyUSB2, plug in the second USB stick +in the MPS3 and start the distro installation process. If the installer does not +start, please try to reboot the board with both USB sticks connected and repeat +the process. **NOTE:** Due to the performance limitation of Corstone-1000 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 install clarifications (applicable to FPGA only) +******************************************************* - debian login: +As the installation process for Debian is different than the one for openSUSE, +Debian may need some extra steps, that are indicated below: -Login with the username root. +During Debian installation, please answer the following question: + - "Force GRUB installation to the EFI removable media path?" Yes + - "Update NVRAM variables to automatically boot into Debian?" No -**NOTE:** The Debian installer has a known issue "Install the GRUB bootloader - unable to install " and these are the steps to -follow on the subsequent popups to solve the issue during the installation: +If the grub installation fails, these are the steps to follow on the subsequent +popups: 1. Select "Continue", then "Continue" again on the next popup 2. Scroll down and select "Execute a shell" @@ -898,19 +1023,59 @@ follow on the subsequent popups to solve the issue during the installation: 7. Select "Continue without boot loader", then select "Continue" on the next popup 8. At this stage, the installation should proceed as normal. -*************************************************************************************** +***************************************************************** +Debian/openSUSE boot after installation (applicable to FPGA only) +***************************************************************** + +Once the installation is complete, unplug the first USB stick and reboot the +board. +The board will then enter recovery mode, from which the user can access a shell +after entering the password for the root user. Proceed to edit the following +files accordingly: + +:: + + vi /etc/systemd/system.conf + DefaultDeviceTimeoutSec=infinity + +The file to be editted next is different depending on the installed distro: + +:: + + vi /etc/login.defs # Only applicable to Debian + vi /usr/etc/login.defs # Only applicable to openSUSE + LOGIN_TIMEOUT 180 + +To make sure the changes are applied, please run: + +:: + + systemctl daemon-reload + +After applying the previous commands, please reboot the board. The user should +see a login prompt after booting, for example, for debian: + +:: + + debian login: + +Login with the username root and its corresponding password (already set at +installation time). + +************************************************************ OpenSUSE Raw image install and boot (applicable to FVP only) -*************************************************************************************** +************************************************************ -Steps to download openSUSE Tumbleweed raw image: - - Go to: http://download.opensuse.org/ports/aarch64/tumbleweed/appliances/ - - The user should look for a Tumbleweed-ARM-JeOS-efi.aarch64-* Snapshot, for example, ``openSUSE-Tumbleweed-ARM-JeOS-efi.aarch64-<date>-Snapshot<date>.raw.xz`` +Steps to download OpenSUSE Tumbleweed raw image: + - Under `OpenSUSE Tumbleweed appliances <http://download.opensuse.org/ports/aarch64/tumbleweed/appliances/>`__ + - The user should look for a Tumbleweed-ARM-JeOS-efi.aarch64-* Snapshot, for example, + ``openSUSE-Tumbleweed-ARM-JeOS-efi.aarch64-<date>-Snapshot<date>.raw.xz`` Once the .raw.xz file is downloaded, the raw image file needs to be extracted: :: - unxz <file-name.raw.xz> + unxz <file-name.raw.xz> The above command will generate a file ending with extension .raw image. Now, use the following command @@ -918,23 +1083,23 @@ to run FVP with raw image installation process. :: -<_workspace>/meta-arm/scripts/runfvp --terminals=xterm <_workspace>/build/tmp/deploy/images/corstone1000-fvp/corstone1000-image-corstone1000-fvp.fvpconf -- -C board.msd_mmc.p_mmc_file="${openSUSE raw image file path}" + <_workspace>/meta-arm/scripts/runfvp --terminals=xterm <_workspace>/build/tmp/deploy/images/corstone1000-fvp/corstone1000-image-corstone1000-fvp.fvpconf -- -C board.msd_mmc.p_mmc_file="${openSUSE raw image file path}" After successfully installing and booting the Linux distro, the user should see a openSUSE login prompt. :: - localhost login: + localhost login: Login with the username 'root' and password 'linux'. PSA API tests ----------------------- +------------- -*************************************************************************************** +*********************************************************** Run PSA API test commands (applicable to both FPGA and FVP) -*************************************************************************************** +*********************************************************** When running PSA API test commands (aka PSA Arch Tests) on MPS3 FPGA, the user should make sure there is no USB stick connected to the board. Power on the board and boot the board to @@ -948,7 +1113,7 @@ First, load FF-A TEE kernel module: :: - insmod /lib/modules/5.19.14-yocto-standard/extra/arm-ffa-tee.ko + insmod /lib/modules/6.1.32-yocto-standard/extra/arm-ffa-tee.ko Then, check whether the FF-A TEE driver is loaded correctly by using the following command: @@ -960,7 +1125,7 @@ The output should be: :: - arm_ffa_tee 16384 - - Live 0xffffffc0004f0000 (O) + arm_ffa_tee 16384 - - Live 0xffffffc000510000 (O) Now, run the PSA API tests in the following order: @@ -971,15 +1136,17 @@ Now, run the PSA API tests in the following order: psa-its-api-test psa-ps-api-test +**NOTE:** The psa-crypto-api-test takes between 30 minutes to 1 hour to run. + External System tests ------------------------------------ +--------------------- -*************************************************************************************** +************************************************************** Running the External System test command (systems-comms-tests) -*************************************************************************************** +************************************************************** Test 1: Releasing the External System out of reset -=================================================== +================================================== Run this command in the Linux command-line: @@ -1004,7 +1171,7 @@ The output on the External System terminal should be: MHUv2 module 'MHU1_SE' started Test 2: Communication -============================================= +===================== Test 2 releases the External System out of reset if not already done. Then, it performs communication between host and External System. @@ -1014,7 +1181,7 @@ After running Test 1, run this command in the Linux command-line: systems-comms-tests 2 -Additional output on the External System terminal will be printed: +Additional output on the External System terminal will be printed: :: @@ -1058,13 +1225,13 @@ The output on the Host terminal should be: Tests results ------------------------------------ +------------- -As a reference for the end user, reports for various tests for `Corstone-1000 software (CORSTONE1000-2022.11.23) <https://git.yoctoproject.org/meta-arm/tag/?h=CORSTONE1000-2022.11.23>`__ -can be found in `here <https://gitlab.arm.com/arm-reference-solutions/arm-reference-solutions-test-report/-/tree/master/embedded-a/corstone1000>`__. +As a reference for the end user, reports for various tests for `Corstone-1000 software (CORSTONE1000-2023.06) <https://git.yoctoproject.org/meta-arm/tag/?h=CORSTONE1000-2023.06>`__ +can be found `here <https://gitlab.arm.com/arm-reference-solutions/arm-reference-solutions-test-report/-/tree/master/embedded-a/corstone1000>`__. Running the software on FVP on Windows ---------------------------------------------------------------- +-------------------------------------- If the user needs to run the Corstone-1000 software on FVP on Windows. The user should follow the build instructions in this document to build on Linux host @@ -1073,6 +1240,7 @@ and launch the FVP binary. -------------- -*Copyright (c) 2022, Arm Limited. All rights reserved.* +*Copyright (c) 2022-2023, Arm Limited. All rights reserved.* .. _Arm Ecosystem FVPs: https://developer.arm.com/tools-and-software/open-source-software/arm-platforms-software/arm-ecosystem-fvps +.. _U-Boot repo: https://github.com/u-boot/u-boot.git |