rtems/score/isrlevel.h

0001 /* SPDX-License-Identifier: BSD-2-Clause */
0002
0003 /**
0004  * @file
0005  *
0006  * @ingroup RTEMSScoreISR
0007  *
0008  * @brief This header file provides the ::ISR_Level related interfaces of the
0009  *   @ref RTEMSScoreISR.
0010  *
0011  * This header file exists to simplify include dependencies.
0012  */
0013
0014 /*
0015  *  COPYRIGHT (c) 1989-2011.
0016  *  On-Line Applications Research Corporation (OAR).
0017  *
0018  * Redistribution and use in source and binary forms, with or without
0019  * modification, are permitted provided that the following conditions
0020  * are met:
0021  * 1. Redistributions of source code must retain the above copyright
0022  *    notice, this list of conditions and the following disclaimer.
0023  * 2. Redistributions in binary form must reproduce the above copyright
0024  *    notice, this list of conditions and the following disclaimer in the
0025  *    documentation and/or other materials provided with the distribution.
0026  *
0027  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
0028  * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
0029  * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
0030  * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE
0031  * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
0032  * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
0033  * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
0034  * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
0035  * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
0036  * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
0037  * POSSIBILITY OF SUCH DAMAGE.
0038  */
0039
0040 #ifndef _RTEMS_SCORE_ISR_LEVEL_h
0041 #define _RTEMS_SCORE_ISR_LEVEL_h
0042
0043 #include <rtems/score/cpu.h>
0044 #include <rtems/score/assert.h>
0045
0046 #ifdef __cplusplus
0047 extern "C" {
0048 #endif
0049
0050 /**
0051  * @addtogroup RTEMSScoreISR ISR Handler
0052  *
0053  * @{
0054  */
0055
0056 /**
0057  *  The following type defines the control block used to manage
0058  *  the interrupt level portion of the status register.
0059  */
0060 typedef uint32_t   ISR_Level;
0061
0062 /**
0063  *  @brief Disables interrupts on this processor.
0064  *
0065  *  This macro disables all interrupts on this processor so that a critical
0066  *  section of code is protected from concurrent access by interrupts of this
0067  *  processor.  Disabling of interrupts disables thread dispatching on the
0068  *  processor as well.
0069  *
0070  *  On SMP configurations other processors can enter such sections if not
0071  *  protected by other means.
0072  *
0073  *  @param[out] _level The argument @a _level will contain the previous
0074  *  interrupt mask level.
0075  */
0076 #define _ISR_Local_disable( _level ) \
0077   do { \
0078     _CPU_ISR_Disable( _level ); \
0079     RTEMS_COMPILER_MEMORY_BARRIER(); \
0080   } while (0)
0081
0082 /**
0083  *  @brief Enables interrupts on this processor.
0084  *
0085  *  This macro restores the interrupt status on the processor with the
0086  *  interrupt level value obtained by _ISR_Local_disable().  It is used at the end of
0087  *  a critical section of code to enable interrupts so they can be processed
0088  *  again.
0089  *
0090  *  @param[in] _level The interrupt level previously obtained by
0091  *  _ISR_Local_disable().
0092  */
0093 #define _ISR_Local_enable( _level ) \
0094   do { \
0095     RTEMS_COMPILER_MEMORY_BARRIER(); \
0096     _CPU_ISR_Enable( _level ); \
0097   } while (0)
0098
0099 /**
0100  *  @brief Temporarily enables interrupts on this processor.
0101  *
0102  *  This macro temporarily enables interrupts to the previous
0103  *  interrupt mask level and then disables all interrupts so that
0104  *  the caller can continue into the second part of a critical
0105  *  section.
0106  *
0107  *  This routine is used to temporarily enable interrupts
0108  *  during a long critical section.  It is used in long sections of
0109  *  critical code when a point is reached at which interrupts can
0110  *  be temporarily enabled.  Deciding where to flash interrupts
0111  *  in a long critical section is often difficult and the point
0112  *  must be selected with care to ensure that the critical section
0113  *  properly protects itself.
0114  *
0115  *  @param[in] _level The interrupt level previously obtained by
0116  *  _ISR_Local_disable().
0117  */
0118 #define _ISR_Local_flash( _level ) \
0119   do { \
0120     RTEMS_COMPILER_MEMORY_BARRIER(); \
0121     _CPU_ISR_Flash( _level ); \
0122     RTEMS_COMPILER_MEMORY_BARRIER(); \
0123   } while (0)
0124
0125 /**
0126  * @brief Returns true if interrupts are enabled in the specified interrupt
0127  * level, otherwise returns false.
0128  *
0129  * @param[in] _level The ISR level.
0130  *
0131  * @retval true Interrupts are enabled in the interrupt level.
0132  * @retval false Otherwise.
0133  */
0134 #define _ISR_Is_enabled( _level ) \
0135   _CPU_ISR_Is_enabled( _level )
0136
0137 /**
0138  *  @brief Return current interrupt level.
0139  *
0140  *  This routine returns the current interrupt level.
0141  *
0142  *  LM32 Specific Information:
0143  *  XXX document implementation including references if appropriate
0144  *
0145  *  @retval This method returns the current level.
0146  */
0147 #define _ISR_Get_level() \
0148         _CPU_ISR_Get_level()
0149
0150 /**
0151  *  @brief Set current interrupt level.
0152  *
0153  *  This routine sets the current interrupt level to that specified
0154  *  by @a _new_level.  The new interrupt level is effective when the
0155  *  routine exits.
0156  *
0157  *  @param[in] _new_level contains the desired interrupt level.
0158  */
0159 #define _ISR_Set_level( _new_level ) \
0160   do { \
0161     RTEMS_COMPILER_MEMORY_BARRIER();  \
0162     _CPU_ISR_Set_level( _new_level ); \
0163     RTEMS_COMPILER_MEMORY_BARRIER();  \
0164   } while (0)
0165
0166 /**
0167  * @brief Checks if an ISR in progress.
0168  *
0169  * This function returns true, if the processor is currently servicing
0170  * and interrupt, and false otherwise.   A return value of true indicates
0171  * that the caller is an interrupt service routine, **not** a thread.
0172  *
0173  * @return true Returns true, if called from within an ISR, otherwise false.
0174  */
0175 bool _ISR_Is_in_progress( void );
0176
0177 /** @} */
0178
0179 #ifdef __cplusplus
0180 }
0181 #endif
0182 #endif