ok
On Wed, Feb 17, 2021 at 12:24 PM Sebastian Huber <sebastian.hu...@embedded-brains.de> wrote: > > The documentation is a consolidation of the comments in Doxygen markup > and the documentation sources in Sphinx markup. The documentation was > transfered to interface specification items. The documentation source > files were generated from the items by a script. > > Update #3993. > --- > c-user/signal/directives.rst | 288 ++++++++++++++++++++------------- > c-user/signal/introduction.rst | 33 +++- > 2 files changed, 209 insertions(+), 112 deletions(-) > > diff --git a/c-user/signal/directives.rst b/c-user/signal/directives.rst > index 2479681..b883b0a 100644 > --- a/c-user/signal/directives.rst > +++ b/c-user/signal/directives.rst > @@ -1,126 +1,198 @@ > .. SPDX-License-Identifier: CC-BY-SA-4.0 > > +.. Copyright (C) 2020, 2021 embedded brains GmbH > (http://www.embedded-brains.de) > .. Copyright (C) 1988, 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 > +.. > +.. 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 > + > +.. _SignalManagerDirectives: > + > Directives > ========== > > -This section details the signal manager's directives. A subsection is > -dedicated to each of this manager's directives and describes the calling > -sequence, related constants, usage, and status codes. > +This section details the directives of the Signal Manager. A subsection is > +dedicated to each of this manager's directives and lists the calling > sequence, > +parameters, description, return values, and notes of the directive. > + > +.. Generated from spec:/rtems/signal/if/catch > > .. raw:: latex > > - \clearpage > + \clearpage > > +.. index:: rtems_signal_catch() > .. index:: establish an ASR > .. index:: install an ASR > -.. index:: rtems_signal_catch > - > -.. _rtems_signal_catch: > - > -SIGNAL_CATCH - Establish an ASR > -------------------------------- > - > -CALLING SEQUENCE: > - .. code-block:: c > - > - rtems_status_code rtems_signal_catch( > - rtems_asr_entry asr_handler, > - rtems_mode mode > - ); > - > -DIRECTIVE STATUS CODES: > - .. list-table:: > - :class: rtems-table > - > - * - ``RTEMS_SUCCESSFUL`` > - - always successful > - > -DESCRIPTION: > - This directive establishes an asynchronous signal routine (ASR) for the > - calling task. The asr_handler parameter specifies the entry point of the > - ASR. If 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 parameter specifies the execution > mode > - for the ASR. This execution mode supersedes the task's execution mode > - while the ASR is executing. > - > -NOTES: > - This directive will not cause the calling task to be preempted. > - > - The following task mode constants are defined by RTEMS: > - > - .. list-table:: > - :class: rtems-table > - > - * - ``RTEMS_PREEMPT`` > - - is masked by ``RTEMS_PREEMPT_MASK`` and enables preemption > - * - ``RTEMS_NO_PREEMPT`` > - - is masked by ``RTEMS_PREEMPT_MASK`` and disables preemption > - * - ``RTEMS_NO_TIMESLICE`` > - - is masked by ``RTEMS_TIMESLICE_MASK`` and disables timeslicing > - * - ``RTEMS_TIMESLICE`` > - - is masked by ``RTEMS_TIMESLICE_MASK`` and enables timeslicing > - * - ``RTEMS_ASR`` > - - is masked by ``RTEMS_ASR_MASK`` and enables ASR processing > - * - ``RTEMS_NO_ASR`` > - - is masked by ``RTEMS_ASR_MASK`` and disables ASR processing > - * - ``RTEMS_INTERRUPT_LEVEL(0)`` > - - is masked by ``RTEMS_INTERRUPT_MASK`` and enables all interrupts > - * - ``RTEMS_INTERRUPT_LEVEL(n)`` > - - is masked by ``RTEMS_INTERRUPT_MASK`` and sets interrupts level n > + > +.. _InterfaceRtemsSignalCatch: > + > +rtems_signal_catch() > +-------------------- > + > +Establishes an asynchronous signal routine (ASR) for the calling task. > + > +.. rubric:: CALLING SEQUENCE: > + > +.. code-block:: c > + > + rtems_status_code rtems_signal_catch( > + rtems_asr_entry asr_handler, > + rtems_mode mode_set > + ); > + > +.. rubric:: PARAMETERS: > + > +``asr_handler`` > + This parameter is the handler to process an asynchronous signal set. > + > +``mode_set`` > + This parameter is the task mode while an asynchronous signal set is > + processed by the handler. See :ref:`InterfaceRtemsTaskMode`. > + > +.. rubric:: DESCRIPTION: > + > +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 > +<https://en.cppreference.com/w/c/types/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. > + > +.. rubric:: RETURN VALUES: > + > +:c:macro:`RTEMS_SUCCESSFUL` > + The requested operation was successful. > + > +:c:macro:`RTEMS_NOT_IMPLEMENTED` > + The :c:macro:`RTEMS_NO_PREEMPT` was set in ``mode_set`` and the system > + configuration had no implementation for this mode. > + > +:c:macro:`RTEMS_NOT_IMPLEMENTED` > + The :c:func:`RTEMS_INTERRUPT_LEVEL` was set to a positive level in > + ``mode_set`` and the system configuration had no implementation for this > + mode. > + > +.. rubric:: NOTES: > + > +It is strongly recommended to disable ASR processing during ASR processing by > +setting :c:macro:`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. > + > +Asynchronous signal handlers can access thread-local storage (:term:`TLS`). > +When thread-local storage is shared between normal task context and ASR > +processing, it may be protected by disabled interrupts. > + > +.. rubric:: CONSTRAINTS: > + > +The following constraints apply to this directive: > + > +* The directive may be called from within task context. > + > +* The directive will not cause the calling task to be preempted. > + > +.. Generated from spec:/rtems/signal/if/send > > .. raw:: latex > > - \clearpage > + \clearpage > > +.. index:: rtems_signal_send() > .. index:: send signal set > -.. index:: rtems_signal_send > - > -.. _rtems_signal_send: > - > -SIGNAL_SEND - Send signal set to a task > ---------------------------------------- > - > -CALLING SEQUENCE: > - .. code-block:: c > - > - rtems_status_code rtems_signal_send( > - rtems_id id, > - rtems_signal_set signal_set > - ); > - > -DIRECTIVE STATUS CODES: > - .. list-table:: > - :class: rtems-table > - > - * - ``RTEMS_SUCCESSFUL`` > - - signal sent successfully > - * - ``RTEMS_INVALID_ID`` > - - task id invalid > - * - ``RTEMS_INVALID_NUMBER`` > - - empty signal set > - * - ``RTEMS_NOT_DEFINED`` > - - ASR invalid > - > -DESCRIPTION: > - This directive sends a signal set to the task specified in id. The > - signal_set parameter contains the signal set to be sent to the task. > - > - 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. > - > -NOTES: > - 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. > + > +.. _InterfaceRtemsSignalSend: > + > +rtems_signal_send() > +------------------- > + > +Sends the signal set to the task. > + > +.. rubric:: CALLING SEQUENCE: > + > +.. code-block:: c > + > + rtems_status_code rtems_signal_send( > + rtems_id id, > + rtems_signal_set signal_set > + ); > + > +.. rubric:: PARAMETERS: > + > +``id`` > + This parameter is the identifier of the target task to receive the signal > + set. > + > +``signal_set`` > + This parameter is the signal set to send. > + > +.. rubric:: DESCRIPTION: > + > +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 :term:`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. > + > +.. rubric:: RETURN VALUES: > + > +:c:macro:`RTEMS_SUCCESSFUL` > + The requested operation was successful. > + > +:c:macro:`RTEMS_INVALID_NUMBER` > + The ``signal_set`` parameter was 0. > + > +:c:macro:`RTEMS_INVALID_ID` > + There was no task associated with the identifier specified by ``id``. > + > +:c:macro:`RTEMS_NOT_DEFINED` > + The target task had no valid ASR installed. > + > +.. rubric:: NOTES: > + > +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. > + > +.. rubric:: CONSTRAINTS: > + > +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. > diff --git a/c-user/signal/introduction.rst b/c-user/signal/introduction.rst > index 292db52..449022a 100644 > --- a/c-user/signal/introduction.rst > +++ b/c-user/signal/introduction.rst > @@ -1,13 +1,38 @@ > .. SPDX-License-Identifier: CC-BY-SA-4.0 > > +.. Copyright (C) 2020, 2021 embedded brains GmbH > (http://www.embedded-brains.de) > .. Copyright (C) 1988, 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 > +.. > +.. 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/group > + > +.. _SignalManagerIntroduction: > + > Introduction > ============ > > -The signal manager provides the capabilities required for asynchronous > -communication. The directives provided by the signal manager are: > +.. The following list was generated from: > +.. spec:/rtems/signal/if/catch > +.. spec:/rtems/signal/if/send > + > +The Signal Manager provides the capabilities required for asynchronous > +communication. The directives provided by the Signal Manager are: > > -- :ref:`rtems_signal_catch` > +* :ref:`InterfaceRtemsSignalCatch` - Establishes an asynchronous signal > routine > + (ASR) for the calling task. > > -- :ref:`rtems_signal_send` > +* :ref:`InterfaceRtemsSignalSend` - Sends the signal set to the task. > -- > 2.26.2 > > _______________________________________________ > devel mailing list > devel@rtems.org > http://lists.rtems.org/mailman/listinfo/devel _______________________________________________ devel mailing list devel@rtems.org http://lists.rtems.org/mailman/listinfo/devel
