rtems: Generate <rtems/rtems/signal.h>

Change license to BSD-2-Clause according to file histories and
documentation re-licensing agreement.

Update #3899.
Update #3993.

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 <rtems/rtems/modes.h>
+#include <stdint.h>
 
 #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 */