[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