diff options
author | Sebastian Huber <sebastian.huber@embedded-brains.de> | 2020-06-22 14:20:19 +0200 |
---|---|---|
committer | Sebastian Huber <sebastian.huber@embedded-brains.de> | 2020-09-22 10:06:05 +0200 |
commit | e623fab3a02bc255392972a1d74ee6660349351e (patch) | |
tree | 20129ae88bcdbb30b159920fa12114143d7673aa | |
parent | f9e010fc8d49979340b7c77dd36fd176116e4963 (diff) |
Generate <rtems/rtems/intr.h>
-rw-r--r-- | cpukit/include/rtems/rtems/intr.h | 430 |
1 files changed, 208 insertions, 222 deletions
diff --git a/cpukit/include/rtems/rtems/intr.h b/cpukit/include/rtems/rtems/intr.h index a55b64d207..f884cd80fc 100644 --- a/cpukit/include/rtems/rtems/intr.h +++ b/cpukit/include/rtems/rtems/intr.h @@ -1,367 +1,358 @@ +/* SPDX-License-Identifier: BSD-2-Clause */ + /** - * @file + * @file * - * @ingroup ClassicINTR + * @ingroup RTEMSAPIClassicIntr * - * 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) 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. */ -/* COPYRIGHT (c) 1989-2013. - * On-Line Applications Research Corporation (OAR). +/* + * This file was automatically generated. Do not edit it manually. + * Please have a look at + * + * https://docs.rtems.org/branches/master/eng/req/howto.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 how to maintain and re-generate this file. */ #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 /** - * @defgroup ClassicINTR Interrupts + * @defgroup RTEMSAPIClassicIntr Interrupt Manager * - * @ingroup RTEMSAPIClassic + * @ingroup RTEMSAPIClassic * - * This encapsulates functionality related to the Classic API Interrupt - * Manager. + * @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. */ -/**@{*/ /** - * @brief Interrupt level type. + * @ingroup RTEMSAPIClassicIntr + * + * @brief % */ -typedef ISR_Level rtems_interrupt_level; +typedef ISR_Vector_number rtems_vector_number; /** - * @brief Control block type used to manage the vectors. + * @ingroup RTEMSAPIClassicIntr + * + * @brief Interrupt service routines installed by rtems_interrupt_catch() shall + * have this function pointer type. */ -typedef ISR_Vector_number rtems_vector_number; +#if CPU_SIMPLE_VECTORED_INTERRUPTS == TRUE + typedef ISR_Handler_entry rtems_isr_entry; +#else + typedef void ( *rtems_isr_entry )( void * ); +#endif /** - * @brief Return type for interrupt handler. + * @ingroup RTEMSAPIClassicIntr + * + * @brief % + * + * @param new_isr_handler % + * + * @param vector % + * + * @param old_isr_handler % */ -typedef ISR_Handler rtems_isr; - -#if (CPU_SIMPLE_VECTORED_INTERRUPTS == FALSE) - -typedef ISR_Handler_entry rtems_isr_entry; +rtems_status_code rtems_interrupt_catch( + rtems_isr_entry new_isr_handler, + rtems_vector_number vector, + rtems_isr_entry *old_isr_handler +); -#else /** - * @brief Interrupt handler type. + * @ingroup RTEMSAPIClassicIntr * - * @see rtems_interrupt_catch() + * @brief % + * + * @param _interrupt_to_cause % */ -typedef rtems_isr ( *rtems_isr_entry )( - rtems_vector_number - ); +#define rtems_interrupt_cause( _interrupt_to_cause ) % /** - * @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 + * @ingroup RTEMSAPIClassicIntr + * + * @brief % + * + * @param _interrupt_to_clear % */ -rtems_status_code rtems_interrupt_catch( - rtems_isr_entry new_isr_handler, - rtems_vector_number vector, - rtems_isr_entry *old_isr_handler -); +#define rtems_interrupt_clear( _interrupt_to_clear ) % + +#if !defined(RTEMS_SMP) + /** + * @ingroup RTEMSAPIClassicIntr + * + * @brief % + * + * @param _isr_cookie % + */ + #define rtems_interrupt_disable( _isr_cookie ) _ISR_Local_disable( _isr_cookie ) #endif #if !defined(RTEMS_SMP) + /** + * @ingroup RTEMSAPIClassicIntr + * + * @brief % + * + * @param _isr_cookie % + */ + #define rtems_interrupt_enable( _isr_cookie ) _ISR_Local_enable( _isr_cookie ) +#endif + +#if !defined(RTEMS_SMP) + /** + * @ingroup RTEMSAPIClassicIntr + * + * @brief % + * + * @param _isr_cookie % + */ + #define rtems_interrupt_flash( _isr_cookie ) _ISR_Local_flash( _isr_cookie ) +#endif /** - * @brief Disable 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() 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() /** - * @brief Enable 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_enable() is available on all configurations. + * @brief % */ -#define rtems_interrupt_enable( _isr_cookie ) \ - _ISR_Local_enable(_isr_cookie) +typedef ISR_Handler rtems_isr; /** - * @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 % */ -#define rtems_interrupt_flash( _isr_cookie ) \ - _ISR_Local_flash(_isr_cookie) - -#endif /* RTEMS_SMP */ +typedef ISR_Level rtems_interrupt_level; /** - * @brief This macro disables the interrupts on the current processor. - * - * On SMP configurations this will not ensure system wide mutual exclusion. - * Use interrupt locks instead. + * @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 ) /** - * @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 + * @ingroup RTEMSAPIClassicIntr * - * 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. + * @brief % */ -#define rtems_interrupt_is_in_progress() \ - _ISR_Is_in_progress() +typedef ISR_lock_Control rtems_interrupt_lock; /** - * @brief This routine generates an interrupt. + * @ingroup RTEMSAPIClassicIntr * - * @note No implementation. - */ -#define rtems_interrupt_cause( _interrupt_to_cause ) - -/** - * @brief This routine clears the specified interrupt. + * @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 ) /** - * @defgroup ClassicINTRLocks Interrupt Locks + * @ingroup RTEMSAPIClassicIntr * - * @ingroup ClassicINTR + * @brief % * - * @brief Low-level lock to protect critical sections accessed by threads and - * interrupt service routines. + * @param _lock % * - * On single processor configurations the interrupt locks degrade to simple - * interrupt disable/enable sequences. No additional storage or objects are - * required. - * - * This synchronization primitive is supported on SMP configurations. Here SMP - * locks are used. - * @{ - */ - -/** - * @brief Interrupt lock control. + * @param _lock_context % */ -typedef ISR_lock_Control rtems_interrupt_lock; +#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 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. + * @ingroup RTEMSAPIClassicIntr * - * Do not add a ';' after this macro. + * @brief % * - * @param _designator The designator for the interrupt lock. - */ -#define RTEMS_INTERRUPT_LOCK_MEMBER( _designator ) \ - ISR_LOCK_MEMBER( _designator ) - -/** - * @brief Declares an interrupt lock variable. - * - * 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 ) /** - * @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 ) /** - * @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. + * @ingroup RTEMSAPIClassicIntr * - * @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 ) - -/** - * @brief Initializes an interrupt lock. + * @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 ) /** - * @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 ) /** - * @brief Disables interrupts on the current processor. - * - * This function can be used in thread and interrupt context. + * @ingroup RTEMSAPIClassicIntr * - * @param[in,out] _lock_context The local interrupt lock context for an acquire - * and release pair. + * @brief % * - * @see rtems_interrupt_lock_acquire_isr(). + * @param _lock_context % */ #define rtems_interrupt_lock_interrupt_disable( _lock_context ) \ _ISR_lock_ISR_disable( _lock_context ) /** - * @brief Acquires an interrupt lock. - * - * Interrupts will be disabled. On SMP configurations this function acquires - * 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. - * - * @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 ) /** - * @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 ) /** - * @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 ) /** - * @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 +365,8 @@ typedef ISR_lock_Context rtems_interrupt_lock_context; do { (void) _lock_context; } while ( 0 ) #endif -/** @} */ - #ifdef __cplusplus } #endif -/**@}*/ - -#endif -/* end of include file */ +#endif /* _RTEMS_RTEMS_INTR_H */ |