[PATCH 04/41] rtems: Add rtems_interrupt_cause_on()

[Gedare Bloom]

Before we bake this into the API forever, I want to ask if "cause" is
the right word to use here? Often, "interrupt cause" is thought of as
a noun to mean what caused the interrupt, while the verb is usually
"raise" or post, trigger, etc. Because "cause" is both a noun and a
verb that mean something in this context, it may be better to use a
different verb. English is pretty much terrible.

I don't have a major problem with sticking to "cause" but thought I'd
bring this up.

On Mon, Jul 12, 2021 at 6:50 AM Sebastian Huber
<sebastian.huber at embedded-brains.de> wrote:
>
> Document the currently not implemented rtems_interrupt_cause() and
> rtems_interrupt_clear().
>
> Update #3269.
> ---
>  cpukit/include/rtems/rtems/intr.h | 162 +++++++++++++++++++++++-------
>  1 file changed, 125 insertions(+), 37 deletions(-)
>
> diff --git a/cpukit/include/rtems/rtems/intr.h b/cpukit/include/rtems/rtems/intr.h
> index 178cf342df..a8b1b892b5 100644
> --- a/cpukit/include/rtems/rtems/intr.h
> +++ b/cpukit/include/rtems/rtems/intr.h
> @@ -54,6 +54,7 @@
>  #ifndef _RTEMS_RTEMS_INTR_H
>  #define _RTEMS_RTEMS_INTR_H
>
> +#include <stdint.h>
>  #include <rtems/rtems/status.h>
>  #include <rtems/score/basedefs.h>
>  #include <rtems/score/cpu.h>
> @@ -99,7 +100,7 @@ typedef ISR_Handler rtems_isr;
>   * @ingroup RTEMSAPIClassicIntr
>   *
>   * @brief Interrupt service routines installed by rtems_interrupt_catch() shall
> - *   have this function pointer type.
> + *   have this type.
>   */
>  #if CPU_SIMPLE_VECTORED_INTERRUPTS == TRUE
>    typedef ISR_Handler_entry rtems_isr_entry;
> @@ -502,42 +503,6 @@ rtems_status_code rtems_interrupt_catch(
>   */
>  #define rtems_interrupt_is_in_progress() _ISR_Is_in_progress()
>
> -/* Generated from spec:/rtems/intr/if/cause */
> -
> -/**
> - * @ingroup RTEMSAPIClassicIntr
> - *
> - * @brief Causes the interrupt.
> - *
> - * @param _vector is the vector number of the interrupt to cause.
> - *
> - * @par Constraints
> - * @parblock
> - * The following constraints apply to this directive:
> - *
> - * * The directive is not implemented.
> - * @endparblock
> - */
> -#define rtems_interrupt_cause( _vector ) do { } while ( 0 )
> -
> -/* Generated from spec:/rtems/intr/if/clear */
> -
> -/**
> - * @ingroup RTEMSAPIClassicIntr
> - *
> - * @brief Clears the interrupt.
> - *
> - * @param _vector is the vector number of the interrupt to clear.
> - *
> - * @par Constraints
> - * @parblock
> - * The following constraints apply to this directive:
> - *
> - * * The directive is not implemented.
> - * @endparblock
> - */
> -#define rtems_interrupt_clear( _vector ) do { } while ( 0 )
> -
>  /* Generated from spec:/rtems/intr/if/lock-initialize */
>
>  /**
> @@ -909,6 +874,129 @@ rtems_status_code rtems_interrupt_catch(
>  #define RTEMS_INTERRUPT_LOCK_REFERENCE( _designator, _target ) \
>    ISR_LOCK_REFERENCE( _designator, _target )
>
> +/* Generated from spec:/rtems/intr/if/cause */
> +
> +/**
> + * @ingroup RTEMSAPIClassicIntr
> + *
> + * @brief Causes the interrupt vector.
> + *
> + * @param vector is the number of the interrupt vector to cause.
> + *
> + * @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_UNSATISFIED The request to cause the interrupt vector has
> + *   not been satisfied.
> + *
> + * @par Notes
> + * The rtems_interrupt_get_attributes() directive may be used to check if an
> + * interrupt vector can be caused.
> + *
> + * @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_cause( rtems_vector_number vector );
> +
> +/* Generated from spec:/rtems/intr/if/cause-on */
> +
> +/**
> + * @ingroup RTEMSAPIClassicIntr
> + *
> + * @brief Causes the interrupt vector on the processor.
> + *
> + * @param vector is the number of the interrupt vector to cause.
> + *
> + * @param cpu_index is the index of the target processor of the interrupt
> + *   vector to cause.
> + *
> + * @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_NOT_CONFIGURED The processor specified by ``cpu_index`` was
> + *   not configured to be used by the application.
> + *
> + * @retval ::RTEMS_INCORRECT_STATE The processor specified by ``cpu_index`` was
> + *   configured to be used by the application, however, it was not online.
> + *
> + * @retval ::RTEMS_UNSATISFIED The request to cause the interrupt vector has
> + *   not been satisfied.
> + *
> + * @par Notes
> + * The rtems_interrupt_get_attributes() directive may be used to check if an
> + * interrupt vector can be caused on a processor.
> + *
> + * @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_cause_on(
> +  rtems_vector_number vector,
> +  uint32_t            cpu_index
> +);
> +
> +/* Generated from spec:/rtems/intr/if/clear */
> +
> +/**
> + * @ingroup RTEMSAPIClassicIntr
> + *
> + * @brief Clears the interrupt vector.
> + *
> + * @param vector is the number of the interrupt vector to clear.
> + *
> + * @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_UNSATISFIED The request to cause the interrupt vector has
> + *   not been satisfied.
> + *
> + * @par Notes
> + * The rtems_interrupt_get_attributes() directive may be used to check if an
> + * interrupt vector can be cleared.
> + *
> + * @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_clear( rtems_vector_number vector );
> +
>  #ifdef __cplusplus
>  }
>  #endif
> --
> 2.26.2
>
> _______________________________________________
> devel mailing list
> devel at rtems.org
> http://lists.rtems.org/mailman/listinfo/devel