rtems/score/apimutex.h

0001 /* SPDX-License-Identifier: BSD-2-Clause */
0002
0003 /**
0004  * @file
0005  *
0006  * @ingroup RTEMSScoreAPIMutex
0007  *
0008  * @brief This header file provides the interfaces of the
0009  *   @ref RTEMSScoreAPIMutex.
0010  */
0011
0012 /*
0013  *  COPYRIGHT (c) 1989-2008.
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_APIMUTEX_H
0039 #define _RTEMS_SCORE_APIMUTEX_H
0040
0041 #include <rtems/score/thread.h>
0042
0043 #include <sys/lock.h>
0044
0045 /**
0046  * @defgroup RTEMSScoreAPIMutex API Mutex Handler
0047  *
0048  * @ingroup RTEMSScore
0049  *
0050  * @brief This group contains the API Mutex Handler implementation.
0051  *
0052  * This handler provides routines to ensure mutual exclusion in a thread
0053  * context at the API level.
0054  *
0055  * @{
0056  */
0057
0058 #ifdef __cplusplus
0059 extern "C" {
0060 #endif
0061
0062 /**
0063  * @brief Control block used to manage each API mutex.
0064  */
0065 typedef struct {
0066   /**
0067    * A recursive mutex.
0068    */
0069   struct _Mutex_recursive_Control Mutex;
0070
0071   /**
0072    * @brief The thread life protection state before the outer-most mutex
0073    * obtain.
0074    */
0075   Thread_Life_state previous_thread_life_state;
0076 } API_Mutex_Control;
0077
0078 /**
0079  * @brief Statically initialize an API mutex.
0080  */
0081 #define API_MUTEX_INITIALIZER( name ) \
0082   { _MUTEX_RECURSIVE_NAMED_INITIALIZER( name ), 0 }
0083
0084 /**
0085  * @brief Acquires the specified API mutex.
0086  *
0087  * @param[in, out] mutex The API mutex to acquire.
0088  */
0089 void _API_Mutex_Lock( API_Mutex_Control *mutex );
0090
0091 /**
0092  * @brief Releases the specified API mutex.
0093  *
0094  * @param[in, out] mutex The API mutex to release.
0095  */
0096 void _API_Mutex_Unlock( API_Mutex_Control *mutex );
0097
0098 /**
0099  * @brief Checks if the specified API mutex is owned by the executing thread.
0100  *
0101  * @param[in] mutex The API mutex to check the owner from.
0102  */
0103 bool _API_Mutex_Is_owner( const API_Mutex_Control *mutex );
0104
0105 /** @} */
0106
0107 /**
0108  * @defgroup RTEMSScoreAllocatorMutex RTEMS Allocator Mutex
0109  *
0110  * @ingroup RTEMSScoreAPIMutex
0111  *
0112  * @brief Protection for all memory allocations and deallocations in RTEMS.
0113  *
0114  * When the APIs all use this for allocation and deallocation protection, then
0115  * this possibly should be renamed and moved to a higher level in the
0116  * hierarchy.
0117  *
0118  * @{
0119  */
0120
0121 void _RTEMS_Lock_allocator( void );
0122
0123 void _RTEMS_Unlock_allocator( void );
0124
0125 bool _RTEMS_Allocator_is_owner( void );
0126
0127 /** @} */
0128
0129 #ifdef __cplusplus
0130 }
0131 #endif
0132
0133 #endif
0134 /*  end of include file */