mirror of
https://git.rtems.org/rtems-docs/
synced 2025-05-17 15:13:59 +08:00
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.
This commit is contained in:
Sebastian Huber
parent
3afdebda9a
commit
c87d8c2af3
@ -1,126 +1,198 @@
|
|||||||
.. SPDX-License-Identifier: CC-BY-SA-4.0
|
.. 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)
|
.. 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
|
Directives
|
||||||
==========
|
==========
|
||||||
|
|
||||||
This section details the signal manager's directives. A subsection is
|
This section details the directives of the Signal Manager. A subsection is
|
||||||
dedicated to each of this manager's directives and describes the calling
|
dedicated to each of this manager's directives and lists the calling sequence,
|
||||||
sequence, related constants, usage, and status codes.
|
parameters, description, return values, and notes of the directive.
|
||||||
|
|
||||||
|
.. Generated from spec:/rtems/signal/if/catch
|
||||||
|
|
||||||
.. raw:: latex
|
.. raw:: latex
|
||||||
|
|
||||||
\clearpage
|
\clearpage
|
||||||
|
|
||||||
|
.. index:: rtems_signal_catch()
|
||||||
.. index:: establish an ASR
|
.. index:: establish an ASR
|
||||||
.. index:: install an ASR
|
.. index:: install an ASR
|
||||||
.. index:: rtems_signal_catch
|
|
||||||
|
|
||||||
.. _rtems_signal_catch:
|
.. _InterfaceRtemsSignalCatch:
|
||||||
|
|
||||||
SIGNAL_CATCH - Establish an ASR
|
rtems_signal_catch()
|
||||||
-------------------------------
|
--------------------
|
||||||
|
|
||||||
CALLING SEQUENCE:
|
Establishes an asynchronous signal routine (ASR) for the calling task.
|
||||||
.. code-block:: c
|
|
||||||
|
|
||||||
rtems_status_code rtems_signal_catch(
|
.. rubric:: CALLING SEQUENCE:
|
||||||
rtems_asr_entry asr_handler,
|
|
||||||
rtems_mode mode
|
|
||||||
);
|
|
||||||
|
|
||||||
DIRECTIVE STATUS CODES:
|
.. code-block:: c
|
||||||
.. list-table::
|
|
||||||
:class: rtems-table
|
|
||||||
|
|
||||||
* - ``RTEMS_SUCCESSFUL``
|
rtems_status_code rtems_signal_catch(
|
||||||
- always successful
|
rtems_asr_entry asr_handler,
|
||||||
|
rtems_mode mode_set
|
||||||
|
);
|
||||||
|
|
||||||
DESCRIPTION:
|
.. rubric:: PARAMETERS:
|
||||||
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:
|
``asr_handler``
|
||||||
This directive will not cause the calling task to be preempted.
|
This parameter is the handler to process an asynchronous signal set.
|
||||||
|
|
||||||
The following task mode constants are defined by RTEMS:
|
``mode_set``
|
||||||
|
This parameter is the task mode while an asynchronous signal set is
|
||||||
|
processed by the handler. See :ref:`InterfaceRtemsTaskMode`.
|
||||||
|
|
||||||
.. list-table::
|
.. rubric:: DESCRIPTION:
|
||||||
:class: rtems-table
|
|
||||||
|
|
||||||
* - ``RTEMS_PREEMPT``
|
This directive establishes an asynchronous signal routine (ASR) for the calling
|
||||||
- is masked by ``RTEMS_PREEMPT_MASK`` and enables preemption
|
task. The ``asr_handler`` parameter specifies the entry point of the ASR. A
|
||||||
* - ``RTEMS_NO_PREEMPT``
|
task may have at most one handler installed at a time. The most recently
|
||||||
- is masked by ``RTEMS_PREEMPT_MASK`` and disables preemption
|
installed handler is used. When ``asr_handler`` is `NULL
|
||||||
* - ``RTEMS_NO_TIMESLICE``
|
<https://en.cppreference.com/w/c/types/NULL>`_, the ASR for the calling task is
|
||||||
- is masked by ``RTEMS_TIMESLICE_MASK`` and disables timeslicing
|
invalidated and all pending signals are cleared. Any signals sent to a task
|
||||||
* - ``RTEMS_TIMESLICE``
|
with an invalid ASR are discarded. The ``mode_set`` parameter specifies the
|
||||||
- is masked by ``RTEMS_TIMESLICE_MASK`` and enables timeslicing
|
execution mode for the ASR. This execution mode supersedes the task's
|
||||||
* - ``RTEMS_ASR``
|
execution mode while the ASR is executing.
|
||||||
- is masked by ``RTEMS_ASR_MASK`` and enables ASR processing
|
|
||||||
* - ``RTEMS_NO_ASR``
|
.. rubric:: RETURN VALUES:
|
||||||
- is masked by ``RTEMS_ASR_MASK`` and disables ASR processing
|
|
||||||
* - ``RTEMS_INTERRUPT_LEVEL(0)``
|
:c:macro:`RTEMS_SUCCESSFUL`
|
||||||
- is masked by ``RTEMS_INTERRUPT_MASK`` and enables all interrupts
|
The requested operation was successful.
|
||||||
* - ``RTEMS_INTERRUPT_LEVEL(n)``
|
|
||||||
- is masked by ``RTEMS_INTERRUPT_MASK`` and sets interrupts level n
|
: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
|
.. raw:: latex
|
||||||
|
|
||||||
\clearpage
|
\clearpage
|
||||||
|
|
||||||
|
.. index:: rtems_signal_send()
|
||||||
.. index:: send signal set
|
.. index:: send signal set
|
||||||
.. index:: rtems_signal_send
|
|
||||||
|
|
||||||
.. _rtems_signal_send:
|
.. _InterfaceRtemsSignalSend:
|
||||||
|
|
||||||
SIGNAL_SEND - Send signal set to a task
|
rtems_signal_send()
|
||||||
---------------------------------------
|
-------------------
|
||||||
|
|
||||||
CALLING SEQUENCE:
|
Sends the signal set to the task.
|
||||||
.. code-block:: c
|
|
||||||
|
|
||||||
rtems_status_code rtems_signal_send(
|
.. rubric:: CALLING SEQUENCE:
|
||||||
rtems_id id,
|
|
||||||
rtems_signal_set signal_set
|
|
||||||
);
|
|
||||||
|
|
||||||
DIRECTIVE STATUS CODES:
|
.. code-block:: c
|
||||||
.. list-table::
|
|
||||||
:class: rtems-table
|
|
||||||
|
|
||||||
* - ``RTEMS_SUCCESSFUL``
|
rtems_status_code rtems_signal_send(
|
||||||
- signal sent successfully
|
rtems_id id,
|
||||||
* - ``RTEMS_INVALID_ID``
|
rtems_signal_set signal_set
|
||||||
- task id invalid
|
);
|
||||||
* - ``RTEMS_INVALID_NUMBER``
|
|
||||||
- empty signal set
|
|
||||||
* - ``RTEMS_NOT_DEFINED``
|
|
||||||
- ASR invalid
|
|
||||||
|
|
||||||
DESCRIPTION:
|
.. rubric:: PARAMETERS:
|
||||||
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
|
``id``
|
||||||
code is returned to the caller. If a caller sends a signal set to a task
|
This parameter is the identifier of the target task to receive the signal
|
||||||
whose ASR is valid but disabled, then the signal set will be caught and
|
set.
|
||||||
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:
|
``signal_set``
|
||||||
Sending a signal set to a task has no effect on that task's state. If a
|
This parameter is the signal set to send.
|
||||||
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
|
.. rubric:: DESCRIPTION:
|
||||||
node will generate a request telling the remote node to send the signal set
|
|
||||||
to the specified task.
|
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.
|
||||||
|
|||||||
@ -1,13 +1,38 @@
|
|||||||
.. SPDX-License-Identifier: CC-BY-SA-4.0
|
.. 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)
|
.. 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
|
Introduction
|
||||||
============
|
============
|
||||||
|
|
||||||
The signal manager provides the capabilities required for asynchronous
|
.. The following list was generated from:
|
||||||
communication. The directives provided by the signal manager are:
|
.. spec:/rtems/signal/if/catch
|
||||||
|
.. spec:/rtems/signal/if/send
|
||||||
|
|
||||||
- :ref:`rtems_signal_catch`
|
The Signal Manager provides the capabilities required for asynchronous
|
||||||
|
communication. The directives provided by the Signal Manager are:
|
||||||
|
|
||||||
- :ref:`rtems_signal_send`
|
* :ref:`InterfaceRtemsSignalCatch` - Establishes an asynchronous signal routine
|
||||||
|
(ASR) for the calling task.
|
||||||
|
|
||||||
|
* :ref:`InterfaceRtemsSignalSend` - Sends the signal set to the task.
|
||||||
|
|||||||
Loading…
x
Reference in New Issue
Block a user