From 8d52e16b45f1d4fbb16ea3a512e9bd56666e4f8e Mon Sep 17 00:00:00 2001 From: Imre Kis Date: Mon, 3 Feb 2020 14:48:21 +0100 Subject: doc: Remove backquotes from external hyperlinks Since Sphinx 2.3.0 backquotes are replaced to \textasciigrave{} during building latexpdf. Using this element in a \sphinxhref{} breaks the build. In order to avoid this error backquotes must not be used in external hyperlinks. Signed-off-by: Imre Kis Change-Id: Ie3cf454427e3d5a7b7f9829b42be45aebda7f0dd --- docs/components/exception-handling.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'docs/components/exception-handling.rst') diff --git a/docs/components/exception-handling.rst b/docs/components/exception-handling.rst index 3f386854f..e330a62a4 100644 --- a/docs/components/exception-handling.rst +++ b/docs/components/exception-handling.rst @@ -467,7 +467,7 @@ SMCs from Non-secure world are synchronous exceptions, and are mechanisms for Non-secure world to request Secure services. They're broadly classified as *Fast* or *Yielding* (see `SMCCC`__). -.. __: `http://infocenter.arm.com/help/topic/com.arm.doc.den0028a/index.html` +.. __: http://infocenter.arm.com/help/topic/com.arm.doc.den0028a/index.html - *Fast* SMCs are atomic from the caller's point of view. I.e., they return to the caller only when the Secure world has finished serving the request. @@ -621,6 +621,6 @@ The |EHF| has the following limitations: -------------- -*Copyright (c) 2018-2019, Arm Limited and Contributors. All rights reserved.* +*Copyright (c) 2018-2020, Arm Limited and Contributors. All rights reserved.* .. _SDEI specification: http://infocenter.arm.com/help/topic/com.arm.doc.den0054a/ARM_DEN0054A_Software_Delegated_Exception_Interface.pdf -- cgit v1.2.3 From 3ba55a3c5fa260c9218be1adff8f39fc2a568d68 Mon Sep 17 00:00:00 2001 From: laurenw-arm Date: Thu, 16 Apr 2020 10:02:17 -0500 Subject: docs: Update SMCCC doc, other changes for release Signed-off-by: Lauren Wehrmeister Change-Id: Ie842d6a9919776de151a4e9304f870aede07c47a --- docs/components/exception-handling.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/components/exception-handling.rst') diff --git a/docs/components/exception-handling.rst b/docs/components/exception-handling.rst index e330a62a4..4cca5f40b 100644 --- a/docs/components/exception-handling.rst +++ b/docs/components/exception-handling.rst @@ -467,7 +467,7 @@ SMCs from Non-secure world are synchronous exceptions, and are mechanisms for Non-secure world to request Secure services. They're broadly classified as *Fast* or *Yielding* (see `SMCCC`__). -.. __: http://infocenter.arm.com/help/topic/com.arm.doc.den0028a/index.html +.. __: https://developer.arm.com/docs/den0028/latest - *Fast* SMCs are atomic from the caller's point of view. I.e., they return to the caller only when the Secure world has finished serving the request. -- cgit v1.2.3 From c3233c11c4a009d1d4c895056c0ca674e4228330 Mon Sep 17 00:00:00 2001 From: Manish Pandey Date: Tue, 30 Jun 2020 00:46:08 +0100 Subject: doc: RAS: fixing broken links There were some links in the file "ras.rst" which were broken, this patch fixes all the broken links in this file. Signed-off-by: Manish Pandey Change-Id: I00cf080e9338af5786239a4843cb4c2e0cc9d99d --- docs/components/exception-handling.rst | 4 ++++ 1 file changed, 4 insertions(+) (limited to 'docs/components/exception-handling.rst') diff --git a/docs/components/exception-handling.rst b/docs/components/exception-handling.rst index 4cca5f40b..4c63a8b47 100644 --- a/docs/components/exception-handling.rst +++ b/docs/components/exception-handling.rst @@ -176,6 +176,8 @@ dispatcher may register more than one priority level. Dispatchers are assigned interrupt priority levels in two steps: +.. _Partitioning priority levels: + Partitioning priority levels ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -365,6 +367,8 @@ assign interrupts to fictitious dispatchers: See also the `Build-time flow`_ and the `Run-time flow`_. +.. _Activating and Deactivating priorities: + Activating and Deactivating priorities -------------------------------------- -- cgit v1.2.3 From 6844c3477b862195c12660f136e22313e84d4306 Mon Sep 17 00:00:00 2001 From: Madhukar Pappireddy Date: Wed, 29 Jul 2020 09:37:25 -0500 Subject: Fix broken links to various sections across docs These broken links were found with the help of this command: $> sphinx-build -M linkcheck . build A sample broken link is reported as follows: (line 80) -local- firmware-design.rst#secure-el1-payloads-and-dispatchers Change-Id: I5dcefdd4b8040908658115647e957f6c2c5da7c2 Signed-off-by: Madhukar Pappireddy --- docs/components/exception-handling.rst | 58 ++++++++++++++-------------------- 1 file changed, 24 insertions(+), 34 deletions(-) (limited to 'docs/components/exception-handling.rst') diff --git a/docs/components/exception-handling.rst b/docs/components/exception-handling.rst index 4c63a8b47..86ed87ce4 100644 --- a/docs/components/exception-handling.rst +++ b/docs/components/exception-handling.rst @@ -10,13 +10,9 @@ of the following exceptions when targeted at EL3: - Asynchronous External Aborts |TF-A|'s handling of synchronous ``SMC`` exceptions raised from lower ELs is -described in the `Firmware Design document`__. However, the |EHF| changes the -semantics of `interrupt handling`__ and `synchronous exceptions`__ other than -SMCs. - -.. __: firmware-design.rst#handling-an-smc -.. __: `Interrupt handling`_ -.. __: `Effect on SMC calls`_ +described in the :ref:`Firmware Design document `. However, the +|EHF| changes the semantics of `Interrupt handling`_ and :ref:`synchronous +exceptions ` other than SMCs. The |EHF| is selected by setting the build option ``EL3_EXCEPTION_HANDLING`` to ``1``, and is only available for AArch64 systems. @@ -77,10 +73,9 @@ On any given system, all of the above handling models may be employed independently depending on platform choice and the nature of the exception received. -.. [#spd] Not to be confused with `Secure Payload Dispatcher`__, which is an - EL3 component that operates in EL3 on behalf of Secure OS. - -.. __: firmware-design.rst#secure-el1-payloads-and-dispatchers +.. [#spd] Not to be confused with :ref:`Secure Payload Dispatcher + `, which is an EL3 component that operates in EL3 + on behalf of Secure OS. The role of Exception Handling Framework ---------------------------------------- @@ -139,6 +134,8 @@ unstacked in strictly the reverse order. For interrupts, the GIC ensures this is the case; for non-interrupts, the |EHF| monitors and asserts this. See `Transition of priority levels`_. +.. _interrupt-handling: + Interrupt handling ------------------ @@ -151,15 +148,12 @@ implications: sufficient priority are signalled as FIQs, and therefore will be routed to EL3. As a result, S-EL1 software cannot expect to handle Non-secure interrupts at S-EL1. Essentially, this deprecates the routing mode described - as `CSS=0, TEL3=0`__. - - .. __: interrupt-framework-design.rst#el3-interrupts + as :ref:`CSS=0, TEL3=0 `. In order for S-EL1 software to handle Non-secure interrupts while having |EHF| enabled, the dispatcher must adopt a model where Non-secure interrupts - are received at EL3, but are then `synchronously`__ handled over to S-EL1. - - .. __: interrupt-framework-design.rst#secure-payload + are received at EL3, but are then :ref:`synchronously ` + handled over to S-EL1. - On GICv2 systems, it's required that the build option ``GICV2_G0_FOR_EL3`` is set to ``1`` so that *Group 0* interrupts target EL3. @@ -283,15 +277,13 @@ The interrupt handler should have the following signature: typedef int (*ehf_handler_t)(uint32_t intr_raw, uint32_t flags, void *handle, void *cookie); -The parameters are as obtained from the top-level `EL3 interrupt handler`__. - -.. __: interrupt-framework-design.rst#el3-runtime-firmware +The parameters are as obtained from the top-level :ref:`EL3 interrupt handler +`. -The `SDEI dispatcher`__, for example, expects the platform to allocate two -different priority levels—``PLAT_SDEI_CRITICAL_PRI``, and -``PLAT_SDEI_NORMAL_PRI``—and registers the same handler to handle both levels. - -.. __: sdei.rst +The :ref:`SDEI dispatcher`, for +example, expects the platform to allocate two different priority levels— +``PLAT_SDEI_CRITICAL_PRI``, and ``PLAT_SDEI_NORMAL_PRI`` —and registers the +same handler to handle both levels. Interrupt handling example -------------------------- @@ -374,11 +366,9 @@ 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, 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 +acknowledged; for non-interrupt exceptions, such as SErrors or :ref:`SDEI +explicit dispatches `, this has to be done via +calling ``ehf_activate_priority()``. See `Run-time flow`_. Conversely, when the dispatcher has reached a logical resolution for the cause of the exception, the corresponding priority level ought to be deactivated. As @@ -457,6 +447,8 @@ calls to these APIs are subject to the following conditions: If these are violated, a panic will result. +.. _Effect on SMC calls: + Effect on SMC calls ------------------- @@ -542,10 +534,8 @@ The following is an example flow for interrupts: interrupts belonging to different dispatchers. #. The |EHF|, during its initialisation, registers a top-level interrupt handler - with the `Interrupt Management Framework`__ for EL3 interrupts. This also - results in setting the routing bits in ``SCR_EL3``. - - .. __: interrupt-framework-design.rst#el3-runtime-firmware + with the :ref:`Interrupt Management Framework` for EL3 + interrupts. This also results in setting the routing bits in ``SCR_EL3``. #. When an interrupt belonging to a dispatcher fires, GIC raises an EL3/Group 0 interrupt, and is taken to EL3. -- cgit v1.2.3 From a4075bb55b4d36a9674d58528f0e6cd3a8cab5ae Mon Sep 17 00:00:00 2001 From: Madhukar Pappireddy Date: Thu, 6 Aug 2020 12:36:17 -0500 Subject: Fix broken links in docs Change-Id: If82aaba9f2a5a74cfb5e4381f968166037a70037 Signed-off-by: Madhukar Pappireddy --- docs/components/exception-handling.rst | 11 +++++------ 1 file changed, 5 insertions(+), 6 deletions(-) (limited to 'docs/components/exception-handling.rst') diff --git a/docs/components/exception-handling.rst b/docs/components/exception-handling.rst index 86ed87ce4..6f223c675 100644 --- a/docs/components/exception-handling.rst +++ b/docs/components/exception-handling.rst @@ -233,12 +233,11 @@ The text in `Partitioning priority levels`_ only describes how the platform expresses the required levels of priority. It however doesn't choose interrupts nor program the required priority in GIC. -The `Firmware Design guide`__ explains methods for configuring secure -interrupts. |EHF| requires the platform to enumerate interrupt properties (as -opposed to just numbers) of Secure interrupts. The priority of secure interrupts -must match that as determined in the `Partitioning priority levels`_ section above. - -.. __: firmware-design.rst#configuring-secure-interrupts +The :ref:`Firmware Design guide` explains methods +for configuring secure interrupts. |EHF| requires the platform to enumerate +interrupt properties (as opposed to just numbers) of Secure interrupts. The +priority of secure interrupts must match that as determined in the +`Partitioning priority levels`_ section above. See `Limitations`_, and also refer to `Interrupt handling example`_ for illustration. -- cgit v1.2.3