rtems/score/corebarrierimpl.h

0001 /* SPDX-License-Identifier: BSD-2-Clause */
0002
0003 /**
0004  * @file
0005  *
0006  * @ingroup RTEMSScoreBarrier
0007  *
0008  * @brief This header file provides interfaces of the
0009  *   @ref RTEMSScoreBarrier which are only used by the implementation.
0010  */
0011
0012 /*
0013  *  COPYRIGHT (c) 1989-2006.
0014  *  On-Line Applications Research Corporation (OAR).
0015  *
0016  * Redistribution and use in source and binary forms, with or without
0017  * modification, are permitted provided that the following conditions
0018  * are met:
0019  * 1. Redistributions of source code must retain the above copyright
0020  *    notice, this list of conditions and the following disclaimer.
0021  * 2. Redistributions in binary form must reproduce the above copyright
0022  *    notice, this list of conditions and the following disclaimer in the
0023  *    documentation and/or other materials provided with the distribution.
0024  *
0025  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
0026  * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
0027  * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
0028  * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE
0029  * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
0030  * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
0031  * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
0032  * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
0033  * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
0034  * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
0035  * POSSIBILITY OF SUCH DAMAGE.
0036  */
0037
0038 #ifndef _RTEMS_SCORE_COREBARRIERIMPL_H
0039 #define _RTEMS_SCORE_COREBARRIERIMPL_H
0040
0041 #include <rtems/score/corebarrier.h>
0042 #include <rtems/score/status.h>
0043 #include <rtems/score/threadqimpl.h>
0044
0045 #ifdef __cplusplus
0046 extern "C" {
0047 #endif
0048
0049 /**
0050  * @addtogroup RTEMSScoreBarrier
0051  *
0052  * @{
0053  */
0054
0055 /**
0056  * @brief This maximum thread count constant indicates that the barrier is a
0057  *   manual release barrier.
0058  */
0059 #define CORE_BARRIER_MANUAL_RELEASE_MAXIMUM_COUNT 0
0060
0061 /**
0062  * @brief These thread queue operations are used for core barriers.
0063  *
0064  * They are a specialization of ::_Thread_queue_Operations_FIFO.  The only
0065  * difference is that the extract operation decrements
0066  * CORE_barrier_Control::number_of_waiting_threads.
0067  */
0068 extern const Thread_queue_Operations _CORE_barrier_Thread_queue_operations;
0069
0070 /**
0071  * @brief Initializes the core barrier.
0072  *
0073  * @param[out] the_barrier is the barrier to initialize.
0074  *
0075  * @param maximum_count is the number of threads which must arrive at the
0076  *   barrier to trip the automatic release or
0077  *   ::CORE_BARRIER_MANUAL_RELEASE_MAXIMUM_COUNT to indicate a manual release
0078  *   barrier.
0079  */
0080 void _CORE_barrier_Initialize(
0081   CORE_barrier_Control *the_barrier,
0082   uint32_t              maximum_count
0083 );
0084
0085 /**
0086  * @brief Destroys the core barrier.
0087  *
0088  * This routine destroys the barrier.
0089  *
0090  * @param[out] the_barrier The barrier to destroy.
0091  */
0092 static inline void _CORE_barrier_Destroy(
0093   CORE_barrier_Control *the_barrier
0094 )
0095 {
0096   _Thread_queue_Destroy( &the_barrier->Wait_queue );
0097 }
0098
0099 /**
0100  * @brief Acquires critical core barrier.
0101  *
0102  * @param[in, out] the_barrier The barrier to acquire.
0103  * @param queue_context The thread queue context.
0104  */
0105 static inline void _CORE_barrier_Acquire_critical(
0106   CORE_barrier_Control *the_barrier,
0107   Thread_queue_Context *queue_context
0108 )
0109 {
0110   _Thread_queue_Acquire_critical( &the_barrier->Wait_queue, queue_context );
0111 }
0112
0113 /**
0114  * @brief Releases core barrier.
0115  *
0116  * @param[in, out] the_barrier The barrier to release.
0117  * @param queue_context The thread queue context.
0118  */
0119 static inline void _CORE_barrier_Release(
0120   CORE_barrier_Control *the_barrier,
0121   Thread_queue_Context *queue_context
0122 )
0123 {
0124   _Thread_queue_Release( &the_barrier->Wait_queue, queue_context );
0125 }
0126
0127 /**
0128  * @brief Waits for the barrier.
0129  *
0130  * This routine waits for the barrier to be released.  If the barrier
0131  * is set to automatic and this is the appropriate thread, then it returns
0132  * immediately.  Otherwise, the calling thread is blocked until the barrier
0133  * is released.
0134  *
0135  * @param[in, out] the_barrier The barrier to wait for.
0136  * @param[in, out] executing The currently executing thread.
0137  * @param wait This parameter is true if the calling thread is willing to wait.
0138  * @param queue_context The thread queue context.
0139  *
0140  * @return The method status.
0141  */
0142 Status_Control _CORE_barrier_Seize(
0143   CORE_barrier_Control *the_barrier,
0144   Thread_Control       *executing,
0145   bool                  wait,
0146   Thread_queue_Context *queue_context
0147 );
0148
0149 /**
0150  * @brief Manually releases the barrier.
0151  *
0152  * This routine manually releases the barrier.  All of the threads waiting
0153  * for the barrier will be readied.
0154  *
0155  * @param[in, out] the_barrier The barrier to surrender.
0156  * @param[out] queue_context The thread queue context.
0157  *
0158  * @return The number of unblocked threads.
0159  */
0160 static inline uint32_t _CORE_barrier_Surrender(
0161   CORE_barrier_Control *the_barrier,
0162   Thread_queue_Context *queue_context
0163 )
0164 {
0165   return _Thread_queue_Flush_critical(
0166     &the_barrier->Wait_queue.Queue,
0167     &_CORE_barrier_Thread_queue_operations,
0168     _Thread_queue_Flush_default_filter,
0169     queue_context
0170   );
0171 }
0172
0173 /**
0174  * @brief Flushes the barrier using _CORE_barrier_Do_flush().
0175  *
0176  * @param[in, out] the_barrier The barrier to flush.
0177  * @param queue_context The thread queue context.
0178  */
0179 static inline void _CORE_barrier_Flush(
0180   CORE_barrier_Control *the_barrier,
0181   Thread_queue_Context *queue_context
0182 )
0183 {
0184   _Thread_queue_Flush_critical(
0185     &the_barrier->Wait_queue.Queue,
0186     &_CORE_barrier_Thread_queue_operations,
0187     _Thread_queue_Flush_status_object_was_deleted,
0188     queue_context
0189   );
0190 }
0191
0192 /** @} */
0193
0194 #ifdef __cplusplus
0195 }
0196 #endif
0197
0198 #endif
0199 /* end of include file */