/** * @file rtems/score/coresem.h * * This include file contains all the constants and structures associated * with the Counting Semaphore Handler. A counting semaphore is the * standard Dijkstra binary semaphore used to provide synchronization * and mutual exclusion capabilities. */ /* * COPYRIGHT (c) 1989-2008. * On-Line Applications Research Corporation (OAR). * * The license and distribution terms for this file may be * found in the file LICENSE in this distribution or at * http://www.rtems.com/license/LICENSE. * * $Id$ */ #ifndef _RTEMS_SCORE_CORESEM_H #define _RTEMS_SCORE_CORESEM_H /** * @defgroup ScoreSemaphore Semaphore Handler * * @ingroup Score * * This handler encapsulates functionality which provides the foundation * Semaphore services used in all of the APIs supported by RTEMS. */ /**@{*/ #include #include #include #include #ifdef __cplusplus extern "C" { #endif #if defined(RTEMS_POSIX_API) || defined(RTEMS_MULTIPROCESSING) #define RTEMS_SCORE_CORESEM_ENABLE_SEIZE_BODY #endif /** * The following type defines the callout which the API provides * to support global/multiprocessor operations on semaphores. */ typedef void ( *CORE_semaphore_API_mp_support_callout )( Thread_Control *, Objects_Id ); /** * Blocking disciplines for a semaphore. */ typedef enum { /** This specifies that threads will wait for the semaphore in FIFO order. */ CORE_SEMAPHORE_DISCIPLINES_FIFO, /** This specifies that threads will wait for the semaphore in * priority order. */ CORE_SEMAPHORE_DISCIPLINES_PRIORITY } CORE_semaphore_Disciplines; /** * Core Semaphore handler return statuses. */ typedef enum { /** This status indicates that the operation completed successfully. */ CORE_SEMAPHORE_STATUS_SUCCESSFUL, /** This status indicates that the calling task did not want to block * and the operation was unable to complete immediately because the * resource was unavailable. */ CORE_SEMAPHORE_STATUS_UNSATISFIED_NOWAIT, /** This status indicates that the thread was blocked waiting for an * operation to complete and the semaphore was deleted. */ CORE_SEMAPHORE_WAS_DELETED, /** This status indicates that the calling task was willing to block * but the operation was unable to complete within the time allotted * because the resource never became available. */ CORE_SEMAPHORE_TIMEOUT, /** This status indicates that an attempt was made to unlock the semaphore * and this would have made its count greater than that allowed. */ CORE_SEMAPHORE_MAXIMUM_COUNT_EXCEEDED } CORE_semaphore_Status; /** * @brief Core Semaphore Last Status * * This is the last status value. */ #define CORE_SEMAPHORE_STATUS_LAST CORE_SEMAPHORE_MAXIMUM_COUNT_EXCEEDED /** * The following defines the control block used to manage the * attributes of each semaphore. */ typedef struct { /** This element indicates the maximum count this semaphore may have. */ uint32_t maximum_count; /** This field indicates whether threads waiting on the semaphore block in * FIFO or priority order. */ CORE_semaphore_Disciplines discipline; } CORE_semaphore_Attributes; /** * The following defines the control block used to manage each * counting semaphore. */ typedef struct { /** This field is the Waiting Queue used to manage the set of tasks * which are blocked waiting to obtain the semaphore. */ Thread_queue_Control Wait_queue; /** This element is the set of attributes which define this instance's * behavior. */ CORE_semaphore_Attributes Attributes; /** This element contains the current count of this semaphore. */ uint32_t count; } CORE_semaphore_Control; /** * This routine initializes the semaphore based on the parameters passed. * * @param[in] the_semaphore is the semaphore to initialize * @param[in] the_semaphore_attributes define the behavior of this instance * @param[in] initial_value is the initial count of the semaphore */ void _CORE_semaphore_Initialize( CORE_semaphore_Control *the_semaphore, CORE_semaphore_Attributes *the_semaphore_attributes, uint32_t initial_value ); #if defined(RTEMS_SCORE_CORESEM_ENABLE_SEIZE_BODY) /** * This routine attempts to receive a unit from @a the_semaphore. * If a unit is available or if the wait flag is false, then the routine * returns. Otherwise, the calling task is blocked until a unit becomes * available. * * @param[in] the_semaphore is the semaphore to seize * @param[in] id is the Id of the API level Semaphore object associated * with this instance of a SuperCore Semaphore * @param[in] wait indicates if the caller is willing to block * @param[in] timeout is the number of ticks the calling thread is willing * to wait if @a wait is true. */ void _CORE_semaphore_Seize( CORE_semaphore_Control *the_semaphore, Objects_Id id, bool wait, Watchdog_Interval timeout ); #endif /** * This routine frees a unit to the semaphore. If a task was blocked waiting * for a unit from this semaphore, then that task will be readied and the unit * given to that task. Otherwise, the unit will be returned to the semaphore. * * @param[in] the_semaphore is the semaphore to surrender * @param[in] id is the Id of the API level Semaphore object associated * with this instance of a SuperCore Semaphore * @param[in] api_semaphore_mp_support is the routine to invoke if the * thread unblocked is remote * * @return an indication of whether the routine succeeded or failed */ CORE_semaphore_Status _CORE_semaphore_Surrender( CORE_semaphore_Control *the_semaphore, Objects_Id id, CORE_semaphore_API_mp_support_callout api_semaphore_mp_support ); /** * This routine assists in the deletion of a semaphore by flushing the * associated wait queue. * * @param[in] the_semaphore is the semaphore to flush * @param[in] remote_extract_callout is the routine to invoke if the * thread unblocked is remote * @param[in] status is the status to be returned to the unblocked thread */ void _CORE_semaphore_Flush( CORE_semaphore_Control *the_semaphore, Thread_queue_Flush_callout remote_extract_callout, uint32_t status ); #ifndef __RTEMS_APPLICATION__ #include #endif #ifdef __cplusplus } #endif /**@}*/ #endif /* end of include file */