[RTEMS Project] #5002: Add API to get and set interrupt priorities for interrupt vectors

[RTEMS trac]

#5002: Add API to get and set interrupt priorities for interrupt vectors
------------------------------+-----------------------------
  Reporter:  Sebastian Huber  |      Owner:  Sebastian Huber
      Type:  enhancement      |     Status:  assigned
  Priority:  normal           |  Milestone:  6.1
 Component:  rtems            |    Version:  6
  Severity:  normal           |   Keywords:
Blocked By:                   |   Blocking:
------------------------------+-----------------------------
 Modern interrupt controllers support interrupt priorities. There is
 currently no API in RTEMS to get or set interrupt priorities. Here is a
 proposal:
 {{{#!patch
 diff --git a/cpukit/include/rtems/rtems/intr.h
 b/cpukit/include/rtems/rtems/intr.h
 index f8809015e4..425e53797a 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,97 @@ 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 set 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
 + * The rtems_interrupt_get_priority() directive may be used to get 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_set_priority(
 +  rtems_vector_number vector,
 +  uint32_t            priority
 +);
 +
  /* Generated from spec:/rtems/intr/if/get-affinity */

  /**
 @@ -2020,6 +2111,28 @@ 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.  Where
 nested
 +   *   interrupts are supported, interrupt vectors can interrupt other
 interrupt
 +   *   vectors which have a higher priority value.  The higher the
 priority
 +   *   value, the less important is the service of the associated
 interrupt
 +   *   vector.
 +   */
 +  uint32_t maximum_priority;
  } rtems_interrupt_attributes;

  /* Generated from spec:/rtems/intr/if/get-attributes */
 }}}

--
Ticket URL: <http://devel.rtems.org/ticket/5002>
RTEMS Project <http://www.rtems.org/>
RTEMS Project