From 0c4c03532c625f5f34232c2e4eabc2ecc4fa036c Mon Sep 17 00:00:00 2001 From: Sebastian Huber Date: Mon, 22 Jun 2020 08:39:29 +0200 Subject: rtems: Generate Change license to BSD-2-Clause according to file histories and documentation re-licensing agreement. Update #3899. Update #3993. --- cpukit/include/rtems/rtems/barrier.h | 368 +++++++++++++++++++++++++++-------- 1 file changed, 287 insertions(+), 81 deletions(-) (limited to 'cpukit/include/rtems/rtems/barrier.h') diff --git a/cpukit/include/rtems/rtems/barrier.h b/cpukit/include/rtems/rtems/barrier.h index f6362f9237..9fdce492d4 100644 --- a/cpukit/include/rtems/rtems/barrier.h +++ b/cpukit/include/rtems/rtems/barrier.h @@ -1,22 +1,60 @@ +/* SPDX-License-Identifier: BSD-2-Clause */ + /** * @file * - * @ingroup ClassicBarrier + * @brief This header file defines the Barrier Manager API. + */ + +/* + * Copyright (C) 2020, 2021 embedded brains GmbH (http://www.embedded-brains.de) + * Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) * - * @brief Classic Barrier Manager API + * 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. + * + * 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. */ -/* COPYRIGHT (c) 1989-2008. - * On-Line Applications Research Corporation (OAR). +/* + * This file is part of the RTEMS quality process and was automatically + * generated. If you find something that needs to be fixed or + * worded better please post a report or patch to an RTEMS mailing list + * or raise a bug report: + * + * https://www.rtems.org/bugs.html * - * 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. + * For information on updating and regenerating please refer to the How-To + * section in the Software Requirements Engineering chapter of the + * RTEMS Software Engineering manual. The manual is provided as a part of + * a release. For development sources please refer to the online + * documentation at: + * + * https://docs.rtems.org */ +/* Generated from spec:/rtems/barrier/if/header */ + #ifndef _RTEMS_RTEMS_BARRIER_H #define _RTEMS_RTEMS_BARRIER_H +#include #include #include #include @@ -25,123 +63,291 @@ extern "C" { #endif +/* Generated from spec:/rtems/barrier/if/group */ + /** - * @defgroup ClassicBarrier Barriers + * @defgroup RTEMSAPIClassicBarrier Barrier Manager * * @ingroup RTEMSAPIClassic * - * This encapsulates functionality which implements the Classic API - * Barrier Manager. + * @brief The Barrier Manager provides a unique synchronization capability + * which can be used to have a set of tasks block and be unblocked as a set. */ -/**@{*/ + +/* Generated from spec:/rtems/barrier/if/create */ /** - * @brief RTEMS Create Barrier + * @ingroup RTEMSAPIClassicBarrier + * + * @brief Creates a barrier. + * + * @param name is the object name of the barrier. + * + * @param attribute_set is the attribute set of the barrier. + * + * @param maximum_waiters is the maximum count of waiters on an automatic + * release barrier. + * + * @param id is the pointer to an object identifier variable. When the + * directive call is successful, the identifier of the created barrier will + * be stored in this variable. + * + * This directive creates a barrier which resides on the local node. The + * barrier has the user-defined object name specified in ``name`` and the + * initial count specified in ``attribute_set``. The assigned object + * identifier is returned in ``id``. This identifier is used to access the + * barrier with other barrier related directives. + * + * The **attribute set** specified in ``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. Attributes not mentioned below are not evaluated by this + * directive and have no effect. Default attributes can be selected by using + * the #RTEMS_DEFAULT_ATTRIBUTES constant. + * + * The **barrier class** is selected by the mutually exclusive + * #RTEMS_BARRIER_MANUAL_RELEASE and #RTEMS_BARRIER_AUTOMATIC_RELEASE + * attributes. + * + * * The **manual release class** is the default and can be emphasized through + * use of the #RTEMS_BARRIER_MANUAL_RELEASE attribute. For this class, there + * is no limit on the number of tasks that will block at the barrier. Only + * when the rtems_barrier_release() directive is invoked, are the tasks + * waiting at the barrier unblocked. * - * Barrier Manager -- Create a Barrier Instance + * * The **automatic release class** is selected by the + * #RTEMS_BARRIER_AUTOMATIC_RELEASE attribute. For this class, tasks calling + * the rtems_barrier_wait() directive will block until there are + * ``maximum_waiters`` minus one tasks waiting at the barrier. When the + * ``maximum_waiters`` task invokes the rtems_barrier_wait() directive, the + * previous ``maximum_waiters`` - 1 tasks are automatically released and the + * caller returns. * - * This routine implements the rtems_barrier_create directive. The - * barrier will have the name name. The starting count for - * the barrier is count. The attribute_set determines if - * the barrier is global or local and the thread queue - * discipline. It returns the id of the created barrier in ID. + * @retval ::RTEMS_SUCCESSFUL The requested operation was successful. * - * @param[in] name is the name of this barrier instance. - * @param[in] attribute_set specifies the attributes of this barrier instance. - * @param[in] maximum_waiters is the maximum number of threads which will - * be allowed to concurrently wait at the barrier. - * @param[out] id will contain the id of this barrier. + * @retval ::RTEMS_INVALID_NAME The ``name`` parameter was invalid. * - * @retval a status code indicating success or the reason for failure. + * @retval ::RTEMS_INVALID_ADDRESS The ``id`` parameter was NULL. + * + * @retval ::RTEMS_INVALID_NUMBER The ``maximum_waiters`` parameter was 0 for + * an automatic release barrier. + * + * @retval ::RTEMS_TOO_MANY There was no inactive object available to create a + * barrier. The number of barriers available to the application is + * configured through the #CONFIGURE_MAXIMUM_BARRIERS application + * configuration option. + * + * @par Notes + * For control and maintenance of the barrier, RTEMS allocates a BCB from the + * local BCB free pool and initializes it. + * + * @par Constraints + * @parblock + * The following constraints apply to this directive: + * + * * The directive may be called from within device driver initialization + * context. + * + * * The directive may be called from within task context. + * + * * The directive may obtain and release the object allocator mutex. This may + * cause the calling task to be preempted. + * + * * The number of barriers available to the application is configured through + * the #CONFIGURE_MAXIMUM_BARRIERS application configuration option. + * + * * Where the object class corresponding to the directive is configured to use + * unlimited objects, the directive may allocate memory from the RTEMS + * Workspace. + * @endparblock */ rtems_status_code rtems_barrier_create( - rtems_name name, - rtems_attribute attribute_set, - uint32_t maximum_waiters, - rtems_id *id + rtems_name name, + rtems_attribute attribute_set, + uint32_t maximum_waiters, + rtems_id *id ); +/* Generated from spec:/rtems/barrier/if/ident */ + /** - * @brief RTEMS Barrier name to Id + * @ingroup RTEMSAPIClassicBarrier + * + * @brief Identifies a barrier by the object name. + * + * @param name is the object name to look up. + * + * @param[out] id is the pointer to an object identifier variable. When the + * directive call is successful, the object identifier of an object with the + * specified name will be stored in this variable. + * + * This directive obtains a barrier identifier associated with the barrier name + * specified in ``name``. + * + * @retval ::RTEMS_SUCCESSFUL The requested operation was successful. + * + * @retval ::RTEMS_INVALID_ADDRESS The ``id`` parameter was NULL. + * + * @retval ::RTEMS_INVALID_NAME The ``name`` parameter was 0. + * + * @retval ::RTEMS_INVALID_NAME There was no object with the specified name on + * the local node. * - * This routine implements the rtems_barrier_ident directive. - * This directive returns the barrier ID associated with name. - * If more than one barrier is named name, then the barrier - * to which the ID belongs is arbitrary. node indicates the - * extent of the search for the ID of the barrier named name. - * The search can be limited to a particular node or allowed to - * encompass all nodes. + * @par Notes + * @parblock + * If the barrier name is not unique, then the barrier identifier will match + * the first barrier with that name in the search order. However, this barrier + * identifier is not guaranteed to correspond to the desired barrier. * - * @param[in] name is the name of this barrier instance. - * @param[out] id will contain the id of this barrier. + * The objects are searched from lowest to the highest index. Only the local + * node is searched. * - * @retval a status code indicating success or the reason for failure. + * The barrier identifier is used with other barrier related directives to + * access the barrier. + * @endparblock + * + * @par Constraints + * @parblock + * The following constraints apply to this directive: + * + * * The directive may be called from within any runtime context. + * + * * The directive will not cause the calling task to be preempted. + * @endparblock */ -rtems_status_code rtems_barrier_ident( - rtems_name name, - rtems_id *id -); +rtems_status_code rtems_barrier_ident( rtems_name name, rtems_id *id ); + +/* Generated from spec:/rtems/barrier/if/delete */ /** - * @brief RTEMS Delete Barrier + * @ingroup RTEMSAPIClassicBarrier + * + * @brief Deletes the barrier. + * + * @param id is the barrier identifier. + * + * This directive deletes the barrier specified by ``id``. All tasks blocked + * waiting for the barrier to be released will be readied and returned a status + * code which indicates that the barrier was deleted. + * + * @retval ::RTEMS_SUCCESSFUL The requested operation was successful. * - * This routine implements the rtems_barrier_delete directive. The - * barrier indicated by @a id is deleted. The barrier is freed back to the - * inactive barrier chain. + * @retval ::RTEMS_INVALID_ID There was no barrier associated with the + * identifier specified by ``id``. * + * @par Notes + * The BCB for the deleted barrier is reclaimed by RTEMS. * - * @param[in] id indicates the barrier to delete + * @par Constraints + * @parblock + * The following constraints apply to this directive: * - * @retval a status code indicating success or the reason for failure. + * * The directive may be called from within device driver initialization + * context. + * + * * The directive may be called from within task context. + * + * * The directive may obtain and release the object allocator mutex. This may + * cause the calling task to be preempted. + * + * * The calling task does not have to be the task that created the object. + * Any local task that knows the object identifier can delete the object. + * + * * Where the object class corresponding to the directive is configured to use + * unlimited objects, the directive may free memory to the RTEMS Workspace. + * @endparblock */ -rtems_status_code rtems_barrier_delete( - rtems_id id -); +rtems_status_code rtems_barrier_delete( rtems_id id ); + +/* Generated from spec:/rtems/barrier/if/wait */ /** - * @brief RTEMS Barrier Wait + * @ingroup RTEMSAPIClassicBarrier + * + * @brief Waits at the barrier. + * + * @param id is the barrier identifier. + * + * @param timeout is the timeout in clock ticks. Use #RTEMS_NO_TIMEOUT to wait + * potentially forever. * - * This routine implements the rtems_barrier_wait directive. It - * attempts to wait at the barrier associated with @a id. The calling task - * may block waiting for the barrier with an optional timeout of @a timeout - * clock ticks. + * This directive waits at the barrier specified by ``id``. The ``timeout`` + * parameter defines how long the calling task is willing to wait. Use + * #RTEMS_NO_TIMEOUT to wait potentially forever, otherwise set a timeout + * interval in clock ticks. * - * @param[in] id indicates the barrier to wait at. - * @param[in] timeout is the maximum length of time in ticks the calling - * thread is willing to block. + * Conceptually, the calling task should always be thought of as blocking when + * it makes this call and being unblocked when the barrier is released. If the + * barrier is configured for manual release, this rule of thumb will always be + * valid. If the barrier is configured for automatic release, all callers will + * block except for the one which trips the automatic release condition. * - * @retval a status code indicating success or the reason for failure. + * @retval ::RTEMS_SUCCESSFUL The requested operation was successful. + * + * @retval ::RTEMS_INVALID_ID There was no barrier associated with the + * identifier specified by ``id``. + * + * @retval ::RTEMS_TIMEOUT The timeout happened while the calling task was + * waiting at the barrier. + * + * @retval ::RTEMS_OBJECT_WAS_DELETED The barrier was deleted while the calling + * task was waiting at the barrier. + * + * @par Notes + * For automatic release barriers, the maximum count of waiting tasks is + * defined during barrier creation, see rtems_barrier_create(). + * + * @par Constraints + * @parblock + * The following constraints apply to this directive: + * + * * The directive may be called from within task context. + * + * * The timeout functionality of the directive requires a clock tick. + * @endparblock */ -rtems_status_code rtems_barrier_wait( - rtems_id id, - rtems_interval timeout -); +rtems_status_code rtems_barrier_wait( rtems_id id, rtems_interval timeout ); + +/* Generated from spec:/rtems/barrier/if/release */ /** - * @brief RTEMS Barrier Release + * @ingroup RTEMSAPIClassicBarrier * - * Barrier Manager -- Release Tasks Waitng at a Barrier + * @brief Releases the barrier. * - * This routine implements the rtems_barrier_release directive. It - * unblocks all of the threads waiting on the barrier associated with - * @a id. The number of threads unblocked is returned in @a released. + * @param id is the barrier identifier. * + * @param[out] released is the pointer to an integer variable. When the + * directive call is successful, the number of released tasks will be stored + * in this variable. * - * @param[in] id indicates the barrier to wait at. - * @param[out] released will contain the number of threads unblocked. + * This directive releases the barrier specified by ``id``. All tasks waiting + * at the barrier will be unblocked. The number of released tasks will be + * returned in ``released``. * - * @retval a status code indicating success or the reason for failure. + * @retval ::RTEMS_SUCCESSFUL The requested operation was successful. + * + * @retval ::RTEMS_INVALID_ADDRESS The ``released`` parameter was NULL. + * + * @retval ::RTEMS_INVALID_ID There was no barrier associated with the + * identifier specified by ``id``. + * + * @par Constraints + * @parblock + * The following constraints apply to this directive: + * + * * The directive may be called from within interrupt context. + * + * * The directive may be called from within task context. + * + * * The directive may unblock another task which may preempt the calling task. + * @endparblock */ -rtems_status_code rtems_barrier_release( - rtems_id id, - uint32_t *released -); - -/**@}*/ +rtems_status_code rtems_barrier_release( rtems_id id, uint32_t *released ); #ifdef __cplusplus } #endif -#endif -/* end of include file */ +#endif /* _RTEMS_RTEMS_BARRIER_H */ -- cgit v1.2.3