diff options
| author | Alistair Delva <adelva@google.com> | 2021-02-16 21:01:22 +0000 |
|---|---|---|
| committer | Automerger Merge Worker <android-build-automerger-merge-worker@system.gserviceaccount.com> | 2021-02-16 21:01:22 +0000 |
| commit | efb2826bb8160e2d8e0fcec85133a7468484f9fd (patch) | |
| tree | 37a21c69306801ee7cdda5167a30896c8740155b /docs | |
| parent | b00a71fc312c9781fa6f404dccfb55b062b2ccac (diff) | |
| parent | faa476c0caaa598afa5a6109d17102db5fe35ec6 (diff) | |
| download | platform_external_arm-trusted-firmware-master.tar.gz platform_external_arm-trusted-firmware-master.tar.bz2 platform_external_arm-trusted-firmware-master.zip | |
Merge branch 'aosp/upstream-master' into HEAD am: faa476c0caHEADandroid-s-beta-5android-s-beta-4android-s-beta-3android-s-beta-2android-s-beta-1mastermain-cg-testing-releaseandroid-s-beta-5android-s-beta-4
Original change: https://android-review.googlesource.com/c/platform/external/arm-trusted-firmware/+/1589611
MUST ONLY BE SUBMITTED BY AUTOMERGER
Change-Id: I3a25534ceed4f8e188510641080d8b8ed49b8f62
Diffstat (limited to 'docs')
92 files changed, 7098 insertions, 1256 deletions
diff --git a/docs/Makefile b/docs/Makefile index eed3a0815..3dd7ebc4d 100644 --- a/docs/Makefile +++ b/docs/Makefile @@ -1,5 +1,5 @@ # -# Copyright (c) 2019, ARM Limited. All rights reserved. +# Copyright (c) 2019-2020, ARM Limited. All rights reserved. # # SPDX-License-Identifier: BSD-3-Clause # @@ -7,7 +7,7 @@ # # You can set these variables from the command line. -SPHINXOPTS = +SPHINXOPTS = -W SPHINXBUILD = sphinx-build SPHINXPROJ = TrustedFirmware-A SOURCEDIR = . diff --git a/docs/about/contact.rst b/docs/about/contact.rst index 9cb25ef47..4440a371a 100644 --- a/docs/about/contact.rst +++ b/docs/about/contact.rst @@ -24,12 +24,21 @@ The relevant lists for the TF-A project are: You can see a `summary of all the lists`_ on the TrustedFirmware.org website. +Open Tech Forum Call +^^^^^^^^^^^^^^^^^^^^ + +Every other week, we organize a call with all interested TF-A contributors. +Anyone is welcome to join. This is an opportunity to discuss any technical +topic within the community. More details can be found `here`_. + +.. _here: https://www.trustedfirmware.org/meetings/tf-a-technical-forum/ + Issue Tracker ^^^^^^^^^^^^^ -Specific issues may be raised using the `issue tracker`_ on the -TrustedFirmware.org website. Using this tracker makes it easy for the -maintainers to prioritise and respond to your ticket. +Bug reports may be filed on the `issue tracker`_ on the TrustedFirmware.org +website. Using this tracker gives everyone visibility of the known issues in +TF-A. Arm Licensees ^^^^^^^^^^^^^ @@ -44,4 +53,4 @@ via their partner managers. -------------- -*Copyright (c) 2019, Arm Limited. All rights reserved.* +*Copyright (c) 2019-2020, Arm Limited. All rights reserved.* diff --git a/docs/about/features.rst b/docs/about/features.rst index 3441c5ebe..964cb2570 100644 --- a/docs/about/features.rst +++ b/docs/about/features.rst @@ -73,6 +73,8 @@ Current features to be configured at runtime if required by the platform. It also enables loading of a hardware configuration (for example, a kernel device tree) as part of the FIP, to be passed through the firmware stages. + This feature is now incorporated inside the firmware configuration framework + (fconf), which is still flagged as experimental. - Support for alternative boot flows, for example to support platforms where the EL3 Runtime Software is loaded using other firmware or a separate @@ -86,8 +88,8 @@ Current features in ROM but is accessed through a jump-table that may be stored in read-write memory, allowing for the library code to be patched. -- A prototype implementation of a Secure Partition Manager (SPM) that is based - on the SPCI Alpha 1 and SPRT draft specifications. +- Support for the Secure Partition Manager Dispatcher (SPMD) component as a + new standard service. - Support for ARMv8.3 pointer authentication in the normal and secure worlds. The use of pointer authentication in the normal world is enabled whenever @@ -96,8 +98,8 @@ Current features experimental configuration at this time and requires the ``BRANCH_PROTECTION`` option to be set to non-zero. -- Position-Independent Executable (PIE) support. Initially for BL31 only, with - further support to be added in a future release. +- Position-Independent Executable (PIE) support. Currently for BL2, BL31, and + TSP, with further support to be added in a future release. Still to come ------------- @@ -106,8 +108,8 @@ Still to come - Refinements to Position Independent Executable (PIE) support. -- Continued support for the draft SPCI specification, to enable the use of - secure partition management in the secure world. +- Continued support for the PSA FF-A v1.0 (formally known as SPCI) specification, to enable the + use of secure partition management in the secure world. - Documentation enhancements. @@ -117,11 +119,11 @@ Still to come - Ongoing security hardening, optimization and quality improvements. -.. _SMC Calling Convention: http://infocenter.arm.com/help/topic/com.arm.doc.den0028b/ARM_DEN0028B_SMC_Calling_Convention.pdf +.. _SMC Calling Convention: https://developer.arm.com/docs/den0028/latest .. _OP-TEE Secure OS: https://github.com/OP-TEE/optee_os .. _NVIDIA Trusted Little Kernel: http://nv-tegra.nvidia.com/gitweb/?p=3rdparty/ote_partner/tlk.git;a=summary .. _Trusty Secure OS: https://source.android.com/security/trusty -------------- -*Copyright (c) 2019, Arm Limited. All rights reserved.* +*Copyright (c) 2019-2020, Arm Limited. All rights reserved.* diff --git a/docs/about/maintainers.rst b/docs/about/maintainers.rst index d9d7f84fd..14a3b45e3 100644 --- a/docs/about/maintainers.rst +++ b/docs/about/maintainers.rst @@ -1,24 +1,28 @@ -Maintainers -=========== +Project Maintenance +=================== -Trusted Firmware-A (TF-A) is an Arm maintained project. All contributions are -ultimately merged by the maintainers listed below. Technical ownership of some -parts of the codebase is delegated to the sub-maintainers listed below. An -acknowledgement from these sub-maintainers may be required before the +Trusted Firmware-A (TF-A) is an open governance community project. All +contributions are ultimately merged by the maintainers listed below. Technical +ownership of most parts of the codebase falls on the code owners listed +below. An acknowledgement from these code owners is required before the maintainers merge a contribution. -Main maintainers ----------------- +More details may be found in the `Project Maintenance Process`_ document. + + +.. _maintainers: + +Maintainers +----------- + :M: Dan Handley <dan.handley@arm.com> :G: `danh-arm`_ :M: Soby Mathew <soby.mathew@arm.com> :G: `soby-mathew`_ :M: Sandrine Bailleux <sandrine.bailleux@arm.com> :G: `sandrine-bailleux-arm`_ -:M: Alexei Fedorov <alexei.fedorov@arm.com> +:M: Alexei Fedorov <Alexei.Fedorov@arm.com> :G: `AlexeiFedorov`_ -:M: György Szing <gyorgy.szing@arm.com> -:G: `gyuri-szing`_ :M: Manish Pandey <manish.pandey2@arm.com> :G: `manish-pandey-arm`_ :M: Mark Dykes <mark.dykes@arm.com> @@ -29,9 +33,282 @@ Main maintainers :G: `bipinravi-arm`_ :M: Joanna Farley <joanna.farley@arm.com> :G: `joannafarley-arm`_ +:M: Julius Werner <jwerner@chromium.org> +:G: `jwerner-chromium`_ +:M: Varun Wadekar <vwadekar@nvidia.com> +:G: `vwadekar`_ +:M: Andre Przywara <andre.przywara@arm.com> +:G: `Andre-ARM`_ +:M: Lauren Wehrmeister <Lauren.Wehrmeister@arm.com> +:G: `laurenw-arm`_ +:M: Madhukar Pappireddy <Madhukar.Pappireddy@arm.com> +:G: `madhukar-Arm`_ +:M: Raghu Krishnamurthy <raghu.ncstate@icloud.com> +:G: `raghuncstate`_ + + +.. _code owners: + +Code owners +----------- + +Core Code +~~~~~~~~~ + +Armv7-A architecture port +^^^^^^^^^^^^^^^^^^^^^^^^^ +:M: Etienne Carriere <etienne.carriere@linaro.org> +:G: `etienne-lms`_ + +Build Definitions for CMake Build System +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +:M: Javier Almansa Sobrino <Javier.AlmansaSobrino@arm.com> +:G: `javieralso-arm`_ +:M: Chris Kay <chris.kay@arm.com> +:G: `CJkay`_ +:F: / + +Software Delegated Exception Interface (SDEI) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +:M: Mark Dykes <mark.dykes@arm.com> +:G: `mardyk01`_ +:M: John Powell <John.Powell@arm.com> +:G: `john-powell-arm`_ +:F: services/std_svc/sdei/ + +Trusted Boot +^^^^^^^^^^^^ +:M: Sandrine Bailleux <sandrine.bailleux@arm.com> +:G: `sandrine-bailleux-arm`_ +:M: Manish Pandey <manish.pandey2@arm.com> +:G: `manish-pandey-arm`_ +:M: Manish Badarkhe <manish.badarkhe@arm.com> +:G: `ManishVB-Arm`_ +:F: drivers/auth/ + +Secure Partition Manager (SPM) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +:M: Olivier Deprez <olivier.deprez@arm.com> +:G: `odeprez`_ +:M: Manish Pandey <manish.pandey2@arm.com> +:G: `manish-pandey-arm`_ +:M: Maksims Svecovs <maksims.svecovs@arm.com> +:G: `max-shvetsov`_ +:M: Joao Alves <Joao.Alves@arm.com> +:G: `J-Alves`_ +:F: services/std_svc/spm\* + +Exception Handling Framework (EHF) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +:M: Manish Badarkhe <manish.badarkhe@arm.com> +:G: `ManishVB-Arm`_ +:M: John Powell <John.Powell@arm.com> +:G: `john-powell-arm`_ +:F: bl31/ehf.c + + +Drivers, Libraries and Framework Code +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Console API framework +^^^^^^^^^^^^^^^^^^^^^ +:M: Julius Werner <jwerner@chromium.org> +:G: `jwerner-chromium`_ +:F: drivers/console/ +:F: include/drivers/console.h +:F: plat/common/aarch64/crash_console_helpers.S + +coreboot support libraries +^^^^^^^^^^^^^^^^^^^^^^^^^^ +:M: Julius Werner <jwerner@chromium.org> +:G: `jwerner-chromium`_ +:F: drivers/coreboot/ +:F: include/drivers/coreboot/ +:F: include/lib/coreboot.h +:F: lib/coreboot/ + +eMMC/UFS drivers +^^^^^^^^^^^^^^^^ +:M: Haojian Zhuang <haojian.zhuang@linaro.org> +:G: `hzhuang1`_ +:F: drivers/partition/ +:F: drivers/synopsys/emmc/ +:F: drivers/synopsys/ufs/ +:F: drivers/ufs/ +:F: include/drivers/dw_ufs.h +:F: include/drivers/ufs.h +:F: include/drivers/synopsys/dw_mmc.h + +Power State Coordination Interface (PSCI) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +:M: Javier Almansa Sobrino <Javier.AlmansaSobrino@arm.com> +:G: `javieralso-arm`_ +:M: Madhukar Pappireddy <Madhukar.Pappireddy@arm.com> +:G: `madhukar-Arm`_ +:M: Lauren Wehrmeister <Lauren.Wehrmeister@arm.com> +:G: `laurenw-arm`_ +:M: Zelalem Aweke <Zelalem.Aweke@arm.com> +:G: `zelalem-aweke`_ +:F: lib/psci/ + +DebugFS +^^^^^^^ +:M: Olivier Deprez <olivier.deprez@arm.com> +:G: `odeprez`_ +:F: lib/debugfs/ + +Firmware Configuration Framework (FCONF) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +:M: Madhukar Pappireddy <Madhukar.Pappireddy@arm.com> +:G: `madhukar-Arm`_ +:M: Manish Badarkhe <manish.badarkhe@arm.com> +:G: `ManishVB-Arm`_ +:M: Lauren Wehrmeister <Lauren.Wehrmeister@arm.com> +:G: `laurenw-arm`_ +:F: lib/fconf/ + +Performance Measurement Framework (PMF) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +:M: Joao Alves <Joao.Alves@arm.com> +:G: `J-Alves`_ +:M: Jimmy Brisson <Jimmy.Brisson@arm.com> +:G: `theotherjimmy`_ +:F: lib/pmf/ + +Arm CPU libraries +^^^^^^^^^^^^^^^^^ +:M: Lauren Wehrmeister <Lauren.Wehrmeister@arm.com> +:G: `laurenw-arm`_ +:M: John Powell <John.Powell@arm.com> +:G: `john-powell-arm`_ +:F: lib/cpus/ + +Reliability Availability Serviceabilty (RAS) framework +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +:M: Olivier Deprez <olivier.deprez@arm.com> +:G: `odeprez`_ +:M: Manish Pandey <manish.pandey2@arm.com> +:G: `manish-pandey-arm`_ +:F: lib/extensions/ras/ + +Activity Monitors Unit (AMU) extensions +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +:M: Alexei Fedorov <Alexei.Fedorov@arm.com> +:G: `AlexeiFedorov`_ +:F: lib/extensions/amu/ + +Memory Partitioning And Monitoring (MPAM) extensions +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +:M: Zelalem Aweke <Zelalem.Aweke@arm.com> +:G: `zelalem-aweke`_ +:M: Jimmy Brisson <Jimmy.Brisson@arm.com> +:G: `theotherjimmy`_ +:F: lib/extensions/mpam/ + +Pointer Authentication (PAuth) and Branch Target Identification (BTI) extensions +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +:M: Alexei Fedorov <Alexei.Fedorov@arm.com> +:G: `AlexeiFedorov`_ +:M: Zelalem Aweke <Zelalem.Aweke@arm.com> +:G: `zelalem-aweke`_ +:F: lib/extensions/pauth/ + +Statistical Profiling Extension (SPE) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +:M: Zelalem Aweke <Zelalem.Aweke@arm.com> +:G: `zelalem-aweke`_ +:M: Jimmy Brisson <Jimmy.Brisson@arm.com> +:G: `theotherjimmy`_ +:F: lib/extensions/spe/ + +Scalable Vector Extension (SVE) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +:M: Jimmy Brisson <Jimmy.Brisson@arm.com> +:G: `theotherjimmy`_ +:F: lib/extensions/sve/ + +Standard C library +^^^^^^^^^^^^^^^^^^ +:M: Alexei Fedorov <Alexei.Fedorov@arm.com> +:G: `AlexeiFedorov`_ +:M: John Powell <John.Powell@arm.com> +:G: `john-powell-arm`_ +:F: lib/libc/ + +Library At ROM (ROMlib) +^^^^^^^^^^^^^^^^^^^^^^^ +:M: Madhukar Pappireddy <Madhukar.Pappireddy@arm.com> +:G: `madhukar-Arm`_ +:F: lib/romlib/ + +Translation tables (``xlat_tables``) library +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +:M: Javier Almansa Sobrino <Javier.AlmansaSobrino@arm.com> +:G: `javieralso-arm`_ +:M: Joao Alves <Joao.Alves@arm.com> +:G: `J-Alves`_ +:F: lib/xlat\_tables_\*/ + +IO abstraction layer +^^^^^^^^^^^^^^^^^^^^ +:M: Manish Pandey <manish.pandey2@arm.com> +:G: `manish-pandey-arm`_ +:M: Olivier Deprez <olivier.deprez@arm.com> +:G: `odeprez`_ +:F: drivers/io/ + +GIC driver +^^^^^^^^^^ +:M: Alexei Fedorov <Alexei.Fedorov@arm.com> +:G: `AlexeiFedorov`_ +:M: Manish Pandey <manish.pandey2@arm.com> +:G: `manish-pandey-arm`_ +:M: Madhukar Pappireddy <Madhukar.Pappireddy@arm.com> +:G: `madhukar-Arm`_ +:M: Olivier Deprez <olivier.deprez@arm.com> +:G: `odeprez`_ +:F: drivers/arm/gic/ + +Libfdt wrappers +^^^^^^^^^^^^^^^ +:M: Madhukar Pappireddy <Madhukar.Pappireddy@arm.com> +:G: `madhukar-Arm`_ +:M: Manish Badarkhe <manish.badarkhe@arm.com> +:G: `ManishVB-Arm`_ +:F: common/fdt_wrappers.c + +Firmware Encryption Framework +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +:M: Sumit Garg <sumit.garg@linaro.org> +:G: `b49020`_ +:F: drivers/io/io_encrypted.c +:F: include/drivers/io/io_encrypted.h +:F: include/tools_share/firmware_encrypted.h + +Measured Boot +^^^^^^^^^^^^^ +:M: Alexei Fedorov <Alexei.Fedorov@arm.com> +:G: `AlexeiFedorov`_ +:M: Javier Almansa Sobrino <Javier.AlmansaSobrino@arm.com> +:G: `javieralso-arm`_ +:F: drivers/measured_boot +:F: include/drivers/measured_boot +:F: plat/arm/board/fvp/fvp_measured_boot.c + +System Control and Management Interface (SCMI) Server +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +:M: Etienne Carriere <etienne.carriere@st.com> +:G: `etienne-lms`_ +:M: Peng Fan <peng.fan@nxp.com> +:G: `MrVan`_ +:F: drivers/scmi-msg +:F: include/drivers/scmi\* + +Platform Ports +~~~~~~~~~~~~~~ Allwinner ARMv8 platform port ------------------------------ +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ :M: Andre Przywara <andre.przywara@arm.com> :G: `Andre-ARM`_ :M: Samuel Holland <samuel@sholland.org> @@ -41,7 +318,7 @@ Allwinner ARMv8 platform port :F: drivers/allwinner/ Amlogic Meson S905 (GXBB) platform port ---------------------------------------- +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ :M: Andre Przywara <andre.przywara@arm.com> :G: `Andre-ARM`_ :F: docs/plat/meson-gxbb.rst @@ -49,28 +326,36 @@ Amlogic Meson S905 (GXBB) platform port :F: plat/amlogic/gxbb/ Amlogic Meson S905x (GXL) platform port ---------------------------------------- +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ :M: Remi Pommarel <repk@triplefau.lt> :G: `remi-triplefault`_ :F: docs/plat/meson-gxl.rst -:F: drivers/amlogic/gxl :F: plat/amlogic/gxl/ Amlogic Meson S905X2 (G12A) platform port ------------------------------------------ +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ :M: Carlo Caione <ccaione@baylibre.com> :G: `carlocaione`_ :F: docs/plat/meson-g12a.rst -:F: drivers/amlogic/g12a :F: plat/amlogic/g12a/ -Armv7-A architecture port -------------------------- -:M: Etienne Carriere <etienne.carriere@linaro.org> -:G: `etienne-lms`_ +Amlogic Meson A113D (AXG) platform port +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +:M: Carlo Caione <ccaione@baylibre.com> +:G: `carlocaione`_ +:F: docs/plat/meson-axg.rst +:F: plat/amlogic/axg/ + +Arm FPGA platform port +^^^^^^^^^^^^^^^^^^^^^^ +:M: Andre Przywara <andre.przywara@arm.com> +:G: `Andre-ARM`_ +:M: Javier Almansa Sobrino <Javier.AlmansaSobrino@arm.com> +:G: `javieralso-arm`_ +:F: plat/arm/board/arm_fpga Arm System Guidance for Infrastructure / Mobile FVP platforms -------------------------------------------------------------- +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ :M: Nariman Poushin <nariman.poushin@linaro.org> :G: `npoushin`_ :M: Thomas Abraham <thomas.abraham@arm.com> @@ -80,37 +365,8 @@ Arm System Guidance for Infrastructure / Mobile FVP platforms :F: plat/arm/board/sgi575/ :F: plat/arm/board/sgm775/ -Console API framework ---------------------- -:M: Julius Werner <jwerner@chromium.org> -:G: `jwerner-chromium`_ -:F: drivers/console/ -:F: include/drivers/console.h -:F: plat/common/aarch64/crash_console_helpers.S - -coreboot support libraries --------------------------- -:M: Julius Werner <jwerner@chromium.org> -:G: `jwerner-chromium`_ -:F: drivers/coreboot/ -:F: include/drivers/coreboot/ -:F: include/lib/coreboot.h -:F: lib/coreboot/ - -eMMC/UFS drivers ----------------- -:M: Haojian Zhuang <haojian.zhuang@linaro.org> -:G: `hzhuang1`_ -:F: drivers/partition/ -:F: drivers/synopsys/emmc/ -:F: drivers/synopsys/ufs/ -:F: drivers/ufs/ -:F: include/drivers/dw_ufs.h -:F: include/drivers/ufs.h -:F: include/drivers/synopsys/dw_mmc.h - HiSilicon HiKey and HiKey960 platform ports -------------------------------------------- +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ :M: Haojian Zhuang <haojian.zhuang@linaro.org> :G: `hzhuang1`_ :F: docs/plat/hikey.rst @@ -119,14 +375,14 @@ HiSilicon HiKey and HiKey960 platform ports :F: plat/hisilicon/hikey960/ HiSilicon Poplar platform port ------------------------------- +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ :M: Shawn Guo <shawn.guo@linaro.org> :G: `shawnguo2`_ :F: docs/plat/poplar.rst :F: plat/hisilicon/poplar/ Intel SocFPGA platform ports ----------------------------- +^^^^^^^^^^^^^^^^^^^^^^^^^^^^ :M: Tien Hock Loh <tien.hock.loh@intel.com> :G: `thloh85-intel`_ :M: Hadi Asyrafi <muhammad.hadi.asyrafi.abdul.halim@intel.com> @@ -135,22 +391,22 @@ Intel SocFPGA platform ports :F: drivers/intel/soc/ MediaTek platform ports ------------------------ +^^^^^^^^^^^^^^^^^^^^^^^ :M: Yidi Lin (林以廸) <yidi.lin@mediatek.com> :G: `mtk09422`_ :F: plat/mediatek/ Marvell platform ports and SoC drivers --------------------------------------- +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ :M: Konstantin Porotchkin <kostap@marvell.com> :G: `kostapr`_ -:F: docs/marvell/ +:F: docs/plat/marvell/ :F: plat/marvell/ :F: drivers/marvell/ :F: tools/marvell/ NVidia platform ports ---------------------- +^^^^^^^^^^^^^^^^^^^^^ :M: Varun Wadekar <vwadekar@nvidia.com> :G: `vwadekar`_ :F: docs/plat/nvidia-tegra.rst @@ -159,14 +415,14 @@ NVidia platform ports :F: plat/nvidia/ NXP QorIQ Layerscape platform ports ------------------------------------ +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ :M: Jiafei Pan <jiafei.pan@nxp.com> :G: `qoriq-open-source`_ :F: docs/plat/ls1043a.rst :F: plat/layerscape/ NXP i.MX 7 WaRP7 platform port and SoC drivers ----------------------------------------------- +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ :M: Bryan O'Donoghue <bryan.odonoghue@linaro.org> :G: `bryanodonoghue`_ :M: Jun Nie <jun.nie@linaro.org> @@ -179,55 +435,85 @@ NXP i.MX 7 WaRP7 platform port and SoC drivers :F: drivers/imx/usdhc/ NXP i.MX 8 platform port ------------------------- +^^^^^^^^^^^^^^^^^^^^^^^^ :M: Anson Huang <Anson.Huang@nxp.com> :G: `Anson-Huang`_ :F: docs/plat/imx8.rst :F: plat/imx/ NXP i.MX8M platform port ------------------------- +^^^^^^^^^^^^^^^^^^^^^^^^ :M: Jacky Bai <ping.bai@nxp.com> :G: `JackyBai`_ -:F: doc/plat/imx8m.rst +:F: docs/plat/imx8m.rst :F: plat/imx/imx8m/ -OP-TEE dispatcher ------------------ -:M: Jens Wiklander <jens.wiklander@linaro.org> -:G: `jenswi-linaro`_ -:F: docs/spd/optee-dispatcher.rst -:F: services/spd/opteed/ - QEMU platform port ------------------- +^^^^^^^^^^^^^^^^^^ :M: Jens Wiklander <jens.wiklander@linaro.org> :G: `jenswi-linaro`_ :F: docs/plat/qemu.rst :F: plat/qemu/ +QTI platform port +^^^^^^^^^^^^^^^^^ +:M: Saurabh Gorecha <sgorecha@codeaurora.org> +:G: `sgorecha`_ +:M: Debasish Mandal <dmandal@codeaurora.org> +:M: QTI TF Maintainers <qti.trustedfirmware.maintainers@codeaurora.org> +:F: docs/plat/qti.rst +:F: plat/qti/ + Raspberry Pi 3 platform port ----------------------------- +^^^^^^^^^^^^^^^^^^^^^^^^^^^^ :M: Ying-Chun Liu (PaulLiu) <paul.liu@linaro.org> :G: `grandpaul`_ :F: docs/plat/rpi3.rst -:F: plat/rpi3/ +:F: plat/rpi/rpi3/ +:F: plat/rpi/common/ +:F: drivers/rpi3/ +:F: include/drivers/rpi3/ + +Raspberry Pi 4 platform port +^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +:M: Andre Przywara <andre.przywara@arm.com> +:G: `Andre-ARM`_ +:F: docs/plat/rpi4.rst +:F: plat/rpi/rpi4/ +:F: plat/rpi/common/ :F: drivers/rpi3/ :F: include/drivers/rpi3/ Renesas rcar-gen3 platform port -------------------------------- +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ :M: Jorge Ramirez-Ortiz <jramirez@baylibre.com> :G: `ldts`_ :M: Marek Vasut <marek.vasut@gmail.com> :G: `marex`_ :F: docs/plat/rcar-gen3.rst +:F: plat/renesas/common :F: plat/renesas/rcar +:F: drivers/renesas/common :F: drivers/renesas/rcar :F: tools/renesas/rcar_layout_create +Renesas RZ/G2 platform port +^^^^^^^^^^^^^^^^^^^^^^^^^^^ +:M: Biju Das <biju.das.jz@bp.renesas.com> +:G: `bijucdas`_ +:M: Marek Vasut <marek.vasut@gmail.com> +:G: `marex`_ +:M: Lad Prabhakar <prabhakar.mahadev-lad.rj@bp.renesas.com> +:G: `prabhakarlad`_ +:F: docs/plat/rz-g2.rst +:F: plat/renesas/common +:F: plat/renesas/rzg +:F: drivers/renesas/common +:F: drivers/renesas/rzg +:F: tools/renesas/rzg_layout_create + RockChip platform port ----------------------- +^^^^^^^^^^^^^^^^^^^^^^ :M: Tony Xie <tony.xie@rock-chips.com> :G: `TonyXie06`_ :G: `rockchip-linux`_ @@ -236,7 +522,7 @@ RockChip platform port :F: plat/rockchip/ STM32MP1 platform port ----------------------- +^^^^^^^^^^^^^^^^^^^^^^ :M: Yann Gautier <yann.gautier@st.com> :G: `Yann-lms`_ :F: docs/plat/stm32mp1.rst @@ -248,46 +534,100 @@ STM32MP1 platform port :F: tools/stm32image/ Synquacer platform port ------------------------ +^^^^^^^^^^^^^^^^^^^^^^^ :M: Sumit Garg <sumit.garg@linaro.org> :G: `b49020`_ :F: docs/plat/synquacer.rst :F: plat/socionext/synquacer/ Texas Instruments platform port -------------------------------- -:M: Andrew F. Davis <afd@ti.com> -:G: `glneo`_ +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +:M: Nishanth Menon <nm@ti.com> +:G: `nmenon`_ :F: docs/plat/ti-k3.rst :F: plat/ti/ +UniPhier platform port +^^^^^^^^^^^^^^^^^^^^^^ +:M: Orphan +:F: docs/plat/socionext-uniphier.rst +:F: plat/socionext/uniphier/ + +Xilinx platform port +^^^^^^^^^^^^^^^^^^^^ +:M: Michal Simek <michal.simek@xilinx.com> +:G: `michalsimek`_ +:M: Venkatesh Yadav Abbarapu <venkatesh.abbarapu@xilinx.com> +:G: `venkatesh`_ +:F: docs/plat/xilinx-zynqmp.rst +:F: plat/xilinx/ + + +Secure Payloads and Dispatchers +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +OP-TEE dispatcher +^^^^^^^^^^^^^^^^^ +:M: Jens Wiklander <jens.wiklander@linaro.org> +:G: `jenswi-linaro`_ +:F: docs/components/spd/optee-dispatcher.rst +:F: services/spd/opteed/ + TLK/Trusty secure payloads --------------------------- +^^^^^^^^^^^^^^^^^^^^^^^^^^ :M: Varun Wadekar <vwadekar@nvidia.com> :G: `vwadekar`_ -:F: docs/spd/tlk-dispatcher.rst -:F: docs/spd/trusty-dispatcher.rst +:F: docs/components/spd/tlk-dispatcher.rst +:F: docs/components/spd/trusty-dispatcher.rst :F: include/bl32/payloads/tlk.h :F: services/spd/tlkd/ :F: services/spd/trusty/ -UniPhier platform port ----------------------- -:M: Masahiro Yamada <yamada.masahiro@socionext.com> -:G: `masahir0y`_ -:F: docs/plat/socionext-uniphier.rst -:F: plat/socionext/uniphier/ +Test Secure Payload (TSP) +^^^^^^^^^^^^^^^^^^^^^^^^^ +:M: Manish Badarkhe <manish.badarkhe@arm.com> +:G: `ManishVB-Arm`_ +:F: bl32/tsp/ +:F: services/spd/tspd/ -Xilinx platform port --------------------- -:M: Siva Durga Prasad Paladugu <siva.durga.paladugu@xilinx.com> -:G: `sivadur`_ -:F: docs/plat/xilinx-zynqmp.rst -:F: plat/xilinx/ +Tools +~~~~~ + +Fiptool +^^^^^^^ +:M: Joao Alves <Joao.Alves@arm.com> +:G: `J-Alves`_ +:F: tools/fiptool/ + +Cert_create tool +^^^^^^^^^^^^^^^^ +:M: Sandrine Bailleux <sandrine.bailleux@arm.com> +:G: `sandrine-bailleux-arm`_ +:F: tools/cert_create/ + +Encrypt_fw tool +^^^^^^^^^^^^^^^ +:M: Sumit Garg <sumit.garg@linaro.org> +:G: `b49020`_ +:F: tools/encrypt_fw/ + +Sptool +^^^^^^ +:M: Manish Pandey <manish.pandey2@arm.com> +:G: `manish-pandey-arm`_ +:F: tools/sptool/ + +Build system +^^^^^^^^^^^^ +:M: Manish Pandey <manish.pandey2@arm.com> +:G: `manish-pandey-arm`_ +:F: Makefile +:F: make_helpers/ .. _AlexeiFedorov: https://github.com/AlexeiFedorov .. _Andre-ARM: https://github.com/Andre-ARM .. _Anson-Huang: https://github.com/Anson-Huang +.. _bijucdas: https://github.com/bijucdas .. _bryanodonoghue: https://github.com/bryanodonoghue .. _b49020: https://github.com/b49020 .. _carlocaione: https://github.com/carlocaione @@ -295,7 +635,6 @@ Xilinx platform port .. _etienne-lms: https://github.com/etienne-lms .. _glneo: https://github.com/glneo .. _grandpaul: https://github.com/grandpaul -.. _gyuri-szing: https://github.com/gyuri-szing .. _hzhuang1: https://github.com/hzhuang1 .. _JackyBai: https://github.com/JackyBai .. _jenswi-linaro: https://github.com/jenswi-linaro @@ -304,25 +643,43 @@ Xilinx platform port .. _ldts: https://github.com/ldts .. _marex: https://github.com/marex .. _masahir0y: https://github.com/masahir0y +.. _michalsimek: https://github.com/michalsimek .. _mmind: https://github.com/mmind +.. _MrVan: https://github.com/MrVan .. _mtk09422: https://github.com/mtk09422 .. _niej: https://github.com/niej .. _npoushin: https://github.com/npoushin +.. _prabhakarlad: https://github.com/prabhakarlad .. _qoriq-open-source: https://github.com/qoriq-open-source .. _remi-triplefault: https://github.com/repk .. _rockchip-linux: https://github.com/rockchip-linux .. _sandrine-bailleux-arm: https://github.com/sandrine-bailleux-arm +.. _sgorecha: https://github.com/sgorecha .. _shawnguo2: https://github.com/shawnguo2 -.. _sivadur: https://github.com/sivadur .. _smaeul: https://github.com/smaeul .. _soby-mathew: https://github.com/soby-mathew .. _thloh85-intel: https://github.com/thloh85-intel .. _thomas-arm: https://github.com/thomas-arm .. _TonyXie06: https://github.com/TonyXie06 .. _vwadekar: https://github.com/vwadekar +.. _venkatesh: https://github.com/vabbarap .. _Yann-lms: https://github.com/Yann-lms .. _manish-pandey-arm: https://github.com/manish-pandey-arm .. _mardyk01: https://github.com/mardyk01 .. _odeprez: https://github.com/odeprez .. _bipinravi-arm: https://github.com/bipinravi-arm .. _joannafarley-arm: https://github.com/joannafarley-arm +.. _ManishVB-Arm: https://github.com/ManishVB-Arm +.. _max-shvetsov: https://github.com/max-shvetsov +.. _javieralso-arm: https://github.com/javieralso-arm +.. _laurenw-arm: https://github.com/laurenw-arm +.. _zelalem-aweke: https://github.com/zelalem-aweke +.. _theotherjimmy: https://github.com/theotherjimmy +.. _J-Alves: https://github.com/J-Alves +.. _madhukar-Arm: https://github.com/madhukar-Arm +.. _john-powell-arm: https://github.com/john-powell-arm +.. _raghuncstate: https://github.com/raghuncstate +.. _CJKay: https://github.com/cjkay +.. _nmenon: https://github.com/nmenon + +.. _Project Maintenance Process: https://developer.trustedfirmware.org/w/collaboration/project-maintenance-process/ diff --git a/docs/about/release-information.rst b/docs/about/release-information.rst index c230e605d..55c8bdaf4 100644 --- a/docs/about/release-information.rst +++ b/docs/about/release-information.rst @@ -40,7 +40,11 @@ depending on project requirement and partner feedback. +-----------------+---------------------------+------------------------------+ | v2.2 | 4th week of Oct '19 | 1st week of Oct '19 | +-----------------+---------------------------+------------------------------+ -| v2.3 | 4th week of Mar '20 | 1st week of Mar '20 | +| v2.3 | 4th week of Apr '20 | 1st week of Apr '20 | ++-----------------+---------------------------+------------------------------+ +| v2.4 | 2nd week of Nov '20 | 4th week of Oct '20 | ++-----------------+---------------------------+------------------------------+ +| v2.5 | 2nd week of May '21 | 4th week of Apr '21 | +-----------------+---------------------------+------------------------------+ Removal of Deprecated Interfaces @@ -55,14 +59,9 @@ Release version after which it will be removed. | | Date | after | | | | | Release | | +================================+=============+=========+=========================================================+ -| ``AARCH32``/``AARCH64`` macros | Oct '19 | v2.3 | Deprecated in favor of ``__aarch64__`` | -+--------------------------------+-------------+---------+---------------------------------------------------------+ -| ``__ASSEMBLY__`` macro | Oct '19 | v2.3 | Deprecated in favor of ``__ASSEMBLER__`` | -+--------------------------------+-------------+---------+---------------------------------------------------------+ -| Prototype SPCI-based SPM | Oct '19 | v2.2 | Based on outdated Alpha 1 spec. Will be replaced with | -| (services/std_svc/spm) | | | alternative methods of secure partitioning support. | +| | | | | +--------------------------------+-------------+---------+---------------------------------------------------------+ -------------- -*Copyright (c) 2018-2019, Arm Limited and Contributors. All rights reserved.* +*Copyright (c) 2018-2020, Arm Limited and Contributors. All rights reserved.* diff --git a/docs/change-log-upcoming.rst b/docs/change-log-upcoming.rst index 14280cbf7..03806d910 100644 --- a/docs/change-log-upcoming.rst +++ b/docs/change-log-upcoming.rst @@ -7,7 +7,7 @@ of this file will be moved to the collective change-log.rst file at the time of release code freeze. -Upcoming Release Version 2.3 +Upcoming Release Version 2.4 ---------------------------- **Trusted Firmware-A Contributors, @@ -22,8 +22,12 @@ New Features - Arm Architecture - Example: "Add support for Branch Target Identification (BTI)" +- BL-specific + - Example: "Enhanced BL2 bootloader flow to load secure partitions based + on firmware configuration data (fconf)." + - Build System - - Add support for documentation build as a target in Makefile + - Example: "Modify FVP makefile for CPUs that support both AArch64/32" - CPU Support - Example: "cortex-a55: Workaround for erratum 1221012" diff --git a/docs/change-log.rst b/docs/change-log.rst index cf5b57ac6..ec88df921 100644 --- a/docs/change-log.rst +++ b/docs/change-log.rst @@ -4,6 +4,1088 @@ Change Log & Release Notes This document contains a summary of the new features, changes, fixes and known issues in each release of Trusted Firmware-A. +Version 2.4 +----------- + +New Features +^^^^^^^^^^^^ + +- Architecture support + - Armv8.6-A + - Added support for Armv8.6 Enhanced Counter Virtualization (ECV) + - Added support for Armv8.6 Fine Grained Traps (FGT) + - Added support for Armv8.6 WFE trap delays + +- Bootloader images + - Added support for Measured Boot + +- Build System + - Added build option ``COT_DESC_IN_DTB`` to create Chain of Trust at runtime + - Added build option ``OPENSSL_DIR`` to direct tools to OpenSSL libraries + - Added build option ``RAS_TRAP_LOWER_EL_ERR_ACCESS`` to enable trapping RAS + register accesses from EL1/EL2 to EL3 + - Extended build option ``BRANCH_PROTECTION`` to support branch target + identification + +- Common components + - Added support for exporting CPU nodes to the device tree + - Added support for single and dual-root Chains of Trust in secure + partitions + +- Drivers + - Added Broadcom RNG driver + - Added Marvell ``mg_conf_cm3`` driver + - Added System Control and Management Interface (SCMI) driver + - Added STMicroelectronics ETZPC driver + + - Arm GICv3 + - Added support for detecting topology at runtime + + - Dual Root + - Added support for platform certificates + + - Marvell Cache LLC + - Added support for mapping the entire LLC into SRAM + + - Marvell CCU + - Added workaround for erratum 3033912 + + - Marvell CP110 COMPHY + - Added support for SATA COMPHY polarity inversion + - Added support for USB COMPHY polarity inversion + - Added workaround for erratum IPCE_COMPHY-1353 + + - STM32MP1 Clocks + - Added ``RTC`` as a gateable clock + - Added support for shifted clock selector bit masks + - Added support for using additional clocks as parents + +- Libraries + - C standard library + - Added support for hexadecimal and pointer format specifiers in + ``snprint()`` + - Added assembly alternatives for various library functions + + - CPU support + - Arm Cortex-A53 + - Added workaround for erratum 1530924 + + - Arm Cortex-A55 + - Added workaround for erratum 1530923 + + - Arm Cortex-A57 + - Added workaround for erratum 1319537 + + - Arm Cortex-A76 + - Added workaround for erratum 1165522 + - Added workaround for erratum 1791580 + - Added workaround for erratum 1868343 + + - Arm Cortex-A72 + - Added workaround for erratum 1319367 + + - Arm Cortex-A77 + - Added workaround for erratum 1508412 + - Added workaround for erratum 1800714 + - Added workaround for erratum 1925769 + + - Arm Neoverse N1 + - Added workaround for erratum 1868343 + + - EL3 Runtime + - Added support for saving/restoring registers related to nested + virtualization in EL2 context switches if the architecture supports it + + - FCONF + - Added support for Measured Boot + - Added support for populating Chain of Trust properties + - Added support for loading the ``fw_config`` image + + - Measured Boot + - Added support for event logging + +- Platforms + - Added support for Arm Morello + - Added support for Arm TC0 + - Added support for iEi PUZZLE-M801 + - Added support for Marvell OCTEON TX2 T9130 + - Added support for MediaTek MT8192 + - Added support for NXP i.MX 8M Nano + - Added support for NXP i.MX 8M Plus + - Added support for QTI CHIP SC7180 + - Added support for STM32MP151F + - Added support for STM32MP153F + - Added support for STM32MP157F + - Added support for STM32MP151D + - Added support for STM32MP153D + - Added support for STM32MP157D + + - Arm + - Added support for platform-owned SPs + - Added support for resetting to BL31 + + - Arm FPGA + - Added support for Klein + - Added support for Matterhorn + - Added support for additional CPU clusters + + - Arm FVP + - Added support for performing SDEI platform setup at runtime + - Added support for SMCCC's ``SMCCC_ARCH_SOC_ID`` command + - Added an ``id`` field under the NV-counter node in the device tree to + differentiate between trusted and non-trusted NV-counters + - Added support for extracting the clock frequency from the timer node + in the device tree + + - Arm Juno + - Added support for SMCCC's ``SMCCC_ARCH_SOC_ID`` command + + - Arm N1SDP + - Added support for cross-chip PCI-e + + - Marvell + - Added support for AVS reduction + + - Marvell ARMADA + - Added support for twin-die combined memory device + + - Marvell ARMADA A8K + - Added support for DDR with 32-bit bus width (both ECC and non-ECC) + + - Marvell AP806 + - Added workaround for erratum FE-4265711 + + - Marvell AP807 + - Added workaround for erratum 3033912 + + - Nvidia Tegra + - Added debug printouts indicating SC7 entry sequence completion + - Added support for SDEI + - Added support for stack protection + - Added support for GICv3 + - Added support for SMCCC's ``SMCCC_ARCH_SOC_ID`` command + + - Nvidia Tegra194 + - Added support for RAS exception handling + - Added support for SPM + + - NXP i.MX + - Added support for SDEI + + - QEMU SBSA + - Added support for the Secure Partition Manager + + - QTI + - Added RNG driver + - Added SPMI PMIC arbitrator driver + - Added support for SMCCC's ``SMCCC_ARCH_SOC_ID`` command + + - STM32MP1 + - Added support for exposing peripheral interfaces to the non-secure + world at runtime + - Added support for SCMI clock and reset services + - Added support for STM32MP15x CPU revision Z + - Added support for SMCCC services in ``SP_MIN`` + +- Services + - Secure Payload Dispatcher + - Added a provision to allow clients to retrieve the service UUID + + - SPMC + - Added secondary core endpoint information to the SPMC context + structure + + - SPMD + - Added support for booting OP-TEE as a guest S-EL1 Secure Partition on + top of Hafnium in S-EL2 + - Added a provision for handling SPMC messages to register secondary + core entry points + - Added support for power management operations + +- Tools + - CertCreate + - Added support for secure partitions + + - CertTool + - Added support for the ``fw_config`` image + + - FIPTool + - Added support for the ``fw_config`` image + +Changed +^^^^^^^ + +- Architecture support + +- Bootloader images + +- Build System + - The top-level Makefile now supports building FipTool on Windows + - The default value of ``KEY_SIZE`` has been changed to to 2048 when RSA is + in use + - The previously-deprecated macro ``__ASSEMBLY__`` has now been removed + +- Common components + - Certain functions that flush the console will no longer return error + information + +- Drivers + - Arm GIC + - Usage of ``drivers/arm/gic/common/gic_common.c`` has now been + deprecated in favour of ``drivers/arm/gic/vX/gicvX.mk`` + - Added support for detecting the presence of a GIC600-AE + - Added support for detecting the presence of a GIC-Clayton + + - Marvell MCI + - Now performs link tuning for all MCI interfaces to improve performance + + - Marvell MoChi + - PIDI masters are no longer forced into a non-secure access level when + ``LLC_SRAM`` is enabled + - The SD/MMC controllers are now accessible from guest virtual machines + + - Mbed TLS + - Migrated to Mbed TLS v2.24.0 + + - STM32 FMC2 NAND + - Adjusted FMC node bindings to include an EBI controller node + + - STM32 Reset + - Added an optional timeout argument to assertion functions + + - STM32MP1 Clocks + - Enabled several additional system clocks during initialization + +- Libraries + - C Standard Library + - Improved ``memset`` performance by avoiding single-byte writes + - Added optimized assembly variants of ``memset`` + + - CPU support + - Renamed Cortex-Hercules to Cortex-A78 + - Renamed Cortex-Hercules AE to Cortex-A78 AE + - Renamed Neoverse Zeus to Neoverse V1 + + - Coreboot + - Updated ‘coreboot_get_memory_type’ API to take an extra argument as a + ’memory size’ that used to return a valid memory type. + + - libfdt + - Updated to latest upstream version + +- Platforms + - Allwinner + - Disabled non-secure access to PRCM power control registers + + - Arm + - ``BL32_BASE`` is now platform-dependent when ``SPD_spmd`` is enabled + - Added support for loading the Chain of Trust from the device tree + - The firmware update check is now executed only once + - NV-counter base addresses are now loaded from the device tree when + ``COT_DESC_IN_DTB`` is enabled + - Now loads and populates ``fw_config`` and ``tb_fw_config`` + - FCONF population now occurs after caches have been enabled in order + to reduce boot times + + - Arm Corstone-700 + - Platform support has been split into both an FVP and an FPGA variant + + - Arm FPGA + - DTB and BL33 load addresses have been given sensible default values + - Now reads generic timer counter frequency, GICD and GICR base + addresses, and UART address from DT + - Now treats the primary PL011 UART as an SBSA Generic UART + + - Arm FVP + - Secure interrupt descriptions, UART parameters, clock frequencies and + GICv3 parameters are now queried through FCONF + - UART parameters are now queried through the device tree + - Added an owner field to Cactus secure partitions + - Increased the maximum size of BL2 when the Chain of Trust is loaded + from the device tree + - Reduces the maximum size of BL31 + - The ``FVP_USE_SP804_TIMER`` and ``FVP_VE_USE_SP804_TIMER`` build + options have been removed in favour of a common ``USE_SP804_TIMER`` + option + - Added a third Cactus partition to manifests + - Device tree nodes now store UUIDs in big-endian + + - Arm Juno + - Increased the maximum size of BL2 when optimizations have not been + applied + - Reduced the maximum size of BL31 and BL32 + + - Marvell AP807 + - Enabled snoop filters + + - Marvell ARMADA A3K + - UART recovery images are now suffixed with ``.bin`` + + - Marvell ARMADA A8K + - Option ``BL31_CACHE_DISABLE`` is now disabled (``0``) by default + + - Nvidia Tegra + - Added VPR resize supported check when processing video memory resize + requests + - Added SMMU verification to prevent potential issues caused by + undetected corruption of the SMMU configuration during boot + - The GIC CPU interface is now properly disabled after CPU off + - The GICv2 sources list and the ``BL31_SIZE`` definition have been made + platform-specific + - The SPE driver will no longer flush the console when writing + individual characters + + - Nvidia Tegra194 + - TZDRAM setup has been moved to platform-specific early boot handlers + - Increased verbosity of debug prints for RAS SErrors + - Support for powering down CPUs during CPU suspend has been removed + - Now verifies firewall settings before using resources + + - TI K3 + - The UART number has been made configurable through ``K3_USART`` + + - Rockchip RK3368 + - The maximum number of memory map regions has been increased to 20 + + - Socionext Uniphier + - The maximum size of BL33 has been increased to support larger + bootloaders + + - STM32 + - Removed platform-specific DT functions in favour of using existing + generic alternatives + + - STM32MP1 + - Increased verbosity of exception reports in debug builds + - Device trees have been updated to align with the Linux kernel + - Now uses the ETZPC driver to configure secure-aware interfaces for + assignment to the non-secure world + - Finished good variants have been added to the board identifier + enumerations + - Non-secure access to clocks and reset domains now depends on their + state of registration + - NEON is now disabled in ``SP_MIN`` + - The last page of ``SYSRAM`` is now used as SCMI shared memory + - Checks to verify platform compatibility have been added to verify that + an image is compatible with the chip ID of the running platform + + - QEMU SBSA + - Removed support for Arm's Cortex-A53 + +- Services + - Renamed SPCI to FF-A + + - SPMD + - No longer forwards requests to the non-secure world when retrieving + partition information + - SPMC manifest size is now retrieved directly from SPMD instead of the + device tree + - The FF-A version handler now returns SPMD's version when the origin + of the call is secure, and SPMC's version when the origin of the call + is non-secure + + - SPMC + - Updated the manifest to declare CPU nodes in descending order as per + the SPM (Hafnium) multicore requirement + - Updated the device tree to mark 2GB as device memory for the first + partition excluding trusted DRAM region (which is reserved for SPMC) + - Increased the number of EC contexts to the maximum number of PEs as + per the FF-A specification + +- Tools + - FIPTool + - Now returns ``0`` on ``help`` and ``help <command>`` + + - Marvell DoImage + - Updated Mbed TLS support to v2.8 + + - SPTool + - Now appends CertTool arguments + +Resolved Issues +^^^^^^^^^^^^^^^ + +- Bootloader images + - Fixed compilation errors for dual-root Chains of Trust caused by symbol + collision + + - BL31 + - Fixed compilation errors on platforms with fewer than 4 cores caused + by initialization code exceeding the end of the stacks + - Fixed compilation errors when building a position-independent image + +- Build System + - Fixed invalid empty version strings + - Fixed compilation errors on Windows caused by a non-portable architecture + revision comparison + +- Drivers + - Arm GIC + - Fixed spurious interrupts caused by a missing barrier + + - STM32 Flexible Memory Controller 2 (FMC2) NAND driver + - Fixed runtime instability caused by incorrect error detection logic + + - STM32MP1 Clock driver + - Fixed incorrectly-formatted log messages + - Fixed runtime instability caused by improper clock gating procedures + + - STMicroelectronics Raw NAND driver + - Fixed runtime instability caused by incorrect unit conversion when + waiting for NAND readiness + +- Libraries + - AMU + - Fixed timeout errors caused by excess error logging + + - EL3 Runtime + - Fixed runtime instability caused by improper register save/restore + routine in EL2 + + - FCONF + - Fixed failure to initialize GICv3 caused by overly-strict device tree + requirements + + - Measured Boot + - Fixed driver errors caused by a missing default value for the + ``HASH_ALG`` build option + + - SPE + - Fixed feature detection check that prevented CPUs supporting SVE from + detecting support for SPE in the non-secure world + + - Translation Tables + - Fixed various MISRA-C 2012 static analysis violations + +- Platforms + - Allwinner A64 + - Fixed USB issues on certain battery-powered device caused by + improperly activated USB power rail + + - Arm + - Fixed compilation errors caused by increase in BL2 size + - Fixed compilation errors caused by missing Makefile dependencies to + generated files when building the FIP + - Fixed MISRA-C 2012 static analysis violations caused by unused + structures in include directives intended to be feature-gated + + - Arm FPGA + - Fixed initialization issues caused by incorrect MPIDR topology mapping + logic + + - Arm RD-N1-edge + - Fixed compilation errors caused by mismatched parentheses in Makefile + + - Arm SGI + - Fixed crashes due to the flash memory used for cold reboot attack + protection not being mapped + + - Intel Agilex + - Fixed initialization issues caused by several compounding bugs + + - Marvell + - Fixed compilation warnings caused by multiple Makefile inclusions + + - Marvell ARMADA A3K + - Fixed boot issue in debug builds caused by checks on the BL33 load + address that are not appropriate for this platform + + - Nvidia Tegra + - Fixed incorrect delay timer reads + - Fixed spurious interrupts in the non-secure world during cold boot + caused by the arbitration bit in the memory controller not being + cleared + - Fixed faulty video memory resize sequence + + - Nvidia Tegra194 + - Fixed incorrect alignment of TZDRAM base address + + - NXP iMX8M + - Fixed CPU hot-plug issues caused by race condition + + - STM32MP1 + - Fixed compilation errors in highly-parallel builds caused by incorrect + Makefile dependencies + + - STM32MP157C-ED1 + - Fixed initialization issues caused by missing device tree hash node + + - Raspberry Pi 3 + - Fixed compilation errors caused by incorrect dependency ordering in + Makefile + + - Rockchip + - Fixed initialization issues caused by non-critical errors when parsing + FDT being treated as critical + + - Rockchip RK3368 + - Fixed runtime instability caused by incorrect CPUID shift value + + - QEMU + - Fixed compilation errors caused by incorrect dependency ordering in + Makefile + + - QEMU SBSA + - Fixed initialization issues caused by FDT exceeding reserved memory + size + + - QTI + - Fixed compilation errors caused by inclusion of a non-existent file + +- Services + - FF-A (previously SPCI) + - Fixed SPMD aborts caused by incorrect behaviour when the manifest is + page-aligned + +- Tools + - Fixed compilation issues when compiling tools from within their respective + directories + + - FIPTool + - Fixed command line parsing issues on Windows when using arguments + whose names also happen to be a subset of another's + + - Marvell DoImage + - Fixed PKCS signature verification errors at boot on some platforms + caused by generation of misaligned images + +Known Issues +^^^^^^^^^^^^ + +- Platforms + - NVIDIA Tegra + - Signed comparison compiler warnings occurring in libfdt are currently + being worked around by disabling the warning for the platform until + the underlying issue is resolved in libfdt + +Version 2.3 +----------- + +New Features +^^^^^^^^^^^^ + +- Arm Architecture + - Add support for Armv8.4-SecEL2 extension through the SPCI defined SPMD/SPMC + components. + + - Build option to support EL2 context save and restore in the secure world + (CTX_INCLUDE_EL2_REGS). + + - Add support for SMCCC v1.2 (introducing the new SMCCC_ARCH_SOC_ID SMC). + Note that the support is compliant, but the SVE registers save/restore will + be done as part of future S-EL2/SPM development. + +- BL-specific + - Enhanced BL2 bootloader flow to load secure partitions based on firmware + configuration data (fconf). + + - Changes necessary to support SEPARATE_NOBITS_REGION feature + + - TSP and BL2_AT_EL3: Add Position Independent Execution ``PIE`` support + +- Build System + - Add support for documentation build as a target in Makefile + + - Add ``COT`` build option to select the Chain of Trust to use when the + Trusted Boot feature is enabled (default: ``tbbr``). + + - Added creation and injection of secure partition packages into the FIP. + + - Build option to support SPMC component loading and run at S-EL1 + or S-EL2 (SPMD_SPM_AT_SEL2). + + - Enable MTE support + + - Enable Link Time Optimization in GCC + + - Enable -Wredundant-decls warning check + + - Makefile: Add support to optionally encrypt BL31 and BL32 + + - Add support to pass the nt_fw_config DTB to OP-TEE. + + - Introduce per-BL ``CPPFLAGS``, ``ASFLAGS``, and ``LDFLAGS`` + + - build_macros: Add CREATE_SEQ function to generate sequence of numbers + +- CPU Support + - cortex-a57: Enable higher performance non-cacheable load forwarding + + - Hercules: Workaround for Errata 1688305 + + - Klein: Support added for Klein CPU + + - Matterhorn: Support added for Matterhorn CPU + +- Drivers + - auth: Add ``calc_hash`` function for hash calculation. Used for + authentication of images when measured boot is enabled. + + - cryptocell: Add authenticated decryption framework, and support + for CryptoCell-713 and CryptoCell-712 RSA 3K + + - gic600: Add support for multichip configuration and Clayton + - gicv3: Introduce makefile, Add extended PPI and SPI range, + Add support for probing multiple GIC Redistributor frames + - gicv4: Add GICv4 extension for GIC driver + + - io: Add an IO abstraction layer to load encrypted firmwares + + - mhu: Derive doorbell base address + + - mtd: Add SPI-NOR, SPI-NAND, SPI-MEM, and raw NAND framework + + - scmi: Allow use of multiple SCMI channels + + - scu: Add a driver for snoop control unit + +- Libraries + - coreboot: Add memory range parsing and use generic base address + + - compiler_rt: Import popcountdi2.c and popcountsi2.c files, + aeabi_ldivmode.S file and dependencies + + - debugFS: Add DebugFS functionality + + - el3_runtime: Add support for enabling S-EL2 + + - fconf: Add Firmware Configuration Framework (fconf) (experimental). + + - libc: Add memrchr function + + - locks: bakery: Use is_dcache_enabled() helper and add a DMB to + the 'read_cache_op' macro + + - psci: Add support to enable different personality of the same soc. + + - xlat_tables_v2: Add support to pass shareability attribute for + normal memory region, use get_current_el_maybe_constant() in + is_dcache_enabled(), read-only xlat tables for BL31 memory, and + add enable_mmu() + +- New Platforms Support + - arm/arm_fpga: New platform support added for FPGA + + - arm/rddaniel: New platform support added for rd-daniel platform + + - brcm/stingray: New platform support added for Broadcom stingray platform + + - nvidia/tegra194: New platform support for Nvidia Tegra194 platform + +- Platforms + - allwinner: Implement PSCI system suspend using SCPI, add a msgbox + driver for use with SCPI, and reserve and map space for the SCP firmware + - allwinner: axp: Add AXP805 support + - allwinner: power: Add DLDO4 power rail + + - amlogic: axg: Add a build flag when using ATOS as BL32 and support for + the A113D (AXG) platform + + - arm/a5ds: Add ethernet node and L2 cache node in devicetree + + - arm/common: Add support for the new `dualroot` chain of trust + - arm/common: Add support for SEPARATE_NOBITS_REGION + - arm/common: Re-enable PIE when RESET_TO_BL31=1 + - arm/common: Allow boards to specify second DRAM Base address + and to define PLAT_ARM_TZC_FILTERS + + - arm/corstone700: Add support for mhuv2 and stack protector + + - arm/fvp: Add support for fconf in BL31 and SP_MIN. Populate power + domain descriptor dynamically by leveraging fconf APIs. + - arm/fvp: Add Cactus/Ivy Secure Partition information and use two + instances of Cactus at S-EL1 + - arm/fvp: Add support to run BL32 in TDRAM and BL31 in secure DRAM + - arm/fvp: Add support for GICv4 extension and BL2 hash calculation in BL1 + + - arm/n1sdp: Setup multichip gic routing table, update platform macros + for dual-chip setup, introduce platform information SDS region, add + support to update presence of External LLC, and enable the + NEOVERSE_N1_EXTERNAL_LLC flag + + - arm/rdn1edge: Add support for dual-chip configuration and use + CREATE_SEQ helper macro to compare chip count + + - arm/sgm: Always use SCMI for SGM platforms + - arm/sgm775: Add support for dynamic config using fconf + + - arm/sgi: Add multi-chip mode parameter in HW_CONFIG dts, macros for + remote chip device region, chip_id and multi_chip_mode to platform + variant info, and introduce number of chips macro + + - brcm: Add BL2 and BL31 support common across Broadcom platforms + - brcm: Add iproc SPI Nor flash support, spi driver, emmc driver, + and support to retrieve plat_toc_flags + + - hisilicon: hikey960: Enable system power off callback + + - intel: Enable bridge access, SiP SMC secure register access, and uboot + entrypoint support + - intel: Implement platform specific system reset 2 + - intel: Introduce mailbox response length handling + + - imx: console: Use CONSOLE_T_BASE for UART base address and generic console_t + data structure + - imx8mm: Provide uart base as build option and add the support for opteed spd + on imx8mq/imx8mm + - imx8qx: Provide debug uart num as build + - imx8qm: Apply clk/pinmux configuration for DEBUG_CONSOLE and provide debug + uart num as build param + + - marvell: a8k: Implement platform specific power off and add support + for loading MG CM3 images + + - mediatek: mt8183: Add Vmodem/Vcore DVS init level + + - qemu: Support optional encryption of BL31 and BL32 images + and ARM_LINUX_KERNEL_AS_BL33 to pass FDT address + - qemu: Define ARMV7_SUPPORTS_VFP + - qemu: Implement PSCI_CPU_OFF and qemu_system_off via semihosting + + - renesas: rcar_gen3: Add new board revision for M3ULCB + + - rockchip: Enable workaround for erratum 855873, claim a macro to enable + hdcp feature for DP, enable power domains of rk3399 before reset, add + support for UART3 as serial output, and initialize reset and poweroff + GPIOs with known invalid value + + - rpi: Implement PSCI CPU_OFF, use MMIO accessor, autodetect Mini-UART + vs. PL011 configuration, and allow using PL011 UART for RPi3/RPi4 + - rpi3: Include GPIO driver in all BL stages and use same "clock-less" + setup scheme as RPi4 + - rpi3/4: Add support for offlining CPUs + + - st: stm32mp1: platform.mk: Support generating multiple images in one build, + migrate to implicit rules, derive map file name from target name, generate + linker script with fixed name, and use PHONY for the appropriate targets + - st: stm32mp1: Add support for SPI-NOR, raw NAND, and SPI-NAND boot device, + QSPI, FMC2 driver + - st: stm32mp1: Use stm32mp_get_ddr_ns_size() function, set XN attribute for + some areas in BL2, dynamically map DDR later and non-cacheable during its + test, add a function to get non-secure DDR size, add DT helper for reg by + name, and add compilation flags for boot devices + + - socionext: uniphier: Turn on ENABLE_PIE + + - ti: k3: Add PIE support + + - xilinx: versal: Add set wakeup source, client wakeup, query data, request + wakeup, PM_INIT_FINALIZE, PM_GET_TRUSTZONE_VERSION, PM IOCTL, support for + suspend related, and Get_ChipID APIs + - xilinx: versal: Implement power down/restart related EEMI, SMC handler for + EEMI, PLL related PM, clock related PM, pin control related PM, reset related + PM, device related PM , APIs + - xilinx: versal: Enable ipi mailbox service + - xilinx: versal: Add get_api_version support and support to send PM API to PMC + using IPI + - xilinx: zynqmp: Add checksum support for IPI data, GET_CALLBACK_DATA + function, support to query max divisor, CLK_SET_RATE_PARENT in gem clock + node, support for custom type flags, LPD WDT clock to the pm_clock structure, + idcodes for new RFSoC silicons ZU48DR and ZU49DR, and id for new RFSoC device + ZU39DR + +- Security + - Use Speculation Barrier instruction for v8.5+ cores + + - Add support for optional firmware encryption feature (experimental). + + - Introduce a new `dualroot` chain of trust. + + - aarch64: Prevent speculative execution past ERET + - aarch32: Stop speculative execution past exception returns. + +- SPCI + - Introduced the Secure Partition Manager Dispatcher (SPMD) component as a + new standard service. + +- Tools + - cert_create: Introduce CoT build option and TBBR CoT makefile, + and define the dualroot CoT + + - encrypt_fw: Add firmware authenticated encryption tool + + - memory: Add show_memory script that prints a representation + of the memory layout for the latest build + +Changed +^^^^^^^ + +- Arm Architecture + - PIE: Make call to GDT relocation fixup generalized + +- BL-Specific + - Increase maximum size of BL2 image + + - BL31: Discard .dynsym .dynstr .hash sections to make ENABLE_PIE work + - BL31: Split into two separate memory regions + + - Unify BL linker scripts and reduce code duplication. + +- Build System + - Changes to drive cert_create for dualroot CoT + + - Enable -Wlogical-op always + + - Enable -Wshadow always + + - Refactor the warning flags + + - PIE: Pass PIE options only to BL31 + + - Reduce space lost to object alignment + + - Set lld as the default linker for Clang builds + + - Remove -Wunused-const-variable and -Wpadded warning + + - Remove -Wmissing-declarations warning from WARNING1 level + +- Drivers + - authentication: Necessary fix in drivers to upgrade to mbedtls-2.18.0 + + - console: Integrate UART base address in generic console_t + + - gicv3: Change API for GICR_IPRIORITYR accessors and separate + GICD and GICR accessor functions + + - io: Change seek offset to signed long long and panic in case + of io setup failure + + - smmu: SMMUv3: Changed retry loop to delay timer + + - tbbr: Reduce size of hash and ECDSA key buffers when possible + +- Library Code + - libc: Consolidate the size_t, unified, and NULL definitions, + and unify intmax_t and uintmax_t on AArch32/64 + + - ROMLIB: Optimize memory layout when ROMLIB is used + + - xlat_tables_v2: Use ARRAY_SIZE in REGISTER_XLAT_CONTEXT_FULL_SPEC, + merge REGISTER_XLAT_CONTEXT_{FULL_SPEC,RO_BASE_TABLE}, + and simplify end address checks in mmap_add_region_check() + +- Platforms + - allwinner: Adjust SRAM A2 base to include the ARISC vectors, clean up MMU + setup, reenable USE_COHERENT_MEM, remove unused include path, move the + NOBITS region to SRAM A1, convert AXP803 regulator setup code into a driver, + enable clock before resetting I2C/RSB + - allwinner: h6: power: Switch to using the AXP driver + - allwinner: a64: power: Use fdt_for_each_subnode, remove obsolete register + check, remove duplicate DT check, and make sunxi_turn_off_soc static + - allwinner: Build PMIC bus drivers only in BL31, clean up PMIC-related error + handling, and synchronize PMIC enumerations + + - arm/a5ds: Change boot address to point to DDR address + + - arm/common: Check for out-of-bound accesses in the platform io policies + + - arm/corstone700: Updating the kernel arguments to support initramfs, + use fdts DDR memory and XIP rootfs, and set UART clocks to 32MHz + + - arm/fvp: Modify multithreaded dts file of DynamIQ FVPs, slightly bump + the stack size for bl1 and bl2, remove re-definition of topology related + build options, stop reclaiming init code with Clang builds, and map only + the needed DRAM region statically in BL31/SP_MIN + + - arm/juno: Maximize space allocated to SCP_BL2 + + - arm/sgi: Bump bl1 RW limit, mark remote chip shared ram as non-cacheable, + move GIC related constants to board files, include AFF3 affinity in core + position calculation, move bl31_platform_setup to board file, and move + topology information to board folder + + - common: Refactor load_auth_image_internal(). + + - hisilicon: Remove uefi-tools in hikey and hikey960 documentation + + - intel: Modify non secure access function, BL31 address mapping, mailbox's + get_config_status, and stratix10 BL31 parameter handling + - intel: Remove un-needed checks for qspi driver r/w and s10 unused source code + - intel: Change all global sip function to static + - intel: Refactor common platform code + - intel: Create SiP service header file + + + - marvell: armada: scp_bl2: Allow loading up to 8 images + - marvell: comphy-a3700: Support SGMII COMPHY power off and fix USB3 + powering on when on lane 2 + - marvell: Consolidate console register calls + + - mediatek: mt8183: Protect 4GB~8GB dram memory, refine GIC driver for + low power scenarios, and switch PLL/CLKSQ/ck_off/axi_26m control to SPM + + - qemu: Update flash address map to keep FIP in secure FLASH0 + + - renesas: rcar_gen3: Update IPL and Secure Monitor Rev.2.0.6, update DDR + setting for H3, M3, M3N, change fixed destination address of BL31 and BL32, + add missing #{address,size}-cells into generated DT, pass DT to OpTee OS, + and move DDR drivers out of staging + + - rockchip: Make miniloader ddr_parameter handling optional, cleanup securing + of ddr regions, move secure init to separate file, use base+size for secure + ddr regions, bring TZRAM_SIZE values in lined, and prevent macro expansion + in paths + + - rpi: Move plat_helpers.S to common + - rpi3: gpio: Simplify GPIO setup + - rpi4: Skip UART initialisation + + - st: stm32m1: Use generic console_t data structure, remove second + QSPI flash instance, update for FMC2 pin muxing, and reduce MAX_XLAT_TABLES + to 4 + + - socionext: uniphier: Make on-chip SRAM and I/O register regions configurable + - socionext: uniphier: Make PSCI related, counter control, UART, pinmon, NAND + controller, and eMMC controller base addresses configurable + - socionext: uniphier: Change block_addressing flag and the return value type + of .is_usb_boot() to bool + - socionext: uniphier: Run BL33 at EL2, call uniphier_scp_is_running() only + when on-chip STM is supported, define PLAT_XLAT_TABLES_DYNAMIC only for BL2, + support read-only xlat tables, use enable_mmu() in common function, shrink + UNIPHIER_ROM_REGION_SIZE, prepare uniphier_soc_info() for next SoC, extend + boot device detection for future SoCs, make all BL images completely + position-independent, make uniphier_mmap_setup() work with PIE, pass SCP + base address as a function parameter, set buffer offset and length for + io_block dynamically, and use more mmap_add_dynamic_region() for loading + images + + - spd/trusty: Disable error messages seen during boot, allow gic base to be + specified with GICD_BASE, and allow getting trusty memsize from BL32_MEM_SIZE + instead of TSP_SEC_MEM_SIZE + + - ti: k3: common: Enable ARM cluster power down and rename device IDs to + be more consistent + - ti: k3: drivers: ti_sci: Put sequence number in coherent memory and + remove indirect structure of const data + + - xilinx: Move ipi mailbox svc to xilinx common + - xilinx: zynqmp: Use GIC framework for warm restart + - xilinx: zynqmp: pm: Move custom clock flags to typeflags, remove + CLK_TOPSW_LSBUS from invalid clock list and rename FPD WDT clock ID + - xilinx: versal: Increase OCM memory size for DEBUG builds and adjust + cpu clock, Move versal_def.h and versal_private to include directory + +- Tools + - sptool: Updated sptool to accommodate building secure partition packages. + +Resolved Issues +^^^^^^^^^^^^^^^ + +- Arm Architecture + - Fix crash dump for lower EL + +- BL-Specific + - Bug fix: Protect TSP prints with lock + + - Fix boot failures on some builds linked with ld.lld. + +- Build System + - Fix clang build if CC is not in the path. + + - Fix 'BL stage' comment for build macros + +- Code Quality + - coverity: Fix various MISRA violations including null pointer violations, + C issues in BL1/BL2/BL31 and FDT helper functions, using boolean essential, + type, and removing unnecessary header file and comparisons to LONG_MAX in + debugfs devfip + + - Based on coding guidelines, replace all `unsigned long` depending on if + fixed based on AArch32 or AArch64. + + - Unify type of "cpu_idx" and Platform specific defines across PSCI module. + +- Drivers + - auth: Necessary fix in drivers to upgrade to mbedtls-2.18.0 + + - delay_timer: Fix non-standard frequency issue in udelay + + - gicv3: Fix compiler dependent behavior + - gic600: Fix include ordering according to the coding style and power up sequence + +- Library Code + - el3_runtime: Fix stack pointer maintenance on EA handling path, + fixup 'cm_setup_context' prototype, and adds TPIDR_EL2 register + to the context save restore routines + + - libc: Fix SIZE_MAX on AArch32 + + - locks: T589: Fix insufficient ordering guarantees in bakery lock + + - pmf: Fix 'tautological-constant-compare' error, Make the runtime + instrumentation work on AArch32, and Simplify PMF helper macro + definitions across header files + + - xlat_tables_v2: Fix assembler warning of PLAT_RO_XLAT_TABLES + +- Platforms + - allwinner: Fix H6 GPIO and CCU memory map addresses and incorrect ARISC + code patch offset check + + - arm/a5ds: Correct system freq and Cache Writeback Granule, and cleanup + enable-method in devicetree + + - arm/fvp: Fix incorrect GIC mapping, BL31 load address and image size + for RESET_TO_BL31=1, topology description of cpus for DynamIQ based + FVP, and multithreaded FVP power domain tree + - arm/fvp: spm-mm: Correcting instructions to build SPM for FVP + + - arm/common: Fix ROTPK hash generation for ECDSA encryption, BL2 bug in + dynamic configuration initialisation, and current RECLAIM_INIT_CODE behavior + + - arm/rde1edge: Fix incorrect topology tree description + + - arm/sgi: Fix the incorrect check for SCMI channel ID + + - common: Flush dcache when storing timestamp + + - intel: Fix UEFI decompression issue, memory calibration, SMC SIP service, + mailbox config return status, mailbox driver logic, FPGA manager on + reconfiguration, and mailbox send_cmd issue + + - imx: Fix shift-overflow errors, the rdc memory region slot's offset, + multiple definition of ipc_handle, missing inclusion of cdefs.h, and + correct the SGIs that used for secure interrupt + + - mediatek: mt8183: Fix AARCH64 init fail on CPU0 + + - rockchip: Fix definition of struct param_ddr_usage + + - rpi4: Fix documentation of armstub config entry + + - st: Correct io possible NULL pointer dereference and device_size type, + nand xor_ecc.val assigned value, static analysis tool issues, and fix + incorrect return value and correctly check pwr-regulators node + + - xilinx: zynqmp: Correct syscnt freq for QEMU and fix clock models + and IDs of GEM-related clocks + +Known Issues +^^^^^^^^^^^^ + +- Build System + - dtb: DTB creation not supported when building on a Windows host. + + This step in the build process is skipped when running on a Windows host. A + known issue from the 1.6 release. + + - Intermittent assertion firing `ASSERT: services/spd/tspd/tspd_main.c:105` + +- Coverity + - Intermittent Race condition in Coverity Jenkins Build Job + +- Platforms + - arm/juno: System suspend from Linux does not function as documented in the + user guide + + Following the instructions provided in the user guide document does not + result in the platform entering system suspend state as expected. A message + relating to the hdlcd driver failing to suspend will be emitted on the + Linux terminal. + + - mediatek/mt6795: This platform does not build in this release + Version 2.2 ----------- @@ -17,6 +1099,7 @@ New Features - Enable Memory Tagging Extension (MTE) support in both secure and non-secure worlds + - Adds support for the new Memory Tagging Extension arriving in ARMv8.5. MTE support is now enabled by default on systems that support it at EL0. @@ -84,6 +1167,7 @@ New Features - gicv3: Enabled multi-socket GIC redistributor frame discovery and migrated ARM platforms to the new API + - Adds ``gicv3_rdistif_probe`` function that delegates the responsibility of discovering the corresponding redistributor base frame to each CPU itself. @@ -2841,7 +3925,7 @@ releases of TF-A. -------------- -*Copyright (c) 2013-2019, Arm Limited and Contributors. All rights reserved.* +*Copyright (c) 2013-2020, Arm Limited and Contributors. All rights reserved.* .. _SDEI Specification: http://infocenter.arm.com/help/topic/com.arm.doc.den0054a/ARM_DEN0054A_Software_Delegated_Exception_Interface.pdf .. _tf-issue#501: https://github.com/ARM-software/tf-issues/issues/501 diff --git a/docs/components/arm-sip-service.rst b/docs/components/arm-sip-service.rst index 01bc04d71..b51a94dc7 100644 --- a/docs/components/arm-sip-service.rst +++ b/docs/components/arm-sip-service.rst @@ -430,6 +430,6 @@ uint32_t w1: On success, debugfs interface version, 32 bits -------------- -*Copyright (c) 2017-2019, Arm Limited and Contributors. All rights reserved.* +*Copyright (c) 2017-2020, Arm Limited and Contributors. All rights reserved.* -.. _SMC Calling Convention: http://infocenter.arm.com/help/topic/com.arm.doc.den0028a/index.html +.. _SMC Calling Convention: https://developer.arm.com/docs/den0028/latest diff --git a/docs/components/cot-binding.rst b/docs/components/cot-binding.rst new file mode 100644 index 000000000..4f8c8b725 --- /dev/null +++ b/docs/components/cot-binding.rst @@ -0,0 +1,332 @@ +Chain of trust bindings +======================= + +The device tree allows to describe the chain of trust with the help of +'cot' node which contain 'manifests' and 'images' as sub-nodes. +'manifests' and 'images' nodes contains number of sub-nodes (i.e. 'certificate' +and 'image' nodes) mentioning properties of the certificate and image respectively. + +Also, device tree describes 'non-volatile-counters' node which contains number of +sub-nodes mentioning properties of all non-volatile-counters used in the chain of trust. + +cot +------------------------------------------------------------------ +This is root node which contains 'manifests' and 'images' as sub-nodes + + +Manifests and Certificate node bindings definition +---------------------------------------------------------------- + +- Manifests node + Description: Container of certificate nodes. + + PROPERTIES + + - compatible: + Usage: required + + Value type: <string> + + Definition: must be "arm, cert-descs" + +- Certificate node + Description: + + Describes certificate properties which are used + during the authentication process. + + PROPERTIES + + - root-certificate + Usage: + + Required for the certificate with no parent. + In other words, certificates which are validated + using root of trust public key. + + Value type: <boolean> + + - image-id + Usage: Required for every certificate with unique id. + + Value type: <u32> + + - parent + Usage: + + It refers to their parent image, which typically contains + information to authenticate the certificate. + This property is required for all non-root certificates. + + This property is not required for root-certificates + as root-certificates are validated using root of trust + public key provided by platform. + + Value type: <phandle> + + - signing-key + Usage: + + This property is used to refer public key node present in + parent certificate node and it is required property for all + non-root certificates which are authenticated using public-key + present in parent certificate. + + This property is not required for root-certificates + as root-certificates are validated using root of trust + public key provided by platform. + + Value type: <phandle> + + - antirollback-counter + Usage: + + This property is used by all certificates which are + protected against rollback attacks using a non-volatile + counter and it is an optional property. + + This property is used to refer one of the non-volatile + counter sub-node present in 'non-volatile counters' node. + + Value type: <phandle> + + + SUBNODES + - Description: + + Hash and public key information present in the certificate + are shown by these nodes. + + - public key node + Description: Provide public key information in the certificate. + + PROPERTIES + + - oid + Usage: + + This property provides the Object ID of public key + provided in the certificate which the help of which + public key information can be extracted. + + Value type: <string> + + - hash node + Description: Provide the hash information in the certificate. + + PROPERTIES + + - oid + Usage: + + This property provides the Object ID of hash provided in + the certificate which the help of which hash information + can be extracted. + + Value type: <string> + +Example: + +.. code:: c + + cot { + manifests { + compatible = "arm, cert-descs” + + trusted-key-cert: trusted-key-cert { + root-certificate; + image-id = <TRUSTED_KEY_CERT_ID>; + antirollback-counter = <&trusted_nv_counter>; + + trusted-world-pk: trusted-world-pk { + oid = TRUSTED_WORLD_PK_OID; + }; + non-trusted-world-pk: non-trusted-world-pk { + oid = NON_TRUSTED_WORLD_PK_OID; + }; + }; + + scp_fw_key_cert: scp_fw_key_cert { + image-id = <SCP_FW_KEY_CERT_ID>; + parent = <&trusted-key-cert>; + signing-key = <&trusted_world_pk>; + antirollback-counter = <&trusted_nv_counter>; + + scp_fw_content_pk: scp_fw_content_pk { + oid = SCP_FW_CONTENT_CERT_PK_OID; + }; + }; + . + . + . + + next-certificate { + + }; + }; + }; + +Images and Image node bindings definition +----------------------------------------- + +- Images node + Description: Container of image nodes + + PROPERTIES + + - compatible: + Usage: required + + Value type: <string> + + Definition: must be "arm, img-descs" + +- Image node + Description: + + Describes image properties which will be used during + authentication process. + + PROPERTIES + + - image-id + Usage: Required for every image with unique id. + + Value type: <u32> + + - parent + Usage: + + Required for every image to provide a reference to + its parent image, which contains the necessary information + to authenticate it. + + Value type: <phandle> + + - hash + Usage: + + Required for all images which are validated using + hash method. This property is used to refer hash + node present in parent certificate node. + + Value type: <phandle> + + Note: + + Currently, all images are validated using 'hash' + method. In future, there may be multiple methods can + be used to validate the image. + +Example: + +.. code:: c + + cot { + images { + compatible = "arm, img-descs"; + + scp_bl2_image { + image-id = <SCP_BL2_IMAGE_ID>; + parent = <&scp_fw_content_cert>; + hash = <&scp_fw_hash>; + }; + + . + . + . + + next-img { + + }; + }; + }; + +non-volatile counter node binding definition +-------------------------------------------- + +- non-volatile counters node + Description: Contains properties for non-volatile counters. + + PROPERTIES + + - compatible: + Usage: required + + Value type: <string> + + Definition: must be "arm, non-volatile-counter" + + - #address-cells + Usage: required + + Value type: <u32> + + Definition: + + Must be set according to address size + of non-volatile counter register + + - #size-cells + Usage: required + + Value type: <u32> + + Definition: must be set to 0 + + SUBNODE + - counters node + Description: Contains various non-volatile counters present in the platform. + + PROPERTIES + - id + Usage: Required for every nv-counter with unique id. + + Value type: <u32> + + - reg + Usage: + + Register base address of non-volatile counter and it is required + property. + + Value type: <u32> + + - oid + Usage: + + This property provides the Object ID of non-volatile counter + provided in the certificate and it is required property. + + Value type: <string> + +Example: +Below is non-volatile counters example for ARM platform + +.. code:: c + + non_volatile_counters: non_volatile_counters { + compatible = "arm, non-volatile-counter"; + #address-cells = <1>; + #size-cells = <0>; + + trusted-nv-counter: trusted_nv_counter { + id = <TRUSTED_NV_CTR_ID>; + reg = <TFW_NVCTR_BASE>; + oid = TRUSTED_FW_NVCOUNTER_OID; + }; + + non_trusted_nv_counter: non_trusted_nv_counter { + id = <NON_TRUSTED_NV_CTR_ID>; + reg = <NTFW_CTR_BASE>; + oid = NON_TRUSTED_FW_NVCOUNTER_OID; + }; + }; + +Future update to chain of trust binding +--------------------------------------- + +This binding document needs to be revisited to generalise some terminologies +which are currently specific to X.509 certificates for e.g. Object IDs. + +*Copyright (c) 2020, Arm Limited. All rights reserved.* diff --git a/docs/components/debugfs-design.rst b/docs/components/debugfs-design.rst index 06916f3d9..253651513 100644 --- a/docs/components/debugfs-design.rst +++ b/docs/components/debugfs-design.rst @@ -15,8 +15,9 @@ Virtual filesystem ------------------ The core functionality lies in a virtual file system based on a 9p file server -interface (`Notes on the Plan 9 Kernel Source`_). The implementation permits -exposing virtual files, firmware drivers, and file blobs. +interface (`Notes on the Plan 9 Kernel Source`_ and +`Linux 9p remote filesystem protocol`_). +The implementation permits exposing virtual files, firmware drivers, and file blobs. Namespace ~~~~~~~~~ @@ -77,10 +78,10 @@ SMC interface ------------- The communication with the 9p layer in BL31 is made through an SMC conduit -(`SMC Calling Convention PDD`_), using a specific SiP Function Id. An NS shared -buffer is used to pass path string parameters, or e.g. to exchange data on a -read operation. Refer to `ARM SiP Services`_ for a description of the SMC -interface. +(`SMC Calling Convention`_), using a specific SiP Function Id. An NS +shared buffer is used to pass path string parameters, or e.g. to exchange +data on a read operation. Refer to :ref:`ARM SiP Services <arm sip services>` +for a description of the SMC interface. Security considerations ----------------------- @@ -114,19 +115,11 @@ The SMC interface is accessible from an NS environment, that is: - a Linux kernel driver running at NS-EL1 - a Linux userspace application through the kernel driver -References ----------- - -.. [#] `SMC Calling Convention PDD`_ -.. [#] `Notes on the Plan 9 Kernel Source`_ -.. [#] `Linux 9p remote filesystem protocol`_ -.. [#] `ARM SiP Services`_ - -------------- -*Copyright (c) 2019, Arm Limited and Contributors. All rights reserved.* +*Copyright (c) 2019-2020, Arm Limited and Contributors. All rights reserved.* -.. _SMC Calling Convention PDD: http://infocenter.arm.com/help/topic/com.arm.doc.den0028b/ +.. _SMC Calling Convention: https://developer.arm.com/docs/den0028/latest .. _Notes on the Plan 9 Kernel Source: http://lsub.org/who/nemo/9.pdf .. _Linux 9p remote filesystem protocol: https://www.kernel.org/doc/Documentation/filesystems/9p.txt .. _ARM SiP Services: arm-sip-service.rst diff --git a/docs/components/exception-handling.rst b/docs/components/exception-handling.rst index 3f386854f..6f223c675 100644 --- a/docs/components/exception-handling.rst +++ b/docs/components/exception-handling.rst @@ -10,13 +10,9 @@ of the following exceptions when targeted at EL3: - Asynchronous External Aborts |TF-A|'s handling of synchronous ``SMC`` exceptions raised from lower ELs is -described in the `Firmware Design document`__. However, the |EHF| changes the -semantics of `interrupt handling`__ and `synchronous exceptions`__ other than -SMCs. - -.. __: firmware-design.rst#handling-an-smc -.. __: `Interrupt handling`_ -.. __: `Effect on SMC calls`_ +described in the :ref:`Firmware Design document <handling-an-smc>`. However, the +|EHF| changes the semantics of `Interrupt handling`_ and :ref:`synchronous +exceptions <Effect on SMC calls>` other than SMCs. The |EHF| is selected by setting the build option ``EL3_EXCEPTION_HANDLING`` to ``1``, and is only available for AArch64 systems. @@ -77,10 +73,9 @@ On any given system, all of the above handling models may be employed independently depending on platform choice and the nature of the exception received. -.. [#spd] Not to be confused with `Secure Payload Dispatcher`__, which is an - EL3 component that operates in EL3 on behalf of Secure OS. - -.. __: firmware-design.rst#secure-el1-payloads-and-dispatchers +.. [#spd] Not to be confused with :ref:`Secure Payload Dispatcher + <firmware_design_sel1_spd>`, which is an EL3 component that operates in EL3 + on behalf of Secure OS. The role of Exception Handling Framework ---------------------------------------- @@ -139,6 +134,8 @@ unstacked in strictly the reverse order. For interrupts, the GIC ensures this is the case; for non-interrupts, the |EHF| monitors and asserts this. See `Transition of priority levels`_. +.. _interrupt-handling: + Interrupt handling ------------------ @@ -151,15 +148,12 @@ implications: sufficient priority are signalled as FIQs, and therefore will be routed to EL3. As a result, S-EL1 software cannot expect to handle Non-secure interrupts at S-EL1. Essentially, this deprecates the routing mode described - as `CSS=0, TEL3=0`__. - - .. __: interrupt-framework-design.rst#el3-interrupts + as :ref:`CSS=0, TEL3=0 <EL3 interrupts>`. In order for S-EL1 software to handle Non-secure interrupts while having |EHF| enabled, the dispatcher must adopt a model where Non-secure interrupts - are received at EL3, but are then `synchronously`__ handled over to S-EL1. - - .. __: interrupt-framework-design.rst#secure-payload + are received at EL3, but are then :ref:`synchronously <sp-synchronous-int>` + handled over to S-EL1. - On GICv2 systems, it's required that the build option ``GICV2_G0_FOR_EL3`` is set to ``1`` so that *Group 0* interrupts target EL3. @@ -176,6 +170,8 @@ dispatcher may register more than one priority level. Dispatchers are assigned interrupt priority levels in two steps: +.. _Partitioning priority levels: + Partitioning priority levels ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -237,12 +233,11 @@ The text in `Partitioning priority levels`_ only describes how the platform expresses the required levels of priority. It however doesn't choose interrupts nor program the required priority in GIC. -The `Firmware Design guide`__ explains methods for configuring secure -interrupts. |EHF| requires the platform to enumerate interrupt properties (as -opposed to just numbers) of Secure interrupts. The priority of secure interrupts -must match that as determined in the `Partitioning priority levels`_ section above. - -.. __: firmware-design.rst#configuring-secure-interrupts +The :ref:`Firmware Design guide<configuring-secure-interrupts>` explains methods +for configuring secure interrupts. |EHF| requires the platform to enumerate +interrupt properties (as opposed to just numbers) of Secure interrupts. The +priority of secure interrupts must match that as determined in the +`Partitioning priority levels`_ section above. See `Limitations`_, and also refer to `Interrupt handling example`_ for illustration. @@ -281,15 +276,13 @@ The interrupt handler should have the following signature: typedef int (*ehf_handler_t)(uint32_t intr_raw, uint32_t flags, void *handle, void *cookie); -The parameters are as obtained from the top-level `EL3 interrupt handler`__. +The parameters are as obtained from the top-level :ref:`EL3 interrupt handler +<el3-runtime-firmware>`. -.. __: interrupt-framework-design.rst#el3-runtime-firmware - -The `SDEI dispatcher`__, for example, expects the platform to allocate two -different priority levels—``PLAT_SDEI_CRITICAL_PRI``, and -``PLAT_SDEI_NORMAL_PRI``—and registers the same handler to handle both levels. - -.. __: sdei.rst +The :ref:`SDEI dispatcher<SDEI: Software Delegated Exception Interface>`, for +example, expects the platform to allocate two different priority levels— +``PLAT_SDEI_CRITICAL_PRI``, and ``PLAT_SDEI_NORMAL_PRI`` —and registers the +same handler to handle both levels. Interrupt handling example -------------------------- @@ -365,16 +358,16 @@ assign interrupts to fictitious dispatchers: See also the `Build-time flow`_ and the `Run-time flow`_. +.. _Activating and Deactivating priorities: + Activating and Deactivating priorities -------------------------------------- A priority level is said to be *active* when an exception of that priority is being handled: for interrupts, this is implied when the interrupt is -acknowledged; for non-interrupt exceptions, such as SErrors or `SDEI explicit -dispatches`__, this has to be done via calling ``ehf_activate_priority()``. See -`Run-time flow`_. - -.. __: sdei.rst#explicit-dispatch-of-events +acknowledged; for non-interrupt exceptions, such as SErrors or :ref:`SDEI +explicit dispatches <explicit-dispatch-of-events>`, this has to be done via +calling ``ehf_activate_priority()``. See `Run-time flow`_. Conversely, when the dispatcher has reached a logical resolution for the cause of the exception, the corresponding priority level ought to be deactivated. As @@ -453,6 +446,8 @@ calls to these APIs are subject to the following conditions: If these are violated, a panic will result. +.. _Effect on SMC calls: + Effect on SMC calls ------------------- @@ -467,7 +462,7 @@ SMCs from Non-secure world are synchronous exceptions, and are mechanisms for Non-secure world to request Secure services. They're broadly classified as *Fast* or *Yielding* (see `SMCCC`__). -.. __: `http://infocenter.arm.com/help/topic/com.arm.doc.den0028a/index.html` +.. __: https://developer.arm.com/docs/den0028/latest - *Fast* SMCs are atomic from the caller's point of view. I.e., they return to the caller only when the Secure world has finished serving the request. @@ -538,10 +533,8 @@ The following is an example flow for interrupts: interrupts belonging to different dispatchers. #. The |EHF|, during its initialisation, registers a top-level interrupt handler - with the `Interrupt Management Framework`__ for EL3 interrupts. This also - results in setting the routing bits in ``SCR_EL3``. - - .. __: interrupt-framework-design.rst#el3-runtime-firmware + with the :ref:`Interrupt Management Framework<el3-runtime-firmware>` for EL3 + interrupts. This also results in setting the routing bits in ``SCR_EL3``. #. When an interrupt belonging to a dispatcher fires, GIC raises an EL3/Group 0 interrupt, and is taken to EL3. @@ -621,6 +614,6 @@ The |EHF| has the following limitations: -------------- -*Copyright (c) 2018-2019, Arm Limited and Contributors. All rights reserved.* +*Copyright (c) 2018-2020, Arm Limited and Contributors. All rights reserved.* .. _SDEI specification: http://infocenter.arm.com/help/topic/com.arm.doc.den0054a/ARM_DEN0054A_Software_Delegated_Exception_Interface.pdf diff --git a/docs/components/fconf/fconf_properties.rst b/docs/components/fconf/fconf_properties.rst new file mode 100644 index 000000000..5c28a7ae5 --- /dev/null +++ b/docs/components/fconf/fconf_properties.rst @@ -0,0 +1,32 @@ +DTB binding for FCONF properties +================================ + +This document describes the device tree format of |FCONF| properties. These +properties are not related to a specific platform and can be queried from +common code. + +Dynamic configuration +~~~~~~~~~~~~~~~~~~~~~ + +The |FCONF| framework expects a *dtb-registry* node with the following field: + +- compatible [mandatory] + - value type: <string> + - Must be the string "fconf,dyn_cfg-dtb_registry". + +Then a list of subnodes representing a configuration |DTB|, which can be used +by |FCONF|. Each subnode should be named according to the information it +contains, and must be formed with the following fields: + +- load-address [mandatory] + - value type: <u64> + - Physical loading base address of the configuration. + +- max-size [mandatory] + - value type: <u32> + - Maximum size of the configuration. + +- id [mandatory] + - value type: <u32> + - Image ID of the configuration. + diff --git a/docs/components/fconf/index.rst b/docs/components/fconf/index.rst new file mode 100644 index 000000000..902063356 --- /dev/null +++ b/docs/components/fconf/index.rst @@ -0,0 +1,147 @@ +Firmware Configuration Framework +================================ + +This document provides an overview of the |FCONF| framework. + +Introduction +~~~~~~~~~~~~ + +The Firmware CONfiguration Framework (|FCONF|) is an abstraction layer for +platform specific data, allowing a "property" to be queried and a value +retrieved without the requesting entity knowing what backing store is being used +to hold the data. + +It is used to bridge new and old ways of providing platform-specific data. +Today, information like the Chain of Trust is held within several, nested +platform-defined tables. In the future, it may be provided as part of a device +blob, along with the rest of the information about images to load. +Introducing this abstraction layer will make migration easier and will preserve +functionality for platforms that cannot / don't want to use device tree. + +Accessing properties +~~~~~~~~~~~~~~~~~~~~ + +Properties defined in the |FCONF| are grouped around namespaces and +sub-namespaces: a.b.property. +Examples namespace can be: + +- (|TBBR|) Chain of Trust data: tbbr.cot.trusted_boot_fw_cert +- (|TBBR|) dynamic configuration info: tbbr.dyn_config.disable_auth +- Arm io policies: arm.io_policies.bl2_image +- GICv3 properties: hw_config.gicv3_config.gicr_base + +Properties can be accessed with the ``FCONF_GET_PROPERTY(a,b,property)`` macro. + +Defining properties +~~~~~~~~~~~~~~~~~~~ + +Properties composing the |FCONF| have to be stored in C structures. If +properties originate from a different backend source such as a device tree, +then the platform has to provide a ``populate()`` function which essentially +captures the property and stores them into a corresponding |FCONF| based C +structure. + +Such a ``populate()`` function is usually platform specific and is associated +with a specific backend source. For example, a populator function which +captures the hardware topology of the platform from the HW_CONFIG device tree. +Hence each ``populate()`` function must be registered with a specific +``config_type`` identifier. It broadly represents a logical grouping of +configuration properties which is usually a device tree file. + +Example: + - FW_CONFIG: properties related to base address, maximum size and image id + of other DTBs etc. + - TB_FW: properties related to trusted firmware such as IO policies, + mbedtls heap info etc. + - HW_CONFIG: properties related to hardware configuration of the SoC + such as topology, GIC controller, PSCI hooks, CPU ID etc. + +Hence the ``populate()`` callback must be registered to the (|FCONF|) framework +with the ``FCONF_REGISTER_POPULATOR()`` macro. This ensures that the function +would be called inside the generic ``fconf_populate()`` function during +initialization. + +:: + + int fconf_populate_topology(uintptr_t config) + { + /* read hw config dtb and fill soc_topology struct */ + } + + FCONF_REGISTER_POPULATOR(HW_CONFIG, topology, fconf_populate_topology); + +Then, a wrapper has to be provided to match the ``FCONF_GET_PROPERTY()`` macro: + +:: + + /* generic getter */ + #define FCONF_GET_PROPERTY(a,b,property) a##__##b##_getter(property) + + /* my specific getter */ + #define hw_config__topology_getter(prop) soc_topology.prop + +This second level wrapper can be used to remap the ``FCONF_GET_PROPERTY()`` to +anything appropriate: structure, array, function, etc.. + +To ensure a good interpretation of the properties, this documentation must +explain how the properties are described for a specific backend. Refer to the +:ref:`binding-document` section for more information and example. + +Loading the property device tree +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The ``fconf_load_config(image_id)`` must be called to load fw_config and +tb_fw_config devices tree containing the properties' values. This must be done +after the io layer is initialized, as the |DTB| is stored on an external +device (FIP). + +.. uml:: ../../resources/diagrams/plantuml/fconf_bl1_load_config.puml + +Populating the properties +~~~~~~~~~~~~~~~~~~~~~~~~~ + +Once a valid device tree is available, the ``fconf_populate(config)`` function +can be used to fill the C data structure with the data from the config |DTB|. +This function will call all the ``populate()`` callbacks which have been +registered with ``FCONF_REGISTER_POPULATOR()`` as described above. + +.. uml:: ../../resources/diagrams/plantuml/fconf_bl2_populate.puml + +Namespace guidance +~~~~~~~~~~~~~~~~~~ + +As mentioned above, properties are logically grouped around namespaces and +sub-namespaces. The following concepts should be considered when adding new +properties/namespaces. +The framework differentiates two types of properties: + + - Properties used inside common code. + - Properties used inside platform specific code. + +The first category applies to properties being part of the firmware and shared +across multiple platforms. They should be globally accessible and defined +inside the ``lib/fconf`` directory. The namespace must be chosen to reflect the +feature/data abstracted. + +Example: + - |TBBR| related properties: tbbr.cot.bl2_id + - Dynamic configuration information: dyn_cfg.dtb_info.hw_config_id + +The second category should represent the majority of the properties defined +within the framework: Platform specific properties. They must be accessed only +within the platform API and are defined only inside the platform scope. The +namespace must contain the platform name under which the properties defined +belong. + +Example: + - Arm io framework: arm.io_policies.bl31_id + +.. _binding-document: + +Properties binding information +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. toctree:: + :maxdepth: 1 + + fconf_properties diff --git a/docs/components/index.rst b/docs/components/index.rst index f1904c004..ffeef80e6 100644 --- a/docs/components/index.rst +++ b/docs/components/index.rst @@ -8,11 +8,17 @@ Components spd/index arm-sip-service + debugfs-design exception-handling + fconf/index firmware-update + measured_boot/index platform-interrupt-controller-API ras romlib-design sdei - secure-partition-manager-design + secure-partition-manager + secure-partition-manager-mm + psa-ffa-manifest-binding xlat-tables-lib-v2-design + cot-binding diff --git a/docs/components/measured_boot/event_log.rst b/docs/components/measured_boot/event_log.rst new file mode 100644 index 000000000..5347dcc19 --- /dev/null +++ b/docs/components/measured_boot/event_log.rst @@ -0,0 +1,35 @@ +DTB binding for Event Log properties +==================================== + +This document describes the device tree format of Event Log properties. +These properties are not related to a specific platform and can be queried +from common code. + +Dynamic configuration for Event Log +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Measured Boot driver expects a *tpm_event_log* node with the following field +in 'nt_fw_config' and 'tsp_fw_config' DTS files: + +- compatible [mandatory] + - value type: <string> + - Must be the string "arm,tpm_event_log". + +Then a list of properties representing Event Log configuration, which +can be used by Measured Boot driver. Each property is named according +to the information it contains: + +- tpm_event_log_sm_addr [fvp_nt_fw_config.dts with OP-TEE] + - value type: <u64> + - Event Log base address in secure memory. + +Note. Currently OP-TEE does not support reading DTBs from Secure memory +and this property should be removed when this feature is supported. + +- tpm_event_log_addr [mandatory] + - value type: <u64> + - Event Log base address in non-secure memory. + +- tpm_event_log_size [mandatory] + - value type: <u32> + - Event Log size. diff --git a/docs/components/measured_boot/index.rst b/docs/components/measured_boot/index.rst new file mode 100644 index 000000000..e7f2634bb --- /dev/null +++ b/docs/components/measured_boot/index.rst @@ -0,0 +1,12 @@ +Measured Boot Driver (MBD) +========================== + +.. _measured-boot-document: + +Properties binding information +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. toctree:: + :maxdepth: 1 + + event_log diff --git a/docs/components/platform-interrupt-controller-API.rst b/docs/components/platform-interrupt-controller-API.rst index 9d02f45c0..069c87b84 100644 --- a/docs/components/platform-interrupt-controller-API.rst +++ b/docs/components/platform-interrupt-controller-API.rst @@ -286,6 +286,8 @@ inserts to order memory updates before updating mask, then writes to the GIC *Priority Mask Register*, and make sure memory updates are visible before potential trigger due to mask update. +.. _plat_ic_get_interrupt_id: + Function: unsigned int plat_ic_get_interrupt_id(unsigned int raw); [optional] ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ diff --git a/docs/components/psa-ffa-manifest-binding.rst b/docs/components/psa-ffa-manifest-binding.rst new file mode 100644 index 000000000..af79074af --- /dev/null +++ b/docs/components/psa-ffa-manifest-binding.rst @@ -0,0 +1,247 @@ +PSA FF-A manifest binding to device tree +======================================== + +This document defines the nodes and properties used to define a partition, +according to the PSA FF-A specification. + +Version 1.0 +----------- + +Partition Properties +^^^^^^^^^^^^^^^^^^^^ + +- compatible [mandatory] + - value type: <string> + - Must be the string "arm,ffa-manifest-X.Y" which specifies the major and + minor versions of the device tree binding for the FFA manifest represented + by this node. The minor number is incremented if the binding changes in a + backwards compatible manner. + + - X is an integer representing the major version number of this document. + - Y is an integer representing the minor version number of this document. + +- ffa-version [mandatory] + - value type: <u32> + - Must be two 16 bits values (X, Y), concatenated as 31:16 -> X, + 15:0 -> Y, where: + + - X is the major version of PSA-FF-A expected by the partition at the FFA + instance it will execute. + - Y is the minor version of PSA-FF-A expected by the partition at the FFA + instance it will execute. + +- uuid [mandatory] + - value type: <prop-encoded-array> + - An array consisting of 4 <u32> values, identifying the UUID of the service + implemented by this partition. The UUID format is described in RFC 4122. + +- id + - value type: <u32> + - Pre-allocated partition ID. + +- auxiliary-id + - value type: <u32> + - Pre-allocated ID that could be used in memory management transactions. + +- description + - value type: <string> + - Name of the partition e.g. for debugging purposes. + +- execution-ctx-count [mandatory] + - value type: <u32> + - Number of vCPUs that a VM or SP wants to instantiate. + + - In the absence of virtualization, this is the number of execution + contexts that a partition implements. + - If value of this field = 1 and number of PEs > 1 then the partition is + treated as UP & migrate capable. + - If the value of this field > 1 then the partition is treated as a MP + capable partition irrespective of the number of PEs. + +- exception-level [mandatory] + - value type: <u32> + - The target exception level for the partition: + + - 0x0: EL1 + - 0x1: S_EL0 + - 0x2: S_EL1 + +- execution-state [mandatory] + - value type: <u32> + - The target execution state of the partition: + + - 0: AArch64 + - 1: AArch32 + +- load-address + - value type: <u64> + - Physical base address of the partition in memory. Absence of this field + indicates that the partition is position independent and can be loaded at + any address chosen at boot time. + +- entrypoint-offset + - value type: <u64> + - Offset from the base of the partition's binary image to the entry point of + the partition. Absence of this field indicates that the entry point is at + offset 0x0 from the base of the partition's binary. + +- xlat-granule [mandatory] + - value type: <u32> + - Translation granule used with the partition: + + - 0x0: 4k + - 0x1: 16k + - 0x2: 64k + +- boot-order + - value type: <u32> + - A unique number amongst all partitions that specifies if this partition + must be booted before others. The partition with the smaller number will be + booted first. + +- rx-tx-buffer + - value type: "memory-regions" node + - Specific "memory-regions" nodes that describe the RX/TX buffers expected + by the partition. + The "compatible" must be the string "arm,ffa-manifest-rx_tx-buffer". + +- messaging-method [mandatory] + - value type: <u32> + - Specifies which messaging methods are supported by the partition: + + - 0x0: direct messaging method + - 0x1: indirect messaging method + - 0x2: both direct and indirect messaging methods + +- has-primary-scheduler + - value type: <empty> + - Presence of this field indicates that the partition implements the primary + scheduler. If so, run-time EL must be EL1. + +- run-time-model + - value type: <u32> + - Run time model that the SPM must enforce for this SP: + + - 0x0: Run to completion + - 0x1: Preemptible + +- time-slice-mem + - value type: <empty> + - Presence of this field indicates that the partition doesn't expect the + partition manager to time slice long running memory management functions. + +- gp-register-num + - value type: <u32> + - Presence of this field indicates that the partition expects the + ffa_init_info structure to be passed in via the specified general purpose + register. + The field specifies the general purpose register number but not its width. + The width is derived from the partition's execution state, as specified in + the partition properties. For example, if the number value is 1 then the + general-purpose register used will be x1 in AArch64 state and w1 in AArch32 + state. + +- stream-endpoint-ids + - value type: <prop-encoded-array> + - List of <u32> tuples, identifying the IDs this partition is acting as + proxy for. + +Memory Regions +-------------- + +- compatible [mandatory] + - value type: <string> + - Must be the string "arm,ffa-manifest-memory-regions". + +- description + - value type: <string> + - Name of the memory region e.g. for debugging purposes. + +- pages-count [mandatory] + - value type: <u32> + - Count of pages of memory region as a multiple of the translation granule + size + +- attributes [mandatory] + - value type: <u32> + - Mapping modes: ORed to get required permission + + - 0x1: Read + - 0x2: Write + - 0x4: Execute + +- base-address + - value type: <u64> + - Base address of the region. The address must be aligned to the translation + granule size. + The address given may be a Physical Address (PA), Virtual Address (VA), or + Intermediate Physical Address (IPA). Refer to the FFA specification for + more information on the restrictions around the address type. + If the base address is omitted then the partition manager must map a memory + region of the specified size into the partition's translation regime and + then communicate the region properties (including the base address chosen + by the partition manager) to the partition. + +Device Regions +-------------- + +- compatible [mandatory] + - value type: <string> + - Must be the string "arm,ffa-manifest-device-regions". + +- description + - value type: <string> + - Name of the device region e.g. for debugging purposes. + +- reg [mandatory] + - value type: <prop-encoded-array> + - A (address, num-pages) pair describing the device, where: + + - address: The physical base address <u64> value of the device MMIO + region. + - num-pages: The <u32> number of pages of the region. The total size of + the region is this value multiplied by the translation granule size. + +- attributes [mandatory] + - value type: <u32> + - Mapping modes: ORed to get required permission + + - 0x1: Read + - 0x2: Write + - 0x4: Execute + +- smmu-id + - value type: <u32> + - On systems with multiple System Memory Management Units (SMMUs) this + identifier is used to inform the partition manager which SMMU the device is + upstream of. If the field is omitted then it is assumed that the device is + not upstream of any SMMU. + +- stream-ids + - value type: <prop-encoded-array> + - A list of (id, mem-manage) pair, where: + + - id: A unique <u32> value amongst all devices assigned to the partition. + +- interrupts [mandatory] + - value type: <prop-encoded-array> + - A list of (id, attributes) pair describing the device interrupts, where: + + - id: The <u32> interrupt IDs. + - attributes: A <u32> value, + containing the attributes for each interrupt ID: + + - Interrupt type: SPI, PPI, SGI + - Interrupt configuration: Edge triggered, Level triggered + - Interrupt security state: Secure, Non-secure + - Interrupt priority value + - Target execution context/vCPU for each SPI + +- exclusive-access + - value type: <empty> + - Presence of this field implies that this endpoint must be granted exclusive + access and ownership of this device's MMIO region. + +-------------- + +*Copyright (c) 2019-2020, Arm Limited and Contributors. All rights reserved.* diff --git a/docs/components/ras.rst b/docs/components/ras.rst index 3d81f17e9..02207d8b7 100644 --- a/docs/components/ras.rst +++ b/docs/components/ras.rst @@ -9,10 +9,8 @@ In conjunction with the |EHF|, support for RAS extension enables firmware-first paradigm for handling platform errors: exceptions resulting from errors are routed to and handled in EL3. Said errors are Synchronous External Abort (SEA), Asynchronous External Abort (signalled as SErrors), Fault Handling and Error -Recovery interrupts. The |EHF| document mentions various `error handling -use-cases`__. - -.. __: exception-handling.rst#delegation-use-cases +Recovery interrupts. The |EHF| document mentions various :ref:`error handling +use-cases <delegation-use-cases>` . For the description of Arm RAS extensions, Standard Error Records, and the precise definition of RAS terminology, please refer to the Arm Architecture @@ -32,7 +30,8 @@ introduced by the RAS extensions. The build option ``RAS_EXTENSION`` when set to ``1`` includes the RAS in run time firmware; ``EL3_EXCEPTION_HANDLING`` and ``HANDLE_EA_EL3_FIRST`` must also -be set ``1``. +be set ``1``. ``RAS_TRAP_LOWER_EL_ERR_ACCESS`` controls the access to the RAS +error record registers from lower ELs. .. _ras-figure: @@ -45,9 +44,7 @@ Platform APIs The RAS framework allows the platform to define handlers for External Abort, Uncontainable Errors, Double Fault, and errors rising from EL3 execution. Please -refer to the porting guide for the `RAS platform API descriptions`__. - -.. __: ../getting_started/porting-guide.rst#external-abort-handling-and-ras-support +refer to :ref:`RAS Porting Guide <External Abort handling and RAS Support>`. Registering RAS error records ----------------------------- @@ -113,9 +110,8 @@ The error handler must have the following prototype: The ``data`` constant parameter describes the various properties of the error, including the reason for the error, exception syndrome, and also ``flags``, -``cookie``, and ``handle`` parameters from the `top-level exception handler`__. - -.. __: interrupt-framework-design.rst#el3-interrupts +``cookie``, and ``handle`` parameters from the :ref:`top-level exception handler +<EL3 interrupts>`. The platform is expected populate an array using the macros above, and register the it with the RAS framework using the macro ``REGISTER_ERR_RECORD_INFO()``, @@ -228,21 +224,17 @@ Interaction with Exception Handling Framework As mentioned in earlier sections, RAS framework interacts with the |EHF| to arbitrate handling of RAS exceptions with others that are routed to EL3. This -means that the platform must partition a `priority level`__ for handling RAS -exceptions. The platform must then define the macro ``PLAT_RAS_PRI`` to the -priority level used for RAS exceptions. Platforms would typically want to -allocate the highest secure priority for RAS handling. - -.. __: exception-handling.rst#partitioning-priority-levels - -Handling of both `interrupt`__ and `non-interrupt`__ exceptions follow the -sequences outlined in the |EHF| documentation. I.e., for interrupts, the -priority management is implicit; but for non-interrupt exceptions, they're -explicit using `EHF APIs`__. - -.. __: exception-handling.rst#interrupt-flow -.. __: exception-handling.rst#non-interrupt-flow -.. __: exception-handling.rst#activating-and-deactivating-priorities +means that the platform must partition a :ref:`priority level <Partitioning +priority levels>` for handling RAS exceptions. The platform must then define +the macro ``PLAT_RAS_PRI`` to the priority level used for RAS exceptions. +Platforms would typically want to allocate the highest secure priority for +RAS handling. + +Handling of both :ref:`interrupt <interrupt-flow>` and :ref:`non-interrupt +<non-interrupt-flow>` exceptions follow the sequences outlined in the |EHF| +documentation. I.e., for interrupts, the priority management is implicit; but +for non-interrupt exceptions, they're explicit using :ref:`EHF APIs +<Activating and Deactivating priorities>`. -------------- diff --git a/docs/components/sdei.rst b/docs/components/sdei.rst index c5275a0b7..60259c830 100644 --- a/docs/components/sdei.rst +++ b/docs/components/sdei.rst @@ -205,6 +205,8 @@ will only allow SDEI calls to be made from: See the function ``sdei_client_el()`` in ``sdei_private.h``. +.. _explicit-dispatch-of-events: + Explicit dispatch of events --------------------------- diff --git a/docs/components/secure-partition-manager-design.rst b/docs/components/secure-partition-manager-mm.rst index 52b1c03e8..d53290102 100644 --- a/docs/components/secure-partition-manager-design.rst +++ b/docs/components/secure-partition-manager-mm.rst @@ -1,5 +1,20 @@ -Secure Partition Manager -************************ +Secure Partition Manager (MM) +***************************** + +Foreword +======== + +Two implementations of a Secure Partition Manager co-exist in the TF-A codebase: + +- SPM based on the PSA FF-A specification (:ref:`Secure Partition Manager`). +- SPM based on the MM interface. + +Both implementations differ in their architectures and only one can be selected +at build time. + +This document describes the latter implementation where the Secure Partition Manager +resides at EL3 and management services run from isolated Secure Partitions at S-EL0. +The communication protocol is established through the Management Mode (MM) interface. Background ========== @@ -807,13 +822,13 @@ Error Codes -------------- -*Copyright (c) 2017-2019, Arm Limited and Contributors. All rights reserved.* +*Copyright (c) 2017-2020, Arm Limited and Contributors. All rights reserved.* .. _Armv8-A ARM: https://developer.arm.com/docs/ddi0487/latest/arm-architecture-reference-manual-armv8-for-armv8-a-architecture-profile .. _instructions in the EDK2 repository: https://github.com/tianocore/edk2-staging/blob/AArch64StandaloneMm/HowtoBuild.MD .. _Management Mode Interface Specification: http://infocenter.arm.com/help/topic/com.arm.doc.den0060a/DEN0060A_ARM_MM_Interface_Specification.pdf .. _SDEI Specification: http://infocenter.arm.com/help/topic/com.arm.doc.den0054a/ARM_DEN0054A_Software_Delegated_Exception_Interface.pdf -.. _SMC Calling Convention: http://infocenter.arm.com/help/topic/com.arm.doc.den0028b/ARM_DEN0028B_SMC_Calling_Convention.pdf +.. _SMC Calling Convention: https://developer.arm.com/docs/den0028/latest .. |Image 1| image:: ../resources/diagrams/secure_sw_stack_tos.png .. |Image 2| image:: ../resources/diagrams/secure_sw_stack_sp.png diff --git a/docs/components/secure-partition-manager.rst b/docs/components/secure-partition-manager.rst new file mode 100644 index 000000000..9a65e6400 --- /dev/null +++ b/docs/components/secure-partition-manager.rst @@ -0,0 +1,873 @@ +Secure Partition Manager +************************ + +.. contents:: + +Acronyms +======== + ++--------+-----------------------------------+ +| DTB | Device Tree Blob | ++--------+-----------------------------------+ +| DTS | Device Tree Source | ++--------+-----------------------------------+ +| EC | Execution Context | ++--------+-----------------------------------+ +| FIP | Firmware Image Package | ++--------+-----------------------------------+ +| FF-A | Firmware Framework for A-class | ++--------+-----------------------------------+ +| IPA | Intermediate Physical Address | ++--------+-----------------------------------+ +| NWd | Normal World | ++--------+-----------------------------------+ +| ODM | Original Design Manufacturer | ++--------+-----------------------------------+ +| OEM | Original Equipment Manufacturer | ++--------+-----------------------------------+ +| PA | Physical Address | ++--------+-----------------------------------+ +| PE | Processing Element | ++--------+-----------------------------------+ +| PVM | Primary VM | ++--------+-----------------------------------+ +| PSA | Platform Security Architecture | ++--------+-----------------------------------+ +| SP | Secure Partition | ++--------+-----------------------------------+ +| SPM | Secure Partition Manager | ++--------+-----------------------------------+ +| SPMC | SPM Core | ++--------+-----------------------------------+ +| SPMD | SPM Dispatcher | ++--------+-----------------------------------+ +| SiP | Silicon Provider | ++--------+-----------------------------------+ +| SWd | Secure World | ++--------+-----------------------------------+ +| TLV | Tag-Length-Value | ++--------+-----------------------------------+ +| TOS | Trusted Operating System | ++--------+-----------------------------------+ +| VM | Virtual Machine | ++--------+-----------------------------------+ + +Foreword +======== + +Two implementations of a Secure Partition Manager co-exist in the TF-A codebase: + +- SPM based on the PSA FF-A specification `[1]`_. +- SPM based on the MM interface to communicate with an S-EL0 partition `[2]`_. + +Both implementations differ in their architectures and only one can be selected +at build time. + +This document: + +- describes the PSA FF-A implementation where the Secure Partition Manager + resides at EL3 and S-EL2 (or EL3 and S-EL1). +- is not an architecture specification and it might provide assumptions + on sections mandated as implementation-defined in the specification. +- covers the implications to TF-A used as a bootloader, and Hafnium + used as a reference code base for an S-EL2 secure firmware on + platforms implementing Armv8.4-SecEL2. + +Terminology +----------- + +- Hypervisor refers to the NS-EL2 component managing Virtual Machines (or + partitions) in the Normal World. +- SPMC refers to the S-EL2 component managing Virtual Machines (or Secure + Partitions) in the Secure World when Armv8.4-SecEL2 extension is implemented. +- Alternatively, SPMC can refer to an S-EL1 component, itself being a Secure + Partition and implementing the FF-A ABI on pre-Armv8.4 platforms. +- VM refers to a Normal World Virtual Machine managed by an Hypervisor. +- SP refers to a Secure World "Virtual Machine" managed by the SPMC component. + +Support for legacy platforms +---------------------------- + +In the implementation, the SPM is split into SPMD and SPMC components +(although not strictly mandated by the specification). SPMD is located +at EL3 and principally relays FF-A messages from NWd (Hypervisor or OS +kernel) to SPMC located either at S-EL1 or S-EL2. + +Hence TF-A must support both cases where SPMC is either located at: + +- S-EL1 supporting pre-Armv8.4 platforms. SPMD conveys FF-A protocol + from EL3 to S-EL1. +- S-EL2 supporting platforms implementing Armv8.4-SecEL2 extension. + SPMD conveys FF-A protocol from EL3 to S-EL2. + +The same SPMD component is used to support both configurations. The SPMC +execution level is a build time choice. + +Sample reference stack +====================== + +The following diagram illustrates a possible configuration with SPMD and SPMC, +one or multiple Secure Partitions, with or without an optional Hypervisor: + +.. image:: ../resources/diagrams/ff-a-spm-sel2.png + +TF-A build options +================== + +The following TF-A build options are provisioned: + +- **SPD=spmd**: this option selects the SPMD component to relay FF-A + protocol from NWd to SWd back and forth. It is not possible to + enable another Secure Payload Dispatcher when this option is chosen. +- **SPMD_SPM_AT_SEL2**: this option adjusts the SPMC execution + level to being S-EL1 or S-EL2. It defaults to enabled (value 1) when + SPD=spmd is chosen. +- **CTX_INCLUDE_EL2_REGS**: this option permits saving (resp. + restoring) the EL2 system register context before entering (resp. + after leaving) the SPMC. It is mandatory when ``SPMD_SPM_AT_SEL2`` is + enabled. The context save/restore routine and exhaustive list of + registers is visible at `[4]`_. +- **SP_LAYOUT_FILE**: this option provides a text description file + providing paths to SP binary images and DTS format manifests + (see `Specifying partition binary image and DT`_). It + is required when ``SPMD_SPM_AT_SEL2`` is enabled hence when multiple + secure partitions are to be loaded on behalf of SPMC. + ++------------------------------+----------------------+------------------+ +| | CTX_INCLUDE_EL2_REGS | SPMD_SPM_AT_SEL2 | ++------------------------------+----------------------+------------------+ +| SPMC at S-EL1 (e.g. OP-TEE) | 0 | 0 | ++------------------------------+----------------------+------------------+ +| SPMC at S-EL2 (e.g. Hafnium) | 1 | 1 (default when | +| | | SPD=spmd) | ++------------------------------+----------------------+------------------+ + +Other combinations of such build options either break the build or are not +supported. + +Note, the ``CTX_INCLUDE_EL2_REGS`` option provides the generic support for +barely saving/restoring EL2 registers from an Arm arch perspective. As such +it is decoupled from the ``SPD=spmd`` option. + +BL32 option is re-purposed to specify the SPMC image. It can specify either the +Hafnium binary path (built for the secure world) or the path to a TEE binary +implementing the FF-A protocol. + +BL33 option can specify either: + +- the TFTF binary or +- the Hafnium binary path (built for the normal world) if VMs were loaded by + TF-A beforehand or +- a minimal loader performing the loading of VMs and Hafnium. + +Sample TF-A build command line when SPMC is located at S-EL1 +(typically pre-Armv8.4): + +.. code:: shell + + make \ + CROSS_COMPILE=aarch64-none-elf- \ + SPD=spmd \ + SPMD_SPM_AT_SEL2=0 \ + BL32=<path-to-tee-binary> \ + BL33=<path-to-nwd-binary> \ + PLAT=fvp \ + all fip + +Sample TF-A build command line for an Armv8.4-SecEL2 enabled system +where SPMC is located at S-EL2: + +.. code:: shell + + make \ + CROSS_COMPILE=aarch64-none-elf- \ + SPD=spmd \ + CTX_INCLUDE_EL2_REGS=1 \ + ARM_ARCH_MINOR=4 \ + BL32=<path-to-swd-hafnium-binary> + BL33=<path-to-nwd-binary> \ + SP_LAYOUT_FILE=sp_layout.json \ + PLAT=fvp \ + all fip + +Build options to enable secure boot: + +.. code:: shell + + make \ + CROSS_COMPILE=aarch64-none-elf- \ + SPD=spmd \ + CTX_INCLUDE_EL2_REGS=1 \ + ARM_ARCH_MINOR=4 \ + BL32=<path-to-swd-hafnium-binary> + BL33=<path-to-nwd-binary> \ + SP_LAYOUT_FILE=../tf-a-tests/build/fvp/debug/sp_layout.json \ + MBEDTLS_DIR=<path-to-mbedtls-lib> \ + TRUSTED_BOARD_BOOT=1 \ + COT=dualroot \ + ARM_ROTPK_LOCATION=devel_rsa \ + ROT_KEY=plat/arm/board/common/rotpk/arm_rotprivk_rsa.pem \ + GENERATE_COT=1 \ + PLAT=fvp \ + all fip + +Boot process +============ + +Loading Hafnium and Secure Partitions in the secure world +--------------------------------------------------------- + +The Hafnium implementation in normal world requires VMs to be loaded in +memory prior to booting. The mechanism upon which VMs are loaded and +exposed to Hafnium are either: + +- by supplying a ramdisk image where VM images are concatenated (1) +- or by providing VM load addresses within Hafnium manifest (2) + +TF-A is the bootlader for the Hafnium and SPs in the secure world. TF-A +does not provide tooling or libraries manipulating ramdisks as required +by (1). Thus BL2 loads SPs payloads independently. +SPs may be signed by different parties (SiP, OEM/ODM, TOS vendor, etc.). +Thus they are supplied as distinct “self-contained” signed entities within +the FIP flash image. The FIP image itself is not signed hence providing +ability to upgrade SPs in the field. + +Booting through TF-A +-------------------- + +SP manifests +~~~~~~~~~~~~ + +An SP manifest describes SP attributes as defined in `[1]`_ +section 3.1 (partition manifest at virtual FF-A instance) in DTS text format. It +is represented as a single file associated with the SP. A sample is +provided by `[5]`_. A binding document is provided by `[6]`_. + +Secure Partition packages +~~~~~~~~~~~~~~~~~~~~~~~~~ + +Secure Partitions are bundled as independent package files consisting +of: + +- a header +- a DTB +- an image payload + +The header starts with a magic value and offset values to SP DTB and +image payload. Each SP package is loaded independently by BL2 loader +and verified for authenticity and integrity. + +The SP package identified by its UUID (matching FF-A uuid) is inserted +as a single entry into the FIP at end of the TF-A build flow as shown: + +.. code:: shell + + Trusted Boot Firmware BL2: offset=0x1F0, size=0x8AE1, cmdline="--tb-fw" + EL3 Runtime Firmware BL31: offset=0x8CD1, size=0x13000, cmdline="--soc-fw" + Secure Payload BL32 (Trusted OS): offset=0x1BCD1, size=0x15270, cmdline="--tos-fw" + Non-Trusted Firmware BL33: offset=0x30F41, size=0x92E0, cmdline="--nt-fw" + HW_CONFIG: offset=0x3A221, size=0x2348, cmdline="--hw-config" + TB_FW_CONFIG: offset=0x3C569, size=0x37A, cmdline="--tb-fw-config" + SOC_FW_CONFIG: offset=0x3C8E3, size=0x48, cmdline="--soc-fw-config" + TOS_FW_CONFIG: offset=0x3C92B, size=0x427, cmdline="--tos-fw-config" + NT_FW_CONFIG: offset=0x3CD52, size=0x48, cmdline="--nt-fw-config" + B4B5671E-4A90-4FE1-B81F-FB13DAE1DACB: offset=0x3CD9A, size=0xC168, cmdline="--blob" + D1582309-F023-47B9-827C-4464F5578FC8: offset=0x48F02, size=0xC168, cmdline="--blob" + +.. uml:: ../resources/diagrams/plantuml/fip-secure-partitions.puml + +Specifying partition binary image and DT +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +A description file (json format) is passed to the build flow specifying +paths to the SP binary image and associated DTS partition manifest file. +The latter is going through the dtc compiler to generate the dtb fed into +the SP package. +This file also specifies the owner of the SP, which is an optional field and +identifies the signing domain in case of dualroot CoT. +The possible owner of an SP could either be Silicon Provider or Platform, and +the corresponding "owner" field value could either be "SiP" or "Plat". +In absence of "owner" field, it defaults to "SiP". + +.. code:: shell + + { + "tee1" : { + "image": "tee1.bin", + "pm": "tee1.dts", + "owner": "SiP" + }, + + "tee2" : { + "image": "tee2.bin", + "pm": "tee2.dts", + "owner": "Plat" + } + } + +SPMC manifest +~~~~~~~~~~~~~ + +This manifest contains an SPMC attributes node consumed by SPMD at boot time. It +is implementing the description from `[1]`_ section 3.2 (SP manifest at physical +FF-A instance). The SP manifest at physical FF-A instance is used by the SPMD to +setup a SP that co-resides with the SPMC and executes at S-EL1 or Secure +Supervisor mode. + +In this implementation its usage is extended to the secure physical FF-A +instance where SPMC executes at S-EL2. + +.. code:: shell + + attribute { + spmc_id = <0x8000>; + maj_ver = <0x1>; + min_ver = <0x0>; + exec_state = <0x0>; + load_address = <0x0 0x6000000>; + entrypoint = <0x0 0x6000000>; + binary_size = <0x60000>; + }; + +- *spmc_id* defines the endpoint ID value that SPMC can query through + ``FFA_ID_GET``. +- *maj_ver/min_ver*. SPMD checks provided version versus its internal + version and aborts if not matching. +- *exec_state* defines SPMC execution state (can be AArch64 for + Hafnium, or AArch64/AArch32 for OP-TEE at S-EL1). +- *load_address* and *binary_size* are mostly used to verify secondary + entry points fit into the loaded binary image. +- *entrypoint* defines the cold boot primary core entry point used by + SPMD (currently matches ``BL32_BASE``) + +Other nodes in the manifest are consumed by Hafnium in the secure world. +A sample can be found at [7]: + +- The *chosen* node is currently unused in SWd. It is meant for NWd to + specify the init ramdisk image. +- The *hypervisor* node describes SPs. *is_ffa_partition* boolean + attribute indicates an SP. Load-addr field specifies the load address + at which TF-A loaded the SP package. +- *cpus* node provide the platform topology and allows MPIDR to VMPIDR + mapping. Notice with current implementation primary cpu is declared + first, then secondary cpus must be declared in reverse order. + +SPMC boot +~~~~~~~~~ + +The SPMC is loaded by BL2 as the BL32 image. + +The SPMC manifest is loaded by BL2 as the ``TOS_FW_CONFIG`` image. + +BL2 passes the SPMC manifest address to BL31 through a register. + +BL31(SPMD) runs from primary core, initializes the core contexts and +launches BL32 passing the SPMC manifest address through a register. + +Loading of SPs +~~~~~~~~~~~~~~ + +.. uml:: ../resources/diagrams/plantuml/bl2-loading-sp.puml + + +Notice this boot flow is an implementation sample on Arm's FVP platform. Platforms +not using FW_CONFIG would adjust to a different implementation. + +Secure boot +~~~~~~~~~~~ + +The SP content certificate is inserted as a separate FIP item so that BL2 loads SPMC, +SPMC manifest and Secure Partitions and verifies them for authenticity and integrity. +Refer to TBBR specification `[3]`_. + +The multiple-signing domain feature (in current state dual signing domain) allows +the use of two root keys namely S-ROTPK and NS-ROTPK (see `[8]`_): + +- SPMC (BL32) and SPMC manifest are signed by the SiP using the S-ROTPK. +- BL33 may be signed by the OEM using NS-ROTPK. +- An SP may be signed either by SiP (using S-ROTPK) or by OEM (using NS-ROTPK). + +Longer term multiple signing domain will allow additional signing keys, e.g. +if SPs originate from different parties. + +See `TF-A build options`_ for a sample build command line. + +Hafnium in the secure world +=========================== + +**NOTE: this section is work in progress. Descriptions and implementation choices +are subject to evolve.** + +General considerations +---------------------- + +Build platform for the secure world +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The implementation might add specific code parts only relevant to the +secure world. Such code parts might be isolated into different files +and/or conditional code enclosed by a ``SECURE_WORLD`` macro. + +Secure Partitions CPU scheduling +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +In the normal world, VMs are scheduled by the FFA_RUN ABI invoked from the +primary scheduler (in the primary VM), or by a direct message request or +response. + +With the FF-A EAC specification, Secure Partitions are scheduled by direct +message invocations from a NWd VM or another SP. + +Platform topology +~~~~~~~~~~~~~~~~~ + +As stated in `[1]`_ section 4.4.1 the SPMC implementation assumes the +following SP types: + +- Pinned MP SPs: an Execution Context id matches a physical PE id. MP + SPs must implement the same number of ECs as the number of PEs in the + platform. Hence the *execution-ctx-count* as defined by + `[1]`_ (or NWd-Hafnium *vcpu_count*) can only take the + value of one or the number of physical PEs. +- Migratable UP SPs: a single execution context can run and be migrated + on any physical PE. It declares a single EC in its SP manifest. An UP + SP can receive a direct message request on any physical core. + +Usage of PSCI services in the secure world +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +- The normal world Hypervisor (optional) or OS kernel issues PSCI service + invocations e.g. to request PSCI version, wake-up a secondary core, or request + core suspend. This happens at the non-secure physical FF-A instance. In the + example case of Hafnium in the normal world, it boots on the primary core and + one of the first initialization step is to request the PSCI version. It then + launches the primary VM. The primary VM upon initializing performs PSCI service + calls (at non-secure virtual FF-A instance) which are trapped by the + Hypervisor. Invocation from OS Kernel ends straight at EL3. The PVM issues + ``PSCI_CPU_ON`` service calls to wake-up secondary cores by passing an + ``MPIDR``, entry point address and a CPU context address. The EL3 PSCI layer + then performs an exception return to the secondary core entry point on the + targeted core. Other PSCI calls can happen at run-time from the PVM e.g. to + request core suspend. +- In the existing TF-A PSCI standard library, PSCI service calls are filtered at + EL3 to only originate from the NWd. Thus concerning the SPMC (at secure + physical FF-A instance) the PSCI service invocations cannot happen as in the + normal world. For example, a ``PSCI_CPU_ON`` service invocation from the SPMC + does not reach the PSCI layer. + +Parsing SP partition manifests +------------------------------ + +Hafnium must be able to consume SP manifests as defined in +`[1]`_ section 3.1, at least for the mandatory fields. + +The SP manifest may contain memory and device regions nodes. + +- Memory regions shall be mapped in the SP Stage-2 translation regime at + load time. A memory region node can specify RX/TX buffer regions in which + case it is not necessary for an SP to explicitly call the ``FFA_RXTX_MAP`` + service. +- Device regions shall be mapped in SP Stage-2 translation regime as + peripherals and possibly allocate additional resources (e.g. interrupts) + +Base addresses for memory and device region nodes are IPAs provided SPMC +identity maps IPAs to PAs within SP Stage-2 translation regime. + +Note: currently both VTTBR_EL2 and VSTTBR_EL2 resolve to the same set of page +tables. It is still open whether two sets of page tables shall be provided per +SP. The memory region node as defined in the spec (section 3.1 Table 10) +provides a memory security attribute hinting to map either to the secure or +non-secure stage-2 table. + +Passing boot data to the SP +--------------------------- + +`[1]`_ Section 3.4.2 “Protocol for passing data” defines a +method to passing boot data to SPs (not currently implemented). + +Provided that the whole Secure Partition package image (see `Secure +Partition packages`_) is mapped to the SP's secure Stage-2 translation +regime, an SP can access its own manifest DTB blob and extract its partition +manifest properties. + +SP Boot order +------------- + +SP manifests provide an optional boot order attribute meant to resolve +dependencies such as an SP providing a service required to properly boot +another SP. + +Boot phases +----------- + +Primary core boot-up +~~~~~~~~~~~~~~~~~~~~ + +The SPMC performs its platform initializations then loads and creates +secure partitions based on SP packages and manifests. Then each secure +partition is launched in sequence (see `SP Boot order`_) on their primary +Execution Context. + +Notice the primary physical core may not be core 0. Hence if the primary +core linear id is N, the 1:1 mapping requires MP SPs are launched using +EC[N] on PE[N] (see `Platform topology`_). + +The SP's primary Execution Context (or the EC used when the partition is booted) +exits through ``FFA_MSG_WAIT`` to indicate successful initialization. + +Secondary physical core boot-up +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Upon boot-up, the SPMC running on the primary core performs +implementation-defined SPMD service calls at secure physical FF-A instance +to register the secondary physical cores entry points and context information: + +- This is done through a direct message request invocation to the SPMD + (``SET_ENTRY_POINT``). This service call does not wake-up the targeted + core immediately. The secondary core is woken up later by a NWd + ``PSCI_CPU_ON`` service invocation. A notification is passed from EL3 + PSCI layer to the SPMD, and then to SPMC through an implementation-defined + interface. +- The SPMC/SPMD interface can consist of FF-A direct message requests/responses + transporting PM events. + +If there is no Hypervisor in the normal world, the OS Kernel issues +``PSCI_CPU_ON`` calls that are directly trapped to EL3. + +When a secondary physical core wakes-up the SPMD notifies the SPMC which updates +its internal states reflecting current physical core is being turned on. +It might then return straight to the SPMD and then to the NWd. + +*(under discussion)* There may be possibility that an SP registers "PM events" +(during primary EC boot stage) through an ad-hoc interface. Such events would +be relayed by SPMC to one or more registered SPs on need basis +(see `Power management`_). + +Secondary virtual core boot-up +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +In the example case where Hafnium exists in the normal world, secondary VMs +issue a ``PSCI_CPU_ON`` service call which is trapped to the Hypervisor. The +latter then enables the vCPU context for the targeted core, and switches to +the PVM down to the kernel driver with an ``HF_WAKE_UP`` message. The NWd +driver in PVM can then schedule the newly woken up vCPU context. + +In the secure world the primary EC of a given SP passes the secondary EC entry +point and context. The SMC service call is trapped into the SPMC. This can be +either *(under discussion)*: + +- a specific interface registering the secondary EC entry point, + similarly to above ``SET_ENTRY_POINT`` service. +- Re-purposing the ``PSCI_CPU_ON`` function id. It is + assumed that even if the input arguments are the same as the ones defined in + the PSCI standard, the usage deviates by the fact the secondary EC is not + woken up immediately. At least for the PSA-FF-A EAC where only + direct messaging is allowed, it is only after the first direct + message invocation that the secondary EC is entered. This option + might be preferred when the same code base is re-used for a VM or + an SP. The ABI to wake-up a secondary EC can remain similar. + +SPs are always scheduled from the NWd, this paradigm did not change from legacy +TEEs. There must always be some logic (or driver) in the NWd to relinquish CPU +cycles to the SWd. If primary core is 0, an SP EC[x>0] entry point is supplied +by the SP EC[0] when the system boots in SWd. But this EC[x] is not immediately +entered at boot. Later in the boot process when NWd is up, a direct message +request issued from physical core 1 ends up in SP EC[1], and only at this stage +this context is effectively scheduled. + +It should be possible for an SP to call into another SP through direct message +provided the latter SP has been booted already. The "boot-order" field in +partition manifests (`SP Boot order`_) fulfills the dependency towards availability +of a service within an SP offered to another SP. + +Mandatory interfaces +-------------------- + +The following interfaces must be exposed to any VM or SP: + +- ``FFA_STATUS`` +- ``FFA_ERROR`` +- ``FFA_INTERRUPT`` +- ``FFA_VERSION`` +- ``FFA_FEATURES`` +- ``FFA_RX_RELEASE`` +- ``FFA_RXTX_MAP`` +- ``FFA_RXTX_UNMAP`` +- ``FFA_PARTITION_INFO_GET`` +- ``FFA_ID_GET`` + +FFA_VERSION +~~~~~~~~~~~ + +Per `[1]`_ section 8.1 ``FFA_VERSION`` requires a +*requested_version* parameter from the caller. + +In the current implementation when ``FFA_VERSION`` is invoked from: + +- Hypervisor in NS-EL2: the SPMD returns the SPMC version specified + in the SPMC manifest. +- OS kernel in NS-EL1 when NS-EL2 is not present: the SPMD returns the + SPMC version specified in the SPMC manifest. +- VM in NWd: the Hypervisor returns its implemented version. +- SP in SWd: the SPMC returns its implemented version. +- SPMC at S-EL1/S-EL2: the SPMD returns its implemented version. + +FFA_FEATURES +~~~~~~~~~~~~ + +FF-A features may be discovered by Secure Partitions while booting +through the SPMC. However, SPMC cannot get features from Hypervisor +early at boot time as NS world is not setup yet. + +The Hypervisor may decide to gather FF-A features from SPMC through SPMD +once at boot time and store the result. Later when a VM requests FF-A +features, the Hypervisor can adjust its own set of features with what +SPMC advertised, if necessary. Another approach is to always forward FF-A +features to the SPMC when a VM requests it to the Hypervisor. Although +the result is not supposed to change over time so there may not be added +value doing the systematic forwarding. + +FFA_RXTX_MAP/FFA_RXTX_UNMAP +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +VM mailboxes are re-purposed to serve as SP RX/TX buffers. The RX/TX +map API maps the send and receive buffer IPAs to the SP Stage-2 translation regime. + +Hafnium in the normal world defines VMs and their attributes as logical structures, +including a mailbox used for FF-A indirect messaging, memory sharing, or the +`FFA_PARTITION_INFO_GET`_ ABI. +This same mailbox structure is re-used in the SPMC. `[1]`_ states only direct +messaging is allowed to SPs. Thus mailbox usage is restricted to implementing +`FFA_PARTITION_INFO_GET`_ and memory sharing ABIs. + +FFA_PARTITION_INFO_GET +~~~~~~~~~~~~~~~~~~~~~~ + +Partition info get service call can originate: + +- from SP to SPM +- from VM to Hypervisor +- from Hypervisor to SPM + +For the latter case, the service call must be forwarded through the SPMD. + +FFA_ID_GET +~~~~~~~~~~ + +The SPMD returns: + +- a default zero value on invocation from the Hypervisor. +- The ``spmc_id`` value specified in the SPMC manifest on invocation from + the SPMC (see `SPMC manifest`_) + +The FF-A id space is split into a non-secure space and secure space: + +- FF-A id with bit 15 clear refer to normal world VMs. +- FF-A id with bit 15 set refer to secure world SPs + +Such convention helps the SPMC discriminating the origin and destination worlds +in an FF-A service invocation. In particular the SPMC shall filter unauthorized +transactions in its world switch routine. It must not be permitted for a VM to +use a secure FF-A id as origin world through spoofing: + +- A VM-to-SP messaging passing shall have an origin world being non-secure + (FF-A id bit 15 clear) and destination world being secure (FF-A id bit 15 + set). +- Similarly, an SP-to-SP message shall have FF-A id bit 15 set for both origin + and destination ids. + +An incoming direct message request arriving at SPMD from NWd is forwarded to +SPMC without a specific check. The SPMC is resumed through eret and "knows" the +message is coming from normal world in this specific code path. Thus the origin +endpoint id must be checked by SPMC for being a normal world id. + +An SP sending a direct message request must have bit 15 set in its origin +endpoint id and this can be checked by the SPMC when the SP invokes the ABI. + +The SPMC shall reject the direct message if the claimed world in origin endpoint +id is not consistent: + +- It is either forwarded by SPMD and thus origin endpoint id must be a "normal + world id", +- or initiated by an SP and thus origin endpoint id must be a "secure world id". + +Direct messaging +---------------- + +This is a mandatory interface for Secure Partitions consisting in direct +message request and responses. + +The ``ffa_handler`` Hafnium function may: + +- trigger a world change e.g. when an SP invokes the direct message + response ABI to a VM. +- handle multiple requests from the NWd without resuming an SP. + +SP-to-SP +~~~~~~~~ + +- An SP can send a direct message request to another SP +- An SP can receive a direct message response from another SP. + +VM-to-SP +~~~~~~~~ + +- A VM can send a direct message request to an SP +- An SP can send a direct message response to a VM + +SPMC-SPMD messaging +~~~~~~~~~~~~~~~~~~~ + +Specific implementation-defined endpoint IDs are allocated to the SPMC and SPMD. +Referring those IDs in source/destination fields of a direct message +request/response permits SPMD to SPMC messaging back and forth. + +Per `[1]`_ Table 114 Config No. 1 (physical FF-A instance): + +- SPMC=>SPMD direct message request uses SMC conduit +- SPMD=>SPMC direct message request uses ERET conduit + +Per `[1]`_ Table 118 Config No. 1 (physical FF-A instance): + +- SPMC=>SPMD direct message response uses SMC conduit +- SPMD=>SPMC direct message response uses ERET conduit + +Memory management +----------------- + +This section only deals with the PE MMU configuration. + +Hafnium in the normal world deals with NS buffers only and provisions +a single root page table directory to VMs. In context of S-EL2 enabled +firmware, two IPA spaces are output from Stage-1 translation (secure +and non-secure). The Stage-2 translation handles: + +- A single secure IPA space when an SP Stage-1 MMU is disabled. +- Two IPA spaces (secure and non-secure) when Stage-1 MMU is enabled. + +``VTCR_EL2`` and ``VSTCR_EL2`` provide additional bits for controlling the +NS/S IPA translations (``VSTCR_EL2.SW``, ``VSTCR_EL2.SA``, ``VTCR_EL2.NSW``, +``VTCR_EL2.NSA``). There may be two approaches: + +- secure and non-secure mappings are rooted as two separate root page + tables +- secure and non-secure mappings use the same root page table. Access + from S-EL1 to an NS region translates to a secure physical address + space access. + +Interrupt management +-------------------- + +Road to a para-virtualized interface +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Current Hafnium implementation uses an ad-hoc mechanism for a VM to get +a pending interrupt number through an hypercall. The PVM injects +interrupts to VMs by delegation from the Hypervisor. The PVM probes a +pending interrupt directly from the GIC distributor. + +The short-term plan is to have Hafnium/SPMC in the secure world owner +of the GIC configuration. + +The SPMC fully owns the GIC configuration at S-EL2. The SPMC manages +interrupt resources and allocates interrupt ID based on SP manifests. +The SPMC acknowledges physical interrupts and injects virtual interrupts +by setting the vIRQ bit when resuming an SP. A Secure Partition gathers +the interrupt number through an hypercall. + +Notice the SPMC/SPMD has to handle Group0 secure interrupts in addition +to Group1 S/NS interrupts. + +Power management +---------------- + +Assumption on the Nwd: + +- NWd is the best candidate to own the platform Power Management + policy. It is master to invoking PSCI service calls from physical + CPUs. +- EL3 monitor is in charge of the PM control part (its PSCI layer + actually writing to platform registers). +- It is fine for the Hypervisor to trap PSCI calls and relay to EL3, or + OS kernel driver to emit PSCI service calls. + +PSCI notification are relayed through the SPMD/SPD PM hooks to the SPMC. +This can either be through re-use of PSCI FIDs or an FF-A direct message +from SPMD to SPMC. + +The SPMD performs an exception return to the SPMC which is resumed to +its ``eret_handler`` routine. It is then either consuming a PSCI FID or +an FF-A FID. Depending on the servicing, the SPMC may return directly to +the SPMD (and then NWd) without resuming an SP at this stage. An example +of this is invocation of ``FFA_PARTITION_INFO_GET`` from NWd relayed by +the SPMD to the SPMC. The SPMC returns the needed partition information +to the SPMD (then NWd) without actually resuming a partition in secure world. + +*(under discussion)* +About using PSCI FIDs from SPMD to SPMC to notify of PM events, it is still +questioned what to use as the return code from the SPMC. +If the function ID used by the SPMC is not an FF-A ID when doing SMC, then the +EL3 std svc handler won't route the response to the SPMD. That's where comes the +idea to embed the notification into an FF-A message. The SPMC can discriminate +this message as being a PSCI event, process it, and reply with an FF-A return +message that the SPMD receives as an acknowledgement. + +SP notification +--------------- + +Power management notifications are conveyed from PSCI library to the +SPMD / SPD hooks. A range of events can be relayed to SPMC. + +SPs may need to be notified about specific PM events. + +- SPs might register PM events to the SPMC +- On SPMD to SPMC notification, a limited range of SPs may be notified + through a direct message. +- This assumes the mentioned SPs supports managed exit. + +The SPMC is the first to be notified about PM events from the SPMD. It is up +to the SPMC to arbitrate to which SP it needs to send PM events. +An SP explicitly registers to receive notifications to specific PM events. +The register operation can either be an implementation-defined service call +to the SPMC when the primary SP EC boots, or be supplied through the SP +manifest. + +References +========== + +.. _[1]: + +[1] `Platform Security Architecture Firmware Framework for Arm® v8-A 1.0 Platform Design Document <https://developer.arm.com/docs/den0077/latest>`__ + +.. _[2]: + +[2] :ref:`Secure Partition Manager using MM interface<Secure Partition Manager (MM)>` + +.. _[3]: + +[3] `Trusted Boot Board Requirements +Client <https://developer.arm.com/docs/den0006/latest/trusted-board-boot-requirements-client-tbbr-client-armv8-a>`__ + +.. _[4]: + +[4] https://git.trustedfirmware.org/TF-A/trusted-firmware-a.git/tree/lib/el3_runtime/aarch64/context.S#n45 + +.. _[5]: + +[5] https://git.trustedfirmware.org/TF-A/tf-a-tests.git/tree/spm/cactus/cactus.dts + +.. _[6]: + +[6] https://trustedfirmware-a.readthedocs.io/en/latest/components/psa-ffa-manifest-binding.html + +.. _[7]: + +[7] https://git.trustedfirmware.org/TF-A/trusted-firmware-a.git/tree/plat/arm/board/fvp/fdts/fvp_spmc_manifest.dts + +.. _[8]: + +[8] https://developer.trustedfirmware.org/w/tf_a/poc-multiple-signing-domains/ + +-------------- + +*Copyright (c) 2020, Arm Limited and Contributors. All rights reserved.* diff --git a/docs/design/auth-framework.rst b/docs/design/auth-framework.rst index 93f691b7b..6913e66e1 100644 --- a/docs/design/auth-framework.rst +++ b/docs/design/auth-framework.rst @@ -619,11 +619,13 @@ recommended to read this guide along with the source code. The TBBR CoT ~~~~~~~~~~~~ -The CoT can be found in ``drivers/auth/tbbr/tbbr_cot.c``. This CoT consists of -an array of pointers to image descriptors and it is registered in the framework -using the macro ``REGISTER_COT(cot_desc)``, where 'cot_desc' must be the name -of the array (passing a pointer or any other type of indirection will cause the -registration process to fail). +CoT specific to BL1 and BL2 can be found in ``drivers/auth/tbbr/tbbr_cot_bl1.c`` +and ``drivers/auth/tbbr/tbbr_cot_bl2.c`` respectively. The common CoT used across +BL1 and BL2 can be found in ``drivers/auth/tbbr/tbbr_cot_common.c``. +This CoT consists of an array of pointers to image descriptors and it is +registered in the framework using the macro ``REGISTER_COT(cot_desc)``, where +``cot_desc`` must be the name of the array (passing a pointer or any other +type of indirection will cause the registration process to fail). The number of images participating in the boot process depends on the CoT. There is, however, a minimum set of images that are mandatory in TF-A and thus @@ -702,7 +704,7 @@ Each image descriptor must specify: address/size to store the parameter. The CoT is responsible for allocating the required memory to store the parameters. This pointer may be NULL. -In the ``tbbr_cot.c`` file, a set of buffers are allocated to store the parameters +In the ``tbbr_cot*.c`` file, a set of buffers are allocated to store the parameters extracted from the certificates. In the case of the TBBR CoT, these parameters are hashes and public keys. In DER format, an RSA-4096 public key requires 550 bytes, and a hash requires 51 bytes. Depending on the CoT and the authentication @@ -870,32 +872,32 @@ Once the signature has been checked and the certificate authenticated, the Trusted World public key needs to be extracted from the certificate. A new entry is created in the ``authenticated_data`` array for that purpose. In that entry, the corresponding parameter descriptor must be specified along with the buffer -address to store the parameter value. In this case, the ``tz_world_pk`` descriptor -is used to extract the public key from an x509v3 extension with OID +address to store the parameter value. In this case, the ``trusted_world_pk`` +descriptor is used to extract the public key from an x509v3 extension with OID ``TRUSTED_WORLD_PK_OID``. The BL31 key certificate will use this descriptor as parameter in the signature authentication method. The key is stored in the -``plat_tz_world_pk_buf`` buffer. +``trusted_world_pk_buf`` buffer. The **BL31 Key certificate** is authenticated by checking its digital signature using the Trusted World public key obtained previously from the Trusted Key certificate. In the image descriptor, we specify a single authentication method -by signature whose public key is the ``tz_world_pk``. Once this certificate has -been authenticated, we have to extract the BL31 public key, stored in the -extension specified by ``bl31_content_pk``. This key will be copied to the -``plat_content_pk`` buffer. +by signature whose public key is the ``trusted_world_pk``. Once this certificate +has been authenticated, we have to extract the BL31 public key, stored in the +extension specified by ``soc_fw_content_pk``. This key will be copied to the +``content_pk_buf`` buffer. The **BL31 certificate** is authenticated by checking its digital signature using the BL31 public key obtained previously from the BL31 Key certificate. -We specify the authentication method using ``bl31_content_pk`` as public key. +We specify the authentication method using ``soc_fw_content_pk`` as public key. After authentication, we need to extract the BL31 hash, stored in the extension -specified by ``bl31_hash``. This hash will be copied to the ``plat_bl31_hash_buf`` -buffer. +specified by ``soc_fw_hash``. This hash will be copied to the +``soc_fw_hash_buf`` buffer. The **BL31 image** is authenticated by calculating its hash and matching it with the hash obtained from the BL31 certificate. The image descriptor contains a single authentication method by hash. The parameters to the hash method are -the reference hash, ``bl31_hash``, and the data to be hashed. In this case, it is -the whole image, so we specify ``raw_data``. +the reference hash, ``soc_fw_hash``, and the data to be hashed. In this case, +it is the whole image, so we specify ``raw_data``. The image parser library ~~~~~~~~~~~~~~~~~~~~~~~~ @@ -934,7 +936,7 @@ i.e. verify a hash or a digital signature. Arm platforms will use a library based on mbed TLS, which can be found in ``drivers/auth/mbedtls/mbedtls_crypto.c``. This library is registered in the authentication framework using the macro ``REGISTER_CRYPTO_LIB()`` and exports -three functions: +four functions: .. code:: c @@ -945,6 +947,11 @@ three functions: void *pk_ptr, unsigned int pk_len); int verify_hash(void *data_ptr, unsigned int data_len, void *digest_info_ptr, unsigned int digest_info_len); + int auth_decrypt(enum crypto_dec_algo dec_algo, void *data_ptr, + size_t len, const void *key, unsigned int key_len, + unsigned int key_flags, const void *iv, + unsigned int iv_len, const void *tag, + unsigned int tag_len) The mbedTLS library algorithm support is configured by both the ``TF_MBEDTLS_KEY_ALG`` and ``TF_MBEDTLS_KEY_SIZE`` variables. @@ -957,6 +964,9 @@ The mbedTLS library algorithm support is configured by both the - ``TF_MBEDTLS_KEY_SIZE`` sets the supported RSA key size for TFA. Valid values include 1024, 2048, 3072 and 4096. +- ``TF_MBEDTLS_USE_AES_GCM`` enables the authenticated decryption support based + on AES-GCM algorithm. Valid values are 0 and 1. + .. note:: If code size is a concern, the build option ``MBEDTLS_SHA256_SMALLER`` can be defined in the platform Makefile. It will make mbed TLS use an @@ -965,6 +975,6 @@ The mbedTLS library algorithm support is configured by both the -------------- -*Copyright (c) 2017-2019, Arm Limited and Contributors. All rights reserved.* +*Copyright (c) 2017-2020, Arm Limited and Contributors. All rights reserved.* .. _TBBR-Client specification: https://developer.arm.com/docs/den0006/latest/trusted-board-boot-requirements-client-tbbr-client-armv8-a diff --git a/docs/design/cpu-specific-build-macros.rst b/docs/design/cpu-specific-build-macros.rst index f3096b418..7c142d132 100644 --- a/docs/design/cpu-specific-build-macros.rst +++ b/docs/design/cpu-specific-build-macros.rst @@ -127,6 +127,9 @@ For Cortex-A53, the following errata build flags are defined : Earlier revisions of the CPU have other errata which require the same workaround in software, so they should be covered anyway. +- ``ERRATA_A53_1530924``: This applies errata 1530924 workaround to all + revisions of Cortex-A53 CPU. + For Cortex-A55, the following errata build flags are defined : - ``ERRATA_A55_768277``: This applies errata 768277 workaround to Cortex-A55 @@ -147,6 +150,9 @@ For Cortex-A55, the following errata build flags are defined : - ``ERRATA_A55_1221012``: This applies errata 1221012 workaround to Cortex-A55 CPU. This needs to be enabled only for revision <= r1p0 of the CPU. +- ``ERRATA_A55_1530923``: This applies errata 1530923 workaround to all + revisions of Cortex-A55 CPU. + For Cortex-A57, the following errata build flags are defined : - ``ERRATA_A57_806969``: This applies errata 806969 workaround to Cortex-A57 @@ -182,12 +188,17 @@ For Cortex-A57, the following errata build flags are defined : - ``ERRATA_A57_859972``: This applies errata 859972 workaround to Cortex-A57 CPU. This needs to be enabled only for revision <= r1p3 of the CPU. +- ``ERRATA_A57_1319537``: This applies errata 1319537 workaround to all + revisions of Cortex-A57 CPU. For Cortex-A72, the following errata build flags are defined : - ``ERRATA_A72_859971``: This applies errata 859971 workaround to Cortex-A72 CPU. This needs to be enabled only for revision <= r0p3 of the CPU. +- ``ERRATA_A72_1319367``: This applies errata 1319367 workaround to all + revisions of Cortex-A72 CPU. + For Cortex-A73, the following errata build flags are defined : - ``ERRATA_A73_852427``: This applies errata 852427 workaround to Cortex-A73 @@ -227,11 +238,39 @@ For Cortex-A76, the following errata build flags are defined : - ``ERRATA_A76_1275112``: This applies errata 1275112 workaround to Cortex-A76 CPU. This needs to be enabled only for revision <= r3p0 of the CPU. -For Hercules, the following errata build flags are defined : +- ``ERRATA_A76_1791580``: This applies errata 1791580 workaround to Cortex-A76 + CPU. This needs to be enabled only for revision <= r4p0 of the CPU. + +- ``ERRATA_A76_1165522``: This applies errata 1165522 workaround to all + revisions of Cortex-A76 CPU. This errata is fixed in r3p0 but due to + limitation of errata framework this errata is applied to all revisions + of Cortex-A76 CPU. + +- ``ERRATA_A76_1868343``: This applies errata 1868343 workaround to Cortex-A76 + CPU. This needs to be enabled only for revision <= r4p0 of the CPU. -- ``ERRATA_HERCULES_1688305``: This applies errata 1688305 workaround to - Hercules CPU. This needs to be enabled only for revision r0p0 - r1p0 of - the CPU. +- ``ERRATA_A76_1946160``: This applies errata 1946160 workaround to Cortex-A76 + CPU. This needs to be enabled only for revisions r3p0 - r4p1 of the CPU. + +For Cortex-A77, the following errata build flags are defined : + +- ``ERRATA_A77_1508412``: This applies errata 1508412 workaround to Cortex-A77 + CPU. This needs to be enabled only for revision <= r1p0 of the CPU. + +- ``ERRATA_A77_1925769``: This applies errata 1925769 workaround to Cortex-A77 + CPU. This needs to be enabled only for revision <= r1p1 of the CPU. + +For Cortex-A78, the following errata build flags are defined : + +- ``ERRATA_A78_1688305``: This applies errata 1688305 workaround to Cortex-A78 + CPU. This needs to be enabled only for revision r0p0 - r1p0 of the CPU. + +- ``ERRATA_A78_1941498``: This applies errata 1941498 workaround to Cortex-A78 + CPU. This needs to be enabled for revisions r0p0, r1p0, and r1p1 of the CPU. + +- ``ERRATA_A78_1951500``: This applies errata 1951500 workaround to Cortex-A78 + CPU. This needs to be enabled for revisions r1p0 and r1p1, r0p0 has the same + issue but there is no workaround for that revision. For Neoverse N1, the following errata build flags are defined : @@ -268,6 +307,13 @@ For Neoverse N1, the following errata build flags are defined : - ``ERRATA_N1_1542419``: This applies errata 1542419 workaround to Neoverse-N1 CPU. This needs to be enabled only for revisions r3p0 - r4p0 of the CPU. +- ``ERRATA_N1_1868343``: This applies errata 1868343 workaround to Neoverse-N1 + CPU. This needs to be enabled only for revision <= r4p0 of the CPU. + +- ``ERRATA_N1_1946160``: This applies errata 1946160 workaround to Neoverse-N1 + CPU. This needs to be enabled for revisions r3p0, r3p1, r4p0, and r4p1, for + revisions r0p0, r1p0, and r2p0 there is no workaround. + DSU Errata Workarounds ---------------------- @@ -324,14 +370,22 @@ architecture that can be enabled by the platform as desired. as recommended in section "4.7 Non-Temporal Loads/Stores" of the `Cortex-A57 Software Optimization Guide`_. -- ``NEOVERSE_N1_EXTERNAL_LLC``: This flag indicates that an external last +- ''A57_ENABLE_NON_CACHEABLE_LOAD_FWD'': This flag enables non-cacheable + streaming enhancement feature for Cortex-A57 CPUs. Platforms can set + this bit only if their memory system meets the requirement that cache + line fill requests from the Cortex-A57 processor are atomic. Each + Cortex-A57 based platform must make its own decision on whether to use + the optimization. This flag is disabled by default. + +- ``NEOVERSE_Nx_EXTERNAL_LLC``: This flag indicates that an external last level cache(LLC) is present in the system, and that the DataSource field on the master CHI interface indicates when data is returned from the LLC. This is used to control how the LL_CACHE* PMU events count. + Default value is 0 (Disabled). -------------- -*Copyright (c) 2014-2019, Arm Limited and Contributors. All rights reserved.* +*Copyright (c) 2014-2020, Arm Limited and Contributors. All rights reserved.* .. _CVE-2017-5715: http://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2017-5715 .. _CVE-2018-3639: http://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2018-3639 diff --git a/docs/design/firmware-design.rst b/docs/design/firmware-design.rst index 5fc1335b3..c12e73f45 100644 --- a/docs/design/firmware-design.rst +++ b/docs/design/firmware-design.rst @@ -83,6 +83,10 @@ Each of the Boot Loader stages may be dynamically configured if required by the platform. The Boot Loader stage may optionally specify a firmware configuration file and/or hardware configuration file as listed below: +- FW_CONFIG - The firmware configuration file. Holds properties shared across + all BLx images. + An example is the "dtb-registry" node, which contains the information about + the other device tree configurations (load-address, size, image_id). - HW_CONFIG - The hardware configuration file. Can be shared by all Boot Loader stages and also by the Normal World Rich OS. - TB_FW_CONFIG - Trusted Boot Firmware configuration file. Shared between BL1 @@ -109,8 +113,8 @@ convention: the generic hardware configuration is passed the next available argument. For example, - - If TB_FW_CONFIG is loaded by BL1, then its address is passed in ``arg0`` - to BL2. + - FW_CONFIG is loaded by BL1, then its address is passed in ``arg0`` to BL2. + - TB_FW_CONFIG address is retrieved by BL2 from FW_CONFIG device tree. - If HW_CONFIG is loaded by BL1, then its address is passed in ``arg2`` to BL2. Note, ``arg1`` is already used for meminfo_t. - If SOC_FW_CONFIG is loaded by BL2, then its address is passed in ``arg1`` @@ -365,7 +369,7 @@ Architectural initialization For AArch64, BL2 performs the minimal architectural initialization required for subsequent stages of TF-A and normal world software. EL1 and EL0 are given -access to Floating Point and Advanced SIMD registers by clearing the +access to Floating Point and Advanced SIMD registers by setting the ``CPACR.FPEN`` bits. For AArch32, the minimal architectural initialization required for subsequent @@ -544,7 +548,7 @@ It then replaces the exception vectors populated by BL1 with its own. BL31 exception vectors implement more elaborate support for handling SMCs since this is the only mechanism to access the runtime services implemented by BL31 (PSCI for example). BL31 checks each SMC for validity as specified by the -`SMC Calling Convention PDD`_ before passing control to the required SMC +`SMC Calling Convention`_ before passing control to the required SMC handler routine. BL31 programs the ``CNTFRQ_EL0`` register with the clock frequency of the system @@ -953,6 +957,8 @@ Function ID call type and OEN onto a specific service handler in the |Image 1| +.. _handling-an-smc: + Handling an SMC ~~~~~~~~~~~~~~~ @@ -984,7 +990,7 @@ before restoring the stack and CPU state and returning from the original SMC. Exception Handling Framework ---------------------------- -Please refer to the `Exception Handling Framework`_ document. +Please refer to the :ref:`Exception Handling Framework` document. Power State Coordination Interface ---------------------------------- @@ -1177,83 +1183,104 @@ The sample crash output is shown below. :: - x0 :0x000000004F00007C - x1 :0x0000000007FFFFFF - x2 :0x0000000004014D50 - x3 :0x0000000000000000 - x4 :0x0000000088007998 - x5 :0x00000000001343AC - x6 :0x0000000000000016 - x7 :0x00000000000B8A38 - x8 :0x00000000001343AC - x9 :0x00000000000101A8 - x10 :0x0000000000000002 - x11 :0x000000000000011C - x12 :0x00000000FEFDC644 - x13 :0x00000000FED93FFC - x14 :0x0000000000247950 - x15 :0x00000000000007A2 - x16 :0x00000000000007A4 - x17 :0x0000000000247950 - x18 :0x0000000000000000 - x19 :0x00000000FFFFFFFF - x20 :0x0000000004014D50 - x21 :0x000000000400A38C - x22 :0x0000000000247950 - x23 :0x0000000000000010 - x24 :0x0000000000000024 - x25 :0x00000000FEFDC868 - x26 :0x00000000FEFDC86A - x27 :0x00000000019EDEDC - x28 :0x000000000A7CFDAA - x29 :0x0000000004010780 - x30 :0x000000000400F004 - scr_el3 :0x0000000000000D3D - sctlr_el3 :0x0000000000C8181F - cptr_el3 :0x0000000000000000 - tcr_el3 :0x0000000080803520 - daif :0x00000000000003C0 - mair_el3 :0x00000000000004FF - spsr_el3 :0x00000000800003CC - elr_el3 :0x000000000400C0CC - ttbr0_el3 :0x00000000040172A0 - esr_el3 :0x0000000096000210 - sp_el3 :0x0000000004014D50 - far_el3 :0x000000004F00007C - spsr_el1 :0x0000000000000000 - elr_el1 :0x0000000000000000 - spsr_abt :0x0000000000000000 - spsr_und :0x0000000000000000 - spsr_irq :0x0000000000000000 - spsr_fiq :0x0000000000000000 - sctlr_el1 :0x0000000030C81807 - actlr_el1 :0x0000000000000000 - cpacr_el1 :0x0000000000300000 - csselr_el1 :0x0000000000000002 - sp_el1 :0x0000000004028800 - esr_el1 :0x0000000000000000 - ttbr0_el1 :0x000000000402C200 - ttbr1_el1 :0x0000000000000000 - mair_el1 :0x00000000000004FF - amair_el1 :0x0000000000000000 - tcr_el1 :0x0000000000003520 - tpidr_el1 :0x0000000000000000 - tpidr_el0 :0x0000000000000000 - tpidrro_el0 :0x0000000000000000 - dacr32_el2 :0x0000000000000000 - ifsr32_el2 :0x0000000000000000 - par_el1 :0x0000000000000000 - far_el1 :0x0000000000000000 - afsr0_el1 :0x0000000000000000 - afsr1_el1 :0x0000000000000000 - contextidr_el1 :0x0000000000000000 - vbar_el1 :0x0000000004027000 - cntp_ctl_el0 :0x0000000000000000 - cntp_cval_el0 :0x0000000000000000 - cntv_ctl_el0 :0x0000000000000000 - cntv_cval_el0 :0x0000000000000000 - cntkctl_el1 :0x0000000000000000 - sp_el0 :0x0000000004010780 + x0 = 0x000000002a4a0000 + x1 = 0x0000000000000001 + x2 = 0x0000000000000002 + x3 = 0x0000000000000003 + x4 = 0x0000000000000004 + x5 = 0x0000000000000005 + x6 = 0x0000000000000006 + x7 = 0x0000000000000007 + x8 = 0x0000000000000008 + x9 = 0x0000000000000009 + x10 = 0x0000000000000010 + x11 = 0x0000000000000011 + x12 = 0x0000000000000012 + x13 = 0x0000000000000013 + x14 = 0x0000000000000014 + x15 = 0x0000000000000015 + x16 = 0x0000000000000016 + x17 = 0x0000000000000017 + x18 = 0x0000000000000018 + x19 = 0x0000000000000019 + x20 = 0x0000000000000020 + x21 = 0x0000000000000021 + x22 = 0x0000000000000022 + x23 = 0x0000000000000023 + x24 = 0x0000000000000024 + x25 = 0x0000000000000025 + x26 = 0x0000000000000026 + x27 = 0x0000000000000027 + x28 = 0x0000000000000028 + x29 = 0x0000000000000029 + x30 = 0x0000000088000b78 + scr_el3 = 0x000000000003073d + sctlr_el3 = 0x00000000b0cd183f + cptr_el3 = 0x0000000000000000 + tcr_el3 = 0x000000008080351c + daif = 0x00000000000002c0 + mair_el3 = 0x00000000004404ff + spsr_el3 = 0x0000000060000349 + elr_el3 = 0x0000000088000114 + ttbr0_el3 = 0x0000000004018201 + esr_el3 = 0x00000000be000000 + far_el3 = 0x0000000000000000 + spsr_el1 = 0x0000000000000000 + elr_el1 = 0x0000000000000000 + spsr_abt = 0x0000000000000000 + spsr_und = 0x0000000000000000 + spsr_irq = 0x0000000000000000 + spsr_fiq = 0x0000000000000000 + sctlr_el1 = 0x0000000030d00800 + actlr_el1 = 0x0000000000000000 + cpacr_el1 = 0x0000000000000000 + csselr_el1 = 0x0000000000000000 + sp_el1 = 0x0000000000000000 + esr_el1 = 0x0000000000000000 + ttbr0_el1 = 0x0000000000000000 + ttbr1_el1 = 0x0000000000000000 + mair_el1 = 0x0000000000000000 + amair_el1 = 0x0000000000000000 + tcr_el1 = 0x0000000000000000 + tpidr_el1 = 0x0000000000000000 + tpidr_el0 = 0x0000000000000000 + tpidrro_el0 = 0x0000000000000000 + par_el1 = 0x0000000000000000 + mpidr_el1 = 0x0000000080000000 + afsr0_el1 = 0x0000000000000000 + afsr1_el1 = 0x0000000000000000 + contextidr_el1 = 0x0000000000000000 + vbar_el1 = 0x0000000000000000 + cntp_ctl_el0 = 0x0000000000000000 + cntp_cval_el0 = 0x0000000000000000 + cntv_ctl_el0 = 0x0000000000000000 + cntv_cval_el0 = 0x0000000000000000 + cntkctl_el1 = 0x0000000000000000 + sp_el0 = 0x0000000004014940 + isr_el1 = 0x0000000000000000 + dacr32_el2 = 0x0000000000000000 + ifsr32_el2 = 0x0000000000000000 + icc_hppir0_el1 = 0x00000000000003ff + icc_hppir1_el1 = 0x00000000000003ff + icc_ctlr_el3 = 0x0000000000080400 + gicd_ispendr regs (Offsets 0x200-0x278) + Offset Value + 0x200: 0x0000000000000000 + 0x208: 0x0000000000000000 + 0x210: 0x0000000000000000 + 0x218: 0x0000000000000000 + 0x220: 0x0000000000000000 + 0x228: 0x0000000000000000 + 0x230: 0x0000000000000000 + 0x238: 0x0000000000000000 + 0x240: 0x0000000000000000 + 0x248: 0x0000000000000000 + 0x250: 0x0000000000000000 + 0x258: 0x0000000000000000 + 0x260: 0x0000000000000000 + 0x268: 0x0000000000000000 + 0x270: 0x0000000000000000 + 0x278: 0x0000000000000000 Guidelines for Reset Handlers ----------------------------- @@ -1275,6 +1302,8 @@ In other words, the reset handler should be able to detect whether an action has already been performed and act as appropriate. Possible courses of actions are, e.g. skip the action the second time, or undo/redo it. +.. _configuring-secure-interrupts: + Configuring secure interrupts ----------------------------- @@ -1711,7 +1740,7 @@ CONFIG section in memory layouts shown below contains: ``bl2_mem_params_descs`` contains parameters passed from BL2 to next the BL image during boot. -``fw_configs`` includes soc_fw_config, tos_fw_config and tb_fw_config. +``fw_configs`` includes soc_fw_config, tos_fw_config, tb_fw_config and fw_config. **FVP with TSP in Trusted SRAM with firmware configs :** (These diagrams only cover the AArch64 case) @@ -1736,7 +1765,7 @@ BL image during boot. | | <<<<<<<<<<<<< | BL31 PROGBITS | | | <<<<<<<<<<<<< |----------------| | | <<<<<<<<<<<<< | BL32 | - 0x04002000 +----------+ +----------------+ + 0x04003000 +----------+ +----------------+ | CONFIG | 0x04001000 +----------+ | Shared | @@ -1773,7 +1802,7 @@ BL image during boot. |--------------| <<<<<<<<<<<<< |----------------| | | <<<<<<<<<<<<< | BL31 PROGBITS | | | +----------------+ - +--------------+ + 0x04003000 +--------------+ | CONFIG | 0x04001000 +--------------+ | Shared | @@ -1807,7 +1836,7 @@ BL image during boot. |----------| <<<<<<<<<<<<< |----------------| | | <<<<<<<<<<<<< | BL31 PROGBITS | | | +----------------+ - 0x04002000 +----------+ + 0x04003000 +----------+ | CONFIG | 0x04001000 +----------+ | Shared | @@ -1838,7 +1867,7 @@ BL image during boot. | BL2 | <<<<<<<<<<<<< | | |----------| <<<<<<<<<<<<< |----------------| | SCP_BL2 | <<<<<<<<<<<<< | BL31 PROGBITS | - |----------| <<<<<<<<<<<<< |----------------| + | | <<<<<<<<<<<<< |----------------| | | <<<<<<<<<<<<< | BL32 | | | +----------------+ | | @@ -1875,7 +1904,7 @@ BL image during boot. | BL2 | <<<<<<<<<<<<< | | |----------| <<<<<<<<<<<<< |----------------| | SCP_BL2 | <<<<<<<<<<<<< | BL31 PROGBITS | - |----------| +----------------+ + | | +----------------+ 0x04001000 +----------+ | MHU | 0x04000000 +----------+ @@ -2690,20 +2719,20 @@ kernel at boot time. These can be found in the ``fdts`` directory. - `Power State Coordination Interface PDD`_ -- `SMC Calling Convention PDD`_ +- `SMC Calling Convention`_ - :ref:`Interrupt Management Framework` -------------- -*Copyright (c) 2013-2019, Arm Limited and Contributors. All rights reserved.* +*Copyright (c) 2013-2020, Arm Limited and Contributors. All rights reserved.* .. _Power State Coordination Interface PDD: http://infocenter.arm.com/help/topic/com.arm.doc.den0022d/Power_State_Coordination_Interface_PDD_v1_1_DEN0022D.pdf -.. _SMCCC: http://infocenter.arm.com/help/topic/com.arm.doc.den0028b/ARM_DEN0028B_SMC_Calling_Convention.pdf +.. _SMCCC: https://developer.arm.com/docs/den0028/latest .. _PSCI: http://infocenter.arm.com/help/topic/com.arm.doc.den0022d/Power_State_Coordination_Interface_PDD_v1_1_DEN0022D.pdf .. _Power State Coordination Interface PDD: http://infocenter.arm.com/help/topic/com.arm.doc.den0022d/Power_State_Coordination_Interface_PDD_v1_1_DEN0022D.pdf -.. _Arm ARM: http://infocenter.arm.com/help/index.jsp?topic=/com.arm.doc.ddi0487a.e/index.html -.. _SMC Calling Convention PDD: http://infocenter.arm.com/help/topic/com.arm.doc.den0028b/ARM_DEN0028B_SMC_Calling_Convention.pdf +.. _Arm ARM: https://developer.arm.com/docs/ddi0487/latest +.. _SMC Calling Convention: https://developer.arm.com/docs/den0028/latest .. _Trusted Board Boot Requirements CLIENT (TBBR-CLIENT) Armv8-A (ARM DEN0006D): https://developer.arm.com/docs/den0006/latest/trusted-board-boot-requirements-client-tbbr-client-armv8-a .. |Image 1| image:: ../resources/diagrams/rt-svc-descs-layout.png diff --git a/docs/design/interrupt-framework-design.rst b/docs/design/interrupt-framework-design.rst index d155cb356..dfb2eac8e 100644 --- a/docs/design/interrupt-framework-design.rst +++ b/docs/design/interrupt-framework-design.rst @@ -138,6 +138,8 @@ Non-secure interrupts reason to route the interrupt to EL3 software and then hand it back to non-secure software for handling. +.. _EL3 interrupts: + EL3 interrupts ^^^^^^^^^^^^^^ @@ -148,10 +150,8 @@ EL3 interrupts However, when ``EL3_EXCEPTION_HANDLING`` is ``1``, this routing model is invalid as EL3 interrupts are unconditionally routed to EL3, and EL3 - interrupts will always preempt Secure EL1/EL0 execution. See `exception - handling`__ documentation. - - .. __: exception-handling.rst#interrupt-handling + interrupts will always preempt Secure EL1/EL0 execution. See :ref:`exception + handling<interrupt-handling>` documentation. #. **CSS=0, TEL3=1**. Interrupt is routed to EL3 when execution is in Secure-EL1/Secure-EL0. This is a valid routing model as secure software @@ -301,6 +301,8 @@ This section describes in detail the role of each software component (see `Software components`_) during the registration of a handler for an interrupt type. +.. _el3-runtime-firmware: + EL3 runtime firmware ~~~~~~~~~~~~~~~~~~~~ @@ -899,14 +901,14 @@ it is generated during execution in the TSP with ``PSTATE.I`` = 0 when the |Image 2| -Secure payload -~~~~~~~~~~~~~~ +.. _sp-synchronous-int: + +Secure payload interrupt handling +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ The SP should implement one or both of the synchronous and asynchronous interrupt handling models depending upon the interrupt routing model it has -chosen (as described in section `Secure Payload`__). - -.. __: #sp-int-registration +chosen (as described in section :ref:`Secure Payload <sp-int-registration>`). In the synchronous model, it should begin handling a Secure-EL1 interrupt after receiving control from the SPD service at an entrypoint agreed upon during build @@ -1011,9 +1013,9 @@ TSP by returning ``SMC_UNK`` error. -------------- -*Copyright (c) 2014-2019, Arm Limited and Contributors. All rights reserved.* +*Copyright (c) 2014-2020, Arm Limited and Contributors. All rights reserved.* -.. _SMC calling convention: http://infocenter.arm.com/help/topic/com.arm.doc.den0028a/index.html +.. _SMC calling convention: https://developer.arm.com/docs/den0028/latest .. |Image 1| image:: ../resources/diagrams/sec-int-handling.png .. |Image 2| image:: ../resources/diagrams/non-sec-int-handling.png diff --git a/docs/design/trusted-board-boot-build.rst b/docs/design/trusted-board-boot-build.rst index 202524316..dd61b61f5 100644 --- a/docs/design/trusted-board-boot-build.rst +++ b/docs/design/trusted-board-boot-build.rst @@ -32,26 +32,28 @@ images with support for these features: - ``TRUSTED_BOARD_BOOT=1`` - ``GENERATE_COT=1`` + By default, this will use the Chain of Trust described in the TBBR-client + document. To select a different one, use the ``COT`` build option. + In the case of Arm platforms, the location of the ROTPK hash must also be - specified at build time. Two locations are currently supported (see + specified at build time. The following locations are currently supported (see ``ARM_ROTPK_LOCATION`` build option): - ``ARM_ROTPK_LOCATION=regs``: the ROTPK hash is obtained from the Trusted - root-key storage registers present in the platform. On Juno, this + root-key storage registers present in the platform. On Juno, these registers are read-only. On FVP Base and Cortex models, the registers - are read-only, but the value can be specified using the command line + are also read-only, but the value can be specified using the command line option ``bp.trusted_key_storage.public_key`` when launching the model. - On both Juno and FVP models, the default value corresponds to an - ECDSA-SECP256R1 public key hash, whose private part is not currently - available. + On Juno board, the default value corresponds to an ECDSA-SECP256R1 public + key hash, whose private part is not currently available. - - ``ARM_ROTPK_LOCATION=devel_rsa``: use the ROTPK hash that is hardcoded - in the Arm platform port. The private/public RSA key pair may be - found in ``plat/arm/board/common/rotpk``. + - ``ARM_ROTPK_LOCATION=devel_rsa``: use the default hash located in + ``plat/arm/board/common/rotpk/arm_rotpk_rsa_sha256.bin``. Enforce + generation of the new hash if ``ROT_KEY`` is specified. - - ``ARM_ROTPK_LOCATION=devel_ecdsa``: use the ROTPK hash that is hardcoded - in the Arm platform port. The private/public ECDSA key pair may be - found in ``plat/arm/board/common/rotpk``. + - ``ARM_ROTPK_LOCATION=devel_ecdsa``: use the default hash located in + ``plat/arm/board/common/rotpk/arm_rotpk_ecdsa_sha256.bin``. Enforce + generation of the new hash if ``ROT_KEY`` is specified. Example of command line using RSA development keys: @@ -65,9 +67,8 @@ images with support for these features: all fip The result of this build will be the bl1.bin and the fip.bin binaries. This - FIP will include the certificates corresponding to the Chain of Trust - described in the TBBR-client document. These certificates can also be found - in the output build directory. + FIP will include the certificates corresponding to the selected Chain of + Trust. These certificates can also be found in the output build directory. #. The optional FWU_FIP contains any additional images to be loaded from Non-Volatile storage during the :ref:`Firmware Update (FWU)` process. To build the @@ -103,12 +104,12 @@ images with support for these features: The result of this build will be bl1.bin, fip.bin and fwu_fip.bin binaries. Both the FIP and FWU_FIP will include the certificates corresponding to the - Chain of Trust described in the TBBR-client document. These certificates - can also be found in the output build directory. + selected Chain of Trust. These certificates can also be found in the output + build directory. -------------- -*Copyright (c) 2019, Arm Limited. All rights reserved.* +*Copyright (c) 2019-2020, Arm Limited. All rights reserved.* .. _mbed TLS Repository: https://github.com/ARMmbed/mbedtls.git .. _mbed TLS Security Center: https://tls.mbed.org/security diff --git a/docs/design/trusted-board-boot.rst b/docs/design/trusted-board-boot.rst index 49e8adb98..96cf24c0b 100644 --- a/docs/design/trusted-board-boot.rst +++ b/docs/design/trusted-board-boot.rst @@ -19,7 +19,9 @@ A Chain of Trust (CoT) starts with a set of implicitly trusted components. On the Arm development platforms, these components are: - A SHA-256 hash of the Root of Trust Public Key (ROTPK). It is stored in the - trusted root-key storage registers. + trusted root-key storage registers. Alternatively, a development ROTPK might + be used and its hash embedded into the BL1 and BL2 images (only for + development purposes). - The BL1 image, on the assumption that it resides in ROM so cannot be tampered with. @@ -32,17 +34,17 @@ essential information to establish the CoT. In the TBB CoT all certificates are self-signed. There is no need for a Certificate Authority (CA) because the CoT is not established by verifying the validity of a certificate's issuer but by the content of the certificate -extensions. To sign the certificates, the PKCS#1 SHA-256 with RSA Encryption -signature scheme is used with a RSA key length of 2048 bits. Future version of -TF-A will support additional cryptographic algorithms. +extensions. To sign the certificates, different signature schemes are available, +please refer to the :ref:`Build Options` for more details. The certificates are categorised as "Key" and "Content" certificates. Key certificates are used to verify public keys which have been used to sign content certificates. Content certificates are used to store the hash of a boot loader image. An image can be authenticated by calculating its hash and matching it -with the hash extracted from the content certificate. The SHA-256 function is -used to calculate all hashes. The public keys and hashes are included as -non-standard extension fields in the `X.509 v3`_ certificates. +with the hash extracted from the content certificate. Various hash algorithms +are supported to calculate all hashes, please refer to the :ref:`Build Options` +for more details.. The public keys and hashes are included as non-standard +extension fields in the `X.509 v3`_ certificates. The keys used to establish the CoT are: @@ -63,10 +65,10 @@ The keys used to establish the CoT are: non secure world image (BL33). The public part is stored in one of the extension fields in the trusted world certificate. -- **BL3-X keys** +- **BL3X keys** For each of SCP_BL2, BL31, BL32 and BL33, the private part is used to - sign the content certificate for the BL3-X image. The public part is stored + sign the content certificate for the BL3X image. The public part is stored in one of the extension fields in the corresponding key certificate. The following images are included in the CoT: @@ -219,8 +221,7 @@ certificates (in DER format) required to establish the CoT. New keys can be generated by the tool in case they are not provided. The certificates are then passed as inputs to the ``fiptool`` utility for creating the FIP. -The certificates are also stored individually in the in the output build -directory. +The certificates are also stored individually in the output build directory. The tool resides in the ``tools/cert_create`` directory. It uses the OpenSSL SSL library version to generate the X.509 certificates. The specific version of the @@ -229,9 +230,37 @@ library that is required is given in the :ref:`Prerequisites` document. Instructions for building and using the tool can be found at :ref:`tools_build_cert_create`. +Authenticated Encryption Framework +---------------------------------- + +The authenticated encryption framework included in TF-A provides support to +implement the optional firmware encryption feature. This feature can be +optionally enabled on platforms to implement the optional requirement: +R060_TBBR_FUNCTION as specified in the `Trusted Board Boot Requirements (TBBR)`_ +document. + +Note that due to security considerations and complexity of this feature, it is +marked as experimental. + +Firmware Encryption Tool +------------------------ + +The ``encrypt_fw`` tool is built and runs on the host machine as part of the +TF-A build process when ``DECRYPTION_SUPPORT != none``. It takes the plain +firmware image as input and generates the encrypted firmware image which can +then be passed as input to the ``fiptool`` utility for creating the FIP. + +The encrypted firmwares are also stored individually in the output build +directory. + +The tool resides in the ``tools/encrypt_fw`` directory. It uses OpenSSL SSL +library version 1.0.1 or later to do authenticated encryption operation. +Instructions for building and using the tool can be found in the +:ref:`tools_build_enctool`. + -------------- -*Copyright (c) 2015-2019, Arm Limited and Contributors. All rights reserved.* +*Copyright (c) 2015-2020, Arm Limited and Contributors. All rights reserved.* .. _X.509 v3: https://tools.ietf.org/rfc/rfc5280.txt .. _Trusted Board Boot Requirements (TBBR): https://developer.arm.com/docs/den0006/latest/trusted-board-boot-requirements-client-tbbr-client-armv8-a diff --git a/docs/design_documents/cmake_framework.rst b/docs/design_documents/cmake_framework.rst new file mode 100644 index 000000000..d88942e82 --- /dev/null +++ b/docs/design_documents/cmake_framework.rst @@ -0,0 +1,165 @@ +TF-A CMake buildsystem +====================== + +:Author: Balint Dobszay +:Organization: Arm Limited +:Contact: Balint Dobszay <balint.dobszay@arm.com> +:Status: Accepted + +.. contents:: Table of Contents + +Abstract +-------- +This document presents a proposal for a new buildsystem for TF-A using CMake, +and as part of this a reusable CMake framework for embedded projects. For a +summary about the proposal, please see the `Phabricator wiki page +<https://developer.trustedfirmware.org/w/tf_a/cmake-buildsystem-proposal/>`_. As +mentioned there, the proposal consists of two phases. The subject of this +document is the first phase only. + +Introduction +------------ +The current Makefile based buildsystem of TF-A has become complicated and hard +to maintain, there is a need for a new, more flexible solution. The proposal is +to use CMake language for the new buildsystem. The main reasons of this decision +are the following: + +* It is a well-established, mature tool, widely accepted by open-source + projects. +* TF-M is already using CMake, reducing fragmentation for tf.org projects can be + beneficial. +* CMake has various advantages over Make, e.g.: + + * Host and target system agnostic project. + * CMake project is scalable, supports project modularization. + * Supports software integration. + * Out-of-the-box support for integration with several tools (e.g. project + generation for various IDEs, integration with cppcheck, etc). + +Of course there are drawbacks too: + +* Language is problematic (e.g. variable scope). +* Not embedded approach. + +To overcome these and other problems, we need to create workarounds for some +tasks, wrap CMake functions, etc. Since this functionality can be useful in +other embedded projects too, it is beneficial to collect the new code into a +reusable framework and store this in a separate repository. The following +diagram provides an overview of the framework structure: + +|Framework structure| + +Main features +------------- + +Structured configuration description +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +In the current Makefile system the build configuration description, validation, +processing, and the target creation, source file description are mixed and +spread across several files. One of the goals of the framework is to organize +this. + +The framework provides a solution to describe the input build parameters, flags, +macros, etc. in a structured way. It contains two utilities for this purpose: + +* Map: simple key-value pair implementation. +* Group: collection of related maps. + +The related parameters shall be packed into a group (or "setting group"). The +setting groups shall be defined and filled with content in config files. +Currently the config files are created and edited manually, but later a +configuration management tool (e.g. Kconfig) shall be used to generate these +files. Therefore, the framework does not contain parameter validation and +conflict checking, these shall be handled by the configuration tool. + +Target description +^^^^^^^^^^^^^^^^^^ +The framework provides an API called STGT ('simple target') to describe the +targets, i.e. what is the build output, what source files are used, what +libraries are linked, etc. The API wraps the CMake target functions, and also +extends the built-in functionality, it can use the setting groups described in +the previous section. A group can be applied onto a target, i.e. a collection of +macros, flags, etc. can be applied onto the given output executable/library. +This provides a more granular way than the current Makefile system where most of +these are global and applied onto each target. + +Compiler abstraction +^^^^^^^^^^^^^^^^^^^^ +Apart from the built-in CMake usage of the compiler, there are some common tasks +that CMake does not solve (e.g. preprocessing a file). For these tasks the +framework uses wrapper functions instead of direct calls to the compiler. This +way it is not tied to one specific compiler. + +External tools +^^^^^^^^^^^^^^ +In the TF-A buildsystem some external tools are used, e.g. fiptool for image +generation or dtc for device tree compilation. These tools have to be found +and/or built by the framework. For this, the CMake find_package functionality is +used, any other necessary tools can be added later. + +Workflow +-------- +The following diagram demonstrates the development workflow using the framework: + +|Framework workflow| + +The process can be split into two main phases: + +In the provisioning phase, first we have to obtain the necessary resources, i.e. +clone the code repository and other dependencies. Next we have to do the +configuration, preferably using a config tool like KConfig. + +In the development phase first we run CMake, which will generate the buildsystem +using the selected generator backend (currently only the Makefile generator is +supported). After this we run the selected build tool which in turn calls the +compiler, linker, packaging tool, etc. Finally we can run and debug the output +executables. + +Usually during development only the steps in this second phase have to be +repeated, while the provisioning phase needs to be done only once (or rarely). + +Example +------- +This is a short example for the basic framework usage. + +First, we create a setting group called *mem_conf* and fill it with several +parameters. It is worth noting the difference between *CONFIG* and *DEFINE* +types: the former is only a CMake domain option, the latter is only a C language +macro. + +Next, we create a target called *fw1* and add the *mem_conf* setting group to +it. This means that all source and header files used by the target will have all +the parameters declared in the setting group. Then we set the target type to +executable, and add some source files. Since the target has the parameters from +the settings group, we can use it for conditionally adding source files. E.g. +*dram_controller.c* will only be added if MEM_TYPE equals dram. + +.. code-block:: cmake + + group_new(NAME mem_conf) + group_add(NAME mem_conf TYPE DEFINE KEY MEM_SIZE VAL 1024) + group_add(NAME mem_conf TYPE CONFIG DEFINE KEY MEM_TYPE VAL dram) + group_add(NAME mem_conf TYPE CFLAG KEY -Os) + + stgt_create(NAME fw1) + stgt_add_setting(NAME fw1 GROUPS mem_conf) + stgt_set_target(NAME fw1 TYPE exe) + + stgt_add_src(NAME fw1 SRC + ${CMAKE_SOURCE_DIR}/main.c + ) + + stgt_add_src_cond(NAME fw1 KEY MEM_TYPE VAL dram SRC + ${CMAKE_SOURCE_DIR}/dram_controller.c + ) + +.. |Framework structure| image:: + ../resources/diagrams/cmake_framework_structure.png + :width: 75 % + +.. |Framework workflow| image:: + ../resources/diagrams/cmake_framework_workflow.png + +-------------- + +*Copyright (c) 2019-2020, Arm Limited and Contributors. All rights reserved.* diff --git a/docs/design_documents/index.rst b/docs/design_documents/index.rst new file mode 100644 index 000000000..187510a64 --- /dev/null +++ b/docs/design_documents/index.rst @@ -0,0 +1,13 @@ +Design Documents +================ + +.. toctree:: + :maxdepth: 1 + :caption: Contents + :numbered: + + cmake_framework + +-------------- + +*Copyright (c) 2020, Arm Limited and Contributors. All rights reserved.* diff --git a/docs/getting_started/build-options.rst b/docs/getting_started/build-options.rst index 2f44fe817..c520e0c22 100644 --- a/docs/getting_started/build-options.rst +++ b/docs/getting_started/build-options.rst @@ -26,6 +26,12 @@ Common build options ``aarch64`` or ``aarch32`` as values. By default, it is defined to ``aarch64``. +- ``ARM_ARCH_FEATURE``: Optional Arm Architecture build option which specifies + one or more feature modifiers. This option has the form ``[no]feature+...`` + and defaults to ``none``. It translates into compiler option + ``-march=armvX[.Y]-a+[no]feature+...``. See compiler's documentation for the + list of supported feature modifiers. + - ``ARM_ARCH_MAJOR``: The major version of Arm Architecture to target when compiling TF-A. Its value must be numeric, and defaults to 8 . See also, *Armv8 Architecture Extensions* and *Armv7 Architecture Extensions* in @@ -88,6 +94,7 @@ Common build options - 1: Enables all types of branch protection features - 2: Return address signing to its standard level - 3: Extend the signing to include leaf functions +- 4: Turn on branch target identification mechanism The table below summarizes ``BRANCH_PROTECTION`` values, GCC compilation options and resulting PAuth/BTI features. @@ -103,6 +110,8 @@ Common build options +-------+--------------+-------+-----+ | 3 | pac-ret+leaf | Y | N | +-------+--------------+-------+-----+ + | 4 | bti | N | Y | + +-------+--------------+-------+-----+ This option defaults to 0 and this is an experimental feature. Note that Pointer Authentication is enabled for Non-secure world @@ -116,6 +125,8 @@ Common build options - ``BUILD_STRING``: Input string for VERSION_STRING, which allows the TF-A build to be uniquely identified. Defaults to the current git commit id. +- ``BUILD_BASE``: Output directory for the build. Defaults to ``./build`` + - ``CFLAGS``: Extra user options appended on the compiler's command line in addition to the options set by the build system. @@ -146,10 +157,20 @@ Common build options is on hardware that does not implement AArch32, or at least not at EL1 and higher ELs). Default value is 1. +- ``CTX_INCLUDE_EL2_REGS`` : This boolean option provides context save/restore + operations when entering/exiting an EL2 execution context. This is of primary + interest when Armv8.4-SecEL2 extension is implemented. Default is 0 (disabled). + This option must be equal to 1 (enabled) when ``SPD=spmd`` and + ``SPMD_SPM_AT_SEL2`` is set. + - ``CTX_INCLUDE_FPREGS``: Boolean option that, when set to 1, will cause the FP registers to be included when saving and restoring the CPU context. Default is 0. +- ``CTX_INCLUDE_NEVE_REGS``: Boolean option that, when set to 1, will cause the + Armv8.4-NV registers to be saved/restored when entering/exiting an EL2 + execution context. Default value is 0. + - ``CTX_INCLUDE_PAUTH_REGS``: Boolean option that, when set to 1, enables Pointer Authentication for Secure world. This will cause the ARMv8.3-PAuth registers to be included when saving and restoring the CPU context as @@ -160,10 +181,21 @@ Common build options - ``DEBUG``: Chooses between a debug and release build. It can take either 0 (release) or 1 (debug) as values. 0 is the default. +- ``DECRYPTION_SUPPORT``: This build flag enables the user to select the + authenticated decryption algorithm to be used to decrypt firmware/s during + boot. It accepts 2 values: ``aes_gcm`` and ``none``. The default value of + this flag is ``none`` to disable firmware decryption which is an optional + feature as per TBBR. Also, it is an experimental feature. + - ``DISABLE_BIN_GENERATION``: Boolean option to disable the generation of the binary image. If set to 1, then only the ELF image is built. 0 is the default. +- ``DISABLE_MTPMU``: Boolean option to disable FEAT_MTPMU if implemented + (Armv8.6 onwards). Its default value is 0 to keep consistency with platforms + that do not implement FEAT_MTPMU. For more information on FEAT_MTPMU, + check the latest Arm ARM. + - ``DYN_DISABLE_AUTH``: Provides the capability to dynamically disable Trusted Board Boot authentication at runtime. This option is meant to be enabled only for development platforms. ``TRUSTED_BOARD_BOOT`` flag must be set if this @@ -189,7 +221,7 @@ Common build options that is only required for the assertion and does not fit in the assertion itself. -- ``ENABLE_BACKTRACE``: This option controls whether to enables backtrace +- ``ENABLE_BACKTRACE``: This option controls whether to enable backtrace dumps or not. It is supported in both AArch64 and AArch32. However, in AArch32 the format of the frame records are not defined in the AAPCS and they are defined by the implementation. This implementation of backtrace only @@ -257,6 +289,22 @@ Common build options platform hook needs to be implemented. The value is passed as the last component of the option ``-fstack-protector-$ENABLE_STACK_PROTECTOR``. +- ``ENCRYPT_BL31``: Binary flag to enable encryption of BL31 firmware. This + flag depends on ``DECRYPTION_SUPPORT`` build flag which is marked as + experimental. + +- ``ENCRYPT_BL32``: Binary flag to enable encryption of Secure BL32 payload. + This flag depends on ``DECRYPTION_SUPPORT`` build flag which is marked as + experimental. + +- ``ENC_KEY``: A 32-byte (256-bit) symmetric key in hex string format. It could + either be SSK or BSSK depending on ``FW_ENC_STATUS`` flag. This value depends + on ``DECRYPTION_SUPPORT`` build flag which is marked as experimental. + +- ``ENC_NONCE``: A 12-byte (96-bit) encryption nonce or Initialization Vector + (IV) in hex string format. This value depends on ``DECRYPTION_SUPPORT`` + build flag which is marked as experimental. + - ``ERROR_DEPRECATED``: This option decides whether to treat the usage of deprecated platform APIs, helper functions or drivers within Trusted Firmware as error. It can take the value 1 (flag the use of deprecated @@ -267,6 +315,10 @@ Common build options handled at EL3, and a panic will result. This is supported only for AArch64 builds. +- ``EVENT_LOG_LEVEL``: Chooses the log level to use for Measured Boot when + ``MEASURED_BOOT`` is enabled. For a list of valid values, see ``LOG_LEVEL``. + Default value is 40 (LOG_LEVEL_INFO). + - ``FAULT_INJECTION_SUPPORT``: ARMv8.4 extensions introduced support for fault injection from lower ELs, and this build option enables lower ELs to use Error Records accessed via System Registers to inject faults. This is @@ -281,6 +333,18 @@ Common build options - ``FWU_FIP_NAME``: This is an optional build option which specifies the FWU FIP filename for the ``fwu_fip`` target. Default is ``fwu_fip.bin``. +- ``FW_ENC_STATUS``: Top level firmware's encryption numeric flag, values: + + :: + + 0: Encryption is done with Secret Symmetric Key (SSK) which is common + for a class of devices. + 1: Encryption is done with Binding Secret Symmetric Key (BSSK) which is + unique per device. + + This flag depends on ``DECRYPTION_SUPPORT`` build flag which is marked as + experimental. + - ``GENERATE_COT``: Boolean flag used to build and execute the ``cert_create`` tool to create certificates as per the Chain of Trust described in :ref:`Trusted Board Boot`. The build system then calls ``fiptool`` to @@ -303,16 +367,14 @@ Common build options - ``GICV2_G0_FOR_EL3``: Unlike GICv3, the GICv2 architecture doesn't have inherent support for specific EL3 type interrupts. Setting this build option to ``1`` assumes GICv2 *Group 0* interrupts are expected to target EL3, both - by `platform abstraction layer`__ and `Interrupt Management Framework`__. + by :ref:`platform abstraction layer<platform Interrupt Controller API>` and + :ref:`Interrupt Management Framework<Interrupt Management Framework>`. This allows GICv2 platforms to enable features requiring EL3 interrupt type. This also means that all GICv2 Group 0 interrupts are delivered to EL3, and the Secure Payload interrupts needs to be synchronously handed over to Secure EL1 for handling. The default value of this option is ``0``, which means the Group 0 interrupts are assumed to be handled by Secure EL1. - .. __: `platform-interrupt-controller-API.rst` - .. __: `interrupt-framework-design.rst` - - ``HANDLE_EA_EL3_FIRST``: When set to ``1``, External Aborts and SError Interrupts will be always trapped in EL3 i.e. in BL31 at runtime. When set to ``0`` (default), these exceptions will be trapped in the current exception @@ -340,6 +402,11 @@ Common build options translation library (xlat tables v2) must be used; version 1 of translation library is not supported. +- ``INVERTED_MEMMAP``: memmap tool print by default lower addresses at the + bottom, higher addresses at the top. This build flag can be set to '1' to + invert this behavior. Lower addresses will be printed at the top and higher + addresses at the bottom. + - ``JUNO_AARCH32_EL3_RUNTIME``: This build flag enables you to execute EL3 runtime software in AArch32 mode, which is required to run AArch32 on Juno. By default this flag is set to '0'. Enabling this flag builds BL1 and BL2 in @@ -468,7 +535,8 @@ Common build options entrypoint) or 1 (CPU reset to SP_MIN entrypoint). The default value is 0. - ``ROT_KEY``: This option is used when ``GENERATE_COT=1``. It specifies the - file that contains the ROT private key in PEM format. If ``SAVE_KEYS=1``, this + file that contains the ROT private key in PEM format and enforces public key + hash generation. If ``SAVE_KEYS=1``, this file name will be used to save the key. - ``SAVE_KEYS``: This option is used when ``GENERATE_COT=1``. It tells the @@ -496,13 +564,13 @@ Common build options - ``SEPARATE_CODE_AND_RODATA``: Whether code and read-only data should be isolated on separate memory pages. This is a trade-off between security and memory usage. See "Isolating code and read-only data on separate memory - pages" section in :ref:`Firmware Design`. This flag is disabled by default and - affects all BL images. + pages" section in :ref:`Firmware Design`. This flag is disabled by default + and affects all BL images. - ``SEPARATE_NOBITS_REGION``: Setting this option to ``1`` allows the NOBITS sections of BL31 (.bss, stacks, page tables, and coherent memory) to be allocated in RAM discontiguous from the loaded firmware image. When set, the - platform is expected to provide definitons for ``BL31_NOBITS_BASE`` and + platform is expected to provide definitions for ``BL31_NOBITS_BASE`` and ``BL31_NOBITS_LIMIT``. When the option is ``0`` (the default), NOBITS sections are placed in RAM immediately following the loaded firmware image. @@ -510,7 +578,9 @@ Common build options This build option is only valid if ``ARCH=aarch64``. The value should be the path to the directory containing the SPD source, relative to ``services/spd/``; the directory is expected to contain a makefile called - ``<spd-value>.mk``. + ``<spd-value>.mk``. The SPM Dispatcher standard service is located in + services/std_svc/spmd and enabled by ``SPD=spmd``. The SPM Dispatcher + cannot be enabled when the ``SPM_MM`` option is enabled. - ``SPIN_ON_BL1_EXIT``: This option introduces an infinite loop in BL1. It can take either 0 (no loop) or 1 (add a loop). 0 is the default. This loop stops @@ -518,8 +588,23 @@ Common build options firmware images have been loaded in memory, and the MMU and caches are turned off. Refer to the "Debugging options" section for more details. +- ``SPMD_SPM_AT_SEL2`` : this boolean option is used jointly with the SPM + Dispatcher option (``SPD=spmd``). When enabled (1) it indicates the SPMC + component runs at the S-EL2 execution state provided by the Armv8.4-SecEL2 + extension. This is the default when enabling the SPM Dispatcher. When + disabled (0) it indicates the SPMC component runs at the S-EL1 execution + state. This latter configuration supports pre-Armv8.4 platforms (aka not + implementing the Armv8.4-SecEL2 extension). + - ``SPM_MM`` : Boolean option to enable the Management Mode (MM)-based Secure - Partition Manager (SPM) implementation. The default value is ``0``. + Partition Manager (SPM) implementation. The default value is ``0`` + (disabled). This option cannot be enabled (``1``) when SPM Dispatcher is + enabled (``SPD=spmd``). + +- ``SP_LAYOUT_FILE``: Platform provided path to JSON file containing the + description of secure partitions. The build system will parse this file and + package all secure partition blobs into the FIP. This file is not + necessarily part of TF-A tree. Only available when ``SPD=spmd``. - ``SP_MIN_WITH_SECURE_FIQ``: Boolean flag to indicate the SP_MIN handles secure interrupts (caught through the FIQ line). Platforms can enable @@ -577,6 +662,30 @@ Common build options exposing a virtual filesystem interface through BL31 as a SiP SMC function. Default is 0. +- ``ARM_IO_IN_DTB``: This flag determines whether to use IO based on the + firmware configuration framework. This will move the io_policies into a + configuration device tree, instead of static structure in the code base. + This is currently an experimental feature. + +- ``COT_DESC_IN_DTB``: This flag determines whether to create COT descriptors + at runtime using fconf. If this flag is enabled, COT descriptors are + statically captured in tb_fw_config file in the form of device tree nodes + and properties. Currently, COT descriptors used by BL2 are moved to the + device tree and COT descriptors used by BL1 are retained in the code + base statically. This is currently an experimental feature. + +- ``SDEI_IN_FCONF``: This flag determines whether to configure SDEI setup in + runtime using firmware configuration framework. The platform specific SDEI + shared and private events configuration is retrieved from device tree rather + than static C structures at compile time. This is currently an experimental + feature and is only supported if SDEI_SUPPORT build flag is enabled. + +- ``SEC_INT_DESC_IN_FCONF``: This flag determines whether to configure Group 0 + and Group1 secure interrupts using the firmware configuration framework. The + platform specific secure interrupt property descriptor is retrieved from + device tree in runtime rather than depending on static C structure at compile + time. This is currently an experimental feature. + - ``USE_ROMLIB``: This flag determines whether library at ROM will be used. This feature creates a library of functions to be placed in ROM and thus reduces SRAM usage. Refer to :ref:`Library at ROM` for further details. Default @@ -599,6 +708,83 @@ Common build options cluster platforms). If this option is enabled, then warm boot path enables D-caches immediately after enabling MMU. This option defaults to 0. +- ``SUPPORT_STACK_MEMTAG``: This flag determines whether to enable memory + tagging for stack or not. It accepts 2 values: ``yes`` and ``no``. The + default value of this flag is ``no``. Note this option must be enabled only + for ARM architecture greater than Armv8.5-A. + +- ``ERRATA_SPECULATIVE_AT``: This flag determines whether to enable ``AT`` + speculative errata workaround or not. It accepts 2 values: ``1`` and ``0``. + The default value of this flag is ``0``. + + ``AT`` speculative errata workaround disables stage1 page table walk for + lower ELs (EL1 and EL0) in EL3 so that ``AT`` speculative fetch at any point + produces either the correct result or failure without TLB allocation. + + This boolean option enables errata for all below CPUs. + + +---------+--------------+-------------------------+ + | Errata | CPU | Workaround Define | + +=========+==============+=========================+ + | 1165522 | Cortex-A76 | ``ERRATA_A76_1165522`` | + +---------+--------------+-------------------------+ + | 1319367 | Cortex-A72 | ``ERRATA_A72_1319367`` | + +---------+--------------+-------------------------+ + | 1319537 | Cortex-A57 | ``ERRATA_A57_1319537`` | + +---------+--------------+-------------------------+ + | 1530923 | Cortex-A55 | ``ERRATA_A55_1530923`` | + +---------+--------------+-------------------------+ + | 1530924 | Cortex-A53 | ``ERRATA_A53_1530924`` | + +---------+--------------+-------------------------+ + + .. note:: + This option is enabled by build only if platform sets any of above defines + mentioned in ’Workaround Define' column in the table. + If this option is enabled for the EL3 software then EL2 software also must + implement this workaround due to the behaviour of the errata mentioned + in new SDEN document which will get published soon. + +- ``RAS_TRAP_LOWER_EL_ERR_ACCESS``: This flag enables/disables the SCR_EL3.TERR + bit, to trap access to the RAS ERR and RAS ERX registers from lower ELs. + This flag is disabled by default. + +- ``OPENSSL_DIR``: This flag is used to provide the installed openssl directory + path on the host machine which is used to build certificate generation and + firmware encryption tool. + +- ``USE_SP804_TIMER``: Use the SP804 timer instead of the Generic Timer for + functions that wait for an arbitrary time length (udelay and mdelay). The + default value is 0. + +GICv3 driver options +-------------------- + +GICv3 driver files are included using directive: + +``include drivers/arm/gic/v3/gicv3.mk`` + +The driver can be configured with the following options set in the platform +makefile: + +- ``GICV3_SUPPORT_GIC600``: Add support for the GIC-600 variants of GICv3. + Enabling this option will add runtime detection support for the + GIC-600, so is safe to select even for a GIC500 implementation. + This option defaults to 0. + +- ``GICV3_IMPL_GIC600_MULTICHIP``: Selects GIC-600 variant with multichip + functionality. This option defaults to 0 + +- ``GICV3_OVERRIDE_DISTIF_PWR_OPS``: Allows override of default implementation + of ``arm_gicv3_distif_pre_save`` and ``arm_gicv3_distif_post_restore`` + functions. This is required for FVP platform which need to simulate GIC save + and restore during SYSTEM_SUSPEND without powering down GIC. Default is 0. + +- ``GIC_ENABLE_V4_EXTN`` : Enables GICv4 related changes in GICv3 driver. + This option defaults to 0. + +- ``GIC_EXT_INTID``: When set to ``1``, GICv3 driver will support extended + PPI (1056-1119) and SPI (4096-5119) range. This option defaults to 0. + Debugging options ----------------- @@ -657,4 +843,4 @@ commands can be used: -------------- -*Copyright (c) 2019, Arm Limited. All rights reserved.* +*Copyright (c) 2019-2020, Arm Limited. All rights reserved.* diff --git a/docs/getting_started/docs-build.rst b/docs/getting_started/docs-build.rst index 91b1b3a39..87c677fcd 100644 --- a/docs/getting_started/docs-build.rst +++ b/docs/getting_started/docs-build.rst @@ -67,7 +67,7 @@ Output from the build process will be placed in: :: - docs/build/html/ + docs/build/html We also support building documentation in other formats. From the ``docs`` directory of the project, run the following command to see the supported @@ -79,6 +79,31 @@ top-level Makefile for |TF-A| itself. make help +Building rendered documentation from a container +------------------------------------------------ + +There may be cases where you can not either install or upgrade required +dependencies to generate the documents, so in this case, one way to +create the documentation is through a docker container. The first step is +to check if `docker`_ is installed in your host, otherwise check main docker +page for installation instructions. Once installed, run the following script +from project root directory + +.. code:: shell + + docker run --rm -v $PWD:/TF sphinxdoc/sphinx \ + bash -c 'cd /TF && \ + pip3 install plantuml -r ./docs/requirements.txt && make doc' + +The above command fetches the ``sphinxdoc/sphinx`` container from `docker +hub`_, launches the container, installs documentation requirements and finally +creates the documentation. Once done, exit the container and output from the +build process will be placed in: + +:: + + docs/build/html + -------------- *Copyright (c) 2019, Arm Limited. All rights reserved.* @@ -86,3 +111,5 @@ top-level Makefile for |TF-A| itself. .. _Sphinx: http://www.sphinx-doc.org/en/master/ .. _pip homepage: https://pip.pypa.io/en/stable/ .. _Dia: https://wiki.gnome.org/Apps/Dia +.. _docker: https://www.docker.com/ +.. _docker hub: https://hub.docker.com/repository/docker/sphinxdoc/sphinx diff --git a/docs/getting_started/porting-guide.rst b/docs/getting_started/porting-guide.rst index bb1471752..be3f0bb0f 100644 --- a/docs/getting_started/porting-guide.rst +++ b/docs/getting_started/porting-guide.rst @@ -116,7 +116,7 @@ likely to be suitable for all platform ports. by ``plat/common/aarch64/platform_mp_stack.S`` and ``plat/common/aarch64/platform_up_stack.S``. -- **define : CACHE_WRITEBACK_GRANULE** +- **#define : CACHE_WRITEBACK_GRANULE** Defines the size in bits of the largest cache line across all the cache levels in the platform. @@ -562,21 +562,14 @@ behaviour of the ``assert()`` function (for example, to save memory). doesn't print anything to the console. If ``PLAT_LOG_LEVEL_ASSERT`` isn't defined, it defaults to ``LOG_LEVEL``. -If the platform port uses the Activity Monitor Unit, the following constants +If the platform port uses the Activity Monitor Unit, the following constant may be defined: - **PLAT_AMU_GROUP1_COUNTERS_MASK** This mask reflects the set of group counters that should be enabled. The maximum number of group 1 counters supported by AMUv1 is 16 so the mask can be at most 0xffff. If the platform does not define this mask, no group 1 - counters are enabled. If the platform defines this mask, the following - constant needs to also be defined. - -- **PLAT_AMU_GROUP1_NR_COUNTERS** - This value is used to allocate an array to save and restore the counters - specified by ``PLAT_AMU_GROUP1_COUNTERS_MASK`` on CPU suspend. - This value should be equal to the highest bit position set in the - mask, plus 1. The maximum number of group 1 counters in AMUv1 is 16. + counters are enabled. File : plat_macros.S [mandatory] ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -872,6 +865,35 @@ twice. On success the function should return 0 and a negative error code otherwise. +Function : plat_get_enc_key_info() [when FW_ENC_STATUS == 0 or 1] +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +:: + + Arguments : enum fw_enc_status_t fw_enc_status, uint8_t *key, + size_t *key_len, unsigned int *flags, const uint8_t *img_id, + size_t img_id_len + Return : int + +This function provides a symmetric key (either SSK or BSSK depending on +fw_enc_status) which is invoked during runtime decryption of encrypted +firmware images. `plat/common/plat_bl_common.c` provides a dummy weak +implementation for testing purposes which must be overridden by the platform +trying to implement a real world firmware encryption use-case. + +It also allows the platform to pass symmetric key identifier rather than +actual symmetric key which is useful in cases where the crypto backend provides +secure storage for the symmetric key. So in this case ``ENC_KEY_IS_IDENTIFIER`` +flag must be set in ``flags``. + +In addition to above a platform may also choose to provide an image specific +symmetric key/identifier using img_id. + +On success the function should return 0 and a negative error code otherwise. + +Note that this API depends on ``DECRYPTION_SUPPORT`` build flag which is +marked as experimental. + Common optional modifications ----------------------------- @@ -1087,6 +1109,48 @@ can override the common implementation to define a different prefix string for the log output. The implementation should be robust to future changes that increase the number of log levels. +Function : plat_get_soc_version() +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +:: + + Argument : void + Return : int32_t + +This function returns soc version which mainly consist of below fields + +:: + + soc_version[30:24] = JEP-106 continuation code for the SiP + soc_version[23:16] = JEP-106 identification code with parity bit for the SiP + soc_version[15:0] = Implementation defined SoC ID + +Function : plat_get_soc_revision() +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +:: + + Argument : void + Return : int32_t + +This function returns soc revision in below format + +:: + + soc_revision[0:30] = SOC revision of specific SOC + +Function : plat_is_smccc_feature_available() +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +:: + + Argument : u_register_t + Return : int32_t + +This function returns SMC_ARCH_CALL_SUCCESS if the platform supports +the SMCCC function specified in the argument; otherwise returns +SMC_ARCH_CALL_NOT_SUPPORTED. + Modifications specific to a Boot Loader stage --------------------------------------------- @@ -1366,7 +1430,7 @@ are platform specific. On Arm standard platforms, the arguments received are : - arg0 - Points to load address of HW_CONFIG if present + arg0 - Points to load address of FW_CONFIG arg1 - ``meminfo`` structure populated by BL1. The platform copies the contents of ``meminfo`` as it may be subsequently overwritten by BL2. @@ -1678,6 +1742,10 @@ In Arm standard platforms, the arguments received are : which is list of executable images following BL31, arg1 - Points to load address of SOC_FW_CONFIG if present + except in case of Arm FVP platform. + + In case of Arm FVP platform, Points to load address + of FW_CONFIG. arg2 - Points to load address of HW_CONFIG if present @@ -1832,6 +1900,21 @@ frequency for the CPU's generic timer. This value will be programmed into the of the system counter, which is retrieved from the first entry in the frequency modes table. +Function : plat_arm_set_twedel_scr_el3() [optional] +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +:: + + Argument : void + Return : uint32_t + +This function is used in v8.6+ systems to set the WFE trap delay value in +SCR_EL3. If this function returns TWED_DISABLED or is left unimplemented, this +feature is not enabled. The only hook provided is to set the TWED fields in +SCR_EL3, there are similar fields in HCR_EL2, SCTLR_EL2, and SCTLR_EL1 to adjust +the WFE trap delays in lower ELs and these fields should be set by the +appropriate EL2 or EL1 code depending on the platform configuration. + #define : PLAT_PERCPU_BAKERY_LOCK_SIZE [optional] ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -1883,23 +1966,27 @@ be higher than Normal |SDEI| priority. Functions ......... -Function: int plat_sdei_validate_entry_point(uintptr_t ep) [optional] -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +Function: int plat_sdei_validate_entry_point() [optional] +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ :: - Argument: uintptr_t + Argument: uintptr_t ep, unsigned int client_mode Return: int -This function validates the address of client entry points provided for both -event registration and *Complete and Resume* |SDEI| calls. The function -takes one argument, which is the address of the handler the |SDEI| client -requested to register. The function must return ``0`` for successful validation, -or ``-1`` upon failure. +This function validates the entry point address of the event handler provided by +the client for both event registration and *Complete and Resume* |SDEI| calls. +The function ensures that the address is valid in the client translation regime. + +The second argument is the exception level that the client is executing in. It +can be Non-Secure EL1 or Non-Secure EL2. + +The function must return ``0`` for successful validation, or ``-1`` upon failure. The default implementation always returns ``0``. On Arm platforms, this function -is implemented to translate the entry point to physical address, and further to -ensure that the address is located in Non-secure DRAM. +translates the entry point address within the client translation regime and +further ensures that the resulting physical address is located in Non-secure +DRAM. Function: void plat_sdei_handle_masked_trigger(uint64_t mpidr, unsigned int intr) [optional] ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -1922,6 +2009,53 @@ interrupt and the interrupt ID are passed as parameters. The default implementation only prints out a warning message. +.. _porting_guide_trng_requirements: + +TRNG porting requirements +~~~~~~~~~~~~~~~~~~~~~~~~~ + +The |TRNG| backend requires the platform to provide the following values +and mandatory functions. + +Values +...... + +value: uuid_t plat_trng_uuid [mandatory] +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +This value must be defined to the UUID of the TRNG backend that is specific to +the hardware after ``plat_trng_setup`` function is called. This value must +conform to the SMCCC calling convention; The most significant 32 bits of the +UUID must not equal ``0xffffffff`` or the signed integer ``-1`` as this value in +w0 indicates failure to get a TRNG source. + +Functions +......... + +Function: void plat_entropy_setup(void) [mandatory] +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +:: + + Argument: none + Return: none + +This function is expected to do platform-specific initialization of any TRNG +hardware. This may include generating a UUID from a hardware-specific seed. + +Function: bool plat_get_entropy(uint64_t \*out) [mandatory] +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +:: + + Argument: uint64_t * + Return: bool + Out : when the return value is true, the entropy has been written into the + storage pointed to + +This function writes entropy into storage provided by the caller. If no entropy +is available, it must return false and the storage must not be written. + Power State Coordination Interface (in BL31) -------------------------------------------- @@ -2388,9 +2522,7 @@ FVP can be configured to use either GICv2 or GICv3 depending on the build flag ``FVP_USE_GIC_DRIVER`` (See :ref:`build_options_arm_fvp_platform` for more details). -See also: `Interrupt Controller Abstraction APIs`__. - -.. __: ../design/platform-interrupt-controller-API.rst +See also: :ref:`Interrupt Controller Abstraction APIs<Platform Interrupt Controller API>`. Function : plat_interrupt_type_to_line() [mandatory] ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -2515,9 +2647,7 @@ This API is used by the CPU to indicate to the platform IC that processing of the highest pending interrupt has begun. It should return the raw, unmodified value obtained from the interrupt controller when acknowledging an interrupt. The actual interrupt number shall be extracted from this raw value using the API -`plat_ic_get_interrupt_id()`__. - -.. __: ../design/platform-interrupt-controller-API.rst#function-unsigned-int-plat-ic-get-interrupt-id-unsigned-int-raw-optional +`plat_ic_get_interrupt_id()<plat_ic_get_interrupt_id>`. This function in Arm standard platforms using GICv2, reads the *Interrupt Acknowledge Register* (``GICC_IAR``). This changes the state of the highest @@ -2641,12 +2771,13 @@ Function : plat_crash_console_flush [mandatory] :: Argument : void - Return : int + Return : void This API is used by the crash reporting mechanism to force write of all buffered data on the designated crash console. It should only use general purpose -registers x0 through x5 to do its work. The return value is 0 on successful -completion; otherwise the return value is -1. +registers x0 through x5 to do its work. + +.. _External Abort handling and RAS Support: External Abort handling and RAS Support --------------------------------------- @@ -2763,6 +2894,19 @@ build system. to ``no``. If any of the options ``EL3_PAYLOAD_BASE`` or ``PRELOADED_BL33_BASE`` are used, this flag will be set to ``no`` automatically. +Platform include paths +---------------------- + +Platforms are allowed to add more include paths to be passed to the compiler. +The ``PLAT_INCLUDES`` variable is used for this purpose. This is needed in +particular for the file ``platform_def.h``. + +Example: + +.. code:: c + + PLAT_INCLUDES += -Iinclude/plat/myplat/include + C Library --------- @@ -2844,7 +2988,7 @@ amount of open resources per driver. -------------- -*Copyright (c) 2013-2019, Arm Limited and Contributors. All rights reserved.* +*Copyright (c) 2013-2021, Arm Limited and Contributors. All rights reserved.* .. _PSCI: http://infocenter.arm.com/help/topic/com.arm.doc.den0022c/DEN0022C_Power_State_Coordination_Interface.pdf .. _Arm Generic Interrupt Controller version 2.0 (GICv2): http://infocenter.arm.com/help/topic/com.arm.doc.ihi0048b/index.html diff --git a/docs/getting_started/prerequisites.rst b/docs/getting_started/prerequisites.rst index 3e0c8fff2..91ecdf31c 100644 --- a/docs/getting_started/prerequisites.rst +++ b/docs/getting_started/prerequisites.rst @@ -60,7 +60,7 @@ supporting tools: The following libraries are required for Trusted Board Boot support: -- mbed TLS == 2.16.2 (tag: ``mbedtls-2.16.2``) +- mbed TLS == 2.24.0 (tag: ``mbedtls-2.24.0``) These tools are optional: diff --git a/docs/getting_started/psci-lib-integration-guide.rst b/docs/getting_started/psci-lib-integration-guide.rst index 1351fff00..37352659d 100644 --- a/docs/getting_started/psci-lib-integration-guide.rst +++ b/docs/getting_started/psci-lib-integration-guide.rst @@ -538,9 +538,9 @@ workarounds. -------------- -*Copyright (c) 2016-2019, Arm Limited and Contributors. All rights reserved.* +*Copyright (c) 2016-2020, Arm Limited and Contributors. All rights reserved.* .. _PSCI spec: http://infocenter.arm.com/help/topic/com.arm.doc.den0022c/DEN0022C_Power_State_Coordination_Interface.pdf -.. _SMCCC: https://silver.arm.com/download/ARM_and_AMBA_Architecture/AR570-DA-80002-r0p0-00rel0/ARM_DEN0028A_SMC_Calling_Convention.pdf +.. _SMCCC: https://developer.arm.com/docs/den0028/latest .. _PSCI specification: http://infocenter.arm.com/help/topic/com.arm.doc.den0022c/DEN0022C_Power_State_Coordination_Interface.pdf .. _PSCI Specification: http://infocenter.arm.com/help/topic/com.arm.doc.den0022c/DEN0022C_Power_State_Coordination_Interface.pdf diff --git a/docs/getting_started/rt-svc-writers-guide.rst b/docs/getting_started/rt-svc-writers-guide.rst index 5375b659d..b3758b824 100644 --- a/docs/getting_started/rt-svc-writers-guide.rst +++ b/docs/getting_started/rt-svc-writers-guide.rst @@ -314,7 +314,7 @@ provide this information.... -------------- -*Copyright (c) 2014-2019, Arm Limited and Contributors. All rights reserved.* +*Copyright (c) 2014-2020, Arm Limited and Contributors. All rights reserved.* -.. _SMCCC: http://infocenter.arm.com/help/topic/com.arm.doc.den0028a/index.html +.. _SMCCC: https://developer.arm.com/docs/den0028/latest .. _PSCI: http://infocenter.arm.com/help/topic/com.arm.doc.den0022c/DEN0022C_Power_State_Coordination_Interface.pdf diff --git a/docs/getting_started/tools-build.rst b/docs/getting_started/tools-build.rst index bb707cb7c..c050f5851 100644 --- a/docs/getting_started/tools-build.rst +++ b/docs/getting_started/tools-build.rst @@ -135,6 +135,33 @@ verbose. The following command should be used to obtain help about the tool: ./tools/cert_create/cert_create -h +.. _tools_build_enctool: + +Building the Firmware Encryption Tool +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The ``encrypt_fw`` tool is built as part of the TF-A build process when the +``fip`` make target is specified, DECRYPTION_SUPPORT and TBB are enabled, but +it can also be built separately with the following command: + +.. code:: shell + + make PLAT=<platform> [DEBUG=1] [V=1] enctool + +``DEBUG=1`` builds the tool in debug mode. ``V=1`` makes the build process more +verbose. The following command should be used to obtain help about the tool: + +.. code:: shell + + ./tools/encrypt_fw/encrypt_fw -h + +Note that the enctool in its current implementation only supports encryption +key to be provided in plain format. A typical implementation can very well +extend this tool to support custom techniques to protect encryption key. + +Also, a user may choose to provide encryption key or nonce as an input file +via using ``cat <filename>`` instead of a hex string. + -------------- *Copyright (c) 2019, Arm Limited. All rights reserved.* diff --git a/docs/global_substitutions.txt b/docs/global_substitutions.txt index 491b160e6..24ac8300e 100644 --- a/docs/global_substitutions.txt +++ b/docs/global_substitutions.txt @@ -6,12 +6,15 @@ .. |COT| replace:: :term:`COT` .. |CSS| replace:: :term:`CSS` .. |CVE| replace:: :term:`CVE` +.. |DTB| replace:: :term:`DTB` .. |DS-5| replace:: :term:`DS-5` .. |DSU| replace:: :term:`DSU` .. |DT| replace:: :term:`DT` .. |EL| replace:: :term:`EL` .. |EHF| replace:: :term:`EHF` +.. |FCONF| replace:: :term:`FCONF` .. |FDT| replace:: :term:`FDT` +.. |FFA| replace:: :term:`FFA` .. |FIP| replace:: :term:`FIP` .. |FVP| replace:: :term:`FVP` .. |FWU| replace:: :term:`FWU` @@ -42,7 +45,6 @@ .. |SMCCC| replace:: :term:`SMCCC` .. |SoC| replace:: :term:`SoC` .. |SP| replace:: :term:`SP` -.. |SPCI| replace:: :term:`SPCI` .. |SPD| replace:: :term:`SPD` .. |SPM| replace:: :term:`SPM` .. |SSBS| replace:: :term:`SSBS` @@ -54,6 +56,7 @@ .. |TF-M| replace:: :term:`TF-M` .. |TLB| replace:: :term:`TLB` .. |TLK| replace:: :term:`TLK` +.. |TRNG| replace:: :term:`TRNG` .. |TSP| replace:: :term:`TSP` .. |TZC| replace:: :term:`TZC` .. |UBSAN| replace:: :term:`UBSAN` diff --git a/docs/glossary.rst b/docs/glossary.rst index 2f19df59c..54820e4b6 100644 --- a/docs/glossary.rst +++ b/docs/glossary.rst @@ -18,6 +18,9 @@ You can find additional definitions in the `Arm Glossary`_. API Application Programming Interface + AT + Address Translation + BTI Branch Target Identification. An Armv8.5 extension providing additional control flow integrity around indirect branches and their targets. @@ -42,15 +45,24 @@ You can find additional definitions in the `Arm Glossary`_. DT Device Tree + DTB + Device Tree Blob + EL Exception Level EHF Exception Handling Framework + FCONF + Firmware Configuration Framework + FDT Flattened Device Tree + FFA + Firmware Framework for A-class processors + FIP Firmware Image Package @@ -101,6 +113,9 @@ You can find additional definitions in the `Arm Glossary`_. PMF Performance Measurement Framework + PSA + Platform Security Architecture + PSCI Power State Coordination Interface @@ -143,9 +158,6 @@ You can find additional definitions in the `Arm Glossary`_. SP Secure Partition - SPCI - Secure Partition Client Interface - SPD Secure Payload Dispatcher @@ -181,6 +193,9 @@ You can find additional definitions in the `Arm Glossary`_. TLK Trusted Little Kernel. A Trusted OS from NVIDIA. + TRNG + True Randon Number Generator (hardware based) + TSP Test Secure Payload diff --git a/docs/index.rst b/docs/index.rst index 5088bfd87..cb5312753 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -14,6 +14,7 @@ Trusted Firmware-A Documentation plat/index perf/index security_advisories/index + design_documents/index change-log change-log-upcoming glossary @@ -82,7 +83,7 @@ have previously been raised against the software. -------------- -*Copyright (c) 2013-2019, Arm Limited and Contributors. All rights reserved.* +*Copyright (c) 2013-2020, Arm Limited and Contributors. All rights reserved.* .. _Armv7-A and Armv8-A: https://developer.arm.com/products/architecture/a-profile .. _Secure Monitor: http://www.arm.com/products/processors/technologies/trustzone/tee-smc.php @@ -90,4 +91,4 @@ have previously been raised against the software. .. _Trusted Board Boot Requirements CLIENT (TBBR-CLIENT): https://developer.arm.com/docs/den0006/latest/trusted-board-boot-requirements-client-tbbr-client-armv8-a .. _System Control and Management Interface (SCMI): http://infocenter.arm.com/help/topic/com.arm.doc.den0056a/DEN0056A_System_Control_and_Management_Interface.pdf .. _Software Delegated Exception Interface (SDEI): http://infocenter.arm.com/help/topic/com.arm.doc.den0054a/ARM_DEN0054A_Software_Delegated_Exception_Interface.pdf -.. _SMC Calling Convention: http://infocenter.arm.com/help/topic/com.arm.doc.den0028b/ARM_DEN0028B_SMC_Calling_Convention.pdf +.. _SMC Calling Convention: https://developer.arm.com/docs/den0028/latest diff --git a/docs/perf/index.rst b/docs/perf/index.rst index 0f49b4810..1482b80f6 100644 --- a/docs/perf/index.rst +++ b/docs/perf/index.rst @@ -8,7 +8,8 @@ Performance & Testing psci-performance-juno tsp + performance-monitoring-unit -------------- -*Copyright (c) 2019, Arm Limited. All rights reserved.* +*Copyright (c) 2019-2020, Arm Limited. All rights reserved.* diff --git a/docs/perf/performance-monitoring-unit.rst b/docs/perf/performance-monitoring-unit.rst new file mode 100644 index 000000000..5dd1af5fc --- /dev/null +++ b/docs/perf/performance-monitoring-unit.rst @@ -0,0 +1,158 @@ +Performance Monitoring Unit +=========================== + +The Performance Monitoring Unit (PMU) allows recording of architectural and +microarchitectural events for profiling purposes. + +This document gives an overview of the PMU counter configuration to assist with +implementation and to complement the PMU security guidelines given in the +:ref:`Secure Development Guidelines` document. + +.. note:: + This section applies to Armv8-A implementations which have version 3 + of the Performance Monitors Extension (PMUv3). + +PMU Counters +------------ + +The PMU makes 32 counters available at all privilege levels: + +- 31 programmable event counters: ``PMEVCNTR<n>``, where ``n`` is ``0`` to + ``30``. +- A dedicated cycle counter: ``PMCCNTR``. + +Architectural mappings +~~~~~~~~~~~~~~~~~~~~~~ + ++--------------+---------+----------------------------+ +| Counters | State | System Register Name | ++==============+=========+============================+ +| | AArch64 | ``PMEVCNTR<n>_EL0[63*:0]`` | +| Programmable +---------+----------------------------+ +| | AArch32 | ``PMEVCNTR<n>[31:0]`` | ++--------------+---------+----------------------------+ +| | AArch64 | ``PMCCNTR_EL0[63:0]`` | +| Cycle +---------+----------------------------+ +| | AArch32 | ``PMCCNTR[63:0]`` | ++--------------+---------+----------------------------+ + +.. note:: + Bits [63:32] are only available if ARMv8.5-PMU is implemented. Refer to the + `Arm ARM`_ for a detailed description of ARMv8.5-PMU features. + +Configuring the PMU for counting events +--------------------------------------- + +Each programmable counter has an associated register, ``PMEVTYPER<n>`` which +configures it. The cycle counter has the ``PMCCFILTR_EL0`` register, which has +an identical function and bit field layout as ``PMEVTYPER<n>``. In addition, +the counters are enabled (permitted to increment) via the ``PMCNTENSET`` and +``PMCR`` registers. These can be accessed at all privilege levels. + +Architectural mappings +~~~~~~~~~~~~~~~~~~~~~~ + ++-----------------------------+------------------------+ +| AArch64 | AArch32 | ++=============================+========================+ +| ``PMEVTYPER<n>_EL0[63*:0]`` | ``PMEVTYPER<n>[31:0]`` | ++-----------------------------+------------------------+ +| ``PMCCFILTR_EL0[63*:0]`` | ``PMCCFILTR[31:0]`` | ++-----------------------------+------------------------+ +| ``PMCNTENSET_EL0[63*:0]`` | ``PMCNTENSET[31:0]`` | ++-----------------------------+------------------------+ +| ``PMCR_EL0[63*:0]`` | ``PMCR[31:0]`` | ++-----------------------------+------------------------+ + +.. note:: + Bits [63:32] are reserved. + +Relevant register fields +~~~~~~~~~~~~~~~~~~~~~~~~ + +For ``PMEVTYPER<n>_EL0``/``PMEVTYPER<n>`` and ``PMCCFILTR_EL0/PMCCFILTR``, the +most important fields are: + +- ``P``: + + - Bit 31. + - If set to ``0``, will increment the associated ``PMEVCNTR<n>`` at EL1. + +- ``NSK``: + + - Bit 29. + - If equal to the ``P`` bit it enables the associated ``PMEVCNTR<n>`` at + Non-secure EL1. + - Reserved if EL3 not implemented. + +- ``NSH``: + + - Bit 27. + - If set to ``1``, will increment the associated ``PMEVCNTR<n>`` at EL2. + - Reserved if EL2 not implemented. + +- ``SH``: + + - Bit 24. + - If different to the ``NSH`` bit it enables the associated ``PMEVCNTR<n>`` + at Secure EL2. + - Reserved if Secure EL2 not implemented. + +- ``M``: + + - Bit 26. + - If equal to the ``P`` bit it enables the associated ``PMEVCNTR<n>`` at + EL3. + +- ``evtCount[15:10]``: + + - Extension to ``evtCount[9:0]``. Reserved unless ARMv8.1-PMU implemented. + +- ``evtCount[9:0]``: + + - The event number that the associated ``PMEVCNTR<n>`` will count. + +For ``PMCNTENSET_EL0``/``PMCNTENSET``, the most important fields are: + +- ``P[30:0]``: + + - Setting bit ``P[n]`` to ``1`` enables counter ``PMEVCNTR<n>``. + - The effects of ``PMEVTYPER<n>`` are applied on top of this. + In other words, the counter will not increment at any privilege level or + security state unless it is enabled here. + +- ``C``: + + - Bit 31. + - If set to ``1`` enables the cycle counter ``PMCCNTR``. + +For ``PMCR``/``PMCR_EL0``, the most important fields are: + +- ``DP``: + + - Bit 5. + - If set to ``1`` it disables the cycle counter ``PMCCNTR`` where event + counting (by ``PMEVCNTR<n>``) is prohibited (e.g. EL2 and the Secure + world). + - If set to ``0``, ``PMCCNTR`` will not be affected by this bit and + therefore will be able to count where the programmable counters are + prohibited. + +- ``E``: + + - Bit 0. + - Enables/disables counting altogether. + - The effects of ``PMCNTENSET`` and ``PMCR.DP`` are applied on top of this. + In other words, if this bit is ``0`` then no counters will increment + regardless of how the other PMU system registers or bit fields are + configured. + +.. rubric:: References + +- `Arm ARM`_ + +-------------- + +*Copyright (c) 2019-2020, Arm Limited and Contributors. All rights reserved.* + +.. _Arm ARM: https://developer.arm.com/docs/ddi0487/latest diff --git a/docs/perf/psci-performance-juno.rst b/docs/perf/psci-performance-juno.rst index c127c1c4a..eab3e4d2b 100644 --- a/docs/perf/psci-performance-juno.rst +++ b/docs/perf/psci-performance-juno.rst @@ -286,7 +286,7 @@ effects, given that these measurements are at the nano-second level. -------------- -*Copyright (c) 2019, Arm Limited and Contributors. All rights reserved.* +*Copyright (c) 2019-2020, Arm Limited and Contributors. All rights reserved.* -.. _Juno R1 platform: https://www.arm.com/files/pdf/Juno_r1_ARM_Dev_datasheet.pdf +.. _Juno R1 platform: https://static.docs.arm.com/100122/0100/arm_versatile_express_juno_r1_development_platform_(v2m_juno_r1)_technical_reference_manual_100122_0100_05_en.pdf .. _TF master as of 31/01/2017: https://git.trustedfirmware.org/TF-A/trusted-firmware-a.git/tree/?id=c38b36d diff --git a/docs/plat/allwinner.rst b/docs/plat/allwinner.rst index a1e06590a..d82380ddf 100644 --- a/docs/plat/allwinner.rst +++ b/docs/plat/allwinner.rst @@ -34,7 +34,7 @@ To build for machines with an H6 SoC: make CROSS_COMPILE=aarch64-linux-gnu- PLAT=sun50i_h6 DEBUG=1 bl31 -.. _U-Boot documentation: http://git.denx.de/?p=u-boot.git;f=board/sunxi/README.sunxi64;hb=HEAD +.. _U-Boot documentation: https://gitlab.denx.de/u-boot/u-boot/-/blob/master/board/sunxi/README.sunxi64 Trusted OS dispatcher --------------------- diff --git a/docs/plat/arm/arm-build-options.rst b/docs/plat/arm/arm-build-options.rst index d24ad231d..a1d231357 100644 --- a/docs/plat/arm/arm-build-options.rst +++ b/docs/plat/arm/arm-build-options.rst @@ -57,8 +57,7 @@ Arm Platform Build Options ``ARM_ROTPK_LOCATION`` are: - ``regs`` : return the ROTPK hash stored in the Trusted root-key storage - registers. The private key corresponding to this ROTPK hash is not - currently available. + registers. - ``devel_rsa`` : return a development public key hash embedded in the BL1 and BL2 binaries. This hash has been obtained from the RSA public key ``arm_rotpk_rsa.der``, located in ``plat/arm/board/common/rotpk``. To use @@ -70,6 +69,12 @@ Arm Platform Build Options use this option, ``arm_rotprivk_ecdsa.pem`` must be specified as ``ROT_KEY`` when creating the certificates. +- ``ARM_ROTPK_HASH``: used when ``ARM_ROTPK_LOCATION=devel_*``. Specifies the + location of the ROTPK hash. Not expected to be a build option. This defaults to + ``plat/arm/board/common/rotpk/*_sha256.bin`` depending on the specified algorithm. + Providing ``ROT_KEY`` enforces generation of the hash from the ``ROT_KEY`` and + overwrites the default hash file. + - ``ARM_TSP_RAM_LOCATION``: location of the TSP binary. Options: - ``tsram`` : Trusted SRAM (default option when TBB is not enabled) @@ -86,6 +91,13 @@ Arm Platform Build Options platforms. If this option is specified, then the path to the CryptoCell SBROM library must be specified via ``CCSBROM_LIB_PATH`` flag. +- ``ARM_SPMC_MANIFEST_DTS`` : path to an alternate manifest file used as the + SPMC Core manifest. Valid when ``SPD=spmd`` is selected. + +- ``OPTEE_SP_FW_CONFIG``: DTC build flag to include OP-TEE as SP in tb_fw_config + device tree. This flag is defined only when ``ARM_SPMC_MANIFEST_DTS`` manifest + file name contains pattern optee_sp. + For a better understanding of these options, the Arm development platform memory map is explained in the :ref:`Firmware Design`. @@ -109,6 +121,11 @@ Arm CSS Platform-Specific Build Options management operations and for SCP RAM Firmware transfer. If this option is set to 1, then SCMI/SDS drivers will be used. Default is 0. + - ``CSS_SGI_CHIP_COUNT``: Configures the number of chips on a SGI/RD platform + which supports multi-chip operation. If ``CSS_SGI_CHIP_COUNT`` is set to any + valid value greater than 1, the platform code performs required configuration + to support multi-chip operation. + -------------- -*Copyright (c) 2019, Arm Limited. All rights reserved.* +*Copyright (c) 2019-2020, Arm Limited. All rights reserved.* diff --git a/docs/plat/arm/arm_fpga/index.rst b/docs/plat/arm/arm_fpga/index.rst new file mode 100644 index 000000000..5427c1dde --- /dev/null +++ b/docs/plat/arm/arm_fpga/index.rst @@ -0,0 +1,97 @@ +Arm FPGA Platform +================= + +This platform supports FPGA images used internally in Arm Ltd., for +testing and bringup of new cores. With that focus, peripheral support is +minimal: there is no mass storage or display output, for instance. Also +this port ignores any power management features of the platform. +Some interconnect setup is done internally by the platform, so the TF-A code +just needs to setup UART and GIC. + +The FPGA platform requires to pass on a DTB for the non-secure payload +(mostly Linux), so we let TF-A use information from the DTB for dynamic +configuration: the UART and GIC base addresses are read from there. + +As a result this port is a fairly generic BL31-only port, which can serve +as a template for a minimal new (and possibly DT-based) platform port. + +The aim of this port is to support as many FPGA images as possible with +a single build. Image specific data must be described in the DTB or should +be auto-detected at runtime. + +As the number and topology layout of the CPU cores differs significantly +across the various images, this is detected at runtime by BL31. +The /cpus node in the DT will be added and filled accordingly, as long as +it does not exist already. + +Platform-specific build options +------------------------------- + +- ``SUPPORT_UNKNOWN_MPID`` : Boolean option to allow unknown MPIDR registers. + Normally TF-A panics if it encounters a MPID value not matched to its + internal list, but for new or experimental cores this creates a lot of + churn. With this option, the code will fall back to some basic CPU support + code (only architectural system registers, and no errata). + Default value of this flag is 1. + +- ``PRELOADED_BL33_BASE`` : Physical address of the BL33 non-secure payload. + It must have been loaded into DRAM already, typically this is done by + the script that also loads BL31 and the DTB. + It defaults to 0x80080000, which is the traditional load address for an + arm64 Linux kernel. + +- ``FPGA_PRELOADED_DTB_BASE`` : Physical address of the flattened device + tree blob (DTB). This DT will be used by TF-A for dynamic configuration, + so it must describe at least the UART and a GICv3 interrupt controller. + The DT gets amended by the code, to potentially add a command line and + fill the CPU topology nodes. It will also be passed on to BL33, by + putting its address into the x0 register before jumping to the entry + point (following the Linux kernel boot protocol). + It defaults to 0x80070000, which is 64KB before the BL33 load address. + +- ``FPGA_PRELOADED_CMD_LINE`` : Physical address of the command line to + put into the devicetree blob. Due to the lack of a proper bootloader, + a command line can be put somewhere into memory, so that BL31 will + detect it and copy it into the DTB passed on to BL33. + To avoid random garbage, there needs to be a "CMD:" signature before the + actual command line. + Defaults to 0x1000, which is normally in the "ROM" space of the typical + FPGA image (which can be written by the FPGA payload uploader, but is + read-only to the CPU). The FPGA payload tool should be given a text file + containing the desired command line, prefixed by the "CMD:" signature. + +Building the TF-A image +----------------------- + + .. code:: shell + + make PLAT=arm_fgpa DEBUG=1 + + This will use the default load addresses as described above. When those + addresses need to differ for a certain setup, they can be passed on the + make command line: + + .. code:: shell + + make PLAT=arm_fgpa DEBUG=1 PRELOADED_BL33_BASE=0x80200000 FPGA_PRELOADED_DTB_BASE=0x80180000 bl31 + +Running the TF-A image +---------------------- + +After building TF-A, the actual TF-A code will be located in ``bl31.bin`` in +the build directory. +Additionally there is a ``bl31.axf`` ELF file, which contains BL31, as well +as some simple ROM trampoline code (required by the Arm FPGA boot flow) and +a generic DTB to support most of the FPGA images. This can be simply handed +over to the FPGA payload uploader, which will take care of loading the +components at their respective load addresses. In addition to this file +you need at least a BL33 payload (typically a Linux kernel image), optionally +a Linux initrd image file and possibly a command line: + + .. code:: shell + + fpga-run ... -m bl31.axf -l auto -m Image -l 0x80080000 -m initrd.gz -l 0x84000000 -m cmdline.txt -l 0x1000 + +-------------- + +*Copyright (c) 2020, Arm Limited. All rights reserved.* diff --git a/docs/plat/arm/fvp/index.rst b/docs/plat/arm/fvp/index.rst index 37010e1a5..235b7b687 100644 --- a/docs/plat/arm/fvp/index.rst +++ b/docs/plat/arm/fvp/index.rst @@ -12,8 +12,9 @@ Arm FVPs without shifted affinities, and that do not support threaded CPU cores (64-bit host machine only). .. note:: - The FVP models used are Version 11.6 Build 45, unless otherwise stated. + The FVP models used are Version 11.12 Build 38, unless otherwise stated. +- ``FVP_Base_AEMvA`` - ``FVP_Base_AEMv8A-AEMv8A`` - ``FVP_Base_AEMv8A-AEMv8A-AEMv8A-AEMv8A-CCN502`` - ``FVP_Base_RevC-2xAEMv8A`` @@ -26,6 +27,8 @@ Arm FVPs without shifted affinities, and that do not support threaded CPU cores - ``FVP_Base_Cortex-A57x2-A53x4`` - ``FVP_Base_Cortex-A57x4-A53x4`` - ``FVP_Base_Cortex-A57x4`` +- ``FVP_Base_Cortex-A65x4`` +- ``FVP_Base_Cortex-A65AEx8`` - ``FVP_Base_Cortex-A72x4-A53x4`` - ``FVP_Base_Cortex-A72x4`` - ``FVP_Base_Cortex-A73x4-A53x4`` @@ -34,19 +37,28 @@ Arm FVPs without shifted affinities, and that do not support threaded CPU cores - ``FVP_Base_Cortex-A76x4`` - ``FVP_Base_Cortex-A76AEx4`` - ``FVP_Base_Cortex-A76AEx8`` -- ``FVP_Base_Cortex-A77x4`` (Version 11.7 build 36) +- ``FVP_Base_Cortex-A77x4`` +- ``FVP_Base_Cortex-A78x4`` +- ``FVP_Base_Neoverse-E1x1`` +- ``FVP_Base_Neoverse-E1x2`` +- ``FVP_Base_Neoverse-E1x4`` - ``FVP_Base_Neoverse-N1x4`` -- ``FVP_Base_Zeusx4`` -- ``FVP_CSS_SGI-575`` (Version 11.3 build 42) -- ``FVP_CSS_SGM-775`` (Version 11.3 build 42) -- ``FVP_RD_E1Edge`` (Version 11.3 build 42) -- ``FVP_RD_N1Edge`` +- ``FVP_Base_Neoverse-V1x4`` +- ``FVP_CSS_SGI-575`` (Version 11.10 build 36) +- ``FVP_CSS_SGM-775`` +- ``FVP_RD_E1_edge`` (Version 11.9 build 41) +- ``FVP_RD_N1_edge`` (Version 11.10 build 36) +- ``FVP_RD_N1_edge_dual`` (Version 11.10 build 36) +- ``FVP_RD_Daniel`` (Version 11.13 build 10) +- ``FVP_RD_N2`` (Version 11.13 build 10) +- ``FVP_TC0`` (Version 0.0 build 6114) - ``Foundation_Platform`` The latest version of the AArch32 build of TF-A has been tested on the following Arm FVPs without shifted affinities, and that do not support threaded CPU cores (64-bit host machine only). +- ``FVP_Base_AEMvA`` - ``FVP_Base_AEMv8A-AEMv8A`` - ``FVP_Base_Cortex-A32x4`` @@ -114,14 +126,9 @@ Arm FVP Platform Specific Build Options - ``FVP_USE_GIC_DRIVER`` : Selects the GIC driver to be built. Options: - - ``FVP_GIC600`` : The GIC600 implementation of GICv3 is selected - ``FVP_GICV2`` : The GICv2 only driver is selected - ``FVP_GICV3`` : The GICv3 only driver is selected (default option) -- ``FVP_USE_SP804_TIMER`` : Use the SP804 timer instead of the Generic Timer - for functions that wait for an arbitrary time length (udelay and mdelay). - The default value is 0. - - ``FVP_HW_CONFIG_DTS`` : Specify the path to the DTS file to be compiled to DTB and packaged in FIP as the HW_CONFIG. See :ref:`Firmware Design` for details on HW_CONFIG. By default, this is initialized to a sensible DTS @@ -135,6 +142,11 @@ Arm FVP Platform Specific Build Options HW_CONFIG blob instead of the DTS file. This option is useful to override the default HW_CONFIG selected by the build system. +- ``FVP_GICR_REGION_PROTECTION``: Mark the redistributor pages of + inactive/fused CPU cores as read-only. The default value of this option + is ``0``, which means the redistributor pages of all CPU cores are marked + as read and write. + Booting Firmware Update images ------------------------------ @@ -277,15 +289,15 @@ And the FVP binary can be run with the following command: -C cluster0.NUM_CORES=4 \ -C cluster1.NUM_CORES=4 \ -C cache_state_modelled=1 \ - -C cluster0.cpu0.RVBAR=0x04020000 \ - -C cluster0.cpu1.RVBAR=0x04020000 \ - -C cluster0.cpu2.RVBAR=0x04020000 \ - -C cluster0.cpu3.RVBAR=0x04020000 \ - -C cluster1.cpu0.RVBAR=0x04020000 \ - -C cluster1.cpu1.RVBAR=0x04020000 \ - -C cluster1.cpu2.RVBAR=0x04020000 \ - -C cluster1.cpu3.RVBAR=0x04020000 \ - --data cluster0.cpu0="<path-to>/bl31.bin"@0x04020000 \ + -C cluster0.cpu0.RVBAR=0x04001000 \ + -C cluster0.cpu1.RVBAR=0x04001000 \ + -C cluster0.cpu2.RVBAR=0x04001000 \ + -C cluster0.cpu3.RVBAR=0x04001000 \ + -C cluster1.cpu0.RVBAR=0x04001000 \ + -C cluster1.cpu1.RVBAR=0x04001000 \ + -C cluster1.cpu2.RVBAR=0x04001000 \ + -C cluster1.cpu3.RVBAR=0x04001000 \ + --data cluster0.cpu0="<path-to>/bl31.bin"@0x04001000 \ --data cluster0.cpu0="<path-to>/<patched-fdt>"@0x82000000 \ --data cluster0.cpu0="<path-to>/<kernel-binary>"@0x80080000 \ --data cluster0.cpu0="<path-to>/<ramdisk.img>"@0x84000000 @@ -628,9 +640,9 @@ boot Linux with 4 CPUs using the AArch32 build of TF-A. -------------- -*Copyright (c) 2019, Arm Limited. All rights reserved.* +*Copyright (c) 2019-2020, Arm Limited. All rights reserved.* -.. _TB_FW_CONFIG for FVP: ../plat/arm/board/fvp/fdts/fvp_tb_fw_config.dts +.. _TB_FW_CONFIG for FVP: https://git.trustedfirmware.org/TF-A/trusted-firmware-a.git/tree/plat/arm/board/fvp/fdts/fvp_tb_fw_config.dts .. _Arm's website: `FVP models`_ .. _FVP models: https://developer.arm.com/products/system-design/fixed-virtual-platforms .. _Linaro Release 19.06: http://releases.linaro.org/members/arm/platforms/19.06 diff --git a/docs/plat/arm/index.rst b/docs/plat/arm/index.rst index e26f75e56..f72992b80 100644 --- a/docs/plat/arm/index.rst +++ b/docs/plat/arm/index.rst @@ -8,7 +8,10 @@ Arm Development Platforms juno/index fvp/index fvp-ve/index + tc0/index + arm_fpga/index arm-build-options + morello/index This chapter holds documentation related to Arm's development platforms, including both software models (FVPs) and hardware development boards diff --git a/docs/plat/arm/morello/index.rst b/docs/plat/arm/morello/index.rst new file mode 100644 index 000000000..b18001cae --- /dev/null +++ b/docs/plat/arm/morello/index.rst @@ -0,0 +1,33 @@ +Morello Platform +================ + +Morello is an ARMv8-A platform that implements the capability architecture extension. +The platform port present at `site <https://git.trustedfirmware.org/TF-A/trusted-firmware-a.git>`_ +provides ARMv8-A architecture enablement. + +Capability architecture specific changes will be added `here <https://git.morello-project.org/morello>`_ + +Further information on Morello Platform is available at `info <https://developer.arm.com/architectures/cpu-architecture/a-profile/morello>`_ + +Boot Sequence +------------- + +The execution begins from SCP_BL1 which loads the SCP_BL2 and starts its +execution. SCP_BL2 powers up the AP which starts execution at AP_BL31. The AP +then continues executing and hands off execution to Non-secure world (UEFI). + +Build Procedure (TF-A only) +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +- Obtain arm `toolchain <https://developer.arm.com/tools-and-software/open-source-software/developer-tools/gnu-toolchain/gnu-a/downloads>`_. + Set the CROSS_COMPILE environment variable to point to the toolchain folder. + +- Build TF-A: + + .. code:: shell + + export CROSS_COMPILE=<path-to-aarch64-gcc>/bin/aarch64-none-elf- + + make PLAT=morello all + +*Copyright (c) 2020, Arm Limited. All rights reserved.* diff --git a/docs/plat/arm/tc0/index.rst b/docs/plat/arm/tc0/index.rst new file mode 100644 index 000000000..34d1f1342 --- /dev/null +++ b/docs/plat/arm/tc0/index.rst @@ -0,0 +1,50 @@ +TC0 Total Compute Platform +========================== + +Some of the features of TC0 platform referenced in TF-A include: + +- A `System Control Processor <https://github.com/ARM-software/SCP-firmware>`_ + to abstract power and system management tasks away from application + processors. The RAM firmware for SCP is included in the TF-A FIP and is + loaded by AP BL2 from FIP in flash to SRAM for copying by SCP (SCP has access + to AP SRAM). +- GICv4 +- Trusted Board Boot +- SCMI +- MHUv2 + +Boot Sequence +------------- + +The execution begins from SCP_BL1. SCP_BL1 powers up the AP which starts +executing AP_BL1 and then executes AP_BL2 which loads the SCP_BL2 from +FIP to SRAM. The SCP has access to AP SRAM. The address and size of SCP_BL2 +is communicated to SCP using SDS. SCP copies SCP_BL2 from SRAM to its own +RAM and starts executing it. The AP then continues executing the rest of TF-A +stages including BL31 runtime stage and hands off executing to +Non-secure world (u-boot). + +Build Procedure (TF-A only) +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +- Obtain arm `toolchain <https://developer.arm.com/tools-and-software/open-source-software/developer-tools/gnu-toolchain/gnu-a/downloads>`_. + Set the CROSS_COMPILE environment variable to point to the toolchain folder. + +- Build TF-A: + + .. code:: shell + + make PLAT=tc0 BL33=<path_to_uboot.bin> \ + SCP_BL2=<path_to_scp_ramfw.bin> all fip + + Enable TBBR by adding the following options to the make command: + + .. code:: shell + + MBEDTLS_DIR=<path_to_mbedtls_directory> \ + TRUSTED_BOARD_BOOT=1 \ + GENERATE_COT=1 \ + ARM_ROTPK_LOCATION=devel_rsa \ + ROT_KEY=plat/arm/board/common/rotpk/arm_rotprivk_rsa.pem + +*Copyright (c) 2020, Arm Limited. All rights reserved.* diff --git a/docs/plat/brcm-stingray.rst b/docs/plat/brcm-stingray.rst new file mode 100644 index 000000000..95029cc3d --- /dev/null +++ b/docs/plat/brcm-stingray.rst @@ -0,0 +1,43 @@ +Broadcom Stingray +================= + +Description +----------- +Broadcom's Stingray(BCM958742t) is a multi-core processor with 8 Cortex-A72 cores. +Trusted Firmware-A (TF-A) is used to implement secure world firmware, supporting +BL2 and BL31 for Broadcom Stingray SoCs. + +On Poweron, Boot ROM will load bl2 image and Bl2 will initialize the hardware, +then loads bl31 and bl33 into DDR and boots to bl33. + +Boot Sequence +------------- + +Bootrom --> TF-A BL2 --> TF-A BL31 --> BL33(u-boot) + +Code Locations +~~~~~~~~~~~~~~ +- Trusted Firmware-A: + `link <https://git.trustedfirmware.org/TF-A/trusted-firmware-a.git/>`__ + +How to build +------------ + +Build Procedure +~~~~~~~~~~~~~~~ + +- Prepare AARCH64 toolchain. + +- Build u-boot first, and get the binary image: u-boot.bin, + +- Build TF-A + + Build fip: + + .. code:: shell + + make CROSS_COMPILE=aarch64-linux-gnu- PLAT=stingray BOARD_CFG=bcm958742t all fip BL33=u-boot.bin + +Deploy TF-A Images +~~~~~~~~~~~~~~~~~~ +The u-boot will be upstreamed soon, this doc will be updated once they are ready, and the link will be posted. diff --git a/docs/plat/hikey.rst b/docs/plat/hikey.rst index 372d38867..6c488b827 100644 --- a/docs/plat/hikey.rst +++ b/docs/plat/hikey.rst @@ -26,9 +26,6 @@ Code Locations - l-loader: `link <https://github.com/96boards-hikey/l-loader/tree/testing/hikey960_v1.2>`__ -- uefi-tools: - `link <https://git.linaro.org/uefi/uefi-tools.git>`__ - - atf-fastboot: `link <https://github.com/96boards-hikey/atf-fastboot/tree/master>`__ @@ -45,7 +42,6 @@ Build Procedure git clone https://github.com/96boards-hikey/edk2 -b testing/hikey960_v2.5 git clone https://github.com/96boards-hikey/OpenPlatformPkg -b testing/hikey960_v1.3.4 git clone https://github.com/96boards-hikey/l-loader -b testing/hikey960_v1.2 - git clone https://git.linaro.org/uefi/uefi-tools git clone https://github.com/96boards-hikey/atf-fastboot - Create the symbol link to OpenPlatformPkg in edk2. @@ -57,13 +53,12 @@ Build Procedure - Prepare AARCH64 && AARCH32 toolchain. Prepare python. -- If your hikey hardware is built by CircuitCo, update *uefi-tools/platform.config* first. *(optional)* - **Uncomment the below sentence. Otherwise, UEFI can't output messages on serial +- If your hikey hardware is built by CircuitCo, update *OpenPlatformPkg/Platforms/Hisilicon/HiKey/HiKey.dsc* first. *(optional)* console on hikey.** .. code:: shell - BUILDFLAGS=-DSERIAL_BASE=0xF8015000 + DEFINE SERIAL_BASE=0xF8015000 If your hikey hardware is built by LeMaker, nothing to do. @@ -71,19 +66,8 @@ Build Procedure .. code:: shell - BUILD_OPTION=DEBUG - export AARCH64_TOOLCHAIN=GCC5 - export UEFI_TOOLS_DIR=${BUILD_PATH}/uefi-tools - export EDK2_DIR=${BUILD_PATH}/edk2 - EDK2_OUTPUT_DIR=${EDK2_DIR}/Build/HiKey/${BUILD_OPTION}_${AARCH64_TOOLCHAIN} - # Build fastboot for Trusted Firmware-A. It's used for recovery mode. - cd ${BUILD_PATH}/atf-fastboot - CROSS_COMPILE=aarch64-linux-gnu- make PLAT=hikey DEBUG=1 - # Convert DEBUG/RELEASE to debug/release - FASTBOOT_BUILD_OPTION=$(echo ${BUILD_OPTION} | tr '[A-Z]' '[a-z]') - cd ${EDK2_DIR} - # Build UEFI & Trusted Firmware-A - ${UEFI_TOOLS_DIR}/uefi-build.sh -b ${BUILD_OPTION} -a ../arm-trusted-firmware -s ../optee_os hikey + cd {BUILD_PATH}/arm-trusted-firmware + sh ../l-loader/build_uefi.sh hikey - Generate l-loader.bin and partition table for aosp. The eMMC capacity is either 8GB or 4GB. Just change "aosp-8g" to "linux-8g" for debian. diff --git a/docs/plat/hikey960.rst b/docs/plat/hikey960.rst index 3d42a77c5..982c2c854 100644 --- a/docs/plat/hikey960.rst +++ b/docs/plat/hikey960.rst @@ -26,9 +26,6 @@ Code Locations - l-loader: `link <https://github.com/96boards-hikey/l-loader/tree/testing/hikey960_v1.2>`__ -- uefi-tools: - `link <https://git.linaro.org/uefi/uefi-tools.git>`__ - Build Procedure ~~~~~~~~~~~~~~~ @@ -42,7 +39,6 @@ Build Procedure git clone https://github.com/96boards-hikey/edk2 -b testing/hikey960_v2.5 git clone https://github.com/96boards-hikey/OpenPlatformPkg -b testing/hikey960_v1.3.4 git clone https://github.com/96boards-hikey/l-loader -b testing/hikey960_v1.2 - git clone https://git.linaro.org/uefi/uefi-tools - Create the symbol link to OpenPlatformPkg in edk2. @@ -53,13 +49,11 @@ Build Procedure - Prepare AARCH64 toolchain. -- If your hikey960 hardware is v1, update *uefi-tools/platform.config* first. *(optional)* - **Uncomment the below sentence. Otherwise, UEFI can't output messages on serial - console on hikey960 v1.** +- If your hikey960 hardware is v1, update *OpenPlatformPkg/Platforms/Hisilicon/HiKey960/HiKey960.dsc* first. *(optional)* .. code:: shell - BUILDFLAGS=-DSERIAL_BASE=0xFDF05000 + DEFINE SERIAL_BASE=0xFDF05000 If your hikey960 hardware is v2 or newer, nothing to do. @@ -67,14 +61,8 @@ Build Procedure .. code:: shell - BUILD_OPTION=DEBUG - export AARCH64_TOOLCHAIN=GCC5 - export UEFI_TOOLS_DIR=${BUILD_PATH}/uefi-tools - export EDK2_DIR=${BUILD_PATH}/edk2 - EDK2_OUTPUT_DIR=${EDK2_DIR}/Build/HiKey960/${BUILD_OPTION}_${AARCH64_TOOLCHAIN} - cd ${EDK2_DIR} - # Build UEFI & Trusted Firmware-A - ${UEFI_TOOLS_DIR}/uefi-build.sh -b ${BUILD_OPTION} -a ../arm-trusted-firmware -s ../optee_os hikey960 + cd {BUILD_PATH}/arm-trusted-firmware + sh ../l-loader/build_uefi.sh hikey960 - Generate l-loader.bin and partition table. *Make sure that you're using the sgdisk in the l-loader directory.* diff --git a/docs/plat/imx8m.rst b/docs/plat/imx8m.rst index 8acd13cf7..f184b6990 100644 --- a/docs/plat/imx8m.rst +++ b/docs/plat/imx8m.rst @@ -32,6 +32,8 @@ Build Procedure Target_SoC should be "imx8mq" for i.MX8MQ SoC. Target_SoC should be "imx8mm" for i.MX8MM SoC. + Target_SoC should be "imx8mn" for i.MX8MN SoC. + Target_SoC should be "imx8mp" for i.MX8MP SoC. Deploy TF-A Images ~~~~~~~~~~~~~~~~~~ diff --git a/docs/plat/index.rst b/docs/plat/index.rst index 63d29a9be..3cbb55246 100644 --- a/docs/plat/index.rst +++ b/docs/plat/index.rst @@ -9,6 +9,7 @@ Platform Ports allwinner arm/index + meson-axg meson-gxbb meson-gxl meson-g12a @@ -18,6 +19,7 @@ Platform Ports intel-stratix10 marvell/index mt8183 + mt8192 nvidia-tegra warp7 imx8 @@ -26,9 +28,11 @@ Platform Ports poplar qemu qemu-sbsa + qti rpi3 rpi4 rcar-gen3 + rz-g2 rockchip socionext-uniphier synquacer @@ -36,6 +40,7 @@ Platform Ports ti-k3 xilinx-versal xilinx-zynqmp + brcm-stingray This section provides a list of supported upstream *platform ports* and the documentation associated with them. @@ -50,7 +55,8 @@ documentation associated with them. - Arm Neoverse Reference Design E1 Edge (RD-E1-Edge) FVP - Arm SGI-575 and SGM-775 - MediaTek MT6795 and MT8173 SoCs + - Arm Morello Platform -------------- -*Copyright (c) 2019, Arm Limited. All rights reserved.* +*Copyright (c) 2019-2020, Arm Limited. All rights reserved.* diff --git a/docs/plat/marvell/armada/build.rst b/docs/plat/marvell/armada/build.rst new file mode 100644 index 000000000..e55ce3c09 --- /dev/null +++ b/docs/plat/marvell/armada/build.rst @@ -0,0 +1,378 @@ +TF-A Build Instructions for Marvell Platforms +============================================= + +This section describes how to compile the Trusted Firmware-A (TF-A) project for Marvell's platforms. + +Build Instructions +------------------ +(1) Set the cross compiler + + .. code:: shell + + > export CROSS_COMPILE=/path/to/toolchain/aarch64-linux-gnu- + +(2) Set path for FIP images: + +Set U-Boot image path (relatively to TF-A root or absolute path) + + .. code:: shell + + > export BL33=path/to/u-boot.bin + +For example: if U-Boot project (and its images) is located at ``~/project/u-boot``, +BL33 should be ``~/project/u-boot/u-boot.bin`` + + .. note:: + + *u-boot.bin* should be used and not *u-boot-spl.bin* + +Set MSS/SCP image path (mandatory only for A7K/8K/CN913x) + + .. code:: shell + + > export SCP_BL2=path/to/mrvl_scp_bl2*.img + +(3) Armada-37x0 build requires WTP tools installation. + +See below in the section "Tools and external components installation". +Install ARM 32-bit cross compiler, which is required for building WTMI image for CM3 + + .. code:: shell + + > sudo apt-get install gcc-arm-linux-gnueabi + +(4) Clean previous build residuals (if any) + + .. code:: shell + + > make distclean + +(5) Build TF-A + +There are several build options: + +- PLAT + + Supported Marvell platforms are: + + - a3700 - A3720 DB, EspressoBin and Turris MOX + - a70x0 + - a70x0_amc - AMC board + - a80x0 + - a80x0_mcbin - MacchiatoBin + - a80x0_puzzle - IEI Puzzle-M801 + - t9130 - CN913x + +- DEBUG + + Default is without debug information (=0). in order to enable it use ``DEBUG=1``. + Must be disabled when building UART recovery images due to current console driver + implementation that is not compatible with Xmodem protocol used for boot image download. + +- LOG_LEVEL + + Defines the level of logging which will be purged to the default output port. + + - 0 - LOG_LEVEL_NONE + - 10 - LOG_LEVEL_ERROR + - 20 - LOG_LEVEL_NOTICE (default for DEBUG=0) + - 30 - LOG_LEVEL_WARNING + - 40 - LOG_LEVEL_INFO (default for DEBUG=1) + - 50 - LOG_LEVEL_VERBOSE + +- USE_COHERENT_MEM + + This flag determines whether to include the coherent memory region in the + BL memory map or not. Enabled by default. + +- LLC_ENABLE + + Flag defining the LLC (L3) cache state. The cache is enabled by default (``LLC_ENABLE=1``). + +- LLC_SRAM + + Flag enabling the LLC (L3) cache SRAM support. The LLC SRAM is activated and used + by Trusted OS (OP-TEE OS, BL32). The TF-A only prepares CCU address translation windows + for SRAM address range at BL31 execution stage with window target set to DRAM-0. + When Trusted OS activates LLC SRAM, the CCU window target is changed to SRAM. + There is no reason to enable this feature if OP-TEE OS built with CFG_WITH_PAGER=n. + Only set LLC_SRAM=1 if OP-TEE OS is built with CFG_WITH_PAGER=y. + +- CM3_SYSTEM_RESET + + For Armada37x0 only, when ``CM3_SYSTEM_RESET=1``, the Cortex-M3 secure coprocessor will + be used for system reset. + TF-A will send command 0x0009 with a magic value via the rWTM mailbox interface to the + Cortex-M3 secure coprocessor. + The firmware running in the coprocessor must either implement this functionality or + ignore the 0x0009 command (which is true for the firmware from A3700-utils-marvell + repository). If this option is enabled but the firmware does not support this command, + an error message will be printed prior trying to reboot via the usual way. + + This option is needed on Turris MOX as a workaround to a HW bug which causes reset to + sometime hang the board. + +- MARVELL_SECURE_BOOT + + Build trusted(=1)/non trusted(=0) image, default is non trusted. + +- BLE_PATH + + Points to BLE (Binary ROM extension) sources folder. + Only required for A7K/8K/CN913x builds. + The parameter is optional, its default value is ``plat/marvell/armada/a8k/common/ble``. + +- MV_DDR_PATH + + For A7K/8K/CN913x, use this parameter to point to mv_ddr driver sources to allow BLE build. For A37x0, + it is used for ddr_tool build. + + Usage example: MV_DDR_PATH=path/to/mv_ddr + + The parameter is optional for A7K/8K/CN913x, when this parameter is not set, the mv_ddr + sources are expected to be located at: drivers/marvell/mv_ddr. However, the parameter + is necessary for A37x0. + + For the mv_ddr source location, check the section "Tools and external components installation" + + If MV_DDR_PATH source code is a git snapshot then provide path to the full git + repository (including .git subdir) because mv_ddr build process calls git commands. + +- CP_NUM + + Total amount of CPs (South Bridge) connected to AP. When the parameter is omitted, + the build uses the default number of CPs, which is a number of embedded CPs inside the + package: 1 or 2 depending on the SoC used. The parameter is valid for OcteonTX2 CN913x SoC + family (PLAT=t9130), which can have external CPs connected to the MCI ports. Valid + values with CP_NUM are in a range of 1 to 3. + +- DDR_TOPOLOGY + + For Armada37x0 only, the DDR topology map index/name, default is 0. + + Supported Options: + - 0 - DDR3 1CS 512MB (DB-88F3720-DDR3-Modular, EspressoBin V3-V5) + - 1 - DDR4 1CS 512MB (DB-88F3720-DDR4-Modular) + - 2 - DDR3 2CS 1GB (EspressoBin V3-V5) + - 3 - DDR4 2CS 4GB (DB-88F3720-DDR4-Modular) + - 4 - DDR3 1CS 1GB (DB-88F3720-DDR3-Modular, EspressoBin V3-V5) + - 5 - DDR4 1CS 1GB (EspressoBin V7, EspressoBin-Ultra) + - 6 - DDR4 2CS 2GB (EspressoBin V7) + - 7 - DDR3 2CS 2GB (EspressoBin V3-V5) + - CUST - CUSTOMER BOARD (Customer board settings) + +- CLOCKSPRESET + + For Armada37x0 only, the clock tree configuration preset including CPU and DDR frequency, + default is CPU_800_DDR_800. + + - CPU_600_DDR_600 - CPU at 600 MHz, DDR at 600 MHz + - CPU_800_DDR_800 - CPU at 800 MHz, DDR at 800 MHz + - CPU_1000_DDR_800 - CPU at 1000 MHz, DDR at 800 MHz + - CPU_1200_DDR_750 - CPU at 1200 MHz, DDR at 750 MHz + + Look at Armada37x0 chip package marking on board to identify correct CPU frequency. + The last line on package marking (next line after the 88F37x0 line) should contain: + + - C080 or I080 - chip with 800 MHz CPU - use ``CLOCKSPRESET=CPU_800_DDR_800`` + - C100 or I100 - chip with 1000 MHz CPU - use ``CLOCKSPRESET=CPU_1000_DDR_800`` + - C120 - chip with 1200 MHz CPU - use ``CLOCKSPRESET=CPU_1200_DDR_750`` + +- BOOTDEV + + For Armada37x0 only, the flash boot device, default is ``SPINOR``. + + Currently, Armada37x0 only supports ``SPINOR``, ``SPINAND``, ``EMMCNORM`` and ``SATA``: + + - SPINOR - SPI NOR flash boot + - SPINAND - SPI NAND flash boot + - EMMCNORM - eMMC Download Mode + + Download boot loader or program code from eMMC flash into CM3 or CA53 + Requires full initialization and command sequence + + - SATA - SATA device boot + + Image needs to be stored at disk LBA 0 or at disk partition with + MBR type 0x4d (ASCII 'M' as in Marvell) or at disk partition with + GPT name ``MARVELL BOOT PARTITION``. + +- PARTNUM + + For Armada37x0 only, the boot partition number, default is 0. + + To boot from eMMC, the value should be aligned with the parameter in + U-Boot with name of ``CONFIG_SYS_MMC_ENV_PART``, whose value by default is + 1. For details about CONFIG_SYS_MMC_ENV_PART, please refer to the U-Boot + build instructions. + +- WTMI_IMG + + For Armada37x0 only, the path of the binary can point to an image which + does nothing, an image which supports EFUSE or a customized CM3 firmware + binary. The default image is ``fuse.bin`` that built from sources in WTP + folder, which is the next option. If the default image is OK, then this + option should be skipped. + + Please note that this is not a full WTMI image, just a main loop without + hardware initialization code. Final WTMI image is built from this WTMI_IMG + binary and sys-init code from the WTP directory which sets DDR and CPU + clocks according to DDR_TOPOLOGY and CLOCKSPRESET options. + +- WTP + + For Armada37x0 only, use this parameter to point to wtptools source code + directory, which can be found as a3700_utils.zip in the release. Usage + example: ``WTP=/path/to/a3700_utils`` + + If WTP source code is a git snapshot then provide path to the full git + repository (including .git subdir) because WTP build process calls git commands. + +- CRYPTOPP_PATH + + For Armada37x0 only, use this parameter to point to Crypto++ source code + directory. If this option is specified then Crypto++ source code in + CRYPTOPP_PATH directory will be automatically compiled. Crypto++ library + is required for building WTP image tool. Either CRYPTOPP_PATH or + CRYPTOPP_LIBDIR with CRYPTOPP_INCDIR needs to be specified for Armada37x0. + +- CRYPTOPP_LIBDIR + + For Armada37x0 only, use this parameter to point to the directory with + compiled Crypto++ library. By default it points to the CRYPTOPP_PATH. + +- CRYPTOPP_INCDIR + + For Armada37x0 only, use this parameter to point to the directory with + header files of Crypto++ library. By default it points to the CRYPTOPP_PATH. + + +For example, in order to build the image in debug mode with log level up to 'notice' level run + +.. code:: shell + + > make DEBUG=1 USE_COHERENT_MEM=0 LOG_LEVEL=20 PLAT=<MARVELL_PLATFORM> mrvl_flash + +And if we want to build a Armada37x0 image in debug mode with log level up to 'notice' level, +the image has the preset CPU at 1000 MHz, preset DDR3 at 800 MHz, the DDR topology of DDR4 2CS, +the image boot from SPI NOR flash partition 0, and the image is non trusted in WTP, the command +line is as following + +.. code:: shell + + > make DEBUG=1 USE_COHERENT_MEM=0 LOG_LEVEL=20 CLOCKSPRESET=CPU_1000_DDR_800 \ + MARVELL_SECURE_BOOT=0 DDR_TOPOLOGY=3 BOOTDEV=SPINOR PARTNUM=0 PLAT=a3700 \ + MV_DDR_PATH=/path/to/mv-ddr-marvell/ WTP=/path/to/A3700-utils-marvell/ \ + CRYPTOPP_PATH=/path/to/cryptopp/ BL33=/path/to/u-boot.bin \ + all fip mrvl_bootimage mrvl_flash mrvl_uart + +To build just TF-A without WTMI image (useful for A3720 Turris MOX board), run following command: + +.. code:: shell + + > make USE_COHERENT_MEM=0 PLAT=a3700 CM3_SYSTEM_RESET=1 BL33=/path/to/u-boot.bin \ + CROSS_COMPILE=aarch64-linux-gnu- mrvl_bootimage + +Here is full example how to build production release of Marvell firmware image (concatenated +binary of Marvell secure firmware, TF-A and U-Boot) for EspressoBin board (PLAT=a3700) with +1GHz CPU (CLOCKSPRESET=CPU_1000_DDR_800) and 1GB DDR4 RAM (DDR_TOPOLOGY=5): + +.. code:: shell + + > git clone https://review.trustedfirmware.org/TF-A/trusted-firmware-a + > git clone https://gitlab.denx.de/u-boot/u-boot.git + > git clone https://github.com/weidai11/cryptopp.git + > git clone https://github.com/MarvellEmbeddedProcessors/mv-ddr-marvell.git -b master + > git clone https://github.com/MarvellEmbeddedProcessors/A3700-utils-marvell.git -b master + > make -C u-boot CROSS_COMPILE=aarch64-linux-gnu- mvebu_espressobin-88f3720_defconfig u-boot.bin + > make -C trusted-firmware-a CROSS_COMPILE=aarch64-linux-gnu- CROSS_CM3=arm-linux-gnueabi- \ + USE_COHERENT_MEM=0 PLAT=a3700 CLOCKSPRESET=CPU_1000_DDR_800 DDR_TOPOLOGY=5 \ + MV_DDR_PATH=$PWD/mv-ddr-marvell/ WTP=$PWD/A3700-utils-marvell/ CRYPTOPP_PATH=$PWD/cryptopp/ \ + BL33=$PWD/u-boot/u-boot.bin mrvl_flash + +Produced Marvell firmware flash image: ``trusted-firmware-a/build/a3700/release/flash-image.bin`` + +Special Build Flags +-------------------- + +- PLAT_RECOVERY_IMAGE_ENABLE + When set this option to enable secondary recovery function when build atf. + In order to build UART recovery image this operation should be disabled for + A7K/8K/CN913x because of hardware limitation (boot from secondary image + can interrupt UART recovery process). This MACRO definition is set in + ``plat/marvell/armada/a8k/common/include/platform_def.h`` file. + +- DDR32 + In order to work in 32bit DDR, instead of the default 64bit ECC DDR, + this flag should be set to 1. + +For more information about build options, please refer to the +:ref:`Build Options` document. + + +Build output +------------ +Marvell's TF-A compilation generates 8 files: + + - ble.bin - BLe image (not available for Armada37x0) + - bl1.bin - BL1 image + - bl2.bin - BL2 image + - bl31.bin - BL31 image + - fip.bin - FIP image (contains BL2, BL31 & BL33 (U-Boot) images) + - boot-image.bin - TF-A image (contains BL1 and FIP images) + - flash-image.bin - Flashable Marvell firmware image. For Armada37x0 it + contains TIM, WTMI and boot-image.bin images. For other platforms it contains + BLe and boot-image.bin images. Should be placed on the boot flash/device. + - uart-images.tgz.bin - GZIPed TAR archive which contains Armada37x0 images + for booting via UART. Could be loaded via Marvell's WtpDownload tool from + A3700-utils-marvell repository. + +Additional make target ``mrvl_bootimage`` produce ``boot-image.bin`` file. Target +``mrvl_flash`` produce final ``flash-image.bin`` file and target ``mrvl_uart`` +produce ``uart-images.tgz.bin`` file. + + +Tools and external components installation +------------------------------------------ + +Armada37x0 Builds require installation of 3 components +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +(1) ARM cross compiler capable of building images for the service CPU (CM3). + This component is usually included in the Linux host packages. + On Debian/Ubuntu hosts the default GNU ARM tool chain can be installed + using the following command + + .. code:: shell + + > sudo apt-get install gcc-arm-linux-gnueabi + + Only if required, the default tool chain prefix ``arm-linux-gnueabi-`` can be + overwritten using the environment variable ``CROSS_CM3``. + Example for BASH shell + + .. code:: shell + + > export CROSS_CM3=/opt/arm-cross/bin/arm-linux-gnueabi + +(2) DDR initialization library sources (mv_ddr) available at the following repository + (use the "master" branch): + + https://github.com/MarvellEmbeddedProcessors/mv-ddr-marvell.git + +(3) Armada3700 tools available at the following repository + (use the "master" branch): + + https://github.com/MarvellEmbeddedProcessors/A3700-utils-marvell.git + +(4) Crypto++ library available at the following repository: + + https://github.com/weidai11/cryptopp.git + +Armada70x0 and Armada80x0 Builds require installation of an additional component +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +(1) DDR initialization library sources (mv_ddr) available at the following repository + (use the "master" branch): + + https://github.com/MarvellEmbeddedProcessors/mv-ddr-marvell.git diff --git a/docs/plat/marvell/misc/mvebu-a8k-addr-map.rst b/docs/plat/marvell/armada/misc/mvebu-a8k-addr-map.rst index e88a4582b..e88a4582b 100644 --- a/docs/plat/marvell/misc/mvebu-a8k-addr-map.rst +++ b/docs/plat/marvell/armada/misc/mvebu-a8k-addr-map.rst diff --git a/docs/plat/marvell/misc/mvebu-amb.rst b/docs/plat/marvell/armada/misc/mvebu-amb.rst index d734003d6..d734003d6 100644 --- a/docs/plat/marvell/misc/mvebu-amb.rst +++ b/docs/plat/marvell/armada/misc/mvebu-amb.rst diff --git a/docs/plat/marvell/misc/mvebu-ccu.rst b/docs/plat/marvell/armada/misc/mvebu-ccu.rst index 5bac11faf..12118e9d9 100644 --- a/docs/plat/marvell/misc/mvebu-ccu.rst +++ b/docs/plat/marvell/armada/misc/mvebu-ccu.rst @@ -1,7 +1,7 @@ Marvell CCU address decoding bindings ===================================== -CCU configration driver (1st stage address translation) for Marvell Armada 8K and 8K+ SoCs. +CCU configuration driver (1st stage address translation) for Marvell Armada 8K and 8K+ SoCs. The CCU node includes a description of the address decoding configuration. diff --git a/docs/plat/marvell/misc/mvebu-io-win.rst b/docs/plat/marvell/armada/misc/mvebu-io-win.rst index 52845ca02..749829199 100644 --- a/docs/plat/marvell/misc/mvebu-io-win.rst +++ b/docs/plat/marvell/armada/misc/mvebu-io-win.rst @@ -1,7 +1,7 @@ Marvell IO WIN address decoding bindings ======================================== -IO Window configration driver (2nd stage address translation) for Marvell Armada 8K and 8K+ SoCs. +IO Window configuration driver (2nd stage address translation) for Marvell Armada 8K and 8K+ SoCs. The IO WIN includes a description of the address decoding configuration. diff --git a/docs/plat/marvell/misc/mvebu-iob.rst b/docs/plat/marvell/armada/misc/mvebu-iob.rst index d02a7e84c..aa41822f4 100644 --- a/docs/plat/marvell/misc/mvebu-iob.rst +++ b/docs/plat/marvell/armada/misc/mvebu-iob.rst @@ -1,7 +1,7 @@ Marvell IOB address decoding bindings ===================================== -IO bridge configration driver (3rd stage address translation) for Marvell Armada 8K and 8K+ SoCs. +IO bridge configuration driver (3rd stage address translation) for Marvell Armada 8K and 8K+ SoCs. The IOB includes a description of the address decoding configuration. diff --git a/docs/plat/marvell/porting.rst b/docs/plat/marvell/armada/porting.rst index 0a71dbd54..ba8736dc6 100644 --- a/docs/plat/marvell/porting.rst +++ b/docs/plat/marvell/armada/porting.rst @@ -8,13 +8,13 @@ SoC being used is already supported in TF-A. Source Code Structure --------------------- -- The customer platform specific code shall reside under ``plat/marvell/<soc family>/<soc>_cust`` - (e.g. 'plat/marvell/a8k/a7040_cust'). +- The customer platform specific code shall reside under ``plat/marvell/armada/<soc family>/<soc>_cust`` + (e.g. 'plat/marvell/armada/a8k/a7040_cust'). - The platform name for build purposes is called ``<soc>_cust`` (e.g. ``a7040_cust``). - The build system will reuse all files from within the soc directory, and take only the porting files from the customer platform directory. -Files that require porting are located at ``plat/marvell/<soc family>/<soc>_cust`` directory. +Files that require porting are located at ``plat/marvell/armada/<soc family>/<soc>_cust`` directory. Armada-70x0/Armada-80x0 Porting @@ -36,7 +36,7 @@ memory map is required. .. note:: For a detailed information on how CCU, IOWIN, AXI-MBUS & IOB work, please refer to the SoC functional spec, and under - ``docs/marvell/misc/mvebu-[ccu/iob/amb/io-win].txt`` files. + ``docs/plat/marvell/armada/misc/mvebu-[ccu/iob/amb/io-win].rst`` files. boot loader recovery (marvell_plat_config.c) ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -64,7 +64,7 @@ boot loader recovery (marvell_plat_config.c) - Example: In A7040-DB specific implementation -(``plat/marvell/a8k/a70x0/board/marvell_plat_config.c``), the image skip is +(``plat/marvell/armada/a8k/a70x0/board/marvell_plat_config.c``), the image skip is implemented using GPIO: mpp 33 (SW5). Before resetting the board make sure there is a valid image on the next flash @@ -91,7 +91,7 @@ The BLE and consequently, the DDR init code is executed at the early stage of the boot process. Each supported platform of the TF-A has its own DDR porting file called -dram_port.c located at ``atf/plat/marvell/a8k/<platform>/board`` directory. +dram_port.c located at ``atf/plat/marvell/armada/a8k/<platform>/board`` directory. Please refer to '<path_to_mv_ddr_sources>/doc/porting_guide.txt' for detailed porting description. @@ -110,11 +110,6 @@ Comphy Porting (phy-porting-layer.h or phy-default-porting-layer.h) parameters need to be suited and the board designer should provide relevant values. - .. seealso:: - For XFI/SFI comphy type there is procedure "rx_training" which eases - process of suiting some of the parameters. Please see *uboot_cmd* - section: rx_training. - The PHY porting layer simplifies updating static values per board type, which are now grouped in one place. @@ -128,7 +123,7 @@ Comphy Porting (phy-porting-layer.h or phy-default-porting-layer.h) The porting layer for PHY was introduced in TF-A. There is one file ``drivers/marvell/comphy/phy-default-porting-layer.h`` which contains the defaults. Those default parameters are used only if there is no appropriate - phy-porting-layer.h file under: ``plat/marvell/<soc + phy-porting-layer.h file under: ``plat/marvell/armada/<soc family>/<platform>/board/phy-porting-layer.h``. If the phy-porting-layer.h exists, the phy-default-porting-layer.h is not going to be included. @@ -140,7 +135,7 @@ Comphy Porting (phy-porting-layer.h or phy-default-porting-layer.h) The easiest way to prepare the PHY porting layer for custom board is to copy existing example to a new platform: - - cp ``plat/marvell/a8k/a80x0/board/phy-porting-layer.h`` "plat/marvell/<soc family>/<platform>/board/phy-porting-layer.h" + - cp ``plat/marvell/armada/a8k/a80x0/board/phy-porting-layer.h`` "plat/marvell/armada/<soc family>/<platform>/board/phy-porting-layer.h" - adjust relevant parameters or - if different comphy index is used for specific feature, move it to proper table entry and then adjust. @@ -150,7 +145,7 @@ Comphy Porting (phy-porting-layer.h or phy-default-porting-layer.h) - Example: Example porting layer for armada-8040-db is under: - ``plat/marvell/a8k/a80x0/board/phy-porting-layer.h`` + ``plat/marvell/armada/a8k/a80x0/board/phy-porting-layer.h`` .. note:: If there is no PHY porting layer for new platform (missing diff --git a/docs/plat/marvell/build.rst b/docs/plat/marvell/build.rst deleted file mode 100644 index c10bcff79..000000000 --- a/docs/plat/marvell/build.rst +++ /dev/null @@ -1,253 +0,0 @@ -TF-A Build Instructions for Marvell Platforms -============================================= - -This section describes how to compile the Trusted Firmware-A (TF-A) project for Marvell's platforms. - -Build Instructions ------------------- -(1) Set the cross compiler - - .. code:: shell - - > export CROSS_COMPILE=/path/to/toolchain/aarch64-linux-gnu- - -(2) Set path for FIP images: - -Set U-Boot image path (relatively to TF-A root or absolute path) - - .. code:: shell - - > export BL33=path/to/u-boot.bin - -For example: if U-Boot project (and its images) is located at ``~/project/u-boot``, -BL33 should be ``~/project/u-boot/u-boot.bin`` - - .. note:: - - *u-boot.bin* should be used and not *u-boot-spl.bin* - -Set MSS/SCP image path (mandatory only for Armada80x0) - - .. code:: shell - - > export SCP_BL2=path/to/mrvl_scp_bl2*.img - -(3) Armada-37x0 build requires WTP tools installation. - -See below in the section "Tools and external components installation". -Install ARM 32-bit cross compiler, which is required for building WTMI image for CM3 - - .. code:: shell - - > sudo apt-get install gcc-arm-linux-gnueabi - -(4) Clean previous build residuals (if any) - - .. code:: shell - - > make distclean - -(5) Build TF-A - -There are several build options: - -- DEBUG - - Default is without debug information (=0). in order to enable it use ``DEBUG=1``. - Must be disabled when building UART recovery images due to current console driver - implementation that is not compatible with Xmodem protocol used for boot image download. - -- LOG_LEVEL - - Defines the level of logging which will be purged to the default output port. - - LOG_LEVEL_NONE 0 - LOG_LEVEL_ERROR 10 - LOG_LEVEL_NOTICE 20 - LOG_LEVEL_WARNING 30 - LOG_LEVEL_INFO 40 - LOG_LEVEL_VERBOSE 50 - -- USE_COHERENT_MEM - - This flag determines whether to include the coherent memory region in the - BL memory map or not. - -- LLC_ENABLE - - Flag defining the LLC (L3) cache state. The cache is enabled by default (``LLC_ENABLE=1``). - -- MARVELL_SECURE_BOOT - - Build trusted(=1)/non trusted(=0) image, default is non trusted. - -- BLE_PATH - - Points to BLE (Binary ROM extension) sources folder. Only required for A8K builds. - The parameter is optional, its default value is ``plat/marvell/a8k/common/ble``. - -- MV_DDR_PATH - - For A7/8K, use this parameter to point to mv_ddr driver sources to allow BLE build. For A37x0, - it is used for ddr_tool build. - - Usage example: MV_DDR_PATH=path/to/mv_ddr - - The parameter is optional for A7/8K, when this parameter is not set, the mv_ddr - sources are expected to be located at: drivers/marvell/mv_ddr. However, the parameter - is necessary for A37x0. - - For the mv_ddr source location, check the section "Tools and external components installation" - -- DDR_TOPOLOGY - - For Armada37x0 only, the DDR topology map index/name, default is 0. - - Supported Options: - - DDR3 1CS (0): DB-88F3720-DDR3-Modular (512MB); EspressoBIN (512MB) - - DDR4 1CS (1): DB-88F3720-DDR4-Modular (512MB) - - DDR3 2CS (2): EspressoBIN V3-V5 (1GB) - - DDR4 2CS (3): DB-88F3720-DDR4-Modular (4GB) - - DDR3 1CS (4): DB-88F3720-DDR3-Modular (1GB) - - DDR4 1CS (5): EspressoBin V7 (1GB) - - DDR4 2CS (6): EspressoBin V7 (2GB) - - CUSTOMER (CUST): Customer board, DDR3 1CS 512MB - -- CLOCKSPRESET - - For Armada37x0 only, the clock tree configuration preset including CPU and DDR frequency, - default is CPU_800_DDR_800. - - - CPU_600_DDR_600 - CPU at 600 MHz, DDR at 600 MHz - - CPU_800_DDR_800 - CPU at 800 MHz, DDR at 800 MHz - - CPU_1000_DDR_800 - CPU at 1000 MHz, DDR at 800 MHz - - CPU_1200_DDR_750 - CPU at 1200 MHz, DDR at 750 MHz - -- BOOTDEV - - For Armada37x0 only, the flash boot device, default is ``SPINOR``. - - Currently, Armada37x0 only supports ``SPINOR``, ``SPINAND``, ``EMMCNORM`` and ``SATA``: - - - SPINOR - SPI NOR flash boot - - SPINAND - SPI NAND flash boot - - EMMCNORM - eMMC Download Mode - - Download boot loader or program code from eMMC flash into CM3 or CA53 - Requires full initialization and command sequence - - - SATA - SATA device boot - -- PARTNUM - - For Armada37x0 only, the boot partition number, default is 0. - - To boot from eMMC, the value should be aligned with the parameter in - U-Boot with name of ``CONFIG_SYS_MMC_ENV_PART``, whose value by default is - 1. For details about CONFIG_SYS_MMC_ENV_PART, please refer to the U-Boot - build instructions. - -- WTMI_IMG - - For Armada37x0 only, the path of the WTMI image can point to an image which - does nothing, an image which supports EFUSE or a customized CM3 firmware - binary. The default image is wtmi.bin that built from sources in WTP - folder, which is the next option. If the default image is OK, then this - option should be skipped. - -- WTP - - For Armada37x0 only, use this parameter to point to wtptools source code - directory, which can be found as a3700_utils.zip in the release. Usage - example: ``WTP=/path/to/a3700_utils`` - - For example, in order to build the image in debug mode with log level up to 'notice' level run - - .. code:: shell - - > make DEBUG=1 USE_COHERENT_MEM=0 LOG_LEVEL=20 PLAT=<MARVELL_PLATFORM> all fip - - And if we want to build a Armada37x0 image in debug mode with log level up to 'notice' level, - the image has the preset CPU at 1000 MHz, preset DDR3 at 800 MHz, the DDR topology of DDR4 2CS, - the image boot from SPI NOR flash partition 0, and the image is non trusted in WTP, the command - line is as following - - .. code:: shell - - > make DEBUG=1 USE_COHERENT_MEM=0 LOG_LEVEL=20 CLOCKSPRESET=CPU_1000_DDR_800 \ - MARVELL_SECURE_BOOT=0 DDR_TOPOLOGY=3 BOOTDEV=SPINOR PARTNUM=0 PLAT=a3700 all fip - - Supported MARVELL_PLATFORM are: - - a3700 (for both A3720 DB and EspressoBin) - - a70x0 - - a70x0_amc (for AMC board) - - a80x0 - - a80x0_mcbin (for MacciatoBin) - -Special Build Flags --------------------- - -- PLAT_RECOVERY_IMAGE_ENABLE - When set this option to enable secondary recovery function when build atf. - In order to build UART recovery image this operation should be disabled for - a70x0 and a80x0 because of hardware limitation (boot from secondary image - can interrupt UART recovery process). This MACRO definition is set in - ``plat/marvell/a8k/common/include/platform_def.h`` file. - -For more information about build options, please refer to the -:ref:`Build Options` document. - - -Build output ------------- -Marvell's TF-A compilation generates 7 files: - - - ble.bin - BLe image - - bl1.bin - BL1 image - - bl2.bin - BL2 image - - bl31.bin - BL31 image - - fip.bin - FIP image (contains BL2, BL31 & BL33 (U-Boot) images) - - boot-image.bin - TF-A image (contains BL1 and FIP images) - - flash-image.bin - Image which contains boot-image.bin and SPL image. - Should be placed on the boot flash/device. - - -Tools and external components installation ------------------------------------------- - -Armada37x0 Builds require installation of 3 components -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -(1) ARM cross compiler capable of building images for the service CPU (CM3). - This component is usually included in the Linux host packages. - On Debian/Ubuntu hosts the default GNU ARM tool chain can be installed - using the following command - - .. code:: shell - - > sudo apt-get install gcc-arm-linux-gnueabi - - Only if required, the default tool chain prefix ``arm-linux-gnueabi-`` can be - overwritten using the environment variable ``CROSS_CM3``. - Example for BASH shell - - .. code:: shell - - > export CROSS_CM3=/opt/arm-cross/bin/arm-linux-gnueabi - -(2) DDR initialization library sources (mv_ddr) available at the following repository - (use the "mv_ddr-armada-atf-mainline" branch): - - https://github.com/MarvellEmbeddedProcessors/mv-ddr-marvell.git - -(3) Armada3700 tools available at the following repository (use the latest release branch): - - https://github.com/MarvellEmbeddedProcessors/A3700-utils-marvell.git - -Armada70x0 and Armada80x0 Builds require installation of an additional component -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -(1) DDR initialization library sources (mv_ddr) available at the following repository - (use the "mv_ddr-armada-atf-mainline" branch): - - https://github.com/MarvellEmbeddedProcessors/mv-ddr-marvell.git diff --git a/docs/plat/marvell/index.rst b/docs/plat/marvell/index.rst index 89ebdc0a4..0d33432ba 100644 --- a/docs/plat/marvell/index.rst +++ b/docs/plat/marvell/index.rst @@ -5,10 +5,10 @@ Marvell :maxdepth: 1 :caption: Contents - build - porting - misc/mvebu-a8k-addr-map - misc/mvebu-amb - misc/mvebu-ccu - misc/mvebu-io-win - misc/mvebu-iob + armada/build + armada/porting + armada/misc/mvebu-a8k-addr-map + armada/misc/mvebu-amb + armada/misc/mvebu-ccu + armada/misc/mvebu-io-win + armada/misc/mvebu-iob diff --git a/docs/plat/meson-axg.rst b/docs/plat/meson-axg.rst new file mode 100644 index 000000000..6f6732e95 --- /dev/null +++ b/docs/plat/meson-axg.rst @@ -0,0 +1,27 @@ +Amlogic Meson A113D (AXG) +=========================== + +The Amlogic Meson A113D is a SoC with a quad core Arm Cortex-A53 running at +~1.2GHz. It also contains a Cortex-M3 used as SCP. + +This port is a minimal implementation of BL31 capable of booting mainline U-Boot +and Linux: + +- SCPI support. +- Basic PSCI support (CPU_ON, CPU_OFF, SYSTEM_RESET, SYSTEM_OFF). Note that CPU0 + can't be turned off, so there is a workaround to hide this from the caller. +- GICv2 driver set up. +- Basic SIP services (read efuse data, enable/disable JTAG). + +In order to build it: + +.. code:: shell + + CROSS_COMPILE=aarch64-none-elf- make DEBUG=1 PLAT=axg [SPD=opteed] + [AML_USE_ATOS=1 when using ATOS as BL32] + +This port has been tested on a A113D board. After building it, follow the +instructions in the `U-Boot repository`_, replacing the mentioned **bl31.img** +by the one built from this port. + +.. _U-Boot repository: https://github.com/u-boot/u-boot/blob/master/doc/board/amlogic/s400.rst diff --git a/docs/plat/meson-g12a.rst b/docs/plat/meson-g12a.rst index 7cd1bf746..9588ec498 100644 --- a/docs/plat/meson-g12a.rst +++ b/docs/plat/meson-g12a.rst @@ -20,8 +20,8 @@ In order to build it: CROSS_COMPILE=aarch64-linux-gnu- make DEBUG=1 PLAT=g12a This port has been tested on a SEI510 board. After building it, follow the -instructions in the `gxlimg repository` or `U-Boot repository`_, replacing the +instructions in the `gxlimg repository`_ or `U-Boot repository`_, replacing the mentioned **bl31.img** by the one built from this port. .. _gxlimg repository: https://github.com/repk/gxlimg/blob/master/README.g12a -.. _U-Boot repository: https://github.com/u-boot/u-boot/blob/master/board/amlogic/sei510/README +.. _U-Boot repository: https://github.com/u-boot/u-boot/blob/master/doc/board/amlogic/sei510.rst diff --git a/docs/plat/meson-gxbb.rst b/docs/plat/meson-gxbb.rst index 2cd8342cb..dbd83e0bc 100644 --- a/docs/plat/meson-gxbb.rst +++ b/docs/plat/meson-gxbb.rst @@ -23,4 +23,4 @@ This port has been tested in a ODROID-C2. After building it, follow the instructions in the `U-Boot repository`_, replacing the mentioned **bl31.bin** by the one built from this port. -.. _U-Boot repository: https://github.com/u-boot/u-boot/blob/master/board/amlogic/odroid-c2/README.odroid-c2 +.. _U-Boot repository: https://gitlab.denx.de/u-boot/u-boot/-/blob/master/board/amlogic/p200/README.odroid-c2 diff --git a/docs/plat/meson-gxl.rst b/docs/plat/meson-gxl.rst index c6d850446..0751f1d00 100644 --- a/docs/plat/meson-gxl.rst +++ b/docs/plat/meson-gxl.rst @@ -20,8 +20,8 @@ In order to build it: CROSS_COMPILE=aarch64-linux-gnu- make DEBUG=1 PLAT=gxl This port has been tested on a Lepotato. After building it, follow the -instructions in the `gxlimg repository` or `U-Boot repository`_, replacing the +instructions in the `gxlimg repository`_ or `U-Boot repository`_, replacing the mentioned **bl31.img** by the one built from this port. .. _gxlimg repository: https://github.com/repk/gxlimg/blob/master/README -.. _U-Boot repository: https://github.com/u-boot/u-boot/blob/master/board/amlogic/p212/README.libretech-cc +.. _U-Boot repository: https://github.com/u-boot/u-boot/blob/master/doc/board/amlogic/p212.rst diff --git a/docs/plat/mt8192.rst b/docs/plat/mt8192.rst new file mode 100644 index 000000000..369afcfb7 --- /dev/null +++ b/docs/plat/mt8192.rst @@ -0,0 +1,21 @@ +MediaTek 8192 +============= + +MediaTek 8192 (MT8192) is a 64-bit ARM SoC introduced by MediaTek in 2020. +The chip incorporates eight cores - four Cortex-A55 little cores and Cortex-A76. +Cortex-A76 can operate at up to 2.2 GHz. +Cortex-A55 can operate at up to 2 GHz. + +Boot Sequence +------------- + +:: + + Boot Rom --> Coreboot --> TF-A BL31 --> Depthcharge --> Linux Kernel + +How to Build +------------ + +.. code:: shell + + make CROSS_COMPILE=aarch64-linux-gnu- PLAT=mt8192 DEBUG=1 COREBOOT=1 diff --git a/docs/plat/qemu-sbsa.rst b/docs/plat/qemu-sbsa.rst index 51fe41404..bc82ae526 100644 --- a/docs/plat/qemu-sbsa.rst +++ b/docs/plat/qemu-sbsa.rst @@ -19,7 +19,6 @@ and also enable methods for the CPUs. Current limitations: - Only cold boot is supported -- No instructions for how to load a BL32 (Secure Payload) To build TF-A: @@ -27,9 +26,18 @@ To build TF-A: git clone https://git.trustedfirmware.org/TF-A/trusted-firmware-a.git tfa cd tfa - export CROSS_COMPILE=aarch64-linux-gnu- + export CROSS_COMPILE=aarch64-none-elf- make PLAT=qemu_sbsa all fip +To build TF-A with BL32 and SPM enabled(StandaloneMM as a Secure Payload): + +:: + + git clone https://git.trustedfirmware.org/TF-A/trusted-firmware-a.git tfa + cd tfa + export CROSS_COMPILE=aarch64-none-elf- + make PLAT=qemu_sbsa BL32=../STANDALONE_MM.fd SPM_MM=1 EL3_EXCEPTION_HANDLING=1 all fip + Images will be placed at build/qemu_sbsa/release (bl1.bin and fip.bin). Need to copy them into top directory for EDK2 compilation. diff --git a/docs/plat/qemu.rst b/docs/plat/qemu.rst index 88196bc93..66b82473c 100644 --- a/docs/plat/qemu.rst +++ b/docs/plat/qemu.rst @@ -20,12 +20,49 @@ provided as it's generated by QEMU. Current limitations: - Only cold boot is supported -- No build instructions for QEMU\_EFI.fd and rootfs-arm64.cpio.gz -- No instructions for how to load a BL32 (Secure Payload) -``QEMU_EFI.fd`` can be dowloaded from +Getting non-TF images +--------------------- + +``QEMU_EFI.fd`` can be downloaded from http://snapshots.linaro.org/components/kernel/leg-virt-tianocore-edk2-upstream/latest/QEMU-KERNEL-AARCH64/RELEASE_GCC5/QEMU_EFI.fd +or, can be built as follows: + +.. code:: shell + + git clone https://github.com/tianocore/edk2.git + cd edk2 + git submodule update --init + make -C BaseTools + source edksetup.sh + export GCC5_AARCH64_PREFIX=aarch64-linux-gnu- + build -a AARCH64 -t GCC5 -p ArmVirtPkg/ArmVirtQemuKernel.dsc + +```` + +Then, you will get ``Build/ArmVirtQemuKernel-AARCH64/DEBUG_GCC5/FV/QEMU_EFI.fd`` + +Please note you do not need to use GCC 5 in spite of the environment variable +``GCC5_AARCH64_PREFIX`` + +The rootfs can be built by using Buildroot as follows: + +.. code:: shell + + git clone git://git.buildroot.net/buildroot.git + cd buildroot + make qemu_aarch64_virt_defconfig + utils/config -e BR2_TARGET_ROOTFS_CPIO + utils/config -e BR2_TARGET_ROOTFS_CPIO_GZIP + make olddefconfig + make + +Then, you will get ``output/images/rootfs.cpio.gz``. + +Booting via semi-hosting option +------------------------------- + Boot binaries, except BL1, are primarily loaded via semi-hosting so all binaries has to reside in the same directory as QEMU is started from. This is conveniently achieved with symlinks the local names as: @@ -41,12 +78,61 @@ To build: make CROSS_COMPILE=aarch64-none-elf- PLAT=qemu -To start (QEMU v4.1.0): +To start (QEMU v5.0.0): .. code:: shell qemu-system-aarch64 -nographic -machine virt,secure=on -cpu cortex-a57 \ -kernel Image \ - -append "console=ttyAMA0,38400 keep_bootcon root=/dev/vda2" \ - -initrd rootfs-arm64.cpio.gz -smp 2 -m 1024 -bios bl1.bin \ + -append "console=ttyAMA0,38400 keep_bootcon" \ + -initrd rootfs.cpio.gz -smp 2 -m 1024 -bios bl1.bin \ -d unimp -semihosting-config enable,target=native + +Booting via flash based firmwares +--------------------------------- + +Boot firmwares are loaded via secure FLASH0 device so ``bl1.bin`` and +``fip.bin`` should be concatenated to create a ``flash.bin`` that is flashed +onto secure FLASH0. + +- ``bl32.bin`` -> BL32 (``tee-header_v2.bin``) +- ``bl32_extra1.bin`` -> BL32 Extra1 (``tee-pager_v2.bin``) +- ``bl32_extra2.bin`` -> BL32 Extra2 (``tee-pageable_v2.bin``) +- ``bl33.bin`` -> BL33 (``QEMU_EFI.fd``) +- ``Image`` -> linux/arch/arm64/boot/Image + +To build: + +.. code:: shell + + make CROSS_COMPILE=aarch64-linux-gnu- PLAT=qemu BL32=bl32.bin \ + BL32_EXTRA1=bl32_extra1.bin BL32_EXTRA2=bl32_extra2.bin \ + BL33=bl33.bin BL32_RAM_LOCATION=tdram SPD=opteed all fip + +To build with TBBR enabled, BL31 and BL32 encrypted with test key: + +.. code:: shell + + make CROSS_COMPILE=aarch64-linux-gnu- PLAT=qemu BL32=bl32.bin \ + BL32_EXTRA1=bl32_extra1.bin BL32_EXTRA2=bl32_extra2.bin \ + BL33=bl33.bin BL32_RAM_LOCATION=tdram SPD=opteed all fip \ + MBEDTLS_DIR=<path-to-mbedtls-repo> TRUSTED_BOARD_BOOT=1 \ + GENERATE_COT=1 DECRYPTION_SUPPORT=aes_gcm FW_ENC_STATUS=0 \ + ENCRYPT_BL31=1 ENCRYPT_BL32=1 + +To build flash.bin: + +.. code:: shell + + dd if=build/qemu/release/bl1.bin of=flash.bin bs=4096 conv=notrunc + dd if=build/qemu/release/fip.bin of=flash.bin seek=64 bs=4096 conv=notrunc + +To start (QEMU v5.0.0): + +.. code:: shell + + qemu-system-aarch64 -nographic -machine virt,secure=on -cpu cortex-a57 \ + -kernel Image -no-acpi \ + -append 'console=ttyAMA0,38400 keep_bootcon' \ + -initrd rootfs.cpio.gz -smp 2 -m 1024 -bios flash.bin \ + -d unimp diff --git a/docs/plat/qti.rst b/docs/plat/qti.rst new file mode 100644 index 000000000..814e6726a --- /dev/null +++ b/docs/plat/qti.rst @@ -0,0 +1,41 @@ +Qualcomm Technologies, Inc. +=========================== + +Trusted Firmware-A (TF-A) implements the EL3 firmware layer for QTI SC7180. + + +Boot Trace +------------- + +Bootrom --> BL1/BL2 --> BL31 --> BL33 --> Linux kernel + +BL1/2 and BL33 can currently be supplied from Coreboot + Depthcharge + +How to build +------------ + +Code Locations +~~~~~~~~~~~~~~ + +- Trusted Firmware-A: + `link <https://git.trustedfirmware.org/TF-A/trusted-firmware-a.git>`__ + +Build Procedure +~~~~~~~~~~~~~~~ + +QTI SoC expects TF-A's BL31 to get integrated with other boot software +Coreboot, so only bl31.elf need to get build from the TF-A repository. + +The build command looks like + + make CROSS_COMPILE=aarch64-linux-gnu- PLAT=sc7180 COREBOOT=1 + +update value of CROSS_COMPILE argument with your cross-compilation toolchain. + +Additional QTISECLIB_PATH=<path to qtiseclib> can be added in build command. +if QTISECLIB_PATH is not added in build command stub implementation of qtiseclib +is picked. qtiseclib with stub implementation doesn't boot device. This was +added to satisfy compilation. + +QTISELIB for SC7180 is available at +`link <https://review.coreboot.org/cgit/qc_blobs.git/plain/sc7180/qtiseclib/libqtisec.a>`__ diff --git a/docs/plat/rpi4.rst b/docs/plat/rpi4.rst index beb0227c2..6e83fd730 100644 --- a/docs/plat/rpi4.rst +++ b/docs/plat/rpi4.rst @@ -60,7 +60,7 @@ As with the previous models, the GPU and its firmware are the first entity to run after the SoC gets its power. The on-chip Boot ROM loads the next stage (bootcode.bin) from flash (EEPROM), which is again GPU code. This part knows how to access the MMC controller and how to parse a FAT -filesystem, so it will load further compononents and configuration files +filesystem, so it will load further components and configuration files from the first FAT partition on the SD card. To accommodate this existing way of configuring and setting up the board, diff --git a/docs/plat/rz-g2.rst b/docs/plat/rz-g2.rst new file mode 100644 index 000000000..e7ae62040 --- /dev/null +++ b/docs/plat/rz-g2.rst @@ -0,0 +1,228 @@ +Renesas RZ/G +============ + +The "RZ/G" Family of high-end 64-bit Arm®-based microprocessors (MPUs) +enables the solutions required for the smart society of the future. +Through a variety of Arm Cortex®-A53 and A57-based devices, engineers can +easily implement high-resolution human machine interfaces (HMI), embedded +vision, embedded artificial intelligence (e-AI) and real-time control and +industrial ethernet connectivity. + +The scalable RZ/G hardware platform and flexible software platform +cover the full product range, from the premium class to the entry +level. Plug-ins are available for multiple open-source software tools. + + +Renesas RZ/G2 reference platforms: +---------------------------------- + ++--------------+----------------------------------------------------------------------------------+ +| Board | Details | ++==============+===============+==================================================================+ +| hihope-rzg2h | "96 boards" compatible board from Hoperun equipped with Renesas RZ/G2H SoC | +| +----------------------------------------------------------------------------------+ +| | http://hihope.org/product/musashi | ++--------------+----------------------------------------------------------------------------------+ +| hihope-rzg2m | "96 boards" compatible board from Hoperun equipped with Renesas RZ/G2M SoC | +| +----------------------------------------------------------------------------------+ +| | http://hihope.org/product/musashi | ++--------------+----------------------------------------------------------------------------------+ +| hihope-rzg2n | "96 boards" compatible board from Hoperun equipped with Renesas RZ/G2N SoC | +| +----------------------------------------------------------------------------------+ +| | http://hihope.org/product/musashi | ++--------------+----------------------------------------------------------------------------------+ +| ek874 | "96 boards" compatible board from Silicon Linux equipped with Renesas RZ/G2E SoC | +| +----------------------------------------------------------------------------------+ +| | https://www.si-linux.co.jp/index.php?CAT%2FCAT874 | ++--------------+----------------------------------------------------------------------------------+ + +`boards info <https://www.renesas.com/us/en/products/rzg-linux-platform/rzg-marcketplace/board-solutions.html#rzg2>`__ + +The current TF-A port has been tested on the HiHope RZ/G2M +SoC_id r8a774a1 revision ES1.3. + + +:: + + ARM CA57 (ARMv8) 1.5 GHz dual core, with NEON/VFPv4, L1$ I/D 48K/32K, L2$ 1MB + ARM CA53 (ARMv8) 1.2 GHz quad core, with NEON/VFPv4, L1$ I/D 32K/32K, L2$ 512K + Memory controller for LPDDR4-3200 4GB in 2 channels(32-bit bus mode) + Two- and three-dimensional graphics engines, + Video processing units, + Display Output, + Video Input, + SD card host interface, + USB3.0 and USB2.0 interfaces, + CAN interfaces, + Ethernet AVB, + Wi-Fi + BT, + PCI Express Interfaces, + Memories + INTERNAL 384KB SYSTEM RAM + DDR 4 GB LPDDR4 + QSPI FLASH 64MB + EMMC 32 GB EMMC (HS400 240 MBYTES/S) + MICROSD-CARD SLOT (SDR104 100 MBYTES/S) + +Overview +-------- +On RZ/G2 SoCs the BOOTROM starts the cpu at EL3; for this port BL2 +will therefore be entered at this exception level (the Renesas' ATF +reference tree [1] resets into EL1 before entering BL2 - see its +bl2.ld.S) + +BL2 initializes DDR before determining the boot reason (cold or warm). + +Once BL2 boots, it determines the boot reason, writes it to shared +memory (BOOT_KIND_BASE) together with the BL31 parameters +(PARAMS_BASE) and jumps to BL31. + +To all effects, BL31 is as if it is being entered in reset mode since +it still needs to initialize the rest of the cores; this is the reason +behind using direct shared memory access to BOOT_KIND_BASE _and_ +PARAMS_BASE instead of using registers to get to those locations (see +el3_common_macros.S and bl31_entrypoint.S for the RESET_TO_BL31 use +case). + +[1] https://github.com/renesas-rz/meta-rzg2/tree/BSP-1.0.5/recipes-bsp/arm-trusted-firmware/files + + +How to build +------------ + +The TF-A build options depend on the target board so you will have to +refer to those specific instructions. What follows is customized to +the HiHope RZ/G2M development kit used in this port. + +Build Tested: +~~~~~~~~~~~~~ + +.. code:: bash + + make bl2 bl31 rzg LOG_LEVEL=40 PLAT=rzg LSI=G2M RCAR_DRAM_SPLIT=2\ + RCAR_LOSSY_ENABLE=1 SPD="none" MBEDTLS_DIR=$mbedtls + +System Tested: +~~~~~~~~~~~~~~ +* mbed_tls: + git@github.com:ARMmbed/mbedtls.git [devel] + +| commit 72ca39737f974db44723760623d1b29980c00a88 +| Merge: ef94c4fcf dd9ec1c57 +| Author: Janos Follath <janos.follath@arm.com> +| Date: Wed Oct 7 09:21:01 2020 +0100 + +* u-boot: + The port has beent tested using mainline uboot with HiHope RZ/G2M board + specific patches. + +| commit 46ce9e777c1314ccb78906992b94001194eaa87b +| Author: Heiko Schocher <hs@denx.de> +| Date: Tue Nov 3 15:22:36 2020 +0100 + +* linux: + The port has beent tested using mainline kernel. + +| commit f8394f232b1eab649ce2df5c5f15b0e528c92091 +| Author: Linus Torvalds <torvalds@linux-foundation.org> +| Date: Sun Nov 8 16:10:16 2020 -0800 +| Linux 5.10-rc3 + +TF-A Build Procedure +~~~~~~~~~~~~~~~~~~~~ + +- Fetch all the above 3 repositories. + +- Prepare the AARCH64 toolchain. + +- Build u-boot using hihope_rzg2_defconfig. + + Result: u-boot-elf.srec + +.. code:: bash + + make CROSS_COMPILE=aarch64-linux-gnu- + hihope_rzg2_defconfig + + make CROSS_COMPILE=aarch64-linux-gnu- + +- Build TF-A + + Result: bootparam_sa0.srec, cert_header_sa6.srec, bl2.srec, bl31.srec + +.. code:: bash + + make bl2 bl31 rzg LOG_LEVEL=40 PLAT=rzg LSI=G2M RCAR_DRAM_SPLIT=2\ + RCAR_LOSSY_ENABLE=1 SPD="none" MBEDTLS_DIR=$mbedtls + + +Install Procedure +~~~~~~~~~~~~~~~~~ + +- Boot the board in Mini-monitor mode and enable access to the + QSPI flash. + + +- Use the flash_writer utility[2] to flash all the SREC files. + +[2] https://github.com/renesas-rz/rzg2_flash_writer + + +Boot trace +---------- +:: + + INFO: ARM GICv2 driver initialized + NOTICE: BL2: RZ/G2 Initial Program Loader(CA57) Rev.2.0.6 + NOTICE: BL2: PRR is RZ/G2M Ver.1.3 + NOTICE: BL2: Board is HiHope RZ/G2M Rev.4.0 + NOTICE: BL2: Boot device is QSPI Flash(40MHz) + NOTICE: BL2: LCM state is unknown + NOTICE: BL2: DDR3200(rev.0.40) + NOTICE: BL2: [COLD_BOOT] + NOTICE: BL2: DRAM Split is 2ch + NOTICE: BL2: QoS is default setting(rev.0.19) + NOTICE: BL2: DRAM refresh interval 1.95 usec + NOTICE: BL2: Periodic Write DQ Training + NOTICE: BL2: CH0: 400000000 - 47fffffff, 2 GiB + NOTICE: BL2: CH2: 600000000 - 67fffffff, 2 GiB + NOTICE: BL2: Lossy Decomp areas + NOTICE: Entry 0: DCMPAREACRAx:0x80000540 DCMPAREACRBx:0x570 + NOTICE: Entry 1: DCMPAREACRAx:0x40000000 DCMPAREACRBx:0x0 + NOTICE: Entry 2: DCMPAREACRAx:0x20000000 DCMPAREACRBx:0x0 + NOTICE: BL2: FDT at 0xe631db30 + NOTICE: BL2: v2.3(release):v2.4-rc0-2-g1433701e5 + NOTICE: BL2: Built : 13:45:26, Nov 7 2020 + NOTICE: BL2: Normal boot + INFO: BL2: Doing platform setup + INFO: BL2: Loading image id 3 + NOTICE: BL2: dst=0xe631d200 src=0x8180000 len=512(0x200) + NOTICE: BL2: dst=0x43f00000 src=0x8180400 len=6144(0x1800) + WARNING: r-car ignoring the BL31 size from certificate,using RCAR_TRUSTED_SRAM_SIZE instead + INFO: Loading image id=3 at address 0x44000000 + NOTICE: rcar_file_len: len: 0x0003e000 + NOTICE: BL2: dst=0x44000000 src=0x81c0000 len=253952(0x3e000) + INFO: Image id=3 loaded: 0x44000000 - 0x4403e000 + INFO: BL2: Loading image id 5 + INFO: Loading image id=5 at address 0x50000000 + NOTICE: rcar_file_len: len: 0x00100000 + NOTICE: BL2: dst=0x50000000 src=0x8300000 len=1048576(0x100000) + INFO: Image id=5 loaded: 0x50000000 - 0x50100000 + NOTICE: BL2: Booting BL31 + INFO: Entry point address = 0x44000000 + INFO: SPSR = 0x3cd + + + U-Boot 2021.01-rc1-00244-gac37e14fbd (Nov 04 2020 - 20:03:34 +0000) + + CPU: Renesas Electronics R8A774A1 rev 1.3 + Model: HopeRun HiHope RZ/G2M with sub board + DRAM: 3.9 GiB + MMC: mmc@ee100000: 0, mmc@ee160000: 1 + Loading Environment from MMC... OK + In: serial@e6e88000 + Out: serial@e6e88000 + Err: serial@e6e88000 + Net: eth0: ethernet@e6800000 + Hit any key to stop autoboot: 0 + => diff --git a/docs/plat/stm32mp1.rst b/docs/plat/stm32mp1.rst index 2c372a6a3..f597460db 100644 --- a/docs/plat/stm32mp1.rst +++ b/docs/plat/stm32mp1.rst @@ -8,6 +8,23 @@ The STM32MP1 chip also embeds a Cortex-M4. More information can be found on `STM32MP1 Series`_ page. +STM32MP1 Versions +----------------- +The STM32MP1 series is available in 3 different lines which are pin-to-pin compatible: + +- STM32MP157: Dual Cortex-A7 cores, Cortex-M4 core @ 209 MHz, 3D GPU, DSI display interface and CAN FD +- STM32MP153: Dual Cortex-A7 cores, Cortex-M4 core @ 209 MHz and CAN FD +- STM32MP151: Single Cortex-A7 core, Cortex-M4 core @ 209 MHz + +Each line comes with a security option (cryptography & secure boot) and a Cortex-A frequency option: + +- A Basic + Cortex-A7 @ 650 MHz +- C Secure Boot + HW Crypto + Cortex-A7 @ 650 MHz +- D Basic + Cortex-A7 @ 800 MHz +- F Secure Boot + HW Crypto + Cortex-A7 @ 800 MHz + +The `STM32MP1 part number codification`_ page gives more information about part numbers. + Design ------ The STM32MP1 resets in the ROM code of the Cortex-A7. @@ -101,7 +118,7 @@ To build TF-A with OP-TEE support for all bootable devices: cd <optee_directory> make CROSS_COMPILE=arm-linux-gnueabihf- ARCH=arm PLATFORM=stm32mp1 CFG_EMBED_DTB_SOURCE_FILE=stm32mp157c-ev1.dts cd <u-boot_directory> - make stm32mp15_optee_defconfig + make stm32mp15_trusted_defconfig make DEVICE_TREE=stm32mp157c-ev1 all @@ -121,5 +138,12 @@ It should contain at least those partitions: Usually, two copies of fsbl are used (fsbl1 and fsbl2) instead of one partition fsbl. +OP-TEE artifacts go into separate partitions as follows: + +- teeh: tee-header_v2.stm32 +- teed: tee-pageable_v2.stm32 +- teex: tee-pager_v2.stm32 + .. _STM32MP1 Series: https://www.st.com/en/microcontrollers-microprocessors/stm32mp1-series.html +.. _STM32MP1 part number codification: https://wiki.st.com/stm32mpu/wiki/STM32MP15_microprocessor#Part_number_codification diff --git a/docs/process/code-review-guidelines.rst b/docs/process/code-review-guidelines.rst new file mode 100644 index 000000000..67a211f75 --- /dev/null +++ b/docs/process/code-review-guidelines.rst @@ -0,0 +1,216 @@ +Code Review Guidelines +====================== + +This document provides TF-A specific details about the project's code review +process. It should be read in conjunction with the `Project Maintenance +Process`_, which it supplements. + + +Why do we do code reviews? +-------------------------- + +The main goal of code reviews is to improve the code quality. By reviewing each +other's code, we can help catch issues that were missed by the author +before they are integrated in the source tree. Different people bring different +perspectives, depending on their past work, experiences and their current use +cases of TF-A in their products. + +Code reviews also play a key role in sharing knowledge within the +community. People with more expertise in one area of the code base can +help those that are less familiar with it. + +Code reviews are meant to benefit everyone through team work. It is not about +unfairly criticizing or belittling the work of any contributor. + + +Good practices +-------------- + +To ensure the code review gives the greatest possible benefit, participants in +the project should: + +- Be considerate of other people and their needs. Participants may be working + to different timescales, and have different priorities. Keep this in + mind - be gracious while waiting for action from others, and timely in your + actions when others are waiting for you. + +- Review other people's patches where possible. The more active reviewers there + are, the more quickly new patches can be reviewed and merged. Contributing to + code review helps everyone in the long run, as it creates a culture of + participation which serves everyone's interests. + + +Guidelines for patch contributors +--------------------------------- + +In addition to the rules outlined in the :ref:`Contributor's Guide`, as a patch +contributor you are expected to: + +- Answer all comments from people who took the time to review your + patches. + +- Be patient and resilient. It is quite common for patches to go through + several rounds of reviews and rework before they get approved, especially + for larger features. + + In the event that a code review takes longer than you would hope for, you + may try the following actions to speed it up: + + - Ping the reviewers on Gerrit or on the mailing list. If it is urgent, + explain why. Please remain courteous and do not abuse this. + + - If one code owner has become unresponsive, ask the other code owners for + help progressing the patch. + + - If there is only one code owner and they have become unresponsive, ask one + of the project maintainers for help. + +- Do the right thing for the project, not the fastest thing to get code merged. + + For example, if some existing piece of code - say a driver - does not quite + meet your exact needs, go the extra mile and extend the code with the missing + functionality you require - as opposed to copying the code into some other + directory to have the freedom to change it in any way. This way, your changes + benefit everyone and will be maintained over time. + + +Guidelines for all reviewers +---------------------------- + +There are no good or bad review comments. If you have any doubt about a patch or +need some clarifications, it's better to ask rather than letting a potential +issue slip. Examples of review comments could be: + +- Questions ("Why do you need to do this?", "What if X happens?") +- Bugs ("I think you need a logical \|\| rather than a bitwise \|.") +- Design issues ("This won't scale well when we introduce feature X.") +- Improvements ("Would it be better if we did Y instead?") + + +Guidelines for code owners +-------------------------- + +Code owners are listed on the :ref:`Project Maintenance<code owners>` page, +along with the module(s) they look after. + +When reviewing a patch, code owners are expected to check the following: + +- The patch looks good from a technical point of view. For example: + + - The structure of the code is clear. + + - It complies with the relevant standards or technical documentation (where + applicable). + + - It leverages existing interfaces rather than introducing new ones + unnecessarily. + + - It fits well in the design of the module. + + - It adheres to the security model of the project. In particular, it does not + increase the attack surface (e.g. new SMCs) without justification. + +- The patch adheres to the TF-A :ref:`Coding Style`. The CI system should help + catch coding style violations. + +- (Only applicable to generic code) The code is MISRA-compliant (see + :ref:`misra-compliance`). The CI system should help catch violations. + +- Documentation is provided/updated (where applicable). + +- The patch has had an appropriate level of testing. Testing details are + expected to be provided by the patch author. If they are not, do not hesitate + to request this information. + +- All CI automated tests pass. + +If a code owner is happy with a patch, they should give their approval +through the ``Code-Owner-Review+1`` label in Gerrit. If instead, they have +concerns, questions, or any other type of blocking comment, they should set +``Code-Owner-Review-1``. + +Code owners are expected to behave professionally and responsibly. Here are some +guidelines for them: + +- Once you are engaged in a review, make sure you stay involved until the patch + is merged. Rejecting a patch and going away is not very helpful. You are + expected to monitor the patch author's answers to your review comments, + answer back if needed and review new revisions of their patch. + +- Provide constructive feedback. Just saying, "This is wrong, you should do X + instead." is usually not very helpful. The patch author is unlikely to + understand why you are requesting this change and might feel personally + attacked. + +- Be mindful when reviewing a patch. As a code owner, you are viewed as + the expert for the relevant module. By approving a patch, you are partially + responsible for its quality and the effects it has for all TF-A users. Make + sure you fully understand what the implications of a patch might be. + + +Guidelines for maintainers +-------------------------- + +Maintainers are listed on the :ref:`Project Maintenance<maintainers>` page. + +When reviewing a patch, maintainers are expected to check the following: + +- The general structure of the patch looks good. This covers things like: + + - Code organization. + + - Files and directories, names and locations. + + For example, platform code should be added under the ``plat/`` directory. + + - Naming conventions. + + For example, platform identifiers should be properly namespaced to avoid + name clashes with generic code. + + - API design. + +- Interaction of the patch with other modules in the code base. + +- The patch aims at complying with any standard or technical documentation + that applies. + +- New files must have the correct license and copyright headers. See :ref:`this + paragraph<copyright-license-guidance>` for more information. The CI system + should help catch files with incorrect or no copyright/license headers. + +- There is no third party code or binary blobs with potential IP concerns. + Maintainers should look for copyright or license notices in code, and use + their best judgement. If they are unsure about a patch, they should ask + other maintainers for help. + +- Generally speaking, new driver code should be placed in the generic + layer. There are cases where a driver has to stay into the platform layer but + this should be the exception, rather than the rule. + +- Existing common drivers (in particular for Arm IPs like the GIC driver) should + not be copied into the platform layer to cater for platform quirks. This + type of code duplication hurts the maintainability of the project. The + duplicate driver is less likely to benefit from bug fixes and future + enhancements. In most cases, it is possible to rework a generic driver to + make it more flexible and fit slightly different use cases. That way, these + enhancements benefit everyone. + +- When a platform specific driver really is required, the burden lies with the + patch author to prove the need for it. A detailed justification should be + posted via the commit message or on the mailing list. + +- Before merging a patch, verify that all review comments have been addressed. + If this is not the case, encourage the patch author and the relevant + reviewers to resolve these together. + +If a maintainer is happy with a patch, they should give their approval +through the ``Maintainer-Review+1`` label in Gerrit. If instead, they have +concerns, questions, or any other type of blocking comment, they should set +``Maintainer-Review-1``. + +-------------- + +*Copyright (c) 2020, Arm Limited. All rights reserved.* + +.. _Project Maintenance Process: https://developer.trustedfirmware.org/w/collaboration/project-maintenance-process/ diff --git a/docs/process/coding-guidelines.rst b/docs/process/coding-guidelines.rst index cb8b89245..ef319e441 100644 --- a/docs/process/coding-guidelines.rst +++ b/docs/process/coding-guidelines.rst @@ -1,232 +1,130 @@ -Coding Style & Guidelines -========================= +Coding Guidelines +================= -The following sections contain TF coding guidelines. They are continually -evolving and should not be considered "set in stone". Feel free to question them -and provide feedback. +This document provides some additional guidelines to consider when writing +|TF-A| code. These are not intended to be strictly-enforced rules like the +contents of the :ref:`Coding Style`. -Some of the guidelines may also apply to other codebases. +Automatic Editor Configuration +------------------------------ -.. note:: - The existing TF codebase does not necessarily comply with all the - below guidelines but the intent is for it to do so eventually. - -Checkpatch overrides --------------------- - -Some checkpatch warnings in the TF codebase are deliberately ignored. These -include: - -- ``**WARNING: line over 80 characters**``: Although the codebase should - generally conform to the 80 character limit this is overly restrictive in some - cases. - -- ``**WARNING: Use of volatile is usually wrong``: see - `Why the “volatile” type class should not be used`_ . Although this document - contains some very useful information, there are several legitimate uses of - the volatile keyword within the TF codebase. - -Headers and inclusion ---------------------- - -Header guards -^^^^^^^^^^^^^ - -For a header file called "some_driver.h" the style used by the Trusted Firmware -is: - -.. code:: c - - #ifndef SOME_DRIVER_H - #define SOME_DRIVER_H - - <header content> +Many of the rules given below (such as indentation size, use of tabs, and +newlines) can be set automatically using the `EditorConfig`_ configuration file +in the root of the repository: ``.editorconfig``. With a supported editor, the +rules set out in this file can be automatically applied when you are editing +files in the |TF-A| repository. - #endif /* SOME_DRIVER_H */ +Several editors include built-in support for EditorConfig files, and many others +support its functionality through plugins. -Include statement ordering -^^^^^^^^^^^^^^^^^^^^^^^^^^ +Use of the EditorConfig file is suggested but is not required. -All header files that are included by a source file must use the following, -grouped ordering. This is to improve readability (by making it easier to quickly -read through the list of headers) and maintainability. +.. _automatic-compliance-checking: -#. *System* includes: Header files from the standard *C* library, such as - ``stddef.h`` and ``string.h``. - -#. *Project* includes: Header files under the ``include/`` directory within TF - are *project* includes. - -#. *Platform* includes: Header files relating to a single, specific platform, - and which are located under the ``plat/<platform_name>`` directory within TF, - are *platform* includes. +Automatic Compliance Checking +----------------------------- -Within each group, ``#include`` statements must be in alphabetical order, -taking both the file and directory names into account. +To assist with coding style compliance, the project Makefile contains two +targets which both utilise the `checkpatch.pl` script that ships with the Linux +source tree. The project also defines certain *checkpatch* options in the +``.checkpatch.conf`` file in the top-level directory. -Groups must be separated by a single blank line for clarity. +.. note:: + Checkpatch errors will gate upstream merging of pull requests. + Checkpatch warnings will not gate merging but should be reviewed and fixed if + possible. -The example below illustrates the ordering rules using some contrived header -file names; this type of name reuse should be otherwise avoided. +To check the entire source tree, you must first download copies of +``checkpatch.pl``, ``spelling.txt`` and ``const_structs.checkpatch`` available +in the `Linux master tree`_ *scripts* directory, then set the ``CHECKPATCH`` +environment variable to point to ``checkpatch.pl`` (with the other 2 files in +the same directory) and build the `checkcodebase` target: -.. code:: c +.. code:: shell - #include <string.h> + make CHECKPATCH=<path-to-linux>/linux/scripts/checkpatch.pl checkcodebase - #include <a_dir/example/a_header.h> - #include <a_dir/example/b_header.h> - #include <a_dir/test/a_header.h> - #include <b_dir/example/a_header.h> +To just check the style on the files that differ between your local branch and +the remote master, use: - #include "./a_header.h" +.. code:: shell -Include statement variants -^^^^^^^^^^^^^^^^^^^^^^^^^^ + make CHECKPATCH=<path-to-linux>/linux/scripts/checkpatch.pl checkpatch -Two variants of the ``#include`` directive are acceptable in the TF codebase. -Correct use of the two styles improves readability by suggesting the location -of the included header and reducing ambiguity in cases where generic and -platform-specific headers share a name. +If you wish to check your patch against something other than the remote master, +set the ``BASE_COMMIT`` variable to your desired branch. By default, +``BASE_COMMIT`` is set to ``origin/master``. -For header files that are in the same directory as the source file that is -including them, use the ``"..."`` variant. - -For header files that are **not** in the same directory as the source file that -is including them, use the ``<...>`` variant. +Ignored Checkpatch Warnings +^^^^^^^^^^^^^^^^^^^^^^^^^^^ -Example (bl1_fwu.c): +Some checkpatch warnings in the TF codebase are deliberately ignored. These +include: -.. code:: c +- ``**WARNING: line over 80 characters**``: Although the codebase should + generally conform to the 80 character limit this is overly restrictive in some + cases. - #include <assert.h> - #include <errno.h> - #include <string.h> +- ``**WARNING: Use of volatile is usually wrong``: see + `Why the “volatile” type class should not be used`_ . Although this document + contains some very useful information, there are several legimate uses of the + volatile keyword within the TF codebase. - #include "bl1_private.h" +Performance considerations +-------------------------- -Platform include paths -^^^^^^^^^^^^^^^^^^^^^^ +Avoid printf and use logging macros +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -Platforms are allowed to add more include paths to be passed to the compiler. -The ``PLAT_INCLUDES`` variable is used for this purpose. This is needed in -particular for the file ``platform_def.h``. +``debug.h`` provides logging macros (for example, ``WARN`` and ``ERROR``) +which wrap ``tf_log`` and which allow the logging call to be compiled-out +depending on the ``make`` command. Use these macros to avoid print statements +being compiled unconditionally into the binary. -Example: +Each logging macro has a numerical log level: .. code:: c - PLAT_INCLUDES += -Iinclude/plat/myplat/include - -Types and typedefs ------------------- - -Use of built-in *C* and *libc* data types -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -The TF codebase should be kept as portable as possible, especially since both -64-bit and 32-bit platforms are supported. To help with this, the following data -type usage guidelines should be followed: - -- Where possible, use the built-in *C* data types for variable storage (for - example, ``char``, ``int``, ``long long``, etc) instead of the standard *C99* - types. Most code is typically only concerned with the minimum size of the - data stored, which the built-in *C* types guarantee. - -- Avoid using the exact-size standard *C99* types in general (for example, - ``uint16_t``, ``uint32_t``, ``uint64_t``, etc) since they can prevent the - compiler from making optimizations. There are legitimate uses for them, - for example to represent data of a known structure. When using them in struct - definitions, consider how padding in the struct will work across architectures. - For example, extra padding may be introduced in AArch32 systems if a struct - member crosses a 32-bit boundary. - -- Use ``int`` as the default integer type - it's likely to be the fastest on all - systems. Also this can be assumed to be 32-bit as a consequence of the - `Procedure Call Standard for the Arm Architecture`_ and the `Procedure Call - Standard for the Arm 64-bit Architecture`_ . - -- Avoid use of ``short`` as this may end up being slower than ``int`` in some - systems. If a variable must be exactly 16-bit, use ``int16_t`` or - ``uint16_t``. - -- Avoid use of ``long``. This is guaranteed to be at least 32-bit but, given - that `int` is 32-bit on Arm platforms, there is no use for it. For integers of - at least 64-bit, use ``long long``. - -- Use ``char`` for storing text. Use ``uint8_t`` for storing other 8-bit data. - -- Use ``unsigned`` for integers that can never be negative (counts, - indices, sizes, etc). TF intends to comply with MISRA "essential type" coding - rules (10.X), where signed and unsigned types are considered different - essential types. Choosing the correct type will aid this. MISRA static - analysers will pick up any implicit signed/unsigned conversions that may lead - to unexpected behaviour. - -- For pointer types: - - - If an argument in a function declaration is pointing to a known type then - simply use a pointer to that type (for example: ``struct my_struct *``). - - - If a variable (including an argument in a function declaration) is pointing - to a general, memory-mapped address, an array of pointers or another - structure that is likely to require pointer arithmetic then use - ``uintptr_t``. This will reduce the amount of casting required in the code. - Avoid using ``unsigned long`` or ``unsigned long long`` for this purpose; it - may work but is less portable. - - - For other pointer arguments in a function declaration, use ``void *``. This - includes pointers to types that are abstracted away from the known API and - pointers to arbitrary data. This allows the calling function to pass a - pointer argument to the function without any explicit casting (the cast to - ``void *`` is implicit). The function implementation can then do the - appropriate casting to a specific type. - - - Use ``ptrdiff_t`` to compare the difference between 2 pointers. - -- Use ``size_t`` when storing the ``sizeof()`` something. - -- Use ``ssize_t`` when returning the ``sizeof()`` something from a function that - can also return an error code; the signed type allows for a negative return - code in case of error. This practice should be used sparingly. - -- Use ``u_register_t`` when it's important to store the contents of a register - in its native size (32-bit in AArch32 and 64-bit in AArch64). This is not a - standard *C99* type but is widely available in libc implementations, - including the FreeBSD version included with the TF codebase. Where possible, - cast the variable to a more appropriate type before interpreting the data. For - example, the following struct in ``ep_info.h`` could use this type to minimize - the storage required for the set of registers: + #define LOG_LEVEL_NONE 0 + #define LOG_LEVEL_ERROR 10 + #define LOG_LEVEL_NOTICE 20 + #define LOG_LEVEL_WARNING 30 + #define LOG_LEVEL_INFO 40 + #define LOG_LEVEL_VERBOSE 50 -.. code:: c +By default, all logging statements with a log level ``<= LOG_LEVEL_INFO`` will +be compiled into debug builds and all statements with a log level +``<= LOG_LEVEL_NOTICE`` will be compiled into release builds. This can be +overridden from the command line or by the platform makefile (although it may be +necessary to clean the build directory first). - typedef struct aapcs64_params { - u_register_t arg0; - u_register_t arg1; - u_register_t arg2; - u_register_t arg3; - u_register_t arg4; - u_register_t arg5; - u_register_t arg6; - u_register_t arg7; - } aapcs64_params_t; +For example, to enable ``VERBOSE`` logging on FVP: -If some code wants to operate on ``arg0`` and knows that it represents a 32-bit -unsigned integer on all systems, cast it to ``unsigned int``. +.. code:: shell -These guidelines should be updated if additional types are needed. + make PLAT=fvp LOG_LEVEL=50 all -Avoid anonymous typedefs of structs/enums in headers -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +Use const data where possible +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -For example, the following definition: +For example, the following code: .. code:: c - typedef struct { + struct my_struct { int arg1; int arg2; - } my_struct_t; + }; + void init(struct my_struct *ptr); + + void main(void) + { + struct my_struct x; + x.arg1 = 1; + x.arg2 = 2; + init(&x); + } is better written as: @@ -237,31 +135,18 @@ is better written as: int arg2; }; -This allows function declarations in other header files that depend on the -struct/enum to forward declare the struct/enum instead of including the -entire header: - -.. code:: c - - #include <my_struct.h> - void my_func(my_struct_t *arg); - -instead of: - -.. code:: c - - struct my_struct; - void my_func(struct my_struct *arg); - -Some TF definitions use both a struct/enum name **and** a typedef name. This -is discouraged for new definitions as it makes it difficult for TF to comply -with MISRA rule 8.3, which states that "All declarations of an object or -function shall use the same names and type qualifiers". + void init(const struct my_struct *ptr); -The Linux coding standards also discourage new typedefs and checkpatch emits -a warning for this. + void main(void) + { + const struct my_struct x = { 1, 2 }; + init(&x); + } -Existing typedefs will be retained for compatibility. +This allows the linker to put the data in a read-only data section instead of a +writeable data section, which may result in a smaller and faster binary. Note +that this may require dependent functions (``init()`` in the above example) to +have ``const`` arguments, assuming they don't need to modify the data. Libc functions that are banned or to be used with caution --------------------------------------------------------- @@ -410,14 +295,14 @@ error. This situation should be handled in one of the following ways: then emit an ``ERROR`` message and call the platform-specific function ``plat_error_handler()``. -Cases 1 and 2 are subtly different. A platform may implement ``plat_panic_handler`` -and ``plat_error_handler`` in the same way (for example, by waiting for a secure -watchdog to time-out or by invoking an interface on the platform's power -controller to reset the platform). However, ``plat_error_handler`` may take -additional action for some errors (for example, it may set a flag so the -platform resets into a different mode). Also, ``plat_panic_handler()`` may -implement additional debug functionality (for example, invoking a hardware -breakpoint). +Cases 1 and 2 are subtly different. A platform may implement +``plat_panic_handler`` and ``plat_error_handler`` in the same way (for example, +by waiting for a secure watchdog to time-out or by invoking an interface on the +platform's power controller to reset the platform). However, +``plat_error_handler`` may take additional action for some errors (for example, +it may set a flag so the platform resets into a different mode). Also, +``plat_panic_handler()`` may implement additional debug functionality (for +example, invoking a hardware breakpoint). Examples of unexpected unrecoverable errors: @@ -456,131 +341,134 @@ Examples: - Secure world is waiting for a hardware response that is critical for continued operation. -Security considerations ------------------------ - -Part of the security of a platform is handling errors correctly, as described in -the previous section. There are several other security considerations covered in -this section. - -Do not leak secrets to the normal world -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -The secure world **must not** leak secrets to the normal world, for example in -response to an SMC. - -Handling Denial of Service attacks -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +Use of built-in *C* and *libc* data types +----------------------------------------- -The secure world **should never** crash or become unusable due to receiving too -many normal world requests (a *Denial of Service* or *DoS* attack). It should -have a mechanism for throttling or ignoring normal world requests. +The |TF-A| codebase should be kept as portable as possible, especially since +both 64-bit and 32-bit platforms are supported. To help with this, the following +data type usage guidelines should be followed: -Performance considerations --------------------------- +- Where possible, use the built-in *C* data types for variable storage (for + example, ``char``, ``int``, ``long long``, etc) instead of the standard *C99* + types. Most code is typically only concerned with the minimum size of the + data stored, which the built-in *C* types guarantee. -Avoid printf and use logging macros -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +- Avoid using the exact-size standard *C99* types in general (for example, + ``uint16_t``, ``uint32_t``, ``uint64_t``, etc) since they can prevent the + compiler from making optimizations. There are legitimate uses for them, + for example to represent data of a known structure. When using them in struct + definitions, consider how padding in the struct will work across architectures. + For example, extra padding may be introduced in |AArch32| systems if a struct + member crosses a 32-bit boundary. -``debug.h`` provides logging macros (for example, ``WARN`` and ``ERROR``) -which wrap ``tf_log`` and which allow the logging call to be compiled-out -depending on the ``make`` command. Use these macros to avoid print statements -being compiled unconditionally into the binary. +- Use ``int`` as the default integer type - it's likely to be the fastest on all + systems. Also this can be assumed to be 32-bit as a consequence of the + `Procedure Call Standard for the Arm Architecture`_ and the `Procedure Call + Standard for the Arm 64-bit Architecture`_ . -Each logging macro has a numerical log level: +- Avoid use of ``short`` as this may end up being slower than ``int`` in some + systems. If a variable must be exactly 16-bit, use ``int16_t`` or + ``uint16_t``. -.. code:: c +- Avoid use of ``long``. This is guaranteed to be at least 32-bit but, given + that `int` is 32-bit on Arm platforms, there is no use for it. For integers of + at least 64-bit, use ``long long``. - #define LOG_LEVEL_NONE 0 - #define LOG_LEVEL_ERROR 10 - #define LOG_LEVEL_NOTICE 20 - #define LOG_LEVEL_WARNING 30 - #define LOG_LEVEL_INFO 40 - #define LOG_LEVEL_VERBOSE 50 +- Use ``char`` for storing text. Use ``uint8_t`` for storing other 8-bit data. +- Use ``unsigned`` for integers that can never be negative (counts, + indices, sizes, etc). TF intends to comply with MISRA "essential type" coding + rules (10.X), where signed and unsigned types are considered different + essential types. Choosing the correct type will aid this. MISRA static + analysers will pick up any implicit signed/unsigned conversions that may lead + to unexpected behaviour. -By default, all logging statements with a log level ``<= LOG_LEVEL_INFO`` will -be compiled into debug builds and all statements with a log level -``<= LOG_LEVEL_NOTICE`` will be compiled into release builds. This can be -overridden from the command line or by the platform makefile (although it may be -necessary to clean the build directory first). For example, to enable -``VERBOSE`` logging on FVP: +- For pointer types: -``make PLAT=fvp LOG_LEVEL=50 all`` + - If an argument in a function declaration is pointing to a known type then + simply use a pointer to that type (for example: ``struct my_struct *``). -Use const data where possible -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + - If a variable (including an argument in a function declaration) is pointing + to a general, memory-mapped address, an array of pointers or another + structure that is likely to require pointer arithmetic then use + ``uintptr_t``. This will reduce the amount of casting required in the code. + Avoid using ``unsigned long`` or ``unsigned long long`` for this purpose; it + may work but is less portable. -For example, the following code: + - For other pointer arguments in a function declaration, use ``void *``. This + includes pointers to types that are abstracted away from the known API and + pointers to arbitrary data. This allows the calling function to pass a + pointer argument to the function without any explicit casting (the cast to + ``void *`` is implicit). The function implementation can then do the + appropriate casting to a specific type. -.. code:: c + - Avoid pointer arithmetic generally (as this violates MISRA C 2012 rule + 18.4) and especially on void pointers (as this is only supported via + language extensions and is considered non-standard). In TF-A, setting the + ``W`` build flag to ``W=3`` enables the *-Wpointer-arith* compiler flag and + this will emit warnings where pointer arithmetic is used. - struct my_struct { - int arg1; - int arg2; - }; + - Use ``ptrdiff_t`` to compare the difference between 2 pointers. - void init(struct my_struct *ptr); +- Use ``size_t`` when storing the ``sizeof()`` something. - void main(void) - { - struct my_struct x; - x.arg1 = 1; - x.arg2 = 2; - init(&x); - } +- Use ``ssize_t`` when returning the ``sizeof()`` something from a function that + can also return an error code; the signed type allows for a negative return + code in case of error. This practice should be used sparingly. -is better written as: +- Use ``u_register_t`` when it's important to store the contents of a register + in its native size (32-bit in |AArch32| and 64-bit in |AArch64|). This is not a + standard *C99* type but is widely available in libc implementations, + including the FreeBSD version included with the TF codebase. Where possible, + cast the variable to a more appropriate type before interpreting the data. For + example, the following struct in ``ep_info.h`` could use this type to minimize + the storage required for the set of registers: .. code:: c - struct my_struct { - int arg1; - int arg2; - }; + typedef struct aapcs64_params { + u_register_t arg0; + u_register_t arg1; + u_register_t arg2; + u_register_t arg3; + u_register_t arg4; + u_register_t arg5; + u_register_t arg6; + u_register_t arg7; + } aapcs64_params_t; - void init(const struct my_struct *ptr); +If some code wants to operate on ``arg0`` and knows that it represents a 32-bit +unsigned integer on all systems, cast it to ``unsigned int``. - void main(void) - { - const struct my_struct x = { 1, 2 }; - init(&x); - } +These guidelines should be updated if additional types are needed. -This allows the linker to put the data in a read-only data section instead of a -writeable data section, which may result in a smaller and faster binary. Note -that this may require dependent functions (``init()`` in the above example) to -have ``const`` arguments, assuming they don't need to modify the data. +Favor C language over assembly language +--------------------------------------- + +Generally, prefer code written in C over assembly. Assembly code is less +portable, harder to understand, maintain and audit security wise. Also, static +analysis tools generally don't analyze assembly code. -Library and driver code ------------------------ +There are, however, legitimate uses of assembly language. These include: -TF library code (under ``lib/`` and ``include/lib``) is any code that provides a -reusable interface to other code, potentially even to code outside of TF. + - Early boot code executed before the C runtime environment is setup. -In some systems drivers must conform to a specific driver framework to provide -services to the rest of the system. TF has no driver framework and the -distinction between a driver and library is somewhat subjective. + - Exception handling code. -A driver (under ``drivers/`` and ``include/drivers/``) is defined as code that -interfaces with hardware via a memory mapped interface. + - Low-level code where the exact sequence of instructions executed on the CPU + matters, such as CPU reset sequences. -Some drivers (for example, the Arm CCI driver in ``include/drivers/arm/cci.h``) -provide a general purpose API to that specific hardware. Other drivers (for -example, the Arm PL011 console driver in ``drivers/arm/pl011/pl011_console.S``) -provide a specific hardware implementation of a more abstract library API. In -the latter case there may potentially be multiple drivers for the same hardware -device. + - Low-level code where specific system-level instructions must be used, such + as cache maintenance operations. -Neither libraries nor drivers should depend on platform-specific code. If they -require platform-specific data (for example, a base address) to operate then -they should provide an initialization function that takes the platform-specific -data as arguments. +-------------- -TF common code (under ``common/`` and ``include/common/``) is code that is re-used -by other generic (non-platform-specific) TF code. It is effectively internal -library code. +*Copyright (c) 2020, Arm Limited and Contributors. All rights reserved.* +.. _`Linux master tree`: https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/ +.. _`Procedure Call Standard for the Arm Architecture`: https://developer.arm.com/docs/ihi0042/latest/ +.. _`Procedure Call Standard for the Arm 64-bit Architecture`: https://developer.arm.com/docs/ihi0055/latest/ +.. _`EditorConfig`: http://editorconfig.org/ .. _`Why the “volatile” type class should not be used`: https://www.kernel.org/doc/html/latest/process/volatile-considered-harmful.html -.. _`Procedure Call Standard for the Arm Architecture`: http://infocenter.arm.com/help/topic/com.arm.doc.ihi0042f/IHI0042F_aapcs.pdf -.. _`Procedure Call Standard for the Arm 64-bit Architecture`: http://infocenter.arm.com/help/topic/com.arm.doc.ihi0055b/IHI0055B_aapcs64.pdf +.. _`MISRA C:2012 Guidelines`: https://www.misra.org.uk/Activities/MISRAC/tabid/160/Default.aspx +.. _`a spreadsheet`: https://developer.trustedfirmware.org/file/download/lamajxif3w7c4mpjeoo5/PHID-FILE-fp7c7acszn6vliqomyhn/MISRA-and-TF-Analysis-v1.3.ods diff --git a/docs/process/coding-style.rst b/docs/process/coding-style.rst new file mode 100644 index 000000000..be13b14fa --- /dev/null +++ b/docs/process/coding-style.rst @@ -0,0 +1,470 @@ +Coding Style +============ + +The following sections outline the |TF-A| coding style for *C* code. The style +is based on the `Linux kernel coding style`_, with a few modifications. + +The style should not be considered *set in stone*. Feel free to provide feedback +and suggestions. + +.. note:: + You will almost certainly find code in the |TF-A| repository that does not + follow the style. The intent is for all code to do so eventually. + +File Encoding +------------- + +The source code must use the **UTF-8** character encoding. Comments and +documentation may use non-ASCII characters when required (e.g. Greek letters +used for units) but code itself is still limited to ASCII characters. + +Newlines must be in **Unix** style, which means that only the Line Feed (``LF``) +character is used to break a line and reset to the first column. + +Language +-------- + +The primary language for comments and naming must be International English. In +cases where there is a conflict between the American English and British English +spellings of a word, the American English spelling is used. + +Exceptions are made when referring directly to something that does not use +international style, such as the name of a company. In these cases the existing +name should be used as-is. + +C Language Standard +------------------- + +The C language mode used for TF-A is *GNU99*. This is the "GNU dialect of ISO +C99", which implies the *ISO C99* standard with GNU extensions. + +Both GCC and Clang compiler toolchains have support for *GNU99* mode, though +Clang does lack support for a small number of GNU extensions. These +missing extensions are rarely used, however, and should not pose a problem. + +.. _misra-compliance: + +MISRA Compliance +---------------- + +TF-A attempts to comply with the `MISRA C:2012 Guidelines`_. Coverity +Static Analysis is used to regularly generate a report of current MISRA defects +and to prevent the addition of new ones. + +It is not possible for the project to follow all MISRA guidelines. We maintain +`a spreadsheet`_ that lists all rules and directives and whether we aim to +comply with them or not. A rationale is given for each deviation. + +.. note:: + Enforcing a rule does not mean that the codebase is free of defects + of that rule, only that they would ideally be removed. + +.. note:: + Third-party libraries are not considered in our MISRA analysis and we do not + intend to modify them to make them MISRA compliant. + +Indentation +----------- + +Use **tabs** for indentation. The use of spaces for indentation is forbidden +except in the case where a term is being indented to a boundary that cannot be +achieved using tabs alone. + +Tab spacing should be set to **8 characters**. + +Trailing whitespace is not allowed and must be trimmed. + +Spacing +------- + +Single spacing should be used around most operators, including: + +- Arithmetic operators (``+``, ``-``, ``/``, ``*``) +- Assignment operators (``=``, ``+=``, etc) +- Boolean operators (``&&``, ``||``) +- Comparison operators (``<``, ``>``, ``==``, etc) + +A space should also be used to separate parentheses and braces when they are not +already separated by a newline, such as for the ``if`` statement in the +following example: + +.. code:: c + + int function_foo(bool bar) + { + if (bar) { + function_baz(); + } + } + +Note that there is no space between the name of a function and the following +parentheses. + +Control statements (``if``, ``for``, ``switch``, ``while``, etc) must be +separated from the following open parenthesis by a single space. The previous +example illustrates this for an ``if`` statement. + +Line Length +----------- + +Line length *should* be at most **80 characters**. This limit does not include +non-printing characters such as the line feed. + +This rule is a *should*, not a must, and it is acceptable to exceed the limit +**slightly** where the readability of the code would otherwise be significantly +reduced. Use your judgement in these cases. + +Blank Lines +----------- + +Functions are usually separated by a single blank line. In certain cases it is +acceptable to use additional blank lines for clarity, if required. + +The file must end with a single newline character. Many editors have the option +to insert this automatically and to trim multiple blank lines at the end of the +file. + +Braces +------ + +Opening Brace Placement +^^^^^^^^^^^^^^^^^^^^^^^ + +Braces follow the **Kernighan and Ritchie (K&R)** style, where the opening brace +is **not** placed on a new line. + +Example for a ``while`` loop: + +.. code:: c + + while (condition) { + foo(); + bar(); + } + +This style applies to all blocks except for functions which, following the Linux +style, **do** place the opening brace on a new line. + +Example for a function: + +.. code:: c + + int my_function(void) + { + int a; + + a = 1; + return a; + } + +Conditional Statement Bodies +^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Where conditional statements (such as ``if``, ``for``, ``while`` and ``do``) are +used, braces must be placed around the statements that form the body of the +conditional. This is the case regardless of the number of statements in the +body. + +.. note:: + This is a notable departure from the Linux coding style that has been + adopted to follow MISRA guidelines more closely and to help prevent errors. + +For example, use the following style: + +.. code:: c + + if (condition) { + foo++; + } + +instead of omitting the optional braces around a single statement: + +.. code:: c + + /* This is violating MISRA C 2012: Rule 15.6 */ + if (condition) + foo++; + +The reason for this is to prevent accidental changes to control flow when +modifying the body of the conditional. For example, at a quick glance it is easy +to think that the value of ``bar`` is only incremented if ``condition`` +evaluates to ``true`` but this is not the case - ``bar`` will always be +incremented regardless of the condition evaluation. If the developer forgets to +add braces around the conditional body when adding the ``bar++;`` statement then +the program execution will not proceed as intended. + +.. code:: c + + /* This is violating MISRA C 2012: Rule 15.6 */ + if (condition) + foo++; + bar++; + +Naming +------ + +Functions +^^^^^^^^^ + +Use lowercase for function names, separating multiple words with an underscore +character (``_``). This is sometimes referred to as *Snake Case*. An example is +given below: + +.. code:: c + + void bl2_arch_setup(void) + { + ... + } + +Local Variables and Parameters +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Local variables and function parameters use the same format as function names: +lowercase with underscore separation between multiple words. An example is +given below: + +.. code:: c + + static void set_scr_el3_from_rm(uint32_t type, + uint32_t interrupt_type_flags, + uint32_t security_state) + { + uint32_t flag, bit_pos; + + ... + + } + +Preprocessor Macros +^^^^^^^^^^^^^^^^^^^ + +Identifiers that are defined using preprocessor macros are written in all +uppercase text. + +.. code:: c + + #define BUFFER_SIZE_BYTES 64 + +Function Attributes +------------------- + +Place any function attributes after the function type and before the function +name. + +.. code:: c + + void __init plat_arm_interconnect_init(void); + +Alignment +--------- + +Alignment should be performed primarily with tabs, adding spaces if required to +achieve a granularity that is smaller than the tab size. For example, with a tab +size of eight columns it would be necessary to use one tab character and two +spaces to indent text by ten columns. + +Switch Statement Alignment +^^^^^^^^^^^^^^^^^^^^^^^^^^ + +When using ``switch`` statements, align each ``case`` statement with the +``switch`` so that they are in the same column. + +.. code:: c + + switch (condition) { + case A: + foo(); + case B: + bar(); + default: + baz(); + } + +Pointer Alignment +^^^^^^^^^^^^^^^^^ + +The reference and dereference operators (ampersand and *pointer star*) must be +aligned with the name of the object on which they are operating, as opposed to +the type of the object. + +.. code:: c + + uint8_t *foo; + + foo = &bar; + + +Comments +-------- + +The general rule for comments is that the double-slash style of comment (``//``) +is not allowed. Examples of the allowed comment formats are shown below: + +.. code:: c + + /* + * This example illustrates the first allowed style for multi-line comments. + * + * Blank lines within multi-lines are allowed when they add clarity or when + * they separate multiple contexts. + * + */ + +.. code:: c + + /************************************************************************** + * This is the second allowed style for multi-line comments. + * + * In this style, the first and last lines use asterisks that run the full + * width of the comment at its widest point. + * + * This style can be used for additional emphasis. + * + *************************************************************************/ + +.. code:: c + + /* Single line comments can use this format */ + +.. code:: c + + /*************************************************************************** + * This alternative single-line comment style can also be used for emphasis. + **************************************************************************/ + +Headers and inclusion +--------------------- + +Header guards +^^^^^^^^^^^^^ + +For a header file called "some_driver.h" the style used by |TF-A| is: + +.. code:: c + + #ifndef SOME_DRIVER_H + #define SOME_DRIVER_H + + <header content> + + #endif /* SOME_DRIVER_H */ + +Include statement ordering +^^^^^^^^^^^^^^^^^^^^^^^^^^ + +All header files that are included by a source file must use the following, +grouped ordering. This is to improve readability (by making it easier to quickly +read through the list of headers) and maintainability. + +#. *System* includes: Header files from the standard *C* library, such as + ``stddef.h`` and ``string.h``. + +#. *Project* includes: Header files under the ``include/`` directory within + |TF-A| are *project* includes. + +#. *Platform* includes: Header files relating to a single, specific platform, + and which are located under the ``plat/<platform_name>`` directory within + |TF-A|, are *platform* includes. + +Within each group, ``#include`` statements must be in alphabetical order, +taking both the file and directory names into account. + +Groups must be separated by a single blank line for clarity. + +The example below illustrates the ordering rules using some contrived header +file names; this type of name reuse should be otherwise avoided. + +.. code:: c + + #include <string.h> + + #include <a_dir/example/a_header.h> + #include <a_dir/example/b_header.h> + #include <a_dir/test/a_header.h> + #include <b_dir/example/a_header.h> + + #include "a_header.h" + +Include statement variants +^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Two variants of the ``#include`` directive are acceptable in the |TF-A| +codebase. Correct use of the two styles improves readability by suggesting the +location of the included header and reducing ambiguity in cases where generic +and platform-specific headers share a name. + +For header files that are in the same directory as the source file that is +including them, use the ``"..."`` variant. + +For header files that are **not** in the same directory as the source file that +is including them, use the ``<...>`` variant. + +Example (bl1_fwu.c): + +.. code:: c + + #include <assert.h> + #include <errno.h> + #include <string.h> + + #include "bl1_private.h" + +Typedefs +-------- + +Avoid anonymous typedefs of structs/enums in headers +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +For example, the following definition: + +.. code:: c + + typedef struct { + int arg1; + int arg2; + } my_struct_t; + + +is better written as: + +.. code:: c + + struct my_struct { + int arg1; + int arg2; + }; + +This allows function declarations in other header files that depend on the +struct/enum to forward declare the struct/enum instead of including the +entire header: + +.. code:: c + + struct my_struct; + void my_func(struct my_struct *arg); + +instead of: + +.. code:: c + + #include <my_struct.h> + void my_func(my_struct_t *arg); + +Some TF definitions use both a struct/enum name **and** a typedef name. This +is discouraged for new definitions as it makes it difficult for TF to comply +with MISRA rule 8.3, which states that "All declarations of an object or +function shall use the same names and type qualifiers". + +The Linux coding standards also discourage new typedefs and checkpatch emits +a warning for this. + +Existing typedefs will be retained for compatibility. + +-------------- + +*Copyright (c) 2020, Arm Limited. All rights reserved.* + +.. _`Linux kernel coding style`: https://www.kernel.org/doc/html/latest/process/coding-style.html +.. _`MISRA C:2012 Guidelines`: https://www.misra.org.uk/Activities/MISRAC/tabid/160/Default.aspx +.. _`a spreadsheet`: https://developer.trustedfirmware.org/file/download/lamajxif3w7c4mpjeoo5/PHID-FILE-fp7c7acszn6vliqomyhn/MISRA-and-TF-Analysis-v1.3.ods diff --git a/docs/process/contributing.rst b/docs/process/contributing.rst index f569fcbe7..15c2b4529 100644 --- a/docs/process/contributing.rst +++ b/docs/process/contributing.rst @@ -4,17 +4,22 @@ Contributor's Guide Getting Started --------------- -- Make sure you have a Github account and you are logged on - `developer.trustedfirmware.org`_. -- Create an `issue`_ for your work if one does not already exist. This gives - everyone visibility of whether others are working on something similar. +- Make sure you have a Github account and you are logged on both + `developer.trustedfirmware.org`_ and `review.trustedfirmware.org`_. - - If you intend to include Third Party IP in your contribution, please - raise a separate `issue`_ for this and ensure that the changes that - include Third Party IP are made on a separate topic branch. +- If you plan to contribute a major piece of work, it is usually a good idea to + start a discussion around it on the mailing list. This gives everyone + visibility of what is coming up, you might learn that somebody else is + already working on something similar or the community might be able to + provide some early input to help shaping the design of the feature. + + If you intend to include Third Party IP in your contribution, please mention + it explicitly in the email thread and ensure that the changes that include + Third Party IP are made in a separate patch (or patch series). - Clone `Trusted Firmware-A`_ on your own machine as described in :ref:`prerequisites_get_source`. + - Create a local topic branch based on the `Trusted Firmware-A`_ ``master`` branch. @@ -23,61 +28,25 @@ Making Changes - Make commits of logical units. See these general `Git guidelines`_ for contributing to a project. -- Follow the :ref:`Coding Style & Guidelines`. - - - Use the checkpatch.pl script provided with the Linux source tree. A - Makefile target is provided for convenience. - Keep the commits on topic. If you need to fix another bug or make another - enhancement, please create a separate `issue`_ and address it on a separate - topic branch. -- Avoid long commit series. If you do have a long series, consider whether - some commits should be squashed together or addressed in a separate topic. -- Make sure your commit messages are in the proper format. If a commit fixes - an `issue`_, include a reference. -- Where appropriate, please update the documentation. + enhancement, please address it on a separate topic branch. - - Consider whether the :ref:`Porting Guide`, - :ref:`Firmware Design` document or other in-source documentation needs - updating. - - Ensure that each changed file has the correct copyright and license - information. Files that entirely consist of contributions to this - project should have a copyright notice and BSD-3-Clause SPDX license - identifier of the form as shown in :ref:`license`. Files that contain - changes to imported Third Party IP files should retain their original - copyright and license notices. For significant contributions you may - add your own copyright notice in following format: - - :: - - Portions copyright (c) [XXXX-]YYYY, <OWNER>. All rights reserved. - - where XXXX is the year of first contribution (if different to YYYY) and - YYYY is the year of most recent contribution. <OWNER> is your name or - your company name. - - If you are submitting new files that you intend to be the technical - sub-maintainer for (for example, a new platform port), then also update - the :ref:`maintainers` file. - - For topics with multiple commits, you should make all documentation - changes (and nothing else) in the last commit of the series. Otherwise, - include the documentation changes within the single commit. +- Split the patch in manageable units. Small patches are usually easier to + review so this will speed up the review process. -- Please test your changes. As a minimum, ensure that Linux boots on the - Foundation FVP. See :ref:`Arm Fixed Virtual Platforms (FVP)` for more - information. For more extensive testing, consider running the `TF-A Tests`_ - against your patches. - -Submitting Changes ------------------- +- Avoid long commit series. If you do have a long series, consider whether + some commits should be squashed together or addressed in a separate topic. - Ensure that each commit in the series has at least one ``Signed-off-by:`` line, using your real name and email address. The names in the - ``Signed-off-by:`` and ``Author:`` lines must match. If anyone else - contributes to the commit, they must also add their own ``Signed-off-by:`` - line. By adding this line the contributor certifies the contribution is made - under the terms of the + ``Signed-off-by:`` and ``Commit:`` lines must match. By adding this line the + contributor certifies the contribution is made under the terms of the :download:`Developer Certificate of Origin <../../dco.txt>`. + There might be multiple ``Signed-off-by:`` lines, depending on the history + of the patch. + More details may be found in the `Gerrit Signed-off-by Lines guidelines`_. - Ensure that each commit also has a unique ``Change-Id:`` line. If you have @@ -87,27 +56,144 @@ Submitting Changes More details may be found in the `Gerrit Change-Ids documentation`_. +- Write informative and comprehensive commit messages. A good commit message + provides all the background information needed for reviewers to understand + the intent and rationale of the patch. This information is also useful for + future reference. + + For example: + + - What does the patch do? + - What motivated it? + - What impact does it have? + - How was it tested? + - Have alternatives been considered? Why did you choose this approach over + another one? + - If it fixes an `issue`_, include a reference. + +- Follow the :ref:`Coding Style` and :ref:`Coding Guidelines`. + + - Use the checkpatch.pl script provided with the Linux source tree. A + Makefile target is provided for convenience, see :ref:`this + section<automatic-compliance-checking>` for more details. + +- Where appropriate, please update the documentation. + + - Consider whether the :ref:`Porting Guide`, :ref:`Firmware Design` document + or other in-source documentation needs updating. + + - If you are submitting new files that you intend to be the code owner for + (for example, a new platform port), then also update the + :ref:`code owners` file. + + - For topics with multiple commits, you should make all documentation changes + (and nothing else) in the last commit of the series. Otherwise, include + the documentation changes within the single commit. + +.. _copyright-license-guidance: + +- Ensure that each changed file has the correct copyright and license + information. Files that entirely consist of contributions to this project + should have a copyright notice and BSD-3-Clause SPDX license identifier of + the form as shown in :ref:`license`. Files that contain changes to imported + Third Party IP files should retain their original copyright and license + notices. + + For significant contributions you may add your own copyright notice in the + following format: + + :: + + Portions copyright (c) [XXXX-]YYYY, <OWNER>. All rights reserved. + + where XXXX is the year of first contribution (if different to YYYY) and YYYY + is the year of most recent contribution. <OWNER> is your name or your company + name. + +- Ensure that each patch in the patch series compiles in all supported + configurations. Patches which do not compile will not be merged. + +- Please test your changes. As a minimum, ensure that Linux boots on the + Foundation FVP. See :ref:`Arm Fixed Virtual Platforms (FVP)` for more + information. For more extensive testing, consider running the `TF-A Tests`_ + against your patches. + +- Ensure that all CI automated tests pass. Failures should be fixed. They might + block a patch, depending on how critical they are. + +Submitting Changes +------------------ + - Submit your changes for review at https://review.trustedfirmware.org targeting the ``integration`` branch. - - The changes will then undergo further review and testing by the - :ref:`maintainers`. Any review comments will be made directly on your - patch. This may require you to do some rework. +- Add reviewers for your patch: + + - At least one code owner for each module modified by the patch. See the list + of modules and their :ref:`code owners`. + + - At least one maintainer. See the list of :ref:`maintainers`. + + - If some module has no code owner, try to identify a suitable (non-code + owner) reviewer. Running ``git blame`` on the module's source code can + help, as it shows who has been working the most recently on this area of + the code. + + Alternatively, if it is impractical to identify such a reviewer, you might + send an email to the `TF-A mailing list`_ to broadcast your review request + to the community. + + Note that self-reviewing a patch is prohibited, even if the patch author is + the only code owner of a module modified by the patch. Getting a second pair + of eyes on the code is essential to keep up with the quality standards the + project aspires to. + +- The changes will then undergo further review by the designated people. Any + review comments will be made directly on your patch. This may require you to + do some rework. For controversial changes, the discussion might be moved to + the `TF-A mailing list`_ to involve more of the community. Refer to the `Gerrit Uploading Changes documentation`_ for more details. +- The patch submission rules are the following. For a patch to be approved + and merged in the tree, it must get: + + - One ``Code-Owner-Review+1`` for each of the modules modified by the patch. + - A ``Maintainer-Review+1``. + + In the case where a code owner could not be found for a given module, + ``Code-Owner-Review+1`` is substituted by ``Code-Review+1``. + + In addition to these various code review labels, the patch must also get a + ``Verified+1``. This is usually set by the Continuous Integration (CI) bot + when all automated tests passed on the patch. Sometimes, some of these + automated tests may fail for reasons unrelated to the patch. In this case, + the maintainers might (after analysis of the failures) override the CI bot + score to certify that the patch has been correctly tested. + + In the event where the CI system lacks proper tests for a patch, the patch + author or a reviewer might agree to perform additional manual tests + in their review and the reviewer incorporates the review of the additional + testing in the ``Code-Review+1`` or ``Code-Owner-Review+1`` as applicable to + attest that the patch works as expected. Where possible additional tests should + be added to the CI system as a follow up task. For example, for a + platform-dependent patch where the said platform is not available in the CI + system's board farm. + - When the changes are accepted, the :ref:`maintainers` will integrate them. - Typically, the :ref:`maintainers` will merge the changes into the ``integration`` branch. + - If the changes are not based on a sufficiently-recent commit, or if they cannot be automatically rebased, then the :ref:`maintainers` may rebase it - on the ``master`` branch or ask you to do so. + on the ``integration`` branch or ask you to do so. + - After final integration testing, the changes will make their way into the - ``master`` branch. If a problem is found during integration, the merge - commit will be removed from the ``integration`` branch and the - :ref:`maintainers` will ask you to create a new patch set to resolve the - problem. + ``master`` branch. If a problem is found during integration, the + :ref:`maintainers` will request your help to solve the issue. They may + revert your patches and ask you to resubmit a reworked version of them or + they may ask you to provide a fix-up patch. Binary Components ----------------- @@ -128,15 +214,17 @@ Binary Components -------------- -*Copyright (c) 2013-2019, Arm Limited and Contributors. All rights reserved.* +*Copyright (c) 2013-2020, Arm Limited and Contributors. All rights reserved.* .. _developer.trustedfirmware.org: https://developer.trustedfirmware.org +.. _review.trustedfirmware.org: https://review.trustedfirmware.org .. _issue: https://developer.trustedfirmware.org/project/board/1/ .. _Trusted Firmware-A: https://git.trustedfirmware.org/TF-A/trusted-firmware-a.git .. _Git guidelines: http://git-scm.com/book/ch5-2.html .. _Gerrit Uploading Changes documentation: https://review.trustedfirmware.org/Documentation/user-upload.html .. _Gerrit Signed-off-by Lines guidelines: https://review.trustedfirmware.org/Documentation/user-signedoffby.html .. _Gerrit Change-Ids documentation: https://review.trustedfirmware.org/Documentation/user-changeid.html -.. _TF-A Tests: https://git.trustedfirmware.org/TF-A/tf-a-tests.git/about/ +.. _TF-A Tests: https://trustedfirmware-a-tests.readthedocs.io .. _Trusted Firmware binary repository: https://review.trustedfirmware.org/admin/repos/tf-binaries .. _tf-binaries-readme: https://git.trustedfirmware.org/tf-binaries.git/tree/readme.rst +.. _TF-A mailing list: https://lists.trustedfirmware.org/mailman/listinfo/tf-a diff --git a/docs/process/faq.rst b/docs/process/faq.rst index 2c3658480..daab1987f 100644 --- a/docs/process/faq.rst +++ b/docs/process/faq.rst @@ -70,12 +70,10 @@ What are these strange comments in my changes? All the comments from ``ci-bot-user`` are associated with Continuous Integration infrastructure. The links published on the comment are not currently accessible, but would be after the CI has been transitioned to `trustedfirmware.org`_. -Please refer to https://github.com/ARM-software/tf-issues/issues/681 for more -details on the timelines. -------------- -*Copyright (c) 2019, Arm Limited. All rights reserved.* +*Copyright (c) 2019-2020, Arm Limited. All rights reserved.* .. _Gerrit Upload Patch Set documentation: https://review.trustedfirmware.org/Documentation/intro-user.html#upload-patch-set .. _Gerrit Replace Changes documentation: https://review.trustedfirmware.org/Documentation/user-upload.html#push_replace diff --git a/docs/process/index.rst b/docs/process/index.rst index 9c12de82f..37324b0e9 100644 --- a/docs/process/index.rst +++ b/docs/process/index.rst @@ -8,7 +8,9 @@ Processes & Policies security platform-compatibility-policy + coding-style coding-guidelines contributing + code-review-guidelines faq security-hardening diff --git a/docs/process/security-hardening.rst b/docs/process/security-hardening.rst index a18a79203..507046f2e 100644 --- a/docs/process/security-hardening.rst +++ b/docs/process/security-hardening.rst @@ -1,10 +1,123 @@ -Security hardening -================== +Secure Development Guidelines +============================= This page contains guidance on what to check for additional security measures, including build options that can be modified to improve security or catch issues early in development. +Security considerations +----------------------- + +Part of the security of a platform is handling errors correctly, as described in +the previous section. There are several other security considerations covered in +this section. + +Do not leak secrets to the normal world +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The secure world **must not** leak secrets to the normal world, for example in +response to an SMC. + +Handling Denial of Service attacks +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The secure world **should never** crash or become unusable due to receiving too +many normal world requests (a *Denial of Service* or *DoS* attack). It should +have a mechanism for throttling or ignoring normal world requests. + +Preventing Secure-world timing information leakage via PMU counters +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The Secure world needs to implement some defenses to prevent the Non-secure +world from making it leak timing information. In general, higher privilege +levels must defend from those below when the PMU is treated as an attack +vector. + +Refer to the :ref:`Performance Monitoring Unit` guide for detailed information +on the PMU registers. + +Timing leakage attacks from the Non-secure world +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Since the Non-secure world has access to the ``PMCR`` register, it can +configure the PMU to increment counters at any exception level and in both +Secure and Non-secure state. Thus, it attempts to leak timing information from +the Secure world. + +Shown below is an example of such a configuration: + +- ``PMEVTYPER0_EL0`` and ``PMCCFILTR_EL0``: + + - Set ``P`` to ``0``. + - Set ``NSK`` to ``1``. + - Set ``M`` to ``0``. + - Set ``NSH`` to ``0``. + - Set ``SH`` to ``1``. + +- ``PMCNTENSET_EL0``: + + - Set ``P[0]`` to ``1``. + - Set ``C`` to ``1``. + +- ``PMCR_EL0``: + + - Set ``DP`` to ``0``. + - Set ``E`` to ``1``. + +This configuration instructs ``PMEVCNTR0_EL0`` and ``PMCCNTR_EL0`` to increment +at Secure EL1, Secure EL2 (if implemented) and EL3. + +Since the Non-secure world has fine-grained control over where (at which +exception levels) it instructs counters to increment, obtaining event counts +would allow it to carry out side-channel timing attacks against the Secure +world. Examples include Spectre, Meltdown, as well as extracting secrets from +cryptographic algorithms with data-dependent variations in their execution +time. + +Secure world mitigation strategies +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The ``MDCR_EL3`` register allows EL3 to configure the PMU (among other things). +The `Arm ARM`_ details all of the bit fields in this register, but for the PMU +there are two bits which determine the permissions of the counters: + +- ``SPME`` for the programmable counters. +- ``SCCD`` for the cycle counter. + +Depending on the implemented features, the Secure world can prohibit counting +in AArch64 state via the following: + +- ARMv8.2-Debug not implemented: + + - Prohibit general event counters and the cycle counter: + ``MDCR_EL3.SPME == 0 && PMCR_EL0.DP == 1 && !ExternalSecureNoninvasiveDebugEnabled()``. + + - ``MDCR_EL3.SPME`` resets to ``0``, so by default general events should + not be counted in the Secure world. + - The ``PMCR_EL0.DP`` bit therefore needs to be set to ``1`` when EL3 is + entered and ``PMCR_EL0`` needs to be saved and restored in EL3. + - ``ExternalSecureNoninvasiveDebugEnabled()`` is an authentication + interface which is implementation-defined unless ARMv8.4-Debug is + implemented. The `Arm ARM`_ has detailed information on this topic. + + - The only other way is to disable the ``PMCR_EL0.E`` bit upon entering + EL3, which disables counting altogether. + +- ARMv8.2-Debug implemented: + + - Prohibit general event counters: ``MDCR_EL3.SPME == 0``. + - Prohibit cycle counter: ``MDCR_EL3.SPME == 0 && PMCR_EL0.DP == 1``. + ``PMCR_EL0`` therefore needs to be saved and restored in EL3. + +- ARMv8.5-PMU implemented: + + - Prohibit general event counters: as in ARMv8.2-Debug. + - Prohibit cycle counter: ``MDCR_EL3.SCCD == 1`` + +In Aarch32 execution state the ``MDCR_EL3`` alias is the ``SDCR`` register, +which has some of the bit fields of ``MDCR_EL3``, most importantly the ``SPME`` +and ``SCCD`` bits. + Build options ------------- @@ -51,6 +164,12 @@ Several build options can be used to check for security issues. Refer to the NB: The ``Werror`` flag is enabled by default in TF-A and can be disabled by setting the ``E`` build flag to 0. +.. rubric:: References + +- `Arm ARM`_ + -------------- -*Copyright (c) 2019, Arm Limited. All rights reserved.* +*Copyright (c) 2019-2020, Arm Limited. All rights reserved.* + +.. _Arm ARM: https://developer.arm.com/docs/ddi0487/latest diff --git a/docs/process/security-reporting.asc b/docs/process/security-reporting.asc deleted file mode 100644 index 8c41f7bf6..000000000 --- a/docs/process/security-reporting.asc +++ /dev/null @@ -1,45 +0,0 @@ ------BEGIN PGP PUBLIC KEY BLOCK----- -Version: PGP Desktop 10.2.0 (Build 2317) - -mQENBFey/QMBCACyxJaLsMYU794ZfzLdY172tHXRJfP0X3b34HU35G7kYl1zNiYc -/NoygtQdtDv/aW1B2A/YTNhGge+gX4BWAREd5CYDbdPEoMWC395/qbnmMmez7YNY -PEJ9Iq9e5AayAWwZTL1zgKwdvE+WTwWok/nMbsifJSEdhdrOIHNqRcZgplUUyZ2R -sDqFtSbACO3xj4Psk8KJ23Ax7UZgULouZOJaHOnyq8F9V/U7zWvX4Odf96XaC1Em -cUTsG0kQfa7Y4Hqqjzowq366I4k2o2LAtuLPWNCvq5jjEceLs2+qV4cNLgyL2dzO -wtUL6EdkrGfkxsPHpsVKXig4wjeX9ehCSqRlABEBAAG0PVRydXN0ZWQgRmlybXdh -cmUgU2VjdXJpdHkgPHRydXN0ZWQtZmlybXdhcmUtc2VjdXJpdHlAYXJtLmNvbT6J -AYwEEAECAHYFAley/SEwFIAAAAAAIAAHcHJlZmVycmVkLWVtYWlsLWVuY29kaW5n -QHBncC5jb21wZ3BtaW1lCAsJCAcDAgEKAhkBGRhsZGFwOi8va2V5c2VydmVyLnBn -cC5jb20FGwMAAAAFFgADAgEFHgEAAAAGFQgJCgMCAAoJEDq378tFoN/QFJsH/0ly -H91LYYzKIQrbolQw7Rp47lgzH88uN1rInYpW2GaTbjwPffAhYJ4VsN8RaiFskD9m -DjMg4vY8p0jPTCUX1Acq20Wq0Ybv3HcrtjUp4ie0+rLUi3043yJyKFMWkJC2Kr+p -SobnxSrAie4HDFUgSaPoh9Qf1zXEzOavdgcziMiyS5iVUf6NXYZ9z82OTZ6TdPKS -u+L5zOHTdrV3+hD54w00Xa+EIE7u4v0to6Uwm977508hyGuvpOVq+u7+S3qJQvnY -+JheStbgLsm6CyoRjyrlTE01ujAD6hI6Ef9yMgEljOBEy4phKAJ67SCRLEOiCp5U -YHFCULwhzIyg2y3WmZSJASIEEAECAAwFAlezAnwFAwASdQAACgkQlxC4m8pXrXzd -GAf/T8YEICI9qQt2vnCtCbBvVaTc2sAphVZ51kZVDqCDPB7znDtJYRBpi/9IPELt -mYwIElMx2mqmahVaeUghmbzmcLZe8QHUi8GanO1mh+ook6uyjRojSIq6VUVV5uUf -tuscfhpilOvUclqMqYEIgXfl08YwS40Kmmj0qokwad0co0zGQ8GEhlgMi2yvJfiG -fPS0Xcn1J0980E/VgJQCAKwZvukrbb32WVwuhgepqs/4/62PZNxglcErioFt6P0A -ik4t9Hr0uErqCeEKiYtmEw5e9ioRdX7CV+tJgIk907Tpv6E0iDFRJHmJBvmsz82O -stOazS3wZ5Xck7asTqkvoyo9Z7kBDQRXsv0DAQgAsmL1UUIWyoNmYJWixSPDmclP -0ul3T1FCOsIlWTeVeshnHByYdgZOfce78ETCUoq8G7qvYm4GRrEDpqVbxqTxJioP -4Li05WDdNCKzSoqWd8ADA48gYnnJEu2NhA7ZkEC6u3+Mdbmd3M0J6nsAWeE0BV1p -F5zI600sJuoH2QNWB7Kv5N3GCFE4IgCIH8MwDo4Y4FTZtygx4GjEtSExiOIz+bpX -2+GkFCQGpIyLHLP4FmQmrsNzsIdEyFuG0IdoVuQ2PtNLiw+Wkm7CXWgRmFx/dtPN -eVnOFWdbTtjBWVv/Z6zbANos2knfc75KR4FCQ6pWRvVeJuMuMopUDkfFDMtR8QAR -AQABiQJBBBgBAgErBQJXsv0EBRsMAAAAwF0gBBkBCAAGBQJXsv0DAAoJENaB8ph8 -s9hu/nsH/Rx696ZR+1vZi5qCTUwo6s0Qa15x4OuyJEM85VgMLVY7/MZpp1Y8If6u -A5BynQpy4QIPxIRsRx6twduW9/gb8UVhpMRPyuJ+5sSv0/KeUqkPbKSUGro2zGlR -sjqPrchi6uafWZqOR/y/DNkEvkgZZaP+f9xs2qWKuoF08yTioo76QoroA4DVuVAT -MkDFe9d3natAmfmjO4kvxuthg3y7R+sdXrCHpYYJZdbiR6gyj7e8whlSLwHQT3lz -7QBL/CvVvL/dmhu5pk8fsksbehepMQTkCJ6GGEamOPEhwh7IvlzhEt97U4uzjuMd -BPjqOCes+4QTmn/+lMTySG0kXxnHOEUACgkQOrfvy0Wg39D8Jgf/Uf3epkMOJ9xm -N1l5vW8tQQ6RR055YQxQ9P6JMyCQGEJmGOcvrasCho69wMQDy4AYVtJaZd25LH/3 -LX/lcyDOP4C9VYXM+IxlcaRmjBKqWx9UzQeeioIkfmjMpJFU846ZP1dacge0lPx8 -p6ocPbM0rkv0xuF/dwkDQd4BPSmv4/3/UM8FRoYo8Q7SHkDR98wJ8FCm6k9wRtWC -K/jzmBswY2TewAHom3jLzTM0FZ/n5Sini3EGAI2EvnQrxWRpeE7ZOkHKqLHEOaHl -zeST4U/cUgxhwgnhbGJ7zmrFsHpYnnZYM3mIKfQ3/EhksZ68TF9IB1tfUiQTij4r -9jWa0ybRdQ== -=nZZb ------END PGP PUBLIC KEY BLOCK----- diff --git a/docs/process/security.rst b/docs/process/security.rst index c3935daa1..a3b9971e4 100644 --- a/docs/process/security.rst +++ b/docs/process/security.rst @@ -20,40 +20,15 @@ Found a Security Issue? Although we try to keep TF-A secure, we can only do so with the help of the community of developers and security researchers. -If you think you have found a security vulnerability, please **do not** report it -in the `issue tracker`_. Instead send an email to -trusted-firmware-security@arm.com +.. warning:: + If you think you have found a security vulnerability, please **do not** + report it in the `issue tracker`_ or on the `mailing list`_. Instead, please + follow the `TrustedFirmware.org security incident process`_. -Please include: - -* Trusted Firmware-A version (or commit) affected - -* A description of the concern or vulnerability - -* Details on how to replicate the vulnerability, including: - - - Configuration details - - - Proof of concept exploit code - - - Any additional software or tools required - -We recommend using :download:`this PGP/GPG key <./security-reporting.asc>` for -encrypting the information. This key is also available at -http://keyserver.pgp.com and LDAP port 389 of the same server. - -The fingerprint for this key is: - -:: - - 1309 2C19 22B4 8E87 F17B FE5C 3AB7 EFCB 45A0 DFD0 - -If you would like replies to be encrypted, please provide your public key. - -Please give us the time to respond to you and fix the vulnerability before going -public. We do our best to respond and fix any issues quickly. We also need to -ensure providers of products that use TF-A have a chance to consider the -implications of the vulnerability and its remedy. +One of the goals of this process is to ensure providers of products that use +TF-A have a chance to consider the implications of the vulnerability and its +remedy before it is made public. As such, please follow the disclosure plan +outlined in the process. We do our best to respond and fix any issues quickly. Afterwards, we encourage you to write-up your findings about the TF-A source code. @@ -61,8 +36,8 @@ code. Attribution ----------- -We will name and thank you in the :ref:`Change Log & Release Notes` distributed with the source -code and in any published security advisory. +We will name and thank you in the :ref:`Change Log & Release Notes` distributed +with the source code and in any published security advisory. Security Advisories ------------------- @@ -96,7 +71,7 @@ Security Advisories +-----------+------------------------------------------------------------------+ .. _issue tracker: https://developer.trustedfirmware.org/project/board/1/ -.. _this PGP/GPG key: security-reporting.asc +.. _mailing list: https://lists.trustedfirmware.org/mailman/listinfo/tf-a .. |TFV-1| replace:: :ref:`Advisory TFV-1 (CVE-2016-10319)` .. |TFV-2| replace:: :ref:`Advisory TFV-2 (CVE-2017-7564)` @@ -107,6 +82,8 @@ Security Advisories .. |TFV-7| replace:: :ref:`Advisory TFV-7 (CVE-2018-3639)` .. |TFV-8| replace:: :ref:`Advisory TFV-8 (CVE-2018-19440)` +.. _TrustedFirmware.org security incident process: https://developer.trustedfirmware.org/w/collaboration/security_center/ + -------------- -*Copyright (c) 2019, Arm Limited. All rights reserved.* +*Copyright (c) 2019-2020, Arm Limited. All rights reserved.* diff --git a/docs/resources/diagrams/cmake_framework_structure.png b/docs/resources/diagrams/cmake_framework_structure.png Binary files differnew file mode 100644 index 000000000..6006f1c30 --- /dev/null +++ b/docs/resources/diagrams/cmake_framework_structure.png diff --git a/docs/resources/diagrams/cmake_framework_workflow.png b/docs/resources/diagrams/cmake_framework_workflow.png Binary files differnew file mode 100644 index 000000000..7311529c4 --- /dev/null +++ b/docs/resources/diagrams/cmake_framework_workflow.png diff --git a/docs/resources/diagrams/ff-a-spm-sel2.png b/docs/resources/diagrams/ff-a-spm-sel2.png Binary files differnew file mode 100644 index 000000000..6479ff559 --- /dev/null +++ b/docs/resources/diagrams/ff-a-spm-sel2.png diff --git a/docs/resources/diagrams/plantuml/bl2-loading-sp.puml b/docs/resources/diagrams/plantuml/bl2-loading-sp.puml new file mode 100644 index 000000000..3cf7c3620 --- /dev/null +++ b/docs/resources/diagrams/plantuml/bl2-loading-sp.puml @@ -0,0 +1,44 @@ +/' + ' Copyright (c) 2020, ARM Limited and Contributors. All rights reserved. + ' + ' SPDX-License-Identifier: BSD-3-Clause + '/ + +@startuml +participant bl1 +participant FIP + +bl1 -> FIP : read(FW_CONFIG) +create FW_CONFIG +bl1 -> FW_CONFIG : load + +bl1 -> FIP : read(bl2) +create bl2 +bl1 -> bl2 : load +bl1 --> bl2 : hand off (FW_CONFIG) + +bl2 -> FW_CONFIG : read_node(SPKs) +loop for each spkg subnode + bl2 -> FW_CONFIG : read(UUID) + bl2 -> FW_CONFIG : read(load_address) + bl2 -> FIP : read(spkg@UUID) + create SPKG + bl2 -> SPKG : load +end loop + +bl2 -> FW_CONFIG : read_node(TOS_FW_CONFIG) +create TOS_FW_CONFIG +bl2 -> TOS_FW_CONFIG : load + +bl2 -> FIP : read(bl32/SPMC) +create SPMC +bl2 -> SPMC : load + +bl2 -> FIP : read(bl31) +create bl31 +bl2 -> bl31 : load +bl2 --> bl31 : hand off (TOS_FW_CONFIG) + +bl31 --> SPMC : hand off (TOS_FW_CONFIG) + +@enduml diff --git a/docs/resources/diagrams/plantuml/fconf_bl1_load_config.puml b/docs/resources/diagrams/plantuml/fconf_bl1_load_config.puml new file mode 100644 index 000000000..e513ed4c3 --- /dev/null +++ b/docs/resources/diagrams/plantuml/fconf_bl1_load_config.puml @@ -0,0 +1,78 @@ +@startuml + +box "BL1 common code" + participant bl1_main + participant bl_common +end box + +box "arm platform code" #LightBlue + participant fvp_bl1_setup + participant arm_bl1_setup + participant arm_io_storage +end box + +box "platform common code" + participant plat_bl1_common + participant fconf_dyn_cfg_getter + participant fconf +end box + +bl1_main -> fvp_bl1_setup : bl1_platform_setup() +fvp_bl1_setup -> arm_bl1_setup : arm_bl1_platform_setup() +arm_bl1_setup -> arm_io_storage : plat_arm_io_setup() +note over arm_io_storage : register and setup fip +arm_bl1_setup -> fconf : set_fw_config_info(fw_config_base, max_size) +note over fconf + set fw_config information + (address, size, image_id) + in global dtb_infos array. +end note +activate fconf + arm_bl1_setup -> fconf : fconf_load_config(FW_CONFIG_ID) + fconf -> fconf : FCONF_GET_PROPERTY(dyn_cfg, dtb, FW_CONFIG_ID) + fconf -> fconf_dyn_cfg_getter: dyn_cfg_dtb_info_getter(FW_CONFIG_ID) + fconf_dyn_cfg_getter -> fconf: fw_config_info + fconf -> bl_common : load_auth_image(FW_CONFIG_ID, &image_info) + activate bl_common + note over bl_common + load and auth image from fip + with info from plat_io_policy + end note + bl_common -> arm_io_storage + arm_io_storage -> fconf: FCONF_GET_PROPERTY(arm, arm_io_policies, FW_CONFIG_ID) + note over fconf: use statically defined policies in bl1 + fconf <- bl_common : image_info + deactivate bl_common + note over fconf : get fw_config_dtb from image_info + arm_bl1_setup -> fconf: FCONF_GET_PROPERTY(dyn_cfg, dtb, FW_CONFIG_ID) + fconf -> fconf_dyn_cfg_getter: dyn_cfg_dtb_info_getter(FW_CONFIG_ID) + fconf_dyn_cfg_getter -> arm_bl1_setup: fw_config_info + arm_bl1_setup -> fconf_dyn_cfg_getter: populate_dtb_registry(uintptr_t dtb) + arm_bl1_setup -> fconf: fconf_load_config(TB_FW_CONFIG_ID) + fconf -> fconf : FCONF_GET_PROPERTY(dyn_cfg, dtb, TB_FW_CONFIG_ID) + fconf -> fconf_dyn_cfg_getter: dyn_cfg_dtb_info_getter(TB_FW_CONFIG_ID) + fconf_dyn_cfg_getter -> fconf: tb_fw_config_info + fconf -> bl_common : load_auth_image(TB_FW_CONFIG_ID, &image_info) + activate bl_common + note over bl_common + load and auth image from fip + with info from plat_io_policy + end note + bl_common -> arm_io_storage + arm_io_storage -> fconf: FCONF_GET_PROPERTY(arm, arm_io_policies, TB_FW_CONFIG_ID) + note over fconf: use statically defined policies in bl1 + fconf <- bl_common : image_info + deactivate bl_common + note over fconf : get tb_fw_config_dtb from image_info + fconf -> arm_bl1_setup + arm_bl1_setup -> plat_bl1_common : bl1_plat_get_image_desc(BL2_IMAGE_ID) + arm_bl1_setup <- plat_bl1_common : BL2_IMAGE_DESC + note over arm_bl1_setup + set ep_info.args.arg0 of BL2_IMAGE_DESC + to FW_CONFIG base address + end note +deactivate fconf + +== load & auth, prepare and jump to BL2 == + +@enduml diff --git a/docs/resources/diagrams/plantuml/fconf_bl2_populate.puml b/docs/resources/diagrams/plantuml/fconf_bl2_populate.puml new file mode 100644 index 000000000..c536ee090 --- /dev/null +++ b/docs/resources/diagrams/plantuml/fconf_bl2_populate.puml @@ -0,0 +1,49 @@ +@startuml + +box "BL2 common code" + participant bl2_entrypoint + participant bl2_main +end box + +box "platform common code" + participant fconf + participant fconf_tbbr_getter +participant fconf_dyn_cfg_getter +end box + +box "arm platform code" #LightBlue + participant arm_bl2_setup + participant arm_io_storage + participant arm_fconf_io +end box + +== bl2 setup == +bl2_entrypoint -> bl2_main : bl2_setup() +bl2_main -> arm_bl2_setup : bl2_early_platform_setup2(\n\t arg0, arg1, arg2, arg3) +note over arm_bl2_setup + arg0 = fw_config + arg1 = mem_layout +end note +arm_bl2_setup -> arm_bl2_setup : arm_bl2_early_platform_setup(\n\t fw_config, mem_layout) +activate arm_bl2_setup + arm_bl2_setup -> fconf: fconf_populate("FW_CONFIG", fw_config) + activate fconf + fconf -> fconf_dyn_cfg_getter: populate_dtb_registry(uintptr_t dtb) + note over fconf_dyn_cfg_getter: read dtb_registry properties from dtb + fconf_dyn_cfg_getter -> arm_bl2_setup + arm_bl2_setup -> fconf: FCONF_GET_PROPERTY(dyn_cfg, dtb, TB_FW_CONFIG_ID) + fconf -> fconf_dyn_cfg_getter: dyn_cfg_dtb_info_getter(TB_FW_CONFIG_ID) + fconf_dyn_cfg_getter -> arm_bl2_setup: tb_fw_config_info + arm_bl2_setup -> fconf: fconf_populate("TB_FW_CONFIG", tb_fw_config) + fconf -> fconf_tbbr_getter: fconf_populate_tbbr_dyn_config(uintptr_t dtb) + note over fconf_tbbr_getter: read tbbr properties from dtb + fconf -> arm_fconf_io: fconf_populate_arm_io_policies(uintptr_t dtb) + note over arm_fconf_io: read arm io propeties from dtb + deactivate fconf + arm_bl2_setup -> arm_io_storage : plat_arm_io_setup() + note over arm_io_storage: use populated properties +deactivate arm_bl2_setup + +== bl2 main == + +@enduml diff --git a/docs/resources/diagrams/plantuml/fip-secure-partitions.puml b/docs/resources/diagrams/plantuml/fip-secure-partitions.puml new file mode 100644 index 000000000..9457e326a --- /dev/null +++ b/docs/resources/diagrams/plantuml/fip-secure-partitions.puml @@ -0,0 +1,167 @@ +/' + ' Copyright (c) 2020, ARM Limited and Contributors. All rights reserved. + ' + ' SPDX-License-Identifier: BSD-3-Clause + '/ + +@startuml + +folder SP_vendor_1 { + artifact sp_binary_1 + artifact sp_manifest_1 [ + sp_manifest_1 + === + UUID = xxx + load_address = 0xaaa + owner = "Sip" + ... + ] +} + +folder SP_vendor_2 { + artifact sp_binary_2 + artifact sp_manifest_2 [ + sp_manifest_2 + === + UUID = yyy + load_address = 0xbbb + owner = "Plat" + ] +} + +artifact tb_fw_config.dts [ + tb_fw_config.dts + ---- + secure-partitions + === + spkg_1 UUID + spkg_1 load_address + --- + spkg_2 UUID + spkg_2 load_address + --- + ... + === + ...<rest of the nodes> +] + +artifact config.json [ + SP_LAYOUT.json + === + path to sp_binary_1 + path to sp_manifest_1 + --- + path to sp_binary_2 + path to sp_manifest_2 + --- + ... +] + +control sp_mk_generator + +artifact sp_gen [ + sp_gen.mk + === + FDT_SOURCE = ... + SPTOOL_ARGS = ... + FIP_ARGS = ... + CRT_ARGS = ... +] + +control dtc +control sptool + +artifact tb_fw_config.dtb + +artifact spkg_1 [ + sp1.pkg + === + <i>header</i> + --- + manifest + --- + binary +] + +artifact spkg_2 [ + sp2.pkg + === + <i>header</i> + --- + manifest + --- + binary +] + +artifact signed_tb_fw_config.dtb [ + tb_fw_config.dtb (signed) +] + +artifact signed_spkg_1 [ + sp1.pkg (signed) + === + <i>header</i> + --- + manifest + --- + binary + --- + <i>signature</I> +] + +artifact signed_spkg_2 [ + sp2.pkg (signed) + === + <i>header</i> + --- + manifest + --- + binary + --- + <i>signature</I> +] + +control crttool +control fiptool + +artifact fip [ + fip.bin + === + tb_fw_config.dtb (signed) + --- + ... + --- + sp1.pkg (signed & SiP owned) + --- + sp2.pkg (signed & Platform owned) + --- + ... +] + +config.json .up.> SP_vendor_1 +config.json .up.> SP_vendor_2 +config.json --> sp_mk_generator +sp_mk_generator --> sp_gen +sp_gen --> fiptool +sp_gen --> cert_create +sp_gen --> sptool + +sptool --> spkg_1 +sptool --> spkg_2 + +spkg_1 --> cert_create +spkg_2 --> cert_create +cert_create --> signed_spkg_1 +cert_create --> signed_spkg_2 + +tb_fw_config.dts --> dtc +dtc --> tb_fw_config.dtb +tb_fw_config.dtb --> cert_create +cert_create --> signed_tb_fw_config.dtb + +signed_tb_fw_config.dtb --> fiptool +signed_spkg_1 -down-> fiptool +signed_spkg_2 -down-> fiptool +fiptool -down-> fip + +@enduml diff --git a/docs/security_advisories/security-advisory-tfv-8.rst b/docs/security_advisories/security-advisory-tfv-8.rst index c401eb3df..ebe324e72 100644 --- a/docs/security_advisories/security-advisory-tfv-8.rst +++ b/docs/security_advisories/security-advisory-tfv-8.rst @@ -99,5 +99,5 @@ line 19 (referring to the version of the code as of `commit c385955`_): .. _CVE-2018-19440: http://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2018-19440 .. _commit c385955: https://github.com/ARM-software/arm-trusted-firmware/commit/c385955 -.. _SMC Calling Convention: http://arminfo.emea.arm.com/help/topic/com.arm.doc.den0028b/ARM_DEN0028B_SMC_Calling_Convention.pdf +.. _SMC Calling Convention: https://developer.arm.com/docs/den0028/latest .. _Pull Request #1710: https://github.com/ARM-software/arm-trusted-firmware/pull/1710 |
