rtems: Generate <rtems/rtems/intr.h>

Change license to BSD-2-Clause according to file histories and
documentation re-licensing agreement.

Update #3899.
Update #3993.

2 files changed, 276 insertions, 226 deletions

diff --git a/cpukit/include/rtems/irq-extension.h b/cpukit/include/rtems/irq-extension.h
index 2105194c00..915be09e2b 100644
--- a/cpukit/include/rtems/irq-extension.h
+++ b/cpukit/include/rtems/irq-extension.h
@@ -29,7 +29,7 @@ extern "C" {
 /**
  * @defgroup rtems_interrupt_extension Interrupt Manager Extension
  *
- * @ingroup ClassicINTR
+ * @ingroup RTEMSAPIClassicIntr
  *
  * In addition to the Classic API interrupt handler with a handle are
  * supported.  You can also install multiple shared handler for one interrupt
diff --git a/cpukit/include/rtems/rtems/intr.h b/cpukit/include/rtems/rtems/intr.h
index a55b64d207..e92b918fc4 100644
--- a/cpukit/include/rtems/rtems/intr.h
+++ b/cpukit/include/rtems/rtems/intr.h
@@ -1,367 +1,394 @@
+/* SPDX-License-Identifier: BSD-2-Clause */
+
 /**
- *  @file
- *
- * @ingroup ClassicINTR
+ * @file
  *
- * This include file contains all the constants and structures associated with
- * the Interrupt Manager.
+ * @brief This header file defines the Interrupt Manager API.
  */
 
-/* COPYRIGHT (c) 1989-2013.
- * On-Line Applications Research Corporation (OAR).
+/*
+ * Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de)
+ * Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR)
+ *
+ * Redistribution and use in source and binary forms, with or without
+ * modification, are permitted provided that the following conditions
+ * are met:
+ * 1. Redistributions of source code must retain the above copyright
+ *    notice, this list of conditions and the following disclaimer.
+ * 2. Redistributions in binary form must reproduce the above copyright
+ *    notice, this list of conditions and the following disclaimer in the
+ *    documentation and/or other materials provided with the distribution.
+ *
+ * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+ * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+ * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+ * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE
+ * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+ * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+ * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+ * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+ * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+ * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+ * POSSIBILITY OF SUCH DAMAGE.
+ */
+
+/*
+ * This file is part of the RTEMS quality process and was automatically
+ * generated.  If you find something that needs to be fixed or
+ * worded better please post a report or patch to an RTEMS mailing list
+ * or raise a bug report:
+ *
+ * https://www.rtems.org/bugs.html
  *
- * The license and distribution terms for this file may be
- * found in the file LICENSE in this distribution or at
- * http://www.rtems.org/license/LICENSE.
+ * For information on updating and regenerating please refer to the How-To
+ * section in the Software Requirements Engineering chapter of the
+ * RTEMS Software Engineering manual.  The manual is provided as a part of
+ * a release.  For development sources please refer to the online
+ * documentation at:
+ *
+ * https://docs.rtems.org
  */
 
+/* Generated from spec:/rtems/intr/if/header */
+
 #ifndef _RTEMS_RTEMS_INTR_H
 #define _RTEMS_RTEMS_INTR_H
 
 #include <rtems/rtems/status.h>
+#include <rtems/score/basedefs.h>
+#include <rtems/score/cpu.h>
 #include <rtems/score/isr.h>
+#include <rtems/score/isrlevel.h>
 #include <rtems/score/isrlock.h>
+#include <rtems/score/smplock.h>
 
 #ifdef __cplusplus
 extern "C" {
 #endif
 
+/* Generated from spec:/rtems/intr/if/group */
+
 /**
- *  @defgroup ClassicINTR Interrupts
+ * @defgroup RTEMSAPIClassicIntr Interrupt Manager
  *
- *  @ingroup RTEMSAPIClassic
+ * @ingroup RTEMSAPIClassic
  *
- *  This encapsulates functionality related to the Classic API Interrupt
- *  Manager.
- */
-/**@{*/
-
-/**
- *  @brief Interrupt level type.
+ * @brief Any real-time executive must provide a mechanism for quick response
+ *   to externally generated interrupts to satisfy the critical time
+ *   constraints of the application.  The Interrupt Manager provides this
+ *   mechanism for RTEMS. This manager permits quick interrupt response times
+ *   by providing the critical ability to alter task execution which allows a
+ *   task to be preempted upon exit from an ISR.
  */
-typedef ISR_Level rtems_interrupt_level;
 
-/**
- *  @brief Control block type used to manage the vectors.
- */
-typedef ISR_Vector_number rtems_vector_number;
+/* Generated from spec:/rtems/intr/if/cause */
 
 /**
- *  @brief Return type for interrupt handler.
+ * @ingroup RTEMSAPIClassicIntr
+ *
+ * @brief %
+ *
+ * @param _interrupt_to_cause %
  */
-typedef ISR_Handler rtems_isr;
+#define rtems_interrupt_cause( _interrupt_to_cause ) %
 
-#if (CPU_SIMPLE_VECTORED_INTERRUPTS == FALSE)
+/* Generated from spec:/rtems/intr/if/clear */
 
-typedef ISR_Handler_entry rtems_isr_entry;
-
-#else
 /**
- *  @brief Interrupt handler type.
+ * @ingroup RTEMSAPIClassicIntr
+ *
+ * @brief %
  *
- *  @see rtems_interrupt_catch()
+ * @param _interrupt_to_clear %
  */
-typedef rtems_isr ( *rtems_isr_entry )(
-                 rtems_vector_number
-             );
+#define rtems_interrupt_clear( _interrupt_to_clear ) %
 
-/**
- * @brief RTEMS Interrupt Catch
- *
- * This directive installs @a new_isr_handler as the RTEMS interrupt service
- * routine for the interrupt vector with number @a vector. The previous RTEMS
- * interrupt service routine is returned in @a old_isr_handler.
- *  
- * @param[in] new_isr_handler is the address of interrupt service routine
- * @param[in] vector is the interrupt vector number
- * @param[in] old_isr_handler address at which to store previous ISR address
- * 
- * @retval RTEMS_SUCCESSFUL and *old_isr_handler filled with previous ISR
- * 		address
- */
-rtems_status_code rtems_interrupt_catch(
-  rtems_isr_entry      new_isr_handler,
-  rtems_vector_number  vector,
-  rtems_isr_entry     *old_isr_handler
-);
+#if !defined(RTEMS_SMP)
+  /* Generated from spec:/rtems/intr/if/disable */
+
+  /**
+   * @ingroup RTEMSAPIClassicIntr
+   *
+   * @brief %
+   *
+   * @param _isr_cookie %
+   */
+  #define rtems_interrupt_disable( _isr_cookie ) _ISR_Local_disable( _isr_cookie )
 #endif
 
 #if !defined(RTEMS_SMP)
+  /* Generated from spec:/rtems/intr/if/enable */
+
+  /**
+   * @ingroup RTEMSAPIClassicIntr
+   *
+   * @brief %
+   *
+   * @param _isr_cookie %
+   */
+  #define rtems_interrupt_enable( _isr_cookie ) _ISR_Local_enable( _isr_cookie )
+#endif
+
+#if !defined(RTEMS_SMP)
+  /* Generated from spec:/rtems/intr/if/flash */
+
+  /**
+   * @ingroup RTEMSAPIClassicIntr
+   *
+   * @brief %
+   *
+   * @param _isr_cookie %
+   */
+  #define rtems_interrupt_flash( _isr_cookie ) _ISR_Local_flash( _isr_cookie )
+#endif
+
+/* Generated from spec:/rtems/intr/if/is-in-progress */
 
 /**
- *  @brief Disable RTEMS Interrupt
+ * @ingroup RTEMSAPIClassicIntr
  *
- *  @note The interrupt level shall be of type @ref rtems_interrupt_level.
- *
- *  This macro is only available on uni-processor configurations.  The macro
- *  rtems_interrupt_local_disable() is available on all configurations.
+ * @brief %
  */
-#define rtems_interrupt_disable( _isr_cookie ) \
-    _ISR_Local_disable(_isr_cookie)
+#define rtems_interrupt_is_in_progress() _ISR_Is_in_progress()
+
+/* Generated from spec:/rtems/intr/if/isr */
 
 /**
- *  @brief Enable RTEMS Interrupt
+ * @ingroup RTEMSAPIClassicIntr
  *
- *  @note The interrupt level shall be of type @ref rtems_interrupt_level.
- *
- *  This macro is only available on uni-processor configurations.  The macro
- *  rtems_interrupt_local_enable() is available on all configurations.
+ * @brief %
  */
-#define rtems_interrupt_enable( _isr_cookie ) \
-    _ISR_Local_enable(_isr_cookie)
+typedef ISR_Handler rtems_isr;
+
+/* Generated from spec:/rtems/intr/if/isr-entry */
 
 /**
- *  @brief Flash RTEMS Interrupt
- *
- *  @note The interrupt level shall be of type @ref rtems_interrupt_level.
+ * @ingroup RTEMSAPIClassicIntr
  *
- *  This macro is only available on uni-processor configurations.  The macro
- *  rtems_interrupt_local_disable() and rtems_interrupt_local_enable() is
- *  available on all configurations.
+ * @brief Interrupt service routines installed by rtems_interrupt_catch() shall
+ *   have this function pointer type.
  */
-#define rtems_interrupt_flash( _isr_cookie ) \
-    _ISR_Local_flash(_isr_cookie)
+#if CPU_SIMPLE_VECTORED_INTERRUPTS == TRUE
+  typedef ISR_Handler_entry rtems_isr_entry;
+#else
+  typedef void ( *rtems_isr_entry )( void * );
+#endif
 
-#endif /* RTEMS_SMP */
+/* Generated from spec:/rtems/intr/if/level */
 
 /**
- * @brief This macro disables the interrupts on the current processor.
+ * @ingroup RTEMSAPIClassicIntr
  *
- * On SMP configurations this will not ensure system wide mutual exclusion.
- * Use interrupt locks instead.
+ * @brief %
+ */
+typedef ISR_Level rtems_interrupt_level;
+
+/* Generated from spec:/rtems/intr/if/local-disable */
+
+/**
+ * @ingroup RTEMSAPIClassicIntr
  *
- * @param[in] _isr_cookie The previous interrupt level is returned.  The type
- *   of this variable must be rtems_interrupt_level.
+ * @brief %
  *
- * @see rtems_interrupt_local_enable().
+ * @param _isr_cookie %
  */
 #define rtems_interrupt_local_disable( _isr_cookie ) \
   _ISR_Local_disable( _isr_cookie )
 
+/* Generated from spec:/rtems/intr/if/local-enable */
+
 /**
- * @brief This macro restores the previous interrupt level on the current
- * processor.
+ * @ingroup RTEMSAPIClassicIntr
+ *
+ * @brief %
  *
- * @param[in] _isr_cookie The previous interrupt level returned by
- *   rtems_interrupt_local_disable().
+ * @param _isr_cookie %
  */
 #define rtems_interrupt_local_enable( _isr_cookie ) \
   _ISR_Local_enable( _isr_cookie )
 
-/**
- *  @brief RTEMS Interrupt Is in Progress
- *
- *  A return value of true indicates that the caller is an interrupt service
- *  routine and @b not a thread.  The directives available to an interrupt
- *  service routine are restricted.
- */
-#define rtems_interrupt_is_in_progress() \
-    _ISR_Is_in_progress()
+/* Generated from spec:/rtems/intr/if/lock */
 
 /**
- *  @brief This routine generates an interrupt.
+ * @ingroup RTEMSAPIClassicIntr
  *
- *  @note No implementation.
+ * @brief %
  */
-#define rtems_interrupt_cause( _interrupt_to_cause )
+typedef ISR_lock_Control rtems_interrupt_lock;
+
+/* Generated from spec:/rtems/intr/if/lock-acquire */
 
 /**
- *  @brief This routine clears the specified interrupt.
+ * @ingroup RTEMSAPIClassicIntr
+ *
+ * @brief %
  *
- *  @note No implementation.
+ * @param _lock %
+ *
+ * @param _lock_context %
  */
-#define rtems_interrupt_clear( _interrupt_to_clear )
+#define rtems_interrupt_lock_acquire( _lock, _lock_context ) \
+  _ISR_lock_ISR_disable_and_acquire( _lock, _lock_context )
+
+/* Generated from spec:/rtems/intr/if/lock-acquire-isr */
 
 /**
- * @defgroup ClassicINTRLocks Interrupt Locks
- *
- * @ingroup ClassicINTR
+ * @ingroup RTEMSAPIClassicIntr
  *
- * @brief Low-level lock to protect critical sections accessed by threads and
- * interrupt service routines.
+ * @brief %
  *
- * On single processor configurations the interrupt locks degrade to simple
- * interrupt disable/enable sequences.  No additional storage or objects are
- * required.
+ * @param _lock %
  *
- * This synchronization primitive is supported on SMP configurations.  Here SMP
- * locks are used.
- * @{
+ * @param _lock_context %
  */
+#if defined(RTEMS_SMP)
+  #define rtems_interrupt_lock_acquire_isr( _lock, _lock_context ) \
+    _SMP_lock_Acquire( \
+      &( _lock )->Lock, \
+      &( _lock_context )->Lock_context \
+    )
+#else
+  #define rtems_interrupt_lock_acquire_isr( _lock, _lock_context ) \
+    do { (void) _lock_context; } while ( 0 )
+#endif
 
-/**
- * @brief Interrupt lock control.
- */
-typedef ISR_lock_Control rtems_interrupt_lock;
+/* Generated from spec:/rtems/intr/if/lock-context */
 
 /**
- * @brief Local interrupt lock context for acquire and release pairs.
+ * @ingroup RTEMSAPIClassicIntr
+ *
+ * @brief %
  */
 typedef ISR_lock_Context rtems_interrupt_lock_context;
 
-/**
- * @brief Defines an interrupt lock member.
- *
- * Do not add a ';' after this macro.
- *
- * @param _designator The designator for the interrupt lock.
- */
-#define RTEMS_INTERRUPT_LOCK_MEMBER( _designator ) \
-  ISR_LOCK_MEMBER( _designator )
+/* Generated from spec:/rtems/intr/if/lock-declare */
 
 /**
- * @brief Declares an interrupt lock variable.
+ * @ingroup RTEMSAPIClassicIntr
+ *
+ * @brief %
  *
- * Do not add a ';' after this macro.
+ * @param _qualifier %
  *
- * @param _qualifier The qualifier for the interrupt lock, e.g. extern.
- * @param _designator The designator for the interrupt lock.
+ * @param _designator %
  */
 #define RTEMS_INTERRUPT_LOCK_DECLARE( _qualifier, _designator ) \
   ISR_LOCK_DECLARE( _qualifier, _designator )
 
+/* Generated from spec:/rtems/intr/if/lock-define */
+
 /**
- * @brief Defines an interrupt lock variable.
+ * @ingroup RTEMSAPIClassicIntr
+ *
+ * @brief %
+ *
+ * @param _qualifier %
  *
- * Do not add a ';' after this macro.
+ * @param _designator %
  *
- * @param _qualifier The qualifier for the interrupt lock, e.g. static.
- * @param _designator The designator for the interrupt lock.
- * @param _name The name for the interrupt lock.  It must be a string.  The
- * name is only used if profiling is enabled.
+ * @param _name %
  */
 #define RTEMS_INTERRUPT_LOCK_DEFINE( _qualifier, _designator, _name ) \
   ISR_LOCK_DEFINE( _qualifier, _designator, _name )
 
+/* Generated from spec:/rtems/intr/if/lock-destroy */
+
 /**
- * @brief Defines an interrupt lock variable reference.
+ * @ingroup RTEMSAPIClassicIntr
  *
- * Do not add a ';' after this macro.
+ * @brief %
  *
- * @param _designator The designator for the interrupt lock reference.
- * @param _target The target for the interrupt lock reference.
+ * @param _lock %
  */
-#define RTEMS_INTERRUPT_LOCK_REFERENCE( _designator, _target ) \
-  ISR_LOCK_REFERENCE( _designator, _target )
+#define rtems_interrupt_lock_destroy( _lock ) _ISR_lock_Destroy( _lock )
 
-/**
- * @brief Initializer for static initialization of interrupt locks.
- *
- * @param _name The name for the interrupt lock.  It must be a string.  The
- * name is only used if profiling is enabled.
- */
-#define RTEMS_INTERRUPT_LOCK_INITIALIZER( _name ) ISR_LOCK_INITIALIZER( _name )
+/* Generated from spec:/rtems/intr/if/lock-initialize */
 
 /**
- * @brief Initializes an interrupt lock.
+ * @ingroup RTEMSAPIClassicIntr
+ *
+ * @brief %
  *
- * Concurrent initialization leads to unpredictable results.
+ * @param _lock %
  *
- * @param[in,out] _lock The interrupt lock.
- * @param[in] _name The name for the interrupt lock.  This name must be a
- * string persistent throughout the life time of this lock.  The name is only
- * used if profiling is enabled.
+ * @param _name %
  */
 #define rtems_interrupt_lock_initialize( _lock, _name ) \
   _ISR_lock_Initialize( _lock, _name )
 
+/* Generated from spec:/rtems/intr/if/lock-initializer */
+
 /**
- * @brief Destroys an interrupt lock.
+ * @ingroup RTEMSAPIClassicIntr
  *
- * Concurrent destruction leads to unpredictable results.
+ * @brief %
  *
- * @param[in,out] _lock The interrupt lock control.
+ * @param _name %
  */
-#define rtems_interrupt_lock_destroy( _lock ) \
-  _ISR_lock_Destroy( _lock )
+#define RTEMS_INTERRUPT_LOCK_INITIALIZER( _name ) ISR_LOCK_INITIALIZER( _name )
+
+/* Generated from spec:/rtems/intr/if/lock-isr-disable */
 
 /**
- * @brief Disables interrupts on the current processor.
+ * @ingroup RTEMSAPIClassicIntr
  *
- * This function can be used in thread and interrupt context.
+ * @brief %
  *
- * @param[in,out] _lock_context The local interrupt lock context for an acquire
- * and release pair.
- *
- * @see rtems_interrupt_lock_acquire_isr().
+ * @param _lock_context %
  */
 #define rtems_interrupt_lock_interrupt_disable( _lock_context ) \
   _ISR_lock_ISR_disable( _lock_context )
 
+/* Generated from spec:/rtems/intr/if/lock-member */
+
 /**
- * @brief Acquires an interrupt lock.
- *
- * Interrupts will be disabled.  On SMP configurations this function acquires
- * an SMP lock.
- *
- * This function can be used in thread and interrupt context.
+ * @ingroup RTEMSAPIClassicIntr
  *
- * @param[in,out] _lock The interrupt lock.
- * @param[in,out] _lock_context The local interrupt lock context for an acquire
- * and release pair.
+ * @brief %
  *
- * @see rtems_interrupt_lock_release().
+ * @param _designator %
  */
-#define rtems_interrupt_lock_acquire( _lock, _lock_context ) \
-  _ISR_lock_ISR_disable_and_acquire( _lock, _lock_context )
+#define RTEMS_INTERRUPT_LOCK_MEMBER( _designator ) \
+  ISR_LOCK_MEMBER( _designator )
+
+/* Generated from spec:/rtems/intr/if/lock-reference */
 
 /**
- * @brief Releases an interrupt lock.
- *
- * The interrupt status will be restored.  On SMP configurations this function
- * releases an SMP lock.
+ * @ingroup RTEMSAPIClassicIntr
  *
- * This function can be used in thread and interrupt context.
+ * @brief %
  *
- * @param[in,out] _lock The interrupt lock.
- * @param[in,out] _lock_context The local interrupt lock context for an acquire
- * and release pair.
+ * @param _designator %
  *
- * @see rtems_interrupt_lock_acquire().
+ * @param _target %
  */
-#define rtems_interrupt_lock_release( _lock, _lock_context ) \
-  _ISR_lock_Release_and_ISR_enable( _lock, _lock_context )
+#define RTEMS_INTERRUPT_LOCK_REFERENCE( _designator, _target ) \
+  ISR_LOCK_REFERENCE( _designator, _target )
+
+/* Generated from spec:/rtems/intr/if/lock-release */
 
 /**
- * @brief Acquires an interrupt lock in the corresponding interrupt service
- * routine.
+ * @ingroup RTEMSAPIClassicIntr
  *
- * The interrupt status will remain unchanged.  On SMP configurations this
- * function acquires an SMP lock.
+ * @brief %
  *
- * In case the corresponding interrupt service routine can be interrupted by
- * higher priority interrupts and these interrupts enter the critical section
- * protected by this lock, then the result is unpredictable.
+ * @param _lock %
  *
- * @param[in,out] _lock The interrupt lock.
- * @param[in,out] _lock_context The local interrupt lock context for an acquire
- * and release pair.
- *
- * @see rtems_interrupt_lock_release_isr().
+ * @param _lock_context %
  */
-#if defined(RTEMS_SMP)
-  #define rtems_interrupt_lock_acquire_isr( _lock, _lock_context ) \
-    _SMP_lock_Acquire( \
-      &( _lock )->Lock, \
-      &( _lock_context )->Lock_context \
-    )
-#else
-  #define rtems_interrupt_lock_acquire_isr( _lock, _lock_context ) \
-    do { (void) _lock_context; } while ( 0 )
-#endif
+#define rtems_interrupt_lock_release( _lock, _lock_context ) \
+  _ISR_lock_Release_and_ISR_enable( _lock, _lock_context )
+
+/* Generated from spec:/rtems/intr/if/lock-release-isr */
 
 /**
- * @brief Releases an interrupt lock in the corresponding interrupt service
- * routine.
+ * @ingroup RTEMSAPIClassicIntr
  *
- * The interrupt status will remain unchanged.  On SMP configurations this
- * function releases an SMP lock.
+ * @brief %
  *
- * @param[in,out] _lock The interrupt lock.
- * @param[in,out] _lock_context The local interrupt lock context for an acquire
- * and release pair.
+ * @param _lock %
  *
- * @see rtems_interrupt_lock_acquire_isr().
+ * @param _lock_context %
  */
 #if defined(RTEMS_SMP)
   #define rtems_interrupt_lock_release_isr( _lock, _lock_context ) \
@@ -374,13 +401,36 @@ typedef ISR_lock_Context rtems_interrupt_lock_context;
     do { (void) _lock_context; } while ( 0 )
 #endif
 
-/** @} */
+/* Generated from spec:/rtems/intr/if/vector-number */
+
+/**
+ * @ingroup RTEMSAPIClassicIntr
+ *
+ * @brief %
+ */
+typedef ISR_Vector_number rtems_vector_number;
+
+/* Generated from spec:/rtems/intr/if/catch */
+
+/**
+ * @ingroup RTEMSAPIClassicIntr
+ *
+ * @brief %
+ *
+ * @param new_isr_handler %
+ *
+ * @param vector %
+ *
+ * @param old_isr_handler %
+ */
+rtems_status_code rtems_interrupt_catch(
+  rtems_isr_entry     new_isr_handler,
+  rtems_vector_number vector,
+  rtems_isr_entry    *old_isr_handler
+);
 
 #ifdef __cplusplus
 }
 #endif
 
-/**@}*/
-
-#endif
-/* end of include file */
+#endif /* _RTEMS_RTEMS_INTR_H */