[PATCH] c-user: Generate signal manager documentation

Gedare Bloom gedare at rtems.org
Thu Feb 18 17:13:45 UTC 2021


ok

On Wed, Feb 17, 2021 at 12:24 PM Sebastian Huber
<sebastian.huber at 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 at rtems.org
> http://lists.rtems.org/mailman/listinfo/devel


More information about the devel mailing list