diff options
author | Sebastian Huber <sebastian.huber@embedded-brains.de> | 2020-06-22 07:09:23 +0200 |
---|---|---|
committer | Sebastian Huber <sebastian.huber@embedded-brains.de> | 2020-10-01 14:09:47 +0200 |
commit | c7219554dcfad8d680cde7e79a3ea93cc68e39d8 (patch) | |
tree | 1f5d83839114866e2cad9f9eac17586c97474fff | |
parent | 01751158245b49fbe9c9455cd8fde41895e7a7d4 (diff) |
Generate <rtems/rtems/sem.h>
-rw-r--r-- | cpukit/include/rtems/rtems/sem.h | 359 |
1 files changed, 231 insertions, 128 deletions
diff --git a/cpukit/include/rtems/rtems/sem.h b/cpukit/include/rtems/rtems/sem.h index 3dcdfbfda8..6f3e8af99c 100644 --- a/cpukit/include/rtems/rtems/sem.h +++ b/cpukit/include/rtems/rtems/sem.h @@ -1,25 +1,55 @@ +/* SPDX-License-Identifier: BSD-2-Clause */ + /** * @file * - * @ingroup ClassicSem + * @ingroup RTEMSAPIClassicSem * - * @brief Classic Semaphores Manager API + * @brief This header file defines the Semaphore Manager API. */ /* - * COPYRIGHT (c) 1989-2008, 2016. - * On-Line Applications Research Corporation (OAR). + * Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de) + * Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) + * + * Redistribution and use in source and binary forms, with or without + * modification, are permitted provided that the following conditions + * are met: + * 1. Redistributions of source code must retain the above copyright + * notice, this list of conditions and the following disclaimer. + * 2. Redistributions in binary form must reproduce the above copyright + * notice, this list of conditions and the following disclaimer in the + * documentation and/or other materials provided with the distribution. * - * 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. + * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" + * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE + * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE + * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE + * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR + * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF + * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS + * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN + * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) + * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE + * POSSIBILITY OF SUCH DAMAGE. + */ + +/* + * This file was automatically generated. Do not edit it manually. + * Please have a look at + * + * https://docs.rtems.org/branches/master/eng/req/howto.html + * + * for information how to maintain and re-generate this file. */ #ifndef _RTEMS_RTEMS_SEM_H #define _RTEMS_RTEMS_SEM_H +#include <stdint.h> #include <rtems/rtems/attr.h> #include <rtems/rtems/options.h> +#include <rtems/rtems/status.h> #include <rtems/rtems/tasks.h> #include <rtems/rtems/types.h> @@ -28,90 +58,208 @@ extern "C" { #endif /** - * @defgroup ClassicSem Semaphores + * @defgroup RTEMSAPIClassicSem Semaphore Manager * - * @ingroup RTEMSAPIClassic + * @ingroup RTEMSAPIClassic * - * This encapsulates functionality related to the Classic API - * Semaphore Manager. + * @brief The Semaphore Manager utilizes standard Dijkstra counting semaphores + * to provide synchronization and mutual exclusion capabilities. */ -/**@{*/ /** - * @brief rtems_semaphore_create + * @ingroup RTEMSAPIClassicSem + * + * @brief Creates a semaphore with the specified properties and returns its + * identifier. + * + * This directive creates a semaphore which resides on the local node. The new + * semaphore has the user-defined name specified in ``name`` and the initial + * count specified in ``count``. For control and maintenance of the semaphore, + * RTEMS allocates and initializes a SMCB. The RTEMS-assigned semaphore + * identifier is returned in ``id``. This semaphore identifier is used with + * other semaphore related directives to access the semaphore. + * + * The attribute set specified in ``attribute_set`` defines + * + * * the scope of the semaphore (local or global), + * + * * the discipline of the task wait queue used by the semaphore (FIFO or + * priority), + * + * * the class of the semaphore (counting, binary, or simple binary), and + * + * * the locking protocol of a binary semaphore (priority inheritance, priority + * ceiling or MrsP). + * + * The attribute set is built through a *bitwise or* of the attribute constants + * described below. Not all combinations of attributes are allowed. Some + * attributes are mutually exclusive. If mutually exclusive attributes are + * combined, the behaviour is undefined. + * + * The *scope of a semaphore* is either the local node only (local scope) or + * all nodes in a multiprocessing network (global scope). The scope is + * selected by the mutually exclusive #RTEMS_LOCAL and #RTEMS_GLOBAL + * attributes. + * + * * The local scope is the default and can be emphasized through use of the + * #RTEMS_LOCAL attribute. + * + * * The global scope is selected by the #RTEMS_GLOBAL attribute. In a single + * node system and the local and global scope are identical. + * + * The *task wait queue discipline* is selected by the mutually exclusive + * #RTEMS_FIFO and #RTEMS_PRIORITY attributes. + * + * * The FIFO discipline is the default and can be emphasized through use of + * the #RTEMS_FIFO attribute. + * + * * The priority discipline is selected by the #RTEMS_PRIORITY attribute. + * Some locking protocols require the priority discipline. + * + * The *semaphore class* is selected by the mutually exclusive + * #RTEMS_COUNTING_SEMAPHORE, #RTEMS_BINARY_SEMAPHORE, and + * #RTEMS_SIMPLE_BINARY_SEMAPHORE attributes. + * + * * Counting semaphores are the default and can be emphasized through use of + * the #RTEMS_COUNTING_SEMAPHORE attribute. + * + * * Binary semaphores are mutual exclusion (mutex) synchronization primitives + * which may have an owner. The count of a binary semaphore is restricted to + * 0 and 1. The binary semaphore class is selected by the + * #RTEMS_BINARY_SEMAPHORE attribute. + * + * * Simple binary semaphores have no owner. The count of a simple binary + * semaphore is restricted to 0 and 1. They may be used for task and + * interrupt synchronization. The simple binary semaphore class is selected + * by the #RTEMS_SIMPLE_BINARY_SEMAPHORE attribute. + * + * Binary semaphores may use a *locking protocol*. If a locking protocol is + * selected, then the scope shall be local and the priority task wait queue + * discipline shall be selected. The locking protocol is selected by the + * mutually exclusive #RTEMS_INHERIT_PRIORITY, #RTEMS_PRIORITY_CEILING, and + * #RTEMS_MULTIPROCESSOR_RESOURCE_SHARING attributes. + * + * * The default is to use no locking protocol. + * + * * The #RTEMS_INHERIT_PRIORITY attribute selects the priority inheritance + * locking protocol. + * + * * The #RTEMS_PRIORITY_CEILING attribute selects the priority ceiling locking + * protocol. For this locking protocol a priority ceiling shall be specified + * in ``priority_ceiling``. + * + * * The #RTEMS_MULTIPROCESSOR_RESOURCE_SHARING attribute selects the MrsP + * locking protocol in SMP configurations, otherwise it selects the priority + * ceiling protocol. For this locking protocol a priority ceiling shall be + * specified in ``priority_ceiling``. This priority is used to set the + * priority ceiling in all scheduler instances. This can be changed later + * with the rtems_semaphore_set_priority() directive using the returned + * semaphore identifier. + * + * This directive may cause the calling task to be preempted due to an obtain + * and release of the object allocator mutex. + * + * Semaphores should not be made global unless remote tasks must interact with + * the new semaphore. This is to avoid the system overhead incurred by the + * creation of a global semaphore. When a global semaphore is created, the + * semaphore's name and identifier must be transmitted to every node in the + * system for insertion in the local copy of the global object table. + * + * The total number of global objects, including semaphores, is limited by the + * #CONFIGURE_MP_MAXIMUM_GLOBAL_OBJECTS application configuration option. + * + * It is not allowed to create an initially locked MrsP semaphore and the + * ::RTEMS_INVALID_NUMBER status code will be returned in SMP configurations in + * this case. This prevents lock order reversal problems with the allocator + * mutex. + * + * @param name is the object name of the new semaphore. * - * 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. + * @param count is the initial count of the new semaphore. If the semaphore is + * a mutex, then a count of 0 will make the calling task the owner of the new + * mutex and a count of 1 will create a mutex without an owner. + * + * @param attribute_set is the attribute set which defines the properties of + * the new semaphore. + * + * @param priority_ceiling is the priority ceiling if the new semaphore is a + * binary semaphore with the priority ceiling or MrsP semaphore locking + * protocol as defined by the attribute set. + * + * @param[out] id is the pointer to an object identifier variable. The object + * identifier of the new semaphore will be stored in this variable, in case + * of a successful operation. + * + * @retval ::RTEMS_SUCCESSFUL The requested operation was successful. + * + * @retval ::RTEMS_INVALID_ADDRESS The priority_ceiling parameter was NULL. + * + * @retval ::RTEMS_INVALID_NAME The semaphore name was invalid. + * + * @retval ::RTEMS_INVALID_PRIORITY The priority ceiling was invalid. + * + * @retval ::RTEMS_NOT_DEFINED The attribute set was invalid. + * + * @retval ::RTEMS_TOO_MANY There was no inactive semaphore object available to + * create a new semaphore. The semaphore object maximum is defined by the + * #CONFIGURE_MAXIMUM_SEMAPHORES application configuration option. + * + * @retval ::RTEMS_TOO_MANY In multiprocessing configurations, there was no + * inactive global object available to create a new global semaphore. */ rtems_status_code rtems_semaphore_create( - rtems_name name, - uint32_t count, - rtems_attribute attribute_set, - rtems_task_priority priority_ceiling, - rtems_id *id + 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 + * @ingroup RTEMSAPIClassicSem + * + * @brief % + * + * @param id % */ -rtems_status_code rtems_semaphore_ident( - rtems_name name, - uint32_t node, - rtems_id *id -); +rtems_status_code rtems_semaphore_delete( rtems_id id ); + +/** + * @ingroup RTEMSAPIClassicSem + * + * @brief % + * + * @param id % + */ +rtems_status_code rtems_semaphore_flush( rtems_id id ); /** - * @brief RTEMS Delete Semaphore + * @ingroup RTEMSAPIClassicSem + * + * @brief % * - * This routine implements the rtems_semaphore_delete directive. The - * semaphore indicated by ID is deleted. + * @param name % * - * @param[in] id is the semaphore id + * @param node % * - * @retval This method returns RTEMS_SUCCESSFUL if there was not an - * error. Otherwise, a status code is returned indicating the - * source of the error. + * @param id % */ -rtems_status_code rtems_semaphore_delete( - rtems_id id +rtems_status_code rtems_semaphore_ident( + rtems_name name, + uint32_t node, + 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. + * @ingroup RTEMSAPIClassicSem + * + * @brief % + * + * @param id % + * + * @param option_set % + * + * @param timeout % */ rtems_status_code rtems_semaphore_obtain( rtems_id id, @@ -120,68 +268,26 @@ rtems_status_code rtems_semaphore_obtain( ); /** - * @brief RTEMS Semaphore Release + * @ingroup RTEMSAPIClassicSem + * + * @brief % * - * 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. + * @param id % */ -rtems_status_code rtems_semaphore_release( - rtems_id id -); +rtems_status_code rtems_semaphore_release( rtems_id id ); /** - * @brief RTEMS Semaphore Flush + * @ingroup RTEMSAPIClassicSem * - * This method is the implementation of the flush directive - * of the Semaphore Manager. + * @brief % * - * This directive allows a thread to flush the threads - * pending on the semaphore. + * @param semaphore_id % * - * @param[in] id is the semaphore id + * @param scheduler_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(). + * @param new_priority % + * + * @param old_priority % */ rtems_status_code rtems_semaphore_set_priority( rtems_id semaphore_id, @@ -190,11 +296,8 @@ rtems_status_code rtems_semaphore_set_priority( rtems_task_priority *old_priority ); -/**@}*/ - #ifdef __cplusplus } #endif -#endif -/* end of include file */ +#endif /* _RTEMS_RTEMS_SEM_H */ |