diff --git a/meta-arm-bsp/documentation/corstone1000-a320/.readthedocs.yaml b/meta-arm-bsp/documentation/corstone1000-a320/.readthedocs.yaml new file mode 100644 index 00000000..b83cc80f --- /dev/null +++ b/meta-arm-bsp/documentation/corstone1000-a320/.readthedocs.yaml @@ -0,0 +1,12 @@ +version: 2 +build: + os: "ubuntu-22.04" + tools: + python: "3.9" +sphinx: + configuration: meta-arm-bsp/documentation/corstone1000-a320/conf.py +formats: + - pdf +python: + install: + - requirements: meta-arm-bsp/documentation/requirements.txt diff --git a/meta-arm-bsp/documentation/corstone1000-a320/conf.py b/meta-arm-bsp/documentation/corstone1000-a320/conf.py new file mode 100644 index 00000000..9216e8c7 --- /dev/null +++ b/meta-arm-bsp/documentation/corstone1000-a320/conf.py @@ -0,0 +1,117 @@ +# SPDX-FileCopyrightText: Copyright 2026 Arm Limited and/or its +# affiliates +# +# SPDX-License-Identifier: MIT + +# Configuration file for the Sphinx documentation builder. +# +# This file only contains a selection of the most common options. For a full +# list see the documentation: +# https://www.sphinx-doc.org/en/master/usage/configuration.html + +# -- Path setup -------------------------------------------------------------- + +# If extensions (or modules to document with autodoc) are in another directory, +# add these directories to sys.path here. If the directory is relative to the +# documentation root, use os.path.abspath to make it absolute, like shown here. +# +# sys.path.insert(0, os.path.abspath('.')) + +import os +import re +import sys + +import yaml + +# Append the documentation directory to the path, so we can import variables +sys.path.append(os.path.dirname(__file__)) + +_metadata_path = os.path.join(os.path.dirname(__file__), 'corstone-a320_metadata.yaml') +with open(_metadata_path, encoding='utf-8') as metadata_file: + _metadata = yaml.safe_load(metadata_file) or {} + +_metadata_variables = { + item['name']: item['value'] + for item in _metadata.get('variables', []) + if item.get('name') and item.get('value') +} + + +# -- Project information ----------------------------------------------------- + +project = 'Corstone-1000 Armv9-A Edge-AI' +copyright = '2026, Arm Limited' +author = 'Arm Limited' + + +# -- General configuration --------------------------------------------------- + +# Add any Sphinx extension module names here, as strings. They can be +# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom +# ones. +extensions = [ + 'myst_parser', + 'sphinx_rtd_theme', +] + +source_suffix = { + '.rst': 'restructuredtext', + '.md': 'markdown', +} + +myst_enable_extensions = [ + 'colon_fence', +] + +# Add any paths that contain templates here, relative to this directory. +templates_path = ['_templates'] + +# List of patterns, relative to source directory, that match files and +# directories to ignore when looking for source files. +# This pattern also affects html_static_path and html_extra_path. +exclude_patterns = [ + '_build', + 'Thumbs.db', + '.DS_Store', + 'docs/infra', + 'corstone-a320_map.md', + 'corstone-a320_metadata.yaml', +] + + +# -- Options for HTML output ------------------------------------------------- + +# The theme to use for HTML and HTML Help pages. See the documentation for +# a list of builtin themes. +# +html_theme = 'sphinx_rtd_theme' +html_theme_options = { + 'flyout_display': 'attached', +} + +# Define the canonical URL if you are using a custom domain on Read the Docs +html_baseurl = os.environ.get("READTHEDOCS_CANONICAL_URL", "") + +# Tell Jinja2 templates the build is running on Read the Docs +if os.environ.get("READTHEDOCS", "") == "True": + if "html_context" not in globals(): + html_context = {} + html_context["READTHEDOCS"] = True + + +# Add any paths that contain custom static files (such as style sheets) here, +# relative to this directory. They are copied after the builtin static files, +# so a file named "default.css" will overwrite the builtin "default.css". +#html_static_path = ['_static'] + + +def _replace_metadata_variables(app, docname, source): + source[0] = re.sub( + r'\$([A-Za-z0-9_]+)', + lambda match: _metadata_variables.get(match.group(1), match.group(0)), + source[0], + ) + + +def setup(app): + app.connect('source-read', _replace_metadata_variables) diff --git a/meta-arm-bsp/documentation/corstone1000-a320/corstone-a320_map.md b/meta-arm-bsp/documentation/corstone1000-a320/corstone-a320_map.md new file mode 100644 index 00000000..76b3f26c --- /dev/null +++ b/meta-arm-bsp/documentation/corstone1000-a320/corstone-a320_map.md @@ -0,0 +1,6 @@ +- topics/introducing.md +- topics/software-architecture.md +- topics/user-guide.md +- topics/tests.md +- topics/release-notes.md +- topics/change-log.md diff --git a/meta-arm-bsp/documentation/corstone1000-a320/corstone-a320_metadata.yaml b/meta-arm-bsp/documentation/corstone1000-a320/corstone-a320_metadata.yaml new file mode 100644 index 00000000..718232f7 --- /dev/null +++ b/meta-arm-bsp/documentation/corstone1000-a320/corstone-a320_metadata.yaml @@ -0,0 +1,106 @@ +--- +title: Corstone-1000 Armv9-A Edge-AI +subtitle: "" +abstract: Arm Corstone-1000 with Cortex-A320 is a reference solution for IoT devices. It is part of Total Solution for IoT which consists of hardware and software reference implementation. +author: Arm +status: REL +keywords: [IoT, software] +bookpartno: 112000 +product: Corstone-1000 with Cortex-A320 +product_type: Open Source Projects +product_revision: + - prefix: Version + version: "0101" + version_label: "2026.02" +output_type: "software" +conformance_notice: "true" +content_type: User Guide +audience: + - Software Developers +categories: + - IoT +themes: + - IoT +intended_audience: Software Developers +terminology_review: new +releases: + - revision: 0100-01 + date: 2026-05-01 + change_summary: Update + permissions: nonconfidential + +variables: +- name: arm_developer_cs1000_website + value: 'https://developer.arm.com/Tools%20and%20Software/Corstone-1000%20Software' +- name: arm_developer_cs1000_search + value: 'https://developer.arm.com/search#q=corstone-1000' +- name: arm_developer_mhu_website + value: 'https://developer.arm.com/documentation/ka005129/latest/#:~:text=An%20MHU%20is%20a%20device,that%20a%20message%20is%20available' +- name: arm_developer_secureboot_website + value: 'https://developer.arm.com/documentation/PRD29-GENC-009492/c/TrustZone-Software-Architecture/Booting-a-secure-system/Secure-boot' +- name: arm_architecture_security_features_platform_security + value: 'https://www.arm.com/architecture/security-features/platform-security' +- name: linux_repository + value: 'https://git.kernel.org/pub/scm/linux/kernel/git/stable/linux.git/' +- name: arm_trustzone_for_cortex_a_website + value: 'https://www.arm.com/technologies/trustzone-for-cortex-a' +- name: arm_fmw_framework_a_profile_pdf + value: 'https://developer.arm.com/documentation/den0077/latest' +- name: arm_fmw_framework_m_profile_pdf + value: 'https://developer.arm.com/architectures/Firmware%20Framework%20for%20M-Profile' +- name: platform_security_fwu_for_a_profile_pdf + value: 'https://developer.arm.com/documentation/den0118/a/' +- name: psa_firmware_update_ihi_0093_api_reference_website + value: 'https://arm-software.github.io/psa-api/fwu/1.0/api/api.html' +- name: edk2_capsule_generation_tool_repository + value: 'https://github.com/tianocore/edk2/blob/master/BaseTools/Source/Python/Capsule/GenerateCapsule.py' +- name: psa_fwu_den0018_specification_website + value: 'https://developer.arm.com/documentation/den0118/latest/' +- name: ts_psa_fwu_service_website + value: 'https://trusted-services.readthedocs.io/en/stable/services/fwu/psa-fwu-m.html' +- name: tfm_shim_layer_website + value: 'https://trustedfirmware-m.readthedocs.io/en/latest/design_docs/services/tfm_fwu_service.html#shim-layer-between-fwu-and-bootloader' +- name: op_tee_os_repository + value: 'https://github.com/OP-TEE/optee_os' +- name: psa_certified_website + value: 'https://www.psacertified.org/' +- name: psa_l2_ready + value: 'https://www.psacertified.org/products/corstone-1000/' +- name: systemready_ir_certification + value: 'https://armkeil.blob.core.windows.net/developer/Files/pdf/certificate-list/arm-systemready-ve-arm-neoverse.pdf' +- name: trusted_board_boot_requirements_client_pdf + value: 'https://developer.arm.com/documentation/den0006/latest' +- name: trusted_firmware_m_website + value: 'https://www.trustedfirmware.org/projects/tf-m/' +- name: trusted_firmware_m_bl1_website + value: 'https://trustedfirmware-m.readthedocs.io/en/latest/design_docs/booting/bl1.html' +- name: trusted_firmware_a_bl2_website + value: 'https://developer.arm.com/documentation/108028/0000/RD-TC22-software/Software-components/AP-firmware/Trusted-firmware-A-BL2' +- name: trusted_firmware_a_fip_guide + value: 'https://trustedfirmware-a.readthedocs.io/en/latest/design/firmware-design.html#firmware-image-package-fip' +- name: trusted_services_website + value: 'https://www.trustedfirmware.org/projects/trusted-services/' +- name: trusted_services_uefi_smm_website + value: 'https://trusted-services.readthedocs.io/en/integration/services/uefi-smm-services.html#' +- name: das_u_boot_repository + value: 'https://github.com/u-boot/u-boot.git' +- name: keil_rtx5_website + value: 'https://developer.arm.com/Tools%20and%20Software/Keil%20MDK/RTX5%20RTOS' +- name: ppa_website + value: 'https://developer.arm.com/documentation/102738/0100/Power--performance--and-area-analysis' +- name: mcuboot_website + value: 'https://docs.mcuboot.com/' +- name: arm_developer_fvp + value: 'https://developer.arm.com/tools-and-software/open-source-software/arm-platforms-software/arm-ecosystem-fvps' +- name: secure_debug_manager_repo_readme + value: 'https://github.com/ARM-software/secure-debug-manager/tree/master?tab=readme-ov-file#secure-debug-manager-psa-adac--sdc-600' +- name: secure_debug_manager_armds_integration + value: 'https://github.com/ARM-software/secure-debug-manager?tab=readme-ov-file#arm-development-studio-integration' +- name: meta_arm_repository_release_branch + value: 'https://docs.yoctoproject.org/next/migration-guides/migration-5.3.html' +- name: arm_ulink_pro_website + value: 'https://www.arm.com/products/development-tools/debug-probes/ulink-pro' +- name: arm_ds_website + value: 'https://www.arm.com/products/development-tools/embedded-and-software/arm-development-studio' +- name: edk2_repository + value: 'https://github.com/tianocore/edk2' diff --git a/meta-arm-bsp/documentation/corstone1000-a320/images/CorstoneA320Subsystems.png b/meta-arm-bsp/documentation/corstone1000-a320/images/CorstoneA320Subsystems.png new file mode 100644 index 00000000..d3022a16 Binary files /dev/null and b/meta-arm-bsp/documentation/corstone1000-a320/images/CorstoneA320Subsystems.png differ diff --git a/meta-arm-bsp/documentation/corstone1000-a320/images/CorstoneSubsystems.png b/meta-arm-bsp/documentation/corstone1000-a320/images/CorstoneSubsystems.png new file mode 100644 index 00000000..4c6a2a8c Binary files /dev/null and b/meta-arm-bsp/documentation/corstone1000-a320/images/CorstoneSubsystems.png differ diff --git a/meta-arm-bsp/documentation/corstone1000-a320/images/ExternalFlash.png b/meta-arm-bsp/documentation/corstone1000-a320/images/ExternalFlash.png new file mode 100644 index 00000000..2be20178 Binary files /dev/null and b/meta-arm-bsp/documentation/corstone1000-a320/images/ExternalFlash.png differ diff --git a/meta-arm-bsp/documentation/corstone1000-a320/images/FIPDiagram.png b/meta-arm-bsp/documentation/corstone1000-a320/images/FIPDiagram.png new file mode 100644 index 00000000..bfe7315e Binary files /dev/null and b/meta-arm-bsp/documentation/corstone1000-a320/images/FIPDiagram.png differ diff --git a/meta-arm-bsp/documentation/corstone1000-a320/images/SecureBootChain.png b/meta-arm-bsp/documentation/corstone1000-a320/images/SecureBootChain.png new file mode 100644 index 00000000..5ed2a285 Binary files /dev/null and b/meta-arm-bsp/documentation/corstone1000-a320/images/SecureBootChain.png differ diff --git a/meta-arm-bsp/documentation/corstone1000-a320/images/SecureFirmwareUpdate.png b/meta-arm-bsp/documentation/corstone1000-a320/images/SecureFirmwareUpdate.png new file mode 100644 index 00000000..5fdae9db Binary files /dev/null and b/meta-arm-bsp/documentation/corstone1000-a320/images/SecureFirmwareUpdate.png differ diff --git a/meta-arm-bsp/documentation/corstone1000-a320/images/SecureServices.png b/meta-arm-bsp/documentation/corstone1000-a320/images/SecureServices.png new file mode 100644 index 00000000..ff7a2703 Binary files /dev/null and b/meta-arm-bsp/documentation/corstone1000-a320/images/SecureServices.png differ diff --git a/meta-arm-bsp/documentation/corstone1000-a320/images/SystemArchitecturePSAFirmwareUpdate.png b/meta-arm-bsp/documentation/corstone1000-a320/images/SystemArchitecturePSAFirmwareUpdate.png new file mode 100644 index 00000000..75cee8be Binary files /dev/null and b/meta-arm-bsp/documentation/corstone1000-a320/images/SystemArchitecturePSAFirmwareUpdate.png differ diff --git a/meta-arm-bsp/documentation/corstone1000-a320/images/UEFISupport.png b/meta-arm-bsp/documentation/corstone1000-a320/images/UEFISupport.png new file mode 100644 index 00000000..a501de55 Binary files /dev/null and b/meta-arm-bsp/documentation/corstone1000-a320/images/UEFISupport.png differ diff --git a/meta-arm-bsp/documentation/corstone1000-a320/index.md b/meta-arm-bsp/documentation/corstone1000-a320/index.md new file mode 100644 index 00000000..da7fd90a --- /dev/null +++ b/meta-arm-bsp/documentation/corstone1000-a320/index.md @@ -0,0 +1,12 @@ +# Corstone-1000 Armv9-A Edge-AI + +```{toctree} +:maxdepth: 2 + +topics/introducing +topics/software-architecture +topics/user-guide +topics/tests +topics/release-notes +topics/change-log +``` diff --git a/meta-arm-bsp/documentation/corstone1000-a320/topics/change-log.md b/meta-arm-bsp/documentation/corstone1000-a320/topics/change-log.md new file mode 100644 index 00000000..e891fd5c --- /dev/null +++ b/meta-arm-bsp/documentation/corstone1000-a320/topics/change-log.md @@ -0,0 +1,80 @@ +# Change log {.chapter permissions=non-confidential} + +This document contains a summary of the new features, changes and fixes in each release of the Corstone-1000 with Cortex-A320 software stack. + +## Version 2025.12 {.reference} + +The following changes are present in this release: + +- Delivered end-to-end Cortex-A320 enablement across U-Boot, TF-A, TF-M, OP-TEE, Yocto machine layers, and documentation, including device-tree updates, MPIDR handling, and FVP model renaming. +- Rolled out the PSA Firmware Update (DEN0118) pipeline: U-Boot capsule parsing, Bootloader Abstraction Layer in TF-M, ESRT exposure, and Trusted Services IPC bridges replacing legacy capsule code. +- Hardened the new firmware update flow with EFI self-tests, metadata restructuring for partial and multi-image acceptance, and RSE-COMMS gating refinements. +- Upgraded key firmware components (TF-A 2.13.0, TF-M 2.2.1, Trusted Services 1.2.0, OP-TEE OS 4.7.0) and introduced targeted test skips plus integer-only build modes to keep validation green. +- Cleaned and renumbered downstream patch series across Trusted Services and TF-M while removing obsolete integrations to align with upstream baselines. +- Refreshed release material and architecture guides to describe the A320 profile, PSA FWU behavior, and updated software stack. +- Added KAS profiles, machine includes, and automated FVP selection logic to streamline developer workflows for the refreshed platform configuration. + +### Corstone-1000 with Cortex-A320 components versions {.reference} + +The following component versions are available: + +Table: Corstone-1000 with Cortex-A320 component versions + ++----------------------------------------+-----------------------------------+ +| Component | Version | ++========================================+===================================+ +| linux-yocto | 6.12.60 | ++----------------------------------------+-----------------------------------+ +| u-boot | 2025.04 | ++----------------------------------------+-----------------------------------+ +| optee-client | 4.7.0 | ++----------------------------------------+-----------------------------------+ +| optee-os | 4.7.0 | ++----------------------------------------+-----------------------------------+ +| trusted-firmware-a | 2.13.0 | ++----------------------------------------+-----------------------------------+ +| trusted-firmware-m | 2.2.1 | ++----------------------------------------+-----------------------------------+ +| libts | v1.2.0 | ++----------------------------------------+-----------------------------------+ +| ts-sp-{se-proxy, smm-gateway} | v1.2.0 | ++----------------------------------------+-----------------------------------+ +| ts-psa-{crypto, iat, its. ps}-api-test | 74dc6646ff | ++----------------------------------------+-----------------------------------+ + +### Yocto distribution components versions {.reference} + +The following Yocto distribution components versions are available: + + +Table: Yocto distribution component versions + ++-------------------+------------+ +| Component | Version | ++===================+============+ +| meta-arm | whinlatter | ++-------------------+------------+ +| bitbake | 0dde1a3ff8 | ++-------------------+------------+ +| meta-openembedded | fc0152e434 | ++-------------------+------------+ +| openembedded-core | 4bd920ad7d | ++-------------------+------------+ +| meta-yocto | b3b6592635 | ++-------------------+------------+ +| meta-secure-core | 63209fb150 | ++-------------------+------------+ +| meta-ethos | aa2504a32f | ++-------------------+------------+ +| meta-sca | e68f1a9d17 | ++-------------------+------------+ +| busybox | 1.37.0 | ++-------------------+------------+ +| musl | 1.2.5 | ++-------------------+------------+ +| gcc-arm-none-eabi | 13.3.rel1 | ++-------------------+------------+ +| gcc-cross-aarch64 | 15.2.0 | ++-------------------+------------+ +| openssl | 3.5.4 | ++-------------------+------------+ diff --git a/meta-arm-bsp/documentation/corstone1000-a320/topics/introducing.md b/meta-arm-bsp/documentation/corstone1000-a320/topics/introducing.md new file mode 100644 index 00000000..3bba6104 --- /dev/null +++ b/meta-arm-bsp/documentation/corstone1000-a320/topics/introducing.md @@ -0,0 +1,14 @@ +# Introduction {.chapter permissions=non-confidential} + +Arm Corstone-1000 with Cortex-A320 is a reference solution for IoT devices +based on Arm Corstone-1000, but with Cortex-A320 CPU, Ethos-U85 NPU and +GIC700 (Generic Interrupt Controller). It is part of Total Solution +for IoT which consists of hardware and software reference implementations. + +## Disclaimer {.reference} + +Arm reference solutions are Arm public example software projects that track and +pull upstream components, incorporating their respective security fixes +published over time. Arm partners are responsible for ensuring that the +components they use contain all the required security fixes, if and when they +deploy a product derived from Arm reference solutions. diff --git a/meta-arm-bsp/documentation/corstone1000-a320/topics/release-notes.md b/meta-arm-bsp/documentation/corstone1000-a320/topics/release-notes.md new file mode 100644 index 00000000..7eadc1b2 --- /dev/null +++ b/meta-arm-bsp/documentation/corstone1000-a320/topics/release-notes.md @@ -0,0 +1,28 @@ +# Release notes {.chapter permissions=non-confidential} + +You expressly assume all liabilities and risks relating to your use or operation +of your software and hardware designed or modified using the Arm Tools, +including without limitation, your software or hardware designed or +intended for safety-critical applications. Should your software or hardware +prove defective, you assume the entire cost of all necessary servicing, repair +or correction. + +## Release notes - 2025.12 {.reference} + +The following knowns issues and limitations are present in this release: + +- Corstone-1000 with Cortex-A320 FVP does not currently support Symmetric Multiprocessing +- Corstone-1000 with Cortex-A320 FVP becomes unresponsive when the Linux kernel driver for the Ethos-U85 NPU loads automatically after a software reboot. +- Crypto isolation is not supported in the Secure world of Corstone-1000. Additionally, clients in + the Normal world are not isolated from one another. Therefore, if an end user wants to add a new + Secure Partition (SP) (such as a software TPM) that accesses the Crypto service via the SE-Proxy, + they are responsible for implementing their own isolation mechanisms to ensure proper security boundaries. +- DSTREAM debug probe may experience unreliable USB connectivity when used with Arm DS for secure debug. + This issue is under active investigation, and we are working to identify and resolve compatibility issues in a future update. + As a more stable alternative, the ULINKpro debug probe is recommended for use with Corstone-1000 in secure debug scenarios. + +## Support {.reference} + +For technical support, email [Arm subsystem support](mailto:support-subsystem-iot@arm.com). + +For security issues, contact [Arm Security](mailto:psirt@arm.com). diff --git a/meta-arm-bsp/documentation/corstone1000-a320/topics/software-architecture.md b/meta-arm-bsp/documentation/corstone1000-a320/topics/software-architecture.md new file mode 100644 index 00000000..72c18ade --- /dev/null +++ b/meta-arm-bsp/documentation/corstone1000-a320/topics/software-architecture.md @@ -0,0 +1,311 @@ +# Software architecture {.chapter permissions=non-confidential} + +The combination of Corstone-1000 software and hardware reference solution is [PSA Level-2 ready certified]($psa_l2_ready) as well as [Arm SystemReady Devicetree certified]($systemready_ir_certification). Please rely on the Corstone-1000 platform for certification needs. + +More information on the Corstone-1000 subsystems product(s), variants and design can be +found on [Arm Developer]($arm_developer_cs1000_website). + +This document explicitly focuses on the software part of the solution and +provides internal details on the software components. The reference +software package of the platform can be retrieved following instructions +present in the user guide document. + +## Design overview {.reference} + +This variant of the Corstone-1000 platform replaces the Host System's Cortex-A35 +processor with a Cortex-A320. In this configuration, the optional External System +(previously a Cortex-M3) is replaced by an Arm Ethos-U85 Neural Processing Unit (NPU). +The Ethos-U85 runs in the direct drive configuration, where the Host System is +responsible for managing the NPU directly. + +![Cortex-A320 subsystems](../images/CorstoneA320Subsystems.png) + +## Secure boot chain {.reference} + +For the security of a device, it is essential that only authorized +software should run on the device. + +The Corstone-1000 boot uses a [Secure boot]($arm_developer_secureboot_website) chain process +where an already authenticated image verifies and loads the following software in the chain. + +For the boot chain process to work, the start of the chain should be trusted, forming the +Root of Trust (RoT) of the device. The RoT of the device is immutable in +nature and encoded into the device by the device manufacturer before it +is deployed into the field. +In Corstone-1000, the content of the ROM and CC312 One Time Programmable (OTP) memory forms the RoT. + +Verification of an image can happen either by comparing the computed and stored hashes, or by +checking the signature of the image if the image is signed. + +![Secure boot chain](../images/SecureBootChain.png) + +It is a lengthy chain to boot the software on Corstone-1000. + +### TF-M BL1\_1 {.reference} + +On power-up, the Secure Enclave begins execution from TF-M BL1\_1, which resides in ROM and serves as +the Root of Trust (RoT) for the device. + +TF-M BL1\_1 is the immutable bootloader and is responsible for: + +- Provisioning the device during the first boot +- Performing hardware initialization +- Verifying the integrity and authenticity of the next stage in the boot chain + +At boot time, TF-M BL1\_1: + +- Copies the TF-M BL1\_2 image from OTP to RAM. +- Verifies the integrity of BL1\_2 by comparing its computed hash with the hash stored in OTP. + +### TF-M BL1\_2 {.reference} + +During provisioning, the TF-M BL1\_2 binary, along with its hashes and cryptographic keys, is stored +in One-Time Programmable (OTP) memory. + +Once verified, TF-M BL1\_2: + +- Takes control and verifies the next stage in the boot chain, which is TF-M BL2. +- Computes the hash of the BL2 image and compares it with the BL2 hash stored in OTP to ensure + integrity before transferring execution to BL2. + +The TF-M BL1 design details can be found in the [TF-M design documents]($trusted_firmware_m_bl1_website). + +:::note +Corstone-1000 has some differences compared to this design due to memory (OTP/ROM) limitations: + +- BL1\_1 code size is larger than needed because it handles most of the hardware initialization instead of the BL1\_2. +- BL1\_2 cannot be updated during provisioning time because the provisioning bundle that contains its code is located in the ROM. +- BL1\_2 does not use the post-quantum LMS verification. +- BL2 cannot be updated because it is verified by comparing the computed hash to the hash stored in the OTP. + +::: + +### TF-M BL2 {.reference} + +In this system, TF-M BL2 refers to MCUBoot. + +On the first boot, MCUBoot can provision additional cryptographic keys. It is responsible for authenticating both: + +- TF-M (Trusted Firmware-M), and +- The initial bootloader of the Host system, [Trusted Firmware-A (TF-A) BL2]($trusted_firmware_a_bl2_website) + +This authentication is done by verifying the digital signatures of the respective images. + +MCUBoot performs image verification in the following steps: + +1. Load the image from non-volatile memory into RAM. +2. Validate the image's signature using the corresponding public key. + +:::note +The public key present in the image header is validated by comparing with the hash. Depending on the image, the hash of the public key is either stored in the OTP or part of the software which is being already verified in the previous stages. +::: + +The execution control is passed to TF-M after the verification. +As the runtime executable of the Secure Enclave, TF-M initializes itself before +bringing the Host system out of reset. + +### Host system authentication {.reference} + +The Host system follows the boot standard defined in [Trusted Board Boot Requirements Client]($trusted_board_boot_requirements_client_pdf) +to authenticate the Secure and Non-secure software. + +The [Firmware Image Package (FIP)]($trusted_firmware_a_fip_guide) packs bootloader images and +other payloads into a single archive. + +![FIPDiagram](../images/FIPDiagram.png) + +The FIP for Corstone-1000 contains: + +- Trusted firmware-A BL2 +- AP EL3 Runtime firmware, BL31 image +- AP Secure Payload, BL32 image +- AP Normal world firmware -U-boot, BL33 image +- Trusted OS Firmware configuration file used by Trusted OS (BL32), TOS_FW_CONFIG +- Key certificates +- Content certificates + +To load and validate TF-A BL2, TF-M BL2 first parses the GUID Partition Table (GPT) +to locate the FIP. It then determines the offset of TF-A BL2 within the FIP. + +:::note +TF-M does not check the FIP signature, it only checks the TF-A BL2's signature in the FIP. +::: + +The implicitly trusted components are: + +- A SHA-256 hash of the Root of Trust Public Key (ROTPK.) For development purposes, a development ROTPK is used and its hash embedded into the TF-A BL2 image. This public key is provided by the TF-A source code. +- TF-A BL2 image - it can be trusted because it has been verified by TF-M BL2 before starting TF-A. + +The remaining components in the Chain of Trust (CoT) are either certificates or bootloader images. + +#### Bootloader authentication {.reference} + +The FIP contains two types of certificates: + +- Content Certificates used to store the hash of a bootloader image. +- Key Certificates used to verify public keys used to sign Content Certificates. + +The Host system bootloader images are authenticated by computing their hash and comparing it to the corresponding hash found in the Content Certificate. + +#### Certificates verification {.reference} + +The public keys defined in the Trusted Key Certificate are used to verify the later certificates in +the CoT process. The Trusted Key Certificate is verified with the Root of Trust Public Key. + +#### UEFI authenticated variables {.reference} + +For UEFI Secure Boot, authenticated variables can be accessed from the secure flash. +The feature has been integrated in U-Boot, which authenticates the images as per the UEFI +specification before executing them. + +## Secure services {.reference} + +Corstone-1000 is unique in offering a secure environment for running trusted workloads. +While the Host system includes TrustZone technology, the platform also features a hardware-isolated +Secure Enclave, specifically designed to execute these secure workloads. + +In Corstone-1000, essential Secure Services—such as Cryptography, Protected Storage, +Internal Trusted Storage, and Attestation—are provided through PSA Functional APIs implemented in TF-M. + +From the user's perspective, there is no difference when communicating with these services, +whether they run in the Secure Enclave or in the Secure world of the Host system. +The diagram below illustrates the data flow for such calls. + +![Secure services](../images/SecureServices.png) + +The Secure Enclave Proxy Secure Partition (SE Proxy SP) is a proxy managed by OP-TEE that forwards +Secure Service calls to the Secure Enclave. This communication uses the +[RSE communication protocol](https://tf-m-user-guide.trustedfirmware.org/platform/arm/rse/rse_comms.html). +While the protocol supports shared memory and MHU interrupts as a doorbell mechanism between cores, +in Corstone-1000, the entire message is currently transmitted through the MHU channels. +Corstone-1000 implements Isolation Level 2 using the Cortex-M0+ Memory Protection Unit (MPU). + +Users can define their own secure services to run either in the Host system's Secure World or in +the Secure Enclave. This choice involves a trade-off between latency and security. +Services running in the Secure Enclave benefit from strong, hardware-enforced isolation, +offering higher security but at the cost of increased latency. In contrast, services running in the +Host Secure World experience lower latency, but rely on TrustZone technology for virtualized isolation, +which offers comparatively less robust security. + +## PSA secure firmware update {.reference} + +The Corstone-1000 platform necessitates a robust, secure, and flexible firmware update mechanism +including partial capsule update to ensure fielded devices can receive critical patches, feature enhancements, +and security fixes without compromising system integrity. To meet these requirements, we have implemented the +Platform Security Architecture (PSA) Firmware Update (FWU) framework on Corstone-1000, leveraging Trusted Firmware-M (TF-M) +for the Secure Enclave, U-Boot as the host-side client on Cortex-A, and the UEFI capsule update mechanism for payload +encapsulation. This design supports the Fixed Virtual Platform (FVP) target, providing consistent behavior across +simulation-based deployments. The Corstone-1000 supports FWU +which complies with the +[Platform Security Firmware Update for the A-profile Arm Architecture]($platform_security_fwu_for_a_profile_pdf) +and [PSA Firmware Update IHI 0093]($psa_firmware_update_ihi_0093_api_reference_website) +specifications. + +To standardize and streamline capsule creation with multiple FMP payloads, the +[EDK2 capsule generation tool]($edk2_capsule_generation_tool_repository) +tool has been integrated into the meta-arm Yocto layer for Corstone-1000. This integration involves defining +build rules for generating UEFI capsules as part of the firmware image build process. Configuration parameters +exposed in the recipe allow developers to specify the number of FMP payloads, target image GUIDs, version numbers etc. +This capsule ensures that all update payloads conform to the UEFI FMP specification and are ready for +validation and delivery by U‑Boot. + +The FWU solution for Corstone-1000 is composed of three primary domains: + +- Host System +- Trusted Services intermediary +- Secure Enclave + +Each domain has distinct responsibilities and communicates through standardized interfaces. + +![System architecture PSA firmware update](../images/SystemArchitecturePSAFirmwareUpdate.png) + +On the host side, U-Boot functions as the FWU client and orchestrates the update process from capsule retrieval to +payload delivery based on [PSA FWU DEN0018 specification]($psa_fwu_den0018_specification_website) +via Arm FF-A framework. The Trusted-Services SE Proxy secure partition serves as a gateway between the non-secure host +environment and the Secure Enclave. The [PSA FWU service]($ts_psa_fwu_service_website) running in the Trusted Services +implementation forwards the data to the Secure Enclave via MHU-based PSA calls. Within the Secure Enclave, the PSA FWU +Agent, conforming to [PSA Firmware Update IHI 0093]($psa_firmware_update_ihi_0093_api_reference_website) specification, +orchestrates the actual flash programming, metadata management, and rollback protection mechanisms. The agent relies on a +bespoke [shim layer]($tfm_shim_layer_website) to abstract hardware‑specific flash operations and bootloader interactions. + +As defined in the specification, the external flash is divided into two banks: one bank holds the +currently running images, while the other is used to stage new images. + +There are four updatable components: **BL2**, **TF-M**, **the FIP** and **the Kernel Image** (the initramfs bundle). +New images are delivered and accepted in the form of UEFI capsules. + +![External flash](../images/ExternalFlash.png) + +When a FWU is initiated on Corstone-1000, the following sequence of operations takes place: + +1. Capsule Retrieval and Preparation + + U-Boot on the host system retrieves the firmware capsule. + It validates the capsule header and parses the FMP (Firmware Management Protocol) descriptor list to identify the payloads to be updated. + + For each FMP descriptor, U-Boot: + + Splits the firmware payload into 4 KiB chunks. + Invokes the PSA_FWU_Update API for each chunk, transmitting the buffer address via the FF-A (Firmware Framework for Arm) shared memory interface. + +2. Secure Transmission and Forwarding + + The PSA Firmware Update (FWU) service, running as part of Trusted Services, receives the chunks through Secure Partition Client (SPC) calls. + It forwards these chunks to the Secure Enclave using MHU-based PSA calls. + +3. Flashing Within the Secure Enclave + + Inside the Secure Enclave, the PSA FWU Agent dispatches each chunk to the shim layer. + + The shim layer: + + Erases the corresponding sectors in the non-active flash bank. + Writes the received firmware chunks at the correct offsets. + During partial updates, it also copies static partitions from the active bank to the non-active one to maintain consistency. + +4. Finalization and Boot Preparation + + After all chunks are successfully written: + + The shim updates the firmware manifest and the EFI System Resource Table (ESRT) entries to reflect the new image version. + This step enables the bootloader to recognize the new firmware for a trial boot. + The platform then performs an automatic reset, booting into the non-active bank in trial mode. + +5. Trial Boot and Confirmation + + In trial mode, U-Boot evaluates the new firmware and issues either an accept or reject command using the PSA FWU ABI. + These commands are sent to the Secure Enclave, instructing the shim to update the firmware metadata accordingly. + +6. Recovery and Fallback Mechanism + + If the trial boot is successful, the host sends an acknowledgment, transitioning the firmware state from 'trial' to 'regular'. + + If the system fails or becomes unresponsive: + + A watchdog timer triggers a system reset. + The BL1 firmware in the Secure Enclave detects repeated failures and reverts to the previously known-good flash bank. + This rollback mechanism ensures the device remains operational and recoverable, even after a failed update. + +![Secure firmware update](../images/SecureFirmwareUpdate.png) + +## UEFI runtime support in U-Boot {.reference} + +The implementation of UEFI boot-time and runtime APIs requires persistent variable storage. In +Corstone-1000, UEFI variables are stored using the Protected Storage (PS) service. + +The diagram below illustrates the data flow for storing UEFI variables. U-Boot's UEFI subsystem +communicates with the Secure World using the U-Boot FF-A driver, which interfaces with the +[UEFI System Management Mode (SMM) service]($trusted_services_uefi_smm_website). + +The SMM service provides support for the UEFI System Management Mode. This support is implemented by the SMM Gateway secure partition. +The SMM service then uses the Proxy Protected Storage (PS) provided by the SE Proxy SP. +These PS calls are forwarded to the Secure Enclave, following the communication path described earlier. + +![UEFI runtime support flow](../images/UEFISupport.png) + +## References {.reference} + +For more information, see: + +- [Arm Developer]($arm_developer_cs1000_search) +- [Arm Security Architectures]($arm_architecture_security_features_platform_security) diff --git a/meta-arm-bsp/documentation/corstone1000-a320/topics/tests.md b/meta-arm-bsp/documentation/corstone1000-a320/topics/tests.md new file mode 100644 index 00000000..b86d87ca --- /dev/null +++ b/meta-arm-bsp/documentation/corstone1000-a320/topics/tests.md @@ -0,0 +1,1194 @@ +# Tests {.chapter permissions=non-confidential} + +All the tests in this chapter assume you have already built the software stack at least once by following the build instructions in the Build, Flash and Run chapter. + +## Reports {.reference} + +Reports for the tests conducted on the [Corstone-1000 software (CORSTONE1000-2025.12)](https://git.yoctoproject.org/meta-arm/tag/?h=CORSTONE1000-2025.12) release are available for reference in the [GitLab repo](https://gitlab.arm.com/arm-reference-solutions/arm-reference-solutions-test-report/-/tree/CORSTONE1000-2025.12/embedded-a/corstone1000/CORSTONE1000-2025.12?ref_type=tags). + +## SystemReady IR {.reference} + +This section tells you how to run the Architecture Compliance Suite (ACS) tests. + +:::note +In this release, SystemReady IR has been renamed SystemReady Devicetree Band. +::: + +### Build an EFI system partition {.reference} + +A storage with EFI System Partition (ESP) must exist in the system for the UEFI-SCT related tests to pass. + +1. Build an ESP partition for your target + + ``` + kas build meta-arm/kas/corstone1000-fvp.yml:meta-arm/ci/debug.yml:meta-arm/kas/corstone1000-a320.yml --target corstone1000-esp-image + ``` + +2. Locate the `corstone1000-esp-image-corstone1000-fvp.wic` build artefact + in `${WORKSPACE}/build/tmp/deploy/images/corstone1000-fvp/` + +### Use the EFI system partition {.reference} + +The ESP disk image will automatically be used by the Corstone-1000 FVP as the 2nd MMC card image. +It will be used when the SystemReady-IR tests is performed on the FVP in the later section. + +### Run SystemReady IR ACS tests {.reference} + +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 (i.e. SBSA, SBBR, etc.). +Implementers can verify if these behaviors have been interpreted correctly. + +The following test suites and bootable applications are under the `BOOT` partition of the ACS image: + +- SCT +- FWTS +- BSA UEFI +- BSA linux +- GRUB +- UEFI manual capsule application + +See the directory structure of the ACS image `BOOT` partition below: + +``` + +├── acs_results +├── EFI +│ └── BOOT +│ ├── app +│ ├── bbr +│ ├── bootaa64.efi +│ ├── bsa +│ ├── debug +│ ├── grub.cfg +│ ├── Shell.efi +│ ├── sie_startup.nsh +│ └── startup.nsh +├── Image +├── security-interface-extension-keys +│ ├── NullPK.auth +│ ├── TestDB1.auth +│ ├── TestDB1.der +│ ├── TestDBX1.auth +│ ├── TestDBX1.der +│ ├── TestKEK1.auth +│ ├── TestKEK1.der +│ ├── TestPK1.auth +│ └── TestPK1.der +├── startup.nsh +└── yocto_image.flag +``` + +The `BOOT` partition is also used to store test results in the `acs_results` folder. + +:::note +Ensure that the `acs_results` folder is empty before starting the test. +::: + +To build and run ACS tests on Corstone-1000: + +1. On your host development machine, clone the [Arm SystemReady ACS repository](https://github.com/ARM-software/arm-systemready/). + + ``` + cd ${WORKSPACE} + git clone https://github.com/ARM-software/arm-systemready.git -b v23.09_SR_REL2.0.0_ES_REL1.3.0_IR_REL2.1.0 --depth 1 + ``` + + This repository contains the infrastructure to build the ACS and the bootable prebuilt images to be used for the + certifications of SystemReady IR. + +2. Find the pre-built ACS live image in `${WORKSPACE}/arm-systemready/IR/prebuilt_images/v23.09_2.1.0/ir-acs-live-image-generic-arm64.wic.xz`. + + :::note + This prebuilt ACS image includes v5.13 kernel, which does not provide USB driver support for Corstone-1000. + ::: + +3. Decompress the pre-built ACS live image. + + ``` + cd ${WORKSPACE}/arm-systemready/IR/prebuilt_images/v23.09_2.1.0 + unxz ir-acs-live-image-generic-arm64.wic.xz + ``` + +4. Run `tmux`: + + ``` + cd ${WORKSPACE} && tmux + ``` + +5. Run the commands below within `tmux` to run the ACS test on FVP using the built firmware image and the pre-built ACS image identified above: + + ``` + ./meta-arm/scripts/runfvp \ + --terminals=tmux \ + ./build/tmp/deploy/images/corstone1000-fvp/corstone1000-flash-firmware-image-corstone1000-fvp.fvpconf \ + -- -C board.msd_mmc.p_mmc_file=${WORKSPACE}/arm-systemready/IR/prebuilt_images/v23.09_2.1.0/ir-acs-live-image-generic-arm64.wic + ``` + + :::note + The FVP will reset multiple times during the test. The ACS tests might take up to 1 day to complete when run on FVP. + ::: + +The message `ACS run is completed` will be displayed on the FVP host terminal when the test runs to completion. +You will be prompted to press the Enter key to access the Linux prompt. + +#### Test sequence and results {.reference} + +U-Boot should be able to boot the GRUB bootloader from the first partition. + +If GRUB is not interrupted, the tests are executed automatically in the following order: + +- SCT +- UEFI BSA +- FWTS + +The results can be fetched from the `acs_results` folder in the `BOOT` partition of the SD Card image used by FVP. + +Access the `acs_results` folder in FVP by running the following commands: + +``` +sudo mkdir /mnt/test +sudo mount -o rw,offset=1048576 \ +${WORKSPACE}/arm-systemready/IR/prebuilt_images/v23.09_2.1.0/ir-acs-live-image-generic-arm64.wic \ +/mnt/test +``` + +## Capsule update {.reference} + +The following Payload GUIDs (`${BL2_GUID}`, `${TFM_S_GUID}`, `${FIP_GUID}`, and `${INITRAMFS_GUID}`) are for the `fvp`: + +Table: Payload GUIDs + ++-----------+--------------------------------------+ +| Payloads | FVP | ++===========+======================================+ +| BL2 | f1d883f9-dfeb-5363-98d8-686ee3b69f4f | ++-----------+--------------------------------------+ +| TFM_S | 7fad470e-5ec5-5c03-a2c1-4756b495de61 | ++-----------+--------------------------------------+ +| FIP | f1933675-5a8c-5b6d-9ef4-846739e89bc8 | ++-----------+--------------------------------------+ +| INITRAMFS | f771aff9-c7e9-5f99-9eda-2369dd694f61 | ++-----------+--------------------------------------+ + +The following section describes the steps to update the firmware using Capsule Update +as the Corstone-1000 supports UEFI. + +The firmware update process is tested with an invalid capsule and with valid capsules to validate the robustness and +error-handling capabilities of the firmware update mechanism. + +- Positive full capsule update test: The Corstone-1000 is provided with a valid full capsule, which it applies successfully. The system then boots normally and reaches the Linux command prompt. +- Positive partial capsule update test: The Corstone-1000 is provided with a valid partial capsule that specifies an update for a single component only. The capsule is applied successfully, after which the system boots normally and reaches the Linux command prompt. +- Rollback protection capsule update test: The Corstone-1000 is provided with an outdated capsule containing lower version numbers for all payloads. The capsule is correctly rejected due to rollback protection, and the previously installed firmware is retained. + +Three different capsules are therefore needed to perform the tests. + +The following payloads can be individually updated: + +- Boot Loader stage 2 (BL2) +- Trusted Firmware-M Secure partition (TFM_S) +- Firmware Image Package (FIP) +- Initial RAM Filesystem (INITRAMFS) + +### Generate capsules {.reference} + +[EDK II's]($edk2_repository) `GenerateCapsule` tool is used to generate capsules and is built automatically +for the host machine during the firmware image building process. +The tool can be found at `${WORKSPACE}/build/tmp/sysroots-components/aarch64/edk2-basetools-native/usr/bin/edk2-BaseTools/BinWrappers/PosixLike/GenerateCapsule`. + +A JSON file containing metadata about the capsule payloads needs to be created using the script +found at `${WORKSPACE}/meta-arm/meta-arm/scripts/generate_capsule_json_multiple.py`. +This JSON file is required by EDK II's `GenerateCapsule` tool to generate the capsule. + +The capsule's default metadata passed can be found in the `${WORKSPACE}/meta-arm/meta-arm-bsp/recipes-bsp/images/corstone1000-flash-firmware-image.bb` +and `${WORKSPACE}/meta-arm/kas/corstone1000-image-configuration.yml` files. + +#### Valid full capsule {.reference} + +An automatically generated capsule can be found at `${WORKSPACE}/build/tmp/deploy/images/corstone1000-fvp/corstone1000-fvp-v6.uefi.capsule` after running a firmware build. + +The default metadata values are assumed to be correct to generate a valid capsule. + +This capsule will be used for the positive capsule update test. + +#### Valid partial capsule {.reference} + +To generate a capsule that updates only a single component, explicitly set the firmware version for that component and mark it as the only payload to be updated. + +The partial capsule is also valid, but sets the firmware version to 7 only for the BL2 component, indicating that no other components should be updated. + +Use the following commands to generate the `capsule_config.json` file, which is required by the EDK2 tool for capsule creation: + +``` +cd ${WORKSPACE} + +python3 meta-arm/meta-arm/scripts/generate_capsule_json_multiple.py \ +--selected_components DUMMY_START BL2 DUMMY_END \ +--components DUMMY_START BL2 TFM_S FIP INITRAMFS DUMMY_END \ +--fw_versions 0 7 0 0 0 0 \ +--guids \ +6f784cbf-7938-5c23-8d6e-24d2f1410fa9 \ +${BL2_GUID} ${TFM_S_GUID} ${FIP_GUID} ${INITRAMFS_GUID} \ +b57e432b-a250-5c73-93e3-90205e64baba \ +--hardware_instances 1 1 1 1 1 1 \ +--lowest_supported_versions 5 5 5 5 5 5 \ +--monotonic_counts 1 1 1 1 1 1 \ +--payloads \ +build/tmp/work/corstone1000_fvp-poky-linux-musl/corstone1000-flash-firmware-image/1.0/sources/corstone1000-flash-firmware-image-1.0/dummy.bin \ +build/tmp/deploy/images/corstone1000-fvp/trusted-firmware-m/bl2_signed.bin \ +build/tmp/deploy/images/corstone1000-fvp/trusted-firmware-m/tfm_s_signed.bin \ +build/tmp/deploy/images/corstone1000-fvp/signed_fip.bin \ +build/tmp/deploy/images/corstone1000-fvp/Image.gz-initramfs-corstone1000-fvp.bin \ +build/tmp/work/corstone1000_fvp-poky-linux-musl/corstone1000-flash-firmware-image/1.0/sources/corstone1000-flash-firmware-image-1.0/dummy.bin \ +--update_image_indexes 5 1 2 3 4 6 \ +--private_keys \ +build/tmp/deploy/images/corstone1000-fvp/corstone1000_capsule_key.key \ +build/tmp/deploy/images/corstone1000-fvp/corstone1000_capsule_key.key \ +build/tmp/deploy/images/corstone1000-fvp/corstone1000_capsule_key.key \ +build/tmp/deploy/images/corstone1000-fvp/corstone1000_capsule_key.key \ +build/tmp/deploy/images/corstone1000-fvp/corstone1000_capsule_key.key \ +build/tmp/deploy/images/corstone1000-fvp/corstone1000_capsule_key.key \ +--certificates \ +build/tmp/deploy/images/corstone1000-fvp/corstone1000_capsule_cert.crt \ +build/tmp/deploy/images/corstone1000-fvp/corstone1000_capsule_cert.crt \ +build/tmp/deploy/images/corstone1000-fvp/corstone1000_capsule_cert.crt \ +build/tmp/deploy/images/corstone1000-fvp/corstone1000_capsule_cert.crt \ +build/tmp/deploy/images/corstone1000-fvp/corstone1000_capsule_cert.crt \ +build/tmp/deploy/images/corstone1000-fvp/corstone1000_capsule_cert.crt \ +--output capsule_config.json +``` + +Run the command below to generate the partial capsule: + +``` +./build/tmp/sysroots-components/aarch64/edk2-basetools-native/usr/bin/edk2-BaseTools/BinWrappers/PosixLike/GenerateCapsule \ +-e \ +-j capsule_config.json \ +--capflag PersistAcrossReset \ +-o corstone1000-fvp-partial-v7.uefi.capsule +``` + +The partial capsule will be located in the `${WORKSPACE}` directory. + +#### Invalid capsule {.reference} + +Generate a capsule with firmware version metadata for all payloads set lower than that of a valid capsule. +The valid capsule has a default firmware version of 6 for all payloads, while the simulated invalid capsule has the firmware version set to 5 for all payloads. + +Use the following commands to generate the `capsule_config.json` file, which is required by the EDK2 tool for capsule creation: + +``` +cd ${WORKSPACE} + +python3 meta-arm/meta-arm/scripts/generate_capsule_json_multiple.py \ +--selected_components DUMMY_START BL2 TFM_S FIP INITRAMFS DUMMY_END \ +--components DUMMY_START BL2 TFM_S FIP INITRAMFS DUMMY_END \ +--fw_versions 5 5 5 5 5 5 \ +--guids \ +6f784cbf-7938-5c23-8d6e-24d2f1410fa9 \ +${BL2_GUID} ${TFM_S_GUID} ${FIP_GUID} ${INITRAMFS_GUID} \ +b57e432b-a250-5c73-93e3-90205e64baba \ +--hardware_instances 1 1 1 1 1 1 \ +--lowest_supported_versions 5 5 5 5 5 5 \ +--monotonic_counts 1 1 1 1 1 1 \ +--payloads \ +build/tmp/work/corstone1000_fvp-poky-linux-musl/corstone1000-flash-firmware-image/1.0/sources/corstone1000-flash-firmware-image-1.0/dummy.bin \ +build/tmp/deploy/images/corstone1000-fvp/trusted-firmware-m/bl2_signed.bin \ +build/tmp/deploy/images/corstone1000-fvp/trusted-firmware-m/tfm_s_signed.bin \ +build/tmp/deploy/images/corstone1000-fvp/signed_fip.bin \ +build/tmp/deploy/images/corstone1000-fvp/Image.gz-initramfs-corstone1000-fvp.bin \ +build/tmp/work/corstone1000_fvp-poky-linux-musl/corstone1000-flash-firmware-image/1.0/sources/corstone1000-flash-firmware-image-1.0/dummy.bin \ +--update_image_indexes 5 1 2 3 4 6 \ +--private_keys \ +build/tmp/deploy/images/corstone1000-fvp/corstone1000_capsule_key.key \ +build/tmp/deploy/images/corstone1000-fvp/corstone1000_capsule_key.key \ +build/tmp/deploy/images/corstone1000-fvp/corstone1000_capsule_key.key \ +build/tmp/deploy/images/corstone1000-fvp/corstone1000_capsule_key.key \ +build/tmp/deploy/images/corstone1000-fvp/corstone1000_capsule_key.key \ +build/tmp/deploy/images/corstone1000-fvp/corstone1000_capsule_key.key \ +--certificates \ +build/tmp/deploy/images/corstone1000-fvp/corstone1000_capsule_cert.crt \ +build/tmp/deploy/images/corstone1000-fvp/corstone1000_capsule_cert.crt \ +build/tmp/deploy/images/corstone1000-fvp/corstone1000_capsule_cert.crt \ +build/tmp/deploy/images/corstone1000-fvp/corstone1000_capsule_cert.crt \ +build/tmp/deploy/images/corstone1000-fvp/corstone1000_capsule_cert.crt \ +build/tmp/deploy/images/corstone1000-fvp/corstone1000_capsule_cert.crt \ +--output capsule_config.json +``` + +Run the command below to generate the invalid capsule: + +``` +./build/tmp/sysroots-components/aarch64/edk2-basetools-native/usr/bin/edk2-BaseTools/BinWrappers/PosixLike/GenerateCapsule \ +-e \ +-j capsule_config.json \ +--capflag PersistAcrossReset \ +-o corstone1000-fvp-v5.uefi.capsule +``` + +The invalid capsule will be located in the `${WORKSPACE}` directory. + +### Transfer capsules to target {.reference} + +The capsule delivery process described below is the direct method (usage of capsules from the ACS image) +as opposed to the on-disk method (delivery of capsules using a file on a mass storage device). + +1. Download and extract the ACS image as described in the ACS image preparation steps above. + The ACS image extraction location will be referred below as `${ACS_IMAGE_PATH}`. + + :::note + Creating a USB drive with the ACS image is not required as the image will be mounted with the steps below. + ::: + +2. Find the first partition's offset of the `ir-acs-live-image-generic-arm64.wic` image using the `fdisk` tool. + The partition table can be listed using: + + ``` + fdisk -lu ${ACS_IMAGE_PATH}/ir-acs-live-image-generic-arm64.wic + Device Start End Sectors Size Type + ${ACS_IMAGE_PATH}/ir-acs-live-image-generic-arm64.wic1 2048 309247 307200 150M Microsoft basic data + ${ACS_IMAGE_PATH}/ir-acs-live-image-generic-arm64.wic2 309248 1343339 1034092 505M Linux filesystem + ``` + + Given that the first partition starts at sector 2048 and each sector is 512 bytes in size, + the first partition is at offset 1048576 (2048 x 512). + +3. Mount the `ir-acs-live-image-generic-arm64.wic` image using the previously calculated offset: + + ``` + sudo mkdir /mnt/ir-acs-live-image-generic-arm64 + sudo mount -o rw,offset= ${ACS_IMAGE_PATH}/ir-acs-live-image-generic-arm64.wic /mnt/ir-acs-live-image-generic-arm64 + ``` + +4. Copy the capsules: + + ``` + sudo cp ${WORKSPACE}/build/tmp/deploy/images/corstone1000-fvp/corstone1000-fvp-v6.uefi.capsule /mnt/ir-acs-live-image-generic-arm64/ + sudo cp ${WORKSPACE}/corstone1000-fvp-v5.uefi.capsule /mnt/ir-acs-live-image-generic-arm64/ + sudo cp ${WORKSPACE}/corstone1000-fvp-partial-v7.uefi.capsule /mnt/ir-acs-live-image-generic-arm64/ + sync + ``` + +5. Unmount the IR image: + + ``` + sudo umount /mnt/ir-acs-live-image-generic-arm64 + ``` + +### Run capsule update tests {.reference} + +The valid capsules will be used first to run the positive capsule update tests. +This will be followed by using the invalid capsule to run the rollback protection capsule update test. + +:::note +This sequence order must be respected as the invalid capsule has a firmware version lower than the firmware version in the valid capsule. The rollback protection capsule update test effectively tests that firmware rollback is not permitted. +::: + +#### Positive full capsule update {.reference} + +To run the test: + +1. Run Corstone-1000 with the ACS image containing the two capsule files: + + 1. Run `tmux`: + + ``` + cd ${WORKSPACE} && tmux + ``` + + 2. Run the FVP within `tmux` with the IR prebuilt image which now also contains the two capsules: + + ``` + kas shell meta-arm/kas/corstone1000-fvp.yml:meta-arm/ci/debug.yml:meta-arm/kas/corstone1000-a320.yml \ + -c "../meta-arm/scripts/runfvp --terminals=tmux \ + -- -C board.msd_mmc.p_mmc_file=${ACS_IMAGE_PATH}/ir-acs-live-image-generic-arm64.wic" + ``` + + :::note + `${ACS_IMAGE_PATH}` must be an absolute path. Ensure there are no spaces before or after of `=` of the `-C board.msd_mmc.p_mmc_file` option. + ::: + +2. Wait until U-Boot loads EFI from the ACS image and interrupt the EFI shell by pressing the `Escape` key when the following prompt is displayed. + + ``` + Press ESC in 4 seconds to skip startup.nsh or any other key to continue. + ``` + +3. The content of the first file system (`File System 0`), where the capsule files were copied, can be accessed by running the command `FS0:`. + +4. Run the `CapsuleApp` application with the valid capsule file: + + ``` + EFI/BOOT/app/CapsuleApp.efi corstone1000-fvp-v6.uefi.capsule + ``` + + The capsule update will be started. The capsule update takes about 15-30 minutes to complete on FVP. The Corstone-1000 will reset after successfully applying the capsule. + + The software stack copies the capsule content to the external flash, which is shared between the Secure Enclave and the Host Processor + before rebooting the system. + + After the first reboot, TrustedFirmware-M should apply the valid capsule and display the following log on the Secure Enclave terminal + before rebooting the system a second time: + + ``` + ... + SysTick_Handler: counted = 10, expiring on = 360 + SysTick_Handler: counted = 20, expiring on = 360 + SysTick_Handler: counted = 30, expiring on = 360 + ... + metadata_write: success: active = 1, previous = 0 + flash_full_capsule: exit + corstone1000_fwu_flash_image: exit: ret = 0 + ... + ``` + + The above log snippet indicates that the new capsule image is successfully applied, and the board is booting with the external flash's Bank-1. + + After a second reboot, the following log should be displayed on on the Secure Enclave terminal (`ttyUSB1`): + + ``` + ... + fmp_set_image_info:133 Enter + FMP image update: image id = 0 + FMP image update: status = 0version=6 last_attempt_version=6. + fmp_set_image_info:157 Exit. + corstone1000_fwu_host_ack: exit: ret = 0 + ... + ``` + +5. Interrupt the U-Boot shell. + + ``` + Hit any key to stop autoboot: + ``` + +6. Run the following commands in order to run the Corstone-1000 Linux kernel, otherwise, the execution ends up in the ACS live image: + + ``` + $ unzip $kernel_addr 0x90000000 + $ loadm 0x90000000 $kernel_addr_r $filesize + $ bootefi $kernel_addr_r $fdtcontroladdr + ``` + +7. The first boot after a capsule update is considered the trial stage, during which the FWU image is accepted. + However, to view the updated contents of the EFI System Resource Table (ESRT), an additional reboot is required. + + ``` + # reboot + ``` + +8. Interrupt the U-Boot shell when prompted. + + ``` + Hit any key to stop autoboot: + ``` + +9. Run the following commands to boot the Corstone-1000 Linux kernel. + + :::note + If these commands are not executed, the system will default to booting into the ACS live image. + ::: + + ``` + $ unzip $kernel_addr 0x90000000 + $ loadm 0x90000000 $kernel_addr_r $filesize + $ bootefi $kernel_addr_r $fdtcontroladdr + ``` + +10. Once the system has fully booted again, read [Verifying firmware versions with ESRT] to confirm that the firmware version reflects the updated capsule. Do not terminate FVP between the positive full capsule update and partial capsule update tests. + +#### Positive partial capsule update {.reference} + +Follow the steps for the [Positive full capsule update test], ensuring you use `corstone1000-fvp-partial-v7.uefi.capsule` instead of `corstone1000-fvp-v6.uefi.capsule`. + +Once the system has fully booted again, read [Verifying firmware versions with ESRT] to confirm that the firmware version reflects the updated capsule. + +:::note +Do not terminate FVP between the positive partial capsule update rollback protection capsule update tests. +::: + +#### Rollback protection capsule update {.reference} + +The [Positive partial capsule update test] must be run before running the rollback protection capsule update test. + +To run the rollback protection capsule update test: + +1. After running the positive capsule update test, reboot the system by typing the following command: + + ``` + reboot + ``` + +2. Wait until U-Boot loads EFI from the ACS image and interrupt the EFI shell by pressing the `Escape` key when the following prompt is displayed. + + ``` + Press ESC in 4 seconds to skip startup.nsh or any other key to continue. + ``` + +3. The content of the first file system (`File System 0`), where the capsule files were copied, can be accessed by running the following command: + + ``` + FS0: + ``` + +4. Run the `CapsuleApp` application with the invalid capsule file: + + ``` + EFI/BOOT/app/CapsuleApp.efi corstone1000-fvp-v5.uefi.capsule + ``` + +5. TrustedFirmware-M should reject the capsule due to having a lower firmware version and display the following log on 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 = 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=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 + ... + ``` + + The Secure Enclave tries to load the new image a predetermined number of times + if the capsule passes initial verification but fails verifications performed during + boot time. + + ``` + ... + metadata_write: success: active = 0, previous = 1 + fwu_select_previous: in regular state by choosing previous active bank + ... + ``` + + The Secure Enclave eventually reverts back to the previously running image. + +6. Reboot manually: + + ``` + Shell> reset + ``` + +7. Interrupt the U-Boot shell. + + ``` + Hit any key to stop autoboot: + ``` + +8. Run the following commands in order to run the Corstone-1000 Linux kernel, otherwise, the execution ends up in the ACS live image. + + ``` + $ unzip $kernel_addr 0x90000000 + $ loadm 0x90000000 $kernel_addr_r $filesize + $ bootefi $kernel_addr_r $fdtcontroladdr + ``` + +9. The first boot after a capsule update is considered the trial stage, during which the FWU image is rejected. + However, to view the updated contents of the ESRT, an additional reboot is required. + + ``` + # reboot + ``` + +10. Interrupt the U-Boot shell when prompted. + + ``` + Hit any key to stop autoboot: + ``` + +11. Run the following commands to boot the Corstone-1000 Linux kernel. If these commands are not executed, the system will default to booting into the ACS live image. + + ``` + $ unzip $kernel_addr 0x90000000 + $ loadm 0x90000000 $kernel_addr_r $filesize + $ bootefi $kernel_addr_r $fdtcontroladdr + ``` + +12. Once the system has fully booted again, read [Verifying firmware versions with ESRT] to confirm that the firmware version reflects the updated capsule. + +### Verifying firmware versions via ESRT {.reference} + +After the system has fully booted, verify that the firmware versions of all applied capsule payloads +match those currently installed on the system. This can be done by inspecting the ESRT, which is exposed by the Linux kernel. + +#### Reading ESRT entries {.reference} + +To read each ESRT entry, use the following commands: + +``` +cat /sys/firmware/efi/esrt/entries/entry0/* +cat /sys/firmware/efi/esrt/entries/entry1/* +cat /sys/firmware/efi/esrt/entries/entry2/* +cat /sys/firmware/efi/esrt/entries/entry3/* +``` + +These entries typically correspond to: + +- `entry0`: BL2 +- `entry1`: TFM_S +- `entry2`: FIP +- `entry3`: INITRAMFS + +:::note +Entry indices may vary depending on how your firmware capsules are structured. Adjust as needed. +::: + +#### Structure of each ESRT entry {.reference} + +Each directory under `/sys/firmware/efi/esrt/entries/entryX/` contains files representing the following fields: + +Table: ESRT entry fields + ++-------------------------------+------------------------------------------------------------+ +| Field Name | Description | ++===============================+============================================================+ +| `capsule_flags` | Attributes of the update capsule (e.g., persist, reset) | ++-------------------------------+------------------------------------------------------------+ +| `fw_class` | GUID identifying the firmware component | ++-------------------------------+------------------------------------------------------------+ +| `fw_type` | Firmware type (e.g., system, device, peripheral) | ++-------------------------------+------------------------------------------------------------+ +| `fw_version` | Currently installed firmware version | ++-------------------------------+------------------------------------------------------------+ +| `last_attempt_status` | Status of the last update attempt (e.g., success, failure) | ++-------------------------------+------------------------------------------------------------+ +| `last_attempt_version` | Version that was last attempted to install | ++-------------------------------+------------------------------------------------------------+ +| `lowest_supported_fw_version` | Minimum firmware version that is still supported | ++-------------------------------+------------------------------------------------------------+ + +#### Verifying an ESRT entry {.reference} + +To check the version and status of BL2 (`entry0`), run: + +``` +cat /sys/firmware/efi/esrt/entries/entry0/fw_version +cat /sys/firmware/efi/esrt/entries/entry0/last_attempt_version +cat /sys/firmware/efi/esrt/entries/entry0/last_attempt_status +``` + +#### Positive full capsule update test ESRT {.reference} + +The following list shows the details of the first four ESRT entries for the positive capsule update test: + +- BL2 (`${BL2_GUID}`): + - FW type: 0 + - FW version: 6 + - Lowest supported version: 0 + - Capsule flags: 0 + - Last attempt status: 0 + - Last attempt version: 6 +- TFM_S (`${TFM_S_GUID}`): + - FW type: 0 + - FW version: 6 + - Lowest supported version: 0 + - Capsule flags: 0 + - Last attempt status: 0 + - Last attempt version: 6 +- FIP (`${FIP_GUID}`): + - FW type: 0 + - FW version: 6 + - Lowest supported version: 0 + - Capsule flags: 0 + - Last attempt status: 0 + - Last attempt version: 6 +- INITRAMFS (`${INITRAMFS_GUID}`): + - FW type: 0 + - FW version: 6 + - Lowest supported version: 0 + - Capsule flags: 0 + - Last attempt status: 0 + - Last attempt version: 6 + +#### Positive partial capsule update test ESRT {.reference} + +The following list shows the details of the first four ESRT entries for the positive partial capsule update test: + +- BL2 (`${BL2_GUID}`): + - FW type: 0 + - FW version: 7 + - Lowest supported version: 0 + - Capsule flags: 0 + - Last attempt status: 0 + - Last attempt version: 7 +- TFM_S (`${TFM_S_GUID}`): + - FW type: 0 + - FW version: 6 + - Lowest supported version: 0 + - Capsule flags: 0 + - Last attempt status: 0 + - Last attempt version: 6 +- FIP (`${FIP_GUID}`): + - FW type: 0 + - FW version: 6 + - Lowest supported version: 0 + - Capsule flags: 0 + - Last attempt status: 0 + - Last attempt version: 6 +- INITRAMFS (`${INITRAMFS_GUID}`): + - FW type: 0 + - FW version: 6 + - Lowest supported version: 0 + - Capsule flags: 0 + - Last attempt status: 0 + - Last attempt version: 6 + +#### Rollback protection capsule update test ESRT {.reference} + +The following list shows the details of the first four ESRT entries for the rollback protection capsule update test: + +- BL2 (`${BL2_GUID}`): + - FW type: 0 + - FW version: 7 + - Lowest supported version: 0 + - Capsule flags: 0 + - Last attempt status: 1 + - Last attempt version: 5 +- TFM_S (`${TFM_S_GUID}`): + - FW type: 0 + - FW version: 6 + - Lowest supported version: 0 + - Capsule flags: 0 + - Last attempt status: 0 + - Last attempt version: 6 +- FIP (`${FIP_GUID}`): + - FW type: 0 + - FW version: 6 + - Lowest supported version: 0 + - Capsule flags: 0 + - Last attempt status: 0 + - Last attempt version: 6 +- INITRAMFS (`${INITRAMFS_GUID}`): + - FW type: 0 + - FW version: 6 + - Lowest supported version: 0 + - Capsule flags: 0 + - Last attempt status: 0 + - Last attempt version: 6 + +See the [UEFI documentation](https://uefi.org/specs/UEFI/2.10/23_Firmware_Update_and_Reporting.html#id29) for more information on the significance of the table fields. + +## Linux distributions {.reference} + +This sections describes the steps to install major Linux distributions to the Corstone-1000 Host Processor. + +The Linux distributions to be installed are: + +- [Debian](https://www.debian.org/) +- [openSUSE](https://www.opensuse.org/) + +Follow the instructions below to install the Linux distributions to the Corstone-1000 software stack. + +### Prepare installation media {.reference} + +The media containing the bootable files required to start the installation process needs to be prepared. + +Follow the instructions below to create the installation media. + +1. Using your development machine, download one of following Linux distribution images: + + - [Debian installer image](https://cdimage.debian.org/mirror/cdimage/archive/12.7.0/arm64/iso-dvd/) + - [openSUSE Leap installer image](https://download.opensuse.org/distribution/leap/15.6/iso/openSUSE-Leap-15.6-DVD-aarch64-Current.iso) + + Note that the location of the ISO file on the development machine will be referred to as `${DISTRO_INSTALLER_ISO_PATH}`. + +2. Create the installation media which will contain the necessary files to install the operation system. + + The distribution installer ISO file does not need to be burnt to a USB drive. + It will be used as is when starting the FVP install the distribution. + +### Prepare system drive {.reference} + +A system (or boot) drive, to store all the operating system files and used to boot the distribution, is required as +Corstone-1000 on-board non-volatile storage size is insufficient for installing the distributions. + +1. Create an 10 GB GUID Partition Table (GPT) formatted MultiMediaCard (MMC) image. + + ``` + dd if=/dev/zero of=${WORKSPACE}/fvp_distro_system_drive.img \ + bs=1 count=0 seek=10G; sync; \ + parted -s fvp_distro_system_drive.img mklabel gpt + ``` + +2. This MMC image will be used as the primary drive to boot the distribution. + +### Installation {.reference} + +To install: + +1. Run the `tmux`: + + ``` + cd ${WORKSPACE} && tmux + ``` + +2. Start the FVP within `tmux` with the system drive as the primary drive and the distro ISO file as the secondary drive: + + ``` + kas shell meta-arm/kas/corstone1000-fvp.yml:meta-arm/ci/debug.yml:meta-arm/kas/corstone1000-a320.yml \ + -c "../meta-arm/scripts/runfvp --terminals=tmux -- \ + -C board.msd_mmc.p_mmc_file=${WORKSPACE}/fvp_distro_system_drive.img \ + -C board.msd_mmc_2.p_mmc_file=${DISTRO_INSTALLER_ISO_PATH}" + ``` + + The Linux distribution will be installed on `fvp_distro_system_drive.img`. + +#### Debian installation extra steps {.reference} + +The Debian installation may need the following extra steps: + +1. Answer `Yes` to the question `Force grub installation to the EFI removable media path?`. + + 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`. + 3. Select `Continue`. + 4. Enter the following command: + + ``` + in-target grub-install --no-nvram --force-extra-removable + ``` + + 5. Enter the following command: + + ``` + in-target update-grub + ``` + + 6. Enter the following command: + + ``` + exit + ``` + + 7. Select `Continue without boot loader`, then select `Continue` on the next popup. + 8. At this stage, the installation should proceed as normal. + +2. Answer `No` to the question `Update NVRAM variables to automatically boot into Debian?`. + +### Boot distribution {.reference} + +The platform should automatically boot into the installed operating system image. + +Stop the FVP with `CTRL+C` and run `tmux`: + +``` +cd ${WORKSPACE} && tmux +``` + +Run the command below to simulate a cold boot: + +``` +kas shell meta-arm/kas/corstone1000-fvp.yml:meta-arm/ci/debug.yml:meta-arm/kas/corstone1000-a320.yml \ +-c "../meta-arm/scripts/runfvp --terminals=tmux -- \ +-C board.msd_mmc.p_mmc_file=${WORKSPACE}/fvp_distro_system_drive.img" +``` + +:::note +To manually enter recovery mode, once the FVP begins booting, you can quickly change the boot option in GRUB, to boot into recovery mode. This option will disappear quickly, so it is best to preempt it. Select `Advanced Options for ` and then ` (recovery mode)`. +::: + +The platform will then enter recovery mode, from which the user can access a shell after entering the password for the `root` user. + +#### Timeout optimizations {.reference} + +Operating system timeouts are inconsistent across systems. Skip this section if the system boots to Debian or openSUSE without any issue. + +Make the system modification below whilst in recovery mode to increase timeouts and boot to the installed distribution. + +1. Remove the timeout limit for device operations. + + - Debian + + ``` + vi /etc/systemd/system.conf + DefaultDeviceTimeoutSec=infinity + ``` + + - openSUSE + + ``` + vi /usr/lib/systemd/system.conf + DefaultDeviceTimeoutSec=infinity + ``` + + :::note + As modifying `system.conf` in `/usr/lib/systemd/` is not working as it is getting overwritten, copy `system.conf` from `/usr/lib/systemd/` to `/etc/systemd/system.conf.d/` after the above edit. + ::: + +2. Set the maximum time that the system will wait for a user to successfully log in before timing out to 180 seconds. + + - Debian + + ``` + vi /etc/login.defs + LOGIN_TIMEOUT 180 + ``` + + - openSUSE + + ``` + vi /usr/etc/login.defs + LOGIN_TIMEOUT 180 + ``` + +3. Ensure the changes are applied by running the command `systemctl daemon-reload`. + +4. Perform a cold boot of the platform. + +#### Log into the distribution {.reference} + +Log in with the `root` username and its corresponding password (set during installation) +at the distribution login prompt after booting. For example for Debian, use the command `debian login:`. + +## UEFI secure boot {.reference} + +The UEFI Secure Boot test is designed to verify the integrity and authenticity of the system's boot process. +This test ensures that only trusted, signed images are executed, thereby preventing unauthorized or malicious code from running. +A successful test confirms that the signed image executes correctly, while any unsigned image is blocked from running. + +### Generate keys, signed image and unsigned image {.reference} + +To generate keys: + +1. Build an EFI System Partition as described in [Building an EFI system partition]. + +2. Clone the `iot-platform-assets` repository to your workspace. + + ``` + cd ${WORKSPACE} + + git clone https://gitlab.arm.com/arm-reference-solutions/iot-platform-assets \ + -b CORSTONE1000-2025.12 + ``` + +3. Set the current working directory to build directory's subdirectory containing the software stack build images. + + ``` + cd ${WORKSPACE}/build/tmp/deploy/images/corstone1000-fvp/ + ``` + +4. Run the image signing script (without changing the current working directory). + + ``` + ./${WORKSPACE}/iot-platform-assets/corstone1000/secureboot/create_keys_and_sign.sh \ + -d fvp \ + -v ${CERTIFICATE_VALIDITY_DURATION_IN_DAYS} + ``` + + :::note + The [efitools](https://github.com/vathpela/efitools/) package is required to execute the script. `${CERTIFICATE_VALIDITY_DURATION_IN_DAYS}` is an integer that specifies the certificate's validity period in days. Consult the image signing script help message (`-h`) for more information about other optional arguments. The script is interactive and contains commands that require `sudo` level permissions. + ::: + + The keys, signed kernel image, and unsigned kernel image will be copied to the exisiting ESP image. The modified ESP image can be found at `${WORKSPACE}/build/tmp/deploy/images/corstone1000-fvp/corstone1000-esp-image-corstone1000-fvp.wic`. + +### Run unsigned image boot test {.reference} + +To run an unsigned image boot test: + +1. Follow the instructions in [Use the EFI System Partition] to use the ESP. + +2. Run the software stack as described in the Running the FVP model section of the Build, Flash and Run chapter. + +3. On the Host Processor terminal host side, stop the execution of U-Boot when prompted to do so with the message `Press any key to stop`. + + :::note + There is a timeout of 3 seconds to stop the execution at the U-Boot prompt. The U-Boot prompt looks as follows: + + ``` + corstone1000# + ``` + + ::: + + The rest of the instructions below will be executed on the U-Boot terminal. + +4. On the U-Boot , set the current MMC device. + + ``` + corstone1000# mmc dev 1 + ``` + +5. Enroll the four UEFI secure boot authenticated variables. + + ``` + corstone1000# \ + load mmc 1:1 \$loadaddr corstone1000_secureboot_keys/PK.auth && setenv -e -nv -bs -rt -at -i \$loadaddr:\$filesize PK; \ + load mmc 1:1 \$loadaddr corstone1000_secureboot_keys/KEK.auth && setenv -e -nv -bs -rt -at -i \$loadaddr:\$filesize KEK; \ + load mmc 1:1 \$loadaddr corstone1000_secureboot_keys/db.auth && setenv -e -nv -bs -rt -at -i \$loadaddr:\$filesize db; \ + load mmc 1:1 \$loadaddr corstone1000_secureboot_keys/dbx.auth && setenv -e -nv -bs -rt -at -i \$loadaddr:\$filesize dbx + ``` + +6. Attempt to Load the unsigned kernel image. + + ``` + corstone1000# \ + load mmc 1:1 \$loadaddr corstone1000_secureboot_fvp_images/Image_fvp; \ + loadm \$loadaddr \$kernel_addr_r \$filesize; \ + bootefi \$kernel_addr_r \$fdtcontroladdr + + Booting /MemoryMapped(0x0,0x88200000,0x236aa00) + Image not authenticated + Loading image failed + ``` + +The unsigned Linux kernel image should not be loaded. + +### Run signed image boot test {.reference} + +Before running this test, perform the unsigned image boot test first as described in [Running unsigned image boot tests]. + +Load the signed kernel image. + +``` +corstone1000# \ +load mmc 1:1 \$loadaddr corstone1000_secureboot_fvp_images/Image_fvp.signed; \ +loadm \$loadaddr \$kernel_addr_r $filesize; \ +bootefi \$kernel_addr_r \$fdtcontroladdr +``` + +The signed Linux kernel image should be booted successfully. + +### Disable secure boot {.reference} + +Running the UEFI Secure Boot Test steps stores UEFI authenticated variables in the secure flash. +As a result, U-Boot reads these variables and verifies the Linux kernel image before executing it at each reboot. + +In a typical boot scenario, the Linux kernel image is not signed, which will prevent the system from booting due to failed image authentication. +To resolve this, the Platform Key (one of the UEFI authenticated variables for secure boot) needs to be deleted. + +1. On the Host Processor terminal host side, stop the execution of U-Boot when prompted to do so with the message `Press any key to stop`. + +2. On the U-Boot , delete the Platform Key (PK). + + ``` + corstone1000# \ + mmc dev 1; \ + load mmc 1:1 \$loadaddr corstone1000_secureboot_keys/PK_delete.auth && setenv -e -nv -bs -rt -at -i \$loadaddr:\$filesize PK; \ + boot + ``` + +## PSA API {.reference} + +The following tests the implementation of the Application Programming Interface (API) +of the Platform Security Architecture (PSA) certification scheme. + +The test uses Arm Firmware Framework for Arm A-profile (FF-A) +to communicate between the normal world and the secure world to run the [Arm Platform Security Architecture Test Suite](https://github.com/ARM-software/psa-arch-tests). + +The tests use the `arm_tstee` driver to access Trusted Services Secure Partitions from user space. The driver is included in the Linux Kernel, starting from v6.10. + +1. Start the Corstone-1000 FVP and wait until it boots to Linux. + +2. Run the PSA API tests by running the commands below in the order shown: + + ``` + psa-iat-api-test + psa-crypto-api-test + psa-its-api-test + psa-ps-api-test + ``` + +## Symmetric multiprocessing {.reference} + +Symmetric multiprocessing (SMP) mode is supported on the Corstone-1000 with Cortex-A320 FVP, but is disabled by default. + +1. Build the software stack with SMP mode enabled. + + ``` + kas build meta-arm/kas/corstone1000-fvp.yml:meta-arm/ci/debug.yml:meta-arm/kas/corstone1000-a320.yml:\ + meta-arm/kas/corstone1000-multicore.yml + ``` + +2. Run the Corstone-1000 FVP. + + ``` + kas shell meta-arm/kas/corstone1000-fvp.yml:meta-arm/ci/debug.yml:meta-arm/kas/corstone1000-a320.yml:\ + meta-arm/kas/corstone1000-multicore.yml \ + -c "../meta-arm/scripts/runfvp" + ``` + +3. Verify that the FVP is running the Host Processor with more than one CPU core: + + ``` + nproc + 4 # number of processing units + ``` + +## Ethos-U85 NPU {.reference} + +To build on Ethos-U85 NPU: + +1. Clone the `iot-platform-assets` repository to your `${WORKSPACE}`. + + ``` + cd ${WORKSPACE} + git clone https://git.gitlab.arm.com/arm-reference-solutions/iot-platform-assets.git \ + -b CORSTONE1000-2025.12 + ``` + +2. Copy the additional kas configuration file to: + + ``` + cp ${WORKSPACE}/iot-platform-assets/corstone1000/ethos-u85_test/ethos-u85-test.yml \ + ${WORKSPACE}/meta-arm/kas/ + ``` + +3. Copy the mesa package Git patch file to your copy of meta-arm. + + ``` + cp -f ${WORKSPACE}/iot-platform-assets/corstone1000/ethos-u85_test/0001-arm-bsp-mesa-Package-Teflon-test-runner-and-models.patch \ + ${WORKSPACE}/meta-arm/ + ``` + +4. Apply the Git patch to meta-arm. + + ``` + cd ${WORKSPACE}/meta-arm/ + git apply 0001-arm-bsp-mesa-Package-Teflon-test-runner-and-models.patch + cd ${WORKSPACE} + ``` + +5. Re-build the Corstone-1000 FVP software stack as follows: + + ``` + kas build meta-arm/kas/corstone1000-fvp.yml:meta-arm/ci/debug.yml:meta-arm/kas/corstone1000-a320.yml:\ + meta-arm/kas/ethos-u85-test.yml + ``` + +6. Run the Corstone-1000 FVP: + + ``` + kas shell meta-arm/kas/corstone1000-fvp.yml:meta-arm/ci/debug.yml:meta-arm/kas/corstone1000-a320.yml:\ + meta-arm/kas/ethos-u85-test.yml \ + -c "../meta-arm/scripts/runfvp" + ``` + +7. To verify you are running the Corstone-1000 FVP (Cortex-A320), build and run the FVP and inspect the CPU model + reported in `/proc/cpuinfo` as shown below. Inside the FVP shell, confirm the core type: + + ``` + grep -E 'CPU part|model name' /proc/cpuinfo + # Expect: CPU part : 0xd8f (which corresponds to Cortex-A320) + ``` + +8. Run the `test_teflon` test application inside the FVP shell as follows: + + ``` + export TEFLON_TEST_DELEGATE=/usr/lib/libteflon.so + export TEFLON_TEST_DATA=/usr/share/teflon/tests + test_teflon --gtest_filter='Models.*' + ``` + + The test completes in approximately one minute. diff --git a/meta-arm-bsp/documentation/corstone1000-a320/topics/user-guide.md b/meta-arm-bsp/documentation/corstone1000-a320/topics/user-guide.md new file mode 100644 index 00000000..c0b1e6bc --- /dev/null +++ b/meta-arm-bsp/documentation/corstone1000-a320/topics/user-guide.md @@ -0,0 +1,265 @@ +# Build, flash and run {.chapter permissions=non-confidential} + +The Arm Corstone-1000 software stack uses the Yocto Project to build a tiny Linux distribution suitable for the Arm Corstone-1000 platform (kernel and initramfs filesystem less than 6 MB on the flash). + +The Corstone-1000 software stack can be run on [Arm Corstone-1000 Ecosystem FVP (Fixed Virtual Platform)](https://developer.arm.com/downloads/-/arm-ecosystem-fvps) and is built on top of Yocto Project's [Whinlatter release]($meta_arm_repository_release_branch). + +The Yocto Project relies on the [BitBake](https://docs.yoctoproject.org/bitbake.html#bitbake-documentation) tool as its build tool. Please see the [Yocto Project documentation](https://docs.yoctoproject.org/) for more information. + +## Prerequisites {.reference} + +This guide assumes that your host machine is running Ubuntu 24.04 LTS (with `sudo` rights), 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 2.39.2 or greater. +- Python 3.11.2 or greater. +- GNU Tar 1.34 or greater. +- GNU Compiler Collection 12.2 or greater. +- GNU Make 4.3 or greater. +- tmux 3.3 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) + +## Software components {.reference} + +Within the Yocto Project, each component included in the Corstone-1000 software stack is specified as +a [BitBake recipe](https://docs.yoctoproject.org/bitbake/2.2/bitbake-user-manual/bitbake-user-manual-intro.html#recipes). +The recipes specific to the Corstone-1000 BSP are located at: +`${WORKSPACE}/meta-arm/meta-arm-bsp/`. + +`${WORKSPACE}` refers to the absolute path to your workspace where the `meta-arm` repository will be cloned. Consider exporting it (e.g., `export WORKSPACE=$(realpath .)`) if you're already in the workspace directory, +so you can copy and paste the commands from this guide verbatim. + +The Yocto machine config files are at: + +- `${WORKSPACE}/meta-arm/meta-arm-bsp/conf/machine/include/corstone1000-a320.inc` +- `${WORKSPACE}/meta-arm/meta-arm-bsp/conf/machine/corstone1000-a320-fvp.conf` + +:::note +All the paths stated in this document are absolute paths. +::: + +### Host processor components {.reference} + +This section describes the components used in the host processor. + +#### Trusted Firmware-A {.reference} + +The following [Trusted Firmware-A](https://git.trustedfirmware.org/TF-A/trusted-firmware-a.git) components are used: + +Table: Trusted Firmware-A components + +| Type | Path | +| --------- | ---------------------------------------------------------------------------------------------------------------- | +| bbappend | `${WORKSPACE}/meta-arm/meta-arm-bsp/recipes-bsp/trusted-firmware-a/trusted-firmware-a_%.bbappend` | +| Recipe | `${WORKSPACE}/meta-arm/meta-arm/recipes-bsp/trusted-firmware-a/trusted-firmware-a_2.14.0.bb` | + +#### Trusted Services {.reference} + +The following [Trusted Services](https://trusted-services.readthedocs.io/en/latest/index.html) components are used: + +Table: Trusted Services components + +| Type | Path | +| --------- | ---------------------------------------------------------------------------------------------------------------- | +| bbappend | `${WORKSPACE}/meta-arm/meta-arm-bsp/recipes-security/trusted-services/libts_%.bbappend` | +| bbappend | `${WORKSPACE}/meta-arm/meta-arm-bsp/recipes-security/trusted-services/ts-psa-crypto-api-test_%.bbappend` | +| bbappend | `${WORKSPACE}/meta-arm/meta-arm-bsp/recipes-security/trusted-services/ts-psa-iat-api-test_%.bbappend` | +| bbappend | `${WORKSPACE}/meta-arm/meta-arm-bsp/recipes-security/trusted-services/ts-psa-its-api-test_%.bbappend` | +| bbappend | `${WORKSPACE}/meta-arm/meta-arm-bsp/recipes-security/trusted-services/ts-psa-ps-api-test_%.bbappend` | +| bbappend | `${WORKSPACE}/meta-arm/meta-arm-bsp/recipes-security/trusted-services/ts-sp-se-proxy_%.bbappend` | +| bbappend | `${WORKSPACE}/meta-arm/meta-arm-bsp/recipes-security/trusted-services/ts-sp-smm-gateway_%.bbappend` | +| Recipe | `${WORKSPACE}/meta-arm/meta-arm/recipes-security/trusted-services/libts_git.bb` | +| Recipe | `${WORKSPACE}/meta-arm/meta-arm/recipes-security/trusted-services/ts-psa-crypto-api-test_git.bb` | +| Recipe | `${WORKSPACE}/meta-arm/meta-arm/recipes-security/trusted-services/ts-psa-iat-api-test_git.bb` | +| Recipe | `${WORKSPACE}/meta-arm/meta-arm/recipes-security/trusted-services/ts-psa-its-api-test_git.bb` | +| Recipe | `${WORKSPACE}/meta-arm/meta-arm/recipes-security/trusted-services/ts-psa-ps-api-test_git.bb` | +| Recipe | `${WORKSPACE}/meta-arm/meta-arm/recipes-security/trusted-services/ts-sp-smm-gateway_git.bb` | +| Recipe | `${WORKSPACE}/meta-arm/meta-arm/recipes-security/trusted-services/ts-sp-se-proxy_git.bb` | + +#### OP-TEE {.reference} + +The following [OP-TEE](https://git.trustedfirmware.org/OP-TEE/optee_os.git) components are used: + +Table: OP-TEE components + +| Type | Path | +| --------- | ---------------------------------------------------------------------------------------------------------------- | +| bbappend | `${WORKSPACE}/meta-arm/meta-arm-bsp/recipes-security/optee/optee-os_4.%.bbappend` | +| Recipe | `${WORKSPACE}/meta-arm/meta-arm/recipes-security/optee/optee-os_4.9.0.bb` | + +#### U-Boot {.reference} + +The following [U-Boot](https://github.com/u-boot/u-boot.git) components are used: + +Table: U-Boot components + +| Type | Path | +| --------- | ---------------------------------------------------------------------------------------------------------------- | +| 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}/meta-arm/meta-arm-bsp/recipes-bsp/u-boot/u-boot_2025.04.bb` | + +#### Linux {.reference} + +The distribution is based on the [Poky](https://docs.yoctoproject.org/ref-manual/terms.html#term-Poky) +distribution which is a Linux distribution stripped down to a minimal configuration. + +The provided distribution is based on [BusyBox](https://www.busybox.net/) and built using [musl libc](https://musl.libc.org/). + +The following Linux components are used: + +Table: Linux components + +| Type | Path | +| --------- | ---------------------------------------------------------------------------------------------------------------- | +| bbappend | `${WORKSPACE}/meta-arm/meta-arm-bsp/recipes-kernel/linux/linux-yocto_%.bbappend` | +| Recipe | `${WORKSPACE}/meta-arm/meta-arm-bsp/recipes-kernel/linux/linux-yocto_6.19.bb` | +| defconfig | `${WORKSPACE}/meta-arm/meta-arm-bsp/recipes-kernel/linux/files/corstone1000/defconfig` | + +### Secure enclave components {.reference} + +This section describes the secure enclave components. + +#### Trusted Firmware-M {.reference} + +The following [Trusted Firmware-M](https://git.trustedfirmware.org/TF-M/trusted-firmware-m.git) are used: + +Table: Trusted Firmware-M secure enclave components + +| Type | Path | +| --------- | ---------------------------------------------------------------------------------------------------------------- | +| 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_2.2.1.bb` | + +## Build {.reference} + +To build the software stack, do the following: + +:::note +Building binaries natively on Windows and AArch64 Linux is not supported. Use an Intel or AMD 64-bit architecture Linux based development machine to build the software stack and transfer the binaries to run the software stack on an FVP in Windows or AArch64 Linux if required. +::: + +1. Create a new folder that will be your workspace: + + ``` + mkdir ${WORKSPACE} + cd ${WORKSPACE} + ``` + +2. Install kas version 4.4 with `sudo` rights: + + ``` + sudo pip3 install kas==4.4 + ``` + + Ensure the kas installation directory is visible on the `$PATH` environment variable. + +3. Clone the `meta-arm` Yocto layer in the workspace `${WORKSPACE}`. + + ``` + cd ${WORKSPACE} + git clone https://git.yoctoproject.org/git/meta-arm -b CORSTONE1000-2025.12 + ``` + +4. Build a Corstone-1000 image: + + ``` + kas build meta-arm/kas/corstone1000-a320-fvp.yml:meta-arm/ci/debug.yml + ``` + +5. Accept the EULA on the [Arm Developer](https://developer.arm.com/downloads/-/arm-ecosystem-fvps/eula) site to build a Corstone-1000 image for FVP as follows: + + ``` + export ARM_FVP_EULA_ACCEPT="True" + ``` + +A clean build takes a significant amount of time given that all of the development machine utilities are also +built along with the target images. Those development machine utilities include executables (Python, +CMake, etc.) and the required toolchains. + +Once the build succeeds, all output binaries will be placed in `${WORKSPACE}/build/tmp/deploy/images/corstone1000-a320-fvp/`. + +Everything apart from the Secure Enclave ROM firmware is bundled into a single binary, the +`corstone1000-flash-firmware-image-corstone1000-a320-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-a320-fvp/trusted-firmware-m/bl1.bin` +- The internal firmware flash image: `${WORKSPACE}/build/tmp/deploy/images/corstone1000-a320-fvp/corstone1000-flash-firmware-image-corstone1000-a320-fvp.wic` + +## Build with SSH {.reference} + +The `meta-arm/kas/corstone1000-a320-fvp.yml` build produces an image for booting from flash. + +To build a bootable mass storage OS image with Dropbear SSH enabled, run: + +``` +kas build meta-arm/ci/corstone1000-a320-fvp.yml:meta-arm/kas/corstone1000-ssh.yml +``` + +The mass storage OS image can be found at `${WORKSPACE}/build/tmp/deploy/images/corstone1000-a320-fvp/core-image-minimal-corstone1000-a320-fvp.wic` + +:::note +The generated `core-image-minimal-corstone1000-a320-fvp.fvpconf` attaches the mass storage OS image to `board.msd_mmc.p_mmc_file`. +::: + + +## Run {.reference} + +Once the platform is turned ON, the Secure Enclave will start to boot, wherein the relevant memory contents of the `*.wic` +file are copied to their respective memory locations. Firewall policies are enforced +on memories and peripherals before bringing the Host Processor out of reset. + +The Host Processor will boot TrustedFirmware-A, OP-TEE, U-Boot and then Linux before presenting a login prompt. + +A Fixed Virtual Platform (FVP) model of the Corstone-1000 platform must be available to run the +Corstone-1000 FVP software image. + +A Yocto recipe is provided to download the latest supported FVP version. + +The recipe is located at `${WORKSPACE}/meta-arm/meta-arm/recipes-devtools/fvp/fvp-corstone1000-a320.bb`. + +The latest FVP version is `11.30.27` for Corstone-1000, and the model is automatically downloaded and installed when using the `runfvp` command as follows: + +``` +kas shell meta-arm/kas/corstone1000-a320-fvp.yml:meta-arm/ci/debug.yml \ +-c "../meta-arm/scripts/runfvp -- --version" +``` + +The FVP can also be manually downloaded from [Arm Developer](https://developer.arm.com/downloads/-/arm-ecosystem-fvps) to download the Corstone-1000 platform FVP installer. + +To set up the FVP: + +1. Run `tmux`: + + ``` + cd ${WORKSPACE} && tmux + ``` + +2. Run the FVP within `tmux`: + + ``` + kas shell meta-arm/kas/corstone1000-a320-fvp.yml:meta-arm/ci/debug.yml \ + -c "../meta-arm/scripts/runfvp --terminals=tmux" + ``` + + When the script is executed, three terminal instances will be launched: + + - one for the Secure Enclave processing element + - two for the Host processor processing element. + + ``` + corstone1000-a320-fvp login: + ``` + +3. Log in using the `root` username. + +## Security issue reporting {.reference} + +To report any security issues identified with Corstone-1000, please send an email to [psirt@arm.com](mailto:psirt@arm.com). diff --git a/meta-arm-bsp/documentation/requirements.txt b/meta-arm-bsp/documentation/requirements.txt index 4fc9b99b..38b4f577 100644 --- a/meta-arm-bsp/documentation/requirements.txt +++ b/meta-arm-bsp/documentation/requirements.txt @@ -7,5 +7,6 @@ jinja2==3.1.1 # Required to build the documentation sphinx==7.1.2 +myst-parser~=3.0.1 sphinx_rtd_theme~=3.0.0 docutils~=0.18.1