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 _______________________________________________ devel mailing list devel@rtems.org http://lists.rtems.org/mailman/listinfo/devel
