summaryrefslogtreecommitdiffstats
path: root/doc/user/signal.t
diff options
context:
space:
mode:
authorJoel Sherrill <joel@rtems.org>2016-11-15 10:37:59 -0600
committerJoel Sherrill <joel@rtems.org>2017-01-11 12:13:21 -0600
commit48a7fa31f918a6fc88719b3c9393a9ba2829f42a (patch)
tree10bf638de133099fcabe5fe713ca98a546a27ab2 /doc/user/signal.t
parent7a4b264574ce81d5473de6d15950464ea2cff485 (diff)
downloadrtems-48a7fa31f918a6fc88719b3c9393a9ba2829f42a.tar.bz2
Remove texinfo format documentation. Replaced by Sphinx formatted documentation.
closes #2812.
Diffstat (limited to 'doc/user/signal.t')
-rw-r--r--doc/user/signal.t387
1 files changed, 0 insertions, 387 deletions
diff --git a/doc/user/signal.t b/doc/user/signal.t
deleted file mode 100644
index cca162b1e3..0000000000
--- a/doc/user/signal.t
+++ /dev/null
@@ -1,387 +0,0 @@
-@c
-@c COPYRIGHT (c) 1988-2002.
-@c On-Line Applications Research Corporation (OAR).
-@c All rights reserved.
-
-@chapter Signal Manager
-
-@cindex signals
-
-@section Introduction
-
-The signal manager provides the capabilities required
-for asynchronous communication. The directives provided by the
-signal manager are:
-
-@itemize @bullet
-@item @code{@value{DIRPREFIX}signal_catch} - Establish an ASR
-@item @code{@value{DIRPREFIX}signal_send} - Send signal set to a task
-@end itemize
-
-@section Background
-
-@subsection Signal Manager Definitions
-
-@cindex asynchronous signal routine
-@cindex ASR
-
-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.
-
-@findex 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 @code{@value{DIRPREFIX}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.
-
-
-@subsection A Comparison of ASRs and ISRs
-
-@cindex ASR vs. ISR
-@cindex ISR vs. ASR
-
-The format of an ASR is similar to that of an ISR
-with the following exceptions:
-
-@itemize @bullet
-@item ISRs are scheduled by the processor hardware. ASRs are
-scheduled by RTEMS.
-
-@item 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.
-
-@item 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.
-
-@item 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.
-@end itemize
-
-@subsection Building a Signal Set
-
-@cindex signal set, building
-
-A signal set is built by a bitwise OR of the desired
-signals. The set of valid signals is @code{@value{RPREFIX}SIGNAL_0} through
-@code{@value{RPREFIX}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
-@code{@value{RPREFIX}SIGNAL_6},
-@code{@value{RPREFIX}SIGNAL_15}, and
-@code{@value{RPREFIX}SIGNAL_31}. The signal parameter provided
-to the @code{@value{DIRPREFIX}signal_send} directive should be
-@code{@value{RPREFIX}SIGNAL_6 @value{OR}
-@value{RPREFIX}SIGNAL_15 @value{OR} @value{RPREFIX}SIGNAL_31}.
-
-@subsection Building an ASR Mode
-
-@cindex ASR mode, building
-
-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:
-
-@itemize @bullet
-@item @code{@value{RPREFIX}PREEMPT} is masked by
-@code{@value{RPREFIX}PREEMPT_MASK} and enables preemption
-
-@item @code{@value{RPREFIX}NO_PREEMPT} is masked by
-@code{@value{RPREFIX}PREEMPT_MASK} and disables preemption
-
-@item @code{@value{RPREFIX}NO_TIMESLICE} is masked by
-@code{@value{RPREFIX}TIMESLICE_MASK} and disables timeslicing
-
-@item @code{@value{RPREFIX}TIMESLICE} is masked by
-@code{@value{RPREFIX}TIMESLICE_MASK} and enables timeslicing
-
-@item @code{@value{RPREFIX}ASR} is masked by
-@code{@value{RPREFIX}ASR_MASK} and enables ASR processing
-
-@item @code{@value{RPREFIX}NO_ASR} is masked by
-@code{@value{RPREFIX}ASR_MASK} and disables ASR processing
-
-@item @code{@value{RPREFIX}INTERRUPT_LEVEL(0)} is masked by
-@code{@value{RPREFIX}INTERRUPT_MASK} and enables all interrupts
-
-@item @code{@value{RPREFIX}INTERRUPT_LEVEL(n)} is masked by
-@code{@value{RPREFIX}INTERRUPT_MASK} and sets interrupts level n
-@end itemize
-
-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 @code{@value{DIRPREFIX}signal_catch}
-to establish an ASR which executes at
-interrupt level three and is non-preemptible. The mode should
-be set to
-@code{@value{RPREFIX}INTERRUPT_LEVEL(3) @value{OR} @value{RPREFIX}NO_PREEMPT}
-to indicate the
-desired processor mode and interrupt level.
-
-@section Operations
-
-@subsection Establishing an ASR
-
-The @code{@value{DIRPREFIX}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 @code{@value{DIRPREFIX}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 @code{@value{DIRPREFIX}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 (@code{@value{RPREFIX}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 @code{@value{DIRPREFIX}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.
-
-@subsection Sending a Signal Set
-
-The @code{@value{DIRPREFIX}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
-@code{@value{DIRPREFIX}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.
-
-@subsection 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
-@value{LANGUAGE} calling conventions:
-
-@ifset is-C
-@findex rtems_asr
-@example
-rtems_asr user_routine(
- rtems_signal_set signals
-);
-@end example
-@end ifset
-
-@ifset is-Ada
-@example
-procedure User_Routine (
- Signals : in RTEMS.Signal_Set
-);
-@end example
-@end ifset
-
-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.
-
-@section 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.
-
-@c
-@c
-@c
-@page
-@subsection SIGNAL_CATCH - Establish an ASR
-
-@cindex establish an ASR
-@cindex install an ASR
-
-@subheading CALLING SEQUENCE:
-
-@ifset is-C
-@findex rtems_signal_catch
-@example
-rtems_status_code rtems_signal_catch(
- rtems_asr_entry asr_handler,
- rtems_mode mode
-);
-@end example
-@end ifset
-
-@ifset is-Ada
-@example
-procedure Signal_Catch (
- ASR_Handler : in RTEMS.ASR_Handler;
- Mode_Set : in RTEMS.Mode;
- Result : out RTEMS.Status_Codes
-);
-@end example
-@end ifset
-
-@subheading DIRECTIVE STATUS CODES:
-@code{@value{RPREFIX}SUCCESSFUL} - always successful
-
-@subheading 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.
-
-@subheading NOTES:
-
-This directive will not cause the calling task to be
-preempted.
-
-The following task mode constants are defined by RTEMS:
-
-@itemize @bullet
-@item @code{@value{RPREFIX}PREEMPT} is masked by
-@code{@value{RPREFIX}PREEMPT_MASK} and enables preemption
-
-@item @code{@value{RPREFIX}NO_PREEMPT} is masked by
-@code{@value{RPREFIX}PREEMPT_MASK} and disables preemption
-
-@item @code{@value{RPREFIX}NO_TIMESLICE} is masked by
-@code{@value{RPREFIX}TIMESLICE_MASK} and disables timeslicing
-
-@item @code{@value{RPREFIX}TIMESLICE} is masked by
-@code{@value{RPREFIX}TIMESLICE_MASK} and enables timeslicing
-
-@item @code{@value{RPREFIX}ASR} is masked by
-@code{@value{RPREFIX}ASR_MASK} and enables ASR processing
-
-@item @code{@value{RPREFIX}NO_ASR} is masked by
-@code{@value{RPREFIX}ASR_MASK} and disables ASR processing
-
-@item @code{@value{RPREFIX}INTERRUPT_LEVEL(0)} is masked by
-@code{@value{RPREFIX}INTERRUPT_MASK} and enables all interrupts
-
-@item @code{@value{RPREFIX}INTERRUPT_LEVEL(n)} is masked by
-@code{@value{RPREFIX}INTERRUPT_MASK} and sets interrupts level n
-@end itemize
-
-@c
-@c
-@c
-@page
-@subsection SIGNAL_SEND - Send signal set to a task
-
-@cindex send signal set
-
-@subheading CALLING SEQUENCE:
-
-@ifset is-C
-@findex rtems_signal_send
-@example
-rtems_status_code rtems_signal_send(
- rtems_id id,
- rtems_signal_set signal_set
-);
-@end example
-@end ifset
-
-@ifset is-Ada
-@example
-procedure Signal_Send (
- ID : in RTEMS.ID;
- Signal_Set : in RTEMS.Signal_Set;
- Result : out RTEMS.Status_Codes
-);
-@end example
-@end ifset
-
-@subheading DIRECTIVE STATUS CODES:
-@code{@value{RPREFIX}SUCCESSFUL} - signal sent successfully@*
-@code{@value{RPREFIX}INVALID_ID} - task id invalid@*
-@code{@value{RPREFIX}INVALID_NUMBER} - empty signal set@*
-@code{@value{RPREFIX}NOT_DEFINED} - ASR invalid
-
-@subheading 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.
-
-@subheading 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.
-