[ae68ff0] | 1 | @c |
---|
[1e524995] | 2 | @c COPYRIGHT (c) 1988-1998. |
---|
[ae68ff0] | 3 | @c On-Line Applications Research Corporation (OAR). |
---|
| 4 | @c All rights reserved. |
---|
| 5 | @c |
---|
[139b2e4a] | 6 | @c $Id$ |
---|
| 7 | @c |
---|
[ae68ff0] | 8 | |
---|
| 9 | @ifinfo |
---|
| 10 | @node Signal Manager, Signal Manager Introduction, EVENT_RECEIVE - Receive event condition, Top |
---|
| 11 | @end ifinfo |
---|
| 12 | @chapter Signal Manager |
---|
| 13 | @ifinfo |
---|
| 14 | @menu |
---|
| 15 | * Signal Manager Introduction:: |
---|
| 16 | * Signal Manager Background:: |
---|
| 17 | * Signal Manager Operations:: |
---|
| 18 | * Signal Manager Directives:: |
---|
| 19 | @end menu |
---|
| 20 | @end ifinfo |
---|
| 21 | |
---|
| 22 | @ifinfo |
---|
| 23 | @node Signal Manager Introduction, Signal Manager Background, Signal Manager, Signal Manager |
---|
| 24 | @end ifinfo |
---|
| 25 | @section Introduction |
---|
| 26 | |
---|
| 27 | The signal manager provides the capabilities required |
---|
| 28 | for asynchronous communication. The directives provided by the |
---|
| 29 | signal manager are: |
---|
| 30 | |
---|
| 31 | @itemize @bullet |
---|
| 32 | @item @code{signal_catch} - Establish an ASR |
---|
| 33 | @item @code{signal_send} - Send signal set to a task |
---|
| 34 | @end itemize |
---|
| 35 | |
---|
| 36 | @ifinfo |
---|
| 37 | @node Signal Manager Background, Signal Manager Definitions, Signal Manager Introduction, Signal Manager |
---|
| 38 | @end ifinfo |
---|
| 39 | @section Background |
---|
| 40 | @ifinfo |
---|
| 41 | @menu |
---|
| 42 | * Signal Manager Definitions:: |
---|
| 43 | * A Comparison of ASRs and ISRs:: |
---|
| 44 | * Building a Signal Set:: |
---|
| 45 | * Building an ASR's Mode:: |
---|
| 46 | @end menu |
---|
| 47 | @end ifinfo |
---|
| 48 | |
---|
| 49 | @ifinfo |
---|
| 50 | @node Signal Manager Definitions, A Comparison of ASRs and ISRs, Signal Manager Background, Signal Manager Background |
---|
| 51 | @end ifinfo |
---|
| 52 | @subsection Signal Manager Definitions |
---|
| 53 | |
---|
| 54 | The signal manager allows a task to optionally define |
---|
| 55 | an asynchronous signal routine (ASR). An ASR is to a task what |
---|
| 56 | an ISR is to an application's set of tasks. When the processor |
---|
| 57 | is interrupted, the execution of an application is also |
---|
| 58 | interrupted and an ISR is given control. Similarly, when a |
---|
| 59 | signal is sent to a task, that task's execution path will be |
---|
| 60 | "interrupted" by the ASR. Sending a signal to a task has no |
---|
| 61 | effect on the receiving task's current execution state. |
---|
| 62 | |
---|
| 63 | A signal flag is used by a task (or ISR) to inform |
---|
| 64 | another task of the occurrence of a significant situation. |
---|
| 65 | Thirty-two signal flags are associated with each task. A |
---|
| 66 | collection of one or more signals is referred to as a signal |
---|
| 67 | set. A signal set is posted when it is directed (or sent) to a |
---|
| 68 | task. A pending signal is a signal that has been sent to a task |
---|
| 69 | with a valid ASR, but has not been processed by that task's ASR. |
---|
| 70 | |
---|
| 71 | |
---|
| 72 | @ifinfo |
---|
| 73 | @node A Comparison of ASRs and ISRs, Building a Signal Set, Signal Manager Definitions, Signal Manager Background |
---|
| 74 | @end ifinfo |
---|
| 75 | @subsection A Comparison of ASRs and ISRs |
---|
| 76 | |
---|
| 77 | The format of an ASR is similar to that of an ISR |
---|
| 78 | with the following exceptions: |
---|
| 79 | |
---|
| 80 | @itemize @bullet |
---|
| 81 | @item ISRs are scheduled by the processor hardware. ASRs are |
---|
| 82 | scheduled by RTEMS. |
---|
| 83 | |
---|
| 84 | @item ISRs do not execute in the context of a task and may |
---|
| 85 | invoke only a subset of directives. ASRs execute in the context |
---|
| 86 | of a task and may execute any directive. |
---|
| 87 | |
---|
| 88 | @item When an ISR is invoked, it is passed the vector number |
---|
| 89 | as its argument. When an ASR is invoked, it is passed the |
---|
| 90 | signal set as its argument. |
---|
| 91 | |
---|
| 92 | @item An ASR has a task mode which can be different from that |
---|
| 93 | of the task. An ISR does not execute as a task and, as a |
---|
| 94 | result, does not have a task mode. |
---|
| 95 | @end itemize |
---|
| 96 | |
---|
| 97 | @ifinfo |
---|
| 98 | @node Building a Signal Set, Building an ASR's Mode, A Comparison of ASRs and ISRs, Signal Manager Background |
---|
| 99 | @end ifinfo |
---|
| 100 | @subsection Building a Signal Set |
---|
| 101 | |
---|
| 102 | A signal set is built by a bitwise OR of the desired |
---|
[a94c5a5d] | 103 | signals. The set of valid signals is @code{SIGNAL_0} through |
---|
| 104 | @code{SIGNAL_31}. If a signal is not explicitly specified in the |
---|
[ae68ff0] | 105 | signal set, then it is not present. Signal values are |
---|
| 106 | specifically designed to be mutually exclusive, therefore |
---|
| 107 | bitwise OR and addition operations are equivalent as long as |
---|
| 108 | each signal appears exactly once in the component list. |
---|
| 109 | |
---|
| 110 | This example demonstrates the signal parameter used |
---|
[a94c5a5d] | 111 | when sending the signal set consisting of |
---|
| 112 | @code{SIGNAL_6}, @code{SIGNAL_15}, and @code{SIGNAL_31}. |
---|
| 113 | The signal parameter provided to the signal_send directive should be |
---|
| 114 | @code{SIGNAL_6 @value{OR} SIGNAL_15 @value{OR} SIGNAL_31}. |
---|
[ae68ff0] | 115 | |
---|
| 116 | @ifinfo |
---|
| 117 | @node Building an ASR's Mode, Signal Manager Operations, Building a Signal Set, Signal Manager Background |
---|
| 118 | @end ifinfo |
---|
| 119 | @subsection Building an ASR's Mode |
---|
| 120 | |
---|
| 121 | In general, an ASR's mode is built by a bitwise OR of |
---|
| 122 | the desired mode components. The set of valid mode components |
---|
| 123 | is the same as those allowed with the task_create and task_mode |
---|
| 124 | directives. A complete list of mode options is provided in the |
---|
| 125 | following table: |
---|
| 126 | |
---|
| 127 | @itemize @bullet |
---|
| 128 | @item PREEMPT is masked by PREEMPT_MASK and enables preemption |
---|
| 129 | @item NO_PREEMPT is masked by PREEMPT_MASK and disables preemption |
---|
| 130 | @item NO_TIMESLICE is masked by TIMESLICE_MASK and disables timeslicing |
---|
| 131 | @item TIMESLICE is masked by TIMESLICE_MASK and enables timeslicing |
---|
| 132 | @item ASR is masked by ASR_MASK and enables ASR processing |
---|
| 133 | @item NO_ASR is masked by ASR_MASK and disables ASR processing |
---|
| 134 | @item INTERRUPT_LEVEL(0) is masked by INTERRUPT_MASK and enables all interrupts |
---|
| 135 | @item INTERRUPT_LEVEL(n) is masked by INTERRUPT_MASK and sets interrupts level n |
---|
| 136 | @end itemize |
---|
| 137 | |
---|
| 138 | Mode values are specifically designed to be mutually |
---|
| 139 | exclusive, therefore bitwise OR and addition operations are |
---|
| 140 | equivalent as long as each mode appears exactly once in the |
---|
| 141 | component list. A mode component listed as a default is not |
---|
| 142 | required to appear in the mode list, although it is a good |
---|
| 143 | programming practice to specify default components. If all |
---|
| 144 | defaults are desired, the mode DEFAULT_MODES should be specified |
---|
| 145 | on this call. |
---|
| 146 | |
---|
| 147 | This example demonstrates the mode parameter used |
---|
| 148 | with the signal_catch to establish an ASR which executes at |
---|
| 149 | interrupt level three and is non-preemptible. The mode should |
---|
[a94c5a5d] | 150 | be set to |
---|
| 151 | @code{INTERRUPT_LEVEL(3) @value{OR} NO_PREEMPT} to indicate the |
---|
[ae68ff0] | 152 | desired processor mode and interrupt level. |
---|
| 153 | |
---|
| 154 | @ifinfo |
---|
| 155 | @node Signal Manager Operations, Establishing an ASR, Building an ASR's Mode, Signal Manager |
---|
| 156 | @end ifinfo |
---|
| 157 | @section Operations |
---|
| 158 | @ifinfo |
---|
| 159 | @menu |
---|
| 160 | * Establishing an ASR:: |
---|
| 161 | * Sending a Signal Set:: |
---|
| 162 | * Processing an ASR:: |
---|
| 163 | @end menu |
---|
| 164 | @end ifinfo |
---|
| 165 | |
---|
| 166 | @ifinfo |
---|
| 167 | @node Establishing an ASR, Sending a Signal Set, Signal Manager Operations, Signal Manager Operations |
---|
| 168 | @end ifinfo |
---|
| 169 | @subsection Establishing an ASR |
---|
| 170 | |
---|
| 171 | The signal_catch directive establishes an ASR for the |
---|
| 172 | calling task. The address of the ASR and its execution mode are |
---|
| 173 | specified to this directive. The ASR's mode is distinct from |
---|
| 174 | the task's mode. For example, the task may allow preemption, |
---|
| 175 | while that task's ASR may have preemption disabled. Until a |
---|
| 176 | task calls signal_catch the first time, its ASR is invalid, and |
---|
| 177 | no signal sets can be sent to the task. |
---|
| 178 | |
---|
| 179 | A task may invalidate its ASR and discard all pending |
---|
| 180 | signals by calling signal_catch with a value of NULL for the |
---|
| 181 | ASR's address. When a task's ASR is invalid, new signal sets |
---|
| 182 | sent to this task are discarded. |
---|
| 183 | |
---|
| 184 | A task may disable ASR processing (NO_ASR) via the |
---|
| 185 | task_mode directive. When a task's ASR is disabled, the signals |
---|
| 186 | sent to it are left pending to be processed later when the ASR |
---|
| 187 | is enabled. |
---|
| 188 | |
---|
| 189 | Any directive that can be called from a task can also |
---|
| 190 | be called from an ASR. A task is only allowed one active ASR. |
---|
| 191 | Thus, each call to signal_catch replaces the previous one. |
---|
| 192 | |
---|
| 193 | Normally, signal processing is disabled for the ASR's |
---|
| 194 | execution mode, but if signal processing is enabled for the ASR, |
---|
| 195 | the ASR must be reentrant. |
---|
| 196 | |
---|
| 197 | @ifinfo |
---|
| 198 | @node Sending a Signal Set, Processing an ASR, Establishing an ASR, Signal Manager Operations |
---|
| 199 | @end ifinfo |
---|
| 200 | @subsection Sending a Signal Set |
---|
| 201 | |
---|
| 202 | The signal_send directive allows both tasks and ISRs |
---|
| 203 | to send signals to a target task. The target task and a set of |
---|
| 204 | signals are specified to the signal_send directive. The sending |
---|
| 205 | of a signal to a task has no effect on the execution state of |
---|
| 206 | that task. If the task is not the currently running task, then |
---|
| 207 | the signals are left pending and processed by the task's ASR the |
---|
| 208 | next time the task is dispatched to run. The ASR is executed |
---|
| 209 | immediately before the task is dispatched. If the currently |
---|
| 210 | running task sends a signal to itself or is sent a signal from |
---|
| 211 | an ISR, its ASR is immediately dispatched to run provided signal |
---|
| 212 | processing is enabled. |
---|
| 213 | |
---|
| 214 | If an ASR with signals enabled is preempted by |
---|
| 215 | another task or an ISR and a new signal set is sent, then a new |
---|
| 216 | copy of the ASR will be invoked, nesting the preempted ASR. |
---|
| 217 | Upon completion of processing the new signal set, control will |
---|
| 218 | return to the preempted ASR. In this situation, the ASR must be |
---|
| 219 | reentrant. |
---|
| 220 | |
---|
| 221 | Like events, identical signals sent to a task are not |
---|
| 222 | queued. In other words, sending the same signal multiple times |
---|
| 223 | to a task (without any intermediate signal processing occurring |
---|
| 224 | for the task), has the same result as sending that signal to |
---|
| 225 | that task once. |
---|
| 226 | |
---|
| 227 | @ifinfo |
---|
| 228 | @node Processing an ASR, Signal Manager Directives, Sending a Signal Set, Signal Manager Operations |
---|
| 229 | @end ifinfo |
---|
| 230 | @subsection Processing an ASR |
---|
| 231 | |
---|
| 232 | Asynchronous signals were designed to provide the |
---|
| 233 | capability to generate software interrupts. The processing of |
---|
| 234 | software interrupts parallels that of hardware interrupts. As a |
---|
| 235 | result, the differences between the formats of ASRs and ISRs is |
---|
| 236 | limited to the meaning of the single argument passed to an ASR. |
---|
| 237 | The ASR should have the following calling sequence and adhere to |
---|
[a94c5a5d] | 238 | @value{LANGUAGE} calling conventions: |
---|
[ae68ff0] | 239 | |
---|
[61389eac] | 240 | @ifset is-C |
---|
[ae68ff0] | 241 | @example |
---|
| 242 | rtems_asr user_routine( |
---|
| 243 | rtems_signal_set signals |
---|
| 244 | ); |
---|
| 245 | @end example |
---|
[61389eac] | 246 | @end ifset |
---|
| 247 | |
---|
| 248 | @ifset is-Ada |
---|
| 249 | @example |
---|
| 250 | procedure User_Routine ( |
---|
| 251 | Signals : in RTEMS.Signal_Set |
---|
| 252 | ); |
---|
| 253 | @end example |
---|
| 254 | @end ifset |
---|
[ae68ff0] | 255 | |
---|
| 256 | When the ASR returns to RTEMS the mode and execution |
---|
| 257 | path of the interrupted task (or ASR) is restored to the context |
---|
| 258 | prior to entering the ASR. |
---|
| 259 | |
---|
| 260 | @ifinfo |
---|
| 261 | @node Signal Manager Directives, SIGNAL_CATCH - Establish an ASR, Processing an ASR, Signal Manager |
---|
| 262 | @end ifinfo |
---|
| 263 | @section Directives |
---|
| 264 | @ifinfo |
---|
| 265 | @menu |
---|
| 266 | * SIGNAL_CATCH - Establish an ASR:: |
---|
| 267 | * SIGNAL_SEND - Send signal set to a task:: |
---|
| 268 | @end menu |
---|
| 269 | @end ifinfo |
---|
| 270 | |
---|
| 271 | This section details the signal manager's directives. |
---|
| 272 | A subsection is dedicated to each of this manager's directives |
---|
| 273 | and describes the calling sequence, related constants, usage, |
---|
| 274 | and status codes. |
---|
| 275 | |
---|
| 276 | @page |
---|
| 277 | @ifinfo |
---|
| 278 | @node SIGNAL_CATCH - Establish an ASR, SIGNAL_SEND - Send signal set to a task, Signal Manager Directives, Signal Manager Directives |
---|
| 279 | @end ifinfo |
---|
| 280 | @subsection SIGNAL_CATCH - Establish an ASR |
---|
| 281 | |
---|
| 282 | @subheading CALLING SEQUENCE: |
---|
| 283 | |
---|
[61389eac] | 284 | @ifset is-C |
---|
[ae68ff0] | 285 | @example |
---|
| 286 | rtems_status_code rtems_signal_catch( |
---|
| 287 | rtems_asr_entry asr_handler, |
---|
| 288 | rtems_mode mode |
---|
| 289 | ); |
---|
| 290 | @end example |
---|
[61389eac] | 291 | @end ifset |
---|
| 292 | |
---|
| 293 | @ifset is-Ada |
---|
| 294 | @example |
---|
| 295 | procedure Signal_Catch ( |
---|
| 296 | ASR_Handler : in RTEMS.ASR_Handler; |
---|
| 297 | Mode_Set : in RTEMS.Mode; |
---|
| 298 | Result : out RTEMS.Status_Codes |
---|
| 299 | ); |
---|
| 300 | @end example |
---|
| 301 | @end ifset |
---|
[ae68ff0] | 302 | |
---|
| 303 | @subheading DIRECTIVE STATUS CODES: |
---|
| 304 | @code{SUCCESSFUL} - always successful |
---|
| 305 | |
---|
| 306 | @subheading DESCRIPTION: |
---|
| 307 | |
---|
| 308 | This directive establishes an asynchronous signal |
---|
| 309 | routine (ASR) for the calling task. The asr_handler parameter |
---|
| 310 | specifies the entry point of the ASR. If asr_handler is NULL, |
---|
| 311 | the ASR for the calling task is invalidated and all pending |
---|
| 312 | signals are cleared. Any signals sent to a task with an invalid |
---|
| 313 | ASR are discarded. The mode parameter specifies the execution |
---|
| 314 | mode for the ASR. This execution mode supersedes the task's |
---|
| 315 | execution mode while the ASR is executing. |
---|
| 316 | |
---|
| 317 | @subheading NOTES: |
---|
| 318 | |
---|
| 319 | This directive will not cause the calling task to be |
---|
| 320 | preempted. |
---|
| 321 | |
---|
| 322 | The following task mode constants are defined by RTEMS: |
---|
| 323 | |
---|
| 324 | @itemize @bullet |
---|
| 325 | @item PREEMPT is masked by PREEMPT_MASK and enables preemption |
---|
| 326 | @item NO_PREEMPT is masked by PREEMPT_MASK and disables preemption |
---|
| 327 | @item NO_TIMESLICE is masked by TIMESLICE_MASK and disables timeslicing |
---|
| 328 | @item TIMESLICE is masked by TIMESLICE_MASK and enables timeslicing |
---|
| 329 | @item ASR is masked by ASR_MASK and enables ASR processing |
---|
| 330 | @item NO_ASR is masked by ASR_MASK and disables ASR processing |
---|
| 331 | @item INTERRUPT_LEVEL(0) is masked by INTERRUPT_MASK and enables all interrupts |
---|
| 332 | @item INTERRUPT_LEVEL(n) is masked by INTERRUPT_MASK and sets interrupts level n |
---|
| 333 | @end itemize |
---|
| 334 | |
---|
| 335 | @page |
---|
| 336 | @ifinfo |
---|
| 337 | @node SIGNAL_SEND - Send signal set to a task, Partition Manager, SIGNAL_CATCH - Establish an ASR, Signal Manager Directives |
---|
| 338 | @end ifinfo |
---|
| 339 | @subsection SIGNAL_SEND - Send signal set to a task |
---|
| 340 | |
---|
| 341 | @subheading CALLING SEQUENCE: |
---|
| 342 | |
---|
[61389eac] | 343 | @ifset is-C |
---|
[ae68ff0] | 344 | @example |
---|
| 345 | rtems_status_code rtems_signal_send( |
---|
| 346 | rtems_id id, |
---|
| 347 | rtems_signal_set signal_set |
---|
| 348 | ); |
---|
| 349 | @end example |
---|
[61389eac] | 350 | @end ifset |
---|
| 351 | |
---|
| 352 | @ifset is-Ada |
---|
| 353 | @example |
---|
| 354 | procedure Signal_Send ( |
---|
| 355 | ID : in RTEMS.ID; |
---|
| 356 | Signal_Set : in RTEMS.Signal_Set; |
---|
| 357 | Result : out RTEMS.Status_Codes |
---|
| 358 | ); |
---|
| 359 | @end example |
---|
| 360 | @end ifset |
---|
[ae68ff0] | 361 | |
---|
| 362 | @subheading DIRECTIVE STATUS CODES: |
---|
| 363 | @code{SUCCESSFUL} - signal sent successfully@* |
---|
| 364 | @code{INVALID_ID} - task id invalid@* |
---|
| 365 | @code{NOT_DEFINED} - ASR invalid |
---|
| 366 | |
---|
| 367 | @subheading DESCRIPTION: |
---|
| 368 | |
---|
| 369 | This directive sends a signal set to the task |
---|
| 370 | specified in id. The signal_set parameter contains the signal |
---|
| 371 | set to be sent to the task. |
---|
| 372 | |
---|
| 373 | If a caller sends a signal set to a task with an |
---|
| 374 | invalid ASR, then an error code is returned to the caller. If a |
---|
| 375 | caller sends a signal set to a task whose ASR is valid but |
---|
| 376 | disabled, then the signal set will be caught and left pending |
---|
| 377 | for the ASR to process when it is enabled. If a caller sends a |
---|
| 378 | signal set to a task with an ASR that is both valid and enabled, |
---|
| 379 | then the signal set is caught and the ASR will execute the next |
---|
| 380 | time the task is dispatched to run. |
---|
| 381 | |
---|
| 382 | @subheading NOTES: |
---|
| 383 | |
---|
| 384 | Sending a signal set to a task has no effect on that |
---|
| 385 | task's state. If a signal set is sent to a blocked task, then |
---|
| 386 | the task will remain blocked and the signals will be processed |
---|
| 387 | when the task becomes the running task. |
---|
| 388 | |
---|
| 389 | Sending a signal set to a global task which does not |
---|
| 390 | reside on the local node will generate a request telling the |
---|
| 391 | remote node to send the signal set to the specified task. |
---|
| 392 | |
---|