diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/change-log.rst | 442 | ||||
| -rw-r--r-- | docs/user-guide.rst | 59 |
2 files changed, 473 insertions, 28 deletions
diff --git a/docs/change-log.rst b/docs/change-log.rst index b0ef4221b..123fe24db 100644 --- a/docs/change-log.rst +++ b/docs/change-log.rst @@ -4,6 +4,446 @@ .. contents:: +Trusted Firmware-A - version 2.1 +================================ + +New Features +------------ + +- Architecture + - Support for ARMv8.3 pointer authentication in the normal and secure worlds + + The use of pointer authentication in the normal world is enabled whenever + architectural support is available, without the need for additional build + flags. + + Use of pointer authentication in the secure world remains an + experimental configuration at this time. Using both the ``ENABLE_PAUTH`` + and ``CTX_INCLUDE_PAUTH_REGS`` build flags, pointer authentication can be + enabled in EL3 and S-EL1/0. + + See the `Firmware Design`_ document for additional details on the use of + pointer authentication. + + - Enable Data Independent Timing (DIT) in EL3, where supported + +- Build System + - Support for BL-specific build flags + + - Support setting compiler target architecture based on ``ARM_ARCH_MINOR`` + build option. + + - New ``RECLAIM_INIT_CODE`` build flag: + + A significant amount of the code used for the initialization of BL31 is + not needed again after boot time. In order to reduce the runtime memory + footprint, the memory used for this code can be reclaimed after + initialization. + + Certain boot-time functions were marked with the ``__init`` attribute to + enable this reclamation. + +- CPU Support + - cortex-a76: Workaround for erratum 1073348 + - cortex-a76: Workaround for erratum 1220197 + - cortex-a76: Workaround for erratum 1130799 + + - cortex-a75: Workaround for erratum 790748 + - cortex-a75: Workaround for erratum 764081 + + - cortex-a73: Workaround for erratum 852427 + - cortex-a73: Workaround for erratum 855423 + + - cortex-a57: Workaround for erratum 817169 + - cortex-a57: Workaround for erratum 814670 + + - cortex-a55: Workaround for erratum 903758 + - cortex-a55: Workaround for erratum 846532 + - cortex-a55: Workaround for erratum 798797 + - cortex-a55: Workaround for erratum 778703 + - cortex-a55: Workaround for erratum 768277 + + - cortex-a53: Workaround for erratum 819472 + - cortex-a53: Workaround for erratum 824069 + - cortex-a53: Workaround for erratum 827319 + + - cortex-a17: Workaround for erratum 852423 + - cortex-a17: Workaround for erratum 852421 + + - cortex-a15: Workaround for erratum 816470 + - cortex-a15: Workaround for erratum 827671 + +- Documentation + - Exception Handling Framework documentation + + - Library at ROM (romlib) documentation + + - RAS framework documentation + + - Coding Guidelines document + +- Drivers + - ccn: Add API for setting and reading node registers + - Adds ``ccn_read_node_reg`` function + - Adds ``ccn_write_node_reg`` function + + - partition: Support MBR partition entries + + - scmi: Add ``plat_css_get_scmi_info`` function + + Adds a new API ``plat_css_get_scmi_info`` which lets the platform + register a platform-specific instance of ``scmi_channel_plat_info_t`` and + remove the default values + + - tzc380: Add TZC380 TrustZone Controller driver + + - tzc-dmc620: Add driver to manage the TrustZone Controller within the + DMC-620 Dynamic Memory Controller + +- Library at ROM (romlib) + - Add platform-specific jump table list + + - Allow patching of romlib functions + + This change allows patching of functions in the romlib. This can be done by + adding "patch" at the end of the jump table entry for the function that + needs to be patched in the file jmptbl.i. + +- Library Code + - Support non-LPAE-enabled MMU tables in AArch32 + + - mmio: Add ``mmio_clrsetbits_16`` function + - 16-bit variant of ``mmio_clrsetbits`` + + - object_pool: Add Object Pool Allocator + - Manages object allocation using a fixed-size static array + - Adds ``pool_alloc`` and ``pool_alloc_n`` functions + - Does not provide any functions to free allocated objects (by design) + + - libc: Added ``strlcpy`` function + + - libc: Import ``strrchr`` function from FreeBSD + + - xlat_tables: Add support for ARMv8.4-TTST + + - xlat_tables: Support mapping regions without an explicitly specified VA + +- Math + - Added softudiv macro to support software division + +- Memory Partitioning And Monitoring (MPAM) + - Enabled MPAM EL2 traps (``MPAMHCR_EL2`` and ``MPAM_EL2``) + +- Platforms + - amlogic: Add support for Meson S905 (GXBB) + + - arm/fvp_ve: Add support for FVP Versatile Express platform + + - arm/n1sdp: Add support for Neoverse N1 System Development platform + + - arm/rde1edge: Add support for Neoverse E1 platform + + - arm/rdn1edge: Add support for Neoverse N1 platform + + - arm: Add support for booting directly to Linux without an intermediate + loader (AArch32) + + - arm/juno: Enable new CPU errata workarounds for A53 and A57 + + - arm/juno: Add romlib support + + Building a combined BL1 and ROMLIB binary file with the correct page + alignment is now supported on the Juno platform. When ``USE_ROMLIB`` is set + for Juno, it generates the combined file ``bl1_romlib.bin`` which needs to + be used instead of bl1.bin. + + - intel/stratix: Add support for Intel Stratix 10 SoC FPGA platform + + - marvell: Add support for Armada-37xx SoC platform + + - nxp: Add support for i.MX8M and i.MX7 Warp7 platforms + + - renesas: Add support for R-Car Gen3 platform + + - xilinx: Add support for Versal ACAP platforms + +- Position-Independent Executable (PIE) + + PIE support has initially been added to BL31. The ``ENABLE_PIE`` build flag is + used to enable or disable this functionality as required. + +- Secure Partition Manager + - New, SPCI-compliant SPM implementation + + A new version of SPM has been implemented based on draft specifications of + the SPCI (Secure Partition Client Interface) and SPRT (Secure + Partition Runtime) specifications. + + The new implementation is a prototype that is expected to undergo intensive + rework as the specifications change. It has basic support for multiple + Secure Partitions and Resource Descriptions. + + The old version of SPM, based on MM (ARM Management Mode Interface + Specification), is still present in the codebase. A new build flag, + ``SPM_MM`` has been added to allow selection of the desired implementation. + This flag defaults to 1, selecting the MM-based implementation. + +- Security + - Spectre Variant-1 mitigations (``CVE-2017-5753``) + + - Use Speculation Store Bypass Safe (SSBS) functionality where available + + Provides mitigation against ``CVE-2018-19440`` (Not saving x0 to x3 + registers can leak information from one Normal World SMC client to another) + + +Changed +------- + +- Build System + - Warning levels are now selectable with ``W=<1,2,3>`` + + - Removed unneeded include paths in PLAT_INCLUDES + + - "Warnings as errors" (Werror) can be disabled using ``E=0`` + + - Support totally quiet output with ``-s`` flag + + - Support passing options to checkpatch using ``CHECKPATCH_OPTS=<opts>`` + + - Invoke host compiler with ``HOSTCC / HOSTCCFLAGS`` instead of ``CC / CFLAGS`` + + - Make device tree pre-processing similar to U-boot/Linux by: + - Creating separate ``CPPFLAGS`` for DT preprocessing so that compiler + options specific to it can be accommodated. + - Replacing ``CPP`` with ``PP`` for DT pre-processing + +- CPU Support + - Errata report function definition is now mandatory for CPU support files + + CPU operation files must now define a ``<name>_errata_report`` function to + print errata status. This is no longer a weak reference. + +- Documentation + - Migrated some content from GitHub wiki to ``docs/`` directory + + - Security advisories now have CVE links + + - Updated copyright guidelines + + - Miscellaneous small fixes + +- Drivers + - console: The ``MULTI_CONSOLE_API`` framework has been rewritten in C + - console: Ported multi-console driver to AArch32 + + - gic: Remove 'lowest priority' constants + + Removed ``GIC_LOWEST_SEC_PRIORITY`` and ``GIC_LOWEST_NS_PRIORITY``. + Platforms should define these if required, or instead determine the correct + priority values at runtime. + + - delay_timer: Check that the Generic Timer extension is present + + - mmc: Increase command reply timeout to 10 milliseconds + + - mmc: Poll eMMC device status to ensure ``EXT_CSD`` command completion + + - mmc: Correctly check return code from ``mmc_fill_device_info`` + +- External Libraries + + - libfdt: Upgraded from 1.4.2 to 1.4.6-9 + + - mbed TLS: Upgraded from 2.12 to 2.16 + + This change incorporates fixes for security issues that should be reviewed + to determine if they are relevant for software implementations using + Trusted Firmware-A. See the `mbed TLS releases`_ page for details on + changes from the 2.12 to the 2.16 release. + +- Library Code + - compiler-rt: Updated ``lshrdi3.c`` and ``int_lib.h`` with changes from + LLVM master branch (r345645) + + - cpu: Updated macro that checks need for ``CVE-2017-5715`` mitigation + + - libc: Made setjmp and longjmp C standard compliant + + - libc: Allowed overriding the default libc (use ``OVERRIDE_LIBC``) + + - libc: Moved setjmp and longjmp to the ``libc/`` directory + +- Platforms + - Removed Mbed TLS dependency from plat_bl_common.c + + - arm: Removed unused ``ARM_MAP_BL_ROMLIB`` macro + + - arm: Removed ``ARM_BOARD_OPTIMISE_MEM`` feature and build flag + + - arm: Moved several components into ``drivers/`` directory + + This affects the SDS, SCP, SCPI, MHU and SCMI components + + - arm/juno: Increased maximum BL2 image size to ``0xF000`` + + This change was required to accommodate a larger ``libfdt`` library + +- SCMI + - Optimized bakery locks when hardware-assisted coherency is enabled using the + ``HW_ASSISTED_COHERENCY`` build flag + +- SDEI + - Added support for unconditionally resuming secure world execution after + SDEI event processing completes + + SDEI interrupts, although targeting EL3, occur on behalf of the non-secure + world, and may have higher priority than secure world + interrupts. Therefore they might preempt secure execution and yield + execution to the non-secure SDEI handler. Upon completion of SDEI event + handling, resume secure execution if it was preempted. + +- Translation Tables (XLAT) + - Dynamically detect need for ``Common not Private (TTBRn_ELx.CnP)`` bit + + Properly handle the case where ``ARMv8.2-TTCNP`` is implemented in a CPU + that does not implement all mandatory v8.2 features (and so must claim to + implement a lower architecture version). + + +Resolved Issues +--------------- + +- Architecture + - Incorrect check for SSBS feature detection + + - Unintentional register clobber in AArch32 reset_handler function + +- Build System + - Dependency issue during DTB image build + + - Incorrect variable expansion in Arm platform makefiles + + - Building on Windows with verbose mode (``V=1``) enabled is broken + + - AArch32 compilation flags is missing ``$(march32-directive)`` + +- BL-Specific Issues + - bl2: ``uintptr_t is not defined`` error when ``BL2_IN_XIP_MEM`` is defined + + - bl2: Missing prototype warning in ``bl2_arch_setup`` + + - bl31: Omission of Global Offset Table (GOT) section + +- Code Quality Issues + - Multiple MISRA compliance issues + + - Potential NULL pointer dereference (Coverity-detected) + +- Drivers + - mmc: Local declaration of ``scr`` variable causes a cache issue when + invalidating after the read DMA transfer completes + + - mmc: ``ACMD41`` does not send voltage information during initialization, + resulting in the command being treated as a query. This prevents the + command from initializing the controller. + + - mmc: When checking device state using ``mmc_device_state()`` there are no + retries attempted in the event of an error + + - ccn: Incorrect Region ID calculation for RN-I nodes + + - console: ``Fix MULTI_CONSOLE_API`` when used as a crash console + + - partition: Improper NULL checking in gpt.c + + - partition: Compilation failure in ``VERBOSE`` mode (``V=1``) + +- Library Code + - common: Incorrect check for Address Authentication support + + - xlat: Fix XLAT_V1 / XLAT_V2 incompatibility + + The file ``arm_xlat_tables.h`` has been renamed to ``xlat_tables_compat.h`` + and has been moved to a common folder. This header can be used to guarantee + compatibility, as it includes the correct header based on + ``XLAT_TABLES_LIB_V2``. + + - xlat: armclang unused-function warning on ``xlat_clean_dcache_range`` + + - xlat: Invalid ``mm_cursor`` checks in ``mmap_add`` and ``mmap_add_ctx`` + + - sdei: Missing ``context.h`` header + +- Platforms + - common: Missing prototype warning for ``plat_log_get_prefix`` + + - arm: Insufficient maximum BL33 image size + + - arm: Potential memory corruption during BL2-BL31 transition + + On Arm platforms, the BL2 memory can be overlaid by BL31/BL32. The memory + descriptors describing the list of executable images are created in BL2 + R/W memory, which could be possibly corrupted later on by BL31/BL32 due + to overlay. This patch creates a reserved location in SRAM for these + descriptors and are copied over by BL2 before handing over to next BL + image. + + - juno: Invalid behaviour when ``CSS_USE_SCMI_SDS_DRIVER`` is not set + + In ``juno_pm.c`` the ``css_scmi_override_pm_ops`` function was used + regardless of whether the build flag was set. The original behaviour has + been restored in the case where the build flag is not set. + +- Tools + - fiptool: Incorrect UUID parsing of blob parameters + + - doimage: Incorrect object rules in Makefile + + +Deprecations +------------ + +- Common Code + - ``plat_crash_console_init`` function + + - ``plat_crash_console_putc`` function + + - ``plat_crash_console_flush`` function + + - ``finish_console_register`` macro + +- AArch64-specific Code + - helpers: ``get_afflvl_shift`` + + - helpers: ``mpidr_mask_lower_afflvls`` + + - helpers: ``eret`` + +- Secure Partition Manager (SPM) + - Boot-info structure + + +Known Issues +------------ + +- Build System Issues + - 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. + +- Platform Issues + - 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 + Trusted Firmware-A - version 2.0 ================================ @@ -1983,3 +2423,5 @@ releases of TF-A. .. _OP-TEE Dispatcher: optee-dispatcher.rst .. _tf-issue#501: https://github.com/ARM-software/tf-issues/issues/501 .. _PR#1002: https://github.com/ARM-software/arm-trusted-firmware/pull/1002#issuecomment-312650193 +.. _mbed TLS releases: https://tls.mbed.org/tech-updates/releases +.. _Firmware Design: firmware-design.rst diff --git a/docs/user-guide.rst b/docs/user-guide.rst index 5d6f4f8ed..33d7621e9 100644 --- a/docs/user-guide.rst +++ b/docs/user-guide.rst @@ -413,7 +413,7 @@ Common build options and use partitions in EL3 as required. This option defaults to ``0``. - ``ENABLE_PAUTH``: Boolean option to enable ARMv8.3 Pointer Authentication - support for TF-A BL images itself. If enabled, it is needed to use a compiler + support for TF-A BL images itself. If enabled, it is needed to use a compiler that supports the option ``-msign-return-address``. This flag defaults to 0 and this is an experimental feature. Note that Pointer Authentication is enabled for Non-secure world irrespective @@ -1014,18 +1014,13 @@ For AArch64: :: - make PLAT=fvp BL33=<path/to/bl33.bin> fip + make PLAT=fvp BL33=<path-to>/bl33.bin fip For AArch32: :: - make PLAT=fvp ARCH=aarch32 AARCH32_SP=sp_min BL33=<path/to/bl33.bin> fip - -Note that AArch32 support for Normal world boot loader (BL33), like U-boot or -UEFI, on FVP is not available upstream. Hence custom solutions are required to -allow Linux boot on FVP. These instructions assume such a custom boot loader -(BL33) is available. + make PLAT=fvp ARCH=aarch32 AARCH32_SP=sp_min BL33=<path-to>/bl33.bin fip The resulting FIP may be found in: @@ -1276,8 +1271,7 @@ section for more info on selecting the right FDT to use. make [DEBUG=1] [V=1] fiptool # Unpack firmware images from Linaro FIP - ./tools/fiptool/fiptool unpack \ - <path/to/linaro/release>/fip.bin + ./tools/fiptool/fiptool unpack <path-to-linaro-release>/fip.bin The unpack operation will result in a set of binary images extracted to the current working directory. The SCP_BL2 image corresponds to @@ -1287,8 +1281,8 @@ section for more info on selecting the right FDT to use. exist in the current directory. If that is the case, either delete those files or use the ``--force`` option to overwrite. - Note: For AArch32, the instructions below assume that nt-fw.bin is a custom - Normal world boot loader that supports AArch32. + Note: For AArch32, the instructions below assume that nt-fw.bin is a normal + world boot loader that supports AArch32. #. Build TF-A images and create a new FIP for FVP @@ -1309,9 +1303,7 @@ section for more info on selecting the right FDT to use. :: - make PLAT=juno all fip \ - BL33=<path-to-juno-oe-uboot>/SOFTWARE/bl33-uboot.bin \ - SCP_BL2=<path-to-juno-busybox-uboot>/SOFTWARE/scp_bl2.bin + make PLAT=juno BL33=nt-fw.bin SCP_BL2=scp-fw.bin all fip For AArch32: @@ -1333,6 +1325,13 @@ section for more info on selecting the right FDT to use. make ARCH=aarch32 PLAT=juno AARCH32_SP=sp_min \ RESET_TO_SP_MIN=1 JUNO_AARCH32_EL3_RUNTIME=1 bl32 + - Save ``bl32.bin`` to a temporary location and clean the build products. + + :: + + cp <path-to-build>/bl32.bin <path-to-temporary> + make realclean + - Before building BL1 and BL2, the environment variable ``CROSS_COMPILE`` must point to the AArch64 Linaro cross compiler. @@ -1346,9 +1345,8 @@ section for more info on selecting the right FDT to use. :: make ARCH=aarch64 PLAT=juno JUNO_AARCH32_EL3_RUNTIME=1 \ - BL33=<path-to-juno32-oe-uboot>/SOFTWARE/bl33-uboot.bin \ - SCP_BL2=<path-to-juno32-oe-uboot>/SOFTWARE/scp_bl2.bin \ - BL32=<path-to-bl32>/bl32.bin all fip + BL33=nt-fw.bin SCP_BL2=scp-fw.bin \ + BL32=<path-to-temporary>/bl32.bin all fip The resulting BL1 and FIP images may be found in: @@ -1504,7 +1502,7 @@ used: :: - -C bp.flashloader1.fname="/path/to/el3-payload" + -C bp.flashloader1.fname="<path-to>/<el3-payload>" On Foundation FVP, there is no flash loader component and the EL3 payload may be programmed anywhere in flash using method 3 below. @@ -1514,15 +1512,15 @@ used: :: - load /path/to/el3-payload.elf + load <path-to>/el3-payload.elf #. The EL3 payload may be pre-loaded in volatile memory using the following model parameters: :: - --data cluster0.cpu0="/path/to/el3-payload"@address [Base FVPs] - --data="/path/to/el3-payload"@address [Foundation FVP] + --data cluster0.cpu0="<path-to>/el3-payload>"@address [Base FVPs] + --data="<path-to>/<el3-payload>"@address [Foundation FVP] The address provided to the FVP must match the ``EL3_PAYLOAD_BASE`` address used when building TF-A. @@ -1650,12 +1648,10 @@ The latest version of the AArch64 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). -NOTE: Unless otherwise stated, the model version is Version 11.4 Build 37. +The FVP models used are Version 11.5 Build 33, unless otherwise stated. -- ``FVP_Base_Aresx4`` - ``FVP_Base_AEMv8A-AEMv8A`` - ``FVP_Base_AEMv8A-AEMv8A-AEMv8A-AEMv8A-CCN502`` -- ``FVP_Base_AEMv8A-AEMv8A`` - ``FVP_Base_RevC-2xAEMv8A`` - ``FVP_Base_Cortex-A32x4`` - ``FVP_Base_Cortex-A35x4`` @@ -1670,7 +1666,8 @@ NOTE: Unless otherwise stated, the model version is Version 11.4 Build 37. - ``FVP_Base_Cortex-A73x4`` - ``FVP_Base_Cortex-A75x4`` - ``FVP_Base_Cortex-A76x4`` -- ``FVP_CSS_SGI-575`` (Version 11.3 build 40) +- ``FVP_Base_Neoverse-N1x4`` (Tested with internal model) +- ``FVP_CSS_SGI-575`` (Version 11.3 build 42) - ``Foundation_Platform`` The latest version of the AArch32 build of TF-A has been tested on the following @@ -1832,6 +1829,9 @@ with 8 CPUs using the AArch64 build of TF-A. --data cluster0.cpu0="<path-to>/<kernel-binary>"@0x80080000 \ --data cluster0.cpu0="<path-to>/<ramdisk>"@0x84000000 +Note: The ``FVP_Base_RevC-2xAEMv8A`` has shifted affinities and requires a +specific DTS for all the CPUs to be loaded. + Running on the AEMv8 Base FVP (AArch32) with reset to BL1 entrypoint ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -1928,7 +1928,7 @@ with 8 CPUs using the AArch64 build of TF-A. Notes: -- Since Position Independent Executable (PIE) support is enabled for BL31 +- If Position Independent Executable (PIE) support is enabled for BL31 in this config, it can be loaded at any valid address for execution. - Since a FIP is not loaded when using BL31 as reset entrypoint, the @@ -1939,6 +1939,9 @@ Notes: and loaded via the ``--data cluster0.cpu0="<path-to>/<fdt>"@0x82000000`` parameter. +- The ``FVP_Base_RevC-2xAEMv8A`` has shifted affinities and requires a + specific DTS for all the CPUs to be loaded. + - The ``-C cluster<X>.cpu<Y>.RVBAR=@<base-address-of-bl31>`` parameter, where X and Y are the cluster and CPU numbers respectively, is used to set the reset vector for each core. @@ -2107,4 +2110,4 @@ wakeup interrupt from RTC. .. _PSCI: http://infocenter.arm.com/help/topic/com.arm.doc.den0022d/Power_State_Coordination_Interface_PDD_v1_1_DEN0022D.pdf .. _Secure Partition Manager Design guide: secure-partition-manager-design.rst .. _`Trusted Firmware-A Coding Guidelines`: coding-guidelines.rst - _`Library at ROM`: romlib-design.rst
\ No newline at end of file + _`Library at ROM`: romlib-design.rst |