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/asr.h | 485 ++++++++++++++++++++++++++++-------- cpukit/include/rtems/rtems/signal.h | 193 +++++++++++--- 2 files changed, 546 insertions(+), 132 deletions(-) diff --git a/cpukit/include/rtems/rtems/asr.h b/cpukit/include/rtems/rtems/asr.h index c157719238..f58d60790d 100644 --- a/cpukit/include/rtems/rtems/asr.h +++ b/cpukit/include/rtems/rtems/asr.h @@ -1,134 +1,423 @@ +/* SPDX-License-Identifier: BSD-2-Clause */ + /** * @file * - * @ingroup ClassicASR + * @brief This header file defines the parts of the Signal Manager API. + */ + +/* + * 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. * - * This include file contains all the constants and structures associated - * with the Asynchronous Signal Handler. This Handler provides the low-level - * support required by the Signal Manager. + * 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-2013. - * 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: * - * 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. + * https://www.rtems.org/bugs.html + * + * 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-2 */ + #ifndef _RTEMS_RTEMS_ASR_H #define _RTEMS_RTEMS_ASR_H -#include +#include #ifdef __cplusplus extern "C" { #endif +/* Generated from spec:/rtems/signal/if/asr */ + /** - * @defgroup ClassicASR ASR Support + * @ingroup RTEMSAPIClassicSignal * - * @ingroup RTEMSAPIClassic + * @brief This type defines the return type of routines which are used to + * process asynchronous signals. * - * This encapsulates functionality related to the Classic API Signal - * Manager. + * @par Notes + * This type can be used to document asynchronous signal routines in the source + * code. */ -/**@{*/ +typedef void rtems_asr; + +/* Generated from spec:/rtems/signal/if/set */ /** - * The following type defines the control block used to manage - * each signal set. + * @ingroup RTEMSAPIClassicSignal + * + * @brief This integer type represents a bit field which can hold exactly 32 + * individual signals. */ -typedef uint32_t rtems_signal_set; +typedef uint32_t rtems_signal_set; + +/* Generated from spec:/rtems/signal/if/asr-entry */ /** - * Return type for ASR Handler + * @ingroup RTEMSAPIClassicSignal + * + * @brief This type defines the prototype of routines which are used to process + * asynchronous signals. */ -typedef void rtems_asr; +typedef rtems_asr ( *rtems_asr_entry )( + rtems_signal_set +); + +/* Generated from spec:/rtems/signal/if/signal-00 */ /** - * The following type corresponds to the applications asynchronous - * signal processing routine. + * @ingroup RTEMSAPIClassicSignal + * + * @brief This signal set constant represents the bit in the signal set + * associated with signal 0. */ -typedef rtems_asr ( *rtems_asr_entry )( - rtems_signal_set - ); +#define RTEMS_SIGNAL_0 0x00000001 -/* - * The following constants define the individual signals which may - * be used to compose a signal set. - */ - -/** This defines the bit in the signal set associated with signal 0. */ -#define RTEMS_SIGNAL_0 0x00000001 -/** This defines the bit in the signal set associated with signal 1. */ -#define RTEMS_SIGNAL_1 0x00000002 -/** This defines the bit in the signal set associated with signal 2. */ -#define RTEMS_SIGNAL_2 0x00000004 -/** This defines the bit in the signal set associated with signal 3. */ -#define RTEMS_SIGNAL_3 0x00000008 -/** This defines the bit in the signal set associated with signal 4. */ -#define RTEMS_SIGNAL_4 0x00000010 -/** This defines the bit in the signal set associated with signal 5. */ -#define RTEMS_SIGNAL_5 0x00000020 -/** This defines the bit in the signal set associated with signal 6. */ -#define RTEMS_SIGNAL_6 0x00000040 -/** This defines the bit in the signal set associated with signal 7. */ -#define RTEMS_SIGNAL_7 0x00000080 -/** This defines the bit in the signal set associated with signal 8. */ -#define RTEMS_SIGNAL_8 0x00000100 -/** This defines the bit in the signal set associated with signal 9. */ -#define RTEMS_SIGNAL_9 0x00000200 -/** This defines the bit in the signal set associated with signal 10. */ -#define RTEMS_SIGNAL_10 0x00000400 -/** This defines the bit in the signal set associated with signal 11. */ -#define RTEMS_SIGNAL_11 0x00000800 -/** This defines the bit in the signal set associated with signal 12. */ -#define RTEMS_SIGNAL_12 0x00001000 -/** This defines the bit in the signal set associated with signal 13. */ -#define RTEMS_SIGNAL_13 0x00002000 -/** This defines the bit in the signal set associated with signal 14. */ -#define RTEMS_SIGNAL_14 0x00004000 -/** This defines the bit in the signal set associated with signal 15. */ -#define RTEMS_SIGNAL_15 0x00008000 -/** This defines the bit in the signal set associated with signal 16. */ -#define RTEMS_SIGNAL_16 0x00010000 -/** This defines the bit in the signal set associated with signal 17. */ -#define RTEMS_SIGNAL_17 0x00020000 -/** This defines the bit in the signal set associated with signal 18. */ -#define RTEMS_SIGNAL_18 0x00040000 -/** This defines the bit in the signal set associated with signal 19. */ -#define RTEMS_SIGNAL_19 0x00080000 -/** This defines the bit in the signal set associated with signal 20. */ -#define RTEMS_SIGNAL_20 0x00100000 -/** This defines the bit in the signal set associated with signal 21. */ -#define RTEMS_SIGNAL_21 0x00200000 -/** This defines the bit in the signal set associated with signal 22. */ -#define RTEMS_SIGNAL_22 0x00400000 -/** This defines the bit in the signal set associated with signal 23. */ -#define RTEMS_SIGNAL_23 0x00800000 -/** This defines the bit in the signal set associated with signal 24. */ -#define RTEMS_SIGNAL_24 0x01000000 -/** This defines the bit in the signal set associated with signal 25. */ -#define RTEMS_SIGNAL_25 0x02000000 -/** This defines the bit in the signal set associated with signal 26. */ -#define RTEMS_SIGNAL_26 0x04000000 -/** This defines the bit in the signal set associated with signal 27. */ -#define RTEMS_SIGNAL_27 0x08000000 -/** This defines the bit in the signal set associated with signal 28. */ -#define RTEMS_SIGNAL_28 0x10000000 -/** This defines the bit in the signal set associated with signal 29. */ -#define RTEMS_SIGNAL_29 0x20000000 -/** This defines the bit in the signal set associated with signal 30. */ -#define RTEMS_SIGNAL_30 0x40000000 -/** This defines the bit in the signal set associated with signal 31. */ -#define RTEMS_SIGNAL_31 0x80000000 - -/**@}*/ +/* Generated from spec:/rtems/signal/if/signal-01 */ + +/** + * @ingroup RTEMSAPIClassicSignal + * + * @brief This signal set constant represents the bit in the signal set + * associated with signal 1. + */ +#define RTEMS_SIGNAL_1 0x00000002 + +/* Generated from spec:/rtems/signal/if/signal-02 */ + +/** + * @ingroup RTEMSAPIClassicSignal + * + * @brief This signal set constant represents the bit in the signal set + * associated with signal 2. + */ +#define RTEMS_SIGNAL_2 0x00000004 + +/* Generated from spec:/rtems/signal/if/signal-03 */ + +/** + * @ingroup RTEMSAPIClassicSignal + * + * @brief This signal set constant represents the bit in the signal set + * associated with signal 3. + */ +#define RTEMS_SIGNAL_3 0x00000008 + +/* Generated from spec:/rtems/signal/if/signal-04 */ + +/** + * @ingroup RTEMSAPIClassicSignal + * + * @brief This signal set constant represents the bit in the signal set + * associated with signal 4. + */ +#define RTEMS_SIGNAL_4 0x00000010 + +/* Generated from spec:/rtems/signal/if/signal-05 */ + +/** + * @ingroup RTEMSAPIClassicSignal + * + * @brief This signal set constant represents the bit in the signal set + * associated with signal 5. + */ +#define RTEMS_SIGNAL_5 0x00000020 + +/* Generated from spec:/rtems/signal/if/signal-06 */ + +/** + * @ingroup RTEMSAPIClassicSignal + * + * @brief This signal set constant represents the bit in the signal set + * associated with signal 6. + */ +#define RTEMS_SIGNAL_6 0x00000040 + +/* Generated from spec:/rtems/signal/if/signal-07 */ + +/** + * @ingroup RTEMSAPIClassicSignal + * + * @brief This signal set constant represents the bit in the signal set + * associated with signal 7. + */ +#define RTEMS_SIGNAL_7 0x00000080 + +/* Generated from spec:/rtems/signal/if/signal-08 */ + +/** + * @ingroup RTEMSAPIClassicSignal + * + * @brief This signal set constant represents the bit in the signal set + * associated with signal 8. + */ +#define RTEMS_SIGNAL_8 0x00000100 + +/* Generated from spec:/rtems/signal/if/signal-09 */ + +/** + * @ingroup RTEMSAPIClassicSignal + * + * @brief This signal set constant represents the bit in the signal set + * associated with signal 9. + */ +#define RTEMS_SIGNAL_9 0x00000200 + +/* Generated from spec:/rtems/signal/if/signal-10 */ + +/** + * @ingroup RTEMSAPIClassicSignal + * + * @brief This signal set constant represents the bit in the signal set + * associated with signal 10. + */ +#define RTEMS_SIGNAL_10 0x00000400 + +/* Generated from spec:/rtems/signal/if/signal-11 */ + +/** + * @ingroup RTEMSAPIClassicSignal + * + * @brief This signal set constant represents the bit in the signal set + * associated with signal 11. + */ +#define RTEMS_SIGNAL_11 0x00000800 + +/* Generated from spec:/rtems/signal/if/signal-12 */ + +/** + * @ingroup RTEMSAPIClassicSignal + * + * @brief This signal set constant represents the bit in the signal set + * associated with signal 12. + */ +#define RTEMS_SIGNAL_12 0x00001000 + +/* Generated from spec:/rtems/signal/if/signal-13 */ + +/** + * @ingroup RTEMSAPIClassicSignal + * + * @brief This signal set constant represents the bit in the signal set + * associated with signal 13. + */ +#define RTEMS_SIGNAL_13 0x00002000 + +/* Generated from spec:/rtems/signal/if/signal-14 */ + +/** + * @ingroup RTEMSAPIClassicSignal + * + * @brief This signal set constant represents the bit in the signal set + * associated with signal 14. + */ +#define RTEMS_SIGNAL_14 0x00004000 + +/* Generated from spec:/rtems/signal/if/signal-15 */ + +/** + * @ingroup RTEMSAPIClassicSignal + * + * @brief This signal set constant represents the bit in the signal set + * associated with signal 15. + */ +#define RTEMS_SIGNAL_15 0x00008000 + +/* Generated from spec:/rtems/signal/if/signal-16 */ + +/** + * @ingroup RTEMSAPIClassicSignal + * + * @brief This signal set constant represents the bit in the signal set + * associated with signal 16. + */ +#define RTEMS_SIGNAL_16 0x00010000 + +/* Generated from spec:/rtems/signal/if/signal-17 */ + +/** + * @ingroup RTEMSAPIClassicSignal + * + * @brief This signal set constant represents the bit in the signal set + * associated with signal 17. + */ +#define RTEMS_SIGNAL_17 0x00020000 + +/* Generated from spec:/rtems/signal/if/signal-18 */ + +/** + * @ingroup RTEMSAPIClassicSignal + * + * @brief This signal set constant represents the bit in the signal set + * associated with signal 18. + */ +#define RTEMS_SIGNAL_18 0x00040000 + +/* Generated from spec:/rtems/signal/if/signal-19 */ + +/** + * @ingroup RTEMSAPIClassicSignal + * + * @brief This signal set constant represents the bit in the signal set + * associated with signal 19. + */ +#define RTEMS_SIGNAL_19 0x00080000 + +/* Generated from spec:/rtems/signal/if/signal-20 */ + +/** + * @ingroup RTEMSAPIClassicSignal + * + * @brief This signal set constant represents the bit in the signal set + * associated with signal 20. + */ +#define RTEMS_SIGNAL_20 0x00100000 + +/* Generated from spec:/rtems/signal/if/signal-21 */ + +/** + * @ingroup RTEMSAPIClassicSignal + * + * @brief This signal set constant represents the bit in the signal set + * associated with signal 21. + */ +#define RTEMS_SIGNAL_21 0x00200000 + +/* Generated from spec:/rtems/signal/if/signal-22 */ + +/** + * @ingroup RTEMSAPIClassicSignal + * + * @brief This signal set constant represents the bit in the signal set + * associated with signal 22. + */ +#define RTEMS_SIGNAL_22 0x00400000 + +/* Generated from spec:/rtems/signal/if/signal-23 */ + +/** + * @ingroup RTEMSAPIClassicSignal + * + * @brief This signal set constant represents the bit in the signal set + * associated with signal 23. + */ +#define RTEMS_SIGNAL_23 0x00800000 + +/* Generated from spec:/rtems/signal/if/signal-24 */ + +/** + * @ingroup RTEMSAPIClassicSignal + * + * @brief This signal set constant represents the bit in the signal set + * associated with signal 24. + */ +#define RTEMS_SIGNAL_24 0x01000000 + +/* Generated from spec:/rtems/signal/if/signal-25 */ + +/** + * @ingroup RTEMSAPIClassicSignal + * + * @brief This signal set constant represents the bit in the signal set + * associated with signal 25. + */ +#define RTEMS_SIGNAL_25 0x02000000 + +/* Generated from spec:/rtems/signal/if/signal-26 */ + +/** + * @ingroup RTEMSAPIClassicSignal + * + * @brief This signal set constant represents the bit in the signal set + * associated with signal 26. + */ +#define RTEMS_SIGNAL_26 0x04000000 + +/* Generated from spec:/rtems/signal/if/signal-27 */ + +/** + * @ingroup RTEMSAPIClassicSignal + * + * @brief This signal set constant represents the bit in the signal set + * associated with signal 27. + */ +#define RTEMS_SIGNAL_27 0x08000000 + +/* Generated from spec:/rtems/signal/if/signal-28 */ + +/** + * @ingroup RTEMSAPIClassicSignal + * + * @brief This signal set constant represents the bit in the signal set + * associated with signal 28. + */ +#define RTEMS_SIGNAL_28 0x10000000 + +/* Generated from spec:/rtems/signal/if/signal-29 */ + +/** + * @ingroup RTEMSAPIClassicSignal + * + * @brief This signal set constant represents the bit in the signal set + * associated with signal 29. + */ +#define RTEMS_SIGNAL_29 0x20000000 + +/* Generated from spec:/rtems/signal/if/signal-30 */ + +/** + * @ingroup RTEMSAPIClassicSignal + * + * @brief This signal set constant represents the bit in the signal set + * associated with signal 30. + */ +#define RTEMS_SIGNAL_30 0x40000000 + +/* Generated from spec:/rtems/signal/if/signal-31 */ + +/** + * @ingroup RTEMSAPIClassicSignal + * + * @brief This signal set constant represents the bit in the signal set + * associated with signal 31. + */ +#define RTEMS_SIGNAL_31 0x80000000 #ifdef __cplusplus } #endif -#endif -/* end of include file */ +#endif /* _RTEMS_RTEMS_ASR_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