Changeset c87d8c2 in rtems-docs


Ignore:
Timestamp:
Feb 17, 2021, 5:34:23 PM (2 months ago)
Author:
Sebastian Huber <sebastian.huber@…>
Branches:
master
Children:
fcac22e
Parents:
3afdebd
git-author:
Sebastian Huber <sebastian.huber@…> (02/17/21 17:34:23)
git-committer:
Sebastian Huber <sebastian.huber@…> (02/19/21 06:06:00)
Message:

c-user: Generate signal manager documentation

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.

Location:
c-user/signal
Files:
2 edited

Legend:

Unmodified
Added
Removed
  • c-user/signal/directives.rst

    r3afdebd rc87d8c2  
    11.. SPDX-License-Identifier: CC-BY-SA-4.0
    22
     3.. Copyright (C) 2020, 2021 embedded brains GmbH (http://www.embedded-brains.de)
    34.. Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR)
     5
     6.. This file is part of the RTEMS quality process and was automatically
     7.. generated.  If you find something that needs to be fixed or
     8.. worded better please post a report or patch to an RTEMS mailing list
     9.. or raise a bug report:
     10..
     11.. https://www.rtems.org/bugs.html
     12..
     13.. For information on updating and regenerating please refer to the How-To
     14.. section in the Software Requirements Engineering chapter of the
     15.. RTEMS Software Engineering manual.  The manual is provided as a part of
     16.. a release.  For development sources please refer to the online
     17.. documentation at:
     18..
     19.. https://docs.rtems.org
     20
     21.. _SignalManagerDirectives:
    422
    523Directives
    624==========
    725
    8 This section details the signal manager's directives.  A subsection is
    9 dedicated to each of this manager's directives and describes the calling
    10 sequence, related constants, usage, and status codes.
     26This section details the directives of the Signal Manager. A subsection is
     27dedicated to each of this manager's directives and lists the calling sequence,
     28parameters, description, return values, and notes of the directive.
     29
     30.. Generated from spec:/rtems/signal/if/catch
    1131
    1232.. raw:: latex
    1333
    14    \clearpage
     34    \clearpage
    1535
     36.. index:: rtems_signal_catch()
    1637.. index:: establish an ASR
    1738.. index:: install an ASR
    18 .. index:: rtems_signal_catch
    1939
    20 .. _rtems_signal_catch:
     40.. _InterfaceRtemsSignalCatch:
    2141
    22 SIGNAL_CATCH - Establish an ASR
    23 -------------------------------
     42rtems_signal_catch()
     43--------------------
    2444
    25 CALLING SEQUENCE:
    26     .. code-block:: c
     45Establishes an asynchronous signal routine (ASR) for the calling task.
    2746
    28         rtems_status_code rtems_signal_catch(
    29             rtems_asr_entry  asr_handler,
    30             rtems_mode       mode
    31         );
     47.. rubric:: CALLING SEQUENCE:
    3248
    33 DIRECTIVE STATUS CODES:
    34     .. list-table::
    35      :class: rtems-table
     49.. code-block:: c
    3650
    37      * - ``RTEMS_SUCCESSFUL``
    38        - always successful
     51    rtems_status_code rtems_signal_catch(
     52      rtems_asr_entry asr_handler,
     53      rtems_mode      mode_set
     54    );
    3955
    40 DESCRIPTION:
    41     This directive establishes an asynchronous signal routine (ASR) for the
    42     calling task.  The asr_handler parameter specifies the entry point of the
    43     ASR.  If asr_handler is NULL, the ASR for the calling task is invalidated
    44     and all pending signals are cleared.  Any signals sent to a task with an
    45     invalid ASR are discarded.  The mode parameter specifies the execution mode
    46     for the ASR.  This execution mode supersedes the task's execution mode
    47     while the ASR is executing.
     56.. rubric:: PARAMETERS:
    4857
    49 NOTES:
    50     This directive will not cause the calling task to be preempted.
     58``asr_handler``
     59    This parameter is the handler to process an asynchronous signal set.
    5160
    52     The following task mode constants are defined by RTEMS:
     61``mode_set``
     62    This parameter is the task mode while an asynchronous signal set is
     63    processed by the handler.  See :ref:`InterfaceRtemsTaskMode`.
    5364
    54     .. list-table::
    55      :class: rtems-table
     65.. rubric:: DESCRIPTION:
    5666
    57      * - ``RTEMS_PREEMPT``
    58        - is masked by ``RTEMS_PREEMPT_MASK`` and enables preemption
    59      * - ``RTEMS_NO_PREEMPT``
    60        - is masked by ``RTEMS_PREEMPT_MASK`` and disables preemption
    61      * - ``RTEMS_NO_TIMESLICE``
    62        - is masked by ``RTEMS_TIMESLICE_MASK`` and disables timeslicing
    63      * - ``RTEMS_TIMESLICE``
    64        - is masked by ``RTEMS_TIMESLICE_MASK`` and enables timeslicing
    65      * - ``RTEMS_ASR``
    66        - is masked by ``RTEMS_ASR_MASK`` and enables ASR processing
    67      * - ``RTEMS_NO_ASR``
    68        - is masked by ``RTEMS_ASR_MASK`` and disables ASR processing
    69      * - ``RTEMS_INTERRUPT_LEVEL(0)``
    70        - is masked by ``RTEMS_INTERRUPT_MASK`` and enables all interrupts
    71      * - ``RTEMS_INTERRUPT_LEVEL(n)``
    72        - is masked by ``RTEMS_INTERRUPT_MASK`` and sets interrupts level n
     67This directive establishes an asynchronous signal routine (ASR) for the calling
     68task.  The ``asr_handler`` parameter specifies the entry point of the ASR.  A
     69task may have at most one handler installed at a time.  The most recently
     70installed handler is used.  When ``asr_handler`` is `NULL
     71<https://en.cppreference.com/w/c/types/NULL>`_, the ASR for the calling task is
     72invalidated and all pending signals are cleared.  Any signals sent to a task
     73with an invalid ASR are discarded.  The ``mode_set`` parameter specifies the
     74execution mode for the ASR.  This execution mode supersedes the task's
     75execution mode while the ASR is executing.
     76
     77.. rubric:: RETURN VALUES:
     78
     79:c:macro:`RTEMS_SUCCESSFUL`
     80    The requested operation was successful.
     81
     82:c:macro:`RTEMS_NOT_IMPLEMENTED`
     83    The :c:macro:`RTEMS_NO_PREEMPT` was set in ``mode_set`` and the system
     84    configuration had no implementation for this mode.
     85
     86:c:macro:`RTEMS_NOT_IMPLEMENTED`
     87    The :c:func:`RTEMS_INTERRUPT_LEVEL` was set to a positive level in
     88    ``mode_set`` and the system configuration had no implementation for this
     89    mode.
     90
     91.. rubric:: NOTES:
     92
     93It is strongly recommended to disable ASR processing during ASR processing by
     94setting :c:macro:`RTEMS_NO_ASR` in ``mode_set``, otherwise a recursion may
     95happen during ASR processing.  Uncontrolled recursion may lead to stack
     96overflows.
     97
     98Using the same mutex (in particular a recursive mutex) in normal task context
     99and during ASR processing may result in undefined behaviour.
     100
     101Asynchronous signal handlers can access thread-local storage (:term:`TLS`).
     102When thread-local storage is shared between normal task context and ASR
     103processing, it may be protected by disabled interrupts.
     104
     105.. rubric:: CONSTRAINTS:
     106
     107The following constraints apply to this directive:
     108
     109* The directive may be called from within task context.
     110
     111* The directive will not cause the calling task to be preempted.
     112
     113.. Generated from spec:/rtems/signal/if/send
    73114
    74115.. raw:: latex
    75116
    76    \clearpage
     117    \clearpage
    77118
     119.. index:: rtems_signal_send()
    78120.. index:: send signal set
    79 .. index:: rtems_signal_send
    80121
    81 .. _rtems_signal_send:
     122.. _InterfaceRtemsSignalSend:
    82123
    83 SIGNAL_SEND - Send signal set to a task
    84 ---------------------------------------
     124rtems_signal_send()
     125-------------------
    85126
    86 CALLING SEQUENCE:
    87     .. code-block:: c
     127Sends the signal set to the task.
    88128
    89         rtems_status_code rtems_signal_send(
    90             rtems_id         id,
    91             rtems_signal_set signal_set
    92         );
     129.. rubric:: CALLING SEQUENCE:
    93130
    94 DIRECTIVE STATUS CODES:
    95     .. list-table::
    96      :class: rtems-table
     131.. code-block:: c
    97132
    98      * - ``RTEMS_SUCCESSFUL``
    99        - signal sent successfully
    100      * - ``RTEMS_INVALID_ID``
    101        - task id invalid
    102      * - ``RTEMS_INVALID_NUMBER``
    103        - empty signal set
    104      * - ``RTEMS_NOT_DEFINED``
    105        - ASR invalid
     133    rtems_status_code rtems_signal_send(
     134      rtems_id         id,
     135      rtems_signal_set signal_set
     136    );
    106137
    107 DESCRIPTION:
    108     This directive sends a signal set to the task specified in id.  The
    109     signal_set parameter contains the signal set to be sent to the task.
     138.. rubric:: PARAMETERS:
    110139
    111     If a caller sends a signal set to a task with an invalid ASR, then an error
    112     code is returned to the caller.  If a caller sends a signal set to a task
    113     whose ASR is valid but disabled, then the signal set will be caught and
    114     left pending for the ASR to process when it is enabled. If a caller sends a
    115     signal set to a task with an ASR that is both valid and enabled, then the
    116     signal set is caught and the ASR will execute the next time the task is
    117     dispatched to run.
     140``id``
     141    This parameter is the identifier of the target task to receive the signal
     142    set.
    118143
    119 NOTES:
    120     Sending a signal set to a task has no effect on that task's state.  If a
    121     signal set is sent to a blocked task, then the task will remain blocked and
    122     the signals will be processed when the task becomes the running task.
     144``signal_set``
     145    This parameter is the signal set to send.
    123146
    124     Sending a signal set to a global task which does not reside on the local
    125     node will generate a request telling the remote node to send the signal set
    126     to the specified task.
     147.. rubric:: DESCRIPTION:
     148
     149This directive sends the signal set, ``signal_set``, to the target task
     150identified by ``id``.
     151
     152If a caller sends a signal set to a task with an invalid :term:`ASR`, then an
     153error code is returned to the caller.  If a caller sends a signal set to a task
     154whose ASR is valid but disabled, then the signal set will be caught and left
     155pending for the ASR to process when it is enabled.  If a caller sends a signal
     156set to a task with an ASR that is both valid and enabled, then the signal set
     157is caught and the ASR will execute the next time the task is dispatched to run.
     158
     159.. rubric:: RETURN VALUES:
     160
     161:c:macro:`RTEMS_SUCCESSFUL`
     162    The requested operation was successful.
     163
     164:c:macro:`RTEMS_INVALID_NUMBER`
     165    The ``signal_set`` parameter was 0.
     166
     167:c:macro:`RTEMS_INVALID_ID`
     168    There was no task associated with the identifier specified by ``id``.
     169
     170:c:macro:`RTEMS_NOT_DEFINED`
     171    The target task had no valid ASR installed.
     172
     173.. rubric:: NOTES:
     174
     175Sending a signal set to a task has no effect on that task's state.  If a signal
     176set is sent to a blocked task, then the task will remain blocked and the
     177signals will be processed when the task becomes the running task.
     178
     179Sending a signal set to a global task which does not reside on the local node
     180will generate a request telling the remote node to send the signal set to the
     181specified task.
     182
     183.. rubric:: CONSTRAINTS:
     184
     185The following constraints apply to this directive:
     186
     187* The directive may be called from within interrupt context.
     188
     189* The directive may be called from within device driver initialization context.
     190
     191* The directive may be called from within task context.
     192
     193* When the directive operates on a local object, the directive will not cause
     194  the calling task to be preempted.
     195
     196* When the directive operates on a remote object, the directive sends a message
     197  to the remote node and waits for a reply.  This will preempt the calling
     198  task.
  • c-user/signal/introduction.rst

    r3afdebd rc87d8c2  
    11.. SPDX-License-Identifier: CC-BY-SA-4.0
    22
     3.. Copyright (C) 2020, 2021 embedded brains GmbH (http://www.embedded-brains.de)
    34.. Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR)
     5
     6.. This file is part of the RTEMS quality process and was automatically
     7.. generated.  If you find something that needs to be fixed or
     8.. worded better please post a report or patch to an RTEMS mailing list
     9.. or raise a bug report:
     10..
     11.. https://www.rtems.org/bugs.html
     12..
     13.. For information on updating and regenerating please refer to the How-To
     14.. section in the Software Requirements Engineering chapter of the
     15.. RTEMS Software Engineering manual.  The manual is provided as a part of
     16.. a release.  For development sources please refer to the online
     17.. documentation at:
     18..
     19.. https://docs.rtems.org
     20
     21.. Generated from spec:/rtems/signal/if/group
     22
     23.. _SignalManagerIntroduction:
    424
    525Introduction
    626============
    727
    8 The signal manager provides the capabilities required for asynchronous
    9 communication.  The directives provided by the signal manager are:
     28.. The following list was generated from:
     29.. spec:/rtems/signal/if/catch
     30.. spec:/rtems/signal/if/send
    1031
    11 - :ref:`rtems_signal_catch`
     32The Signal Manager provides the capabilities required for asynchronous
     33communication. The directives provided by the Signal Manager are:
    1234
    13 - :ref:`rtems_signal_send`
     35* :ref:`InterfaceRtemsSignalCatch` - Establishes an asynchronous signal routine
     36  (ASR) for the calling task.
     37
     38* :ref:`InterfaceRtemsSignalSend` - Sends the signal set to the task.
Note: See TracChangeset for help on using the changeset viewer.