From 8aa050554b996406231a66a048b56fa03ba220c8 Mon Sep 17 00:00:00 2001 From: Paul Beesley Date: Thu, 7 Mar 2019 15:47:15 +0000 Subject: [PATCH 01/11] doc: Reword document titles This patch attempts to standardise the document titles as well as adding titles to documents that were missing one. The aim is to remove needless references to "TF-A" or "Trusted Firmware" in the title of every document and to make sure that the title matches with the document content. Change-Id: I9b93ccf43b5d57e8dc793a5311b8ed7c4dd245cc Signed-off-by: Paul Beesley --- docs/acknowledgements.rst | 6 +++--- docs/change-log.rst | 4 ++-- docs/components/arm-sip-service.rst | 4 ++-- docs/components/exception-handling.rst | 7 ++----- docs/components/firmware-update.rst | 7 ++----- docs/components/platform-interrupt-controller-API.rst | 6 ++---- docs/components/ras.rst | 6 ++---- docs/components/secure-partition-manager-design.rst | 7 ++----- docs/components/xlat-tables-lib-v2-design.rst | 5 +---- docs/design/auth-framework.rst | 7 ++----- docs/design/firmware-design.rst | 7 ++----- docs/design/interrupt-framework-design.rst | 7 ++----- docs/design/psci-pd-tree.rst | 7 ++----- docs/design/reset-design.rst | 4 ++-- docs/design/trusted-board-boot.rst | 4 ++-- docs/getting_started/porting-guide.rst | 6 ++---- docs/getting_started/rt-svc-writers-guide.rst | 2 +- docs/getting_started/user-guide.rst | 7 ++----- docs/index.rst | 2 +- docs/maintainers.rst | 4 ++-- docs/process/coding-guidelines.rst | 6 ++---- docs/process/contributing.rst | 4 ++-- docs/process/index.rst | 2 +- docs/process/platform-compatibility-policy.rst | 4 ++-- docs/process/release-information.rst | 4 ++-- docs/process/{security-center.rst => security.rst} | 4 ++-- 26 files changed, 49 insertions(+), 84 deletions(-) rename docs/process/{security-center.rst => security.rst} (99%) diff --git a/docs/acknowledgements.rst b/docs/acknowledgements.rst index 095b5adbb..5f2d5bc6b 100644 --- a/docs/acknowledgements.rst +++ b/docs/acknowledgements.rst @@ -1,12 +1,12 @@ +Contributor Acknowledgements +============================ + **Note: This file is only relevant for legacy contributions, to acknowledge the specific contributors referred to in "Arm Limited and Contributors" copyright notices. As contributors are now encouraged to put their name or company name directly into the copyright notices, this file is not relevant for new contributions.** -Contributor Acknowledgements -============================ - Companies --------- diff --git a/docs/change-log.rst b/docs/change-log.rst index 6893582a3..76ec07082 100644 --- a/docs/change-log.rst +++ b/docs/change-log.rst @@ -1,5 +1,5 @@ -Trusted Firmware-A Release Notes -================================ +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. diff --git a/docs/components/arm-sip-service.rst b/docs/components/arm-sip-service.rst index 6cdac8357..9cbf19946 100644 --- a/docs/components/arm-sip-service.rst +++ b/docs/components/arm-sip-service.rst @@ -1,5 +1,5 @@ -Arm SiP Service -=============== +Arm SiP Services +================ This document enumerates and describes the Arm SiP (Silicon Provider) services. diff --git a/docs/components/exception-handling.rst b/docs/components/exception-handling.rst index e3684f133..b370c02fd 100644 --- a/docs/components/exception-handling.rst +++ b/docs/components/exception-handling.rst @@ -1,8 +1,5 @@ -Exception Handling Framework in Trusted Firmware-A -================================================== - - - +Exception Handling Framework +============================ .. contents:: :depth: 2 diff --git a/docs/components/firmware-update.rst b/docs/components/firmware-update.rst index f3ad6af1f..8124097a9 100644 --- a/docs/components/firmware-update.rst +++ b/docs/components/firmware-update.rst @@ -1,8 +1,5 @@ -Trusted Firmware-A - Firmware Update design guide -================================================= - - - +Firmware Update (FWU) +===================== .. contents:: diff --git a/docs/components/platform-interrupt-controller-API.rst b/docs/components/platform-interrupt-controller-API.rst index 42d92be2a..5c2293f09 100644 --- a/docs/components/platform-interrupt-controller-API.rst +++ b/docs/components/platform-interrupt-controller-API.rst @@ -1,7 +1,5 @@ -Platform Interrupt Controller API documentation -=============================================== - - +Platform Interrupt Controller API +================================= .. contents:: diff --git a/docs/components/ras.rst b/docs/components/ras.rst index f329fb0b2..4c16009c4 100644 --- a/docs/components/ras.rst +++ b/docs/components/ras.rst @@ -1,7 +1,5 @@ -RAS support in Trusted Firmware-A -================================= - - +Reliability, Availability, and Serviceability (RAS) Extensions +============================================================== .. contents:: :depth: 2 diff --git a/docs/components/secure-partition-manager-design.rst b/docs/components/secure-partition-manager-design.rst index 2c32eba12..91a135b98 100644 --- a/docs/components/secure-partition-manager-design.rst +++ b/docs/components/secure-partition-manager-design.rst @@ -1,8 +1,5 @@ -******************************* -Secure Partition Manager Design -******************************* - - +Secure Partition Manager +************************ .. contents:: diff --git a/docs/components/xlat-tables-lib-v2-design.rst b/docs/components/xlat-tables-lib-v2-design.rst index d55f010a3..26e4f2b9b 100644 --- a/docs/components/xlat-tables-lib-v2-design.rst +++ b/docs/components/xlat-tables-lib-v2-design.rst @@ -1,9 +1,6 @@ -Translation Tables Library Design +Translation (XLAT) Tables Library ================================= - - - .. contents:: diff --git a/docs/design/auth-framework.rst b/docs/design/auth-framework.rst index 1bc501547..dc45127f8 100644 --- a/docs/design/auth-framework.rst +++ b/docs/design/auth-framework.rst @@ -1,8 +1,5 @@ -Abstracting a Chain of Trust -============================ - - - +Authentication Framework & Chain of Trust +========================================= .. contents:: diff --git a/docs/design/firmware-design.rst b/docs/design/firmware-design.rst index e7107ba1a..d6d7b1530 100644 --- a/docs/design/firmware-design.rst +++ b/docs/design/firmware-design.rst @@ -1,8 +1,5 @@ -Trusted Firmware-A design -========================= - - - +Firmware Design +=============== .. contents:: diff --git a/docs/design/interrupt-framework-design.rst b/docs/design/interrupt-framework-design.rst index e4ec65aa1..2a641b128 100644 --- a/docs/design/interrupt-framework-design.rst +++ b/docs/design/interrupt-framework-design.rst @@ -1,8 +1,5 @@ -Trusted Firmware-A interrupt management design guide -==================================================== - - - +Interrupt Management Framework +============================== .. contents:: diff --git a/docs/design/psci-pd-tree.rst b/docs/design/psci-pd-tree.rst index 2e2163af1..23c985b6e 100644 --- a/docs/design/psci-pd-tree.rst +++ b/docs/design/psci-pd-tree.rst @@ -1,8 +1,5 @@ -PSCI Power Domain Tree design -============================= - - - +PSCI Power Domain Tree Structure +================================ .. contents:: diff --git a/docs/design/reset-design.rst b/docs/design/reset-design.rst index 147385102..405b4920d 100644 --- a/docs/design/reset-design.rst +++ b/docs/design/reset-design.rst @@ -1,5 +1,5 @@ -Trusted Firmware-A reset design -=============================== +CPU Reset +========= diff --git a/docs/design/trusted-board-boot.rst b/docs/design/trusted-board-boot.rst index ae21bf05e..76badb623 100644 --- a/docs/design/trusted-board-boot.rst +++ b/docs/design/trusted-board-boot.rst @@ -1,5 +1,5 @@ -Trusted Board Boot Design Guide -=============================== +Trusted Board Boot +================== diff --git a/docs/getting_started/porting-guide.rst b/docs/getting_started/porting-guide.rst index cad8b5c9a..f07284333 100644 --- a/docs/getting_started/porting-guide.rst +++ b/docs/getting_started/porting-guide.rst @@ -1,7 +1,5 @@ -Trusted Firmware-A Porting Guide -================================ - - +Porting Guide +============= .. contents:: diff --git a/docs/getting_started/rt-svc-writers-guide.rst b/docs/getting_started/rt-svc-writers-guide.rst index f4d786cd2..35948b547 100644 --- a/docs/getting_started/rt-svc-writers-guide.rst +++ b/docs/getting_started/rt-svc-writers-guide.rst @@ -1,4 +1,4 @@ -Trusted Firmware-A EL3 runtime service writer's guide +EL3 Runtime Service Writer's Guide ===================================================== diff --git a/docs/getting_started/user-guide.rst b/docs/getting_started/user-guide.rst index 3cc5f3cc9..894313a7f 100644 --- a/docs/getting_started/user-guide.rst +++ b/docs/getting_started/user-guide.rst @@ -1,8 +1,5 @@ -Trusted Firmware-A User Guide -============================= - - - +User Guide +========== .. contents:: diff --git a/docs/index.rst b/docs/index.rst index 8eecb3ca6..b0348f165 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -14,8 +14,8 @@ Trusted Firmware-A Documentation perf/index security_advisories/index change-log - maintainers acknowledgements + maintainers license Trusted Firmware-A (TF-A) provides a reference implementation of secure world diff --git a/docs/maintainers.rst b/docs/maintainers.rst index 0fa909fb6..5449faa20 100644 --- a/docs/maintainers.rst +++ b/docs/maintainers.rst @@ -1,5 +1,5 @@ -Trusted Firmware-A maintainers -============================== +Maintainers +=========== Trusted Firmware-A (TF-A) is an Arm maintained project. All contributions are ultimately merged by the maintainers listed below. Technical ownership of some diff --git a/docs/process/coding-guidelines.rst b/docs/process/coding-guidelines.rst index 644f82885..def5bf991 100644 --- a/docs/process/coding-guidelines.rst +++ b/docs/process/coding-guidelines.rst @@ -1,7 +1,5 @@ -Trusted Firmware-A Coding Guidelines -==================================== - - +Coding Style & Guidelines +========================= .. contents:: diff --git a/docs/process/contributing.rst b/docs/process/contributing.rst index bd950e511..8f8143f87 100644 --- a/docs/process/contributing.rst +++ b/docs/process/contributing.rst @@ -1,5 +1,5 @@ -Contributing to Trusted Firmware-A -================================== +Contributor's Guide +=================== Getting Started --------------- diff --git a/docs/process/index.rst b/docs/process/index.rst index 91f1beb2a..aa5d6bba7 100644 --- a/docs/process/index.rst +++ b/docs/process/index.rst @@ -7,7 +7,7 @@ Processes & Policies :numbered: release-information - security-center + security platform-compatibility-policy coding-guidelines contributing diff --git a/docs/process/platform-compatibility-policy.rst b/docs/process/platform-compatibility-policy.rst index e977e63a8..47b0e7e96 100644 --- a/docs/process/platform-compatibility-policy.rst +++ b/docs/process/platform-compatibility-policy.rst @@ -1,5 +1,5 @@ -TF-A Platform Compatibility Policy -================================== +Platform Compatibility Policy +============================= diff --git a/docs/process/release-information.rst b/docs/process/release-information.rst index 553115036..0b5e7d7f1 100644 --- a/docs/process/release-information.rst +++ b/docs/process/release-information.rst @@ -1,5 +1,5 @@ -TF-A Release Information -======================== +Release Processes +================= .. section-numbering:: :suffix: . diff --git a/docs/process/security-center.rst b/docs/process/security.rst similarity index 99% rename from docs/process/security-center.rst rename to docs/process/security.rst index 672c56322..b4831c822 100644 --- a/docs/process/security-center.rst +++ b/docs/process/security.rst @@ -1,5 +1,5 @@ -Security Center -=============== +Security Handling +================= Security Disclosures -------------------- From 83993177d9d34a3e6032b71147bde86d75704f4a Mon Sep 17 00:00:00 2001 From: Paul Beesley Date: Thu, 7 Mar 2019 15:53:44 +0000 Subject: [PATCH 02/11] doc: Normalise section numbering and headings Required work to make all documents sit at the correct levels within the document tree and any derived content like the table of contents and the categories in the sidebar. Change-Id: I4885fbe30864a87c8822ee67482b71fb46a8fbc6 Signed-off-by: Paul Beesley --- docs/components/romlib-design.rst | 3 --- docs/components/spd/index.rst | 1 - docs/components/spd/tlk-dispatcher.rst | 10 +++++----- docs/components/spd/trusty-dispatcher.rst | 4 ++-- docs/getting_started/image-terminology.rst | 3 --- docs/process/release-information.rst | 3 --- 6 files changed, 7 insertions(+), 17 deletions(-) diff --git a/docs/components/romlib-design.rst b/docs/components/romlib-design.rst index 41957214d..00dbf67c8 100644 --- a/docs/components/romlib-design.rst +++ b/docs/components/romlib-design.rst @@ -1,9 +1,6 @@ Library at ROM ============== -.. section-numbering:: - :suffix: . - .. contents:: This document provides an overview of the "library at ROM" implementation in diff --git a/docs/components/spd/index.rst b/docs/components/spd/index.rst index e03bfe33d..25d0124b1 100644 --- a/docs/components/spd/index.rst +++ b/docs/components/spd/index.rst @@ -4,7 +4,6 @@ Secure Payload Dispatcher (SPD) .. toctree:: :maxdepth: 1 :caption: Contents - :numbered: optee-dispatcher tlk-dispatcher diff --git a/docs/components/spd/tlk-dispatcher.rst b/docs/components/spd/tlk-dispatcher.rst index 90af5faf6..a6c658cc4 100644 --- a/docs/components/spd/tlk-dispatcher.rst +++ b/docs/components/spd/tlk-dispatcher.rst @@ -15,7 +15,7 @@ Once a BL32 is ready, TLKD can be included in the image by adding "SPD=tlkd" to the build command. Trusted Little Kernel (TLK) -=========================== +--------------------------- TLK is a Trusted OS running as Secure EL1. It is a Free Open Source Software (FOSS) release of the NVIDIA® Trusted Little Kernel (TLK) technology, which @@ -54,20 +54,20 @@ TLK and OTE can be found in the Tegra\_BSP\_for\_Android\_TLK\_FOSS\_Reference.p manual located under the "documentation" directory\_. Build TLK -========= +--------- To build and execute TLK, follow the instructions from "Building a TLK Device" section from Tegra\_BSP\_for\_Android\_TLK\_FOSS\_Reference.pdf manual. Input parameters to TLK -======================= +----------------------- TLK expects the TZDRAM size and a structure containing the boot arguments. BL2 passes this information to the EL3 software as members of the bl32\_ep\_info struct, where bl32\_ep\_info is part of bl31\_params\_t (passed by BL2 in X0) -Example: --------- +Example +~~~~~~~ :: diff --git a/docs/components/spd/trusty-dispatcher.rst b/docs/components/spd/trusty-dispatcher.rst index be085705d..a3cb8295e 100644 --- a/docs/components/spd/trusty-dispatcher.rst +++ b/docs/components/spd/trusty-dispatcher.rst @@ -9,7 +9,7 @@ Open Source Project (AOSP) webpage for Trusty hosted at https://source.android.com/security/trusty Boot parameters -=============== +--------------- Custom boot parameters can be passed to Trusty by providing a platform specific function: @@ -26,7 +26,7 @@ can be set to a platform specific parameter block, and ``args->arg2`` should then be set to the size of that block. Supported platforms -=================== +------------------- Out of all the platforms supported by Trusted Firmware-A, Trusty is only verified and supported by NVIDIA's Tegra SoCs. diff --git a/docs/getting_started/image-terminology.rst b/docs/getting_started/image-terminology.rst index 4dc1d7346..10aebf5e4 100644 --- a/docs/getting_started/image-terminology.rst +++ b/docs/getting_started/image-terminology.rst @@ -1,9 +1,6 @@ Image Terminology ================= -.. section-numbering:: - :suffix: . - .. contents:: This page contains the current name, abbreviated name and purpose of the various diff --git a/docs/process/release-information.rst b/docs/process/release-information.rst index 0b5e7d7f1..89c19ab2a 100644 --- a/docs/process/release-information.rst +++ b/docs/process/release-information.rst @@ -1,9 +1,6 @@ Release Processes ================= -.. section-numbering:: - :suffix: . - .. contents:: -------------- From 24dba2b39f880e156965237dc49a253aa196585a Mon Sep 17 00:00:00 2001 From: Paul Beesley Date: Wed, 22 May 2019 11:22:44 +0100 Subject: [PATCH 03/11] doc: Reformat platform port documents The platform port documents are not very standardised right now and they don't integrate properly into the document tree so: 1) Make sure each port has a proper name and title (incl. owner) 2) Correct use of headings, subheadings, etc in each port 3) Resolve any naming conflicts between documents Change-Id: I4c2da6f57172b7f2af3512e766ae9ce3b840b50f Signed-off-by: Paul Beesley --- docs/plat/allwinner.rst | 7 ++--- docs/plat/fvp_ve.rst | 14 +++++----- docs/plat/imx8.rst | 12 ++++---- docs/plat/imx8m.rst | 12 ++++---- docs/plat/index.rst | 2 +- docs/plat/intel-stratix10.rst | 16 ++++++----- docs/plat/ls1043a.rst | 12 ++++---- docs/plat/meson-gxbb.rst | 4 +-- docs/plat/meson-gxl.rst | 4 +-- docs/plat/mt8183.rst | 8 +++--- docs/plat/nvidia-tegra.rst | 16 +++++------ docs/plat/qemu.rst | 6 ++-- docs/plat/rcar-gen3.rst | 17 ++++++----- docs/plat/rockchip.rst | 10 +++---- docs/plat/rpi3.rst | 8 ++---- docs/plat/socionext-uniphier.rst | 5 ++-- docs/plat/stm32mp1.rst | 4 +-- docs/plat/synquacer.rst | 14 +++++----- docs/plat/ti-k3.rst | 12 ++++---- docs/plat/warp7.rst | 28 +++++++++++-------- .../{xilinx-versal.md => xilinx-versal.rst} | 8 ++++-- docs/plat/xilinx-zynqmp.rst | 10 +++---- 22 files changed, 118 insertions(+), 111 deletions(-) rename docs/plat/{xilinx-versal.md => xilinx-versal.rst} (90%) diff --git a/docs/plat/allwinner.rst b/docs/plat/allwinner.rst index 140edf511..46a5f9bf3 100644 --- a/docs/plat/allwinner.rst +++ b/docs/plat/allwinner.rst @@ -1,5 +1,5 @@ -Trusted Firmware-A for Allwinner ARMv8 SoCs -=========================================== +Allwinner ARMv8 SoCs +==================== Trusted Firmware-A (TF-A) implements the EL3 firmware layer for Allwinner SoCs with ARMv8 cores. Only BL31 is used to provide proper EL3 setup and @@ -37,11 +37,10 @@ To build for machines with an H6 SoC: .. _U-Boot documentation: http://git.denx.de/?p=u-boot.git;f=board/sunxi/README.sunxi64;hb=HEAD Trusted OS dispatcher -===================== +--------------------- One can boot Trusted OS(OP-TEE OS, bl32 image) along side bl31 image on Allwinner A64. In order to include the 'opteed' dispatcher in the image, pass 'SPD=opteed' on the command line while compiling the bl31 image and make sure the loader (SPL) loads the Trusted OS binary to the beginning of DRAM (0x40000000). - diff --git a/docs/plat/fvp_ve.rst b/docs/plat/fvp_ve.rst index c6d67c090..525386321 100644 --- a/docs/plat/fvp_ve.rst +++ b/docs/plat/fvp_ve.rst @@ -1,5 +1,5 @@ -Description -=========== +Arm Versatile Express +===================== Versatile Express (VE) family development platform provides an ultra fast environment for prototyping arm-v7 System-on-Chip designs. @@ -9,21 +9,21 @@ and Cortex-A7 VE FVP's. This platform is tested on and only expected to work with single core models. Boot Sequence -============= +------------- BL1 --> BL2 --> BL32(sp_min) --> BL33(u-boot) --> Linux kernel How to build -============ +------------ Code Locations ---------------- +~~~~~~~~~~~~~~ - `U-boot `__ - `arm-trusted-firmware `__ Build Procedure ---------------- +~~~~~~~~~~~~~~~ - Obtain arm toolchain. The software stack has been verified with linaro 6.2 `arm-linux-gnueabihf `__. @@ -68,7 +68,7 @@ Build Procedure BL33= all fip Run Procedure -------------- +~~~~~~~~~~~~~ The following model parameters should be used to boot Linux using the build of arm-trusted-firmware-a made using the above make commands: diff --git a/docs/plat/imx8.rst b/docs/plat/imx8.rst index 42409623d..49ba37412 100644 --- a/docs/plat/imx8.rst +++ b/docs/plat/imx8.rst @@ -1,5 +1,5 @@ -Description -=========== +NXP i.MX 8 Series +================= The i.MX 8 series of applications processors is a feature- and performance-scalable multi-core platform that includes single-, @@ -20,15 +20,15 @@ control for system-level resources on i.MX8. The heart of the system controller is a Cortex-M4 that executes system controller firmware. Boot Sequence -============= +------------- Bootrom --> BL31 --> BL33(u-boot) --> Linux kernel How to build -============ +------------ Build Procedure ---------------- +~~~~~~~~~~~~~~~ - Prepare AARCH64 toolchain. @@ -46,7 +46,7 @@ Build Procedure Target_SoC should be "imx8qx" for i.MX8QX SoC. Deploy TF-A Images ------------------ +~~~~~~~~~~~~~~~~~~ TF-A binary(bl31.bin), scfw_tcm.bin and u-boot.bin are combined together to generate a binary file called flash.bin, the imx-mkimage tool is used diff --git a/docs/plat/imx8m.rst b/docs/plat/imx8m.rst index a69f02227..8acd13cf7 100644 --- a/docs/plat/imx8m.rst +++ b/docs/plat/imx8m.rst @@ -1,5 +1,5 @@ -Description -=========== +NXP i.MX 8M Series +================== The i.MX 8M family of applications processors based on Arm Corte-A53 and Cortex-M4 cores provide high-performance computing, power efficiency, enhanced system @@ -7,15 +7,15 @@ reliability and embedded security needed to drive the growth of fast-growing edge node computing, streaming multimedia, and machine learning applications. Boot Sequence -============= +------------- Bootrom --> SPL --> BL31 --> BL33(u-boot) --> Linux kernel How to build -============ +------------ Build Procedure ---------------- +~~~~~~~~~~~~~~~ - Prepare AARCH64 toolchain. @@ -34,7 +34,7 @@ Build Procedure Target_SoC should be "imx8mm" for i.MX8MM SoC. Deploy TF-A Images ------------------ +~~~~~~~~~~~~~~~~~~ TF-A binary(bl31.bin), u-boot-spl.bin u-boot-nodtb.bin and dtb are combined together to generate a binary file called flash.bin, the imx-mkimage tool is diff --git a/docs/plat/index.rst b/docs/plat/index.rst index 3a917f363..595141372 100644 --- a/docs/plat/index.rst +++ b/docs/plat/index.rst @@ -16,7 +16,6 @@ Platform Ports meson-gxl mt8183 nvidia-tegra - poplar qemu rcar-gen3 rockchip @@ -26,4 +25,5 @@ Platform Ports synquacer ti-k3 warp7 + xilinx-versal xilinx-zynqmp diff --git a/docs/plat/intel-stratix10.rst b/docs/plat/intel-stratix10.rst index 9a3c89252..77a45a478 100644 --- a/docs/plat/intel-stratix10.rst +++ b/docs/plat/intel-stratix10.rst @@ -1,5 +1,5 @@ -Description -=========== +Intel Stratix 10 SoCFPGA +======================== Stratix 10 SoCFPGA is a FPGA with integrated quad-core 64-bit Arm Cortex A53 processor. @@ -11,10 +11,10 @@ the hardware, then loads bl31 and bl33 (UEFI) into DDR and boots to bl33. Boot ROM --> Trusted Firmware-A --> UEFI How to build -============ +------------ Code Locations --------------- +~~~~~~~~~~~~~~ - Trusted Firmware-A: `link `__ @@ -23,7 +23,7 @@ Code Locations `link `__ Build Procedure ---------------- +~~~~~~~~~~~~~~~ - Fetch all the above 2 repositories into local host. Make all the repositories in the same ${BUILD\_PATH}. @@ -45,7 +45,7 @@ Build Procedure BL33=PEI.ROM Install Procedure ------------------ +~~~~~~~~~~~~~~~~~ - dd fip.bin to a A2 partition on the MMC drive to be booted in Stratix 10 board. @@ -53,16 +53,18 @@ Install Procedure - Generate a SOF containing bl2 .. code:: bash + aarch64-linux-gnu-objcopy -I binary -O ihex --change-addresses 0xffe00000 bl2.bin bl2.hex quartus_cpf --bootloader bl2.hex - Configure SOF to board .. code:: bash + nios2-configure-sof Boot trace -========== +---------- :: INFO: DDR: DRAM calibration success. diff --git a/docs/plat/ls1043a.rst b/docs/plat/ls1043a.rst index 0d604aaeb..72a51f3cc 100644 --- a/docs/plat/ls1043a.rst +++ b/docs/plat/ls1043a.rst @@ -1,5 +1,5 @@ -Description -=========== +NXP QorIQ® LS1043A +================== The QorIQ® LS1043A processor is NXP's first quad-core, 64-bit Arm®-based processor for embedded networking. The LS1023A (two core version) and the @@ -36,7 +36,7 @@ UART: supports two UARTs up to 115200 bps for console More information are listed in `ls1043`_. Boot Sequence -============= +------------- Bootrom --> TF-A BL1 --> TF-A BL2 --> TF-A BL1 --> TF-A BL31 @@ -44,10 +44,10 @@ Bootrom --> TF-A BL1 --> TF-A BL2 --> TF-A BL1 --> TF-A BL31 How to build -============ +------------ Build Procedure ---------------- +~~~~~~~~~~~~~~~ - Prepare AARCH64 toolchain. @@ -69,7 +69,7 @@ Build Procedure BL33=u-boot.bin NEED_BL32=yes BL32=tee.bin SPD=opteed Deploy TF-A Images ------------------ +~~~~~~~~~~~~~~~~~~ - Deploy TF-A images on Nor flash Alt Bank. diff --git a/docs/plat/meson-gxbb.rst b/docs/plat/meson-gxbb.rst index d76149e33..cae11cd54 100644 --- a/docs/plat/meson-gxbb.rst +++ b/docs/plat/meson-gxbb.rst @@ -1,5 +1,5 @@ -Trusted Firmware-A for Amlogic Meson S905 (GXBB) -================================================ +Amlogic Meson S905 (GXBB) +========================= The Amlogic Meson S905 is a SoC with a quad core Arm Cortex-A53 running at 1.5Ghz. It also contains a Cortex-M3 used as SCP. diff --git a/docs/plat/meson-gxl.rst b/docs/plat/meson-gxl.rst index feac2dd07..3c39c9d46 100644 --- a/docs/plat/meson-gxl.rst +++ b/docs/plat/meson-gxl.rst @@ -1,5 +1,5 @@ -Trusted Firmware-A for Amlogic Meson S905x (GXL) -================================================ +Amlogic Meson S905x (GXL) +========================= The Amlogic Meson S905x is a SoC with a quad core Arm Cortex-A53 running at 1.5Ghz. It also contains a Cortex-M3 used as SCP. diff --git a/docs/plat/mt8183.rst b/docs/plat/mt8183.rst index c559e198a..c639be1ee 100644 --- a/docs/plat/mt8183.rst +++ b/docs/plat/mt8183.rst @@ -1,19 +1,19 @@ -Description -=========== +MediaTek 8183 +============= MediaTek 8183 (MT8183) is a 64-bit ARM SoC introduced by MediaTek in early 2018. The chip incorporates eight cores - four Cortex-A53 little cores and Cortex-A73. Both clusters can operate at up to 2 GHz. Boot Sequence -============= +------------- :: Boot Rom --> Coreboot --> TF-A BL31 --> Depthcharge --> Linux Kernel How to Build -============ +------------ .. code:: shell diff --git a/docs/plat/nvidia-tegra.rst b/docs/plat/nvidia-tegra.rst index 6a03b1283..bc9e35b4f 100644 --- a/docs/plat/nvidia-tegra.rst +++ b/docs/plat/nvidia-tegra.rst @@ -1,5 +1,5 @@ -Tegra SoCs - Overview -===================== +NVIDIA Tegra +============ - .. rubric:: T186 :name: t186 @@ -58,13 +58,13 @@ to extensive power-gating and dynamic voltage and clock scaling based on workloads. Directory structure -=================== +------------------- - plat/nvidia/tegra/common - Common code for all Tegra SoCs - plat/nvidia/tegra/soc/txxx - Chip specific code Trusted OS dispatcher -===================== +--------------------- Tegra supports multiple Trusted OS'. @@ -83,7 +83,7 @@ Tegra210: TLK and Trusty Tegra186: Trusty Scatter files -============= +------------- Tegra platforms currently support scatter files and ld.S scripts. The scatter files help support ARMLINK linker to generate BL31 binaries. For now, there @@ -93,7 +93,7 @@ the scatter file to be used. Tegra platforms have verified BL31 image generation with ARMCLANG (compilation) and ARMLINK (linking) for the Tegra186 platforms. Preparing the BL31 image to run on Tegra SoCs -============================================= +--------------------------------------------- .. code:: shell @@ -125,7 +125,7 @@ uint64\_t boot\_profiler\_shmem\_base; } plat\_params\_from\_bl2\_t; Power Management -================ +---------------- The PSCI implementation expects each platform to expose the 'power state' parameter to be used during the 'SYSTEM SUSPEND' call. The state-id field @@ -133,7 +133,7 @@ is implementation defined on Tegra SoCs and is preferably defined by tegra\_def.h. Tegra configs -============= +------------- - 'tegra\_enable\_l2\_ecc\_parity\_prot': This flag enables the L2 ECC and Parity Protection bit, for Arm Cortex-A57 CPUs, during CPU boot. This flag will diff --git a/docs/plat/qemu.rst b/docs/plat/qemu.rst index 57ed6293d..30ae97dda 100644 --- a/docs/plat/qemu.rst +++ b/docs/plat/qemu.rst @@ -1,5 +1,5 @@ -Trusted Firmware-A for QEMU virt Armv8-A -======================================== +QEMU virt Armv8-A +================= Trusted Firmware-A (TF-A) implements the EL3 firmware layer for QEMU virt Armv8-A. BL1 is used as the BootROM, supplied with the -bios argument. @@ -35,7 +35,7 @@ To build: :: - make CROSS_COMPILE=aarch64-none-elf- PLAT=qemu + make CROSS_COMPILE=aarch64-none-elf- PLAT=qemu To start (QEMU v2.6.0): diff --git a/docs/plat/rcar-gen3.rst b/docs/plat/rcar-gen3.rst index 84e0e6793..7107bea06 100644 --- a/docs/plat/rcar-gen3.rst +++ b/docs/plat/rcar-gen3.rst @@ -1,5 +1,5 @@ -Description -=========== +Renesas R-Car +============= "R-Car" is the nickname for Renesas' system-on-chip (SoC) family for car information systems designed for the next-generation of automotive @@ -97,14 +97,14 @@ program counters. 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 H3 SiP Salvator-X development system used in this port. Build Tested: -------------- +~~~~~~~~~~~~~ RCAR_OPT="LSI=H3 RCAR_DRAM_SPLIT=1 RCAR_LOSSY_ENABLE=1" MBEDTLS_DIR=$mbedtls_src @@ -112,7 +112,7 @@ $ MBEDTLS_DIR=$mbedtls_src_tree make clean bl2 bl31 rcar_layout_tool \ PLAT=rcar ${RCAR_OPT} SPD=opteed System Tested: --------------------- +~~~~~~~~~~~~~~ * mbed_tls: git@github.com:ARMmbed/mbedtls.git [devel] @@ -150,7 +150,7 @@ System Tested: Linux 4.19-rc4 TF-A Build Procedure --------------------- +~~~~~~~~~~~~~~~~~~~~ - Fetch all the above 4 repositories. @@ -184,7 +184,7 @@ TF-A Build Procedure make -j8 PLATFORM="rcar" CFG_ARM64_core=y Install Procedure ------------------ +~~~~~~~~~~~~~~~~~ - Boot the board in Mini-monitor mode and enable access to the Hyperflash. @@ -195,7 +195,7 @@ Install Procedure Boot trace -========== +---------- Notice that BL31 traces are not accessible via the console and that in order to verbose the BL2 output you will have to compile TF-A with @@ -266,4 +266,3 @@ LOG_LEVEL=50 and DEBUG=1 Net: eth0: ethernet@e6800000 Hit any key to stop autoboot: 0 => - diff --git a/docs/plat/rockchip.rst b/docs/plat/rockchip.rst index e88706b2f..cee35e425 100644 --- a/docs/plat/rockchip.rst +++ b/docs/plat/rockchip.rst @@ -1,5 +1,5 @@ -Trusted Firmware-A for Rockchip SoCs -==================================== +Rockchip SoCs +============= Trusted Firmware-A supports a number of Rockchip ARM SoCs from both AARCH32 and AARCH64 fields. @@ -12,7 +12,7 @@ This includes right now: Boot Sequence -============= +------------- For AARCH32: Bootrom --> BL1/BL2 --> BL32 --> BL33 --> Linux kernel @@ -26,7 +26,7 @@ BL1/2 and BL33 can currently be supplied from either: How to build -============ +------------ Rockchip SoCs expect TF-A's BL31 (AARCH64) or BL32 (AARCH32) to get integrated with other boot software like U-Boot or Coreboot, so only @@ -46,7 +46,7 @@ compilation toolchain. How to deploy -============= +------------- Both upstream U-Boot and Coreboot projects contain instructions on where to put the built images during their respective build process. diff --git a/docs/plat/rpi3.rst b/docs/plat/rpi3.rst index 122b1de61..f8b59b52f 100644 --- a/docs/plat/rpi3.rst +++ b/docs/plat/rpi3.rst @@ -1,7 +1,5 @@ -Trusted Firmware-A for Raspberry Pi 3 -===================================== - - +Raspberry Pi 3 +============== .. contents:: @@ -167,7 +165,7 @@ Secondary cores ~~~~~~~~~~~~~~~ This port of the Trusted Firmware-A supports ``PSCI_CPU_ON``, -`PSCI_SYSTEM_RESET`` and ``PSCI_SYSTEM_OFF``. The last one doesn't really turn +``PSCI_SYSTEM_RESET`` and ``PSCI_SYSTEM_OFF``. The last one doesn't really turn the system off, it simply reboots it and asks the VideoCore firmware to keep it in a low power mode permanently. diff --git a/docs/plat/socionext-uniphier.rst b/docs/plat/socionext-uniphier.rst index 37cab3b2a..82b9b503a 100644 --- a/docs/plat/socionext-uniphier.rst +++ b/docs/plat/socionext-uniphier.rst @@ -1,6 +1,5 @@ -Trusted Firmware-A for Socionext UniPhier SoCs -============================================== - +Socionext UniPhier +================== Socionext UniPhier Armv8-A SoCs use Trusted Firmware-A (TF-A) as the secure world firmware, supporting BL2 and BL31. diff --git a/docs/plat/stm32mp1.rst b/docs/plat/stm32mp1.rst index 1cfdb8453..7adc3c870 100644 --- a/docs/plat/stm32mp1.rst +++ b/docs/plat/stm32mp1.rst @@ -1,5 +1,5 @@ -Trusted Firmware-A for STM32MP1 -=============================== +STMicroelectronics STM32MP1 +=========================== STM32MP1 is a microprocessor designed by STMicroelectronics based on a dual Arm Cortex-A7. diff --git a/docs/plat/synquacer.rst b/docs/plat/synquacer.rst index ca53deb52..dd29d29da 100644 --- a/docs/plat/synquacer.rst +++ b/docs/plat/synquacer.rst @@ -1,5 +1,5 @@ -Trusted Firmware-A for Socionext Synquacer SoCs -=============================================== +Socionext Synquacer +=================== Socionext's Synquacer SC2A11 is a multi-core processor with 24 cores of Arm Cortex-A53. The Developerbox, of 96boards, is a platform that contains this @@ -9,10 +9,10 @@ the moment. More information are listed in `link`_. How to build -============ +------------ Code Locations --------------- +~~~~~~~~~~~~~~ - Trusted Firmware-A: `link `__ @@ -27,12 +27,12 @@ Code Locations `link `__ Boot Flow ---------- +~~~~~~~~~ SCP firmware --> TF-A BL31 --> UEFI(edk2) Build Procedure ---------------- +~~~~~~~~~~~~~~~ - Firstly, in addition to the “normal” build tools you will also need a few specialist tools. On a Debian or Ubuntu operating system try: @@ -98,7 +98,7 @@ Build Procedure Note #2: Replace -b RELEASE with -b DEBUG to build a debug. Install the System Firmware ---------------------------- +~~~~~~~~~~~~~~~~~~~~~~~~~~~ - Providing your Developerbox is fully working and has on operating system installed then you can adopt your the newly compiled system firmware using diff --git a/docs/plat/ti-k3.rst b/docs/plat/ti-k3.rst index 6515c644d..4843227df 100644 --- a/docs/plat/ti-k3.rst +++ b/docs/plat/ti-k3.rst @@ -1,15 +1,17 @@ -Trusted Firmware-A for Texas Instruments K3 SoCs -================================================ +Texas Instruments K3 +==================== Trusted Firmware-A (TF-A) implements the EL3 firmware layer for Texas Instruments K3 SoCs. Boot Flow --------- -R5(U-Boot) --> TF-A BL31 --> BL32(OP-TEE) --> TF-A BL31 --> BL33(U-Boot) --> Linux +:: + + R5(U-Boot) --> TF-A BL31 --> BL32(OP-TEE) --> TF-A BL31 --> BL33(U-Boot) --> Linux \ - Optional direct to Linux boot - \ + Optional direct to Linux boot + \ --> BL33(Linux) Texas Instruments K3 SoCs contain an R5 processor used as the boot master, it diff --git a/docs/plat/warp7.rst b/docs/plat/warp7.rst index 6c04d91ec..f98a76faf 100644 --- a/docs/plat/warp7.rst +++ b/docs/plat/warp7.rst @@ -1,5 +1,5 @@ -Trusted Firmware-A for i.MX7 WaRP7 -================================== +NXP i.MX7 WaRP7 +=============== The Trusted Firmware-A port for the i.MX7Solo WaRP7 implements BL2 at EL3. The i.MX7S contains a BootROM with a High Assurance Boot (HAB) functionality. @@ -7,21 +7,23 @@ This functionality provides a mechanism for establishing a root-of-trust from the reset vector to the command-line in user-space. Boot Flow -========= +--------- BootROM --> TF-A BL2 --> BL32(OP-TEE) --> BL33(U-Boot) --> Linux In the WaRP7 port we encapsulate OP-TEE, DTB and U-Boot into a FIP. This FIP is expected and required -# Build Instructions +Build Instructions +------------------ We need to use a file generated by u-boot in order to generate a .imx image the BootROM will boot. It is therefore _required_ to build u-boot before TF-A and furthermore it is _recommended_ to use the mkimage in the u-boot/tools directory to generate the TF-A .imx image. -## U-Boot: +U-Boot +~~~~~~ https://git.linaro.org/landing-teams/working/mbl/u-boot.git @@ -31,7 +33,8 @@ https://git.linaro.org/landing-teams/working/mbl/u-boot.git make warp7_bl33_defconfig; make u-boot.imx arch=ARM CROSS_COMPILE=arm-linux-gnueabihf- -## OP-TEE: +OP-TEE +~~~~~~ https://github.com/OP-TEE/optee_os.git @@ -39,7 +42,8 @@ https://github.com/OP-TEE/optee_os.git make ARCH=arm CROSS_COMPILE=arm-linux-gnueabihf- PLATFORM=imx PLATFORM_FLAVOR=mx7swarp7 ARCH=arm CFG_PAGEABLE_ADDR=0 CFG_DT_ADDR=0x83000000 CFG_NS_ENTRY_ADDR=0x87800000 -## TF-A: +TF-A +~~~~ https://github.com/ARM-software/arm-trusted-firmware.git @@ -75,7 +79,8 @@ It is also assumed copy of mbedtls is available on the path path ../mbedtls /path/to/u-boot/tools/mkimage -n /path/to/u-boot/u-boot.cfgout -T imximage -e 0x9df00000 -d ./build/warp7/debug/bl2.bin ./build/warp7/debug/bl2.bin.imx -## FIP: +FIP +~~~ .. code:: shell @@ -110,8 +115,8 @@ It is also assumed copy of mbedtls is available on the path path ../mbedtls --trusted-key-cert fiptool_images/trusted-key-cert.key-crt \ --tb-fw-cert fiptool_images/trusted-boot-fw.key-crt warp7.fip -# Deploy Images - +Deploy Images +------------- First place the WaRP7 into UMS mode in u-boot this should produce an entry in /dev like /dev/disk/by-id/usb-Linux_UMS_disk_0_WaRP7-0xf42400d3000001d4-0\:0 @@ -138,7 +143,8 @@ Remember to umount the USB device pefore proceeding sudo umount /dev/disk/by-id/usb-Linux_UMS_disk_0_WaRP7-0xf42400d3000001d4-0\:0* -# Signing BL2 +Signing BL2 +----------- A further step is to sign BL2. diff --git a/docs/plat/xilinx-versal.md b/docs/plat/xilinx-versal.rst similarity index 90% rename from docs/plat/xilinx-versal.md rename to docs/plat/xilinx-versal.rst index c84014c39..231286e7e 100644 --- a/docs/plat/xilinx-versal.md +++ b/docs/plat/xilinx-versal.rst @@ -1,5 +1,5 @@ -Trusted Firmware-A for Xilinx Versal -================================ +Xilinx Versal +============= Trusted Firmware-A implements the EL3 firmware layer for Xilinx Versal. The platform only uses the runtime part of TF-A as Xilinx Versal already has a @@ -19,7 +19,9 @@ To build ATF for different platform (for now its just versal virtual "versal_vir make RESET_TO_BL31=1 CROSS_COMPILE=aarch64-none-elf- PLAT=versal VERSAL_PLATFORM=versal_virt bl31 ``` -# Xilinx Versal platform specific build options +Xilinx Versal platform specific build options +--------------------------------------------- + * `VERSAL_ATF_MEM_BASE`: Specifies the base address of the bl31 binary. * `VERSAL_ATF_MEM_SIZE`: Specifies the size of the memory region of the bl31 binary. * `VERSAL_BL32_MEM_BASE`: Specifies the base address of the bl32 binary. diff --git a/docs/plat/xilinx-zynqmp.rst b/docs/plat/xilinx-zynqmp.rst index 2b48ba92d..5db4488a0 100644 --- a/docs/plat/xilinx-zynqmp.rst +++ b/docs/plat/xilinx-zynqmp.rst @@ -1,5 +1,5 @@ -Trusted Firmware-A for Xilinx Zynq UltraScale+ MPSoC -==================================================== +Xilinx Zynq UltraScale+ MPSoC +============================= Trusted Firmware-A (TF-A) implements the EL3 firmware layer for Xilinx Zynq UltraScale + MPSoC. @@ -23,7 +23,7 @@ To build bl32 TSP you have to rebuild bl31 too: make CROSS_COMPILE=aarch64-none-elf- PLAT=zynqmp SPD=tspd bl31 bl32 ZynqMP platform specific build options -====================================== +-------------------------------------- - ``ZYNQMP_ATF_MEM_BASE``: Specifies the base address of the bl31 binary. - ``ZYNQMP_ATF_MEM_SIZE``: Specifies the size of the memory region of the bl31 binary. @@ -36,7 +36,7 @@ ZynqMP platform specific build options - ``cadence1`` : Cadence UART 1 FSBL->TF-A Parameter Passing -=========================== +---------------------------- The FSBL populates a data structure with image information for TF-A. TF-A uses that data to hand off to the loaded images. The address of the handoff data @@ -45,7 +45,7 @@ register is free to be used by other software once TF-A has brought up further firmware images. Power Domain Tree -================= +----------------- The following power domain tree represents the power domain model used by TF-A for ZynqMP: From 267f8085f25046406db2676fb2770a702ccf1243 Mon Sep 17 00:00:00 2001 From: Paul Beesley Date: Thu, 7 Mar 2019 16:22:44 +0000 Subject: [PATCH 04/11] doc: Format security advisory titles and headings Required so that the advisory documents are all valid RST files (with a header) and that they all integrate into the document tree. Change-Id: I68ca2b0b9e648e24b460deb772c471a38518da26 Signed-off-by: Paul Beesley --- docs/security_advisories/security-advisory-tfv-1.rst | 3 +++ docs/security_advisories/security-advisory-tfv-2.rst | 3 +++ docs/security_advisories/security-advisory-tfv-3.rst | 3 +++ docs/security_advisories/security-advisory-tfv-4.rst | 3 +++ docs/security_advisories/security-advisory-tfv-5.rst | 3 +++ docs/security_advisories/security-advisory-tfv-6.rst | 9 ++++++--- docs/security_advisories/security-advisory-tfv-7.rst | 7 +++++-- docs/security_advisories/security-advisory-tfv-8.rst | 3 +++ 8 files changed, 29 insertions(+), 5 deletions(-) diff --git a/docs/security_advisories/security-advisory-tfv-1.rst b/docs/security_advisories/security-advisory-tfv-1.rst index e3d1984b0..9d58d083c 100644 --- a/docs/security_advisories/security-advisory-tfv-1.rst +++ b/docs/security_advisories/security-advisory-tfv-1.rst @@ -1,3 +1,6 @@ +Advisory TFV-1 (CVE-2016-10319) +=============================== + +----------------+-------------------------------------------------------------+ | Title | Malformed Firmware Update SMC can result in copy of | | | unexpectedly large data into secure memory | diff --git a/docs/security_advisories/security-advisory-tfv-2.rst b/docs/security_advisories/security-advisory-tfv-2.rst index db4745854..0ed2a7fb7 100644 --- a/docs/security_advisories/security-advisory-tfv-2.rst +++ b/docs/security_advisories/security-advisory-tfv-2.rst @@ -1,3 +1,6 @@ +Advisory TFV-2 (CVE-2017-7564) +============================== + +----------------+-------------------------------------------------------------+ | Title | Enabled secure self-hosted invasive debug interface can | | | allow normal world to panic secure world | diff --git a/docs/security_advisories/security-advisory-tfv-3.rst b/docs/security_advisories/security-advisory-tfv-3.rst index 28e10bff2..f74ef1712 100644 --- a/docs/security_advisories/security-advisory-tfv-3.rst +++ b/docs/security_advisories/security-advisory-tfv-3.rst @@ -1,3 +1,6 @@ +Advisory TFV-3 (CVE-2017-7563) +============================== + +----------------+-------------------------------------------------------------+ | Title | RO memory is always executable at AArch64 Secure EL1 | +================+=============================================================+ diff --git a/docs/security_advisories/security-advisory-tfv-4.rst b/docs/security_advisories/security-advisory-tfv-4.rst index 386d0da07..66dd54258 100644 --- a/docs/security_advisories/security-advisory-tfv-4.rst +++ b/docs/security_advisories/security-advisory-tfv-4.rst @@ -1,3 +1,6 @@ +Advisory TFV-4 (CVE-2017-9607) +============================== + +----------------+-------------------------------------------------------------+ | Title | Malformed Firmware Update SMC can result in copy or | | | authentication of unexpected data in secure memory in | diff --git a/docs/security_advisories/security-advisory-tfv-5.rst b/docs/security_advisories/security-advisory-tfv-5.rst index 4479bf027..2214f2d50 100644 --- a/docs/security_advisories/security-advisory-tfv-5.rst +++ b/docs/security_advisories/security-advisory-tfv-5.rst @@ -1,3 +1,6 @@ +Advisory TFV-5 (CVE-2017-15031) +=============================== + +----------------+-------------------------------------------------------------+ | Title | Not initializing or saving/restoring ``PMCR_EL0`` can leak | | | secure world timing information | diff --git a/docs/security_advisories/security-advisory-tfv-6.rst b/docs/security_advisories/security-advisory-tfv-6.rst index 7b556d8e8..f968262c2 100644 --- a/docs/security_advisories/security-advisory-tfv-6.rst +++ b/docs/security_advisories/security-advisory-tfv-6.rst @@ -1,3 +1,6 @@ +Advisory TFV-6 (CVE-2017-5753, CVE-2017-5715, CVE-2017-5754) +============================================================ + +----------------+-------------------------------------------------------------+ | Title | Arm Trusted Firmware exposure to speculative processor | | | vulnerabilities using cache timing side-channels | @@ -28,13 +31,13 @@ these vulnerabilities on Arm systems, please refer to the `Arm Processor Security Update`_. Variant 1 (`CVE-2017-5753`_) -~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +---------------------------- At the time of writing, no vulnerable patterns have been observed in upstream TF code, therefore no workarounds have been applied or are planned. Variant 2 (`CVE-2017-5715`_) -~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +---------------------------- Where possible on vulnerable CPUs, Arm recommends invalidating the branch predictor as early as possible on entry into the secure world, before any branch @@ -122,7 +125,7 @@ Cortex-A76, Cortex-A53, Cortex-A55, Cortex-A32, Cortex-A7 and Cortex-A5. For more information about non-Arm CPUs, please contact the CPU vendor. Variant 3 (`CVE-2017-5754`_) -~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +---------------------------- This variant is only exploitable between Exception Levels within the same translation regime, for example between EL0 and EL1, therefore this variant diff --git a/docs/security_advisories/security-advisory-tfv-7.rst b/docs/security_advisories/security-advisory-tfv-7.rst index 572268aae..8e06762c7 100644 --- a/docs/security_advisories/security-advisory-tfv-7.rst +++ b/docs/security_advisories/security-advisory-tfv-7.rst @@ -1,3 +1,6 @@ +Advisory TFV-7 (CVE-2018-3639) +============================== + +----------------+-------------------------------------------------------------+ | Title | Trusted Firmware-A exposure to cache speculation | | | vulnerability Variant 4 | @@ -46,7 +49,7 @@ for platforms that are unaffected or where the risk is deemed low enough. Arm CPUs not mentioned below are unaffected. Static mitigation -~~~~~~~~~~~~~~~~~ +----------------- For affected CPUs, this approach enables the mitigation during EL3 initialization, following every PE reset. No mechanism is provided to disable @@ -67,7 +70,7 @@ TF-A implements this approach for the following affected CPUs: (``S3_0_C15_C1_0``). Dynamic mitigation -~~~~~~~~~~~~~~~~~~ +------------------ For affected CPUs, this approach also enables the mitigation during EL3 initialization, following every PE reset. In addition, this approach implements diff --git a/docs/security_advisories/security-advisory-tfv-8.rst b/docs/security_advisories/security-advisory-tfv-8.rst index eacdc7bcd..5a5ef7cb1 100644 --- a/docs/security_advisories/security-advisory-tfv-8.rst +++ b/docs/security_advisories/security-advisory-tfv-8.rst @@ -1,3 +1,6 @@ +Advisory TFV-8 (CVE-2018-19440) +=============================== + +----------------+-------------------------------------------------------------+ | Title | Not saving x0 to x3 registers can leak information from one | | | Normal World SMC client to another | From 1ef35512cff8268d518fb15eace03f03f5fb6d6b Mon Sep 17 00:00:00 2001 From: Paul Beesley Date: Thu, 7 Mar 2019 16:42:31 +0000 Subject: [PATCH 05/11] doc: Make checkpatch ignore rst files Previously checkpatch was invoked with options to make it ignore Markdown (md) files as this was the dominant format for TF-A documents. Now that rst is being used everywhere this option needs updating. Change-Id: I59b5a0bcc45d2386df4f880b8d333baef0bbee77 Signed-off-by: Paul Beesley --- Makefile | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/Makefile b/Makefile index 16b4ccc42..976f514dd 100644 --- a/Makefile +++ b/Makefile @@ -55,7 +55,7 @@ ROOT_DIRS_TO_CHECK := $(sort $(filter-out \ lib \ include \ docs \ - %.md, \ + %.rst, \ $(wildcard *))) CHECK_PATHS := ${ROOT_DIRS_TO_CHECK} \ ${INC_DIRS_TO_CHECK} \ @@ -815,7 +815,7 @@ realclean distclean: checkcodebase: locate-checkpatch @echo " CHECKING STYLE" @if test -d .git ; then \ - git ls-files | grep -E -v 'libfdt|libc|docs|\.md' | \ + git ls-files | grep -E -v 'libfdt|libc|docs|\.rst' | \ while read GIT_FILE ; \ do ${CHECKPATCH} ${CHECKCODE_ARGS} -f $$GIT_FILE ; \ done ; \ @@ -825,7 +825,7 @@ checkcodebase: locate-checkpatch -not -iwholename "*libfdt*" \ -not -iwholename "*libc*" \ -not -iwholename "*docs*" \ - -not -iwholename "*.md" \ + -not -iwholename "*.rst" \ -exec ${CHECKPATCH} ${CHECKCODE_ARGS} -f {} \; ; \ fi From 57354abb2032b4598ce513d5d1ca788fe3bcf356 Mon Sep 17 00:00:00 2001 From: Paul Beesley Date: Thu, 7 Mar 2019 17:03:22 +0000 Subject: [PATCH 06/11] doc: Remove per-page contents lists These are no longer needed as there will always be a table of contents rendered to the left of every page. Some of these lists can be quite long and, when opening a page, the reader sees nothing but a huge list of contents! After this patch, the document contents are front-and-centre and the contents are nicely rendered in the sidebar without duplication. Change-Id: I444754d548ec91d00f2b04e861de8dde8856aa62 Signed-off-by: Paul Beesley --- docs/change-log.rst | 2 -- docs/components/exception-handling.rst | 3 --- docs/components/firmware-update.rst | 4 ---- docs/components/platform-interrupt-controller-API.rst | 2 -- docs/components/ras.rst | 3 --- docs/components/romlib-design.rst | 2 -- docs/components/sdei.rst | 3 --- docs/components/secure-partition-manager-design.rst | 2 -- docs/components/xlat-tables-lib-v2-design.rst | 3 --- docs/design/auth-framework.rst | 2 -- docs/design/cpu-specific-build-macros.rst | 5 ----- docs/design/firmware-design.rst | 2 -- docs/design/interrupt-framework-design.rst | 2 -- docs/design/psci-pd-tree.rst | 4 ---- docs/design/reset-design.rst | 5 ----- docs/design/trusted-board-boot.rst | 5 ----- docs/getting_started/image-terminology.rst | 2 -- docs/getting_started/porting-guide.rst | 2 -- docs/getting_started/psci-lib-integration-guide.rst | 4 ---- docs/getting_started/rt-svc-writers-guide.rst | 4 ---- docs/getting_started/user-guide.rst | 2 -- docs/index.rst | 5 ++++- docs/plat/rpi3.rst | 2 -- docs/process/coding-guidelines.rst | 2 -- docs/process/platform-compatibility-policy.rst | 7 ------- docs/process/release-information.rst | 4 ---- 26 files changed, 4 insertions(+), 79 deletions(-) diff --git a/docs/change-log.rst b/docs/change-log.rst index 76ec07082..1b6a481f9 100644 --- a/docs/change-log.rst +++ b/docs/change-log.rst @@ -4,8 +4,6 @@ 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. -.. contents:: - Version 2.1 ----------- diff --git a/docs/components/exception-handling.rst b/docs/components/exception-handling.rst index b370c02fd..2452e06a5 100644 --- a/docs/components/exception-handling.rst +++ b/docs/components/exception-handling.rst @@ -1,9 +1,6 @@ Exception Handling Framework ============================ -.. contents:: - :depth: 2 - .. |EHF| replace:: Exception Handling Framework .. |TF-A| replace:: Trusted Firmware-A diff --git a/docs/components/firmware-update.rst b/docs/components/firmware-update.rst index 8124097a9..608803d57 100644 --- a/docs/components/firmware-update.rst +++ b/docs/components/firmware-update.rst @@ -1,10 +1,6 @@ Firmware Update (FWU) ===================== -.. contents:: - --------------- - Introduction ------------ diff --git a/docs/components/platform-interrupt-controller-API.rst b/docs/components/platform-interrupt-controller-API.rst index 5c2293f09..7890cd38f 100644 --- a/docs/components/platform-interrupt-controller-API.rst +++ b/docs/components/platform-interrupt-controller-API.rst @@ -1,8 +1,6 @@ Platform Interrupt Controller API ================================= -.. contents:: - This document lists the optional platform interrupt controller API that abstracts the runtime configuration and control of interrupt controller from the generic code. The mandatory APIs are described in the `porting guide`__. diff --git a/docs/components/ras.rst b/docs/components/ras.rst index 4c16009c4..9d56e63a5 100644 --- a/docs/components/ras.rst +++ b/docs/components/ras.rst @@ -1,9 +1,6 @@ Reliability, Availability, and Serviceability (RAS) Extensions ============================================================== -.. contents:: - :depth: 2 - .. |EHF| replace:: Exception Handling Framework .. |TF-A| replace:: Trusted Firmware-A diff --git a/docs/components/romlib-design.rst b/docs/components/romlib-design.rst index 00dbf67c8..9f62b7c45 100644 --- a/docs/components/romlib-design.rst +++ b/docs/components/romlib-design.rst @@ -1,8 +1,6 @@ Library at ROM ============== -.. contents:: - This document provides an overview of the "library at ROM" implementation in Trusted Firmware-A (TF-A). diff --git a/docs/components/sdei.rst b/docs/components/sdei.rst index aca1ccb06..8c0878976 100644 --- a/docs/components/sdei.rst +++ b/docs/components/sdei.rst @@ -1,9 +1,6 @@ SDEI: Software Delegated Exception Interface ============================================ -.. contents:: - :depth: 2 - This document provides an overview of the SDEI dispatcher implementation in Trusted Firmware-A (TF-A). diff --git a/docs/components/secure-partition-manager-design.rst b/docs/components/secure-partition-manager-design.rst index 91a135b98..31276cd76 100644 --- a/docs/components/secure-partition-manager-design.rst +++ b/docs/components/secure-partition-manager-design.rst @@ -1,8 +1,6 @@ Secure Partition Manager ************************ -.. contents:: - Background ========== diff --git a/docs/components/xlat-tables-lib-v2-design.rst b/docs/components/xlat-tables-lib-v2-design.rst index 26e4f2b9b..a78d35116 100644 --- a/docs/components/xlat-tables-lib-v2-design.rst +++ b/docs/components/xlat-tables-lib-v2-design.rst @@ -1,9 +1,6 @@ Translation (XLAT) Tables Library ================================= -.. contents:: - - This document describes the design of the translation tables library (version 2) used by Trusted Firmware-A (TF-A). This library provides APIs to create page tables based on a description of the memory layout, as well as setting up system diff --git a/docs/design/auth-framework.rst b/docs/design/auth-framework.rst index dc45127f8..49f0def5e 100644 --- a/docs/design/auth-framework.rst +++ b/docs/design/auth-framework.rst @@ -1,8 +1,6 @@ Authentication Framework & Chain of Trust ========================================= -.. contents:: - The aim of this document is to describe the authentication framework implemented in Trusted Firmware-A (TF-A). This framework fulfills the following requirements: diff --git a/docs/design/cpu-specific-build-macros.rst b/docs/design/cpu-specific-build-macros.rst index d099ebe26..e49c73e7b 100644 --- a/docs/design/cpu-specific-build-macros.rst +++ b/docs/design/cpu-specific-build-macros.rst @@ -1,11 +1,6 @@ Arm CPU Specific Build Macros ============================= - - - -.. contents:: - This document describes the various build options present in the CPU specific operations framework to enable errata workarounds and to enable optimizations for a specific CPU on a platform. diff --git a/docs/design/firmware-design.rst b/docs/design/firmware-design.rst index d6d7b1530..27d09480a 100644 --- a/docs/design/firmware-design.rst +++ b/docs/design/firmware-design.rst @@ -1,8 +1,6 @@ Firmware Design =============== -.. contents:: - Trusted Firmware-A (TF-A) implements a subset of the Trusted Board Boot Requirements (TBBR) Platform Design Document (PDD) [1]_ for Arm reference platforms. The TBB sequence starts when the platform is powered on and runs up diff --git a/docs/design/interrupt-framework-design.rst b/docs/design/interrupt-framework-design.rst index 2a641b128..6f692b2f1 100644 --- a/docs/design/interrupt-framework-design.rst +++ b/docs/design/interrupt-framework-design.rst @@ -1,8 +1,6 @@ Interrupt Management Framework ============================== -.. contents:: - This framework is responsible for managing interrupts routed to EL3. It also allows EL3 software to configure the interrupt routing behavior. Its main objective is to implement the following two requirements. diff --git a/docs/design/psci-pd-tree.rst b/docs/design/psci-pd-tree.rst index 23c985b6e..e52da77c6 100644 --- a/docs/design/psci-pd-tree.rst +++ b/docs/design/psci-pd-tree.rst @@ -1,10 +1,6 @@ PSCI Power Domain Tree Structure ================================ -.. contents:: - --------------- - Requirements ------------ diff --git a/docs/design/reset-design.rst b/docs/design/reset-design.rst index 405b4920d..c38f62748 100644 --- a/docs/design/reset-design.rst +++ b/docs/design/reset-design.rst @@ -1,11 +1,6 @@ CPU Reset ========= - - - -.. contents:: - This document describes the high-level design of the framework to handle CPU resets in Trusted Firmware-A (TF-A). It also describes how the platform integrator can tailor this code to the system configuration to some extent, diff --git a/docs/design/trusted-board-boot.rst b/docs/design/trusted-board-boot.rst index 76badb623..dbe2f2aa4 100644 --- a/docs/design/trusted-board-boot.rst +++ b/docs/design/trusted-board-boot.rst @@ -1,11 +1,6 @@ Trusted Board Boot ================== - - - -.. contents:: - The Trusted Board Boot (TBB) feature prevents malicious firmware from running on the platform by authenticating all firmware images up to and including the normal world bootloader. It does this by establishing a Chain of Trust using diff --git a/docs/getting_started/image-terminology.rst b/docs/getting_started/image-terminology.rst index 10aebf5e4..d9e08f76c 100644 --- a/docs/getting_started/image-terminology.rst +++ b/docs/getting_started/image-terminology.rst @@ -1,8 +1,6 @@ Image Terminology ================= -.. contents:: - This page contains the current name, abbreviated name and purpose of the various images referred to in the Trusted Firmware project. diff --git a/docs/getting_started/porting-guide.rst b/docs/getting_started/porting-guide.rst index f07284333..458615ec3 100644 --- a/docs/getting_started/porting-guide.rst +++ b/docs/getting_started/porting-guide.rst @@ -1,8 +1,6 @@ Porting Guide ============= -.. contents:: - Introduction ------------ diff --git a/docs/getting_started/psci-lib-integration-guide.rst b/docs/getting_started/psci-lib-integration-guide.rst index c8cf3f393..f5ea0d78b 100644 --- a/docs/getting_started/psci-lib-integration-guide.rst +++ b/docs/getting_started/psci-lib-integration-guide.rst @@ -1,10 +1,6 @@ PSCI Library Integration guide for Armv8-A AArch32 systems ========================================================== - - -.. contents:: - This document describes the PSCI library interface with a focus on how to integrate with a suitable Trusted OS for an Armv8-A AArch32 system. The PSCI Library implements the PSCI Standard as described in `PSCI spec`_ and is meant diff --git a/docs/getting_started/rt-svc-writers-guide.rst b/docs/getting_started/rt-svc-writers-guide.rst index 35948b547..559d701a3 100644 --- a/docs/getting_started/rt-svc-writers-guide.rst +++ b/docs/getting_started/rt-svc-writers-guide.rst @@ -1,10 +1,6 @@ EL3 Runtime Service Writer's Guide ===================================================== - - -.. contents:: - Introduction ------------ diff --git a/docs/getting_started/user-guide.rst b/docs/getting_started/user-guide.rst index 894313a7f..a4aa1a791 100644 --- a/docs/getting_started/user-guide.rst +++ b/docs/getting_started/user-guide.rst @@ -1,8 +1,6 @@ User Guide ========== -.. contents:: - This document describes how to build Trusted Firmware-A (TF-A) and run it with a tested set of other software components using defined configurations on the Juno Arm development platform and Arm Fixed Virtual Platform (FVP) models. It is diff --git a/docs/index.rst b/docs/index.rst index b0348f165..f23b948d0 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -3,7 +3,7 @@ Trusted Firmware-A Documentation .. toctree:: :maxdepth: 1 - :caption: Contents + :hidden: Home getting_started/index @@ -18,6 +18,9 @@ Trusted Firmware-A Documentation maintainers license +.. contents:: On This Page + :depth: 3 + Trusted Firmware-A (TF-A) provides a reference implementation of secure world software for `Armv7-A and Armv8-A`_, including a `Secure Monitor`_ executing at Exception Level 3 (EL3). It implements various Arm interface standards, diff --git a/docs/plat/rpi3.rst b/docs/plat/rpi3.rst index f8b59b52f..d155fcbfb 100644 --- a/docs/plat/rpi3.rst +++ b/docs/plat/rpi3.rst @@ -1,8 +1,6 @@ Raspberry Pi 3 ============== -.. contents:: - The `Raspberry Pi 3`_ is an inexpensive single-board computer that contains four Arm Cortex-A53 cores. diff --git a/docs/process/coding-guidelines.rst b/docs/process/coding-guidelines.rst index def5bf991..856882b5f 100644 --- a/docs/process/coding-guidelines.rst +++ b/docs/process/coding-guidelines.rst @@ -1,8 +1,6 @@ Coding Style & Guidelines ========================= -.. contents:: - 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. diff --git a/docs/process/platform-compatibility-policy.rst b/docs/process/platform-compatibility-policy.rst index 47b0e7e96..1c80eb562 100644 --- a/docs/process/platform-compatibility-policy.rst +++ b/docs/process/platform-compatibility-policy.rst @@ -1,13 +1,6 @@ Platform Compatibility Policy ============================= - - - -.. contents:: - --------------- - Introduction ------------ diff --git a/docs/process/release-information.rst b/docs/process/release-information.rst index 89c19ab2a..b81d42d59 100644 --- a/docs/process/release-information.rst +++ b/docs/process/release-information.rst @@ -1,10 +1,6 @@ Release Processes ================= -.. contents:: - --------------- - Project Release Cadence ----------------------- From 8f62ca7b3060b87ede0a55c1972e5d2146a23890 Mon Sep 17 00:00:00 2001 From: Paul Beesley Date: Wed, 13 Mar 2019 13:58:02 +0000 Subject: [PATCH 07/11] doc: Add minimal glossary One of the current issues with the documentation is that terms and abbreviations are frequently redefined. For example, we might have a sentence like "... the SCP (System Control Processor) will ...". These definitions might be repeated several times across pages, or even within the same document. Equally, some of these abbreviations are missed and are never expanded. Sphinx provides a :term: keyword that takes some text and, if that text is defined in a glossary document, links to its glossary entry. Using this functionality will prevent repeated definitions and will make the docs more maintainable by using a single definition source. The glossary added in this patch was created from a quick scrub of the source code - there may be missing entries. The SDEI abbreviation was used as an example. Note that a global_substitutions file was created. This file contains the RST 'replace' statements that convert plain text terms into linked terms (by adding the ':term:' keyword to them). An example is: .. |TF-A| replace:: :term:`TF-A` The 'rst_prolog' variable in conf.py is used to inject this list of replacements into each page. Terms must be surrounded with the pipe character to be turned into links - this means that we can still prevent certain terms from being linked if we don't want them to be. Change-Id: I87010ed9cfa4a60011a9b4a431b98cb4bb7baa28 Signed-off-by: Paul Beesley --- docs/change-log.rst | 14 +- docs/components/exception-handling.rst | 21 ++- docs/conf.py | 7 +- docs/getting_started/porting-guide.rst | 33 ++--- docs/global_substitutions.txt | 55 ++++++++ docs/glossary.rst | 177 +++++++++++++++++++++++++ docs/index.rst | 3 +- 7 files changed, 273 insertions(+), 37 deletions(-) create mode 100644 docs/global_substitutions.txt create mode 100644 docs/glossary.rst diff --git a/docs/change-log.rst b/docs/change-log.rst index 1b6a481f9..bbd7feca9 100644 --- a/docs/change-log.rst +++ b/docs/change-log.rst @@ -294,12 +294,12 @@ Changed - SDEI - Added support for unconditionally resuming secure world execution after - SDEI event processing completes + |SDEI| event processing completes - SDEI interrupts, although targeting EL3, occur on behalf of the non-secure + |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 + execution to the non-secure |SDEI| handler. Upon completion of |SDEI| event handling, resume secure execution if it was preempted. - Translation Tables (XLAT) @@ -501,7 +501,7 @@ New Features - Implement dynamic mitigation for CVE-2018-3639 on Cortex-A76 - - Ensure SDEI handler executes with CVE-2018-3639 mitigation enabled + - Ensure |SDEI| handler executes with CVE-2018-3639 mitigation enabled - Introduce RAS handling on AArch64 @@ -621,7 +621,7 @@ New Features - Introduce jump primitives for BL31 - - Mask events after CPU wakeup in SDEI dispatcher to conform to the + - Mask events after CPU wakeup in |SDEI| dispatcher to conform to the specification - Misc TF-A Core Common Code Enhancements @@ -785,8 +785,8 @@ New features management and security services. The SPM is the firmware component that is responsible for managing a Secure Partition. - - SDEI dispatcher: Support for interrupt-based SDEI events and all - interfaces as defined by the SDEI specification v1.0, see + - SDEI dispatcher: Support for interrupt-based |SDEI| events and all + interfaces as defined by the |SDEI| specification v1.0, see `SDEI Specification`_ - Exception Handling Framework (EHF): Framework that allows dispatching of diff --git a/docs/components/exception-handling.rst b/docs/components/exception-handling.rst index 2452e06a5..a89a05c97 100644 --- a/docs/components/exception-handling.rst +++ b/docs/components/exception-handling.rst @@ -1,9 +1,6 @@ Exception Handling Framework ============================ -.. |EHF| replace:: Exception Handling Framework -.. |TF-A| replace:: Trusted Firmware-A - This document describes various aspects of handling exceptions by Runtime Firmware (BL31) that are targeted at EL3, other than SMCs. The |EHF| takes care of the following exceptions when targeted at EL3: @@ -48,11 +45,11 @@ exceptions are targeted at and handled in EL3. For instance: - The Arm `SDEI specification`_ defines interfaces through which Normal world interacts with the Runtime Firmware in order to request notification of - system events. The SDEI specification requires that these events are notified - even when the Normal world executes with the exceptions masked. This too - implies that firmware-first handling is required, where the events are first - received by the EL3 firmware, and then dispatched to Normal world through - purely software mechanism. + system events. The |SDEI| specification requires that these events are + notified even when the Normal world executes with the exceptions masked. This + too implies that firmware-first handling is required, where the events are + first received by the EL3 firmware, and then dispatched to Normal world + through purely software mechanism. For |TF-A|, firmware-first handling means that asynchronous exceptions are suitably routed to EL3, and the Runtime Firmware (BL31) is extended to include @@ -73,8 +70,8 @@ choose to: processing of the error to dedicated software stack running at lower secure ELs (as above); additionally, the Normal world may also be required to participate in the handling, or be notified of such events (for example, as - an SDEI event). In this scheme, exception handling potentially and maximally - spans all ELs in both Secure and Normal worlds. + an |SDEI| event). In this scheme, exception handling potentially and + maximally spans all ELs in both Secure and Normal worlds. On any given system, all of the above handling models may be employed independently depending on platform choice and the nature of the exception @@ -603,8 +600,8 @@ should carefully consider the assignment of priorities to dispatchers integrated into runtime firmware. The platform should sensibly delineate priority to various dispatchers according to their nature. In particular, dispatchers of critical nature (RAS, for example) should be assigned higher priority than -others (SDEI, for example); and within SDEI, Critical priority SDEI should be -assigned higher priority than Normal ones. +others (|SDEI|, for example); and within |SDEI|, Critical priority +|SDEI| should be assigned higher priority than Normal ones. Limitations ----------- diff --git a/docs/conf.py b/docs/conf.py index 0fcc50d2f..697b87115 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -9,6 +9,8 @@ # # See the options documentation at http://www.sphinx-doc.org/en/master/config +import os + # -- Project information ----------------------------------------------------- project = 'Trusted Firmware-A' @@ -16,7 +18,6 @@ project = 'Trusted Firmware-A' version = '2.1' release = version # We don't need these to be distinct - # -- General configuration --------------------------------------------------- # Add any Sphinx extension module names here, as strings. They can be @@ -48,6 +49,10 @@ exclude_patterns = [] # The name of the Pygments (syntax highlighting) style to use. pygments_style = 'sphinx' +# Load the contents of the global substitutions file into the 'rst_prolog' +# variable. This ensures that the substitutions are all inserted into each page. +with open('global_substitutions.txt', 'r') as subs: + rst_prolog = subs.read() # -- Options for HTML output ------------------------------------------------- diff --git a/docs/getting_started/porting-guide.rst b/docs/getting_started/porting-guide.rst index 458615ec3..5be8c1525 100644 --- a/docs/getting_started/porting-guide.rst +++ b/docs/getting_started/porting-guide.rst @@ -1840,7 +1840,7 @@ line boundary. SDEI porting requirements ~~~~~~~~~~~~~~~~~~~~~~~~~ -The SDEI dispatcher requires the platform to provide the following macros +The |SDEI| dispatcher requires the platform to provide the following macros and functions, of which some are optional, and some others mandatory. Macros @@ -1850,19 +1850,19 @@ Macro: PLAT_SDEI_NORMAL_PRI [mandatory] ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ This macro must be defined to the EL3 exception priority level associated with -Normal SDEI events on the platform. This must have a higher value (therefore of -lower priority) than ``PLAT_SDEI_CRITICAL_PRI``. +Normal |SDEI| events on the platform. This must have a higher value +(therefore of lower priority) than ``PLAT_SDEI_CRITICAL_PRI``. Macro: PLAT_SDEI_CRITICAL_PRI [mandatory] ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ This macro must be defined to the EL3 exception priority level associated with -Critical SDEI events on the platform. This must have a lower value (therefore of -higher priority) than ``PLAT_SDEI_NORMAL_PRI``. +Critical |SDEI| events on the platform. This must have a lower value +(therefore of higher priority) than ``PLAT_SDEI_NORMAL_PRI``. -**Note**: SDEI exception priorities must be the lowest among Secure priorities. -Among the SDEI exceptions, Critical SDEI priority must be higher than Normal -SDEI priority. +**Note**: |SDEI| exception priorities must be the lowest among Secure +priorities. Among the |SDEI| exceptions, Critical |SDEI| priority must +be higher than Normal |SDEI| priority. Functions ......... @@ -1876,10 +1876,10 @@ Function: int plat_sdei_validate_entry_point(uintptr_t ep) [optional] 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. +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. The default implementation always returns ``0``. On Arm platforms, this function is implemented to translate the entry point to physical address, and further to @@ -1894,11 +1894,12 @@ Function: void plat_sdei_handle_masked_trigger(uint64_t mpidr, unsigned int intr Argument: unsigned int Return: void -SDEI specification requires that a PE comes out of reset with the events masked. -The client therefore is expected to call ``PE_UNMASK`` to unmask SDEI events on -the PE. No SDEI events can be dispatched until such time. +|SDEI| specification requires that a PE comes out of reset with the events +masked. The client therefore is expected to call ``PE_UNMASK`` to unmask +|SDEI| events on the PE. No |SDEI| events can be dispatched until such +time. -Should a PE receive an interrupt that was bound to an SDEI event while the +Should a PE receive an interrupt that was bound to an |SDEI| event while the events are masked on the PE, the dispatcher implementation invokes the function ``plat_sdei_handle_masked_trigger``. The MPIDR of the PE that received the interrupt and the interrupt ID are passed as parameters. diff --git a/docs/global_substitutions.txt b/docs/global_substitutions.txt new file mode 100644 index 000000000..242e62c7c --- /dev/null +++ b/docs/global_substitutions.txt @@ -0,0 +1,55 @@ +.. |AArch32| replace:: :term:`AArch32` +.. |AArch64| replace:: :term:`AArch64` +.. |API| replace:: :term:`API` +.. |CoT| replace:: :term:`CoT` +.. |COT| replace:: :term:`COT` +.. |CSS| replace:: :term:`CSS` +.. |CVE| replace:: :term:`CVE` +.. |DS-5| replace:: :term:`DS-5` +.. |DT| replace:: :term:`DT` +.. |EL| replace:: :term:`EL` +.. |EHF| replace:: :term:`EHF` +.. |FDT| replace:: :term:`FDT` +.. |FIP| replace:: :term:`FIP` +.. |FVP| replace:: :term:`FVP` +.. |FWU| replace:: :term:`FWU` +.. |GIC| replace:: :term:`GIC` +.. |ISA| replace:: :term:`ISA` +.. |Linaro| replace:: :term:`Linaro` +.. |MMU| replace:: :term:`MMU` +.. |MPAM| replace:: :term:`MPAM` +.. |MPIDR| replace:: :term:`MPIDR` +.. |OEN| replace:: :term:`OEN` +.. |OP-TEE| replace:: :term:`OP-TEE` +.. |OTE| replace:: :term:`OTE` +.. |PDD| replace:: :term:`PDD` +.. |PMF| replace:: :term:`PMF` +.. |PSCI| replace:: :term:`PSCI` +.. |RAS| replace:: :term:`RAS` +.. |ROT| replace:: :term:`ROT` +.. |SCMI| replace:: :term:`SCMI` +.. |SCP| replace:: :term:`SCP` +.. |SDEI| replace:: :term:`SDEI` +.. |SDS| replace:: :term:`SDS` +.. |SEA| replace:: :term:`SEA` +.. |SiP| replace:: :term:`SiP` +.. |SIP| replace:: :term:`SIP` +.. |SMC| replace:: :term:`SMC` +.. |SMCCC| replace:: :term:`SMCCC` +.. |SoC| replace:: :term:`SoC` +.. |SP| replace:: :term:`SP` +.. |SPD| replace:: :term:`SPD` +.. |SPM| replace:: :term:`SPM` +.. |SVE| replace:: :term:`SVE` +.. |TBB| replace:: :term:`TBB` +.. |TBBR| replace:: :term:`TBBR` +.. |TEE| replace:: :term:`TEE` +.. |TF-A| replace:: :term:`TF-A` +.. |TF-M| replace:: :term:`TF-M` +.. |TLB| replace:: :term:`TLB` +.. |TLK| replace:: :term:`TLK` +.. |TSP| replace:: :term:`TSP` +.. |TZC| replace:: :term:`TZC` +.. |UEFI| replace:: :term:`UEFI` +.. |WDOG| replace:: :term:`WDOG` +.. |XLAT| replace:: :term:`XLAT` \ No newline at end of file diff --git a/docs/glossary.rst b/docs/glossary.rst new file mode 100644 index 000000000..afe0acf75 --- /dev/null +++ b/docs/glossary.rst @@ -0,0 +1,177 @@ +Glossary +======== + +This glossary provides definitions for terms and abbreviations used in the TF-A +documentation. + +You can find additional definitions in the `Arm Glossary`_. + +.. glossary:: + :sorted: + + AArch32 + 32-bit execution state of the ARMv8 ISA + + AArch64 + 64-bit execution state of the ARMv8 ISA + + API + Application Programming Interface + + CoT + COT + Chain of Trust + + CSS + Compute Sub-System + + CVE + Common Vulnerabilities and Exposures. A CVE document is commonly used to + describe a publicly-known security vulnerability. + + DS-5 + Arm Development Studio 5 + + DT + Device Tree + + EL + Exception Level + + EHF + Exception Handling Framework + + FDT + Flattened Device Tree + + FIP + Firmware Image Package + + FVP + Fixed Virtual Platform + + FWU + FirmWare Update + + GIC + Generic Interrupt Controller + + ISA + Instruction Set Architecture + + Linaro + A collaborative engineering organization consolidating + and optimizing open source software and tools for the Arm architecture. + + MMU + Memory Management Unit + + MPAM + Memory Partitioning And Monitoring. An optional Armv8.4 extension. + + MPIDR + Multiprocessor Affinity Register + + OEN + Owning Entity Number + + OP-TEE + Open Portable Trusted Execution Environment. An example of a :term:`TEE` + + OTE + Open-source Trusted Execution Environment + + PDD + Platform Design Document + + PMF + Performance Measurement Framework + + PSCI + Power State Coordination Interface + + RAS + Reliability, Availability, and Serviceability extensions. A mandatory + extension for the Armv8.2 architecture and later. An optional extension to + the base Armv8 architecture. + + ROT + Root of Trust + + SCMI + System Control and Management Interface + + SCP + System Control Processor + + SDEI + Software Delegated Exception Interface + + SDS + Shared Data Storage + + SEA + Synchronous External Abort + + SiP + SIP + Silicon Provider + + SMC + Secure Monitor Call + + SMCCC + :term:`SMC` Calling Convention + + SoC + System on Chip + + SP + Secure Partition + + SPD + Secure Payload Dispatcher + + SPM + Secure Partition Manager + + SVE + Scalable Vector Extension + + TBB + Trusted Board Boot + + TBBR + Trusted Board Boot Requirements + + TEE + Trusted Execution Environment + + TF-A + Trusted Firmware-A + + TF-M + Trusted Firmware-M + + TLB + Translation Lookaside Buffer + + TLK + Trusted Little Kernel. A Trusted OS from NVIDIA. + + TSP + Test Secure Payload + + TZC + TrustZone Controller + + UEFI + Unified Extensible Firmware Interface + + WDOG + Watchdog + + XLAT + Translation (abbr.). For example, "XLAT table". + +.. _`Arm Glossary`: https://developer.arm.com/support/arm-glossary \ No newline at end of file diff --git a/docs/index.rst b/docs/index.rst index f23b948d0..b0eff61dd 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -15,6 +15,7 @@ Trusted Firmware-A Documentation security_advisories/index change-log acknowledgements + glossary maintainers license @@ -102,7 +103,7 @@ Functionality Secure-EL0, which can be used to implement simple management and security services. - - An SDEI dispatcher to route interrupt-based SDEI events. + - An |SDEI| dispatcher to route interrupt-based |SDEI| events. - An Exception Handling Framework (EHF) that allows dispatching of EL3 interrupts to their registered handlers, to facilitate firmware-first From 29c02529592fb2489edee6c92e418918e5732105 Mon Sep 17 00:00:00 2001 From: Paul Beesley Date: Wed, 13 Mar 2019 15:11:04 +0000 Subject: [PATCH 08/11] doc: Set correct syntax highlighting style Several code blocks do not specify a language for syntax highlighting. This results in Sphinx using a default highlighter which is Python. This patch adds the correct language to each code block that doesn't already specify it. Change-Id: Icce1949aabfdc11a334a42d49edf55fa673cddc3 Signed-off-by: Paul Beesley --- docs/components/romlib-design.rst | 2 +- docs/components/sdei.rst | 2 +- .../secure-partition-manager-design.rst | 2 +- docs/design/auth-framework.rst | 2 +- docs/design/firmware-design.rst | 8 +- docs/design/interrupt-framework-design.rst | 2 +- docs/design/psci-pd-tree.rst | 4 +- docs/getting_started/rt-svc-writers-guide.rst | 2 +- docs/getting_started/user-guide.rst | 98 +++++++++---------- docs/perf/psci-performance-juno.rst | 2 +- docs/plat/allwinner.rst | 4 +- docs/plat/meson-gxbb.rst | 2 +- docs/plat/meson-gxl.rst | 2 +- docs/plat/qemu.rst | 4 +- docs/process/coding-guidelines.rst | 2 +- .../security-advisory-tfv-3.rst | 2 +- .../security-advisory-tfv-8.rst | 2 +- 17 files changed, 71 insertions(+), 71 deletions(-) diff --git a/docs/components/romlib-design.rst b/docs/components/romlib-design.rst index 9f62b7c45..ab39723f0 100644 --- a/docs/components/romlib-design.rst +++ b/docs/components/romlib-design.rst @@ -106,7 +106,7 @@ The environment variable ``CROSS_COMPILE`` must be set as per the user guide. In the below example the usage of ROMLIB together with mbed TLS is demonstrated to showcase the benefits of library at ROM - it's not mandatory. -:: +.. code:: shell make PLAT=fvp \ MBEDTLS_DIR= \ diff --git a/docs/components/sdei.rst b/docs/components/sdei.rst index 8c0878976..7b6cc913d 100644 --- a/docs/components/sdei.rst +++ b/docs/components/sdei.rst @@ -224,7 +224,7 @@ activity, such as receiving a Secure interrupt or an exception. The SDEI dispatcher implementation provides ``sdei_dispatch_event()`` API for this purpose. The API has the following signature: -:: +.. code:: c int sdei_dispatch_event(int ev_num); diff --git a/docs/components/secure-partition-manager-design.rst b/docs/components/secure-partition-manager-design.rst index 31276cd76..88052c552 100644 --- a/docs/components/secure-partition-manager-design.rst +++ b/docs/components/secure-partition-manager-design.rst @@ -130,7 +130,7 @@ First, build the Standalone MM Secure Partition. To build it, refer to the Then build TF-A with SPM support and include the Standalone MM Secure Partition image in the FIP: -:: +.. code:: shell BL32=path/to/standalone/mm/sp BL33=path/to/bl33.bin \ make PLAT=fvp ENABLE_SPM=1 ARM_BL31_IN_DRAM=1 fip all diff --git a/docs/design/auth-framework.rst b/docs/design/auth-framework.rst index 49f0def5e..7a742d5f0 100644 --- a/docs/design/auth-framework.rst +++ b/docs/design/auth-framework.rst @@ -408,7 +408,7 @@ An IPL must provide functions with the following prototypes: An IPL for each type must be registered using the following macro: -:: +.. code:: c REGISTER_IMG_PARSER_LIB(_type, _name, _init, _check_int, _get_param) diff --git a/docs/design/firmware-design.rst b/docs/design/firmware-design.rst index 27d09480a..e9384e62b 100644 --- a/docs/design/firmware-design.rst +++ b/docs/design/firmware-design.rst @@ -2304,7 +2304,7 @@ result in build error. Subscribing to an undefined event however won't. Subscribed handlers must be of type ``pubsub_cb_t``, with following function signature: -:: +.. code:: c typedef void* (*pubsub_cb_t)(const void *arg); @@ -2331,7 +2331,7 @@ A publisher that wants to publish event ``foo`` would: - Define the event ``foo`` in the ``pubsub_events.h``. - :: + .. code:: c REGISTER_PUBSUB_EVENT(foo); @@ -2467,7 +2467,7 @@ respectively. From outside TF-A, timestamps for individual CPUs can be retrieved by calling into ``pmf_smc_handler()``. -.. code:: c +:: Interface : pmf_smc_handler() Argument : unsigned int smc_fid, u_register_t x1, @@ -2597,7 +2597,7 @@ Platform may choose to not define straight the toolchain target architecture directive by defining ``MARCH32_DIRECTIVE``. I.e: -:: +.. code:: make MARCH32_DIRECTIVE := -mach=armv7-a diff --git a/docs/design/interrupt-framework-design.rst b/docs/design/interrupt-framework-design.rst index 6f692b2f1..d4057ea42 100644 --- a/docs/design/interrupt-framework-design.rst +++ b/docs/design/interrupt-framework-design.rst @@ -48,7 +48,7 @@ the exception level(s) it is handled in. The following constants define the various interrupt types in the framework implementation. -:: +.. code:: c #define INTR_TYPE_S_EL1 0 #define INTR_TYPE_EL3 1 diff --git a/docs/design/psci-pd-tree.rst b/docs/design/psci-pd-tree.rst index e52da77c6..56a6d6ff6 100644 --- a/docs/design/psci-pd-tree.rst +++ b/docs/design/psci-pd-tree.rst @@ -109,7 +109,7 @@ separately. This tree is defined by the platform as the array described above as follows: -:: +.. code:: c #define PLAT_NUM_POWER_DOMAINS 20 #define PLATFORM_CORE_COUNT 13 @@ -219,7 +219,7 @@ to represent leaf and non-leaf power domain nodes in the tree. The power domain tree is implemented as a combination of the following data structures. -:: +.. code:: c non_cpu_pd_node_t psci_non_cpu_pd_nodes[PSCI_NUM_NON_CPU_PWR_DOMAINS]; cpu_pd_node_t psci_cpu_pd_nodes[PLATFORM_CORE_COUNT]; diff --git a/docs/getting_started/rt-svc-writers-guide.rst b/docs/getting_started/rt-svc-writers-guide.rst index 559d701a3..51e9d3fa7 100644 --- a/docs/getting_started/rt-svc-writers-guide.rst +++ b/docs/getting_started/rt-svc-writers-guide.rst @@ -92,7 +92,7 @@ A runtime service is registered using the ``DECLARE_RT_SVC()`` macro, specifying the name of the service, the range of OENs covered, the type of service and initialization and call handler functions. -:: +.. code:: c #define DECLARE_RT_SVC(_name, _start, _end, _type, _setup, _smch) diff --git a/docs/getting_started/user-guide.rst b/docs/getting_started/user-guide.rst index a4aa1a791..42040275f 100644 --- a/docs/getting_started/user-guide.rst +++ b/docs/getting_started/user-guide.rst @@ -44,7 +44,7 @@ Tools Install the required packages to build TF-A with the following command: -:: +.. code:: shell sudo apt-get install device-tree-compiler build-essential gcc make git libssl-dev @@ -106,14 +106,14 @@ 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:: shell make CHECKPATCH=/linux/scripts/checkpatch.pl checkcodebase To just check the style on the files that differ between your local branch and the remote master, use: -:: +.. code:: shell make CHECKPATCH=/linux/scripts/checkpatch.pl checkpatch @@ -129,13 +129,13 @@ Building TF-A For AArch64: - :: + .. code:: shell export CROSS_COMPILE=/bin/aarch64-linux-gnu- For AArch32: - :: + .. code:: shell export CROSS_COMPILE=/bin/arm-linux-gnueabihf- @@ -153,7 +153,7 @@ Building TF-A For AArch64 using Arm Compiler 6: - :: + .. code:: shell export CROSS_COMPILE=/bin/aarch64-linux-gnu- make CC=/bin/armclang PLAT= all @@ -164,7 +164,7 @@ Building TF-A For AArch64 using clang: - :: + .. code:: shell export CROSS_COMPILE=/bin/aarch64-linux-gnu- make CC=/bin/clang PLAT= all @@ -173,13 +173,13 @@ Building TF-A For AArch64: - :: + .. code:: shell make PLAT= all For AArch32: - :: + .. code:: shell make PLAT= ARCH=aarch32 AARCH32_SP=sp_min all @@ -222,7 +222,7 @@ Building TF-A - Build products for a specific build variant can be removed using: - :: + .. code:: shell make DEBUG= PLAT= clean @@ -230,7 +230,7 @@ Building TF-A The build tree can be removed completely using: - :: + .. code:: shell make realclean @@ -935,7 +935,7 @@ Debugging options To compile a debug version and make the build more verbose use -:: +.. code:: shell make PLAT= DEBUG=1 V=1 all @@ -955,7 +955,7 @@ platforms** section in the `Firmware Design`_). Extra debug options can be passed to the build system by setting ``CFLAGS`` or ``LDFLAGS``: -.. code:: makefile +.. code:: shell CFLAGS='-O0 -gdwarf-2' \ make PLAT= DEBUG=1 V=1 all @@ -996,7 +996,7 @@ must be recompiled as well. For more information on SPs and SPDs, see the First clean the TF-A build directory to get rid of any previous BL31 binary. Then to build the TSP image use: -:: +.. code:: shell make PLAT= SPD=tspd all @@ -1024,13 +1024,13 @@ and BL33 images. For AArch64: -:: +.. code:: shell make PLAT=fvp BL33=/bl33.bin fip For AArch32: -:: +.. code:: shell make PLAT=fvp ARCH=aarch32 AARCH32_SP=sp_min BL33=/bl33.bin fip @@ -1046,13 +1046,13 @@ steps: It is recommended to remove old artifacts before building the tool: -:: +.. code:: shell make -C tools/fiptool clean Build the tool: -:: +.. code:: shell make [DEBUG=1] [V=1] fiptool @@ -1067,7 +1067,7 @@ options. Example 1: create a new Firmware package ``fip.bin`` that contains BL2 and BL31: -:: +.. code:: shell ./tools/fiptool/fiptool create \ --tb-fw build///bl2.bin \ @@ -1076,13 +1076,13 @@ Example 1: create a new Firmware package ``fip.bin`` that contains BL2 and BL31: Example 2: view the contents of an existing Firmware package: -:: +.. code:: shell ./tools/fiptool/fiptool info /fip.bin Example 3: update the entries of an existing Firmware package: -:: +.. code:: shell # Change the BL2 from Debug to Release version ./tools/fiptool/fiptool update \ @@ -1091,14 +1091,14 @@ Example 3: update the entries of an existing Firmware package: Example 4: unpack all entries from an existing Firmware package: -:: +.. code:: shell # Images will be unpacked to the working directory ./tools/fiptool/fiptool unpack /fip.bin Example 5: remove an entry from an existing Firmware package: -:: +.. code:: shell ./tools/fiptool/fiptool remove \ --tb-fw build//debug/fip.bin @@ -1168,7 +1168,7 @@ images with support for these features: Example of command line using RSA development keys: - :: + .. code:: shell MBEDTLS_DIR= \ make PLAT= TRUSTED_BOARD_BOOT=1 GENERATE_COT=1 \ @@ -1225,7 +1225,7 @@ The ``cert_create`` tool is built as part of the TF-A build process when the previous section), but it can also be built separately with the following command: -:: +.. code:: shell make PLAT= [DEBUG=1] [V=1] certtool @@ -1234,14 +1234,14 @@ For platforms that require their own IDs in certificate files, the generic platform must define its IDs within a ``platform_oid.h`` header file for the build to succeed. -:: +.. code:: shell make PLAT= USE_TBBR_DEFS=0 [DEBUG=1] [V=1] certtool ``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/cert_create/cert_create -h @@ -1270,7 +1270,7 @@ section for more info on selecting the right FDT to use. #. Clean the working directory - :: + .. code:: shell make realclean @@ -1279,7 +1279,7 @@ section for more info on selecting the right FDT to use. Use the fiptool to extract the SCP_BL2 and BL33 images from the FIP package included in the Linaro release: - :: + .. code:: shell # Build the fiptool make [DEBUG=1] [V=1] fiptool @@ -1300,7 +1300,7 @@ section for more info on selecting the right FDT to use. #. Build TF-A images and create a new FIP for FVP - :: + .. code:: shell # AArch64 make PLAT=fvp BL33=nt-fw.bin all fip @@ -1315,7 +1315,7 @@ section for more info on selecting the right FDT to use. Building for AArch64 on Juno simply requires the addition of ``SCP_BL2`` as a build parameter. - :: + .. code:: shell make PLAT=juno BL33=nt-fw.bin SCP_BL2=scp-fw.bin all fip @@ -1328,13 +1328,13 @@ section for more info on selecting the right FDT to use. - Before building BL32, the environment variable ``CROSS_COMPILE`` must point to the AArch32 Linaro cross compiler. - :: + .. code:: shell export CROSS_COMPILE=/bin/arm-linux-gnueabihf- - Build BL32 in AArch32. - :: + .. code:: shell make ARCH=aarch32 PLAT=juno AARCH32_SP=sp_min \ RESET_TO_SP_MIN=1 JUNO_AARCH32_EL3_RUNTIME=1 bl32 @@ -1349,14 +1349,14 @@ section for more info on selecting the right FDT to use. - Before building BL1 and BL2, the environment variable ``CROSS_COMPILE`` must point to the AArch64 Linaro cross compiler. - :: + .. code:: shell export CROSS_COMPILE=/bin/aarch64-linux-gnu- - The following parameters should be used to build BL1 and BL2 in AArch64 and point to the BL32 file. - :: + .. code:: shell make ARCH=aarch64 PLAT=juno JUNO_AARCH32_EL3_RUNTIME=1 \ BL33=nt-fw.bin SCP_BL2=scp-fw.bin \ @@ -1494,7 +1494,7 @@ clear the mailbox at start-up. One way to do that is to create an 8-byte file containing all zero bytes using the following command: -:: +.. code:: shell dd if=/dev/zero of=mailbox.dat bs=1 count=8 @@ -1564,7 +1564,7 @@ used when compiling TF-A. For example, the following command will create a FIP without a BL33 and prepare to jump to a BL33 image loaded at address 0x80000000: -:: +.. code:: shell make PRELOADED_BL33_BASE=0x80000000 PLAT=fvp all fip @@ -1579,7 +1579,7 @@ memory (like in FVP). For example, if the kernel is loaded at ``0x80080000`` and the DTB is loaded at address ``0x82000000``, the firmware can be built like this: -:: +.. code:: shell CROSS_COMPILE=aarch64-linux-gnu- \ make PLAT=fvp DEBUG=1 \ @@ -1627,7 +1627,7 @@ offset in ``INITRD_START`` has to be removed. And the FVP binary can be run with the following command: -:: +.. code:: shell /FVP_Base_AEMv8A-AEMv8A \ -C pctl.startup=0.0.0.0 \ @@ -1801,7 +1801,7 @@ Running on the Foundation FVP with reset to BL1 entrypoint The following ``Foundation_Platform`` parameters should be used to boot Linux with 4 CPUs using the AArch64 build of TF-A. -:: +.. code:: shell /Foundation_Platform \ --cores=4 \ @@ -1837,7 +1837,7 @@ Running on the AEMv8 Base FVP with reset to BL1 entrypoint The following ``FVP_Base_RevC-2xAEMv8A`` parameters should be used to boot Linux with 8 CPUs using the AArch64 build of TF-A. -:: +.. code:: shell /FVP_Base_RevC-2xAEMv8A \ -C pctl.startup=0.0.0.0 \ @@ -1860,7 +1860,7 @@ Running on the AEMv8 Base FVP (AArch32) with reset to BL1 entrypoint The following ``FVP_Base_AEMv8A-AEMv8A`` parameters should be used to boot Linux with 8 CPUs using the AArch32 build of TF-A. -:: +.. code:: shell /FVP_Base_AEMv8A-AEMv8A \ -C pctl.startup=0.0.0.0 \ @@ -1888,7 +1888,7 @@ Running on the Cortex-A57-A53 Base FVP with reset to BL1 entrypoint The following ``FVP_Base_Cortex-A57x4-A53x4`` model parameters should be used to boot Linux with 8 CPUs using the AArch64 build of TF-A. -:: +.. code:: shell /FVP_Base_Cortex-A57x4-A53x4 \ -C pctl.startup=0.0.0.0 \ @@ -1906,7 +1906,7 @@ Running on the Cortex-A32 Base FVP (AArch32) with reset to BL1 entrypoint The following ``FVP_Base_Cortex-A32x4`` model parameters should be used to boot Linux with 4 CPUs using the AArch32 build of TF-A. -:: +.. code:: shell /FVP_Base_Cortex-A32x4 \ -C pctl.startup=0.0.0.0 \ @@ -1924,7 +1924,7 @@ Running on the AEMv8 Base FVP with reset to BL31 entrypoint The following ``FVP_Base_RevC-2xAEMv8A`` parameters should be used to boot Linux with 8 CPUs using the AArch64 build of TF-A. -:: +.. code:: shell /FVP_Base_RevC-2xAEMv8A \ -C pctl.startup=0.0.0.0 \ @@ -1979,7 +1979,7 @@ Running on the AEMv8 Base FVP (AArch32) with reset to SP_MIN entrypoint The following ``FVP_Base_AEMv8A-AEMv8A`` parameters should be used to boot Linux with 8 CPUs using the AArch32 build of TF-A. -:: +.. code:: shell /FVP_Base_AEMv8A-AEMv8A \ -C pctl.startup=0.0.0.0 \ @@ -2019,7 +2019,7 @@ Running on the Cortex-A57-A53 Base FVP with reset to BL31 entrypoint The following ``FVP_Base_Cortex-A57x4-A53x4`` model parameters should be used to boot Linux with 8 CPUs using the AArch64 build of TF-A. -:: +.. code:: shell /FVP_Base_Cortex-A57x4-A53x4 \ -C pctl.startup=0.0.0.0 \ @@ -2047,7 +2047,7 @@ Running on the Cortex-A32 Base FVP (AArch32) with reset to SP_MIN entrypoint The following ``FVP_Base_Cortex-A32x4`` model parameters should be used to boot Linux with 4 CPUs using the AArch32 build of TF-A. -:: +.. code:: shell /FVP_Base_Cortex-A32x4 \ -C pctl.startup=0.0.0.0 \ @@ -2096,7 +2096,7 @@ The SYSTEM SUSPEND is a PSCI API which can be used to implement system suspend to RAM. For more details refer to section 5.16 of `PSCI`_. To test system suspend on Juno, at the linux shell prompt, issue the following command: -:: +.. code:: shell echo +10 > /sys/class/rtc/rtc0/wakealarm echo -n mem > /sys/power/state diff --git a/docs/perf/psci-performance-juno.rst b/docs/perf/psci-performance-juno.rst index caed8bf9a..b6fd8c803 100644 --- a/docs/perf/psci-performance-juno.rst +++ b/docs/perf/psci-performance-juno.rst @@ -28,7 +28,7 @@ levels 0, 1 and 2 respectively. It does not support any retention states. We used the upstream `TF master as of 31/01/2017`_, building the platform using the ``ENABLE_RUNTIME_INSTRUMENTATION`` option: -:: +.. code:: shell make PLAT=juno ENABLE_RUNTIME_INSTRUMENTATION=1 \ SCP_BL2= \ diff --git a/docs/plat/allwinner.rst b/docs/plat/allwinner.rst index 46a5f9bf3..a1e06590a 100644 --- a/docs/plat/allwinner.rst +++ b/docs/plat/allwinner.rst @@ -24,13 +24,13 @@ See the respective `U-Boot documentation`_ for more details. To build for machines with an A64 or H5 SoC: -:: +.. code:: shell make CROSS_COMPILE=aarch64-linux-gnu- PLAT=sun50i_a64 DEBUG=1 bl31 To build for machines with an H6 SoC: -:: +.. code:: shell make CROSS_COMPILE=aarch64-linux-gnu- PLAT=sun50i_h6 DEBUG=1 bl31 diff --git a/docs/plat/meson-gxbb.rst b/docs/plat/meson-gxbb.rst index cae11cd54..2cd8342cb 100644 --- a/docs/plat/meson-gxbb.rst +++ b/docs/plat/meson-gxbb.rst @@ -15,7 +15,7 @@ and Linux: In order to build it: -:: +.. code:: shell CROSS_COMPILE=aarch64-linux-gnu- make DEBUG=1 PLAT=gxbb bl31 diff --git a/docs/plat/meson-gxl.rst b/docs/plat/meson-gxl.rst index 3c39c9d46..c6d850446 100644 --- a/docs/plat/meson-gxl.rst +++ b/docs/plat/meson-gxl.rst @@ -15,7 +15,7 @@ and Linux: In order to build it: -:: +.. code:: shell CROSS_COMPILE=aarch64-linux-gnu- make DEBUG=1 PLAT=gxl diff --git a/docs/plat/qemu.rst b/docs/plat/qemu.rst index 30ae97dda..4ebe64b85 100644 --- a/docs/plat/qemu.rst +++ b/docs/plat/qemu.rst @@ -33,13 +33,13 @@ is conveniently achieved with symlinks the local names as: To build: -:: +.. code:: shell make CROSS_COMPILE=aarch64-none-elf- PLAT=qemu To start (QEMU v2.6.0): -:: +.. code:: shell qemu-system-aarch64 -nographic -machine virt,secure=on -cpu cortex-a57 \ -kernel Image \ diff --git a/docs/process/coding-guidelines.rst b/docs/process/coding-guidelines.rst index 856882b5f..930f76c8c 100644 --- a/docs/process/coding-guidelines.rst +++ b/docs/process/coding-guidelines.rst @@ -292,7 +292,7 @@ of the size of an array is the same. If ``MY_STRUCT_SIZE`` in the above example were wrong then the compiler would emit an error like this: -.. code:: c +:: my_struct.h:10:1: error: size of array ‘assert_my_struct_size_mismatch’ is negative diff --git a/docs/security_advisories/security-advisory-tfv-3.rst b/docs/security_advisories/security-advisory-tfv-3.rst index f74ef1712..b395f1305 100644 --- a/docs/security_advisories/security-advisory-tfv-3.rst +++ b/docs/security_advisories/security-advisory-tfv-3.rst @@ -68,7 +68,7 @@ The vulnerability is mitigated by the following factors: of the ``XN``, ``UXN`` or ``PXN`` bits in the translation tables. See the ``enable_mmu()`` function: - .. code:: c + :: sctlr = read_sctlr_el##_el(); \ sctlr |= SCTLR_WXN_BIT | SCTLR_M_BIT; \ diff --git a/docs/security_advisories/security-advisory-tfv-8.rst b/docs/security_advisories/security-advisory-tfv-8.rst index 5a5ef7cb1..c401eb3df 100644 --- a/docs/security_advisories/security-advisory-tfv-8.rst +++ b/docs/security_advisories/security-advisory-tfv-8.rst @@ -39,7 +39,7 @@ CPU context stored on the stack. This includes registers ``x0`` to ``x3``, as can be seen in the ``lib/el3_runtime/aarch64/context.S`` file at line 339 (referring to the version of the code as of `commit c385955`_): -.. code:: c +:: /* * This function restores all general purpose registers except x30 from the From a2c320a83ef3966b30929636fb8345a7eabee2ae Mon Sep 17 00:00:00 2001 From: Paul Beesley Date: Wed, 13 Mar 2019 15:49:27 +0000 Subject: [PATCH 09/11] doc: Reorganise images and update links Change-Id: I679d1499376a524bef1cfc33df995b0a719b5ac8 Signed-off-by: Paul Beesley --- docs/components/exception-handling.rst | 2 +- docs/components/firmware-update.rst | 4 ++-- docs/components/ras.rst | 2 +- docs/components/romlib-design.rst | 4 ++-- docs/components/sdei.rst | 4 ++-- docs/components/secure-partition-manager-design.rst | 4 ++-- docs/components/xlat-tables-lib-v2-design.rst | 2 +- docs/design/firmware-design.rst | 2 +- docs/design/interrupt-framework-design.rst | 4 ++-- docs/design/reset-design.rst | 8 ++++---- docs/{ => resources}/diagrams/Makefile | 0 .../{ => resources}/diagrams/default_reset_code.png | Bin docs/{ => resources/diagrams}/draw.io/ehf.svg | 0 docs/{ => resources/diagrams}/draw.io/ehf.xml | 0 docs/{ => resources/diagrams}/draw.io/ras.svg | 0 docs/{ => resources/diagrams}/draw.io/ras.xml | 0 docs/{ => resources}/diagrams/fwu_flow.png | Bin docs/{ => resources}/diagrams/fwu_states.png | Bin docs/{ => resources}/diagrams/int_handling.dia | Bin .../diagrams/non-sec-int-handling.png | Bin .../diagrams}/plantuml/plantuml_to_svg.sh | 0 .../diagrams}/plantuml/sdei_explicit_dispatch.puml | 0 .../diagrams}/plantuml/sdei_explicit_dispatch.svg | 0 .../diagrams}/plantuml/sdei_general.puml | 0 .../diagrams}/plantuml/sdei_general.svg | 0 .../diagrams/psci-suspend-sequence.png | Bin docs/{ => resources}/diagrams/reset_code_flow.dia | Bin .../diagrams/reset_code_no_boot_type_check.png | Bin .../diagrams/reset_code_no_checks.png | Bin .../diagrams/reset_code_no_cpu_check.png | Bin docs/{ => resources}/diagrams/romlib_design.dia | Bin docs/{ => resources}/diagrams/romlib_design.png | Bin docs/{ => resources}/diagrams/romlib_wrapper.dia | Bin docs/{ => resources}/diagrams/romlib_wrapper.png | Bin .../diagrams/rt-svc-descs-layout.png | Bin docs/{ => resources}/diagrams/sec-int-handling.png | Bin .../{ => resources}/diagrams/secure_sw_stack_sp.png | Bin .../diagrams/secure_sw_stack_tos.png | Bin docs/{ => resources}/diagrams/xlat_align.dia | Bin docs/{ => resources}/diagrams/xlat_align.png | Bin 40 files changed, 18 insertions(+), 18 deletions(-) rename docs/{ => resources}/diagrams/Makefile (100%) rename docs/{ => resources}/diagrams/default_reset_code.png (100%) rename docs/{ => resources/diagrams}/draw.io/ehf.svg (100%) rename docs/{ => resources/diagrams}/draw.io/ehf.xml (100%) rename docs/{ => resources/diagrams}/draw.io/ras.svg (100%) rename docs/{ => resources/diagrams}/draw.io/ras.xml (100%) rename docs/{ => resources}/diagrams/fwu_flow.png (100%) rename docs/{ => resources}/diagrams/fwu_states.png (100%) rename docs/{ => resources}/diagrams/int_handling.dia (100%) rename docs/{ => resources}/diagrams/non-sec-int-handling.png (100%) rename docs/{ => resources/diagrams}/plantuml/plantuml_to_svg.sh (100%) mode change 100755 => 100644 rename docs/{ => resources/diagrams}/plantuml/sdei_explicit_dispatch.puml (100%) rename docs/{ => resources/diagrams}/plantuml/sdei_explicit_dispatch.svg (100%) rename docs/{ => resources/diagrams}/plantuml/sdei_general.puml (100%) rename docs/{ => resources/diagrams}/plantuml/sdei_general.svg (100%) rename docs/{ => resources}/diagrams/psci-suspend-sequence.png (100%) rename docs/{ => resources}/diagrams/reset_code_flow.dia (100%) rename docs/{ => resources}/diagrams/reset_code_no_boot_type_check.png (100%) rename docs/{ => resources}/diagrams/reset_code_no_checks.png (100%) rename docs/{ => resources}/diagrams/reset_code_no_cpu_check.png (100%) rename docs/{ => resources}/diagrams/romlib_design.dia (100%) mode change 100755 => 100644 rename docs/{ => resources}/diagrams/romlib_design.png (100%) mode change 100755 => 100644 rename docs/{ => resources}/diagrams/romlib_wrapper.dia (100%) mode change 100755 => 100644 rename docs/{ => resources}/diagrams/romlib_wrapper.png (100%) mode change 100755 => 100644 rename docs/{ => resources}/diagrams/rt-svc-descs-layout.png (100%) rename docs/{ => resources}/diagrams/sec-int-handling.png (100%) rename docs/{ => resources}/diagrams/secure_sw_stack_sp.png (100%) rename docs/{ => resources}/diagrams/secure_sw_stack_tos.png (100%) rename docs/{ => resources}/diagrams/xlat_align.dia (100%) rename docs/{ => resources}/diagrams/xlat_align.png (100%) diff --git a/docs/components/exception-handling.rst b/docs/components/exception-handling.rst index a89a05c97..30600f95c 100644 --- a/docs/components/exception-handling.rst +++ b/docs/components/exception-handling.rst @@ -107,7 +107,7 @@ for more than one priority level. .. _ehf-figure: -.. image:: ../draw.io/ehf.svg +.. image:: ../resources/diagrams/draw.io/ehf.svg A priority level is *active* when a handler at that priority level is currently executing in EL3, or has delegated the execution to a lower EL. For interrupts, diff --git a/docs/components/firmware-update.rst b/docs/components/firmware-update.rst index 608803d57..31f5917e0 100644 --- a/docs/components/firmware-update.rst +++ b/docs/components/firmware-update.rst @@ -400,5 +400,5 @@ This is only allowed if the image is not being executed. .. _Authentication Framework Design: ./auth-framework.rst .. _Universally Unique Identifier: https://tools.ietf.org/rfc/rfc4122.txt -.. |Flow Diagram| image:: diagrams/fwu_flow.png?raw=true -.. |FWU state machine| image:: diagrams/fwu_states.png?raw=true +.. |Flow Diagram| image:: ../resources/diagrams/fwu_flow.png +.. |FWU state machine| image:: ../resources/diagrams/fwu_states.png diff --git a/docs/components/ras.rst b/docs/components/ras.rst index 9d56e63a5..137c0c301 100644 --- a/docs/components/ras.rst +++ b/docs/components/ras.rst @@ -39,7 +39,7 @@ be set ``1``. .. _ras-figure: -.. image:: ../draw.io/ras.svg +.. image:: ../resources/diagrams/draw.io/ras.svg See more on `Engaging the RAS framework`_. diff --git a/docs/components/romlib-design.rst b/docs/components/romlib-design.rst index ab39723f0..a70ed17ff 100644 --- a/docs/components/romlib-design.rst +++ b/docs/components/romlib-design.rst @@ -23,7 +23,7 @@ are placed in ROM. The capabilities of the "library at ROM" are: Index file ~~~~~~~~~~ -.. image:: diagrams/romlib_design.png +.. image:: ../resources/diagrams/romlib_design.png :width: 600 Library at ROM is described by an index file with the list of functions to be @@ -54,7 +54,7 @@ For an index file example, refer to ``lib/romlib/jmptbl.i``. Wrapper functions ~~~~~~~~~~~~~~~~~ -.. image:: diagrams/romlib_wrapper.png +.. image:: ../resources/diagrams/romlib_wrapper.png :width: 600 When invoking a function of the "library at ROM", the calling sequence is as diff --git a/docs/components/sdei.rst b/docs/components/sdei.rst index 7b6cc913d..845a29556 100644 --- a/docs/components/sdei.rst +++ b/docs/components/sdei.rst @@ -26,7 +26,7 @@ The following figure depicts a general sequence involving SDEI client executing at EL2 and an event dispatch resulting from the triggering of a bound interrupt. A commentary is provided below: -.. image:: ../plantuml/sdei_general.svg +.. image:: ../resources/diagrams/plantuml/sdei_general.svg As part of initialisation, the SDEI client binds a Non-secure interrupt [1], and the SDEI dispatcher returns a platform dynamic event number [2]. The client then @@ -234,7 +234,7 @@ on success, or ``-1`` on failure. The following figure depicts a scenario involving explicit dispatch of SDEI event. A commentary is provided below: -.. image:: ../plantuml/sdei_explicit_dispatch.svg +.. image:: ../resources/diagrams/plantuml/sdei_explicit_dispatch.svg As part of initialisation, the SDEI client registers a handler for a platform event [1], enables the event [3], and unmasks the current PE [5]. Note that, diff --git a/docs/components/secure-partition-manager-design.rst b/docs/components/secure-partition-manager-design.rst index 88052c552..ac1172c8f 100644 --- a/docs/components/secure-partition-manager-design.rst +++ b/docs/components/secure-partition-manager-design.rst @@ -814,5 +814,5 @@ Error Codes .. _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 -.. |Image 1| image:: ../diagrams/secure_sw_stack_tos.png -.. |Image 2| image:: ../diagrams/secure_sw_stack_sp.png +.. |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/xlat-tables-lib-v2-design.rst b/docs/components/xlat-tables-lib-v2-design.rst index a78d35116..786dd3bcb 100644 --- a/docs/components/xlat-tables-lib-v2-design.rst +++ b/docs/components/xlat-tables-lib-v2-design.rst @@ -418,4 +418,4 @@ mapping cannot be cached in the TLBs. .. _aarch32/xlat_tables_arch.c: ../../lib/xlat_tables_v2/aarch32/xlat_tables_arch.c .. _aarch64/xlat_tables_arch.c: ../../lib/xlat_tables_v2/aarch64/xlat_tables_arch.c .. _Porting Guide: ../getting_started/porting-guide.rst -.. |Alignment Example| image:: ../diagrams/xlat_align.png?raw=true +.. |Alignment Example| image:: ../resources/diagrams/xlat_align.png diff --git a/docs/design/firmware-design.rst b/docs/design/firmware-design.rst index e9384e62b..710d26ded 100644 --- a/docs/design/firmware-design.rst +++ b/docs/design/firmware-design.rst @@ -2679,4 +2679,4 @@ References .. _ROMLIB Design: romlib-design.rst .. _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:: diagrams/rt-svc-descs-layout.png?raw=true +.. |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 d4057ea42..b19f7f73d 100644 --- a/docs/design/interrupt-framework-design.rst +++ b/docs/design/interrupt-framework-design.rst @@ -1015,5 +1015,5 @@ TSP by returning ``SMC_UNK`` error. .. _Porting Guide: ../getting_started/porting-guide.rst .. _SMC calling convention: http://infocenter.arm.com/help/topic/com.arm.doc.den0028a/index.html -.. |Image 1| image:: diagrams/sec-int-handling.png?raw=true -.. |Image 2| image:: diagrams/non-sec-int-handling.png?raw=true +.. |Image 1| image:: ../resources/diagrams/sec-int-handling.png +.. |Image 2| image:: ../resources/diagrams/non-sec-int-handling.png diff --git a/docs/design/reset-design.rst b/docs/design/reset-design.rst index c38f62748..b5c9bb410 100644 --- a/docs/design/reset-design.rst +++ b/docs/design/reset-design.rst @@ -154,7 +154,7 @@ This might be done by the Trusted Boot Firmware or by platform code in BL31. .. _Firmware Design: firmware-design.rst .. _User Guide: ../getting_started/user-guide.rst -.. |Default reset code flow| image:: ../diagrams/default_reset_code.png?raw=true -.. |Reset code flow with programmable reset address| image:: ../diagrams/reset_code_no_boot_type_check.png?raw=true -.. |Reset code flow with single CPU released out of reset| image:: ../diagrams/reset_code_no_cpu_check.png?raw=true -.. |Reset code flow with programmable reset address and single CPU released out of reset| image:: ../diagrams/reset_code_no_checks.png?raw=true +.. |Default reset code flow| image:: ../resources/diagrams/default_reset_code.png +.. |Reset code flow with programmable reset address| image:: ../resources/diagrams/reset_code_no_boot_type_check.png +.. |Reset code flow with single CPU released out of reset| image:: ../resources/diagrams/reset_code_no_cpu_check.png +.. |Reset code flow with programmable reset address and single CPU released out of reset| image:: ../resources/diagrams/reset_code_no_checks.png diff --git a/docs/diagrams/Makefile b/docs/resources/diagrams/Makefile similarity index 100% rename from docs/diagrams/Makefile rename to docs/resources/diagrams/Makefile diff --git a/docs/diagrams/default_reset_code.png b/docs/resources/diagrams/default_reset_code.png similarity index 100% rename from docs/diagrams/default_reset_code.png rename to docs/resources/diagrams/default_reset_code.png diff --git a/docs/draw.io/ehf.svg b/docs/resources/diagrams/draw.io/ehf.svg similarity index 100% rename from docs/draw.io/ehf.svg rename to docs/resources/diagrams/draw.io/ehf.svg diff --git a/docs/draw.io/ehf.xml b/docs/resources/diagrams/draw.io/ehf.xml similarity index 100% rename from docs/draw.io/ehf.xml rename to docs/resources/diagrams/draw.io/ehf.xml diff --git a/docs/draw.io/ras.svg b/docs/resources/diagrams/draw.io/ras.svg similarity index 100% rename from docs/draw.io/ras.svg rename to docs/resources/diagrams/draw.io/ras.svg diff --git a/docs/draw.io/ras.xml b/docs/resources/diagrams/draw.io/ras.xml similarity index 100% rename from docs/draw.io/ras.xml rename to docs/resources/diagrams/draw.io/ras.xml diff --git a/docs/diagrams/fwu_flow.png b/docs/resources/diagrams/fwu_flow.png similarity index 100% rename from docs/diagrams/fwu_flow.png rename to docs/resources/diagrams/fwu_flow.png diff --git a/docs/diagrams/fwu_states.png b/docs/resources/diagrams/fwu_states.png similarity index 100% rename from docs/diagrams/fwu_states.png rename to docs/resources/diagrams/fwu_states.png diff --git a/docs/diagrams/int_handling.dia b/docs/resources/diagrams/int_handling.dia similarity index 100% rename from docs/diagrams/int_handling.dia rename to docs/resources/diagrams/int_handling.dia diff --git a/docs/diagrams/non-sec-int-handling.png b/docs/resources/diagrams/non-sec-int-handling.png similarity index 100% rename from docs/diagrams/non-sec-int-handling.png rename to docs/resources/diagrams/non-sec-int-handling.png diff --git a/docs/plantuml/plantuml_to_svg.sh b/docs/resources/diagrams/plantuml/plantuml_to_svg.sh old mode 100755 new mode 100644 similarity index 100% rename from docs/plantuml/plantuml_to_svg.sh rename to docs/resources/diagrams/plantuml/plantuml_to_svg.sh diff --git a/docs/plantuml/sdei_explicit_dispatch.puml b/docs/resources/diagrams/plantuml/sdei_explicit_dispatch.puml similarity index 100% rename from docs/plantuml/sdei_explicit_dispatch.puml rename to docs/resources/diagrams/plantuml/sdei_explicit_dispatch.puml diff --git a/docs/plantuml/sdei_explicit_dispatch.svg b/docs/resources/diagrams/plantuml/sdei_explicit_dispatch.svg similarity index 100% rename from docs/plantuml/sdei_explicit_dispatch.svg rename to docs/resources/diagrams/plantuml/sdei_explicit_dispatch.svg diff --git a/docs/plantuml/sdei_general.puml b/docs/resources/diagrams/plantuml/sdei_general.puml similarity index 100% rename from docs/plantuml/sdei_general.puml rename to docs/resources/diagrams/plantuml/sdei_general.puml diff --git a/docs/plantuml/sdei_general.svg b/docs/resources/diagrams/plantuml/sdei_general.svg similarity index 100% rename from docs/plantuml/sdei_general.svg rename to docs/resources/diagrams/plantuml/sdei_general.svg diff --git a/docs/diagrams/psci-suspend-sequence.png b/docs/resources/diagrams/psci-suspend-sequence.png similarity index 100% rename from docs/diagrams/psci-suspend-sequence.png rename to docs/resources/diagrams/psci-suspend-sequence.png diff --git a/docs/diagrams/reset_code_flow.dia b/docs/resources/diagrams/reset_code_flow.dia similarity index 100% rename from docs/diagrams/reset_code_flow.dia rename to docs/resources/diagrams/reset_code_flow.dia diff --git a/docs/diagrams/reset_code_no_boot_type_check.png b/docs/resources/diagrams/reset_code_no_boot_type_check.png similarity index 100% rename from docs/diagrams/reset_code_no_boot_type_check.png rename to docs/resources/diagrams/reset_code_no_boot_type_check.png diff --git a/docs/diagrams/reset_code_no_checks.png b/docs/resources/diagrams/reset_code_no_checks.png similarity index 100% rename from docs/diagrams/reset_code_no_checks.png rename to docs/resources/diagrams/reset_code_no_checks.png diff --git a/docs/diagrams/reset_code_no_cpu_check.png b/docs/resources/diagrams/reset_code_no_cpu_check.png similarity index 100% rename from docs/diagrams/reset_code_no_cpu_check.png rename to docs/resources/diagrams/reset_code_no_cpu_check.png diff --git a/docs/diagrams/romlib_design.dia b/docs/resources/diagrams/romlib_design.dia old mode 100755 new mode 100644 similarity index 100% rename from docs/diagrams/romlib_design.dia rename to docs/resources/diagrams/romlib_design.dia diff --git a/docs/diagrams/romlib_design.png b/docs/resources/diagrams/romlib_design.png old mode 100755 new mode 100644 similarity index 100% rename from docs/diagrams/romlib_design.png rename to docs/resources/diagrams/romlib_design.png diff --git a/docs/diagrams/romlib_wrapper.dia b/docs/resources/diagrams/romlib_wrapper.dia old mode 100755 new mode 100644 similarity index 100% rename from docs/diagrams/romlib_wrapper.dia rename to docs/resources/diagrams/romlib_wrapper.dia diff --git a/docs/diagrams/romlib_wrapper.png b/docs/resources/diagrams/romlib_wrapper.png old mode 100755 new mode 100644 similarity index 100% rename from docs/diagrams/romlib_wrapper.png rename to docs/resources/diagrams/romlib_wrapper.png diff --git a/docs/diagrams/rt-svc-descs-layout.png b/docs/resources/diagrams/rt-svc-descs-layout.png similarity index 100% rename from docs/diagrams/rt-svc-descs-layout.png rename to docs/resources/diagrams/rt-svc-descs-layout.png diff --git a/docs/diagrams/sec-int-handling.png b/docs/resources/diagrams/sec-int-handling.png similarity index 100% rename from docs/diagrams/sec-int-handling.png rename to docs/resources/diagrams/sec-int-handling.png diff --git a/docs/diagrams/secure_sw_stack_sp.png b/docs/resources/diagrams/secure_sw_stack_sp.png similarity index 100% rename from docs/diagrams/secure_sw_stack_sp.png rename to docs/resources/diagrams/secure_sw_stack_sp.png diff --git a/docs/diagrams/secure_sw_stack_tos.png b/docs/resources/diagrams/secure_sw_stack_tos.png similarity index 100% rename from docs/diagrams/secure_sw_stack_tos.png rename to docs/resources/diagrams/secure_sw_stack_tos.png diff --git a/docs/diagrams/xlat_align.dia b/docs/resources/diagrams/xlat_align.dia similarity index 100% rename from docs/diagrams/xlat_align.dia rename to docs/resources/diagrams/xlat_align.dia diff --git a/docs/diagrams/xlat_align.png b/docs/resources/diagrams/xlat_align.png similarity index 100% rename from docs/diagrams/xlat_align.png rename to docs/resources/diagrams/xlat_align.png From f94102ba965709aa6110e60b03a6d9f89923e3d2 Mon Sep 17 00:00:00 2001 From: Paul Beesley Date: Wed, 13 Mar 2019 16:02:25 +0000 Subject: [PATCH 10/11] doc: Refactor contributor acknowledgements - Make the list of contributors into an actual list - Use note syntax for the note - Remove the Individuals heading since there are none This file could be considered for removal as it is a legacy document, as its note explains. Change-Id: Idf984bc192af7a0ec367a6642ab99ccccf5df1a8 Signed-off-by: Paul Beesley --- docs/acknowledgements.rst | 37 +++++++++++++------------------------ 1 file changed, 13 insertions(+), 24 deletions(-) diff --git a/docs/acknowledgements.rst b/docs/acknowledgements.rst index 5f2d5bc6b..74b77ff16 100644 --- a/docs/acknowledgements.rst +++ b/docs/acknowledgements.rst @@ -1,28 +1,17 @@ Contributor Acknowledgements ============================ -**Note: This file is only relevant for legacy contributions, to acknowledge the -specific contributors referred to in "Arm Limited and Contributors" copyright -notices. As contributors are now encouraged to put their name or company name -directly into the copyright notices, this file is not relevant for new -contributions.** +.. note:: + This file is only relevant for legacy contributions, to acknowledge the + specific contributors referred to in "Arm Limited and Contributors" copyright + notices. As contributors are now encouraged to put their name or company name + directly into the copyright notices, this file is not relevant for new + contributions. -Companies ---------- - -Linaro Limited - -NVIDIA Corporation - -Socionext Inc. - -Xilinx, Inc. - -NXP Semiconductors - -Marvell International Ltd. - -STMicroelectronics - -Individuals ------------ +- Linaro Limited +- Marvell International Ltd. +- NVIDIA Corporation +- NXP Semiconductors +- Socionext Inc. +- STMicroelectronics +- Xilinx, Inc. From e1c5026ac7e9da1b74047bf8cb9be2a5c9564532 Mon Sep 17 00:00:00 2001 From: Paul Beesley Date: Wed, 13 Mar 2019 16:20:44 +0000 Subject: [PATCH 11/11] doc: Use proper note and warning annotations The documentation contains plenty of notes and warnings. Enable special rendering of these blocks by converting the note prefix into a .. note:: annotation. Change-Id: I34e26ca6bf313d335672ab6c2645741900338822 Signed-off-by: Paul Beesley --- docs/change-log.rst | 30 ++-- docs/components/exception-handling.rst | 4 +- docs/design/auth-framework.rst | 8 +- docs/design/firmware-design.rst | 16 +- docs/design/interrupt-framework-design.rst | 5 +- docs/design/reset-design.rst | 9 +- docs/design/trusted-board-boot.rst | 5 +- docs/getting_started/porting-guide.rst | 34 +++-- docs/getting_started/rt-svc-writers-guide.rst | 5 +- docs/getting_started/user-guide.rst | 139 ++++++++++-------- docs/index.rst | 6 +- docs/plat/rpi3.rst | 11 +- docs/process/coding-guidelines.rst | 5 +- license.rst | 4 +- 14 files changed, 168 insertions(+), 113 deletions(-) diff --git a/docs/change-log.rst b/docs/change-log.rst index bbd7feca9..5941a8ba0 100644 --- a/docs/change-log.rst +++ b/docs/change-log.rst @@ -1186,7 +1186,8 @@ New features - Migrated to use SPDX[0] license identifiers to make software license auditing simpler. - *NOTE:* Files that have been imported by FreeBSD have not been modified. + .. note:: + Files that have been imported by FreeBSD have not been modified. [0]: https://spdx.org/ @@ -2205,7 +2206,8 @@ New features be used on the AEMv8 and Cortex-A57-A53 Base FVPs, as well as the Foundation FVP. - NOTE: The software will not work on Version 1.0 of the Foundation FVP. + .. note:: + The software will not work on Version 1.0 of the Foundation FVP. - Enabled third party contributions. Added a new contributing.md containing instructions for how to contribute and updated copyright text in all files @@ -2236,15 +2238,18 @@ New features FIP from NOR flash, although some support for image loading using semi- hosting is retained. - NOTE: Building a FIP by default is a non-backwards-compatible change. + .. note:: + Building a FIP by default is a non-backwards-compatible change. - NOTE: Generic BL2 code now loads a BL3-3 (non-trusted firmware) image into - DRAM instead of expecting this to be pre-loaded at known location. This is - also a non-backwards-compatible change. + .. note:: + Generic BL2 code now loads a BL3-3 (non-trusted firmware) image into + DRAM instead of expecting this to be pre-loaded at known location. This is + also a non-backwards-compatible change. - NOTE: Some non-trusted firmware (e.g. UEFI) will need to be rebuilt so that - it knows the new location to execute from and no longer needs to copy - particular code modules to DRAM itself. + .. note:: + Some non-trusted firmware (e.g. UEFI) will need to be rebuilt so that + it knows the new location to execute from and no longer needs to copy + particular code modules to DRAM itself. - Reworked BL2 to BL3-1 handover interface. A new composite structure (bl31_args) holds the superset of information that needs to be passed from @@ -2270,8 +2275,11 @@ New features Dispatcher (TSPD), which is loaded as an EL3 runtime service. The TSPD implements Secure Monitor functionality such as world switching and EL1 context management, and is responsible for communication with the TSP. - NOTE: The TSPD does not yet contain support for secure world interrupts. - NOTE: The TSP/TSPD is not built by default. + + .. note:: + The TSPD does not yet contain support for secure world interrupts. + .. note:: + The TSP/TSPD is not built by default. Issues resolved since last release ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ diff --git a/docs/components/exception-handling.rst b/docs/components/exception-handling.rst index 30600f95c..8f74eb657 100644 --- a/docs/components/exception-handling.rst +++ b/docs/components/exception-handling.rst @@ -193,7 +193,7 @@ priority assignment: 6 and 5), the platform can partition into 4 secure priority ranges: ``0x0``, ``0x20``, ``0x40``, and ``0x60``. See `Interrupt handling example`_. -Note: +.. note:: The Arm GIC architecture requires that a GIC implementation that supports two security states must implement at least 32 priority levels; i.e., at least 5 @@ -215,7 +215,7 @@ priority level descriptors. Each entry in the array is of type ``ehf_pri_desc_t``, and declares a priority level, and shall be populated by the ``EHF_PRI_DESC()`` macro. -Note: +.. warning:: The macro ``EHF_PRI_DESC()`` installs the descriptors in the array at a computed index, and not necessarily where the macro is placed in the array. diff --git a/docs/design/auth-framework.rst b/docs/design/auth-framework.rst index 7a742d5f0..da958b7c2 100644 --- a/docs/design/auth-framework.rst +++ b/docs/design/auth-framework.rst @@ -953,9 +953,11 @@ sources in the build for the various algorithms. Setting the variable to `rsa+ecdsa` enables support for both rsa and ecdsa algorithms in the mbedTLS library. -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 implementation -of SHA-256 with smaller memory footprint (~1.5 KB less) but slower (~30%). +.. 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 + implementation of SHA-256 with smaller memory footprint (~1.5 KB less) but + slower (~30%). -------------- diff --git a/docs/design/firmware-design.rst b/docs/design/firmware-design.rst index 710d26ded..21b823463 100644 --- a/docs/design/firmware-design.rst +++ b/docs/design/firmware-design.rst @@ -1141,8 +1141,10 @@ returning through EL3 and running the non-trusted firmware (BL33): ``bl31_register_bl32_init()`` which provides a SPD-defined mechanism to invoke a 'world-switch synchronous call' to Secure-EL1 to run the BL32 entrypoint. - NOTE: The Test SPD service included with TF-A provides one implementation - of such a mechanism. + + .. note:: + The Test SPD service included with TF-A provides one implementation + of such a mechanism. On completion BL32 returns control to BL31 via a SMC, and on receipt the SPD service handler invokes the synchronous call return mechanism to return @@ -1675,8 +1677,9 @@ The location of the BL32 image will result in different memory maps. This is illustrated for both FVP and Juno in the following diagrams, using the TSP as an example. -Note: Loading the BL32 image in TZC secured DRAM doesn't change the memory -layout of the other images in Trusted SRAM. +.. note:: + Loading the BL32 image in TZC secured DRAM doesn't change the memory + layout of the other images in Trusted SRAM. CONFIG section in memory layouts shown below contains: @@ -2215,8 +2218,9 @@ The default memory layout for each BL image is as follows: | Code | +-------------------+ BLx_BASE -Note: The 2KB alignment for the exception vectors is an architectural -requirement. +.. note:: + The 2KB alignment for the exception vectors is an architectural + requirement. The read-write data start on a new memory page so that they can be mapped with read-write permissions, whereas the code and read-only data below are configured diff --git a/docs/design/interrupt-framework-design.rst b/docs/design/interrupt-framework-design.rst index b19f7f73d..f68cf219a 100644 --- a/docs/design/interrupt-framework-design.rst +++ b/docs/design/interrupt-framework-design.rst @@ -416,8 +416,9 @@ runtime. Test secure payload dispatcher behavior ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -**Note:** where this document discusses ``TSP_NS_INTR_ASYNC_PREEMPT`` as being -``1``, the same results also apply when ``EL3_EXCEPTION_HANDLING`` is ``1``. +.. note:: + Where this document discusses ``TSP_NS_INTR_ASYNC_PREEMPT`` as being + ``1``, the same results also apply when ``EL3_EXCEPTION_HANDLING`` is ``1``. The TSPD only handles Secure-EL1 interrupts and is provided with the following routing model at build time. diff --git a/docs/design/reset-design.rst b/docs/design/reset-design.rst index b5c9bb410..ccd717a06 100644 --- a/docs/design/reset-design.rst +++ b/docs/design/reset-design.rst @@ -23,10 +23,11 @@ configuration, some of these steps might be unnecessary. The following sections guide the platform integrator by indicating which build options exclude which steps, depending on the capability of the platform. -Note: If BL31 is used as the TF-A entry point instead of BL1, the diagram -above is still relevant, as all these operations will occur in BL31 in -this case. Please refer to section 6 "Using BL31 entrypoint as the reset -address" for more information. +.. note:: + If BL31 is used as the TF-A entry point instead of BL1, the diagram + above is still relevant, as all these operations will occur in BL31 in + this case. Please refer to section 6 "Using BL31 entrypoint as the reset + address" for more information. Programmable CPU reset address ------------------------------ diff --git a/docs/design/trusted-board-boot.rst b/docs/design/trusted-board-boot.rst index dbe2f2aa4..6f648f513 100644 --- a/docs/design/trusted-board-boot.rst +++ b/docs/design/trusted-board-boot.rst @@ -141,8 +141,9 @@ if any of the steps fail. compared with the hash of the ROTPK read from the trusted root-key storage registers. If they match, the BL2 hash is read from the certificate. - Note: the matching operation is platform specific and is currently - unimplemented on the Arm development platforms. + .. note:: + The matching operation is platform specific and is currently + unimplemented on the Arm development platforms. - BL1 loads the BL2 image. Its hash is calculated and compared with the hash read from the certificate. Control is transferred to the BL2 image if all diff --git a/docs/getting_started/porting-guide.rst b/docs/getting_started/porting-guide.rst index 5be8c1525..94ec93232 100644 --- a/docs/getting_started/porting-guide.rst +++ b/docs/getting_started/porting-guide.rst @@ -331,7 +331,9 @@ must also be defined: SCP_BL2U image identifier, used by BL1 to fetch an image descriptor corresponding to SCP_BL2U. - NOTE: TF-A does not provide source code for this image. + + .. note:: + TF-A does not provide source code for this image. If the Non-Secure Firmware Updater ROM, NS_BL1U is used, the following must also be defined: @@ -340,7 +342,9 @@ also be defined: Defines the base address in non-secure ROM where NS_BL1U executes. Must be aligned on a page-size boundary. - NOTE: TF-A does not provide source code for this image. + + .. note:: + TF-A does not provide source code for this image. - **#define : NS_BL1U_IMAGE_ID** @@ -354,7 +358,9 @@ be defined: Defines the base address in non-secure memory where NS_BL2U executes. Must be aligned on a page-size boundary. - NOTE: TF-A does not provide source code for this image. + + .. note:: + TF-A does not provide source code for this image. - **#define : NS_BL2U_IMAGE_ID** @@ -1000,8 +1006,9 @@ situation from which it cannot recover. This function must not return, and must be implemented in assembly because it may be called before the C environment is initialized. -Note: The address from where it was called is stored in x30 (Link Register). -The default implementation simply spins. +.. note:: + The address from where it was called is stored in x30 (Link Register). + The default implementation simply spins. Function : plat_get_bl_image_load_info() ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -1042,9 +1049,10 @@ value will weaken the protection as the attacker could easily write the right value as part of the attack most of the time. Therefore, it should return a true random number. -Note: For the protection to be effective, the global data need to be placed at -a lower address than the stack bases. Failure to do so would allow an attacker -to overwrite the canary as part of the stack buffer overflow attack. +.. warning:: + For the protection to be effective, the global data need to be placed at + a lower address than the stack bases. Failure to do so would allow an + attacker to overwrite the canary as part of the stack buffer overflow attack. Function : plat_flush_next_bl_params() ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -2564,10 +2572,12 @@ makefiles in order to benefit from them. By default, they will cause the crash output to be routed over the normal console infrastructure and get printed on consoles configured to output in crash state. ``console_set_scope()`` can be used to control whether a console is used for crash output. -NOTE: Platforms are responsible for making sure that they only mark consoles for -use in the crash scope that are able to support this, i.e. that are written in -assembly and conform with the register clobber rules for putc() (x0-x2, x16-x17) -and flush() (x0-x3, x16-x17) crash callbacks. + +.. note:: + Platforms are responsible for making sure that they only mark consoles for + use in the crash scope that are able to support this, i.e. that are written + in assembly and conform with the register clobber rules for putc() + (x0-x2, x16-x17) and flush() (x0-x3, x16-x17) crash callbacks. In some cases (such as debugging very early crashes that happen before the normal boot console can be set up), platforms may want to control crash output diff --git a/docs/getting_started/rt-svc-writers-guide.rst b/docs/getting_started/rt-svc-writers-guide.rst index 51e9d3fa7..03212af1a 100644 --- a/docs/getting_started/rt-svc-writers-guide.rst +++ b/docs/getting_started/rt-svc-writers-guide.rst @@ -260,8 +260,9 @@ The ``cookie`` parameter to the handler is reserved for future use and can be ignored. The ``handle`` is returned by the SMC handler - completion of the handler function must always be via one of the ``SMC_RETn()`` macros. -NOTE: The PSCI and Test Secure-EL1 Payload Dispatcher services do not follow -all of the above requirements yet. +.. note:: + The PSCI and Test Secure-EL1 Payload Dispatcher services do not follow + all of the above requirements yet. Services that contain multiple sub-services ------------------------------------------- diff --git a/docs/getting_started/user-guide.rst b/docs/getting_started/user-guide.rst index 42040275f..606546447 100644 --- a/docs/getting_started/user-guide.rst +++ b/docs/getting_started/user-guide.rst @@ -96,9 +96,10 @@ 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. -**Note:** Checkpatch errors will gate upstream merging of pull requests. -Checkpatch warnings will not gate merging but should be reviewed and fixed if -possible. +.. note:: + Checkpatch errors will gate upstream merging of pull requests. + Checkpatch warnings will not gate merging but should be reviewed and fixed if + possible. To check the entire source tree, you must first download copies of ``checkpatch.pl``, ``spelling.txt`` and ``const_structs.checkpatch`` available @@ -718,8 +719,9 @@ Common build options of certificates in the FIP and FWU_FIP depends upon the value of the ``GENERATE_COT`` option. - Note: This option depends on ``CREATE_KEYS`` to be enabled. If the keys - already exist in disk, they will be overwritten without further notice. + .. warning:: + This option depends on ``CREATE_KEYS`` to be enabled. If the keys + already exist in disk, they will be overwritten without further notice. - ``TRUSTED_WORLD_KEY``: This option is used when ``GENERATE_COT=1``. It specifies the file that contains the Trusted World private key in PEM @@ -739,8 +741,9 @@ Common build options interrupts to TSP allowing it to save its context and hand over synchronously to EL3 via an SMC. - Note: when ``EL3_EXCEPTION_HANDLING`` is ``1``, ``TSP_NS_INTR_ASYNC_PREEMPT`` - must also be set to ``1``. + .. note:: + When ``EL3_EXCEPTION_HANDLING`` is ``1``, ``TSP_NS_INTR_ASYNC_PREEMPT`` + must also be set to ``1``. - ``USE_ARM_LINK``: This flag determines whether to enable support for ARM linker. When the ``LINKER`` build variable points to the armlink linker, @@ -948,9 +951,10 @@ version to 2 is recommended for DS-5 versions older than 5.16. When debugging logic problems it might also be useful to disable all compiler optimizations by using ``-O0``. -NOTE: Using ``-O0`` could cause output images to be larger and base addresses -might need to be recalculated (see the **Memory layout on Arm development -platforms** section in the `Firmware Design`_). +.. warning:: + Using ``-O0`` could cause output images to be larger and base addresses + might need to be recalculated (see the **Memory layout on Arm development + platforms** section in the `Firmware Design`_). Extra debug options can be passed to the build system by setting ``CFLAGS`` or ``LDFLAGS``: @@ -1205,12 +1209,14 @@ images with support for these features: NS_BL2U=/ \ all fip fwu_fip - Note: The BL2U image will be built by default and added to the FWU_FIP. - The user may override this by adding ``BL2U=/`` - to the command line above. + .. note:: + The BL2U image will be built by default and added to the FWU_FIP. + The user may override this by adding ``BL2U=/`` + to the command line above. - Note: Building and installing the non-secure and SCP FWU images (NS_BL1U, - NS_BL2U and SCP_BL2U) is outside the scope of this document. + .. note:: + Building and installing the non-secure and SCP FWU images (NS_BL1U, + NS_BL2U and SCP_BL2U) is outside the scope of this document. 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 @@ -1252,21 +1258,26 @@ This section provides Juno and FVP specific instructions to build Trusted Firmware, obtain the additional required firmware, and pack it all together in a single FIP binary. It assumes that a `Linaro Release`_ has been installed. -Note: Pre-built binaries for AArch32 are available from Linaro Release 16.12 -onwards. Before that release, pre-built binaries are only available for AArch64. +.. note:: + Pre-built binaries for AArch32 are available from Linaro Release 16.12 + onwards. Before that release, pre-built binaries are only available for + AArch64. -Note: Follow the full instructions for one platform before switching to a -different one. Mixing instructions for different platforms may result in -corrupted binaries. +.. warning:: + Follow the full instructions for one platform before switching to a + different one. Mixing instructions for different platforms may result in + corrupted binaries. -Note: The uboot image downloaded by the Linaro workspace script does not always -match the uboot image packaged as BL33 in the corresponding fip file. It is -recommended to use the version that is packaged in the fip file using the -instructions below. +.. warning:: + The uboot image downloaded by the Linaro workspace script does not always + match the uboot image packaged as BL33 in the corresponding fip file. It is + recommended to use the version that is packaged in the fip file using the + instructions below. -Note: For the FVP, the kernel FDT is packaged in FIP during build and loaded -by the firmware at runtime. See `Obtaining the Flattened Device Trees`_ -section for more info on selecting the right FDT to use. +.. note:: + For the FVP, the kernel FDT is packaged in FIP during build and loaded + by the firmware at runtime. See `Obtaining the Flattened Device Trees`_ + section for more info on selecting the right FDT to use. #. Clean the working directory @@ -1291,12 +1302,14 @@ section for more info on selecting the right FDT to use. current working directory. The SCP_BL2 image corresponds to ``scp-fw.bin`` and BL33 corresponds to ``nt-fw.bin``. - Note: The fiptool will complain if the images to be unpacked already - exist in the current directory. If that is the case, either delete those - files or use the ``--force`` option to overwrite. + .. note:: + The fiptool will complain if the images to be unpacked already + 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 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 @@ -1662,7 +1675,8 @@ 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). -The FVP models used are Version 11.6 Build 45, unless otherwise stated. +.. note:: + The FVP models used are Version 11.6 Build 45, unless otherwise stated. - ``FVP_Base_AEMv8A-AEMv8A`` - ``FVP_Base_AEMv8A-AEMv8A-AEMv8A-AEMv8A-CCN502`` @@ -1699,30 +1713,36 @@ Arm FVPs without shifted affinities, and that do not support threaded CPU cores - ``FVP_Base_AEMv8A-AEMv8A`` - ``FVP_Base_Cortex-A32x4`` -NOTE: The ``FVP_Base_RevC-2xAEMv8A`` FVP only supports shifted affinities, which -is not compatible with legacy GIC configurations. Therefore this FVP does not -support these legacy GIC configurations. +.. note:: + The ``FVP_Base_RevC-2xAEMv8A`` FVP only supports shifted affinities, which + is not compatible with legacy GIC configurations. Therefore this FVP does not + support these legacy GIC configurations. -NOTE: The build numbers quoted above are those reported by launching the FVP -with the ``--version`` parameter. +.. note:: + The build numbers quoted above are those reported by launching the FVP + with the ``--version`` parameter. -NOTE: Linaro provides a ramdisk image in prebuilt FVP configurations and full -file systems that can be downloaded separately. To run an FVP with a virtio -file system image an additional FVP configuration option -``-C bp.virtioblockdevice.image_path="/`` can be -used. +.. note:: + Linaro provides a ramdisk image in prebuilt FVP configurations and full + file systems that can be downloaded separately. To run an FVP with a virtio + file system image an additional FVP configuration option + ``-C bp.virtioblockdevice.image_path="/`` can be + used. -NOTE: The software will not work on Version 1.0 of the Foundation FVP. -The commands below would report an ``unhandled argument`` error in this case. +.. note:: + The software will not work on Version 1.0 of the Foundation FVP. + The commands below would report an ``unhandled argument`` error in this case. -NOTE: FVPs can be launched with ``--cadi-server`` option such that a -CADI-compliant debugger (for example, Arm DS-5) can connect to and control its -execution. +.. note:: + FVPs can be launched with ``--cadi-server`` option such that a + CADI-compliant debugger (for example, Arm DS-5) can connect to and control + its execution. -NOTE: Since FVP model Version 11.0 Build 11.0.34 and Version 8.5 Build 0.8.5202 -the internal synchronisation timings changed compared to older versions of the -models. The models can be launched with ``-Q 100`` option if they are required -to match the run time characteristics of the older versions. +.. warning:: + Since FVP model Version 11.0 Build 11.0.34 and Version 8.5 Build 0.8.5202 + the internal synchronisation timings changed compared to older versions of + the models. The models can be launched with ``-Q 100`` option if they are + required to match the run time characteristics of the older versions. The Foundation FVP is a cut down version of the AArch64 Base FVP. It can be downloaded for free from `Arm's website`_. @@ -1743,8 +1763,9 @@ be found in the TF-A source directory under ``fdts/``. The Foundation FVP has a subset of the Base FVP components. For example, the Foundation FVP lacks CLCD and MMC support, and has only one CPU cluster. -Note: It is not recommended to use the FDTs built along the kernel because not -all FDTs are available from there. +.. note:: + It is not recommended to use the FDTs built along the kernel because not + all FDTs are available from there. The dynamic configuration capability is enabled in the firmware for FVPs. This means that the firmware can authenticate and load the FDT if present in @@ -1851,8 +1872,9 @@ with 8 CPUs using the AArch64 build of TF-A. --data cluster0.cpu0="/"@0x80080000 \ --data cluster0.cpu0="/"@0x84000000 -Note: The ``FVP_Base_RevC-2xAEMv8A`` has shifted affinities and requires a -specific DTS for all the CPUs to be loaded. +.. 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 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -2010,8 +2032,9 @@ with 8 CPUs using the AArch32 build of TF-A. --data cluster0.cpu0="/"@0x80080000 \ --data cluster0.cpu0="/"@0x84000000 -Note: The load address of ```` depends on the value ``BL32_BASE``. -It should match the address programmed into the RVBAR register as well. +.. note:: + The load address of ```` depends on the value ``BL32_BASE``. + It should match the address programmed into the RVBAR register as well. Running on the Cortex-A57-A53 Base FVP with reset to BL31 entrypoint ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ diff --git a/docs/index.rst b/docs/index.rst index b0eff61dd..6f6cfdff0 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -153,7 +153,8 @@ 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). -The FVP models used are Version 11.5 Build 33, unless otherwise stated. +.. note:: + The FVP models used are Version 11.5 Build 33, unless otherwise stated. - ``FVP_Base_AEMv8A-AEMv8A`` - ``FVP_Base_AEMv8A-AEMv8A-AEMv8A-AEMv8A-CCN502`` @@ -190,7 +191,8 @@ Arm FVPs without shifted affinities, and that do not support threaded CPU cores - ``FVP_Base_AEMv8A-AEMv8A`` - ``FVP_Base_Cortex-A32x4`` -NOTE: The ``FVP_Base_RevC-2xAEMv8A`` FVP only supports shifted affinities. +.. note:: + The ``FVP_Base_RevC-2xAEMv8A`` FVP only supports shifted affinities. The Foundation FVP can be downloaded free of charge. The Base FVPs can be licensed from Arm. See the `Arm FVP website`_. diff --git a/docs/plat/rpi3.rst b/docs/plat/rpi3.rst index d155fcbfb..38c3dfa82 100644 --- a/docs/plat/rpi3.rst +++ b/docs/plat/rpi3.rst @@ -270,11 +270,12 @@ The following build options are supported: BL32_EXTRA1=tee-pager_v2.bin BL32_EXTRA2=tee-pageable_v2.bin`` to put the binaries into the FIP. - Note: If OP-TEE is used it may be needed to add the following options to the - Linux command line so that the USB driver doesn't use FIQs: - ``dwc_otg.fiq_enable=0 dwc_otg.fiq_fsm_enable=0 dwc_otg.nak_holdoff=0``. - This will unfortunately reduce the performance of the USB driver. It is needed - when using Raspbian, for example. + .. warning:: + If OP-TEE is used it may be needed to add the following options to the + Linux command line so that the USB driver doesn't use FIQs: + ``dwc_otg.fiq_enable=0 dwc_otg.fiq_fsm_enable=0 dwc_otg.nak_holdoff=0``. + This will unfortunately reduce the performance of the USB driver. It is + needed when using Raspbian, for example. - ``TRUSTED_BOARD_BOOT``: This port supports TBB. Set this option to 1 to enable it. In order to use TBB, you might want to set ``GENERATE_COT=1`` to let the diff --git a/docs/process/coding-guidelines.rst b/docs/process/coding-guidelines.rst index 930f76c8c..d524d7331 100644 --- a/docs/process/coding-guidelines.rst +++ b/docs/process/coding-guidelines.rst @@ -7,8 +7,9 @@ and provide feedback. Some of the guidelines may also apply to other codebases. -**Note:** the existing TF codebase does not necessarily comply with all the -below guidelines but the intent is for it to do so eventually. +.. 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 -------------------- diff --git a/license.rst b/license.rst index 29bdf5672..974313467 100644 --- a/license.rst +++ b/license.rst @@ -27,8 +27,8 @@ SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. -------------- -Note: -Individual files contain the following tag instead of the full license text. +.. note:: + Individual files contain the following tag instead of the full license text. ::