[PATCH] rtems: Add get/set interrupt priorities

[Sebastian Huber]

Add directives to get and set the priority of an interrupt vector.

Update #5002.
---
 cpukit/include/rtems/rtems/intr.h | 154 +++++++++++++++++++++++++++++-
 1 file changed, 153 insertions(+), 1 deletion(-)

diff --git a/cpukit/include/rtems/rtems/intr.h b/cpukit/include/rtems/rtems/intr.h
index f8809015e4..68fd7e6c45 100644
--- a/cpukit/include/rtems/rtems/intr.h
+++ b/cpukit/include/rtems/rtems/intr.h
@@ -9,7 +9,7 @@
  */
 
 /*
- * 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)
  *
  * Redistribution and use in source and binary forms, with or without
@@ -1743,6 +1743,135 @@ rtems_status_code rtems_interrupt_raise_on(
  */
 rtems_status_code rtems_interrupt_clear( rtems_vector_number vector );
 
+/* Generated from spec:/rtems/intr/if/get-priority */
+
+/**
+ * @ingroup RTEMSAPIClassicIntr
+ *
+ * @brief Gets the priority of the interrupt vector.
+ *
+ * @param vector is the interrupt vector number.
+ *
+ * @param[out] priority is the pointer to an uint32_t object.  When the
+ *   directive call is successful, the priority of the interrupt vector will be
+ *   stored in this object.
+ *
+ * @retval ::RTEMS_SUCCESSFUL The requested operation was successful.
+ *
+ * @retval ::RTEMS_INVALID_ADDRESS The ``priority`` parameter was NULL.
+ *
+ * @retval ::RTEMS_INVALID_ID There was no interrupt vector associated with the
+ *   number specified by ``vector``.
+ *
+ * @retval ::RTEMS_UNSATISFIED There is no priority associated with the
+ *   interrupt vector.
+ *
+ * @par Notes
+ * The rtems_interrupt_set_priority() directive may be used to set the priority
+ * associated with an interrupt vector.
+ *
+ * @par Constraints
+ * @parblock
+ * 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.
+ * @endparblock
+ */
+rtems_status_code rtems_interrupt_get_priority(
+  rtems_vector_number vector,
+  uint32_t           *priority
+);
+
+/* Generated from spec:/rtems/intr/if/set-priority */
+
+/**
+ * @ingroup RTEMSAPIClassicIntr
+ *
+ * @brief Sets the priority of the interrupt vector.
+ *
+ * @param vector is the interrupt vector number.
+ *
+ * @param priority is the new priority for the interrupt vector.
+ *
+ * @retval ::RTEMS_SUCCESSFUL The requested operation was successful.
+ *
+ * @retval ::RTEMS_INVALID_ID There was no interrupt vector associated with the
+ *   number specified by ``vector``.
+ *
+ * @retval ::RTEMS_INVALID_PRIORITY The priority specified by ``priority`` was
+ *   not a valid new priority for the interrupt vector.
+ *
+ * @retval ::RTEMS_UNSATISFIED The request to set the priority of the interrupt
+ *   vector has not been satisfied.
+ *
+ * @par Notes
+ * @parblock
+ * The rtems_interrupt_get_priority() directive may be used to get the priority
+ * associated with an interrupt vector.
+ *
+ * The interrupt prioritization support depends on the interrupt controller of
+ * the 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.
+ *
+ * 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.  Such interrupts shall not use operating system services.
+ *
+ * For the RISC-V Platform-Level Interrupt Controller (PLIC), all priority
+ * values from 0 to the maximum priority value of the platform are supported.
+ * 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.
+ * @endparblock
+ *
+ * @par Constraints
+ * @parblock
+ * 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.
+ * @endparblock
+ */
+rtems_status_code rtems_interrupt_set_priority(
+  rtems_vector_number vector,
+  uint32_t            priority
+);
+
 /* Generated from spec:/rtems/intr/if/get-affinity */
 
 /**
@@ -2020,6 +2149,29 @@ typedef struct {
    * rtems_interrupt_raise(), or rtems_interrupt_raise_on().
    */
   rtems_interrupt_signal_variant trigger_signal;
+
+  /**
+   * @brief This member is true, if the priority of the interrupt vector can be
+   *   obtained by rtems_interrupt_get_priority(), otherwise it is false.
+   */
+  bool can_get_priority;
+
+  /**
+   * @brief This member is true, if the priority of the interrupt vector can be
+   *   set by rtems_interrupt_set_priority(), otherwise it is false.
+   */
+  bool can_set_priority;
+
+  /**
+   * @brief 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.
+   */
+  uint32_t maximum_priority;
 } rtems_interrupt_attributes;
 
 /* Generated from spec:/rtems/intr/if/get-attributes */
-- 
2.35.3