From e3523ed062f50def78cc159f9ac7a24946116943 Mon Sep 17 00:00:00 2001 From: Sebastian Huber Date: Thu, 20 Aug 2020 10:11:15 +0200 Subject: c-user: Split up signal manager This makes it easier to automatically generate parts of the manager documentation in the future. Update #3993. --- c-user/index.rst | 2 +- c-user/signal/background.rst | 112 ++++++++++++++ c-user/signal/directives.rst | 126 ++++++++++++++++ c-user/signal/index.rst | 15 ++ c-user/signal/introduction.rst | 13 ++ c-user/signal/operations.rst | 75 ++++++++++ c-user/signal_manager.rst | 322 ----------------------------------------- 7 files changed, 342 insertions(+), 323 deletions(-) create mode 100644 c-user/signal/background.rst create mode 100644 c-user/signal/directives.rst create mode 100644 c-user/signal/index.rst create mode 100644 c-user/signal/introduction.rst create mode 100644 c-user/signal/operations.rst delete mode 100644 c-user/signal_manager.rst (limited to 'c-user') diff --git a/c-user/index.rst b/c-user/index.rst index 7bd6017..3628634 100644 --- a/c-user/index.rst +++ b/c-user/index.rst @@ -39,7 +39,7 @@ RTEMS Classic API Guide (|version|). barrier/index message/index event/index - signal_manager + signal/index partition/index region/index dual-ported-memory/index diff --git a/c-user/signal/background.rst b/c-user/signal/background.rst new file mode 100644 index 0000000..5ba5eeb --- /dev/null +++ b/c-user/signal/background.rst @@ -0,0 +1,112 @@ +.. SPDX-License-Identifier: CC-BY-SA-4.0 + +.. Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) + +Background +========== + +.. index:: asynchronous signal routine +.. index:: ASR + +Signal Manager Definitions +-------------------------- + +The signal manager allows a task to optionally define an asynchronous signal +routine (ASR). An ASR is to a task what an ISR is to an application's set of +tasks. When the processor is interrupted, the execution of an application is +also interrupted and an ISR is given control. Similarly, when a signal is sent +to a task, that task's execution path will be "interrupted" by the ASR. +Sending a signal to a task has no effect on the receiving task's current +execution state. + +.. index:: rtems_signal_set + +A signal flag is used by a task (or ISR) to inform another task of the +occurrence of a significant situation. Thirty-two signal flags are associated +with each task. A collection of one or more signals is referred to as a signal +set. The data type ``rtems_signal_set`` is used to manipulate signal sets. + +A signal set is posted when it is directed (or sent) to a task. A pending +signal is a signal that has been sent to a task with a valid ASR, but has not +been processed by that task's ASR. + +.. index:: ASR vs. ISR +.. index:: ISR vs. ASR + +A Comparison of ASRs and ISRs +----------------------------- + +The format of an ASR is similar to that of an ISR with the following +exceptions: + +- ISRs are scheduled by the processor hardware. ASRs are scheduled by RTEMS. + +- ISRs do not execute in the context of a task and may invoke only a subset of + directives. ASRs execute in the context of a task and may execute any + directive. + +- When an ISR is invoked, it is passed the vector number as its argument. When + an ASR is invoked, it is passed the signal set as its argument. + +- An ASR has a task mode which can be different from that of the task. An ISR + does not execute as a task and, as a result, does not have a task mode. + +.. index:: signal set, building + +Building a Signal Set +--------------------- + +A signal set is built by a bitwise OR of the desired signals. The set of valid +signals is ``RTEMS_SIGNAL_0`` through ``RTEMS_SIGNAL_31``. If a signal is not +explicitly specified in the signal set, then it is not present. Signal values +are specifically designed to be mutually exclusive, therefore bitwise OR and +addition operations are equivalent as long as each signal appears exactly once +in the component list. + +This example demonstrates the signal parameter used when sending the signal set +consisting of ``RTEMS_SIGNAL_6``, ``RTEMS_SIGNAL_15``, and ``RTEMS_SIGNAL_31``. +The signal parameter provided to the ``rtems_signal_send`` directive should be +``RTEMS_SIGNAL_6 | RTEMS_SIGNAL_15 | RTEMS_SIGNAL_31``. + +.. index:: ASR mode, building + +Building an ASR Mode +-------------------- + +In general, an ASR's mode is built by a bitwise OR of the desired mode +components. The set of valid mode components is the same as those allowed with +the task_create and task_mode directives. A complete list of mode options is +provided in the following table: + +.. 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 + +Mode values are specifically designed to be mutually exclusive, therefore +bitwise OR and addition operations are equivalent as long as each mode appears +exactly once in the component list. A mode component listed as a default is +not required to appear in the mode list, although it is a good programming +practice to specify default components. If all defaults are desired, the mode +``DEFAULT_MODES`` should be specified on this call. + +This example demonstrates the mode parameter used with the +``rtems_signal_catch`` to establish an ASR which executes at interrupt level +three and is non-preemptible. The mode should be set to +``RTEMS_INTERRUPT_LEVEL(3) | RTEMS_NO_PREEMPT`` to indicate the desired +processor mode and interrupt level. diff --git a/c-user/signal/directives.rst b/c-user/signal/directives.rst new file mode 100644 index 0000000..2479681 --- /dev/null +++ b/c-user/signal/directives.rst @@ -0,0 +1,126 @@ +.. SPDX-License-Identifier: CC-BY-SA-4.0 + +.. Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) + +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. + +.. raw:: latex + + \clearpage + +.. 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 + +.. raw:: latex + + \clearpage + +.. 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. diff --git a/c-user/signal/index.rst b/c-user/signal/index.rst new file mode 100644 index 0000000..ad28b9f --- /dev/null +++ b/c-user/signal/index.rst @@ -0,0 +1,15 @@ +.. SPDX-License-Identifier: CC-BY-SA-4.0 + +.. Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de) + +.. index:: signals + +Signal Manager +************** + +.. toctree:: + + introduction + background + operations + directives diff --git a/c-user/signal/introduction.rst b/c-user/signal/introduction.rst new file mode 100644 index 0000000..292db52 --- /dev/null +++ b/c-user/signal/introduction.rst @@ -0,0 +1,13 @@ +.. SPDX-License-Identifier: CC-BY-SA-4.0 + +.. Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) + +Introduction +============ + +The signal manager provides the capabilities required for asynchronous +communication. The directives provided by the signal manager are: + +- :ref:`rtems_signal_catch` + +- :ref:`rtems_signal_send` diff --git a/c-user/signal/operations.rst b/c-user/signal/operations.rst new file mode 100644 index 0000000..967b35f --- /dev/null +++ b/c-user/signal/operations.rst @@ -0,0 +1,75 @@ +.. SPDX-License-Identifier: CC-BY-SA-4.0 + +.. Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) + +Operations +========== + +Establishing an ASR +------------------- + +The ``rtems_signal_catch`` directive establishes an ASR for the calling task. +The address of the ASR and its execution mode are specified to this directive. +The ASR's mode is distinct from the task's mode. For example, the task may +allow preemption, while that task's ASR may have preemption disabled. Until a +task calls ``rtems_signal_catch`` the first time, its ASR is invalid, and no +signal sets can be sent to the task. + +A task may invalidate its ASR and discard all pending signals by calling +``rtems_signal_catch`` with a value of NULL for the ASR's address. When a +task's ASR is invalid, new signal sets sent to this task are discarded. + +A task may disable ASR processing (``RTEMS_NO_ASR``) via the task_mode +directive. When a task's ASR is disabled, the signals sent to it are left +pending to be processed later when the ASR is enabled. + +Any directive that can be called from a task can also be called from an ASR. A +task is only allowed one active ASR. Thus, each call to ``rtems_signal_catch`` +replaces the previous one. + +Normally, signal processing is disabled for the ASR's execution mode, but if +signal processing is enabled for the ASR, the ASR must be reentrant. + +Sending a Signal Set +-------------------- + +The ``rtems_signal_send`` directive allows both tasks and ISRs to send signals +to a target task. The target task and a set of signals are specified to the +``rtems_signal_send`` directive. The sending of a signal to a task has no +effect on the execution state of that task. If the task is not the currently +running task, then the signals are left pending and processed by the task's ASR +the next time the task is dispatched to run. The ASR is executed immediately +before the task is dispatched. If the currently running task sends a signal to +itself or is sent a signal from an ISR, its ASR is immediately dispatched to +run provided signal processing is enabled. + +If an ASR with signals enabled is preempted by another task or an ISR and a new +signal set is sent, then a new copy of the ASR will be invoked, nesting the +preempted ASR. Upon completion of processing the new signal set, control will +return to the preempted ASR. In this situation, the ASR must be reentrant. + +Like events, identical signals sent to a task are not queued. In other words, +sending the same signal multiple times to a task (without any intermediate +signal processing occurring for the task), has the same result as sending that +signal to that task once. + +.. index:: rtems_asr + +Processing an ASR +----------------- + +Asynchronous signals were designed to provide the capability to generate +software interrupts. The processing of software interrupts parallels that of +hardware interrupts. As a result, the differences between the formats of ASRs +and ISRs is limited to the meaning of the single argument passed to an ASR. +The ASR should have the following calling sequence and adhere to C calling +conventions: + +.. code-block:: c + + rtems_asr user_routine( + rtems_signal_set signals + ); + +When the ASR returns to RTEMS the mode and execution path of the interrupted +task (or ASR) is restored to the context prior to entering the ASR. diff --git a/c-user/signal_manager.rst b/c-user/signal_manager.rst deleted file mode 100644 index 8cf1101..0000000 --- a/c-user/signal_manager.rst +++ /dev/null @@ -1,322 +0,0 @@ -.. SPDX-License-Identifier: CC-BY-SA-4.0 - -.. Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) - -.. index:: signals - -Signal Manager -************** - -Introduction -============ - -The signal manager provides the capabilities required for asynchronous -communication. The directives provided by the signal manager are: - -- rtems_signal_catch_ - Establish an ASR - -- rtems_signal_send_ - Send signal set to a task - -Background -========== - -.. index:: asynchronous signal routine -.. index:: ASR - -Signal Manager Definitions --------------------------- - -The signal manager allows a task to optionally define an asynchronous signal -routine (ASR). An ASR is to a task what an ISR is to an application's set of -tasks. When the processor is interrupted, the execution of an application is -also interrupted and an ISR is given control. Similarly, when a signal is sent -to a task, that task's execution path will be "interrupted" by the ASR. -Sending a signal to a task has no effect on the receiving task's current -execution state. - -.. index:: rtems_signal_set - -A signal flag is used by a task (or ISR) to inform another task of the -occurrence of a significant situation. Thirty-two signal flags are associated -with each task. A collection of one or more signals is referred to as a signal -set. The data type ``rtems_signal_set`` is used to manipulate signal sets. - -A signal set is posted when it is directed (or sent) to a task. A pending -signal is a signal that has been sent to a task with a valid ASR, but has not -been processed by that task's ASR. - -.. index:: ASR vs. ISR -.. index:: ISR vs. ASR - -A Comparison of ASRs and ISRs ------------------------------ - -The format of an ASR is similar to that of an ISR with the following -exceptions: - -- ISRs are scheduled by the processor hardware. ASRs are scheduled by RTEMS. - -- ISRs do not execute in the context of a task and may invoke only a subset of - directives. ASRs execute in the context of a task and may execute any - directive. - -- When an ISR is invoked, it is passed the vector number as its argument. When - an ASR is invoked, it is passed the signal set as its argument. - -- An ASR has a task mode which can be different from that of the task. An ISR - does not execute as a task and, as a result, does not have a task mode. - -.. index:: signal set, building - -Building a Signal Set ---------------------- - -A signal set is built by a bitwise OR of the desired signals. The set of valid -signals is ``RTEMS_SIGNAL_0`` through ``RTEMS_SIGNAL_31``. If a signal is not -explicitly specified in the signal set, then it is not present. Signal values -are specifically designed to be mutually exclusive, therefore bitwise OR and -addition operations are equivalent as long as each signal appears exactly once -in the component list. - -This example demonstrates the signal parameter used when sending the signal set -consisting of ``RTEMS_SIGNAL_6``, ``RTEMS_SIGNAL_15``, and ``RTEMS_SIGNAL_31``. -The signal parameter provided to the ``rtems_signal_send`` directive should be -``RTEMS_SIGNAL_6 | RTEMS_SIGNAL_15 | RTEMS_SIGNAL_31``. - -.. index:: ASR mode, building - -Building an ASR Mode --------------------- - -In general, an ASR's mode is built by a bitwise OR of the desired mode -components. The set of valid mode components is the same as those allowed with -the task_create and task_mode directives. A complete list of mode options is -provided in the following table: - -.. 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 - -Mode values are specifically designed to be mutually exclusive, therefore -bitwise OR and addition operations are equivalent as long as each mode appears -exactly once in the component list. A mode component listed as a default is -not required to appear in the mode list, although it is a good programming -practice to specify default components. If all defaults are desired, the mode -``DEFAULT_MODES`` should be specified on this call. - -This example demonstrates the mode parameter used with the -``rtems_signal_catch`` to establish an ASR which executes at interrupt level -three and is non-preemptible. The mode should be set to -``RTEMS_INTERRUPT_LEVEL(3) | RTEMS_NO_PREEMPT`` to indicate the desired -processor mode and interrupt level. - -Operations -========== - -Establishing an ASR -------------------- - -The ``rtems_signal_catch`` directive establishes an ASR for the calling task. -The address of the ASR and its execution mode are specified to this directive. -The ASR's mode is distinct from the task's mode. For example, the task may -allow preemption, while that task's ASR may have preemption disabled. Until a -task calls ``rtems_signal_catch`` the first time, its ASR is invalid, and no -signal sets can be sent to the task. - -A task may invalidate its ASR and discard all pending signals by calling -``rtems_signal_catch`` with a value of NULL for the ASR's address. When a -task's ASR is invalid, new signal sets sent to this task are discarded. - -A task may disable ASR processing (``RTEMS_NO_ASR``) via the task_mode -directive. When a task's ASR is disabled, the signals sent to it are left -pending to be processed later when the ASR is enabled. - -Any directive that can be called from a task can also be called from an ASR. A -task is only allowed one active ASR. Thus, each call to ``rtems_signal_catch`` -replaces the previous one. - -Normally, signal processing is disabled for the ASR's execution mode, but if -signal processing is enabled for the ASR, the ASR must be reentrant. - -Sending a Signal Set --------------------- - -The ``rtems_signal_send`` directive allows both tasks and ISRs to send signals -to a target task. The target task and a set of signals are specified to the -``rtems_signal_send`` directive. The sending of a signal to a task has no -effect on the execution state of that task. If the task is not the currently -running task, then the signals are left pending and processed by the task's ASR -the next time the task is dispatched to run. The ASR is executed immediately -before the task is dispatched. If the currently running task sends a signal to -itself or is sent a signal from an ISR, its ASR is immediately dispatched to -run provided signal processing is enabled. - -If an ASR with signals enabled is preempted by another task or an ISR and a new -signal set is sent, then a new copy of the ASR will be invoked, nesting the -preempted ASR. Upon completion of processing the new signal set, control will -return to the preempted ASR. In this situation, the ASR must be reentrant. - -Like events, identical signals sent to a task are not queued. In other words, -sending the same signal multiple times to a task (without any intermediate -signal processing occurring for the task), has the same result as sending that -signal to that task once. - -.. index:: rtems_asr - -Processing an ASR ------------------ - -Asynchronous signals were designed to provide the capability to generate -software interrupts. The processing of software interrupts parallels that of -hardware interrupts. As a result, the differences between the formats of ASRs -and ISRs is limited to the meaning of the single argument passed to an ASR. -The ASR should have the following calling sequence and adhere to C calling -conventions: - -.. code-block:: c - - rtems_asr user_routine( - rtems_signal_set signals - ); - -When the ASR returns to RTEMS the mode and execution path of the interrupted -task (or ASR) is restored to the context prior to entering the ASR. - -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. - -.. raw:: latex - - \clearpage - -.. 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 - -.. raw:: latex - - \clearpage - -.. 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. -- cgit v1.2.3