Skip to content

GitLab

Unverified Commit fb45044b authored by davidcunado-arm's avatar davidcunado-arm Committed by GitHub
Browse files

Merge pull request #1312 from davidcunado-arm/dc/update_docs 

Docs: Update various for v1.5 release
parents c3e34a9e 855ac025
Expand all Show whitespace changes
Inline Side-by-side
contributing.rst
View file @ fb45044b
Contributing to ARM Trusted Firmware Contributing to Trusted Firmware-A
==================================== ==================================
Getting Started Getting Started
--------------- ---------------
- Make sure you have a `GitHub account`_. - Make sure you have a `GitHub account`_.
- Create an `issue`_ for your work if one does not already exist. This gives - Create an `issue`_ for your work if one does not already exist. This gives
everyone visibility of whether others are working on something similar. ARM everyone visibility of whether others are working on something similar. Arm
licensees may contact ARM directly via their partner managers instead if licensees may contact Arm directly via their partner managers instead if
they prefer. they prefer.
- Note that the `issue`_ tracker for this project is in a separate - Note that the `issue`_ tracker for this project is in a separate
...@@ -27,8 +27,8 @@ Making Changes ...@@ -27,8 +27,8 @@ Making Changes
- Make commits of logical units. See these general `Git guidelines`_ for - Make commits of logical units. See these general `Git guidelines`_ for
contributing to a project. contributing to a project.
- Follow the `Linux coding style`_; this style is enforced for the ARM Trusted - Follow the `Linux coding style`_; this style is enforced for the TF-A
Firmware project (style errors only, not warnings). project (style errors only, not warnings).
- Use the checkpatch.pl script provided with the Linux source tree. A - Use the checkpatch.pl script provided with the Linux source tree. A
Makefile target is provided for convenience (see section 2 in the Makefile target is provided for convenience (see section 2 in the
...@@ -57,7 +57,7 @@ Making Changes ...@@ -57,7 +57,7 @@ Making Changes
:: ::
Portions copyright (c) [XXXX-]YYYY, ARM Limited and Contributors. All rights reserved. Portions copyright (c) [XXXX-]YYYY, Arm Limited and Contributors. All rights reserved.
where XXXX is the year of first contribution (if different to YYYY) and where XXXX is the year of first contribution (if different to YYYY) and
YYYY is the year of most recent contribution. YYYY is the year of most recent contribution.
...@@ -108,7 +108,7 @@ Submitting Changes ...@@ -108,7 +108,7 @@ Submitting Changes
-------------- --------------
*Copyright (c) 2013-2017, ARM Limited and Contributors. All rights reserved.* *Copyright (c) 2013-2018, Arm Limited and Contributors. All rights reserved.*
.. _GitHub account: https://github.com/signup/free .. _GitHub account: https://github.com/signup/free
.. _issue: https://github.com/ARM-software/tf-issues/issues .. _issue: https://github.com/ARM-software/tf-issues/issues
......
docs/arm-sip-service.rst
View file @ fb45044b
ARM SiP Service Arm SiP Service
=============== ===============
This document enumerates and describes the ARM SiP (Silicon Provider) services. This document enumerates and describes the Arm SiP (Silicon Provider) services.
SiP services are non-standard, platform-specific services offered by the silicon SiP services are non-standard, platform-specific services offered by the silicon
implementer or platform provider. They are accessed via. ``SMC`` ("SMC calls") implementer or platform provider. They are accessed via. ``SMC`` ("SMC calls")
...@@ -13,20 +13,20 @@ services: ...@@ -13,20 +13,20 @@ services:
``0xc200ffff`` for 64-bit calls, and ``0x82000000`` - ``0x8200ffff`` for 32-bit ``0xc200ffff`` for 64-bit calls, and ``0x82000000`` - ``0x8200ffff`` for 32-bit
calls. calls.
The ARM SiP implementation offers the following services: The Arm SiP implementation offers the following services:
- Performance Measurement Framework (PMF) - Performance Measurement Framework (PMF)
- Execution State Switching service - Execution State Switching service
Source definitions for ARM SiP service are located in the ``arm_sip_svc.h`` header Source definitions for Arm SiP service are located in the ``arm_sip_svc.h`` header
file. file.
Performance Measurement Framework (PMF) Performance Measurement Framework (PMF)
--------------------------------------- ---------------------------------------
The `Performance Measurement Framework`_ The `Performance Measurement Framework`_
allows callers to retrieve timestamps captured at various paths in ARM Trusted allows callers to retrieve timestamps captured at various paths in TF-A
Firmware execution. It's described in detail in `Firmware Design document`_. execution. It's described in detail in `Firmware Design document`_.
Execution State Switching service Execution State Switching service
--------------------------------- ---------------------------------
...@@ -35,8 +35,8 @@ Execution State Switching service provides a mechanism for a non-secure lower ...@@ -35,8 +35,8 @@ Execution State Switching service provides a mechanism for a non-secure lower
Exception Level (either EL2, or NS EL1 if EL2 isn't implemented) to request to Exception Level (either EL2, or NS EL1 if EL2 isn't implemented) to request to
switch its execution state (a.k.a. Register Width), either from AArch64 to switch its execution state (a.k.a. Register Width), either from AArch64 to
AArch32, or from AArch32 to AArch64, for the calling CPU. This service is only AArch32, or from AArch32 to AArch64, for the calling CPU. This service is only
available when ARM Trusted Firmware is built for AArch64 (i.e. when build option available when Trusted Firmware-A (TF-A) is built for AArch64 (i.e. when build
``ARCH`` is set to ``aarch64``). option ``ARCH`` is set to ``aarch64``).
``ARM_SIP_SVC_EXE_STATE_SWITCH`` ``ARM_SIP_SVC_EXE_STATE_SWITCH``
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
...@@ -79,8 +79,8 @@ The service may return the following error codes: ...@@ -79,8 +79,8 @@ The service may return the following error codes:
- ``STATE_SW_E_PARAM``: If any of the parameters were deemed invalid for - ``STATE_SW_E_PARAM``: If any of the parameters were deemed invalid for
a specific request. a specific request.
- ``STATE_SW_E_DENIED``: If the call is not successful, or when ARM Trusted - ``STATE_SW_E_DENIED``: If the call is not successful, or when TF-A is
Firmware is built for AArch32. built for AArch32.
If the call is successful, the caller wouldn't observe the SMC returning. If the call is successful, the caller wouldn't observe the SMC returning.
Instead, execution starts at the supplied entry point, with the CPU registers 0 Instead, execution starts at the supplied entry point, with the CPU registers 0
...@@ -89,7 +89,7 @@ respectively. ...@@ -89,7 +89,7 @@ respectively.
-------------- --------------
*Copyright (c) 2017, ARM Limited and Contributors. All rights reserved.* *Copyright (c) 2017-2018, Arm Limited and Contributors. All rights reserved.*
.. _SMC Calling Convention: http://infocenter.arm.com/help/topic/com.arm.doc.den0028a/index.html .. _SMC Calling Convention: http://infocenter.arm.com/help/topic/com.arm.doc.den0028a/index.html
.. _Performance Measurement Framework: ./firmware-design.rst#user-content-performance-measurement-framework .. _Performance Measurement Framework: ./firmware-design.rst#user-content-performance-measurement-framework
......
docs/auth-framework.rst
View file @ fb45044b
...@@ -7,8 +7,9 @@ Abstracting a Chain of Trust ...@@ -7,8 +7,9 @@ Abstracting a Chain of Trust
.. contents:: .. contents::
The aim of this document is to describe the authentication framework implemented The aim of this document is to describe the authentication framework
in the Trusted Firmware. This framework fulfills the following requirements: implemented in Trusted Firmware-A (TF-A). This framework fulfills the
following requirements:
#. It should be possible for a platform port to specify the Chain of Trust in #. It should be possible for a platform port to specify the Chain of Trust in
terms of certificate hierarchy and the mechanisms used to verify a terms of certificate hierarchy and the mechanisms used to verify a
...@@ -152,8 +153,8 @@ performed to verify it: ...@@ -152,8 +153,8 @@ performed to verify it:
In Diagram 1, each component is responsible for one or more of these operations. In Diagram 1, each component is responsible for one or more of these operations.
The responsibilities are briefly described below. The responsibilities are briefly described below.
TF Generic code and IO framework (GEN/IO) TF-A Generic code and IO framework (GEN/IO)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
These components are responsible for initiating the authentication process for a These components are responsible for initiating the authentication process for a
particular image in BL1 or BL2. For each BL image that requires authentication, particular image in BL1 or BL2. For each BL image that requires authentication,
...@@ -162,8 +163,8 @@ image until either an authenticated image or the ROT is reached. Then the ...@@ -162,8 +163,8 @@ image until either an authenticated image or the ROT is reached. Then the
Generic code calls the IO framewotk to load the image and calls the Generic code calls the IO framewotk to load the image and calls the
Authentication module to authenticate it, following the CoT from ROT to Image. Authentication module to authenticate it, following the CoT from ROT to Image.
TF Platform Port (PP) TF-A Platform Port (PP)
^^^^^^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^^^^^^^
The platform is responsible for: The platform is responsible for:
...@@ -374,8 +375,8 @@ single parsing method. There has to be one IPL for every method used by the ...@@ -374,8 +375,8 @@ single parsing method. There has to be one IPL for every method used by the
platform. platform.
#. Raw format: This format is effectively a nop as an image using this method #. Raw format: This format is effectively a nop as an image using this method
is treated as being in raw binary format e.g. boot loader images used by ARM is treated as being in raw binary format e.g. boot loader images used by
TF. This method should only be used by data images. TF-A. This method should only be used by data images.
#. X509V3 method: This method uses industry standards like X.509 to represent #. X509V3 method: This method uses industry standards like X.509 to represent
PKI certificates (authentication images). It is expected that open source PKI certificates (authentication images). It is expected that open source
...@@ -631,8 +632,8 @@ array of image descriptors and it is registered in the framework using the macro ...@@ -631,8 +632,8 @@ array of image descriptors and it is registered in the framework using the macro
process to fail). process to fail).
The number of images participating in the boot process depends on the CoT. There The number of images participating in the boot process depends on the CoT. There
is, however, a minimum set of images that are mandatory in the Trusted Firmware is, however, a minimum set of images that are mandatory in TF-A and thus all
and thus all CoTs must present: CoTs must present:
- ``BL2`` - ``BL2``
- ``SCP_BL2`` (platform specific) - ``SCP_BL2`` (platform specific)
...@@ -648,7 +649,7 @@ Following the `Platform Porting Guide`_, a platform must provide unique ...@@ -648,7 +649,7 @@ Following the `Platform Porting Guide`_, a platform must provide unique
identifiers for all the images and certificates that will be loaded during the identifiers for all the images and certificates that will be loaded during the
boot process. If a platform is using the TBBR as a reference for trusted boot, boot process. If a platform is using the TBBR as a reference for trusted boot,
these identifiers can be obtained from ``include/common/tbbr/tbbr_img_def.h``. these identifiers can be obtained from ``include/common/tbbr/tbbr_img_def.h``.
ARM platforms include this file in ``include/plat/arm/common/arm_def.h``. Other Arm platforms include this file in ``include/plat/arm/common/arm_def.h``. Other
platforms may also include this file or provide their own identifiers. platforms may also include this file or provide their own identifiers.
**Important**: the authentication module uses these identifiers to index the **Important**: the authentication module uses these identifiers to index the
...@@ -880,7 +881,7 @@ extract the authentication parameters. The number and type of parser libraries ...@@ -880,7 +881,7 @@ extract the authentication parameters. The number and type of parser libraries
depend on the images used in the CoT. Raw images do not need a library, so depend on the images used in the CoT. Raw images do not need a library, so
only an x509v3 library is required for the TBBR CoT. only an x509v3 library is required for the TBBR CoT.
ARM platforms will use an x509v3 library based on mbed TLS. This library may be Arm platforms will use an x509v3 library based on mbed TLS. This library may be
found in ``drivers/auth/mbedtls/mbedtls_x509_parser.c``. It exports three found in ``drivers/auth/mbedtls/mbedtls_x509_parser.c``. It exports three
functions: functions:
...@@ -898,14 +899,14 @@ an image of type ``IMG_CERT``, it will call the corresponding function exported ...@@ -898,14 +899,14 @@ an image of type ``IMG_CERT``, it will call the corresponding function exported
in this file. in this file.
The build system must be updated to include the corresponding library and The build system must be updated to include the corresponding library and
mbed TLS sources. ARM platforms use the ``arm_common.mk`` file to pull the mbed TLS sources. Arm platforms use the ``arm_common.mk`` file to pull the
sources. sources.
The cryptographic library The cryptographic library
~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~
The cryptographic module relies on a library to perform the required operations, The cryptographic module relies on a library to perform the required operations,
i.e. verify a hash or a digital signature. ARM platforms will use a library i.e. verify a hash or a digital signature. Arm platforms will use a library
based on mbed TLS, which can be found in based on mbed TLS, which can be found in
``drivers/auth/mbedtls/mbedtls_crypto.c``. This library is registered in the ``drivers/auth/mbedtls/mbedtls_crypto.c``. This library is registered in the
authentication framework using the macro ``REGISTER_CRYPTO_LIB()`` and exports authentication framework using the macro ``REGISTER_CRYPTO_LIB()`` and exports
...@@ -934,7 +935,7 @@ of SHA-256 with smaller memory footprint (~1.5 KB less) but slower (~30%). ...@@ -934,7 +935,7 @@ of SHA-256 with smaller memory footprint (~1.5 KB less) but slower (~30%).
-------------- --------------
*Copyright (c) 2017, ARM Limited and Contributors. All rights reserved.* *Copyright (c) 2017-2018, Arm Limited and Contributors. All rights reserved.*
.. _Trusted Board Boot: ./trusted-board-boot.rst .. _Trusted Board Boot: ./trusted-board-boot.rst
.. _Platform Porting Guide: ./porting-guide.rst .. _Platform Porting Guide: ./porting-guide.rst
docs/change-log.rst
View file @ fb45044b
This diff is collapsed.
docs/cpu-specific-build-macros.rst
View file @ fb45044b
ARM CPU Specific Build Macros Arm CPU Specific Build Macros
============================= =============================
...@@ -14,8 +14,8 @@ for a specific CPU on a platform. ...@@ -14,8 +14,8 @@ for a specific CPU on a platform.
Security Vulnerability Workarounds Security Vulnerability Workarounds
---------------------------------- ----------------------------------
ARM Trusted Firmware exports a series of build flags which control which TF-A exports a series of build flags which control which security
security vulnerability workarounds should be applied at runtime. vulnerability workarounds should be applied at runtime.
- ``WORKAROUND_CVE_2017_5715``: Enables the security workaround for - ``WORKAROUND_CVE_2017_5715``: Enables the security workaround for
`CVE-2017-5715`_. Defaults to 1. `CVE-2017-5715`_. Defaults to 1.
...@@ -23,10 +23,9 @@ security vulnerability workarounds should be applied at runtime. ...@@ -23,10 +23,9 @@ security vulnerability workarounds should be applied at runtime.
CPU Errata Workarounds CPU Errata Workarounds
---------------------- ----------------------
ARM Trusted Firmware exports a series of build flags which control the TF-A exports a series of build flags which control the errata workarounds that
errata workarounds that are applied to each CPU by the reset handler. The are applied to each CPU by the reset handler. The errata details can be found
errata details can be found in the CPU specific errata documents published in the CPU specific errata documents published by Arm:
by ARM:
- `Cortex-A53 MPCore Software Developers Errata Notice`_ - `Cortex-A53 MPCore Software Developers Errata Notice`_
- `Cortex-A57 MPCore Software Developers Errata Notice`_ - `Cortex-A57 MPCore Software Developers Errata Notice`_
...@@ -135,8 +134,8 @@ architecture that can be enabled by the platform as desired. ...@@ -135,8 +134,8 @@ architecture that can be enabled by the platform as desired.
- ``A53_DISABLE_NON_TEMPORAL_HINT``: This flag disables the cache non-temporal - ``A53_DISABLE_NON_TEMPORAL_HINT``: This flag disables the cache non-temporal
hint. The LDNP/STNP instructions as implemented on Cortex-A53 do not behave hint. The LDNP/STNP instructions as implemented on Cortex-A53 do not behave
in a way most programmers expect, and will most probably result in a in a way most programmers expect, and will most probably result in a
significant speed degradation to any code that employs them. The ARMv8-A significant speed degradation to any code that employs them. The Armv8-A
architecture (see ARM DDI 0487A.h, section D3.4.3) allows cores to ignore architecture (see Arm DDI 0487A.h, section D3.4.3) allows cores to ignore
the non-temporal hint and treat LDNP/STNP as LDP/STP instead. Enabling this the non-temporal hint and treat LDNP/STNP as LDP/STP instead. Enabling this
flag enforces this behaviour. This needs to be enabled only for revisions flag enforces this behaviour. This needs to be enabled only for revisions
<= r0p3 of the CPU and is enabled by default. <= r0p3 of the CPU and is enabled by default.
...@@ -149,7 +148,7 @@ architecture that can be enabled by the platform as desired. ...@@ -149,7 +148,7 @@ architecture that can be enabled by the platform as desired.
-------------- --------------
*Copyright (c) 2014-2016, ARM Limited and Contributors. All rights reserved.* *Copyright (c) 2014-2018, Arm Limited and Contributors. All rights reserved.*
.. _CVE-2017-5715: http://www.cve.mitre.org/cgi-bin/cvename.cgi?name=2017-5715 .. _CVE-2017-5715: http://www.cve.mitre.org/cgi-bin/cvename.cgi?name=2017-5715
.. _Cortex-A53 MPCore Software Developers Errata Notice: http://infocenter.arm.com/help/topic/com.arm.doc.epm048406/Cortex_A53_MPCore_Software_Developers_Errata_Notice.pdf .. _Cortex-A53 MPCore Software Developers Errata Notice: http://infocenter.arm.com/help/topic/com.arm.doc.epm048406/Cortex_A53_MPCore_Software_Developers_Errata_Notice.pdf
......
docs/firmware-design.rst
View file @ fb45044b
This diff is collapsed.
docs/firmware-update.rst
View file @ fb45044b
ARM Trusted Firmware - Firmware Update Design Guide Trusted Firmware-A - Firmware Update design guide
=================================================== =================================================
.. section-numbering:: .. section-numbering::
...@@ -21,9 +21,9 @@ is corrupt or missing; it therefore may be used as a recovery mode. It may also ...@@ -21,9 +21,9 @@ is corrupt or missing; it therefore may be used as a recovery mode. It may also
be complemented by other, higher level firmware update software. be complemented by other, higher level firmware update software.
FWU implements a specific part of the Trusted Board Boot Requirements (TBBR) FWU implements a specific part of the Trusted Board Boot Requirements (TBBR)
specification, ARM DEN0006C-1. It should be used in conjunction with the specification, Arm DEN0006C-1. It should be used in conjunction with the
`Trusted Board Boot`_ design document, which describes the image authentication `Trusted Board Boot`_ design document, which describes the image authentication
parts of the Trusted Firmware (TF) TBBR implementation. parts of the Trusted Firmware-A (TF-A) TBBR implementation.
Scope Scope
~~~~~ ~~~~~
...@@ -63,11 +63,11 @@ The primary requirements of the FWU feature are: ...@@ -63,11 +63,11 @@ The primary requirements of the FWU feature are:
it needs, and to enable platform specific FWU functionality. See the it needs, and to enable platform specific FWU functionality. See the
`Porting Guide`_ for details of this interface. `Porting Guide`_ for details of this interface.
TF uses abbreviated image terminology for FWU images like for other TF images. TF-A uses abbreviated image terminology for FWU images like for other TF-A
An overview of this terminology can be found `here`_. images. An overview of this terminology can be found `here`_.
The following diagram shows the FWU boot flow for ARM development platforms. The following diagram shows the FWU boot flow for Arm development platforms.
ARM CSS platforms like Juno have a System Control Processor (SCP), and these Arm CSS platforms like Juno have a System Control Processor (SCP), and these
use all defined FWU images. Other platforms may use a subset of these. use all defined FWU images. Other platforms may use a subset of these.
|Flow Diagram| |Flow Diagram|
...@@ -193,8 +193,8 @@ BL1\_SMC\_RUN\_IMAGE ...@@ -193,8 +193,8 @@ BL1\_SMC\_RUN\_IMAGE
if (ep_info not EL3) synchronous exception if (ep_info not EL3) synchronous exception
This SMC passes execution control to an EL3 image described by the provided This SMC passes execution control to an EL3 image described by the provided
``entry_point_info_t`` structure. In the normal TF boot flow, BL2 invokes this SMC ``entry_point_info_t`` structure. In the normal TF-A boot flow, BL2 invokes
for BL1 to pass execution control to BL31. this SMC for BL1 to pass execution control to BL31.
FWU\_SMC\_IMAGE\_COPY FWU\_SMC\_IMAGE\_COPY
~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~
...@@ -400,7 +400,7 @@ This is only allowed if the image is not being executed. ...@@ -400,7 +400,7 @@ This is only allowed if the image is not being executed.
-------------- --------------
*Copyright (c) 2015-2017, ARM Limited and Contributors. All rights reserved.* *Copyright (c) 2015-2018, Arm Limited and Contributors. All rights reserved.*
.. _Trusted Board Boot: ./trusted-board-boot.rst .. _Trusted Board Boot: ./trusted-board-boot.rst
.. _Porting Guide: ./porting-guide.rst .. _Porting Guide: ./porting-guide.rst
......
docs/interrupt-framework-design.rst
View file @ fb45044b
ARM Trusted Firmware Interrupt Management Design guide Trusted Firmware-A interrupt management design guide
====================================================== ====================================================
.. section-numbering:: .. section-numbering::
...@@ -88,8 +88,8 @@ The framework considers certain routing models for each type of interrupt to be ...@@ -88,8 +88,8 @@ The framework considers certain routing models for each type of interrupt to be
incorrect as they conflict with the requirements mentioned in Section 1. The incorrect as they conflict with the requirements mentioned in Section 1. The
following sub-sections describe all the possible routing models and specify following sub-sections describe all the possible routing models and specify
which ones are valid or invalid. EL3 interrupts are currently supported only which ones are valid or invalid. EL3 interrupts are currently supported only
for GIC version 3.0 (ARM GICv3) and only the Secure-EL1 and Non-secure interrupt for GIC version 3.0 (Arm GICv3) and only the Secure-EL1 and Non-secure interrupt
types are supported for GIC version 2.0 (ARM GICv2) (See 1.2). The terminology types are supported for GIC version 2.0 (Arm GICv2) (See 1.2). The terminology
used in the following sub-sections is explained below. used in the following sub-sections is explained below.
#. **CSS**. Current Security State. ``0`` when secure and ``1`` when non-secure #. **CSS**. Current Security State. ``0`` when secure and ``1`` when non-secure
...@@ -111,7 +111,7 @@ Secure-EL1 interrupts ...@@ -111,7 +111,7 @@ Secure-EL1 interrupts
#. **CSS=1, TEL3=0**. Interrupt is routed to the FEL when execution is in #. **CSS=1, TEL3=0**. Interrupt is routed to the FEL when execution is in
non-secure state. This is an invalid routing model as a secure interrupt non-secure state. This is an invalid routing model as a secure interrupt
is not visible to the secure software which violates the motivation behind is not visible to the secure software which violates the motivation behind
the ARM Security Extensions. the Arm Security Extensions.
#. **CSS=1, TEL3=1**. Interrupt is routed to EL3 when execution is in #. **CSS=1, TEL3=1**. Interrupt is routed to EL3 when execution is in
non-secure state. This is a valid routing model as secure software in EL3 non-secure state. This is a valid routing model as secure software in EL3
...@@ -162,7 +162,7 @@ EL3 interrupts ...@@ -162,7 +162,7 @@ EL3 interrupts
#. **CSS=1, TEL3=0**. Interrupt is routed to the FEL when execution is in #. **CSS=1, TEL3=0**. Interrupt is routed to the FEL when execution is in
non-secure state. This is an invalid routing model as a secure interrupt non-secure state. This is an invalid routing model as a secure interrupt
is not visible to the secure software which violates the motivation behind is not visible to the secure software which violates the motivation behind
the ARM Security Extensions. the Arm Security Extensions.
#. **CSS=1, TEL3=1**. Interrupt is routed to EL3 when execution is in #. **CSS=1, TEL3=1**. Interrupt is routed to EL3 when execution is in
non-secure state. This is a valid routing model as secure software in EL3 non-secure state. This is a valid routing model as secure software in EL3
...@@ -179,7 +179,7 @@ uses this information to determine whether the IRQ or the FIQ bit should be ...@@ -179,7 +179,7 @@ uses this information to determine whether the IRQ or the FIQ bit should be
programmed in ``SCR_EL3`` while applying the routing model for a type of programmed in ``SCR_EL3`` while applying the routing model for a type of
interrupt. The platform provides this information through the interrupt. The platform provides this information through the
``plat_interrupt_type_to_line()`` API (described in the ``plat_interrupt_type_to_line()`` API (described in the
`Porting Guide`_). For example, on the FVP port when the platform uses an ARM GICv2 `Porting Guide`_). For example, on the FVP port when the platform uses an Arm GICv2
interrupt controller, Secure-EL1 interrupts are signaled through the FIQ signal interrupt controller, Secure-EL1 interrupts are signaled through the FIQ signal
while Non-secure interrupts are signaled through the IRQ signal. This applies while Non-secure interrupts are signaled through the IRQ signal. This applies
when execution is in either security state. when execution is in either security state.
...@@ -194,7 +194,7 @@ that security state. This means that all the other interrupt types using the ...@@ -194,7 +194,7 @@ that security state. This means that all the other interrupt types using the
same interrupt signal will be forced to the same routing model. This should be same interrupt signal will be forced to the same routing model. This should be
borne in mind when choosing the routing model for an interrupt type. borne in mind when choosing the routing model for an interrupt type.
For example, in ARM GICv3, when the execution context is Secure-EL1/ For example, in Arm GICv3, when the execution context is Secure-EL1/
Secure-EL0, both the EL3 and the non secure interrupt types map to the FIQ Secure-EL0, both the EL3 and the non secure interrupt types map to the FIQ
signal. So if either one of the interrupt type sets the routing model so signal. So if either one of the interrupt type sets the routing model so
that **TEL3=1** when **CSS=0**, the FIQ bit in ``SCR_EL3`` will be programmed to that **TEL3=1** when **CSS=0**, the FIQ bit in ``SCR_EL3`` will be programmed to
...@@ -208,8 +208,8 @@ The framework makes the following assumptions to simplify its implementation. ...@@ -208,8 +208,8 @@ The framework makes the following assumptions to simplify its implementation.
#. Although the framework has support for 2 types of secure interrupts (EL3 #. Although the framework has support for 2 types of secure interrupts (EL3
and Secure-EL1 interrupt), only interrupt controller architectures and Secure-EL1 interrupt), only interrupt controller architectures
like ARM GICv3 has architectural support for EL3 interrupts in the form of like Arm GICv3 has architectural support for EL3 interrupts in the form of
Group 0 interrupts. In ARM GICv2, all secure interrupts are assumed to be Group 0 interrupts. In Arm GICv2, all secure interrupts are assumed to be
handled in Secure-EL1. They can be delivered to Secure-EL1 via EL3 but they handled in Secure-EL1. They can be delivered to Secure-EL1 via EL3 but they
cannot be handled in EL3. cannot be handled in EL3.
...@@ -260,7 +260,7 @@ the non-secure interrupts and target them to the primary CPU. It should also ...@@ -260,7 +260,7 @@ the non-secure interrupts and target them to the primary CPU. It should also
export the interface described in the `Porting Guide`_ to enable export the interface described in the `Porting Guide`_ to enable
handling of interrupts. handling of interrupts.
In the remainder of this document, for the sake of simplicity a ARM GICv2 system In the remainder of this document, for the sake of simplicity a Arm GICv2 system
is considered and it is assumed that the FIQ signal is used to generate Secure-EL1 is considered and it is assumed that the FIQ signal is used to generate Secure-EL1
interrupts and the IRQ signal is used to generate non-secure interrupts in either interrupts and the IRQ signal is used to generate non-secure interrupts in either
security state. EL3 interrupts are not considered. security state. EL3 interrupts are not considered.
...@@ -272,8 +272,7 @@ Roles and responsibilities for interrupt management are sub-divided between the ...@@ -272,8 +272,7 @@ Roles and responsibilities for interrupt management are sub-divided between the
following components of software running in EL3 and Secure-EL1. Each component is following components of software running in EL3 and Secure-EL1. Each component is
briefly described below. briefly described below.
#. EL3 Runtime Firmware. This component is common to all ports of the ARM #. EL3 Runtime Firmware. This component is common to all ports of TF-A.
Trusted Firmware.
#. Secure Payload Dispatcher (SPD) service. This service interfaces with the #. Secure Payload Dispatcher (SPD) service. This service interfaces with the
Secure Payload (SP) software which runs in Secure-EL1/Secure-EL0 and is Secure Payload (SP) software which runs in Secure-EL1/Secure-EL0 and is
...@@ -282,20 +281,20 @@ briefly described below. ...@@ -282,20 +281,20 @@ briefly described below.
exported by the Context management library to implement this functionality. exported by the Context management library to implement this functionality.
Switching execution between the two security states is a requirement for Switching execution between the two security states is a requirement for
interrupt management as well. This results in a significant dependency on interrupt management as well. This results in a significant dependency on
the SPD service. ARM Trusted firmware implements an example Test Secure the SPD service. TF-A implements an example Test Secure Payload Dispatcher
Payload Dispatcher (TSPD) service. (TSPD) service.
An SPD service plugs into the EL3 runtime firmware and could be common to An SPD service plugs into the EL3 runtime firmware and could be common to
some ports of the ARM Trusted Firmware. some ports of TF-A.
#. Secure Payload (SP). On a production system, the Secure Payload corresponds #. Secure Payload (SP). On a production system, the Secure Payload corresponds
to a Secure OS which runs in Secure-EL1/Secure-EL0. It interfaces with the to a Secure OS which runs in Secure-EL1/Secure-EL0. It interfaces with the
SPD service to manage communication with non-secure software. ARM Trusted SPD service to manage communication with non-secure software. TF-A
Firmware implements an example secure payload called Test Secure Payload implements an example secure payload called Test Secure Payload (TSP)
(TSP) which runs only in Secure-EL1. which runs only in Secure-EL1.
A Secure payload implementation could be common to some ports of the ARM A Secure payload implementation could be common to some ports of TF-A,
Trusted Firmware just like the SPD service. just like the SPD service.
Interrupt registration Interrupt registration
---------------------- ----------------------
...@@ -515,7 +514,7 @@ the interrupt routing model is not known to the SPD service at compile time, ...@@ -515,7 +514,7 @@ the interrupt routing model is not known to the SPD service at compile time,
then the SP should pass this information to the SPD service at runtime during then the SP should pass this information to the SPD service at runtime during
its initialisation phase. its initialisation phase.
As mentioned earlier, a ARM GICv2 system is considered and it is assumed that As mentioned earlier, an Arm GICv2 system is considered and it is assumed that
the FIQ signal is used to generate Secure-EL1 interrupts and the IRQ signal the FIQ signal is used to generate Secure-EL1 interrupts and the IRQ signal
is used to generate non-secure interrupts in either security state. is used to generate non-secure interrupts in either security state.
...@@ -595,7 +594,7 @@ exceptions taken at the same (Secure-EL1) exception level. This table is ...@@ -595,7 +594,7 @@ exceptions taken at the same (Secure-EL1) exception level. This table is
referenced through the ``tsp_exceptions`` variable and programmed into the referenced through the ``tsp_exceptions`` variable and programmed into the
VBAR\_EL1. It caters for the asynchronous handling model. VBAR\_EL1. It caters for the asynchronous handling model.
The TSP also programs the Secure Physical Timer in the ARM Generic Timer block The TSP also programs the Secure Physical Timer in the Arm Generic Timer block
to raise a periodic interrupt (every half a second) for the purpose of testing to raise a periodic interrupt (every half a second) for the purpose of testing
interrupt management across all the software components listed in 2.1 interrupt management across all the software components listed in 2.1
...@@ -999,7 +998,7 @@ TSP by returning ``SMC_UNK`` error. ...@@ -999,7 +998,7 @@ TSP by returning ``SMC_UNK`` error.
-------------- --------------
*Copyright (c) 2014-2018, ARM Limited and Contributors. All rights reserved.* *Copyright (c) 2014-2018, Arm Limited and Contributors. All rights reserved.*
.. _Porting Guide: ./porting-guide.rst .. _Porting Guide: ./porting-guide.rst
.. _SMC calling convention: http://infocenter.arm.com/help/topic/com.arm.doc.den0028a/index.html .. _SMC calling convention: http://infocenter.arm.com/help/topic/com.arm.doc.den0028a/index.html
......
docs/plat/hikey.rst
View file @ fb45044b
...@@ -11,7 +11,7 @@ How to build ...@@ -11,7 +11,7 @@ How to build
Code Locations Code Locations
-------------- --------------
- ARM Trusted Firmware: - Trusted Firmware-A:
`link <https://github.com/ARM-software/arm-trusted-firmware>`__ `link <https://github.com/ARM-software/arm-trusted-firmware>`__
- OP-TEE - OP-TEE
...@@ -76,13 +76,13 @@ Build Procedure ...@@ -76,13 +76,13 @@ Build Procedure
export UEFI_TOOLS_DIR=${BUILD_PATH}/uefi-tools export UEFI_TOOLS_DIR=${BUILD_PATH}/uefi-tools
export EDK2_DIR=${BUILD_PATH}/edk2 export EDK2_DIR=${BUILD_PATH}/edk2
EDK2_OUTPUT_DIR=${EDK2_DIR}/Build/HiKey/${BUILD_OPTION}_${AARCH64_TOOLCHAIN} EDK2_OUTPUT_DIR=${EDK2_DIR}/Build/HiKey/${BUILD_OPTION}_${AARCH64_TOOLCHAIN}
# Build fastboot for ARM Trust Firmware. It's used for recovery mode. # Build fastboot for Trusted Firmware-A. It's used for recovery mode.
cd ${BUILD_PATH}/atf-fastboot cd ${BUILD_PATH}/atf-fastboot
CROSS_COMPILE=aarch64-linux-gnu- make PLAT=hikey DEBUG=1 CROSS_COMPILE=aarch64-linux-gnu- make PLAT=hikey DEBUG=1
# Convert DEBUG/RELEASE to debug/release # Convert DEBUG/RELEASE to debug/release
FASTBOOT_BUILD_OPTION=$(echo ${BUILD_OPTION} | tr '[A-Z]' '[a-z]') FASTBOOT_BUILD_OPTION=$(echo ${BUILD_OPTION} | tr '[A-Z]' '[a-z]')
cd ${EDK2_DIR} cd ${EDK2_DIR}
# Build UEFI & ARM Trust Firmware # Build UEFI & Trusted Firmware-A
${UEFI_TOOLS_DIR}/uefi-build.sh -b ${BUILD_OPTION} -a ../arm-trusted-firmware -s ../optee_os hikey ${UEFI_TOOLS_DIR}/uefi-build.sh -b ${BUILD_OPTION} -a ../arm-trusted-firmware -s ../optee_os hikey
- Generate l-loader.bin and partition table for aosp. The eMMC capacity is either 8GB or 4GB. Just change "aosp-8g" to "linux-8g" for debian. - Generate l-loader.bin and partition table for aosp. The eMMC capacity is either 8GB or 4GB. Just change "aosp-8g" to "linux-8g" for debian.
......
docs/plat/hikey960.rst
View file @ fb45044b
...@@ -11,7 +11,7 @@ How to build ...@@ -11,7 +11,7 @@ How to build
Code Locations Code Locations
-------------- --------------
- ARM Trusted Firmware: - Trusted Firmware-A:
`link <https://github.com/ARM-software/arm-trusted-firmware>`__ `link <https://github.com/ARM-software/arm-trusted-firmware>`__
- OP-TEE: - OP-TEE:
...@@ -73,7 +73,7 @@ Build Procedure ...@@ -73,7 +73,7 @@ Build Procedure
export EDK2_DIR=${BUILD_PATH}/edk2 export EDK2_DIR=${BUILD_PATH}/edk2
EDK2_OUTPUT_DIR=${EDK2_DIR}/Build/HiKey960/${BUILD_OPTION}_${AARCH64_TOOLCHAIN} EDK2_OUTPUT_DIR=${EDK2_DIR}/Build/HiKey960/${BUILD_OPTION}_${AARCH64_TOOLCHAIN}
cd ${EDK2_DIR} cd ${EDK2_DIR}
# Build UEFI & ARM Trust Firmware # Build UEFI & Trusted Firmware-A
${UEFI_TOOLS_DIR}/uefi-build.sh -b ${BUILD_OPTION} -a ../arm-trusted-firmware -s ../optee_os hikey960 ${UEFI_TOOLS_DIR}/uefi-build.sh -b ${BUILD_OPTION} -a ../arm-trusted-firmware -s ../optee_os hikey960
- Generate l-loader.bin and partition table. - Generate l-loader.bin and partition table.
......
docs/plat/nvidia-tegra.rst
View file @ fb45044b
...@@ -4,10 +4,10 @@ Tegra SoCs - Overview ...@@ -4,10 +4,10 @@ Tegra SoCs - Overview
- .. rubric:: T210 - .. rubric:: T210
:name: t210 :name: t210
T210 has Quad ARM® Cortex®-A57 cores in a switched configuration with a T210 has Quad Arm® Cortex®-A57 cores in a switched configuration with a
companion set of quad ARM Cortex-A53 cores. The Cortex-A57 and A53 cores companion set of quad Arm Cortex-A53 cores. The Cortex-A57 and A53 cores
support ARMv8, executing both 64-bit Aarch64 code, and 32-bit Aarch32 code support Armv8-A, executing both 64-bit Aarch64 code, and 32-bit Aarch32 code
including legacy ARMv7 applications. The Cortex-A57 processors each have including legacy Armv7-A applications. The Cortex-A57 processors each have
48 KB Instruction and 32 KB Data Level 1 caches; and have a 2 MB shared 48 KB Instruction and 32 KB Data Level 1 caches; and have a 2 MB shared
Level 2 unified cache. The Cortex-A53 processors each have 32 KB Instruction Level 2 unified cache. The Cortex-A53 processors each have 32 KB Instruction
and 32 KB Data Level 1 caches; and have a 512 KB shared Level 2 unified cache. and 32 KB Data Level 1 caches; and have a 512 KB shared Level 2 unified cache.
...@@ -16,7 +16,7 @@ and 32 KB Data Level 1 caches; and have a 512 KB shared Level 2 unified cache. ...@@ -16,7 +16,7 @@ and 32 KB Data Level 1 caches; and have a 512 KB shared Level 2 unified cache.
:name: t132 :name: t132
Denver is NVIDIA's own custom-designed, 64-bit, dual-core CPU which is Denver is NVIDIA's own custom-designed, 64-bit, dual-core CPU which is
fully ARMv8 architecture compatible. Each of the two Denver cores fully Armv8-A architecture compatible. Each of the two Denver cores
implements a 7-way superscalar microarchitecture (up to 7 concurrent implements a 7-way superscalar microarchitecture (up to 7 concurrent
micro-ops can be executed per clock), and includes a 128KB 4-way L1 micro-ops can be executed per clock), and includes a 128KB 4-way L1
instruction cache, a 64KB 4-way L1 data cache, and a 2MB 16-way L2 instruction cache, a 64KB 4-way L1 data cache, and a 2MB 16-way L2
...@@ -94,5 +94,5 @@ Tegra configs ...@@ -94,5 +94,5 @@ Tegra configs
============= =============
- 'tegra\_enable\_l2\_ecc\_parity\_prot': This flag enables the L2 ECC and Parity - '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 Protection bit, for Arm Cortex-A57 CPUs, during CPU boot. This flag will
be enabled by Tegrs SoCs during 'Cluster power up' or 'System Suspend' exit. be enabled by Tegrs SoCs during 'Cluster power up' or 'System Suspend' exit.
docs/plat/poplar.rst
View file @ fb45044b
...@@ -5,7 +5,7 @@ Poplar is the first development board compliant with the 96Boards Enterprise ...@@ -5,7 +5,7 @@ Poplar is the first development board compliant with the 96Boards Enterprise
Edition TV Platform specification. Edition TV Platform specification.
The board features the Hi3798C V200 with an integrated quad-core 64-bit The board features the Hi3798C V200 with an integrated quad-core 64-bit
ARM Cortex A53 processor and high performance Mali T720 GPU, making it capable Arm Cortex A53 processor and high performance Mali T720 GPU, making it capable
of running any commercial set-top solution based on Linux or Android. of running any commercial set-top solution based on Linux or Android.
It supports a premium user experience with up to H.265 HEVC decoding of 4K It supports a premium user experience with up to H.265 HEVC decoding of 4K
...@@ -14,7 +14,7 @@ video at 60 frames per second. ...@@ -14,7 +14,7 @@ video at 60 frames per second.
:: ::
SOC Hisilicon Hi3798CV200 SOC Hisilicon Hi3798CV200
CPU Quad-core ARM Cortex-A53 64 bit CPU Quad-core Arm Cortex-A53 64 bit
DRAM DDR3/3L/4 SDRAM interface, maximum 32-bit data width 2 GB DRAM DDR3/3L/4 SDRAM interface, maximum 32-bit data width 2 GB
USB Two USB 2.0 ports One USB 3.0 ports USB Two USB 2.0 ports One USB 3.0 ports
CONSOLE USB-micro port for console support CONSOLE USB-micro port for console support
...@@ -28,11 +28,11 @@ video at 60 frames per second. ...@@ -28,11 +28,11 @@ video at 60 frames per second.
At the start of the boot sequence, the bootROM executes the so called l-loader At the start of the boot sequence, the bootROM executes the so called l-loader
binary whose main role is to change the processor state to 64bit mode. This binary whose main role is to change the processor state to 64bit mode. This
must happen prior invoking the arm trusted firmware: must happen prior to invoking Trusted Firmware-A:
:: ::
l-loader --> arm_trusted_firmware --> u-boot l-loader --> Trusted Firmware-A --> u-boot
How to build How to build
============ ============
...@@ -40,7 +40,7 @@ How to build ...@@ -40,7 +40,7 @@ How to build
Code Locations Code Locations
-------------- --------------
- ARM Trusted Firmware: - Trusted Firmware-A:
`link <https://github.com/ARM-software/arm-trusted-firmware>`__ `link <https://github.com/ARM-software/arm-trusted-firmware>`__
- l-loader: - l-loader:
......
docs/plat/qemu.rst
View file @ fb45044b
ARM Trusted Firmware for QEMU virt ARMv8-A Trusted Firmware-A for QEMU virt Armv8-A
========================================== ========================================
ARM Trusted Firmware implements the EL3 firmware layer for QEMU virt 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. Armv8-A. BL1 is used as the BootROM, supplied with the -bios argument.
When QEMU starts all CPUs are released simultaneously, BL1 selects a When QEMU starts all CPUs are released simultaneously, BL1 selects a
primary CPU to handle the boot and the secondaries are placed in a polling primary CPU to handle the boot and the secondaries are placed in a polling
loop to be released by normal world via PSCI. loop to be released by normal world via PSCI.
...@@ -10,7 +10,7 @@ loop to be released by normal world via PSCI. ...@@ -10,7 +10,7 @@ loop to be released by normal world via PSCI.
BL2 edits the Flattened Device Tree, FDT, generated by QEMU at run-time to BL2 edits the Flattened Device Tree, FDT, generated by QEMU at run-time to
add a node describing PSCI and also enable methods for the CPUs. add a node describing PSCI and also enable methods for the CPUs.
An ARM64 defonfig v4.5 Linux kernel is known to boot, FTD doesn't need to be An ARM64 defconfig v4.5 Linux kernel is known to boot, FDT doesn't need to be
provided as it's generated by QEMU. provided as it's generated by QEMU.
Current limitations: Current limitations:
......
docs/plat/rpi3.rst
View file @ fb45044b
Arm Trusted Firmware for Raspberry Pi 3 Trusted Firmware-A for Raspberry Pi 3
======================================= =====================================
.. section-numbering:: .. section-numbering::
:suffix: . :suffix: .
...@@ -7,16 +7,16 @@ Arm Trusted Firmware for Raspberry Pi 3 ...@@ -7,16 +7,16 @@ Arm Trusted Firmware for Raspberry Pi 3
.. contents:: .. contents::
The `Raspberry Pi 3`_ is an inexpensive single-board computer that contains four The `Raspberry Pi 3`_ is an inexpensive single-board computer that contains four
Cortex-A53 cores, which makes it possible to have a port of the Arm Trusted Arm Cortex-A53 cores, which makes it possible to have a port of Trusted
Firmware. Firmware-A (TF-A).
The following instructions explain how to use this port of the Trusted Firmware The following instructions explain how to use this port of the TF-A with the
with the default distribution of `Raspbian`_ because that's the distribution default distribution of `Raspbian`_ because that's the distribution officially
officially supported by the Raspberry Pi Foundation. At the moment of writing supported by the Raspberry Pi Foundation. At the moment of writing this, the
this, the officially supported kernel is a AArch32 kernel. This doesn't mean officially supported kernel is a AArch32 kernel. This doesn't mean that this
that this port of the Trusted Firmware can't boot a AArch64 kernel. The `Linux port of TF-A can't boot a AArch64 kernel. The `Linux tree fork`_ maintained by
tree fork`_ maintained by the Foundation can be compiled for AArch64 by the Foundation can be compiled for AArch64 by following the steps in
following the steps in `AArch64 kernel build instructions`_. `AArch64 kernel build instructions`_.
**IMPORTANT NOTE**: This port isn't secure. All of the memory used is DRAM, **IMPORTANT NOTE**: This port isn't secure. All of the memory used is DRAM,
which is available from both the Non-secure and Secure worlds. This port which is available from both the Non-secure and Secure worlds. This port
...@@ -46,15 +46,15 @@ The rules are simple: ...@@ -46,15 +46,15 @@ The rules are simple:
the cores are powered on at the same time and start at address **0x0**. the cores are powered on at the same time and start at address **0x0**.
This means that we can use the default AArch32 kernel provided in the official This means that we can use the default AArch32 kernel provided in the official
`Raspbian`_ distribution by renaming it to ``kernel8.img``, while the Trusted `Raspbian`_ distribution by renaming it to ``kernel8.img``, while TF-A and
Firmware and anything else we need is in ``armstub8.bin``. This way we can anything else we need is in ``armstub8.bin``. This way we can forget about the
forget about the default bootstrap code. When using a AArch64 kernel, it is only default bootstrap code. When using a AArch64 kernel, it is only needed to make
needed to make sure that the name on the SD card is ``kernel8.img``. sure that the name on the SD card is ``kernel8.img``.
Ideally, we want to load the kernel and have all cores available, which means Ideally, we want to load the kernel and have all cores available, which means
that we need to make the secondary cores work in the way the kernel expects, as that we need to make the secondary cores work in the way the kernel expects, as
explained in `Secondary cores`_. In practice, a small bootstrap is needed explained in `Secondary cores`_. In practice, a small bootstrap is needed
between the Trusted Firmware and the kernel. between TF-A and the kernel.
To get the most out of a AArch32 kernel, we want to boot it in Hypervisor mode To get the most out of a AArch32 kernel, we want to boot it in Hypervisor mode
in AArch32. This means that BL33 can't be in EL2 in AArch64 mode. The in AArch32. This means that BL33 can't be in EL2 in AArch64 mode. The
...@@ -66,7 +66,7 @@ Placement of images ...@@ -66,7 +66,7 @@ Placement of images
The file ``armstub8.bin`` contains BL1 and the FIP. It is needed to add padding The file ``armstub8.bin`` contains BL1 and the FIP. It is needed to add padding
between them so that the addresses they are loaded to match the ones specified between them so that the addresses they are loaded to match the ones specified
when compiling the Trusted Firmware. when compiling TF-A.
The device tree block is loaded by the VideoCore loader from an appropriate The device tree block is loaded by the VideoCore loader from an appropriate
file, but we can specify the address it is loaded to in ``config.txt``. file, but we can specify the address it is loaded to in ``config.txt``.
...@@ -87,8 +87,8 @@ There are no similar restrictions for AArch64 kernels, as specified in the file ...@@ -87,8 +87,8 @@ There are no similar restrictions for AArch64 kernels, as specified in the file
``Documentation/arm64/booting.txt``. ``Documentation/arm64/booting.txt``.
This means that we need to avoid the first 128 MiB of RAM when placing the This means that we need to avoid the first 128 MiB of RAM when placing the
Trusted Firmware images (and specially the first 32 MiB, as they are directly TF-A images (and specially the first 32 MiB, as they are directly used to
used to place the uncompressed AArch32 kernel image. This way, both AArch32 and place the uncompressed AArch32 kernel image. This way, both AArch32 and
AArch64 kernels can be placed at the same address. AArch64 kernels can be placed at the same address.
In the end, the images look like the following diagram when placed in memory. In the end, the images look like the following diagram when placed in memory.
...@@ -143,18 +143,17 @@ different mappings than the Arm cores in which the I/O addresses don't overlap ...@@ -143,18 +143,17 @@ different mappings than the Arm cores in which the I/O addresses don't overlap
the DRAM. The memory reserved to be used by the VideoCore is always placed at the DRAM. The memory reserved to be used by the VideoCore is always placed at
the end of the DRAM, so this space isn't wasted. the end of the DRAM, so this space isn't wasted.
Considering the 128 MiB allocated to the GPU and the 16 MiB allocated for the Considering the 128 MiB allocated to the GPU and the 16 MiB allocated for
Trusted Firmware, there are 880 MiB available for Linux. TF-A, there are 880 MiB available for Linux.
Boot sequence Boot sequence
~~~~~~~~~~~~~ ~~~~~~~~~~~~~
The boot sequence of the Trusted Firmware is the usual one except when booting The boot sequence of TF-A is the usual one except when booting an AArch32
a AArch32 kernel. In that case, BL33 is booted in AArch32 Hypervisor mode so kernel. In that case, BL33 is booted in AArch32 Hypervisor mode so that it
that it can jump to the kernel in the same mode and let it take over that can jump to the kernel in the same mode and let it take over that privilege
privilege level. If BL33 was running in EL2 in AArch64 (as in the default level. If BL33 was running in EL2 in AArch64 (as in the default bootflow of
bootflow of the Trusted Firmware) it could only jump to the kernel in AArch32 in TF-A) it could only jump to the kernel in AArch32 in Supervisor mode.
Supervisor mode.
The `Linux kernel tree`_ has instructions on how to jump to the Linux kernel The `Linux kernel tree`_ has instructions on how to jump to the Linux kernel
in ``Documentation/arm/Booting`` and ``Documentation/arm64/booting.txt``. The in ``Documentation/arm/Booting`` and ``Documentation/arm64/booting.txt``. The
...@@ -168,9 +167,9 @@ use mailboxes to trap the secondary cores until they are ready to jump to the ...@@ -168,9 +167,9 @@ use mailboxes to trap the secondary cores until they are ready to jump to the
kernel. This mailbox is located at a different address in the AArch32 default kernel. This mailbox is located at a different address in the AArch32 default
kernel than in the AArch64 kernel. kernel than in the AArch64 kernel.
Also, this port of the Trusted Firmware has another Trusted Mailbox in Shared BL Also, this port of TF-A has another Trusted Mailbox in Shared BL RAM. During
RAM. During cold boot, all secondary cores wait in a loop until they are given cold boot, all secondary cores wait in a loop until they are given given an
given an address to jump to in this Mailbox (``bl31_warm_entrypoint``). address to jump to in this Mailbox (``bl31_warm_entrypoint``).
Once BL31 has finished and the primary core has jumped to the BL33 payload, it Once BL31 has finished and the primary core has jumped to the BL33 payload, it
has to call ``PSCI_CPU_ON`` to release the secondary CPUs from the wait loop. has to call ``PSCI_CPU_ON`` to release the secondary CPUs from the wait loop.
...@@ -188,11 +187,10 @@ To boot a AArch32 kernel, both AArch64 and AArch32 toolchains are required. The ...@@ -188,11 +187,10 @@ To boot a AArch32 kernel, both AArch64 and AArch32 toolchains are required. The
AArch32 toolchain is needed for the AArch32 bootstrap needed to load a 32-bit AArch32 toolchain is needed for the AArch32 bootstrap needed to load a 32-bit
kernel. kernel.
First, clone and compile `Raspberry Pi 3 Arm Trusted Firmware bootstrap`_. First, clone and compile `Raspberry Pi 3 TF-A bootstrap`_. Choose the one
Choose the one needed for the architecture of your kernel. needed for the architecture of your kernel.
Then compile the Arm Trusted Firmware. For a AArch32 kernel, use the following Then compile TF-A. For a AArch32 kernel, use the following command line:
command line:
.. code:: shell .. code:: shell
...@@ -219,8 +217,8 @@ by ``debug`` if you set the build option ``DEBUG=1``): ...@@ -219,8 +217,8 @@ by ``debug`` if you set the build option ``DEBUG=1``):
cat bl1.pad.bin build/rpi3/release/fip.bin > armstub8.bin cat bl1.pad.bin build/rpi3/release/fip.bin > armstub8.bin
The resulting file, ``armstub8.bin``, contains BL1 and the FIP in the place they The resulting file, ``armstub8.bin``, contains BL1 and the FIP in the place they
need to be for the Trusted Firmware to boot correctly. Now, follow the need to be for TF-A to boot correctly. Now, follow the instructions in
instructions in `Setup SD card`_. `Setup SD card`_.
The following build options are supported: The following build options are supported:
...@@ -235,17 +233,17 @@ The following build options are supported: ...@@ -235,17 +233,17 @@ The following build options are supported:
is reserved by the command line passed to the kernel. is reserved by the command line passed to the kernel.
- ``RPI3_BL33_IN_AARCH32``: This port can load a AArch64 or AArch32 BL33 image. - ``RPI3_BL33_IN_AARCH32``: This port can load a AArch64 or AArch32 BL33 image.
By default this option is 0, which means that the Trusted Firmware will jump By default this option is 0, which means that TF-A will jump to BL33 in EL2
to BL33 in EL2 in AArch64 mode. If set to 1, it will jump to BL33 in in AArch64 mode. If set to 1, it will jump to BL33 in Hypervisor in AArch32
Hypervisor in AArch32 mode. mode.
The following is not currently supported: The following is not currently supported:
- AArch32 for the Trusted Firmware itself. - AArch32 for TF-A itself.
- ``EL3_PAYLOAD_BASE``: The reason is that you can already load anything to any - ``EL3_PAYLOAD_BASE``: The reason is that you can already load anything to any
address by changing the file ``armstub8.bin``, so there's no point in using address by changing the file ``armstub8.bin``, so there's no point in using
the Trusted Firmware in this case. TF-A in this case.
- ``LOAD_IMAGE_V2=0``: Only version 2 is supported. - ``LOAD_IMAGE_V2=0``: Only version 2 is supported.
...@@ -307,16 +305,16 @@ untouched). They have been tested with the image available in 2017-09-07. ...@@ -307,16 +305,16 @@ untouched). They have been tested with the image available in 2017-09-07.
1. Insert the SD card and open the ``boot`` partition. 1. Insert the SD card and open the ``boot`` partition.
2. Rename ``kernel7.img`` to ``kernel8.img``. This tricks the VideoCore 2. Rename ``kernel7.img`` to ``kernel8.img``. This tricks the VideoCore
bootloader into booting the Arm cores in AArch64 mode, like the Trusted bootloader into booting the Arm cores in AArch64 mode, like TF-A needs,
Firmware needs, even though the kernel is not compiled for AArch64. even though the kernel is not compiled for AArch64.
3. Copy ``armstub8.bin`` here. When ``kernel8.img`` is available, The VideoCore 3. Copy ``armstub8.bin`` here. When ``kernel8.img`` is available, The VideoCore
bootloader will look for a file called ``armstub8.bin`` and load it at bootloader will look for a file called ``armstub8.bin`` and load it at
address **0x0** instead of a predefined one. address **0x0** instead of a predefined one.
4. Open ``cmdline.txt`` and add ``memmap=256M$16M`` to prevent the kernel from 4. Open ``cmdline.txt`` and add ``memmap=256M$16M`` to prevent the kernel from
using the memory needed by the Trusted Firmware. If you want to enable the using the memory needed by TF-A. If you want to enable the serial port
serial port "Mini UART", make sure that this file also contains "Mini UART", make sure that this file also contains
``console=serial0,115200 console=tty1``. ``console=serial0,115200 console=tty1``.
Note that the 16 MiB reserved this way won't be available for Linux, the same Note that the 16 MiB reserved this way won't be available for Linux, the same
...@@ -359,6 +357,6 @@ HDMI output won't show any text during boot. ...@@ -359,6 +357,6 @@ HDMI output won't show any text during boot.
.. _Linux kernel tree: https://github.com/torvalds/linux .. _Linux kernel tree: https://github.com/torvalds/linux
.. _Linux tree fork: https://github.com/raspberrypi/linux .. _Linux tree fork: https://github.com/raspberrypi/linux
.. _Raspberry Pi 3: https://www.raspberrypi.org/products/raspberry-pi-3-model-b/ .. _Raspberry Pi 3: https://www.raspberrypi.org/products/raspberry-pi-3-model-b/
.. _Raspberry Pi 3 Arm Trusted Firmware bootstrap: https://github.com/AntonioND/rpi3-arm-tf-bootstrap .. _Raspberry Pi 3 TF-A bootstrap: https://github.com/AntonioND/rpi3-arm-tf-bootstrap
.. _Raspberry Pi 3 documentation: https://www.raspberrypi.org/documentation/ .. _Raspberry Pi 3 documentation: https://www.raspberrypi.org/documentation/
.. _Raspbian: https://www.raspberrypi.org/downloads/raspbian/ .. _Raspbian: https://www.raspberrypi.org/downloads/raspbian/
docs/plat/socionext-uniphier.rst
View file @ fb45044b
ARM Trusted Firmware for Socionext UniPhier SoCs Trusted Firmware-A for Socionext UniPhier SoCs
================================================ ==============================================
Socionext UniPhier ARMv8-A SoCs use ARM Trusted Firmware as the secure world Socionext UniPhier Armv8-A SoCs use Trusted Firmware-A (TF-A) as the secure
firmware, supporting BL2 and BL31. world firmware, supporting BL2 and BL31.
UniPhier SoC family implements its internal boot ROM, which loads 64KB [1]_ UniPhier SoC family implements its internal boot ROM, which loads 64KB [1]_
image from a non-volatile storage to the on-chip SRAM, and jumps over to it. image from a non-volatile storage to the on-chip SRAM, and jumps over to it.
ARM Trusted Firmware provides a special mode, BL2-AT-EL3, which enables BL2 to TF-A provides a special mode, BL2-AT-EL3, which enables BL2 to execute at EL3.
execute at EL3. It is useful for platforms with non-TF boot ROM, like UniPhier. It is useful for platforms with non-TF-A boot ROM, like UniPhier. Here, a
Here, a problem is BL2 does not fit in the 64KB limit if `Trusted Board Boot`_ problem is BL2 does not fit in the 64KB limit if `Trusted Board Boot`_ (TBB)
(TBB) is enabled. To solve this issue, Socionext provides a first stage loader is enabled. To solve this issue, Socionext provides a first stage loader
called `UniPhier BL`_. This loader runs in the on-chip SRAM, initializes the called `UniPhier BL`_. This loader runs in the on-chip SRAM, initializes the
DRAM, expands BL2 there, and hands the control over to it. Therefore, all images DRAM, expands BL2 there, and hands the control over to it. Therefore, all images
of ARM Trusted Firmware run in DRAM. of TF-A run in DRAM.
The UniPhier platform works with/without TBB. See below for the build process The UniPhier platform works with/without TBB. See below for the build process
of each case. The image authentication for the UniPhier platform fully of each case. The image authentication for the UniPhier platform fully
...@@ -46,7 +46,7 @@ Boot Flow ...@@ -46,7 +46,7 @@ Boot Flow
This runs in the DRAM. It extracts more images such as BL31, BL33 (optionally This runs in the DRAM. It extracts more images such as BL31, BL33 (optionally
SCP_BL2, BL32 as well) from Firmware Image Package (FIP). If TBB is enabled, SCP_BL2, BL32 as well) from Firmware Image Package (FIP). If TBB is enabled,
they are all authenticated by the standard mechanism of ARM Trusted Firmware. they are all authenticated by the standard mechanism of TF-A.
After loading all the images, it jumps to the BL31 entry. After loading all the images, it jumps to the BL31 entry.
4. BL31, BL32, and BL33 4. BL31, BL32, and BL33
......
docs/plat/xilinx-zynqmp.rst
View file @ fb45044b
ARM Trusted Firmware for Xilinx Zynq UltraScale+ MPSoC Trusted Firmware-A for Xilinx Zynq UltraScale+ MPSoC
====================================================== ====================================================
ARM Trusted Firmware implements the EL3 firmware layer for Xilinx Zynq Trusted Firmware-A (TF-A) implements the EL3 firmware layer for Xilinx Zynq
UltraScale + MPSoC. UltraScale + MPSoC.
The platform only uses the runtime part of ATF as ZynqMP already has a The platform only uses the runtime part of TF-A as ZynqMP already has a
BootROM (BL1) and FSBL (BL2). BootROM (BL1) and FSBL (BL2).
BL31 is ATF. BL31 is TF-A.
BL32 is an optional Secure Payload. BL32 is an optional Secure Payload.
BL33 is the non-secure world software (U-Boot, Linux etc). BL33 is the non-secure world software (U-Boot, Linux etc).
...@@ -35,20 +35,20 @@ ZynqMP platform specific build options ...@@ -35,20 +35,20 @@ ZynqMP platform specific build options
- ``cadence``, ``cadence0``: Cadence UART 0 - ``cadence``, ``cadence0``: Cadence UART 0
- ``cadence1`` : Cadence UART 1 - ``cadence1`` : Cadence UART 1
FSBL->ATF Parameter Passing FSBL->TF-A Parameter Passing
=========================== ===========================
The FSBL populates a data structure with image information for the ATF. The ATF The FSBL populates a data structure with image information for TF-A. TF-A uses
uses that data to hand off to the loaded images. The address of the handoff data that data to hand off to the loaded images. The address of the handoff data
structure is passed in the ``PMU_GLOBAL.GLOBAL_GEN_STORAGE6`` register. The structure is passed in the ``PMU_GLOBAL.GLOBAL_GEN_STORAGE6`` register. The
register is free to be used by other software once the ATF is bringing up register is free to be used by other software once TF-A has brought up
further firmware images. further firmware images.
Power Domain Tree Power Domain Tree
================= =================
The following power domain tree represents the power domain model used by the The following power domain tree represents the power domain model used by TF-A
ATF for ZynqMP: for ZynqMP:
:: ::
......
docs/platform-interrupt-controller-API.rst
View file @ fb45044b
...@@ -24,7 +24,7 @@ This API should return the priority of the interrupt the PE is currently ...@@ -24,7 +24,7 @@ This API should return the priority of the interrupt the PE is currently
servicing. This must be be called only after an interrupt has already been servicing. This must be be called only after an interrupt has already been
acknowledged via. ``plat_ic_acknowledge_interrupt``. acknowledged via. ``plat_ic_acknowledge_interrupt``.
In the case of ARM standard platforms using GIC, the *Running Priority Register* In the case of Arm standard platforms using GIC, the *Running Priority Register*
is read to determine the priority of the interrupt. is read to determine the priority of the interrupt.
Function: int plat_ic_is_spi(unsigned int id); [optional] Function: int plat_ic_is_spi(unsigned int id); [optional]
...@@ -77,7 +77,7 @@ Function: unsigned int plat_ic_get_interrupt_active(unsigned int id); [optional] ...@@ -77,7 +77,7 @@ Function: unsigned int plat_ic_get_interrupt_active(unsigned int id); [optional]
This API should return the *active* status of the interrupt ID specified by the This API should return the *active* status of the interrupt ID specified by the
first parameter, ``id``. first parameter, ``id``.
In case of ARM standard platforms using GIC, the implementation of the API reads In case of Arm standard platforms using GIC, the implementation of the API reads
the GIC *Set Active Register* to read and return the active status of the the GIC *Set Active Register* to read and return the active status of the
interrupt. interrupt.
...@@ -92,7 +92,7 @@ Function: void plat_ic_enable_interrupt(unsigned int id); [optional] ...@@ -92,7 +92,7 @@ Function: void plat_ic_enable_interrupt(unsigned int id); [optional]
This API should enable the interrupt ID specified by the first parameter, This API should enable the interrupt ID specified by the first parameter,
``id``. PEs in the system are expected to receive only enabled interrupts. ``id``. PEs in the system are expected to receive only enabled interrupts.
In case of ARM standard platforms using GIC, the implementation of the API In case of Arm standard platforms using GIC, the implementation of the API
inserts barrier to make memory updates visible before enabling interrupt, and inserts barrier to make memory updates visible before enabling interrupt, and
then writes to GIC *Set Enable Register* to enable the interrupt. then writes to GIC *Set Enable Register* to enable the interrupt.
...@@ -107,7 +107,7 @@ Function: void plat_ic_disable_interrupt(unsigned int id); [optional] ...@@ -107,7 +107,7 @@ Function: void plat_ic_disable_interrupt(unsigned int id); [optional]
This API should disable the interrupt ID specified by the first parameter, This API should disable the interrupt ID specified by the first parameter,
``id``. PEs in the system are not expected to receive disabled interrupts. ``id``. PEs in the system are not expected to receive disabled interrupts.
In case of ARM standard platforms using GIC, the implementation of the API In case of Arm standard platforms using GIC, the implementation of the API
writes to GIC *Clear Enable Register* to disable the interrupt, and inserts writes to GIC *Clear Enable Register* to disable the interrupt, and inserts
barrier to make memory updates visible afterwards. barrier to make memory updates visible afterwards.
...@@ -123,7 +123,7 @@ Function: void plat_ic_set_interrupt_priority(unsigned int id, unsigned int prio ...@@ -123,7 +123,7 @@ Function: void plat_ic_set_interrupt_priority(unsigned int id, unsigned int prio
This API should set the priority of the interrupt specified by first parameter This API should set the priority of the interrupt specified by first parameter
``id`` to the value set by the second parameter ``priority``. ``id`` to the value set by the second parameter ``priority``.
In case of ARM standard platforms using GIC, the implementation of the API In case of Arm standard platforms using GIC, the implementation of the API
writes to GIC *Priority Register* set interrupt priority. writes to GIC *Priority Register* set interrupt priority.
Function: int plat_ic_has_interrupt_type(unsigned int type); [optional] Function: int plat_ic_has_interrupt_type(unsigned int type); [optional]
...@@ -138,10 +138,10 @@ This API should return whether the platform supports a given interrupt type. The ...@@ -138,10 +138,10 @@ This API should return whether the platform supports a given interrupt type. The
parameter ``type`` shall be one of ``INTR_TYPE_EL3``, ``INTR_TYPE_S_EL1``, or parameter ``type`` shall be one of ``INTR_TYPE_EL3``, ``INTR_TYPE_S_EL1``, or
``INTR_TYPE_NS``. ``INTR_TYPE_NS``.
In case of ARM standard platforms using GICv3, the implementation of the API In case of Arm standard platforms using GICv3, the implementation of the API
returns ``1`` for all interrupt types. returns ``1`` for all interrupt types.
In case of ARM standard platforms using GICv2, the API always return ``1`` for In case of Arm standard platforms using GICv2, the API always return ``1`` for
``INTR_TYPE_NS``. Return value for other types depends on the value of build ``INTR_TYPE_NS``. Return value for other types depends on the value of build
option ``GICV2_G0_FOR_EL3``: option ``GICV2_G0_FOR_EL3``:
...@@ -180,7 +180,7 @@ one of: ...@@ -180,7 +180,7 @@ one of:
- ``INTR_TYPE_EL3``: interrupt is meant to be consumed by EL3. - ``INTR_TYPE_EL3``: interrupt is meant to be consumed by EL3.
In case of ARM standard platforms using GIC, the implementation of the API In case of Arm standard platforms using GIC, the implementation of the API
writes to the GIC *Group Register* and *Group Modifier Register* (only GICv3) to writes to the GIC *Group Register* and *Group Modifier Register* (only GICv3) to
assign the interrupt to the right group. assign the interrupt to the right group.
...@@ -213,7 +213,7 @@ This API should raise an EL3 SGI. The first parameter, ``sgi_num``, specifies ...@@ -213,7 +213,7 @@ This API should raise an EL3 SGI. The first parameter, ``sgi_num``, specifies
the ID of the SGI. The second parameter, ``target``, must be the MPIDR of the the ID of the SGI. The second parameter, ``target``, must be the MPIDR of the
target PE. target PE.
In case of ARM standard platforms using GIC, the implementation of the API In case of Arm standard platforms using GIC, the implementation of the API
inserts barrier to make memory updates visible before raising SGI, then writes inserts barrier to make memory updates visible before raising SGI, then writes
to appropriate *SGI Register* in order to raise the EL3 SGI. to appropriate *SGI Register* in order to raise the EL3 SGI.
...@@ -239,7 +239,7 @@ The ``routing_mode`` parameter can be one of: ...@@ -239,7 +239,7 @@ The ``routing_mode`` parameter can be one of:
- ``INTR_ROUTING_MODE_PE`` means the interrupt is routed to the PE whose MPIDR - ``INTR_ROUTING_MODE_PE`` means the interrupt is routed to the PE whose MPIDR
value is specified by the parameter ``mpidr``. value is specified by the parameter ``mpidr``.
In case of ARM standard platforms using GIC, the implementation of the API In case of Arm standard platforms using GIC, the implementation of the API
writes to the GIC *Target Register* (GICv2) or *Route Register* (GICv3) to set writes to the GIC *Target Register* (GICv2) or *Route Register* (GICv3) to set
the routing. the routing.
...@@ -254,7 +254,7 @@ Function: void plat_ic_set_interrupt_pending(unsigned int id); [optional] ...@@ -254,7 +254,7 @@ Function: void plat_ic_set_interrupt_pending(unsigned int id); [optional]
This API should set the interrupt specified by first parameter ``id`` to This API should set the interrupt specified by first parameter ``id`` to
*Pending*. *Pending*.
In case of ARM standard platforms using GIC, the implementation of the API In case of Arm standard platforms using GIC, the implementation of the API
inserts barrier to make memory updates visible before setting interrupt pending, inserts barrier to make memory updates visible before setting interrupt pending,
and writes to the GIC *Set Pending Register* to set the interrupt pending and writes to the GIC *Set Pending Register* to set the interrupt pending
status. status.
...@@ -270,7 +270,7 @@ Function: void plat_ic_clear_interrupt_pending(unsigned int id); [optional] ...@@ -270,7 +270,7 @@ Function: void plat_ic_clear_interrupt_pending(unsigned int id); [optional]
This API should clear the *Pending* status of the interrupt specified by first This API should clear the *Pending* status of the interrupt specified by first
parameter ``id``. parameter ``id``.
In case of ARM standard platforms using GIC, the implementation of the API In case of Arm standard platforms using GIC, the implementation of the API
writes to the GIC *Clear Pending Register* to clear the interrupt pending writes to the GIC *Clear Pending Register* to clear the interrupt pending
status, and inserts barrier to make memory updates visible afterwards. status, and inserts barrier to make memory updates visible afterwards.
...@@ -287,7 +287,7 @@ controller such that only interrupts of higher priority than the supplied one ...@@ -287,7 +287,7 @@ controller such that only interrupts of higher priority than the supplied one
may be signalled to the PE. The API should return the current priority value may be signalled to the PE. The API should return the current priority value
that it's overwriting. that it's overwriting.
In case of ARM standard platforms using GIC, the implementation of the API In case of Arm standard platforms using GIC, the implementation of the API
inserts to order memory updates before updating mask, then writes to the GIC inserts to order memory updates before updating mask, then writes to the GIC
*Priority Mask Register*, and make sure memory updates are visible before *Priority Mask Register*, and make sure memory updates are visible before
potential trigger due to mask update. potential trigger due to mask update.
...@@ -305,9 +305,9 @@ obtained by the acknowledging the interrupt (read using ...@@ -305,9 +305,9 @@ obtained by the acknowledging the interrupt (read using
``plat_ic_acknowledge_interrupt()``). If the interrupt ID is invalid, this API ``plat_ic_acknowledge_interrupt()``). If the interrupt ID is invalid, this API
should return ``INTR_ID_UNAVAILABLE``. should return ``INTR_ID_UNAVAILABLE``.
In case of ARM standard platforms using GIC, the implementation of the API In case of Arm standard platforms using GIC, the implementation of the API
masks out the interrupt ID field from the acknowledged value from GIC. masks out the interrupt ID field from the acknowledged value from GIC.
---- ----
*Copyright (c) 2017, ARM Limited and Contributors. All rights reserved.* *Copyright (c) 2017-2018, Arm Limited and Contributors. All rights reserved.*
docs/platform-migration-guide.rst
View file @ fb45044b
...@@ -12,8 +12,8 @@ Guide to migrate to new Platform porting interface ...@@ -12,8 +12,8 @@ Guide to migrate to new Platform porting interface
Introduction Introduction
------------ ------------
The PSCI implementation in Trusted Firmware has undergone a redesign because of The PSCI implementation in TF-A has undergone a redesign because of three
three requirements that the PSCI 1.0 specification introduced : requirements that the PSCI 1.0 specification introduced :
- Removing the framework assumption about the structure of the MPIDR, and - Removing the framework assumption about the structure of the MPIDR, and
its relation to the power topology enables support for deeper and more its relation to the power topology enables support for deeper and more
...@@ -217,7 +217,7 @@ layer and the platform layer. ...@@ -217,7 +217,7 @@ layer and the platform layer.
Refer `plat/arm/board/fvp/fvp\_pm.c`_ for the implementation details of Refer `plat/arm/board/fvp/fvp\_pm.c`_ for the implementation details of
these handlers for the FVP. The commit `38dce70f51fb83b27958ba3e2ad15f5635cb1061`_ these handlers for the FVP. The commit `38dce70f51fb83b27958ba3e2ad15f5635cb1061`_
demonstrates the migration of ARM reference platforms to the new platform API. demonstrates the migration of Arm reference platforms to the new platform API.
Miscellaneous modifications Miscellaneous modifications
--------------------------- ---------------------------
...@@ -271,7 +271,7 @@ within its domain. It does so by storing the core index of first core ...@@ -271,7 +271,7 @@ within its domain. It does so by storing the core index of first core
within it and number of core indexes following it. This means that core within it and number of core indexes following it. This means that core
indices returned by ``platform_get_core_pos()`` for cores within a particular indices returned by ``platform_get_core_pos()`` for cores within a particular
power domain must be consecutive. We expect that this is the case for most power domain must be consecutive. We expect that this is the case for most
platform ports including ARM reference platforms. platform ports including Arm reference platforms.
The old PSCI helpers like ``psci_get_suspend_powerstate()``, The old PSCI helpers like ``psci_get_suspend_powerstate()``,
``psci_get_suspend_stateid()``, ``psci_get_suspend_stateid_by_mpidr()``, ``psci_get_suspend_stateid()``, ``psci_get_suspend_stateid_by_mpidr()``,
...@@ -298,7 +298,7 @@ The mandatory macros to be defined by the platform port in ``platform_def.h`` ...@@ -298,7 +298,7 @@ The mandatory macros to be defined by the platform port in ``platform_def.h``
- **#define : PLATFORM\_MAX\_AFFLVL** - **#define : PLATFORM\_MAX\_AFFLVL**
Defines the maximum affinity level that the power management operations Defines the maximum affinity level that the power management operations
should apply to. ARMv8-A has support for four affinity levels. It is likely should apply to. Armv8-A has support for four affinity levels. It is likely
that hardware will implement fewer affinity levels. This macro allows the that hardware will implement fewer affinity levels. This macro allows the
PSCI implementation to consider only those affinity levels in the system PSCI implementation to consider only those affinity levels in the system
that the platform implements. For example, the Base AEM FVP implements two that the platform implements. For example, the Base AEM FVP implements two
...@@ -329,7 +329,7 @@ to handle the condition where the core has been warm reset but there is no ...@@ -329,7 +329,7 @@ to handle the condition where the core has been warm reset but there is no
entrypoint to jump to. entrypoint to jump to.
This function does not follow the Procedure Call Standard used by the This function does not follow the Procedure Call Standard used by the
Application Binary Interface for the ARM 64-bit architecture. The caller should Application Binary Interface for the Arm 64-bit architecture. The caller should
not assume that callee saved registers are preserved across a call to this not assume that callee saved registers are preserved across a call to this
function. function.
...@@ -410,7 +410,7 @@ Modifications for Power State Coordination Interface (in BL31) ...@@ -410,7 +410,7 @@ Modifications for Power State Coordination Interface (in BL31)
-------------------------------------------------------------- --------------------------------------------------------------
The following functions must be implemented to initialize PSCI functionality in The following functions must be implemented to initialize PSCI functionality in
the ARM Trusted Firmware. TF-A.
Function : plat\_get\_aff\_count() [mandatory] Function : plat\_get\_aff\_count() [mandatory]
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
...@@ -595,7 +595,7 @@ PSCI specification for the CPU\_SUSPEND API. ...@@ -595,7 +595,7 @@ PSCI specification for the CPU\_SUSPEND API.
-------------- --------------
*Copyright (c) 2015, ARM Limited and Contributors. All rights reserved.* *Copyright (c) 2015-2018, Arm Limited and Contributors. All rights reserved.*
.. _PSCI: http://infocenter.arm.com/help/topic/com.arm.doc.den0022c/DEN0022C_Power_State_Coordination_Interface.pdf .. _PSCI: http://infocenter.arm.com/help/topic/com.arm.doc.den0022c/DEN0022C_Power_State_Coordination_Interface.pdf
.. _Porting Guide: porting-guide.rst#user-content-function--plat_my_core_pos .. _Porting Guide: porting-guide.rst#user-content-function--plat_my_core_pos
......
docs/porting-guide.rst
View file @ fb45044b
This diff is collapsed.
docs/psci-lib-integration-guide.rst
View file @ fb45044b
PSCI Library Integration guide for ARMv8-A AArch32 systems PSCI Library Integration guide for Armv8-A AArch32 systems
========================================================== ==========================================================
...@@ -8,7 +8,7 @@ PSCI Library Integration guide for ARMv8-A AArch32 systems ...@@ -8,7 +8,7 @@ PSCI Library Integration guide for ARMv8-A AArch32 systems
.. contents:: .. contents::
This document describes the PSCI library interface with a focus on how to 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 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 Library implements the PSCI Standard as described in `PSCI spec`_ and is meant
to be integrated with EL3 Runtime Software which invokes the PSCI Library to be integrated with EL3 Runtime Software which invokes the PSCI Library
interface appropriately. **EL3 Runtime Software** refers to software executing interface appropriately. **EL3 Runtime Software** refers to software executing
...@@ -17,9 +17,10 @@ Monitor mode in AArch32, and provides runtime services to the non-secure world. ...@@ -17,9 +17,10 @@ Monitor mode in AArch32, and provides runtime services to the non-secure world.
The runtime service request is made via SMC (Secure Monitor Call) and the call The runtime service request is made via SMC (Secure Monitor Call) and the call
must adhere to `SMCCC`_. In AArch32, EL3 Runtime Software may additionally must adhere to `SMCCC`_. In AArch32, EL3 Runtime Software may additionally
include Trusted OS functionality. A minimal AArch32 Secure Payload, SP-MIN, is include Trusted OS functionality. A minimal AArch32 Secure Payload, SP-MIN, is
provided in ARM Trusted Firmware to illustrate the usage and integration of the provided in Trusted Firmware-A (TF-A) to illustrate the usage and integration
PSCI library. The description of PSCI library interface and its integration of the PSCI library. The description of PSCI library interface and its
with EL3 Runtime Software in this document is targeted towards AArch32 systems. integration with EL3 Runtime Software in this document is targeted towards
AArch32 systems.
Generic call sequence for PSCI Library interface (AArch32) Generic call sequence for PSCI Library interface (AArch32)
---------------------------------------------------------- ----------------------------------------------------------
...@@ -315,7 +316,7 @@ Software must provide an SMC handling framework capable of MP adhering to ...@@ -315,7 +316,7 @@ Software must provide an SMC handling framework capable of MP adhering to
The EL3 Runtime Software must also export cache maintenance primitives The EL3 Runtime Software must also export cache maintenance primitives
and some helper utilities for assert, print and memory operations as listed and some helper utilities for assert, print and memory operations as listed
below. The ARM Trusted Firmware source tree provides implementations for all below. The TF-A source tree provides implementations for all
these functions but the EL3 Runtime Software may use its own implementation. these functions but the EL3 Runtime Software may use its own implementation.
**Functions : assert(), memcpy(), memset** **Functions : assert(), memcpy(), memset**
...@@ -355,10 +356,10 @@ failure that cannot be recovered from. This function **must not** return. ...@@ -355,10 +356,10 @@ failure that cannot be recovered from. This function **must not** return.
**Function : tf\_printf()** **Function : tf\_printf()**
This is printf-compatible function, but unlike printf, it does not return any This is printf-compatible function, but unlike printf, it does not return any
value. The ARM Trusted Firmware source tree provides an implementation which value. The TF-A source tree provides an implementation which
is optimized for stack usage and supports only a subset of format specifiers. is optimized for stack usage and supports only a subset of format specifiers.
The details of the format specifiers supported can be found in the The details of the format specifiers supported can be found in the
``tf_printf.c`` file in ARM Trusted Firmware source tree. ``tf_printf.c`` file in the TF-A source tree.
CPU Context management API CPU Context management API
~~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~
...@@ -537,7 +538,8 @@ CPU operations ...@@ -537,7 +538,8 @@ CPU operations
~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~
The CPU operations (cpu\_ops) framework implement power down sequence specific The CPU operations (cpu\_ops) framework implement power down sequence specific
to the CPU and the details of which can be found in the ``CPU specific operations framework`` section of `Firmware Design`_. The ARM Trusted Firmware to the CPU and the details of which can be found in the
``CPU specific operations framework`` section of `Firmware Design`_. The TF-A
tree implements the ``cpu_ops`` for various supported CPUs and the EL3 Runtime tree implements the ``cpu_ops`` for various supported CPUs and the EL3 Runtime
Software needs to include the required ``cpu_ops`` in its build. The start and Software needs to include the required ``cpu_ops`` in its build. The start and
end of the ``cpu_ops`` descriptors must be exported by the EL3 Runtime Software end of the ``cpu_ops`` descriptors must be exported by the EL3 Runtime Software
...@@ -550,7 +552,7 @@ workarounds. ...@@ -550,7 +552,7 @@ workarounds.
-------------- --------------
*Copyright (c) 2016, ARM Limited and Contributors. All rights reserved.* *Copyright (c) 2016-2018, Arm Limited and Contributors. All rights reserved.*
.. _PSCI spec: http://infocenter.arm.com/help/topic/com.arm.doc.den0022c/DEN0022C_Power_State_Coordination_Interface.pdf .. _PSCI spec: http://infocenter.arm.com/help/topic/com.arm.doc.den0022c/DEN0022C_Power_State_Coordination_Interface.pdf
.. _SMCCC: https://silver.arm.com/download/ARM_and_AMBA_Architecture/AR570-DA-80002-r0p0-00rel0/ARM_DEN0028A_SMC_Calling_Convention.pdf .. _SMCCC: https://silver.arm.com/download/ARM_and_AMBA_Architecture/AR570-DA-80002-r0p0-00rel0/ARM_DEN0028A_SMC_Calling_Convention.pdf
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment