From 292585be901de6b89f8b62c20f4158407e5f36ea Mon Sep 17 00:00:00 2001 From: Sandrine Bailleux Date: Wed, 8 Feb 2023 14:07:29 +0100 Subject: [PATCH 1/2] docs(porting): move porting guide upper in table of contents The porting guide is currently hosted under the 'Getting started' section. Yet, porting the full firmware to a new platform is probably not the first thing that one would do. Before delving into the details, one would probably start by building the code for an emulated platform, such as Arm FVP. Furthermore, the porting guide is such a big and important document that it probably deserves being visible in the main table of contents. Thus, move it just above the list of supported platforms. Signed-off-by: Sandrine Bailleux Change-Id: I51b3d2a93832505ab90d73c823f06f9540e84c77 --- docs/getting_started/index.rst | 3 +-- docs/index.rst | 3 ++- docs/{getting_started => }/porting-guide.rst | 8 ++++---- 3 files changed, 7 insertions(+), 7 deletions(-) rename docs/{getting_started => }/porting-guide.rst (99%) diff --git a/docs/getting_started/index.rst b/docs/getting_started/index.rst index 5ebabea81..8180a3f31 100644 --- a/docs/getting_started/index.rst +++ b/docs/getting_started/index.rst @@ -12,10 +12,9 @@ Getting Started build-options build-internals image-terminology - porting-guide psci-lib-integration-guide rt-svc-writers-guide -------------- -*Copyright (c) 2019, Arm Limited. All rights reserved.* +*Copyright (c) 2019-2023, Arm Limited. All rights reserved.* diff --git a/docs/index.rst b/docs/index.rst index 386019943..d5ab8fcf7 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -11,6 +11,7 @@ Trusted Firmware-A Documentation process/index components/index design/index + porting-guide plat/index perf/index security_advisories/index @@ -84,7 +85,7 @@ have previously been raised against the software. -------------- -*Copyright (c) 2013-2021, Arm Limited and Contributors. All rights reserved.* +*Copyright (c) 2013-2023, Arm Limited and Contributors. All rights reserved.* .. _Armv7-A and Armv8-A: https://developer.arm.com/products/architecture/a-profile .. _Secure Monitor: http://www.arm.com/products/processors/technologies/trustzone/tee-smc.php diff --git a/docs/getting_started/porting-guide.rst b/docs/porting-guide.rst similarity index 99% rename from docs/getting_started/porting-guide.rst rename to docs/porting-guide.rst index 21e02899b..366734c43 100644 --- a/docs/getting_started/porting-guide.rst +++ b/docs/porting-guide.rst @@ -3578,7 +3578,7 @@ layer is used to load data from non-volatile platform storage. Currently storage access is only required by BL1 and BL2 phases and performed inside the ``load_image()`` function in ``bl_common.c``. -.. uml:: ../resources/diagrams/plantuml/io_framework_usage_overview.puml +.. uml:: resources/diagrams/plantuml/io_framework_usage_overview.puml It is mandatory to implement at least one storage driver. For the Arm development platforms the Firmware Image Package (FIP) driver is provided as @@ -3588,7 +3588,7 @@ The storage layer is described in the header file in ``drivers/io/io_storage.c`` and the driver files are located in ``drivers/io/``. -.. uml:: ../resources/diagrams/plantuml/io_arm_class_diagram.puml +.. uml:: resources/diagrams/plantuml/io_arm_class_diagram.puml Each IO driver must provide ``io_dev_*`` structures, as described in ``drivers/io/io_driver.h``. These are returned via a mandatory registration @@ -3599,12 +3599,12 @@ Each platform should register devices and their drivers via the storage abstraction layer. These drivers then need to be initialized by bootloader phases as required in their respective ``blx_platform_setup()`` functions. -.. uml:: ../resources/diagrams/plantuml/io_dev_registration.puml +.. uml:: resources/diagrams/plantuml/io_dev_registration.puml The storage abstraction layer provides mechanisms (``io_dev_init()``) to initialize storage devices before IO operations are called. -.. uml:: ../resources/diagrams/plantuml/io_dev_init_and_check.puml +.. uml:: resources/diagrams/plantuml/io_dev_init_and_check.puml The basic operations supported by the layer include ``open()``, ``close()``, ``read()``, ``write()``, ``size()`` and ``seek()``. From fd0933516b10f5298f402c43677588b47a7d9a5e Mon Sep 17 00:00:00 2001 From: Sandrine Bailleux Date: Tue, 4 Apr 2023 16:36:08 +0200 Subject: [PATCH 2/2] docs(porting): refer the reader back to the threat model When porting TF-A to a new platform, it is essential to read the threat model documents in conjunction with the porting guide to understand the security responsibilities of each platform interface to implement. Add a note to highlight this in the porting guide. Change-Id: Icd1e41ae4b15032b72531690dd82a9ef95ca0db5 Signed-off-by: Sandrine Bailleux --- docs/porting-guide.rst | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/docs/porting-guide.rst b/docs/porting-guide.rst index 366734c43..bc9c00f3c 100644 --- a/docs/porting-guide.rst +++ b/docs/porting-guide.rst @@ -26,6 +26,13 @@ provide their own implementation if the default implementation is inadequate. defined. We intend to convert existing weak functions over time. Until then, you will find references to *weak* functions in this document. +Please review the :ref:`Threat Model` documents as part of the porting +effort. Some platform interfaces play a key role in mitigating against some of +the threats. Failing to fulfill these expectations could undermine the security +guarantees offered by TF-A. These platform responsibilities are highlighted in +the threat assessment section, under the "`Mitigations implemented?`" box for +each threat. + Some modifications are common to all Boot Loader (BL) stages. Section 2 discusses these in detail. The subsequent sections discuss the remaining modifications for each BL stage in detail.