/**
* @file
*
* @ingroup ClassicSem
*
* @brief Classic Semaphores API
*
* This include file contains all the constants and structures associated
* with the Semaphore Manager. This manager utilizes standard Dijkstra
* counting semaphores to provide synchronization and mutual exclusion
* capabilities.
*
* Directives provided are:
*
* - create a semaphore
* - get an ID of a semaphore
* - delete a semaphore
* - acquire a semaphore
* - release a semaphore
* - flush a semaphore
* - set ceiling priority for a semaphore
*/
/*
* COPYRIGHT (c) 1989-2008, 2016.
* 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.org/license/LICENSE.
*/
#ifndef _RTEMS_RTEMS_SEM_H
#define _RTEMS_RTEMS_SEM_H
#include <rtems/rtems/types.h>
#include <rtems/rtems/options.h>
#include <rtems/rtems/support.h>
#include <rtems/rtems/tasks.h>
#include <rtems/rtems/attr.h>
#include <rtems/score/coremutex.h>
#include <rtems/score/object.h>
#include <rtems/score/coresem.h>
#include <rtems/score/mrsp.h>
#ifdef __cplusplus
extern "C" {
#endif
/**
* @defgroup ClassicSem Semaphores
*
* @ingroup ClassicRTEMS
*
* This encapsulates functionality related to the Classic API
* Semaphore Manager.
*/
/**@{*/
/**
* The following defines the control block used to manage each semaphore.
*/
typedef struct {
/** This field is the object management portion of a Semaphore instance. */
Objects_Control Object;
/**
* This contains the memory associated with the SuperCore Semaphore or
* Mutex instance that provides the primary functionality of each
* Classic API Semaphore instance. The structure used is dependent
* on the attributes specified by the user on the create directive.
*
* @note Only one of these has meaning in a particular Classic API
* Semaphore instance.
*/
union {
/**
* @brief The thread queue present in all other variants.
*/
Thread_queue_Control Wait_queue;
/**
* This is the SuperCore Mutex instance associated with this Classic
* API Semaphore instance.
*/
CORE_ceiling_mutex_Control Mutex;
/**
* This is the SuperCore Semaphore instance associated with this Classic
* API Semaphore instance.
*/
CORE_semaphore_Control Semaphore;
#if defined(RTEMS_SMP)
MRSP_Control MRSP;
#endif
} Core_control;
/**
* @brief The semaphore variant.
*
* @see Semaphore_Variant.
*/
unsigned int variant : 3;
/**
* @brief The semaphore thread queue discipline.
*
* @see Semaphore_Discipline.
*/
unsigned int discipline : 1;
#if defined(RTEMS_MULTIPROCESSING)
unsigned int is_global : 1;
#endif
} Semaphore_Control;
/**
* @brief rtems_semaphore_create
*
* This routine implements the rtems_semaphore_create directive. The
* semaphore will have the name name. The starting count for
* the semaphore is count. The attribute_set determines if
* the semaphore is global or local and the thread queue
* discipline. It returns the id of the created semaphore in ID.
*/
rtems_status_code rtems_semaphore_create(
rtems_name name,
uint32_t count,
rtems_attribute attribute_set,
rtems_task_priority priority_ceiling,
rtems_id *id
);
/**
* @brief RTEMS Semaphore Name to Id
*
* This routine implements the rtems_semaphore_ident directive.
* This directive returns the semaphore ID associated with name.
* If more than one semaphore is named name, then the semaphore
* to which the ID belongs is arbitrary. node indicates the
* extent of the search for the ID of the semaphore named name.
* The search can be limited to a particular node or allowed to
* encompass all nodes.
*
* @param[in] name is the user defined semaphore name
* @param[in] node is(are) the node(s) to be searched
* @param[in] id is the pointer to semaphore id
*
* @retval RTEMS_SUCCESSFUL if successful or error code if unsuccessful and
* *id filled in with the semaphore id
*/
rtems_status_code rtems_semaphore_ident(
rtems_name name,
uint32_t node,
rtems_id *id
);
/**
* @brief RTEMS Delete Semaphore
*
* This routine implements the rtems_semaphore_delete directive. The
* semaphore indicated by ID is deleted.
*
* @param[in] id is the semaphore id
*
* @retval This method returns RTEMS_SUCCESSFUL if there was not an
* error. Otherwise, a status code is returned indicating the
* source of the error.
*/
rtems_status_code rtems_semaphore_delete(
rtems_id id
);
/**
* @brief RTEMS Obtain Semaphore
*
* This routine implements the rtems_semaphore_obtain directive. It
* attempts to obtain a unit from the semaphore associated with ID.
* If a unit can be allocated, the calling task will return immediately.
* If no unit is available, then the task may return immediately or
* block waiting for a unit with an optional timeout of timeout
* clock ticks. Whether the task blocks or returns immediately
* is based on the RTEMS_NO_WAIT option in the option_set.
*
* @param[in] id is the semaphore id
* @param[in] option_set is the wait option
* @param[in] timeout is the number of ticks to wait (0 means wait forever)
*
* @retval This method returns RTEMS_SUCCESSFUL if there was not an
* error. Otherwise, a status code is returned indicating the
* source of the error.
*/
rtems_status_code rtems_semaphore_obtain(
rtems_id id,
rtems_option option_set,
rtems_interval timeout
);
/**
* @brief RTEMS Semaphore Release
*
* This routine implements the rtems_semaphore_release directive. It
* frees a unit to the semaphore associated with ID. 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.
*/
rtems_status_code rtems_semaphore_release(
rtems_id id
);
/**
* @brief RTEMS Semaphore Flush
*
* This method is the implementation of the flush directive
* of the Semaphore Manager.
*
* This directive allows a thread to flush the threads
* pending on the semaphore.
*
* @param[in] id is the semaphore id
*
* @retval RTEMS_SUCCESSFUL if successful or error code if unsuccessful
*/
rtems_status_code rtems_semaphore_flush(
rtems_id id
);
/**
* @brief Sets the priority value with respect to the specified scheduler of a
* semaphore.
*
* The special priority value @ref RTEMS_CURRENT_PRIORITY can be used to get
* the current priority value without changing it.
*
* The interpretation of the priority value depends on the protocol of the
* semaphore object.
*
* - The Multiprocessor Resource Sharing Protocol needs a ceiling priority per
* scheduler instance. This operation can be used to specify these priority
* values.
* - For the Priority Ceiling Protocol the ceiling priority is used with this
* operation.
* - For other protocols this operation is not defined.
*
* @param[in] semaphore_id Identifier of the semaphore.
* @param[in] scheduler_id Identifier of the scheduler.
* @param[in] new_priority The new priority value. Use
* @ref RTEMS_CURRENT_PRIORITY to not set a new priority and only get the
* current priority.
* @param[out] old_priority Reference to store the old priority value.
*
* @retval RTEMS_SUCCESSFUL Successful operation.
* @retval RTEMS_INVALID_ID Invalid semaphore or scheduler identifier.
* @retval RTEMS_INVALID_ADDRESS The old priority reference is @c NULL.
* @retval RTEMS_INVALID_PRIORITY The new priority value is invalid.
* @retval RTEMS_NOT_DEFINED The set priority operation is not defined for the
* protocol of this semaphore object.
* @retval RTEMS_ILLEGAL_ON_REMOTE_OBJECT Not supported for remote semaphores.
*
* @see rtems_scheduler_ident() and rtems_task_set_priority().
*/
rtems_status_code rtems_semaphore_set_priority(
rtems_id semaphore_id,
rtems_id scheduler_id,
rtems_task_priority new_priority,
rtems_task_priority *old_priority
);
/**@}*/
#ifdef __cplusplus
}
#endif
#endif
/* end of include file */
