From 8b1b9872015b689172990556e8d958a732d88196 Mon Sep 17 00:00:00 2001 From: Sebastian Huber Date: Wed, 24 Jun 2020 07:10:25 +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/signal.h | 193 +++++++++++++++++++++++++++++------- 1 file changed, 159 insertions(+), 34 deletions(-) (limited to 'cpukit/include/rtems/rtems/signal.h') diff --git a/cpukit/include/rtems/rtems/signal.h b/cpukit/include/rtems/rtems/signal.h index 1ed1392e2f..c9fbd79b5d 100644 --- a/cpukit/include/rtems/rtems/signal.h +++ b/cpukit/include/rtems/rtems/signal.h @@ -1,19 +1,56 @@ +/* SPDX-License-Identifier: BSD-2-Clause */ + /** * @file * - * @ingroup ClassicSignal + * @brief This header file defines the parts of the Signal 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 Signals 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/signal/if/header */ + #ifndef _RTEMS_RTEMS_SIGNAL_H #define _RTEMS_RTEMS_SIGNAL_H @@ -26,58 +63,146 @@ extern "C" { #endif +/* Generated from spec:/rtems/signal/if/group */ + /** - * @defgroup ClassicSignal Signals + * @defgroup RTEMSAPIClassicSignal Signal Manager * * @ingroup RTEMSAPIClassic * - * Directives provided are: - * - * + establish an asynchronous signal routine - * + send a signal set to a task + * @brief The Signal Manager provides the capabilities required for + * asynchronous communication. */ -/**@{*/ + +/* Generated from spec:/rtems/signal/if/catch */ /** - * @brief RTEMS Catch Signal + * @ingroup RTEMSAPIClassicSignal + * + * @brief Establishes an asynchronous signal routine (ASR) for the calling + * task. + * + * @param asr_handler is the handler to process an asynchronous signal set. + * + * @param mode_set is the task mode while an asynchronous signal set is + * processed by the handler. See rtems_task_mode(). + * + * This directive establishes an asynchronous signal routine (ASR) for the + * calling task. The ``asr_handler`` parameter specifies the entry point of + * the ASR. A task may have at most one handler installed at a time. The most + * recently installed handler is used. When ``asr_handler`` is NULL, the ASR + * for the calling task is invalidated and all pending signals are cleared. + * Any signals sent to a task with an invalid ASR are discarded. The + * ``mode_set`` parameter specifies the execution mode for the ASR. This + * execution mode supersedes the task's execution mode while the ASR is + * executing. + * + * @retval ::RTEMS_SUCCESSFUL The requested operation was successful. + * + * @retval ::RTEMS_NOT_IMPLEMENTED The #RTEMS_NO_PREEMPT was set in + * ``mode_set`` and the system configuration had no implementation for this + * mode. + * + * @retval ::RTEMS_NOT_IMPLEMENTED The RTEMS_INTERRUPT_LEVEL() was set to a + * positive level in ``mode_set`` and the system configuration had no + * implementation for this mode. + * + * @par Notes + * @parblock + * It is strongly recommended to disable ASR processing during ASR processing + * by setting #RTEMS_NO_ASR in ``mode_set``, otherwise a recursion may happen + * during ASR processing. Uncontrolled recursion may lead to stack overflows. + * + * Using the same mutex (in particular a recursive mutex) in normal task + * context and during ASR processing may result in undefined behaviour. * - * This routine implements the rtems_signal_catch directive. This directive - * is used to establish asr_handler as the Asynchronous Signal Routine - * (RTEMS_ASR) for the calling task. The asr_handler will execute with a - * mode of mode_set. + * Asynchronous signal handlers can access thread-local storage (TLS). When + * thread-local storage is shared between normal task context and ASR + * processing, it may be protected by disabled interrupts. + * @endparblock * - * @param[in] asr_handler is the address of asynchronous signal routine (asr) - * ( NULL indicates asr is invalid ) - * @param[in] mode_set is the mode value for asr + * @par Constraints + * @parblock + * The following constraints apply to this directive: * - * @retval RTEMS_SUCCESSFUL + * * The directive may be called from within task context. + * + * * The directive will not cause the calling task to be preempted. + * @endparblock */ rtems_status_code rtems_signal_catch( - rtems_asr_entry asr_handler, - rtems_mode mode_set + rtems_asr_entry asr_handler, + rtems_mode mode_set ); +/* Generated from spec:/rtems/signal/if/send */ + /** - * @brief RTEMS Send Signal + * @ingroup RTEMSAPIClassicSignal + * + * @brief Sends the signal set to the task. + * + * @param id is the identifier of the target task to receive the signal set. + * + * @param signal_set is the signal set to send. + * + * This directive sends the signal set, ``signal_set``, to the target task + * identified by ``id``. + * + * If a caller sends a signal set to a task with an invalid ASR, then an error + * code is returned to the caller. If a caller sends a signal set to a task + * whose ASR is valid but disabled, then the signal set will be caught and left + * pending for the ASR to process when it is enabled. If a caller sends a + * signal set to a task with an ASR that is both valid and enabled, then the + * signal set is caught and the ASR will execute the next time the task is + * dispatched to run. + * + * @retval ::RTEMS_SUCCESSFUL The requested operation was successful. + * + * @retval ::RTEMS_INVALID_NUMBER The ``signal_set`` parameter was 0. * - * This routine implements the rtems_signal_send directive. This directive - * sends the signal_set to the task specified by ID. + * @retval ::RTEMS_INVALID_ID There was no task associated with the identifier + * specified by ``id``. * - * @param[in] id is the thread thread id - * @param[in] signal_set is the signal set + * @retval ::RTEMS_NOT_DEFINED The target task had no valid ASR installed. * - * @retval RTEMS_SUCCESSFUL if successful or error code if unsuccessful + * @par Notes + * @parblock + * Sending a signal set to a task has no effect on that task's state. If a + * signal set is sent to a blocked task, then the task will remain blocked and + * the signals will be processed when the task becomes the running task. + * + * Sending a signal set to a global task which does not reside on the local + * node will generate a request telling the remote node to send the signal set + * to the specified task. + * @endparblock + * + * @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 device driver initialization + * context. + * + * * The directive may be called from within task context. + * + * * When the directive operates on a local object, the directive will not + * cause the calling task to be preempted. + * + * * When the directive operates on a remote object, the directive sends a + * message to the remote node and waits for a reply. This will preempt the + * calling task. + * @endparblock */ rtems_status_code rtems_signal_send( rtems_id id, rtems_signal_set signal_set ); -/**@}*/ - #ifdef __cplusplus } #endif -#endif -/* end of include file */ +#endif /* _RTEMS_RTEMS_SIGNAL_H */ -- cgit v1.2.3