[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