diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/arm-sip-service.rst | 2 | ||||
| -rw-r--r-- | docs/cpu-specific-build-macros.rst | 59 | ||||
| -rw-r--r-- | docs/exception-handling.rst | 14 | ||||
| -rw-r--r-- | docs/firmware-design.rst | 22 | ||||
| -rw-r--r-- | docs/plat/intel-stratix10.rst | 91 | ||||
| -rw-r--r-- | docs/platform-interrupt-controller-API.rst | 2 | ||||
| -rw-r--r-- | docs/porting-guide.rst | 18 | ||||
| -rw-r--r-- | docs/ras.rst | 12 | ||||
| -rw-r--r-- | docs/sdei.rst | 4 | ||||
| -rw-r--r-- | docs/user-guide.rst | 39 |
10 files changed, 226 insertions, 37 deletions
diff --git a/docs/arm-sip-service.rst b/docs/arm-sip-service.rst index 9f0e26615..6cdac8357 100644 --- a/docs/arm-sip-service.rst +++ b/docs/arm-sip-service.rst @@ -4,7 +4,7 @@ Arm SiP Service This document enumerates and describes the Arm SiP (Silicon Provider) services. 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") instruction executed from Exception Levels below EL3. SMC calls for SiP services: diff --git a/docs/cpu-specific-build-macros.rst b/docs/cpu-specific-build-macros.rst index 315457a19..95538d02b 100644 --- a/docs/cpu-specific-build-macros.rst +++ b/docs/cpu-specific-build-macros.rst @@ -73,9 +73,18 @@ will enable it. For Cortex-A53, the following errata build flags are defined : +- ``ERRATA_A53_819472``: This applies errata 819472 workaround to all + CPUs. This needs to be enabled only for revision <= r0p1 of Cortex-A53. + +- ``ERRATA_A53_824069``: This applies errata 824069 workaround to all + CPUs. This needs to be enabled only for revision <= r0p2 of Cortex-A53. + - ``ERRATA_A53_826319``: This applies errata 826319 workaround to Cortex-A53 CPU. This needs to be enabled only for revision <= r0p2 of the CPU. +- ``ERRATA_A53_827319``: This applies errata 827319 workaround to all + CPUs. This needs to be enabled only for revision <= r0p2 of Cortex-A53. + - ``ERRATA_A53_835769``: This applies erratum 835769 workaround at compile and link time to Cortex-A53 CPU. This needs to be enabled for some variants of revision <= r0p4. This workaround can lead the linker to create ``*.stub`` @@ -97,6 +106,23 @@ For Cortex-A53, the following errata build flags are defined : Earlier revisions of the CPU have other errata which require the same workaround in software, so they should be covered anyway. +For Cortex-A55, the following errata build flags are defined : + +- ``ERRATA_A55_768277``: This applies errata 768277 workaround to Cortex-A55 + CPU. This needs to be enabled only for revision r0p0 of the CPU. + +- ``ERRATA_A55_778703``: This applies errata 778703 workaround to Cortex-A55 + CPU. This needs to be enabled only for revision r0p0 of the CPU. + +- ``ERRATA_A55_798797``: This applies errata 798797 workaround to Cortex-A55 + CPU. This needs to be enabled only for revision r0p0 of the CPU. + +- ``ERRATA_A55_846532``: This applies errata 846532 workaround to Cortex-A55 + CPU. This needs to be enabled only for revision <= r0p1 of the CPU. + +- ``ERRATA_A55_903758``: This applies errata 903758 workaround to Cortex-A55 + CPU. This needs to be enabled only for revision <= r0p1 of the CPU. + For Cortex-A57, the following errata build flags are defined : - ``ERRATA_A57_806969``: This applies errata 806969 workaround to Cortex-A57 @@ -108,6 +134,12 @@ For Cortex-A57, the following errata build flags are defined : - ``ERRATA_A57_813420``: This applies errata 813420 workaround to Cortex-A57 CPU. This needs to be enabled only for revision r0p0 of the CPU. +- ``ERRATA_A57_814670``: This applies errata 814670 workaround to Cortex-A57 + CPU. This needs to be enabled only for revision r0p0 of the CPU. + +- ``ERRATA_A57_817169``: This applies errata 817169 workaround to Cortex-A57 + CPU. This needs to be enabled only for revision <= r0p1 of the CPU. + - ``ERRATA_A57_826974``: This applies errata 826974 workaround to Cortex-A57 CPU. This needs to be enabled only for revision <= r1p1 of the CPU. @@ -132,6 +164,33 @@ For Cortex-A72, the following errata build flags are defined : - ``ERRATA_A72_859971``: This applies errata 859971 workaround to Cortex-A72 CPU. This needs to be enabled only for revision <= r0p3 of the CPU. +For Cortex-A73, the following errata build flags are defined : + +- ``ERRATA_A73_852427``: This applies errata 852427 workaround to Cortex-A73 + CPU. This needs to be enabled only for revision r0p0 of the CPU. + +- ``ERRATA_A73_855423``: This applies errata 855423 workaround to Cortex-A73 + CPU. This needs to be enabled only for revision <= r0p1 of the CPU. + +For Cortex-A75, the following errata build flags are defined : + +- ``ERRATA_A75_764081``: This applies errata 764081 workaround to Cortex-A75 + CPU. This needs to be enabled only for revision r0p0 of the CPU. + +- ``ERRATA_A75_790748``: This applies errata 790748 workaround to Cortex-A75 + CPU. This needs to be enabled only for revision r0p0 of the CPU. + +For Cortex-A76, the following errata build flags are defined : + +- ``ERRATA_A76_1073348``: This applies errata 1073348 workaround to Cortex-A76 + CPU. This needs to be enabled only for revision <= r1p0 of the CPU. + +- ``ERRATA_A76_1130799``: This applies errata 1130799 workaround to Cortex-A76 + CPU. This needs to be enabled only for revision <= r2p0 of the CPU. + +- ``ERRATA_A76_1220197``: This applies errata 1220197 workaround to Cortex-A76 + CPU. This needs to be enabled only for revision <= r2p0 of the CPU. + DSU Errata Workarounds ---------------------- diff --git a/docs/exception-handling.rst b/docs/exception-handling.rst index dbcd4bca8..b7cd69d4c 100644 --- a/docs/exception-handling.rst +++ b/docs/exception-handling.rst @@ -233,7 +233,7 @@ Note: The ``ARRAY_SIZE()`` macro therefore should be used to determine the size of array. -Finally, this array of descriptors is exposed to |EHF| via. the +Finally, this array of descriptors is exposed to |EHF| via the ``EHF_REGISTER_PRIORITIES()`` macro. Refer to the `Interrupt handling example`_ for usage. See also: `Interrupt @@ -379,8 +379,8 @@ Activating and Deactivating priorities A priority level is said to be *active* when an exception of that priority is being handled: for interrupts, this is implied when the interrupt is -acknowledged; for non-interrupt exceptions, viz. SErrors or `SDEI explicit -dispatches`__, this has to be done via. calling ``ehf_activate_priority()``. See +acknowledged; for non-interrupt exceptions, such as SErrors or `SDEI explicit +dispatches`__, this has to be done via calling ``ehf_activate_priority()``. See `Run-time flow`_. .. __: sdei.rst#explicit-dispatch-of-events @@ -388,7 +388,7 @@ dispatches`__, this has to be done via. calling ``ehf_activate_priority()``. See Conversely, when the dispatcher has reached a logical resolution for the cause of the exception, the corresponding priority level ought to be deactivated. As above, for interrupts, this is implied when the interrupt is EOId in the GIC; -for other exceptions, this has to be done via. calling +for other exceptions, this has to be done via calling ``ehf_deactivate_priority()``. Thanks to `different provisions`__ for exception delegation, there are @@ -405,7 +405,7 @@ potentially more than one work flow for deactivation: - The dispatcher has to delegate the execution to lower ELs, and the cause of the exception can be considered resolved only when the lower EL returns - signals complete (via. an ``SMC``) at a future point in time. The following + signals complete (via an ``SMC``) at a future point in time. The following sequence ensues: #. The dispatcher calls ``setjmp()`` to setup a jump point, and arranges to @@ -414,7 +414,7 @@ potentially more than one work flow for deactivation: #. Through the ensuing ``ERET`` from runtime firmware, execution is delegated to a lower EL. - #. The lower EL completes its execution, and signals completion via. an + #. The lower EL completes its execution, and signals completion via an ``SMC``. #. The ``SMC`` is handled by the same dispatcher that handled the exception @@ -597,7 +597,7 @@ world ones. The platform further assigns relative priorities amongst Secure dispatchers through |EHF|. As mentioned in `Partitioning priority levels`_, interrupts targeting distinct -dispatchers fall in distinct priority levels. Because they're routed via. the +dispatchers fall in distinct priority levels. Because they're routed via the GIC, interrupt delivery to the PE is subject to GIC prioritisation rules. In particular, when an interrupt is being handled by the PE (i.e., the interrupt is in *Active* state), only interrupts of higher priority are signalled to the PE, diff --git a/docs/firmware-design.rst b/docs/firmware-design.rst index 299654fc2..266de2795 100644 --- a/docs/firmware-design.rst +++ b/docs/firmware-design.rst @@ -1282,9 +1282,9 @@ interrupt configuration during the driver initialisation. Secure interrupt configuration are specified in an array of secure interrupt properties. In this scheme, in both GICv2 and GICv3 driver data structures, the ``interrupt_props`` member points to an array of interrupt properties. Each -element of the array specifies the interrupt number and its configuration, viz. -priority, group, configuration. Each element of the array shall be populated by -the macro ``INTR_PROP_DESC()``. The macro takes the following arguments: +element of the array specifies the interrupt number and its attributes +(priority, group, configuration). Each element of the array shall be populated +by the macro ``INTR_PROP_DESC()``. The macro takes the following arguments: - 10-bit interrupt number, @@ -1439,7 +1439,7 @@ C run time. Therefore it must follow AAPCS, and must not use stack. CPU drivers that apply errata workaround can optionally implement an assembly function that report the status of errata workarounds pertaining to that CPU. -For a driver that registers the CPU, for example, ``cpux`` via. ``declare_cpu_ops`` +For a driver that registers the CPU, for example, ``cpux`` via ``declare_cpu_ops`` macro, the errata reporting function, if it exists, must be named ``cpux_errata_report``. This function will always be called with MMU enabled; it must follow AAPCS and may use stack. @@ -2558,8 +2558,18 @@ Armv8.2-A Armv8.3-A ~~~~~~~~~ -- Pointer Authentication features of Armv8.3-A are unconditionally enabled so - that lower ELs are allowed to use them without causing a trap to EL3. +- Pointer authentication features of Armv8.3-A are unconditionally enabled in + the Non-secure world so that lower ELs are allowed to use them without + causing a trap to EL3. + + In order to enable the Secure world to use it, ``CTX_INCLUDE_PAUTH_REGS`` + must be set to 1. This will add all pointer authentication system registers + to the context that is saved when doing a world switch. + + The Trusted Firmware itself has support for pointer authentication at runtime + that can be enabled by setting both options ``ENABLE_PAUTH`` and + ``CTX_INCLUDE_PAUTH_REGS`` to 1. This enables pointer authentication in BL1, + BL2, BL31, and the TSP if it is used. Armv7-A ~~~~~~~ diff --git a/docs/plat/intel-stratix10.rst b/docs/plat/intel-stratix10.rst new file mode 100644 index 000000000..9a3c89252 --- /dev/null +++ b/docs/plat/intel-stratix10.rst @@ -0,0 +1,91 @@ +Description +=========== + +Stratix 10 SoCFPGA is a FPGA with integrated quad-core 64-bit Arm Cortex A53 processor. + +Upon boot, Boot ROM loads bl2 into OCRAM. Bl2 subsequently initializes +the hardware, then loads bl31 and bl33 (UEFI) into DDR and boots to bl33. + +:: + + Boot ROM --> Trusted Firmware-A --> UEFI + +How to build +============ + +Code Locations +-------------- + +- Trusted Firmware-A: + `link <https://github.com/ARM-software/arm-trusted-firmware>`__ + +- UEFI (to be updated with new upstreamed UEFI): + `link <https://github.com/altera-opensource/uefi-socfpga>`__ + +Build Procedure +--------------- + +- Fetch all the above 2 repositories into local host. + Make all the repositories in the same ${BUILD\_PATH}. + +- Prepare the AARCH64 toolchain. + +- Build UEFI using Stratix 10 platform as configuration + This will be updated to use an updated UEFI using the latest EDK2 source + +.. code:: bash + + make CROSS_COMPILE=aarch64-linux-gnu- device=s10 + +- Build atf providing the previously generated UEFI as the BL33 image + +.. code:: bash + + make CROSS_COMPILE=aarch64-linux-gnu- bl2 fip PLAT=stratix10 + BL33=PEI.ROM + +Install Procedure +----------------- + +- dd fip.bin to a A2 partition on the MMC drive to be booted in Stratix 10 + board. + +- Generate a SOF containing bl2 + +.. code:: bash + aarch64-linux-gnu-objcopy -I binary -O ihex --change-addresses 0xffe00000 bl2.bin bl2.hex + quartus_cpf --bootloader bl2.hex <quartus_generated_sof> <output_sof_with_bl2> + +- Configure SOF to board + +.. code:: bash + nios2-configure-sof <output_sof_with_bl2> + +Boot trace +========== + +:: + INFO: DDR: DRAM calibration success. + INFO: ECC is disabled. + INFO: Init HPS NOC's DDR Scheduler. + NOTICE: BL2: v2.0(debug):v2.0-809-g7f8474a-dirty + NOTICE: BL2: Built : 17:38:19, Feb 18 2019 + INFO: BL2: Doing platform setup + INFO: BL2: Loading image id 3 + INFO: Loading image id=3 at address 0xffe1c000 + INFO: Image id=3 loaded: 0xffe1c000 - 0xffe24034 + INFO: BL2: Loading image id 5 + INFO: Loading image id=5 at address 0x50000 + INFO: Image id=5 loaded: 0x50000 - 0x550000 + NOTICE: BL2: Booting BL31 + INFO: Entry point address = 0xffe1c000 + INFO: SPSR = 0x3cd + NOTICE: BL31: v2.0(debug):v2.0-810-g788c436-dirty + NOTICE: BL31: Built : 15:17:16, Feb 20 2019 + INFO: ARM GICv2 driver initialized + INFO: BL31: Initializing runtime services + WARNING: BL31: cortex_a53: CPU workaround for 855873 was missing! + INFO: BL31: Preparing for EL3 exit to normal world + INFO: Entry point address = 0x50000 + INFO: SPSR = 0x3c9 + UEFI firmware (version 1.0 built at 11:26:18 on Nov 7 2018) diff --git a/docs/platform-interrupt-controller-API.rst b/docs/platform-interrupt-controller-API.rst index 230a99055..ad68709a3 100644 --- a/docs/platform-interrupt-controller-API.rst +++ b/docs/platform-interrupt-controller-API.rst @@ -22,7 +22,7 @@ Function: unsigned int plat_ic_get_running_priority(void); [optional] 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 -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* is read to determine the priority of the interrupt. diff --git a/docs/porting-guide.rst b/docs/porting-guide.rst index 7a3963bda..3ea86b04f 100644 --- a/docs/porting-guide.rst +++ b/docs/porting-guide.rst @@ -1792,6 +1792,22 @@ defined by the translation library, and can be found in the file On DynamIQ systems, this function must not use stack while enabling MMU, which is how the function in xlat table library version 2 is implemented. +Function : plat_init_apiakey [optional] +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +:: + + Argument : void + Return : uint64_t * + +This function populates the ``plat_apiakey`` array that contains the values used +to set the ``APIAKey{Hi,Lo}_EL1`` registers. It returns a pointer to this array. + +The value should be obtained from a reliable source of randomness. + +This function is only needed if ARMv8.3 pointer authentication is used in the +Trusted Firmware by building with ``ENABLE_PAUTH=1``. + Function : plat_get_syscnt_freq2() [mandatory] ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -1920,7 +1936,7 @@ handler (if present) is called for the CPU power domain. The ``power-state`` parameter of a PSCI ``CPU_SUSPEND`` call can be used to describe composite power states specific to a platform. The PSCI implementation -defines a generic representation of the power-state parameter viz which is an +defines a generic representation of the power-state parameter, which is an array of local power states where each index corresponds to a power domain level. Each entry contains the local power state the power domain at that power level could enter. It depends on the ``validate_power_state()`` handler to diff --git a/docs/ras.rst b/docs/ras.rst index cea74e9af..ac4d019f1 100644 --- a/docs/ras.rst +++ b/docs/ras.rst @@ -15,10 +15,10 @@ Serviceability (RAS) extensions. RAS is a mandatory extension for Armv8.2 and later CPUs, and also an optional extension to the base Armv8.0 architecture. In conjunction with the |EHF|, support for RAS extension enables firmware-first -paradigm for handling platform errors, in which exceptions resulting from -errors—viz. Synchronous External Abort (SEA), Asynchronous External Abort -(signalled as SErrors), Fault Handling and Error Recovery interrupts are routed -to and handled in EL3. The |EHF| document mentions various `error handling +paradigm for handling platform errors: exceptions resulting from errors are +routed to and handled in EL3. Said errors are Synchronous External Abort (SEA), +Asynchronous External Abort (signalled as SErrors), Fault Handling and Error +Recovery interrupts. The |EHF| document mentions various `error handling use-cases`__. .. __: exception-handling.rst#delegation-use-cases @@ -66,7 +66,7 @@ through one one of the notification mechanisms—SEAs, SErrors, or interrupts. R nodes contain one or more error records, which are registers through which the nodes advertise various properties of the signalled error. Arm recommends that error records are implemented in the Standard Error Record format. The RAS -architecture allows for error records to be accessible via. system or +architecture allows for error records to be accessible via system or memory-mapped registers. The platform should enumerate the error records providing for each of them: @@ -121,7 +121,7 @@ The error handler must have the following prototype: int probe_data, const struct err_handler_data *const data); The ``data`` constant parameter describes the various properties of the error, -viz. the reason for the error, exception syndrome, and also ``flags``, +including the reason for the error, exception syndrome, and also ``flags``, ``cookie``, and ``handle`` parameters from the `top-level exception handler`__. .. __: interrupt-framework-design.rst#el3-interrupts diff --git a/docs/sdei.rst b/docs/sdei.rst index 531145f87..c52481706 100644 --- a/docs/sdei.rst +++ b/docs/sdei.rst @@ -142,7 +142,7 @@ Event flags describe the properties of the event. They are bit maps that can be .. __: `Defining events`_ - ``SDEI_MAPF_DYNAMIC``: Marks the event as dynamic. Dynamic events can be - bound to (or released from) any Non-secure interrupt at runtime via. the + bound to (or released from) any Non-secure interrupt at runtime via the ``SDEI_INTERRUPT_BIND`` and ``SDEI_INTERRUPT_RELEASE`` calls. - ``SDEI_MAPF_BOUND``: Marks the event as statically bound to an interrupt. @@ -226,7 +226,7 @@ Explicit dispatch of events Typically, an SDEI event dispatch is caused by the PE receiving interrupts that are bound to an SDEI event. However, there are cases where the Secure world requires dispatch of an SDEI event as a direct or indirect result of a past -activity, viz. receiving a Secure interrupt or an exception. +activity, such as receiving a Secure interrupt or an exception. The SDEI dispatcher implementation provides ``sdei_dispatch_event()`` API for this purpose. The API has the following signature: diff --git a/docs/user-guide.rst b/docs/user-guide.rst index 03cce7d1a..d3c63c751 100644 --- a/docs/user-guide.rst +++ b/docs/user-guide.rst @@ -358,6 +358,12 @@ Common build options registers to be included when saving and restoring the CPU context. Default is 0. +- ``CTX_INCLUDE_PAUTH_REGS``: Boolean option that, when set to 1, will cause + the ARMv8.3-PAuth registers to be included when saving and restoring the CPU + context. Note that if the hardware supports this extension and this option is + set to 0 the value of the registers will be leaked between Secure and + Non-secure worlds if PAuth is used on both sides. The default is 0. + - ``DEBUG``: Chooses between a debug and release build. It can take either 0 (release) or 1 (debug) as values. 0 is the default. @@ -405,6 +411,13 @@ Common build options partitioning in EL3, however. Platform initialisation code should configure and use partitions in EL3 as required. This option defaults to ``0``. +- ``ENABLE_PAUTH``: Boolean option to enable ARMv8.3 Pointer Authentication + (``ARMv8.3-PAuth``) support in the Trusted Firmware itself. Note that this + option doesn't affect the saving of the registers introduced with this + extension, they are always saved if they are detected regardless of the value + of this option. If enabled, it is needed to use a compiler that supports the + option ``-msign-return-address``. It defaults to 0. + - ``ENABLE_PIE``: Boolean option to enable Position Independent Executable(PIE) support within generic code in TF-A. This option is currently only supported in BL31. Default is 0. @@ -535,13 +548,13 @@ Common build options - ``KEY_ALG``: This build flag enables the user to select the algorithm to be used for generating the PKCS keys and subsequent signing of the certificate. - It accepts 3 values viz. ``rsa``, ``rsa_1_5``, ``ecdsa``. The ``rsa_1_5`` is - the legacy PKCS#1 RSA 1.5 algorithm which is not TBBR compliant and is - retained only for compatibility. The default value of this flag is ``rsa`` - which is the TBBR compliant PKCS#1 RSA 2.1 scheme. + It accepts 3 values: ``rsa``, ``rsa_1_5`` and ``ecdsa``. The option + ``rsa_1_5`` is the legacy PKCS#1 RSA 1.5 algorithm which is not TBBR + compliant and is retained only for compatibility. The default value of this + flag is ``rsa`` which is the TBBR compliant PKCS#1 RSA 2.1 scheme. - ``HASH_ALG``: This build flag enables the user to select the secure hash - algorithm. It accepts 3 values viz. ``sha256``, ``sha384``, ``sha512``. + algorithm. It accepts 3 values: ``sha256``, ``sha384`` and ``sha512``. The default value of this flag is ``sha256``. - ``LDFLAGS``: Extra user options appended to the linkers' command line in @@ -606,14 +619,14 @@ Common build options does not need to be implemented in this case. - ``PSCI_EXTENDED_STATE_ID``: As per PSCI1.0 Specification, there are 2 formats - possible for the PSCI power-state parameter viz original and extended - State-ID formats. This flag if set to 1, configures the generic PSCI layer - to use the extended format. The default value of this flag is 0, which - means by default the original power-state format is used by the PSCI - implementation. This flag should be specified by the platform makefile - and it governs the return value of PSCI_FEATURES API for CPU_SUSPEND - smc function id. When this option is enabled on Arm platforms, the - option ``ARM_RECOM_STATE_ID_ENC`` needs to be set to 1 as well. + possible for the PSCI power-state parameter: original and extended State-ID + formats. This flag if set to 1, configures the generic PSCI layer to use the + extended format. The default value of this flag is 0, which means by default + the original power-state format is used by the PSCI implementation. This flag + should be specified by the platform makefile and it governs the return value + of PSCI_FEATURES API for CPU_SUSPEND smc function id. When this option is + enabled on Arm platforms, the option ``ARM_RECOM_STATE_ID_ENC`` needs to be + set to 1 as well. - ``RAS_EXTENSION``: When set to ``1``, enable Armv8.2 RAS features. RAS features are an optional extension for pre-Armv8.2 CPUs, but are mandatory for Armv8.2 |