Commit 9f96f73d authored by Lakshmi Kailasanathan's avatar Lakshmi Kailasanathan
Browse files

Merge branch 'topics/tc0' into 'master'

totalcompute/tc0: update doc for TC0-2021.07.31 release

See merge request !1
parents a542c8b9 8b30411e
# Minimal makefile for Sphinx documentation
#
# You can set these variables from the command line, and also
# from the environment for the first two.
SPHINXOPTS ?=
SPHINXBUILD ?= sphinx-build
SOURCEDIR = .
BUILDDIR = _build
# Put it first so that "make" without argument is like "make help".
help:
@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
.PHONY: help Makefile
# Catch-all target: route all unknown targets to Sphinx using the new
# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS).
%: Makefile
@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
# 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.
#
# import os
# import sys
# sys.path.insert(0, os.path.abspath('.'))
# -- Project information -----------------------------------------------------
project = 'Arm reference solutions'
copyright = '2020-2021, Arm'
author = 'Avinash Mehta'
# -- 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 = [
]
# 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']
# -- 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'
# 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']
.. _docs/infra/readme:
Neoverse Reference Design Platform Software
===========================================
......
.. _docs/totalcompute/readme:
.. section-numbering::
:suffix: .
Total Compute Platform
----------------------
Total Compute is an approach to moving beyond optimizing individual IP to take a system-level solution view of the SoC that puts use cases and experiences at the heart of the designs.
Total Compute focuses on optimizing Performance, Security, and Developer Access across Arm’s IP, software, and tools. This means higher-performing, more immersive, and more secure experiences on devices coupled with an easier app and software development process.
TC Software Stack Overview
--------------------------
The TC0 software consists of firmware, kernel and file system components that can run on the associated FVP.
Following are the Software components:
#. SCP firmware – System initialization, Clock and Power control
#. AP firmware – Arm Trusted firmware
#. Secure Partition Manager
#. Secure Partitions
* OP-TEE Trusted OS
* Trusted Services with Shim layer
#. U-Boot – loads and verifies the fitImage for poky boot, containing kernel and filesystem or boot Image for Android Verified Boot, containing kernel and ramdisk.
#. Kernel – supports the following hardware features
* Mailbox hardware unit
* PAC/MTE/BTI features
#. Android
* Supports PAC/MTE/BTI features
.. figure:: tc0_sw_stack.png
:alt: Total Compute Software Stack
:ref:`Total Compute Platform Software Components <docs/totalcompute/sw_stack>`
Further Details
---------------
More details on building the TC0 software stack can be found below
#. :ref:`user-guide <docs/totalcompute/tc0/user-guide>`
#. :ref:`change-log <docs/totalcompute/tc0/change-log>`
#. :ref:`release_notes <docs/totalcompute/tc0/release_notes>`
.. _docs/totalcompute/sw_stack:
.. section-numbering::
:suffix: .
Total Compute Platform Software Components
==========================================
SCP Firmware
------------
The System Control Processor (SCP) is a compute unit of Total Compute and is responsible for low-level system management. The SCP is a Cortex-M3 processor with a set of dedicated peripherals and interfaces that you can extend.
SCP firmware supports:
#. Powerup sequence and system start-up
#. Initial hardware configuration
#. Clock management
#. Servicing power state requests from the OS Power Management (OSPM) software
SCP Boot ROM
............
SCP Boot ROM code is the first software that executes right after a cold reset or Power-on.
It performs the following functions:
#. Sets up generic timer, UART console and clocks
#. Initializes the Coherent Interconnect
#. Powers ON primary AP CPU
#. Loads SCP Runtime Firmware
SCP Runtime Firmware
....................
SCP runtime code starts execution after TF-A BL2 has authenticated and copied it from flash.
It performs the following functions:
#. Responds to SCMI messages via MHUv2 for CPU power control and DVFS
#. Power Domain management
#. Clock management
Secure Software
---------------
Secure software/firmware is a trusted software component that runs in the AP secure world. It mainly consists of AP firmware, Secure Partition Manager and Secure Partitions (OP-TEE, Trusted Services).
AP firmware
...........
The AP firmware consists of the code that is required to boot Total Compute platform up the point where the OS execution starts. This firmware performs architecture and platform initialization. It also loads and initializes secure world images like Secure partition manager and Trusted OS.
Arm Trusted firmware BL1
++++++++++++++++++++++++
AP Trusted ROM contains an on-chip trusted ROM that runs the boot code on Total Compute platform. BL1 performs minimal architectural initialization (like exception vectors, CPU initialization) and Platform initialization. It loads the BL2 image and passes control to it.
Arm Trusted firmware BL2
++++++++++++++++++++++++
BL2 runs at S-EL1 and performs architectural initialization required for subsequent stages of TF-A and normal world software. It configures the TrustZone Controller and carves out memory region in DRAM for secure and non-secure use. BL2 loads below images:
#. SCP BL2 image
#. EL3 Runtime Software (BL31 image)
#. Secure Partition Manager (BL32 image)
#. Non-Trusted firmware - U-boot (BL33 image)
#. Secure Partitions images (OP-TEE and Trusted Services)
Arm Trusted firmware BL31
+++++++++++++++++++++++++
BL2 loads EL3 Runtime Software (BL31) and BL1 passes control to BL31 at EL3. In Total Compute BL31 runs at trusted SRAM. It provides below mentioned runtime services:
#. Power State Coordination Interface (PSCI)
#. Secure Monitor framework
#. Secure Partition Manager Dispatcher
Secure Partition Manager
........................
Total Compute enables FEAT S-EL2 architectural extension, and it uses Hafnium as Secure Partition Manager Core (SPMC). BL32 option in TF-A is re-purposed to specify the SPMC image. The SPMC component runs at S-EL2 exception level.
Secure Partitions
.................
Software image isolated using SPM is Secure Partition. Total Compute enables OP-TEE and Trusted Services (crypto, secure storage) as Secure Partitions.
OP-TEE
++++++
OP-TEE Trusted OS is virtualized using Hafnium at S-EL2. OP-TEE OS for Total Compute is built with FFA and SEL2 SPMC support. This enables OP-TEE as a Secure Partition running in an isolated address space managed by Hafnium. The OP-TEE kernel runs at S-EL1 with Trusted applications running at S-EL0.
Trusted Services
++++++++++++++++
Trusted Services like Crypto Service and Secure Storage runs as S-EL0 Secure Partitions using a Shim layer at S-EL1. Crypto Service along with S-EL1 Shim layer is built as a single image. The Shim layer forwards FF-A calls from S-EL0 to S-EL2.
U-Boot
------
TF-A BL31 passes execution control to U-boot bootloader (BL33). U-boot in Total Compute has support for multiple image formats:
#. FitImage format: this contains the Linux kernel and poky ramdisk which are authenticated and loaded in their respective positions in DRAM and execution is handed off to the kernel.
#. Android boot image: This contains the Linux kernel and Android ramdisk. If using Android Verified Boot (AVB) boot.img is loaded from MMC to DRAM, authenticated and then execution is handed off to the kernel.
Kernel
------
Linux Kernel in Total Compute contains the subsystem-specific features that demonstrate the capabilities of Total Compute. Apart from default configuration, it enables:
#. Arm MHUv2 controller driver
#. Arm FF-A driver
#. OP-TEE driver with FF-A Transport Support
#. Arm FF-A user space interface driver
Android
-------
Total Compute has support for Android Open-Source Project (AOSP), which contains the Android framework, Native Libraries, Android Runtime and the Hardware Abstraction Layers (HALs) for Android Operating system.
The Total Compute device profile defines the required variables for Android such as partition size and product packages and has support for 2 different configurations of Android:
#. Nano: This is a stripped-down version to provide the bare minimum for Android Runtime and boot Android to console. It does not have Android UI support.
#. Software rendering: This profile has support for Android UI and boots Android to home screen. It uses SwiftShader to achieve this. Swiftshader is a CPU base implementation of the Vulkan graphics API by Google.
.. _docs/totalcompute/tc0/change-log:
Change Log
==========
.. contents::
This document contains a summary of the new features, changes and
fixes in each release of TC0 software stack.
Version 2021.07.31
------------------
Features added
~~~~~~~~~~~~~~
- Memory Tagging Extension (MTE)
- Pointer Authentication Code (PAC)
- Branch Target Identification (BTI)
Changes
~~~~~~~
- Updated Android AOSP to master (May21)
- Updated Android Common Kernel to v5.10
- Updated Trusted Firmware-A & Hafnium to v2.5
- Updated OP-TEE to v3.14.0
- Updated SCP firmware to v2.8
- Updated U-boot to v2021.07
- Updated Yocto to master
Version 2021.04.23
------------------
......
Release notes - 2021.04.23
.. _docs/totalcompute/tc0/release_notes:
Release notes - 2021.07.31
==========================
.. section-numbering::
:suffix: .
.. contents::
Release tag
-----------
The manifest tag for this release is TC0-2021.04.23
The manifest tag for this release is TC0-2021.07.31
Components
----------
......@@ -19,6 +17,7 @@ The following is a summary of the key software features of the release:
- U-Boot bootloader.
- Hafnium for S-EL2 Secure Partition Manager core.
- OP-TEE for Trusted Execution Environment (TEE).
- Crypto and Storage Trusted Services running at S-EL0.
Hardware Features
-----------------
......@@ -33,37 +32,38 @@ Hardware Features
Software Features
-----------------
- Poky Distribution support.
- Android R/11 Support.
- Android Common Kernel 5.4.
- Trusted Firmware-A.
- Android AOSP Support (May21).
- Android Common Kernel 5.10 with PAC/BTI/MTE
- Trusted Firmware-A & Hafnium v2.5
- OP-TEE 3.14.0
- Support secure boot based on TBBR specification https://developer.arm.com/documentation/den0006/latest
- System Control Processor firmware.
- Yocto based build system.
- U-Boot bootloader.
- System Control Processor (SCP) firmware v2.8
- Build system based on Yocto master
- U-Boot bootloader v2021.07
- Power management features: cpufreq and cpuidle.
- SCMI (System Control and Management Interface) support.
- Verified u-boot for authenticating fit image (containing kernel + ramdisk) during poky boot.
- Android Verified Boot (AVB) for authenticating boot and system image during Android boot.
- Software rendering on Android with DRM Hardware Composer offloading composition to Mali D71 DPU.
- Hafnium as Secure Partition Manager (SPM) at S-EL2.
- Trusted OS OP-TEE as Secure Partition at S-EL1, managed by S-EL2 SPMC (Hafnium)
- Arm FF-A driver and FF-A Transport support for OP-TEE driver in Android Common Kernel. This is an experimental feature.
- OP-TEE as Secure Partition at S-EL1, managed by S-EL2 SPMC (Hafnium)
- Arm FF-A driver and FF-A Transport support for OP-TEE driver in Android Common Kernel.
- OP-TEE Support in Poky distribution. This includes OP-TEE client and OP-TEE test suite.
- Crypto and Storage Trusted Services running at S-EL0.
- Trusted Services test suite added to poky distribution.
- Shim Layer at S-EL1 running on top of S-EL2 SPMC (Hafnium).
- Shim Layer at S-EL1 running on top of S-EL2 SPMC (Hafnium) used by Trusted Services running in S-EL0.
Platform Support
----------------
- This Software release is tested on TC0 Fast Model platform (FVP).
- Supported Fast model version for this release is 11.14.32
- Supported Fast model version for this release is 11.15.20
Known issues or Limitations
---------------------------
1. At the U-Boot prompt press enter and type "boot" to continue booting else wait
for ~15 secs for boot to continue automatically.This is because of the time
differrence in CPU frequency and FVP operating frequency.
2. OPTEE Test (xtest) sometimes throw some failures ,issue is under investigation.
for ~15 secs for boot to continue automatically. This is because of the time
difference in CPU frequency and FVP operating frequency.
2. OP-TEE test suite xtest, fails for Storage concurrency test case. This issue is under investigation.
Support
......
.. _docs/totalcompute/tc0/user-guide:
User Guide
==========
.. section-numbering::
:suffix: .
.. contents::
......@@ -74,7 +72,7 @@ in these instructions.
mkdir <tc0_workspace>
cd <tc0_workspace>
export TC0_RELEASE=refs/tags/TC0-2021.04.23
export TC0_RELEASE=refs/tags/TC0-2021.07.31
To sync BSP only without Android, run the repo command.
......@@ -247,18 +245,17 @@ S-EL0 trusted-services
Based on `Trusted Services <https://www.trustedfirmware.org/projects/trusted-services/>`__
+--------+------------------------------------------------------------------------------------------------------+
| Recipe | <tc0_workspace>/bsp/layers/meta-arm/meta-arm/recipes-security/trusted-services/secure-storage_git.bb |
| | <tc0_workspace>/bsp/layers/meta-arm/meta-arm/recipes-security/trusted-services/crypto-sp_git.bb |
+--------+------------------------------------------------------------------------------------------------------+
| Files | * <tc0_workspace>/bsp/build-poky/tmp-poky/deploy/images/tc0/firmware/crypto-sp.bin |
| | * <tc0_workspace>/bsp/build-poky/tmp-poky/deploy/images/tc0/firmware/secure-storage.bin |
+--------+------------------------------------------------------------------------------------------------------+
+--------+-----------------------------------------------------------------------------------------------+
| Recipe | <tc0_workspace>/bsp/layers/meta-tc/recipes-security/trusted-services/secure-partitions_git.bb |
+--------+-----------------------------------------------------------------------------------------------+
| Files | * <tc0_workspace>/bsp/build-poky/tmp-poky/deploy/images/tc0/firmware/crypto-sp.bin |
| | * <tc0_workspace>/bsp/build-poky/tmp-poky/deploy/images/tc0/firmware/secure-storage.bin |
+--------+-----------------------------------------------------------------------------------------------+
Linux
*****
The recipe responsible for building a 5.4 version of the Android Common kernel (`ACK <https://android.googlesource.com/kernel/common/>`__).
The recipe responsible for building a 5.10 version of the Android Common kernel (`ACK <https://android.googlesource.com/kernel/common/>`__).
+--------+-----------------------------------------------------------------------------------------------+
| Recipe | <tc0_workspace>/bsp/layers/meta-arm/meta-arm-bsp/recipes-kernel/linux/linux-arm-platforms.inc |
......@@ -273,11 +270,11 @@ Poky Linux distro
The layer is based on the `poky <https://www.yoctoproject.org/software-item/poky/>`__ Linux distribution.
The provided distribution is based on BusyBox and built using glibc.
+--------+---------------------------------------------------------------------------------------------------+
| Recipe | <tc0_workspace>/bsp/layers/openembedded-core/meta/recipes-core/images/core-image-minimal.bb |
+--------+---------------------------------------------------------------------------------------------------+
| Files | * <tc0_workspace>/bsp/build-poky/tmp-poky/deploy/images/tc0/fitImage-core-image-minimal-tc0-tc0 |
+--------+---------------------------------------------------------------------------------------------------+
+--------+-------------------------------------------------------------------------------------------------+
| Recipe | <tc0_workspace>/bsp/layers/openembedded-core/meta/recipes-core/images/core-image-minimal.bb |
+--------+-------------------------------------------------------------------------------------------------+
| Files | * <tc0_workspace>/bsp/build-poky/tmp-poky/deploy/images/tc0/fitImage-core-image-minimal-tc0-tc0 |
+--------+-------------------------------------------------------------------------------------------------+
Android
......
Welcome to Arm reference solutions documentation!
===================================================
.. toctree::
:maxdepth: 2
:caption: Infra:
docs/infra/readme
.. toctree::
:maxdepth: 2
:caption: Total Compute:
docs/totalcompute/readme
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment