[1baa059] | 1 | @c |
---|
[086a898a] | 2 | @c COPYRIGHT (c) 1988-1999. |
---|
| 3 | @c On-Line Applications Research Corporation (OAR). |
---|
| 4 | @c All rights reserved. |
---|
| 5 | @c |
---|
[1baa059] | 6 | @c This is the chapter from the RTEMS ITRON User's Guide that |
---|
| 7 | @c documents the services provided by the eventflags |
---|
| 8 | @c manager. |
---|
| 9 | @c |
---|
| 10 | @c $Id$ |
---|
| 11 | @c |
---|
| 12 | |
---|
| 13 | @chapter Eventflags Manager |
---|
| 14 | |
---|
| 15 | @section Introduction |
---|
| 16 | |
---|
| 17 | The eventflag manager provides a high performance method of intertask communication and synchronization. The directives provided by the eventflag manager are: |
---|
| 18 | |
---|
| 19 | The services provided by the eventflags manager are: |
---|
| 20 | |
---|
| 21 | @itemize @bullet |
---|
| 22 | @item @code{cre_flg} - Create Eventflag |
---|
| 23 | @item @code{del_flg} - Delete Eventflag |
---|
| 24 | @item @code{set_flg} - Set Eventflag |
---|
| 25 | @item @code{clr_flg} - Clear Eventflag |
---|
| 26 | @item @code{wai_flg} - Wait on Eventflag |
---|
[a5f5acad] | 27 | @item @code{pol_flg} - Wait for Eventflag (Polling) |
---|
[1baa059] | 28 | @item @code{twai_flg} - Wait on Eventflag with Timeout |
---|
| 29 | @item @code{ref_flg} - Reference Eventflag Status |
---|
| 30 | @end itemize |
---|
| 31 | |
---|
| 32 | @section Background |
---|
| 33 | |
---|
| 34 | @subsection Event sets |
---|
| 35 | |
---|
| 36 | An eventflag is used by a task (or ISR) to inform another task of the |
---|
[a5f5acad] | 37 | occurrence of a significant situation. One word bit-field is associated with each eventflags. The application developer should remember the |
---|
[1baa059] | 38 | following key characteristics of event operations when utilizing the event |
---|
| 39 | manager: |
---|
| 40 | |
---|
| 41 | @itemize @bullet |
---|
| 42 | @item Events provide a simple synchronization facility. |
---|
| 43 | @item Events are aimed at tasks. |
---|
| 44 | @item Tasks can wait on more than one event simultaneously. |
---|
| 45 | @item Events are independent of one another. |
---|
| 46 | @item Events do not hold or transport data. |
---|
| 47 | @item Events are not queued. In other words, if an event is sent more than once to a task before being received, the second and subsequent send operations to that same task have no effect. |
---|
| 48 | @end itemize |
---|
| 49 | |
---|
[a5f5acad] | 50 | A pending event is an event that has been set. An |
---|
[1baa059] | 51 | event condition is used to specify the events which the task desires to |
---|
| 52 | receive and the algorithm which will be used to determine when the request |
---|
| 53 | is satisfied. An event condition is satisfied based upon one of two |
---|
| 54 | algorithms which are selected by the user. The @code{TWF_ORW} algorithm |
---|
| 55 | states that an event condition is satisfied when at least a single |
---|
| 56 | requested event is posted. The @code{TWF_ANDW} algorithm states that an |
---|
| 57 | event condition is satisfied when every requested event is posted. |
---|
| 58 | |
---|
[a5f5acad] | 59 | An eventflags or condition is built by a bitwise OR of the desired events. |
---|
[1baa059] | 60 | If an event is not explicitly specified in the set or condition, then it |
---|
| 61 | is not present. Events are specifically designed to be mutually exclusive, |
---|
| 62 | therefore bitwise OR and addition operations are equivalent as long as |
---|
| 63 | each event appears exactly once in the event set list. |
---|
| 64 | |
---|
| 65 | @subsection T_CFLG Structure |
---|
| 66 | |
---|
| 67 | The T_CFLG structire is used to define the characteristics of an eventflag |
---|
| 68 | and passed as an argument to the @code{cre_flg} service. The structure is |
---|
| 69 | defined as follows: |
---|
| 70 | |
---|
| 71 | @example |
---|
| 72 | |
---|
| 73 | /* |
---|
| 74 | * Create Eventflags (cre_flg) Structure |
---|
| 75 | */ |
---|
| 76 | |
---|
| 77 | typedef struct t_cflg @{ |
---|
| 78 | VP exinf; /* extended information */ |
---|
| 79 | ATR flgatr; /* eventflag attribute */ |
---|
| 80 | UINT iflgptn; /* initial eventflag */ |
---|
| 81 | /* additional implementation dependent information may be included */ |
---|
| 82 | @} T_CFLG; |
---|
| 83 | |
---|
| 84 | /* |
---|
| 85 | * flgatr - Eventflag Attribute Values |
---|
| 86 | */ |
---|
| 87 | |
---|
| 88 | |
---|
| 89 | /* multiple tasks are not allowed to wait (Wait Single Task)*/ |
---|
| 90 | |
---|
| 91 | #define TA_WSGL 0x00 |
---|
| 92 | |
---|
| 93 | /* multiple tasks are allowed to wait (Wait Multiple Task) */ |
---|
| 94 | |
---|
| 95 | #define TA_WMUL 0x08 |
---|
| 96 | |
---|
| 97 | /* wfmode */ |
---|
| 98 | #define TWF_ANDW 0x00 /* AND wait */ |
---|
| 99 | #define TWF_ORW 0x02 /* OR wait */ |
---|
| 100 | #define TWF_CLR 0x01 /* clear specification */ |
---|
| 101 | @end example |
---|
| 102 | |
---|
| 103 | where the meaning of each field is: |
---|
| 104 | |
---|
| 105 | @table @b |
---|
| 106 | |
---|
| 107 | @item exinf |
---|
| 108 | |
---|
| 109 | may be used freely by the user for including extended information about |
---|
| 110 | the eventflag to be created. Information set here may be accessed by |
---|
[a5f5acad] | 111 | @code{ref_flg}. If a larger region is desired for including user information, or |
---|
[1baa059] | 112 | if the user wishes to change the contents of this information, the usr |
---|
| 113 | should allocate memory area and set the address of this memory packet to |
---|
[a5f5acad] | 114 | @code{exinf}. The OS does not take care of the contents of @code{exinf}. This |
---|
[1baa059] | 115 | implementation does not use this field. |
---|
| 116 | |
---|
| 117 | @item flgatr |
---|
| 118 | |
---|
| 119 | is the attributes for this eventflag. The lower bits of flgatr represent |
---|
| 120 | system attributes, while the upper bits represent implementation-dependent |
---|
| 121 | attributes. |
---|
| 122 | |
---|
| 123 | @item iflgptn |
---|
| 124 | |
---|
| 125 | is the initial eventflag pattern. |
---|
| 126 | (CPU and/or implementation-dependent information may also be included) |
---|
| 127 | |
---|
| 128 | @end table |
---|
| 129 | |
---|
| 130 | @subsection T_RFLG Structure |
---|
| 131 | |
---|
| 132 | The T_RFLG structire is used to define the characteristics of an eventflag |
---|
| 133 | and passed as an argument to the @code{ref_flg} service. The structure is |
---|
| 134 | defined as follows: |
---|
| 135 | |
---|
| 136 | @example |
---|
| 137 | /* Reference Eventflags (ref_flg) Structure */ |
---|
| 138 | typedef struct t_rflg @{ |
---|
[a5f5acad] | 139 | VP exinf; /* extended information */ |
---|
| 140 | BOOL_ID wtsk; /* indicates whether or not there is a waiting task */ |
---|
[1baa059] | 141 | UINT flgptn; /* eventflag bit pattern */ |
---|
| 142 | /* additional implementation dependent information may be included */ |
---|
| 143 | @} T_RFLG; |
---|
| 144 | @end example |
---|
| 145 | |
---|
| 146 | @table @b |
---|
| 147 | |
---|
| 148 | @item exinf |
---|
| 149 | |
---|
| 150 | see @code{T_CFLG}. |
---|
| 151 | |
---|
| 152 | @item wtsk |
---|
| 153 | |
---|
| 154 | indicates whether or not there is a task waiting for the eventflag in |
---|
[a5f5acad] | 155 | question. If there is no waiting task, @code{wtsk} is returned as FALSE = 0. |
---|
| 156 | If there is a waiting task, @code{wtsk} is returned as a value other than 0. |
---|
[1baa059] | 157 | |
---|
| 158 | @item flgptn |
---|
| 159 | |
---|
| 160 | is the eventflag pattern. |
---|
| 161 | |
---|
| 162 | @end table |
---|
| 163 | |
---|
| 164 | @section Operations |
---|
| 165 | |
---|
| 166 | @section System Calls |
---|
| 167 | |
---|
| 168 | This section details the eventflags manager's services. A subsection is |
---|
| 169 | dedicated to each of this manager's services and describes the calling |
---|
| 170 | sequence, related constants, usage, and status codes. |
---|
| 171 | |
---|
| 172 | |
---|
| 173 | @c |
---|
| 174 | @c cre_flg |
---|
| 175 | @c |
---|
| 176 | |
---|
| 177 | @page |
---|
| 178 | @subsection cre_flg - Create Eventflag |
---|
| 179 | |
---|
| 180 | @subheading CALLING SEQUENCE: |
---|
| 181 | |
---|
| 182 | @ifset is-C |
---|
| 183 | @example |
---|
| 184 | ER cre_flg( |
---|
| 185 | ID flgid, |
---|
| 186 | T_CFLG *pk_cflg |
---|
| 187 | ); |
---|
| 188 | @end example |
---|
| 189 | @end ifset |
---|
| 190 | |
---|
| 191 | @ifset is-Ada |
---|
| 192 | @end ifset |
---|
| 193 | |
---|
| 194 | @subheading STATUS CODES: |
---|
| 195 | |
---|
| 196 | @code{E_OK} - Normal Completion |
---|
| 197 | |
---|
| 198 | @code{E_NOMEM} - Insufficient memory (Memory for control block cannot be |
---|
| 199 | allocated) |
---|
| 200 | |
---|
| 201 | @code{E_ID} - Invalid ID number (flgid was invalid or could not be used) |
---|
| 202 | |
---|
| 203 | @code{E_RSATR} - Reserved attribute (flgatr was invalid or could not be |
---|
| 204 | used) |
---|
| 205 | |
---|
| 206 | @code{E_OBJ} - Invalid object state (an eventflag of the same ID already |
---|
| 207 | exists) |
---|
| 208 | |
---|
| 209 | @code{E_OACV} - Object access violation (A flgid less than -4 was |
---|
| 210 | specified from a user task. This is implementation dependent.) |
---|
| 211 | |
---|
| 212 | @code{E_PAR} - Parameter error (pk_cflg is invalid) |
---|
| 213 | |
---|
| 214 | @code{EN_OBJNO} - An object number which could not be accessed on the |
---|
| 215 | target node is specified. |
---|
| 216 | |
---|
| 217 | @code{EN_CTXID} - Specified an object on another node when the system call |
---|
| 218 | was issued from a task in dispatch disabled state or from a |
---|
| 219 | task-independent portion |
---|
| 220 | |
---|
| 221 | @code{EN_PAR}- A value outside the range supported by the target node |
---|
| 222 | and/or transmission packet format was specified as a parameter (a value |
---|
| 223 | outside supported range was specified for exinf, flgatr and/or iflgptn) |
---|
| 224 | |
---|
| 225 | @subheading DESCRIPTION: |
---|
| 226 | |
---|
| 227 | This system call creates the eventflag specified by @code{flgid}. |
---|
| 228 | Specifically, a control block for the eventflag to be created is allocated |
---|
| 229 | and the associated flag pattern is initialized using @code{iflgptn}. A |
---|
| 230 | single eventflag handles one word's worth of bits of the processor in |
---|
| 231 | question as a group. All operations are done in single word units. |
---|
| 232 | |
---|
| 233 | User eventflags have positive ID numbers, while system eventflags have |
---|
| 234 | negative ID numbers. User tasks (tasks having positive task IDs) cannot |
---|
| 235 | access system eventflags. An @code{E_OACV} error will result if a user |
---|
| 236 | task issues a system call on a system eventflag, but error detection is |
---|
| 237 | implementation dependent. |
---|
| 238 | |
---|
| 239 | Eventflags having ID numbers from -4 through 0 cannot be created. An |
---|
| 240 | @code{E_ID} error will result if a value in this range is specified for |
---|
| 241 | @code{flgid}. |
---|
| 242 | |
---|
| 243 | The system attribute part of @code{flgatr} may be specified as @code{TA_WSGL} |
---|
| 244 | (Wait Single Task) or @code{TA_WMUL} (Wait Multiple Tasks) |
---|
| 245 | |
---|
| 246 | @subheading NOTES: |
---|
| 247 | |
---|
| 248 | Multiprocessing is not supported. Thus none of the "@code{EN_}" status |
---|
| 249 | codes will be returned. |
---|
| 250 | |
---|
| 251 | All memory is preallocated for @code{RTEMS ITRON} objects. Thus, no |
---|
| 252 | dynamic memory allocation is performed by @code{cre_flg} and the |
---|
| 253 | @code{E_NOMEM} error can not be returned. |
---|
| 254 | |
---|
| 255 | @c |
---|
| 256 | @c del_flg |
---|
| 257 | @c |
---|
| 258 | |
---|
| 259 | @page |
---|
| 260 | @subsection del_flg - Delete Eventflag |
---|
| 261 | |
---|
| 262 | @subheading CALLING SEQUENCE: |
---|
| 263 | |
---|
| 264 | @ifset is-C |
---|
| 265 | @example |
---|
| 266 | ER del_flg( |
---|
| 267 | ID flgid |
---|
| 268 | ); |
---|
| 269 | @end example |
---|
| 270 | @end ifset |
---|
| 271 | |
---|
| 272 | @ifset is-Ada |
---|
| 273 | @end ifset |
---|
| 274 | |
---|
| 275 | @subheading STATUS CODES: |
---|
| 276 | |
---|
| 277 | @code{E_OK} - Normal Completion |
---|
| 278 | |
---|
| 279 | @code{E_ID} - Invalid ID number (flgid was invalid or could not be used) |
---|
| 280 | |
---|
| 281 | @code{E_NOEXS} - Object does not exist (the eventflag specified by flgid |
---|
| 282 | does not exist) |
---|
| 283 | |
---|
| 284 | @code{E_OACV} - Object access violation (A flgid less than -4 was |
---|
| 285 | specified from a user task. This is implementation dependent.) |
---|
| 286 | |
---|
| 287 | @code{EN_OBJNO} - An object number which could not be accessed on the |
---|
| 288 | target node is specified. |
---|
| 289 | |
---|
| 290 | @code{EN_CTXID} - Specified an object on another node when the system call |
---|
| 291 | was issued from a task in dispatch disabled state or from a |
---|
| 292 | task-independent portion |
---|
| 293 | |
---|
| 294 | @subheading DESCRIPTION: |
---|
| 295 | |
---|
| 296 | This system call deletes the eventflag specified by @code{flgid}. |
---|
| 297 | |
---|
| 298 | Issuing this system call causes memory used for the control block of the |
---|
| 299 | associated eventflag to be released. After this system call is invoked, |
---|
| 300 | another eventflag having the same ID number can be created. |
---|
| 301 | |
---|
| 302 | This system call will complete normally even if there are tasks waiting |
---|
| 303 | for the eventflag. In that case, an @code{E_DLT} error will be returned |
---|
| 304 | to each waiting task. |
---|
| 305 | |
---|
| 306 | @subheading NOTES: |
---|
| 307 | |
---|
| 308 | Multiprocessing is not supported. Thus none of the "@code{EN_}" status |
---|
| 309 | codes will be returned. |
---|
| 310 | |
---|
| 311 | When an eventflag being waited for by more than one tasks is deleted, the |
---|
| 312 | order of tasks on the ready queue after the WAIT state is cleared is |
---|
| 313 | implementation dependent in the case of tasks having the same priority. |
---|
| 314 | |
---|
| 315 | @c |
---|
| 316 | @c set_flg |
---|
| 317 | @c |
---|
| 318 | |
---|
| 319 | @page |
---|
| 320 | @subsection set_flg - Set Eventflag |
---|
| 321 | |
---|
| 322 | @subheading CALLING SEQUENCE: |
---|
| 323 | |
---|
| 324 | @ifset is-C |
---|
| 325 | @example |
---|
| 326 | ER set_flg( |
---|
| 327 | ID flgid, |
---|
| 328 | UINT setptn |
---|
| 329 | ); |
---|
| 330 | @end example |
---|
| 331 | @end ifset |
---|
| 332 | |
---|
| 333 | @ifset is-Ada |
---|
| 334 | @end ifset |
---|
| 335 | |
---|
| 336 | @subheading STATUS CODES: |
---|
| 337 | |
---|
| 338 | @code{E_OK} - Normal Completion |
---|
| 339 | |
---|
| 340 | @code{E_ID} - Invalid ID number (flgid was invalid or could not be used) |
---|
| 341 | |
---|
| 342 | @code{E_NOEXS} - Object does not exist (the eventflag specified by flgid |
---|
| 343 | does not exist) |
---|
| 344 | |
---|
| 345 | @code{E_OACV} - Object access violation (A flgid less than -4 was |
---|
| 346 | specified from a user task. This is implementation dependent.) |
---|
| 347 | |
---|
| 348 | @code{EN_OBJNO} - An object number which could not be accessed on the |
---|
| 349 | target node is specified. |
---|
| 350 | |
---|
| 351 | @code{EN_CTXID} - Specified an object on another node when the system call |
---|
| 352 | was issued from a task in dispatch disabled state or from a |
---|
| 353 | task-independent portion |
---|
| 354 | |
---|
| 355 | @code{EN_PAR} - A value outside the range supported by the target node |
---|
| 356 | and/or transmission packet format was specified as a parameter (a value |
---|
| 357 | outside supported range was specified for setptn or clrptn) |
---|
| 358 | |
---|
| 359 | @subheading DESCRIPTION: |
---|
| 360 | |
---|
| 361 | The @code{set_flg} system call sets the bits specified by @code{setptn} of the |
---|
| 362 | one word eventflag specified by @code{flgid}. In other words, a logical |
---|
[a5f5acad] | 363 | sum is taken for the values of the eventflag specified by @code{flgid} with the |
---|
[1baa059] | 364 | value of @code{setptn}. |
---|
| 365 | |
---|
| 366 | If the eventflag value is changed by @code{set_flg} and the new eventflag |
---|
| 367 | value satisfies the condition to release the WAIT state of the task which |
---|
| 368 | issued @code{wai_flg} on the eventflag, the WAIT state of that task will |
---|
| 369 | be released and the task will be put into RUN or READY state (or SUSPEND |
---|
| 370 | state if the task was in WAIT-SUSPEND). |
---|
| 371 | |
---|
| 372 | Nothing will happen to the target eventflag if all bits of @code{setptn} |
---|
| 373 | are specified as 0 with @code{set_flg}. No error will result in either |
---|
| 374 | case. |
---|
| 375 | |
---|
| 376 | Multiple tasks can wait for a single eventflag if that eventflags has the |
---|
| 377 | @code{TA_WMUL} attribute. This means that even eventflags can make queues |
---|
| 378 | for tasks to wait on. When such eventflags are used, a single |
---|
| 379 | @code{set_flg} call may result in the release of multiple waiting tasks. |
---|
| 380 | In this case, the order of tasks on the ready queue after the WAIT state |
---|
| 381 | is cleared is preserved for tasks having the same priority. |
---|
| 382 | |
---|
| 383 | @subheading NOTES: |
---|
| 384 | |
---|
| 385 | Multiprocessing is not supported. Thus none of the "@code{EN_}" status |
---|
| 386 | codes will be returned. |
---|
| 387 | |
---|
| 388 | @c |
---|
| 389 | @c clr_flg |
---|
| 390 | @c |
---|
| 391 | |
---|
| 392 | @page |
---|
| 393 | @subsection clr_flg - Clear Eventflag |
---|
| 394 | |
---|
| 395 | @subheading CALLING SEQUENCE: |
---|
| 396 | |
---|
| 397 | @ifset is-C |
---|
| 398 | @example |
---|
| 399 | ER clr_flg( |
---|
| 400 | ID flgid, |
---|
| 401 | UINT clrptn |
---|
| 402 | ); |
---|
| 403 | @end example |
---|
| 404 | @end ifset |
---|
| 405 | |
---|
| 406 | @ifset is-Ada |
---|
| 407 | @end ifset |
---|
| 408 | |
---|
| 409 | @subheading STATUS CODES: |
---|
| 410 | |
---|
| 411 | |
---|
| 412 | @code{E_OK} - Normal Completion |
---|
| 413 | |
---|
| 414 | @code{E_ID} - Invalid ID number (flgid was invalid or could not be used) |
---|
| 415 | |
---|
| 416 | @code{E_NOEXS} - Object does not exist (the eventflag specified by flgid |
---|
| 417 | does not exist) |
---|
| 418 | |
---|
| 419 | @code{E_OACV} - Object access violation (A flgid less than -4 was |
---|
| 420 | specified from a user task. This is implementation dependent.) |
---|
| 421 | |
---|
| 422 | @code{EN_OBJNO} - An object number which could not be accessed on the |
---|
| 423 | target node is specified. |
---|
| 424 | |
---|
| 425 | @code{EN_CTXID} - Specified an object on another node when the system call |
---|
| 426 | was issued from a task in dispatch disabled state or from a |
---|
| 427 | task-independent portion |
---|
| 428 | |
---|
| 429 | @code{EN_PAR} - A value outside the range supported by the target node |
---|
| 430 | and/or transmission packet format was specified as a parameter (a value |
---|
| 431 | outside supported range was specified for setptn or clrptn) |
---|
| 432 | |
---|
| 433 | @subheading DESCRIPTION: |
---|
| 434 | |
---|
| 435 | The @code{clr_flg} system call clears the bits of the one word eventflag |
---|
| 436 | based on the corresponding zero bits of @code{clrptn}. In other words, a |
---|
| 437 | logical product is taken for the values of the eventflag specified by |
---|
| 438 | @code{flgid} with the value of @code{clrptn}. |
---|
| 439 | |
---|
| 440 | Issuing @code{clr_flg} never results in wait conditions being released on |
---|
| 441 | a task waiting for the specified eventflag. In other words, dispatching |
---|
| 442 | never occurs with @code{clr_flg}. |
---|
| 443 | |
---|
| 444 | Nothing will happen to the target eventflag if all bits of @code{clrptn} |
---|
| 445 | are specified as 1 with @code{clr_flg}. No error will result. |
---|
| 446 | |
---|
| 447 | @subheading NOTES: |
---|
| 448 | |
---|
| 449 | Multiprocessing is not supported. Thus none of the "@code{EN_}" status |
---|
| 450 | codes will be returned. |
---|
| 451 | |
---|
| 452 | @c |
---|
| 453 | @c wai_flg |
---|
| 454 | @c |
---|
| 455 | |
---|
| 456 | @page |
---|
| 457 | @subsection wai_flg - Wait on Eventflag |
---|
| 458 | |
---|
| 459 | @subheading CALLING SEQUENCE: |
---|
| 460 | |
---|
| 461 | @ifset is-C |
---|
| 462 | @example |
---|
| 463 | ER wai_flg( |
---|
| 464 | UINT *p_flgptn, |
---|
| 465 | ID flgid, |
---|
| 466 | UINT waiptn, |
---|
| 467 | UINT wfmode |
---|
| 468 | ); |
---|
| 469 | @end example |
---|
| 470 | @end ifset |
---|
| 471 | |
---|
| 472 | @ifset is-Ada |
---|
| 473 | @end ifset |
---|
| 474 | |
---|
| 475 | @subheading STATUS CODES: |
---|
| 476 | |
---|
| 477 | |
---|
| 478 | @code{E_OK} - Normal Completion |
---|
| 479 | |
---|
| 480 | @code{E_ID} - Invalid ID number (flgid was invalid or could not be used) |
---|
| 481 | |
---|
| 482 | @code{E_NOEXS} - Object does not exist (the eventflag specified by flgid |
---|
| 483 | does not exist) |
---|
| 484 | |
---|
| 485 | @code{E_OACV} - Object access violation (A flgid less than -4 was |
---|
| 486 | specified from a user task. This is implementation dependent.) |
---|
| 487 | |
---|
| 488 | @code{E_PAR} - Parameter error (waiptn = 0, wfmode invalid, or tmout is -2 |
---|
| 489 | or less) |
---|
| 490 | |
---|
| 491 | @code{E_OBJ} - Invalid object state (multiple tasks waiting for an |
---|
| 492 | eventflag with the TA_WSGL attribute) |
---|
| 493 | |
---|
| 494 | @code{E_DLT} - The object being waited for was deleted (the specified |
---|
| 495 | eventflag was deleted while waiting) |
---|
| 496 | |
---|
| 497 | @code{E_RLWAI} - WAIT state was forcibly released (rel_wai was received |
---|
| 498 | while waiting) |
---|
| 499 | |
---|
| 500 | @code{E_TMOUT} - Polling failure or timeout exceeded |
---|
| 501 | |
---|
| 502 | @code{E_CTX} - Context error (issued from task-independent portions or a |
---|
| 503 | task in dispatch disabled state) |
---|
| 504 | |
---|
| 505 | @code{EN_OBJNO} - An object number which could not be accessed on the |
---|
| 506 | target node is specified. |
---|
| 507 | |
---|
| 508 | @code{EN_PAR} - A value outside the range supported by the target node |
---|
| 509 | and/or transmission packet format was specified as a parameter (a value |
---|
| 510 | outside supported range was specified for waiptn and tmout) |
---|
| 511 | |
---|
| 512 | @code{EN_RPAR} - A value outside the range supported by the requesting |
---|
| 513 | node and/or transmission packet format was specified as a parameter (a |
---|
| 514 | value exceeding the range for the requesting node was specified for |
---|
| 515 | flgptn) |
---|
| 516 | |
---|
| 517 | @subheading DESCRIPTION: |
---|
| 518 | |
---|
| 519 | The @code{wai_flg} system call waits for the eventflag specified by |
---|
| 520 | @code{flgid} to be set to satisfy the wait release condition specified by |
---|
[a5f5acad] | 521 | @code{wfmode}. The Eventflags bit-pattern will be returned with a pointer @code{p_flgptn}. |
---|
[1baa059] | 522 | |
---|
| 523 | If the eventflag specified by @code{flgid} already satisfies the wait |
---|
| 524 | release conditions given by @code{wfmode}, the issuing task will continue |
---|
| 525 | execution without waiting. @code{wfmode} may be specified as follows. |
---|
| 526 | |
---|
| 527 | @example |
---|
| 528 | wfmode = TWF_ANDW (or TWF_ORW) | TWF_CLR(optional) |
---|
| 529 | @end example |
---|
| 530 | |
---|
| 531 | If @code{TWF_ORW} is specified, the issuing task will wait for any of the |
---|
| 532 | bits specified by @code{waiptn} to be set for the eventflag given by |
---|
| 533 | @code{flgid} (OR wait). If @code{TWF_ANDW} is specified, the issuing task |
---|
| 534 | will wait for all of the bits specified by @code{waiptn} to be set for the |
---|
| 535 | eventflag given by @code{flgid} (AND wait). |
---|
| 536 | |
---|
| 537 | If the @code{TWF_CLR} specification is not present, the eventflag value |
---|
| 538 | will remain unchanged even after the wait conditions have been satisfied |
---|
| 539 | and the task has been released from the WAIT state. If @code{TWF_CLR} is |
---|
| 540 | specified, all bits of the eventflag will be cleared to 0 once the wait |
---|
| 541 | conditions of the waiting task have been satisfied. |
---|
| 542 | |
---|
| 543 | The return parameter @code{flgptn} returns the value of the eventflag after the |
---|
| 544 | wait state of a task has been released due to this system call. If |
---|
| 545 | @code{TWF_CLR} was specified, the value before eventflag bits were cleared |
---|
| 546 | is returned. The value returned by @code{flgptn} fulfills the wait |
---|
| 547 | release conditions of this system call. |
---|
| 548 | |
---|
| 549 | An @code{E_PAR} parameter error will result if @code{waiptn} is 0. |
---|
| 550 | |
---|
| 551 | A task can not execute any of @code{wai_flg, twai_flg} or @code{pol_flg} |
---|
| 552 | on an eventflag having the @code{TA_WSGL} attribute if another task is |
---|
| 553 | already waiting for that eventflag. An @code{E_OBJ} error will be |
---|
| 554 | returned to a task which executes @code{wai_flg} at a later time |
---|
| 555 | regardless as to whether or not the task that executes @code{wai_flg} or |
---|
| 556 | @code{twai_flg} later will be placed in a WAIT state (conditions for |
---|
| 557 | releasing wait state be satisfied). An @code{E_OBJ} error will be |
---|
| 558 | returned even to tasks which just execute @code{pol_flg}, again regardless |
---|
| 559 | as to whether or not wait release conditions for that task were satisfied. |
---|
| 560 | |
---|
| 561 | On the other hand, multiple tasks can wait at the same time for the same |
---|
| 562 | eventflag if that eventflag has the @code{TA_WMUL} attribute. This means |
---|
| 563 | that event flags can make queues for tasks to wait on. When such |
---|
| 564 | eventflags are used, a single @code{set_flg} call may release multiple |
---|
| 565 | waiting tasks. |
---|
| 566 | |
---|
| 567 | The following processing takes place if a queue for allowing multiple |
---|
| 568 | tasks to wait has been created for an eventflag with the @code{TA_WMUL} |
---|
| 569 | attribute. |
---|
| 570 | |
---|
| 571 | @itemize @bullet |
---|
| 572 | |
---|
| 573 | @item The waiting order on the queue is FIFO. (However, depending on |
---|
| 574 | @code{waiptn} and @code{wfmode}, task at the head of the queue will not |
---|
| 575 | always be released from waiting.) |
---|
| 576 | |
---|
| 577 | @item If a task specifying that the eventflag be cleared is on the queue, |
---|
| 578 | the flag is cleared when that task is released from waiting. |
---|
| 579 | |
---|
| 580 | @item Since any tasks behind a task which clears the eventflag (by |
---|
| 581 | specifying @code{TWF_CLR}) will check the eventflag after it is cleared, |
---|
| 582 | they will not be released from waiting. |
---|
| 583 | |
---|
| 584 | @end itemize |
---|
| 585 | |
---|
| 586 | If multiple tasks having the same priority are released from waiting |
---|
| 587 | simultaneously due to @code{set_flg}, the order of tasks on the ready |
---|
| 588 | queue after release will be the same as their original order on the |
---|
| 589 | eventflag queue. |
---|
| 590 | |
---|
| 591 | @subheading NOTES: |
---|
| 592 | |
---|
| 593 | Multiprocessing is not supported. Thus none of the "@code{EN_}" status |
---|
| 594 | codes will be returned. |
---|
| 595 | |
---|
| 596 | |
---|
| 597 | @c |
---|
| 598 | @c pol_flg |
---|
| 599 | @c |
---|
| 600 | |
---|
| 601 | @page |
---|
| 602 | @subsection pol_flg - Wait for Eventflag (Polling) |
---|
| 603 | |
---|
| 604 | @subheading CALLING SEQUENCE: |
---|
| 605 | |
---|
| 606 | @ifset is-C |
---|
| 607 | @example |
---|
| 608 | ER pol_flg( |
---|
| 609 | UINT *p_flgptn, |
---|
| 610 | ID flgid, |
---|
| 611 | UINT waiptn, |
---|
| 612 | UINT wfmode |
---|
| 613 | ); |
---|
| 614 | @end example |
---|
| 615 | @end ifset |
---|
| 616 | |
---|
| 617 | @ifset is-Ada |
---|
| 618 | @end ifset |
---|
| 619 | |
---|
| 620 | @subheading STATUS CODES: |
---|
| 621 | |
---|
| 622 | |
---|
| 623 | @code{E_OK} - Normal Completion |
---|
| 624 | |
---|
| 625 | @code{E_ID} - Invalid ID number (flgid was invalid or could not be used) |
---|
| 626 | |
---|
| 627 | @code{E_NOEXS} - Object does not exist (the eventflag specified by flgid |
---|
| 628 | does not exist) |
---|
| 629 | |
---|
| 630 | @code{E_OACV} - Object access violation (A flgid less than -4 was |
---|
| 631 | specified from a user task. This is implementation dependent.) |
---|
| 632 | |
---|
| 633 | @code{E_PAR} - Parameter error (waiptn = 0, wfmode invalid, or tmout is -2 |
---|
| 634 | or less) |
---|
| 635 | |
---|
| 636 | @code{E_OBJ} - Invalid object state (multiple tasks waiting for an |
---|
| 637 | eventflag with the TA_WSGL attribute) |
---|
| 638 | |
---|
| 639 | @code{E_DLT} - The object being waited for was deleted (the specified |
---|
| 640 | eventflag was deleted while waiting) |
---|
| 641 | |
---|
| 642 | @code{E_RLWAI} - WAIT state was forcibly released (rel_wai was received |
---|
| 643 | while waiting) |
---|
| 644 | |
---|
| 645 | @code{E_TMOUT} - Polling failure or timeout exceeded |
---|
| 646 | |
---|
| 647 | @code{E_CTX} - Context error (issued from task-independent portions or a |
---|
| 648 | task in dispatch disabled state) |
---|
| 649 | |
---|
| 650 | @code{EN_OBJNO} - An object number which could not be accessed on the |
---|
| 651 | target node is specified. |
---|
| 652 | |
---|
| 653 | @code{EN_PAR} - A value outside the range supported by the target node |
---|
| 654 | and/or transmission packet format was specified as a parameter (a value |
---|
| 655 | outside supported range was specified for waiptn and tmout) |
---|
| 656 | |
---|
| 657 | @code{EN_RPAR} - A value outside the range supported by the requesting |
---|
| 658 | node and/or transmission packet format was specified as a parameter (a |
---|
| 659 | value exceeding the range for the requesting node was specified for |
---|
| 660 | flgptn) |
---|
| 661 | |
---|
| 662 | @subheading DESCRIPTION: |
---|
| 663 | |
---|
| 664 | The @code{pol_flg} system call has the same function as @code{wai_flg} |
---|
| 665 | except for the waiting feature. @code{pol_flg} polls whether or not the |
---|
| 666 | task should wait if @code{wai_flg} is executed. The meanings of |
---|
| 667 | parameters to @code{pol_flg} are the same as for @code{wai_flg}. The |
---|
| 668 | specific operations by @code{pol_flg} are as follows. |
---|
| 669 | |
---|
| 670 | @itemize @bullet |
---|
| 671 | |
---|
| 672 | @item If the target eventflag already satisfies the conditions for |
---|
| 673 | releasing wait given by @code{wfmode}, processing is the same as |
---|
| 674 | @code{wai_flg}: the eventflag is cleared if @code{TWF_CLR} is specified |
---|
| 675 | and the system call completes normally. |
---|
| 676 | |
---|
| 677 | @item If the target eventflag does not yet satisfy the conditions for |
---|
| 678 | releasing wait given by @code{wfmode}, an @code{E_TMOUT} error is returned to |
---|
| 679 | indicate polling failed and the system call finishes. Unlike |
---|
| 680 | @code{wai_flg}, the issuing task does not wait in this case. The eventflag |
---|
| 681 | is not cleared in this case even if @code{TWF_CLR} has been specified. |
---|
| 682 | |
---|
| 683 | @end itemize |
---|
| 684 | |
---|
| 685 | @subheading NOTES: |
---|
| 686 | |
---|
| 687 | Multiprocessing is not supported. Thus none of the "@code{EN_}" status |
---|
| 688 | codes will be returned. |
---|
| 689 | |
---|
| 690 | |
---|
| 691 | @c |
---|
| 692 | @c twai_flg |
---|
| 693 | @c |
---|
| 694 | |
---|
| 695 | @page |
---|
| 696 | @subsection twai_flg - Wait on Eventflag with Timeout |
---|
| 697 | |
---|
| 698 | @subheading CALLING SEQUENCE: |
---|
| 699 | |
---|
| 700 | @ifset is-C |
---|
| 701 | @example |
---|
| 702 | ER twai_flg( |
---|
| 703 | UINT *p_flgptn, |
---|
| 704 | ID flgid, |
---|
| 705 | UINT waiptn, |
---|
| 706 | UINT wfmode, |
---|
[a5f5acad] | 707 | TMO tmout |
---|
[1baa059] | 708 | ); |
---|
| 709 | @end example |
---|
| 710 | @end ifset |
---|
| 711 | |
---|
| 712 | @ifset is-Ada |
---|
| 713 | @end ifset |
---|
| 714 | |
---|
| 715 | @subheading STATUS CODES: |
---|
| 716 | |
---|
| 717 | |
---|
| 718 | @code{E_OK} - Normal Completion |
---|
| 719 | |
---|
| 720 | @code{E_ID} - Invalid ID number (flgid was invalid or could not be used) |
---|
| 721 | |
---|
| 722 | @code{E_NOEXS} - Object does not exist (the eventflag specified by flgid |
---|
| 723 | does not exist) |
---|
| 724 | |
---|
| 725 | @code{E_OACV} - Object access violation (A flgid less than -4 was |
---|
| 726 | specified from a user task. This is implementation dependent.) |
---|
| 727 | |
---|
| 728 | @code{E_PAR} - Parameter error (waiptn = 0, wfmode invalid, or tmout is -2 |
---|
| 729 | or less) |
---|
| 730 | |
---|
| 731 | @code{E_OBJ} - Invalid object state (multiple tasks waiting for an |
---|
| 732 | eventflag with the TA_WSGL attribute) |
---|
| 733 | |
---|
| 734 | @code{E_DLT} - The object being waited for was deleted (the specified |
---|
| 735 | eventflag was deleted while waiting) |
---|
| 736 | |
---|
| 737 | @code{E_RLWAI} - WAIT state was forcibly released (rel_wai was received |
---|
| 738 | while waiting) |
---|
| 739 | |
---|
| 740 | @code{E_TMOUT} - Polling failure or timeout exceeded |
---|
| 741 | |
---|
| 742 | @code{E_CTX} - Context error (issued from task-independent portions or a |
---|
| 743 | task in dispatch disabled state) |
---|
| 744 | |
---|
| 745 | @code{EN_OBJNO} - An object number which could not be accessed on the |
---|
| 746 | target node is specified. |
---|
| 747 | |
---|
| 748 | @code{EN_PAR} - A value outside the range supported by the target node |
---|
| 749 | and/or transmission packet format was specified as a parameter (a value |
---|
| 750 | outside supported range was specified for waiptn and tmout) |
---|
| 751 | |
---|
| 752 | @code{EN_RPAR} - A value outside the range supported by the requesting |
---|
| 753 | node and/or transmission packet format was specified as a parameter (a |
---|
| 754 | value exceeding the range for the requesting node was specified for |
---|
| 755 | flgptn) |
---|
| 756 | |
---|
| 757 | @subheading DESCRIPTION: |
---|
| 758 | |
---|
| 759 | The @code{twai_flg} system call has the same function as @code{wai_flg} |
---|
| 760 | with an additional timeout feature. A maximum wait time (timeout value) |
---|
| 761 | can be specified using the parameter @code{tmout}. When a timeout is specified, |
---|
| 762 | a timeout error, @code{E_TMOUT}, will result and the system call will |
---|
| 763 | finish if the period specified by @code{tmout} elapses without conditions for |
---|
| 764 | releasing wait being satisfied. |
---|
| 765 | |
---|
| 766 | Specifying @code{TMO_POL = 0} to @code{twai_flg} for @code{tmout} indicates that |
---|
| 767 | a timeout value of 0 be used, resulting in exactly the same processing as |
---|
| 768 | @code{pol_flg}. Specifying @code{TMO_FEVR = -1} to @code{twai_flg} for |
---|
| 769 | @code{tmout} indicates that an infinite timeout value be used, resulting in |
---|
| 770 | exactly the same processing as @code{wai_flg}. |
---|
| 771 | |
---|
| 772 | @subheading NOTES: |
---|
| 773 | |
---|
| 774 | Multiprocessing is not supported. Thus none of the "@code{EN_}" status |
---|
| 775 | codes will be returned. |
---|
| 776 | |
---|
| 777 | |
---|
| 778 | @code{Pol_flg} and @code{wai_flg} represent the same processing as |
---|
| 779 | specifying certain values (@code{TMO_POL} or @code{TMO_FEVR}) to |
---|
| 780 | @code{twai_flg} for tmout. As such, only @code{twai_flg} is implemented |
---|
| 781 | in the kernel; @code{pol_flg} and @code{wai_flg} should be implemented as macros |
---|
| 782 | which call @code{twai_flg}. |
---|
| 783 | |
---|
| 784 | @c |
---|
| 785 | @c ref_flg |
---|
| 786 | @c |
---|
| 787 | |
---|
| 788 | @page |
---|
| 789 | @subsection ref_flg - Reference Eventflag Status |
---|
| 790 | |
---|
| 791 | @subheading CALLING SEQUENCE: |
---|
| 792 | |
---|
| 793 | @ifset is-C |
---|
| 794 | @example |
---|
| 795 | ER ref_flg( |
---|
| 796 | T_RFLG *pk_rflg, |
---|
| 797 | ID flgid ); |
---|
| 798 | @end example |
---|
| 799 | @end ifset |
---|
| 800 | |
---|
| 801 | @ifset is-Ada |
---|
| 802 | @end ifset |
---|
| 803 | |
---|
| 804 | @subheading STATUS CODES: |
---|
| 805 | |
---|
| 806 | |
---|
| 807 | @code{E_OK} - Normal Completion |
---|
| 808 | |
---|
| 809 | @code{E_ID} - Invalid ID number (flgid was invalid or could not be used) |
---|
| 810 | |
---|
| 811 | @code{E_NOEXS} - Object does not exist (the eventflag specified by flgid |
---|
| 812 | does not exist) |
---|
| 813 | |
---|
| 814 | @code{E_OACV} - Object access violation (A flgid less than -4 was |
---|
| 815 | specified from a user task. This is implementation dependent.) |
---|
| 816 | |
---|
| 817 | @code{E_PAR} - Parameter error (the packet address for the return |
---|
| 818 | parameters could not be used) |
---|
| 819 | |
---|
| 820 | @code{EN_OBJNO} - An object number which could not be accessed on the |
---|
| 821 | target node is specified. |
---|
| 822 | |
---|
| 823 | @code{EN_CTXID} - Specified an object on another node when the system call |
---|
| 824 | was issued from a task in dispatch disabled state or from a |
---|
| 825 | task-independent portion |
---|
| 826 | |
---|
| 827 | @code{EN_RPAR} - A value outside the range supported by the requesting |
---|
| 828 | node and/or transmission packet format was returned as a parameter (a |
---|
| 829 | value outside supported range was specified for exinf, wtsk and/or flgptn) |
---|
| 830 | |
---|
| 831 | @subheading DESCRIPTION: |
---|
| 832 | |
---|
| 833 | This system call refers to the state of the eventflag specified by |
---|
| 834 | @code{flgid}, and returns its current flag pattern (@code{flgptn}), |
---|
| 835 | waiting task information (@code{wtsk}), and its extended information |
---|
| 836 | (@code{exinf}). |
---|
| 837 | |
---|
| 838 | Depending on the implementation, @code{wtsk} may be returned as the ID |
---|
| 839 | (non-zero) of the task waiting for the eventflag. If there are multiple |
---|
| 840 | tasks waiting for the eventflag (only when attribute is @code{TA_WMUL}), |
---|
| 841 | the ID of the task at the head of the queue is returned. |
---|
| 842 | |
---|
| 843 | An @code{E_NOEXS} error will result if the eventflag specified to |
---|
| 844 | @code{ref_flg} does not exist. |
---|
| 845 | |
---|
| 846 | @subheading NOTES: |
---|
| 847 | |
---|
| 848 | Multiprocessing is not supported. Thus none of the "@code{EN_}" status |
---|
| 849 | codes will be returned. |
---|
| 850 | |
---|
| 851 | Although both @code{ref_flg} and @code{pol_flg} can be used to find an |
---|
| 852 | eventflag's pattern (@code{flgptn}) without causing the issuing task to |
---|
| 853 | wait, @code{ref_flg} simply reads the eventflag's pattern (@code{flgptn}) |
---|
| 854 | while @code{pol_flg} functions is identical to @code{wai_flg} when wait |
---|
| 855 | release conditions are satisfied (it clears the eventflag if |
---|
| 856 | @code{TWF_CLR} is specified). |
---|
| 857 | |
---|
| 858 | Depending on the implementation, additional information besides |
---|
| 859 | @code{wtsk} and @code{flgptn} (such as eventflag attributes, |
---|
| 860 | @code{flgatr}) may also be referred. |
---|