[rtems-docs] c-user: Document interrupt get/set priority
Sebastian Huber
sebastian.huber at embedded-brains.de
Tue Apr 9 14:32:23 UTC 2024
Update #5002.
---
c-user/interrupt/directives.rst | 185 +++++++++++++++++++++++++++++-
c-user/interrupt/introduction.rst | 10 +-
c-user/rtems_data_types.rst | 19 ++-
3 files changed, 211 insertions(+), 3 deletions(-)
diff --git a/c-user/interrupt/directives.rst b/c-user/interrupt/directives.rst
index 80eddfd..a8f7a79 100644
--- a/c-user/interrupt/directives.rst
+++ b/c-user/interrupt/directives.rst
@@ -1,6 +1,6 @@
.. SPDX-License-Identifier: CC-BY-SA-4.0
-.. Copyright (C) 2008, 2022 embedded brains GmbH & Co. KG
+.. Copyright (C) 2008, 2024 embedded brains GmbH & Co. KG
.. Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR)
.. This file is part of the RTEMS quality process and was automatically
@@ -2005,6 +2005,189 @@ The following constraints apply to this directive:
* The directive will not cause the calling task to be preempted.
+.. Generated from spec:/rtems/intr/if/get-priority
+
+.. raw:: latex
+
+ \clearpage
+
+.. index:: rtems_interrupt_get_priority()
+
+.. _InterfaceRtemsInterruptGetPriority:
+
+rtems_interrupt_get_priority()
+------------------------------
+
+Gets the priority of the interrupt vector.
+
+.. rubric:: CALLING SEQUENCE:
+
+.. code-block:: c
+
+ rtems_status_code rtems_interrupt_get_priority(
+ rtems_vector_number vector,
+ uint32_t *priority
+ );
+
+.. rubric:: PARAMETERS:
+
+``vector``
+ This parameter is the interrupt vector number.
+
+``priority``
+ This parameter is the pointer to an `uint32_t
+ <https://en.cppreference.com/w/c/types/integer>`_ object. When the
+ directive call is successful, the priority of the interrupt vector will be
+ stored in this object.
+
+.. rubric:: RETURN VALUES:
+
+:c:macro:`RTEMS_SUCCESSFUL`
+ The requested operation was successful.
+
+:c:macro:`RTEMS_INVALID_ADDRESS`
+ The ``priority`` parameter was `NULL
+ <https://en.cppreference.com/w/c/types/NULL>`_.
+
+:c:macro:`RTEMS_INVALID_ID`
+ There was no interrupt vector associated with the number specified by
+ ``vector``.
+
+:c:macro:`RTEMS_UNSATISFIED`
+ There is no priority associated with the interrupt vector.
+
+.. rubric:: NOTES:
+
+The :ref:`InterfaceRtemsInterruptSetPriority` directive may be used to set the
+priority associated with an interrupt vector.
+
+.. rubric:: CONSTRAINTS:
+
+The following constraints apply to this directive:
+
+* The directive may be called from within interrupt context.
+
+* The directive may be called from within device driver initialization context.
+
+* The directive may be called from within task context.
+
+* The directive will not cause the calling task to be preempted.
+
+.. Generated from spec:/rtems/intr/if/set-priority
+
+.. raw:: latex
+
+ \clearpage
+
+.. index:: rtems_interrupt_set_priority()
+
+.. _InterfaceRtemsInterruptSetPriority:
+
+rtems_interrupt_set_priority()
+------------------------------
+
+Sets the priority of the interrupt vector.
+
+.. rubric:: CALLING SEQUENCE:
+
+.. code-block:: c
+
+ rtems_status_code rtems_interrupt_set_priority(
+ rtems_vector_number vector,
+ uint32_t priority
+ );
+
+.. rubric:: PARAMETERS:
+
+``vector``
+ This parameter is the interrupt vector number.
+
+``priority``
+ This parameter is the new priority for the interrupt vector.
+
+.. rubric:: DESCRIPTION:
+
+This directive sets the priority of the interrupt specified by ``vector`` to
+the priority specified by ``priority``.
+
+For processor-specific interrupts, the priority of the interrupt specific to a
+processor executing the directive call will be set.
+
+.. rubric:: RETURN VALUES:
+
+:c:macro:`RTEMS_SUCCESSFUL`
+ The requested operation was successful.
+
+:c:macro:`RTEMS_INVALID_ID`
+ There was no interrupt vector associated with the number specified by
+ ``vector``.
+
+:c:macro:`RTEMS_INVALID_PRIORITY`
+ The priority specified by ``priority`` was not a valid new priority for the
+ interrupt vector.
+
+:c:macro:`RTEMS_UNSATISFIED`
+ The request to set the priority of the interrupt vector has not been
+ satisfied.
+
+.. rubric:: NOTES:
+
+The :ref:`InterfaceRtemsInterruptGetPriority` directive may be used to get the
+priority associated with an interrupt vector.
+
+The interrupt prioritization support depends on the interrupt controller of the
+:term:`target`. It is strongly recommended to read the relevant hardware
+documentation. What happens when the priority of a pending or active interrupt
+is changed, depends on the interrupt controller. In general, you should set
+the interrupt priority of an interrupt vector before a handler is installed.
+On some interrupt controllers, setting the priority to the maximum value
+(lowest importance) effectively disables the interrupt. On some architectures,
+a range of interrupt priority values may be not disabled by the interrupt
+disable directives. Handlers of such interrupts shall not use operating system
+services.
+
+For the ARM Generic Interrupt Controller (GIC), an 8-bit priority value is
+supported. The granularity of the priority levels depends on the interrupt
+controller configuration. Some low-order bits of a priority value may be
+read-as-zero (RAZ) and writes are ignored (WI). Where group 0 (FIQ) and group
+1 (IRQ) interrupts are used, it is recommended to use the lower half of the
+supported priority value range for the group 0 interrupts and the upper half
+for group 1 interrupts. This ensures that group 1 interrupts cannot preempt
+group 0 interrupts.
+
+For the Armv7-M Nested Vector Interrupt Controller (NVIC), an 8-bit priority
+value is supported. The granularity of the priority levels depends on the
+interrupt controller configuration. Some lower bits of a priority value may be
+read-as-zero (RAZ) and writes are ignored (WI). Interrupts with a priority
+value less than 128 are not disabled by the RTEMS interrupt disable directives.
+Handlers of such interrupts shall not use operating system services.
+
+For the RISC-V Platform-Level Interrupt Controller (PLIC), all priority values
+from 0 up to and including the 0xffffffff are supported since the priority for
+the PLIC is defined by a write-any-read-legal (WARL) register. Please note that
+for this directive in contrast to the PLIC, a higher priority value is
+associated with a lower importance. The maximum priority value (mapped to the
+value 0 for the PLIC) is reserved to mean "never interrupt" and effectively
+disables the interrupt.
+
+For the QorIQ Multicore Programmable Interrupt Controller (MPIC), a 4-bit
+priority value is supported. Please note that for this directive in contrast
+to the MPIC, a higher priority value is associated with a lower importance. The
+maximum priority value of 15 (mapped to the value 0 for the MPIC) inhibits
+signalling of this interrupt.
+
+.. rubric:: CONSTRAINTS:
+
+The following constraints apply to this directive:
+
+* The directive may be called from within interrupt context.
+
+* The directive may be called from within device driver initialization context.
+
+* The directive may be called from within task context.
+
+* The directive will not cause the calling task to be preempted.
+
.. Generated from spec:/rtems/intr/if/get-affinity
.. raw:: latex
diff --git a/c-user/interrupt/introduction.rst b/c-user/interrupt/introduction.rst
index 14ea275..401f826 100644
--- a/c-user/interrupt/introduction.rst
+++ b/c-user/interrupt/introduction.rst
@@ -1,6 +1,6 @@
.. SPDX-License-Identifier: CC-BY-SA-4.0
-.. Copyright (C) 2008, 2022 embedded brains GmbH & Co. KG
+.. Copyright (C) 2008, 2024 embedded brains GmbH & Co. KG
.. Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR)
.. This file is part of the RTEMS quality process and was automatically
@@ -58,6 +58,8 @@ Introduction
.. spec:/rtems/intr/if/raise
.. spec:/rtems/intr/if/raise-on
.. spec:/rtems/intr/if/clear
+.. spec:/rtems/intr/if/get-priority
+.. spec:/rtems/intr/if/set-priority
.. spec:/rtems/intr/if/get-affinity
.. spec:/rtems/intr/if/set-affinity
.. spec:/rtems/intr/if/get-attributes
@@ -173,6 +175,12 @@ from an ISR. The directives provided by the Interrupt Manager are:
* :ref:`InterfaceRtemsInterruptClear` - Clears the interrupt vector.
+* :ref:`InterfaceRtemsInterruptGetPriority` - Gets the priority of the
+ interrupt vector.
+
+* :ref:`InterfaceRtemsInterruptSetPriority` - Sets the priority of the
+ interrupt vector.
+
* :ref:`InterfaceRtemsInterruptGetAffinity` - Gets the processor affinity set
of the interrupt vector.
diff --git a/c-user/rtems_data_types.rst b/c-user/rtems_data_types.rst
index 0a5461c..c1fd561 100644
--- a/c-user/rtems_data_types.rst
+++ b/c-user/rtems_data_types.rst
@@ -1,6 +1,6 @@
.. SPDX-License-Identifier: CC-BY-SA-4.0
-.. Copyright (C) 2008, 2021 embedded brains GmbH & Co. KG
+.. Copyright (C) 2008, 2024 embedded brains GmbH & Co. KG
.. Copyright (C) 1988, 2017 On-Line Applications Research Corporation (OAR)
.. This file is part of the RTEMS quality process and was automatically
@@ -572,6 +572,23 @@ trigger_signal
triggered by messages, :ref:`InterfaceRtemsInterruptRaise`, or
:ref:`InterfaceRtemsInterruptRaiseOn`.
+can_get_priority
+ This member is true, if the priority of the interrupt vector can be
+ obtained by :ref:`InterfaceRtemsInterruptGetPriority`, otherwise it is
+ false.
+
+can_set_priority
+ This member is true, if the priority of the interrupt vector can be set by
+ :ref:`InterfaceRtemsInterruptSetPriority`, otherwise it is false.
+
+maximum_priority
+ This member represents the maximum priority value of the interrupt vector.
+ By convention, the minimum priority value is zero. Lower priority values
+ shall be associated with a higher importance. The higher the priority
+ value, the less important is the service of the associated interrupt
+ vector. Where nested interrupts are supported, interrupts with a lower
+ priority value may preempt other interrupts having a higher priority value.
+
.. rubric:: DESCRIPTION:
The :ref:`InterfaceRtemsInterruptGetAttributes` directive may be used to obtain
--
2.35.3
More information about the devel
mailing list