From eb68ea9b10c190c237216dee92166f9e7b2ce3d4 Mon Sep 17 00:00:00 2001 From: Jeenu Viswambharan Date: Fri, 22 Sep 2017 08:32:09 +0100 Subject: GIC: Add API to get running priority Document the API in separate platform interrupt controller API document. Change-Id: If18f208e10a8a243f5c59d226fcf48e985941949 Co-authored-by: Yousuf A Signed-off-by: Jeenu Viswambharan --- docs/platform-interrupt-controller-API.rst | 32 ++++++++++++++++++++++++++++++ 1 file changed, 32 insertions(+) create mode 100644 docs/platform-interrupt-controller-API.rst (limited to 'docs/platform-interrupt-controller-API.rst') diff --git a/docs/platform-interrupt-controller-API.rst b/docs/platform-interrupt-controller-API.rst new file mode 100644 index 000000000..9ef2e3f67 --- /dev/null +++ b/docs/platform-interrupt-controller-API.rst @@ -0,0 +1,32 @@ +Platform Interrupt Controller API documentation +=============================================== + +.. section-numbering:: + :suffix: . + +.. contents:: + +This document lists the optional platform interrupt controller API that +abstracts the runtime configuration and control of interrupt controller from the +generic code. The mandatory APIs are described in the `porting guide`__. + +.. __: porting-guide.rst#interrupt-management-framework-in-bl31 + +Function: unsigned int plat_ic_get_running_priority(void); [optional] +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +:: + + Argument : void + Return : unsigned int + +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``. + +In the case of ARM standard platforms using GIC, the *Running Priority Register* +is read to determine the priority of the interrupt. + +---- + +*Copyright (c) 2017, ARM Limited and Contributors. All rights reserved.* -- cgit v1.2.3 From ca43b55d22f3a48f408d16d4bedbf677cbdf8f48 Mon Sep 17 00:00:00 2001 From: Jeenu Viswambharan Date: Fri, 22 Sep 2017 08:32:09 +0100 Subject: GIC: Add APIs to query interrupt types These APIs allow the GIC implementation to categorize interrupt numbers into SPIs, PPIs, and SGIs. The default implementations for GICv2 and GICv3 follows interrupt numbering as specified by the ARM GIC architecture. API documentation updated. Change-Id: Ia6aa379dc955994333232e6138f259535d4fa087 Signed-off-by: Jeenu Viswambharan --- docs/platform-interrupt-controller-API.rst | 39 ++++++++++++++++++++++++++++++ 1 file changed, 39 insertions(+) (limited to 'docs/platform-interrupt-controller-API.rst') diff --git a/docs/platform-interrupt-controller-API.rst b/docs/platform-interrupt-controller-API.rst index 9ef2e3f67..a94a90c75 100644 --- a/docs/platform-interrupt-controller-API.rst +++ b/docs/platform-interrupt-controller-API.rst @@ -27,6 +27,45 @@ 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. +Function: int plat_ic_is_spi(unsigned int id); [optional] +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +:: + + Argument : unsigned int + Return : int + +The API should return whether the interrupt ID (first parameter) is categorized +as a Shared Peripheral Interrupt. Shared Peripheral Interrupts are typically +associated to system-wide peripherals, and these interrupts can target any PE in +the system. + +Function: int plat_ic_is_ppi(unsigned int id); [optional] +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +:: + + Argument : unsigned int + Return : int + +The API should return whether the interrupt ID (first parameter) is categorized +as a Private Peripheral Interrupt. Private Peripheral Interrupts are typically +associated with peripherals that are private to each PE. Interrupts from private +peripherals target to that PE only. + +Function: int plat_ic_is_sgi(unsigned int id); [optional] +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +:: + + Argument : unsigned int + Return : int + +The API should return whether the interrupt ID (first parameter) is categorized +as a Software Generated Interrupt. Software Generated Interrupts are raised by +explicit programming by software, and are typically used in inter-PE +communication. Secure SGIs are reserved for use by Secure world software. + ---- *Copyright (c) 2017, ARM Limited and Contributors. All rights reserved.* -- cgit v1.2.3 From cbd3f3706d4217ee3669deeb52b158e84eb97f56 Mon Sep 17 00:00:00 2001 From: Jeenu Viswambharan Date: Fri, 22 Sep 2017 08:32:09 +0100 Subject: GIC: Add API to get interrupt active status API documentation updated. Change-Id: I6d61785af0d5330930c709de971a904dc7c3516c Co-authored-by: Yousuf A Signed-off-by: Jeenu Viswambharan --- docs/platform-interrupt-controller-API.rst | 15 +++++++++++++++ 1 file changed, 15 insertions(+) (limited to 'docs/platform-interrupt-controller-API.rst') diff --git a/docs/platform-interrupt-controller-API.rst b/docs/platform-interrupt-controller-API.rst index a94a90c75..d0a2ad276 100644 --- a/docs/platform-interrupt-controller-API.rst +++ b/docs/platform-interrupt-controller-API.rst @@ -66,6 +66,21 @@ as a Software Generated Interrupt. Software Generated Interrupts are raised by explicit programming by software, and are typically used in inter-PE communication. Secure SGIs are reserved for use by Secure world software. +Function: unsigned int plat_ic_get_interrupt_active(unsigned int id); [optional] +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +:: + + Argument : unsigned int + Return : int + +This API should return the *active* status of the interrupt ID specified by the +first parameter, ``id``. + +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 +interrupt. + ---- *Copyright (c) 2017, ARM Limited and Contributors. All rights reserved.* -- cgit v1.2.3 From 979225f4eed00d631bb57ebd09068edd91b8df7b Mon Sep 17 00:00:00 2001 From: Jeenu Viswambharan Date: Fri, 22 Sep 2017 08:32:09 +0100 Subject: GIC: Add APIs to enable and disable interrupt API documentation updated. Change-Id: Ice7511f8df5356851001d2f7dc2a46cfe318f9ba Co-authored-by: Yousuf A Signed-off-by: Jeenu Viswambharan --- docs/platform-interrupt-controller-API.rst | 30 ++++++++++++++++++++++++++++++ 1 file changed, 30 insertions(+) (limited to 'docs/platform-interrupt-controller-API.rst') diff --git a/docs/platform-interrupt-controller-API.rst b/docs/platform-interrupt-controller-API.rst index d0a2ad276..bea1a64b5 100644 --- a/docs/platform-interrupt-controller-API.rst +++ b/docs/platform-interrupt-controller-API.rst @@ -81,6 +81,36 @@ 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 interrupt. +Function: void plat_ic_enable_interrupt(unsigned int id); [optional] +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +:: + + Argument : unsigned int + Return : void + +This API should enable the interrupt ID specified by the first parameter, +``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 +inserts barrier to make memory updates visible before enabling interrupt, and +then writes to GIC *Set Enable Register* to enable the interrupt. + +Function: void plat_ic_disable_interrupt(unsigned int id); [optional] +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +:: + + Argument : unsigned int + Return : void + +This API should disable the interrupt ID specified by the first parameter, +``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 +writes to GIC *Clear Enable Register* to disable the interrupt, and inserts +barrier to make memory updates visible afterwards. + ---- *Copyright (c) 2017, ARM Limited and Contributors. All rights reserved.* -- cgit v1.2.3 From f3a866004ea8f9a0cd5420f3dd4d4683f638e6da Mon Sep 17 00:00:00 2001 From: Jeenu Viswambharan Date: Fri, 22 Sep 2017 08:32:09 +0100 Subject: GIC: Add API to set interrupt priority API documentation updated. Change-Id: Ib700eb1b8ca65503aeed0ac4ce0e7b934df67ff9 Co-authored-by: Yousuf A Signed-off-by: Jeenu Viswambharan --- docs/platform-interrupt-controller-API.rst | 15 +++++++++++++++ 1 file changed, 15 insertions(+) (limited to 'docs/platform-interrupt-controller-API.rst') diff --git a/docs/platform-interrupt-controller-API.rst b/docs/platform-interrupt-controller-API.rst index bea1a64b5..3161c20a2 100644 --- a/docs/platform-interrupt-controller-API.rst +++ b/docs/platform-interrupt-controller-API.rst @@ -111,6 +111,21 @@ 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 barrier to make memory updates visible afterwards. +Function: void plat_ic_set_interrupt_priority(unsigned int id, unsigned int priority); [optional] +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +:: + + Argument : unsigned int + Argument : unsigned int + Return : void + +This API should set the priority of the interrupt specified by first parameter +``id`` to the value set by the second parameter ``priority``. + +In case of ARM standard platforms using GIC, the implementation of the API +writes to GIC *Priority Register* set interrupt priority. + ---- *Copyright (c) 2017, ARM Limited and Contributors. All rights reserved.* -- cgit v1.2.3 From 74dce7fa6e42cab3aa54a9543e4a546c1450b2ae Mon Sep 17 00:00:00 2001 From: Jeenu Viswambharan Date: Fri, 22 Sep 2017 08:32:09 +0100 Subject: GIC: Add APIs to set interrupt type and query support The back end GIC driver converts and assigns the interrupt type to suitable group. For GICv2, a build option GICV2_G0_FOR_EL3 is introduced, which determines to which type Group 0 interrupts maps to. - When the build option is set 0 (the default), Group 0 interrupts are meant for Secure EL1. This is presently the case. - Otherwise, Group 0 interrupts are meant for EL3. This means the SPD will have to synchronously hand over the interrupt to Secure EL1. The query API allows the platform to query whether the platform supports interrupts of a given type. API documentation updated. Change-Id: I60fdb4053ffe0bd006b3b20914914ebd311fc858 Co-authored-by: Yousuf A Signed-off-by: Jeenu Viswambharan --- docs/platform-interrupt-controller-API.rst | 74 ++++++++++++++++++++++++++++++ 1 file changed, 74 insertions(+) (limited to 'docs/platform-interrupt-controller-API.rst') diff --git a/docs/platform-interrupt-controller-API.rst b/docs/platform-interrupt-controller-API.rst index 3161c20a2..3d46cf344 100644 --- a/docs/platform-interrupt-controller-API.rst +++ b/docs/platform-interrupt-controller-API.rst @@ -126,6 +126,80 @@ This API should set the priority of the interrupt specified by first parameter In case of ARM standard platforms using GIC, the implementation of the API writes to GIC *Priority Register* set interrupt priority. +Function: int plat_ic_has_interrupt_type(unsigned int type); [optional] +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +:: + + Argument : unsigned int + Return : int + +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 +``INTR_TYPE_NS``. + +In case of ARM standard platforms using GICv3, the implementation of the API +returns ``1`` for all interrupt types. + +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 +option ``GICV2_G0_FOR_EL3``: + +- For interrupt type ``INTR_TYPE_EL3``: + + - When ``GICV2_G0_FOR_EL3`` is ``0``, it returns ``0``, indicating no support + for EL3 interrupts. + + - When ``GICV2_G0_FOR_EL3`` is ``1``, it returns ``1``, indicating support for + EL3 interrupts. + +- For interrupt type ``INTR_TYPE_S_EL1``: + + - When ``GICV2_G0_FOR_EL3`` is ``0``, it returns ``1``, indicating support for + Secure EL1 interrupts. + + - When ``GICV2_G0_FOR_EL3`` is ``1``, it returns ``0``, indicating no support + for Secure EL1 interrupts. + +Function: void plat_ic_set_interrupt_type(unsigned int id, unsigned int type); [optional] +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +:: + + Argument : unsigned int + Argument : unsigned int + Return : void + +This API should set the interrupt specified by first parameter ``id`` to the +type specified by second parameter ``type``. The ``type`` parameter can be +one of: + +- ``INTR_TYPE_NS``: interrupt is meant to be consumed by the Non-secure world. + +- ``INTR_TYPE_S_EL1``: interrupt is meant to be consumed by Secure EL1. + +- ``INTR_TYPE_EL3``: interrupt is meant to be consumed by EL3. + +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 +assign the interrupt to the right group. + +For GICv3: + +- ``INTR_TYPE_NS`` maps to Group 1 interrupt. + +- ``INTR_TYPE_S_EL1`` maps to Secure Group 1 interrupt. + +- ``INTR_TYPE_EL3`` maps to Secure Group 0 interrupt. + +For GICv2: + +- ``INTR_TYPE_NS`` maps to Group 1 interrupt. + +- When the build option ``GICV2_G0_FOR_EL3`` is set to ``0`` (the default), + ``INTR_TYPE_S_EL1`` maps to Group 0. Otherwise, ``INTR_TYPE_EL3`` maps to + Group 0 interrupt. + ---- *Copyright (c) 2017, ARM Limited and Contributors. All rights reserved.* -- cgit v1.2.3 From 8db978b5a8606a658c65b16fab7edd7a17c7c940 Mon Sep 17 00:00:00 2001 From: Jeenu Viswambharan Date: Fri, 22 Sep 2017 08:32:09 +0100 Subject: GIC: Add API to raise secure SGI API documentation updated. Change-Id: I129725059299af6cc612bafa8d74817f779d7c4f Signed-off-by: Jeenu Viswambharan --- docs/platform-interrupt-controller-API.rst | 17 +++++++++++++++++ 1 file changed, 17 insertions(+) (limited to 'docs/platform-interrupt-controller-API.rst') diff --git a/docs/platform-interrupt-controller-API.rst b/docs/platform-interrupt-controller-API.rst index 3d46cf344..74291bcaa 100644 --- a/docs/platform-interrupt-controller-API.rst +++ b/docs/platform-interrupt-controller-API.rst @@ -200,6 +200,23 @@ For GICv2: ``INTR_TYPE_S_EL1`` maps to Group 0. Otherwise, ``INTR_TYPE_EL3`` maps to Group 0 interrupt. +Function: void plat_ic_raise_el3_sgi(int sgi_num, u_register_t target); [optional] +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +:: + + Argument : int + Argument : u_register_t + Return : void + +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 +target PE. + +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 +to appropriate *SGI Register* in order to raise the EL3 SGI. + ---- *Copyright (c) 2017, ARM Limited and Contributors. All rights reserved.* -- cgit v1.2.3 From fc529fee720de5fef8388c52bfefcb807ac764b0 Mon Sep 17 00:00:00 2001 From: Jeenu Viswambharan Date: Fri, 22 Sep 2017 08:32:09 +0100 Subject: GIC: Add API to set interrupt routing SPIs can be routed to either a specific PE, or to any one of all available PEs. API documentation updated. Change-Id: I28675f634568aaf4ea1aa8aa7ebf25b419a963ed Co-authored-by: Yousuf A Signed-off-by: Jeenu Viswambharan --- docs/platform-interrupt-controller-API.rst | 26 ++++++++++++++++++++++++++ 1 file changed, 26 insertions(+) (limited to 'docs/platform-interrupt-controller-API.rst') diff --git a/docs/platform-interrupt-controller-API.rst b/docs/platform-interrupt-controller-API.rst index 74291bcaa..df4139e3d 100644 --- a/docs/platform-interrupt-controller-API.rst +++ b/docs/platform-interrupt-controller-API.rst @@ -217,6 +217,32 @@ 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 to appropriate *SGI Register* in order to raise the EL3 SGI. +Function: void plat_ic_set_spi_routing(unsigned int id, unsigned int routing_mode, u_register_t mpidr); [optional] +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +:: + + Argument : unsigned int + Argument : unsigned int + Argument : u_register_t + Return : void + +This API should set the routing mode of Share Peripheral Interrupt (SPI) +specified by first parameter ``id`` to that specified by the second parameter +``routing_mode``. + +The ``routing_mode`` parameter can be one of: + +- ``INTR_ROUTING_MODE_ANY`` means the interrupt can be routed to any PE in the + system. The ``mpidr`` parameter is ignored in this case. + +- ``INTR_ROUTING_MODE_PE`` means the interrupt is routed to the PE whose MPIDR + value is specified by the parameter ``mpidr``. + +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 +the routing. + ---- *Copyright (c) 2017, ARM Limited and Contributors. All rights reserved.* -- cgit v1.2.3 From a2816a16440d9eb1223ba505bc30faf6cd31b0ee Mon Sep 17 00:00:00 2001 From: Jeenu Viswambharan Date: Fri, 22 Sep 2017 08:32:09 +0100 Subject: GIC: Add API to set/clear interrupt pending API documentation updated. Change-Id: I14e33cfc7dfa93257c82d76fae186b17a1b6d266 Co-authored-by: Yousuf A Signed-off-by: Jeenu Viswambharan --- docs/platform-interrupt-controller-API.rst | 31 ++++++++++++++++++++++++++++++ 1 file changed, 31 insertions(+) (limited to 'docs/platform-interrupt-controller-API.rst') diff --git a/docs/platform-interrupt-controller-API.rst b/docs/platform-interrupt-controller-API.rst index df4139e3d..d5c167339 100644 --- a/docs/platform-interrupt-controller-API.rst +++ b/docs/platform-interrupt-controller-API.rst @@ -243,6 +243,37 @@ 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 the routing. +Function: void plat_ic_set_interrupt_pending(unsigned int id); [optional] +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +:: + + Argument : unsigned int + Return : void + +This API should set the interrupt specified by first parameter ``id`` to +*Pending*. + +In case of ARM standard platforms using GIC, the implementation of the API +inserts barrier to make memory updates visible before setting interrupt pending, +and writes to the GIC *Set Pending Register* to set the interrupt pending +status. + +Function: void plat_ic_clear_interrupt_pending(unsigned int id); [optional] +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +:: + + Argument : unsigned int + Return : void + +This API should clear the *Pending* status of the interrupt specified by first +parameter ``id``. + +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 +status, and inserts barrier to make memory updates visible afterwards. + ---- *Copyright (c) 2017, ARM Limited and Contributors. All rights reserved.* -- cgit v1.2.3 From d55a445069736e2652b44ddfeb9ea4d306796a0a Mon Sep 17 00:00:00 2001 From: Jeenu Viswambharan Date: Fri, 22 Sep 2017 08:32:09 +0100 Subject: GIC: Add API to set priority mask API documentation updated. Change-Id: I40feec1fe67a960d035061b54dd55610bc34ce1d Signed-off-by: Jeenu Viswambharan --- docs/platform-interrupt-controller-API.rst | 18 ++++++++++++++++++ 1 file changed, 18 insertions(+) (limited to 'docs/platform-interrupt-controller-API.rst') diff --git a/docs/platform-interrupt-controller-API.rst b/docs/platform-interrupt-controller-API.rst index d5c167339..795c08562 100644 --- a/docs/platform-interrupt-controller-API.rst +++ b/docs/platform-interrupt-controller-API.rst @@ -274,6 +274,24 @@ 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 status, and inserts barrier to make memory updates visible afterwards. +Function: unsigned int plat_ic_set_priority_mask(unsigned int id); [optional] +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +:: + + Argument : unsigned int + Return : int + +This API should set the priority mask (first parameter) in the interrupt +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 +that it's overwriting. + +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 +*Priority Mask Register*, and make sure memory updates are visible before +potential trigger due to mask update. + ---- *Copyright (c) 2017, ARM Limited and Contributors. All rights reserved.* -- cgit v1.2.3