doc/html/ref/compat-uitron-task-management-functions.html

   1 <!-- Copyright (C) 2003 Red Hat, Inc.                                -->
   2 <!-- This material may be distributed only subject to the terms      -->
   3 <!-- and conditions set forth in the Open Publication License, v1.0  -->
   4 <!-- or later (the latest version is presently available at          -->
   5 <!-- http://www.opencontent.org/openpub/).                           -->
   6 <!-- Distribution of the work or derivative of the work in any       -->
   7 <!-- standard (paper) book form is prohibited unless prior           -->
   8 <!-- permission is obtained from the copyright holder.               -->
   9 <HTML
  10 ><HEAD
  11 ><TITLE
  12 >Task Management Functions</TITLE
  13 ><meta name="MSSmartTagsPreventParsing" content="TRUE">
  14 <META
  15 NAME="GENERATOR"
  16 CONTENT="Modular DocBook HTML Stylesheet Version 1.76b+
  17 "><LINK
  18 REL="HOME"
  19 TITLE="eCos Reference Manual"
  20 HREF="ecos-ref.html"><LINK
  21 REL="UP"
  22 TITLE="µITRON API"
  23 HREF="compat-uitron-microitron-api.html"><LINK
  24 REL="PREVIOUS"
  25 TITLE="µITRON and eCos"
  26 HREF="compat-uitron-over-ecos.html"><LINK
  27 REL="NEXT"
  28 TITLE="Task-Dependent Synchronization Functions"
  29 HREF="compat-uitron-task-dependent-synch-functions.html"></HEAD
  30 ><BODY
  31 CLASS="SECT1"
  32 BGCOLOR="#FFFFFF"
  33 TEXT="#000000"
  34 LINK="#0000FF"
  35 VLINK="#840084"
  36 ALINK="#0000FF"
  37 ><DIV
  38 CLASS="NAVHEADER"
  39 ><TABLE
  40 SUMMARY="Header navigation table"
  41 WIDTH="100%"
  42 BORDER="0"
  43 CELLPADDING="0"
  44 CELLSPACING="0"
  45 ><TR
  46 ><TH
  47 COLSPAN="3"
  48 ALIGN="center"
  49 >eCos Reference Manual</TH
  50 ></TR
  51 ><TR
  52 ><TD
  53 WIDTH="10%"
  54 ALIGN="left"
  55 VALIGN="bottom"
  56 ><A
  57 HREF="compat-uitron-over-ecos.html"
  58 ACCESSKEY="P"
  59 >Prev</A
  60 ></TD
  61 ><TD
  62 WIDTH="80%"
  63 ALIGN="center"
  64 VALIGN="bottom"
  65 >Chapter 32. &micro;ITRON API</TD
  66 ><TD
  67 WIDTH="10%"
  68 ALIGN="right"
  69 VALIGN="bottom"
  70 ><A
  71 HREF="compat-uitron-task-dependent-synch-functions.html"
  72 ACCESSKEY="N"
  73 >Next</A
  74 ></TD
  75 ></TR
  76 ></TABLE
  77 ><HR
  78 ALIGN="LEFT"
  79 WIDTH="100%"></DIV
  80 ><DIV
  81 CLASS="SECT1"
  82 ><H1
  83 CLASS="SECT1"
  84 ><A
  85 NAME="COMPAT-UITRON-TASK-MANAGEMENT-FUNCTIONS">Task Management Functions</H1
  86 ><P
  87 >The following functions are fully supported in this release: </P
  88 ><TABLE
  89 BORDER="5"
  90 BGCOLOR="#E0E0F0"
  91 WIDTH="70%"
  92 ><TR
  93 ><TD
  94 ><PRE
  95 CLASS="PROGRAMLISTING"
  96 >ER <TT
  97 CLASS="FUNCTION"
  98 >sta_tsk</TT
  99 >(
 100   ID <SPAN
 101 CLASS="emphasis"
 102 ><I
 103 CLASS="EMPHASIS"
 104 >tskid,</I
 105 ></SPAN
 106 >
 107   INT <SPAN
 108 CLASS="emphasis"
 109 ><I
 110 CLASS="EMPHASIS"
 111 >stacd</I
 112 ></SPAN
 113 > )</PRE
 114 ></TD
 115 ></TR
 116 ></TABLE
 117 ><TABLE
 118 BORDER="5"
 119 BGCOLOR="#E0E0F0"
 120 WIDTH="70%"
 121 ><TR
 122 ><TD
 123 ><PRE
 124 CLASS="PROGRAMLISTING"
 125 >void <TT
 126 CLASS="FUNCTION"
 127 >ext_tsk</TT
 128 >( void )</PRE
 129 ></TD
 130 ></TR
 131 ></TABLE
 132 ><TABLE
 133 BORDER="5"
 134 BGCOLOR="#E0E0F0"
 135 WIDTH="70%"
 136 ><TR
 137 ><TD
 138 ><PRE
 139 CLASS="PROGRAMLISTING"
 140 >void <TT
 141 CLASS="FUNCTION"
 142 >exd_tsk</TT
 143 >( void )</PRE
 144 ></TD
 145 ></TR
 146 ></TABLE
 147 ><TABLE
 148 BORDER="5"
 149 BGCOLOR="#E0E0F0"
 150 WIDTH="70%"
 151 ><TR
 152 ><TD
 153 ><PRE
 154 CLASS="PROGRAMLISTING"
 155 >ER <TT
 156 CLASS="FUNCTION"
 157 >dis_dsp</TT
 158 >( void )</PRE
 159 ></TD
 160 ></TR
 161 ></TABLE
 162 ><TABLE
 163 BORDER="5"
 164 BGCOLOR="#E0E0F0"
 165 WIDTH="70%"
 166 ><TR
 167 ><TD
 168 ><PRE
 169 CLASS="PROGRAMLISTING"
 170 >ER <TT
 171 CLASS="FUNCTION"
 172 >ena_dsp</TT
 173 >( void )</PRE
 174 ></TD
 175 ></TR
 176 ></TABLE
 177 ><TABLE
 178 BORDER="5"
 179 BGCOLOR="#E0E0F0"
 180 WIDTH="70%"
 181 ><TR
 182 ><TD
 183 ><PRE
 184 CLASS="PROGRAMLISTING"
 185 >ER <TT
 186 CLASS="FUNCTION"
 187 >chg_pri</TT
 188 >(
 189   ID <SPAN
 190 CLASS="emphasis"
 191 ><I
 192 CLASS="EMPHASIS"
 193 >tskid,</I
 194 ></SPAN
 195 >
 196   PRI <SPAN
 197 CLASS="emphasis"
 198 ><I
 199 CLASS="EMPHASIS"
 200 >tskpri</I
 201 ></SPAN
 202 > )</PRE
 203 ></TD
 204 ></TR
 205 ></TABLE
 206 ><TABLE
 207 BORDER="5"
 208 BGCOLOR="#E0E0F0"
 209 WIDTH="70%"
 210 ><TR
 211 ><TD
 212 ><PRE
 213 CLASS="PROGRAMLISTING"
 214 >ER <TT
 215 CLASS="FUNCTION"
 216 >rot_rdq</TT
 217 >(
 218   PRI <SPAN
 219 CLASS="emphasis"
 220 ><I
 221 CLASS="EMPHASIS"
 222 >tskpri</I
 223 ></SPAN
 224 > )</PRE
 225 ></TD
 226 ></TR
 227 ></TABLE
 228 ><TABLE
 229 BORDER="5"
 230 BGCOLOR="#E0E0F0"
 231 WIDTH="70%"
 232 ><TR
 233 ><TD
 234 ><PRE
 235 CLASS="PROGRAMLISTING"
 236 >ER <TT
 237 CLASS="FUNCTION"
 238 >get_tid</TT
 239 >(
 240   ID *<SPAN
 241 CLASS="emphasis"
 242 ><I
 243 CLASS="EMPHASIS"
 244 >p_tskid</I
 245 ></SPAN
 246 > )</PRE
 247 ></TD
 248 ></TR
 249 ></TABLE
 250 ><TABLE
 251 BORDER="5"
 252 BGCOLOR="#E0E0F0"
 253 WIDTH="70%"
 254 ><TR
 255 ><TD
 256 ><PRE
 257 CLASS="PROGRAMLISTING"
 258 >ER <TT
 259 CLASS="FUNCTION"
 260 >ref_tsk</TT
 261 >(
 262   T_RTSK *<SPAN
 263 CLASS="emphasis"
 264 ><I
 265 CLASS="EMPHASIS"
 266 >pk_rtsk,</I
 267 ></SPAN
 268 >
 269   ID <SPAN
 270 CLASS="emphasis"
 271 ><I
 272 CLASS="EMPHASIS"
 273 >tskid</I
 274 ></SPAN
 275 > )</PRE
 276 ></TD
 277 ></TR
 278 ></TABLE
 279 ><TABLE
 280 BORDER="5"
 281 BGCOLOR="#E0E0F0"
 282 WIDTH="70%"
 283 ><TR
 284 ><TD
 285 ><PRE
 286 CLASS="PROGRAMLISTING"
 287 >ER <TT
 288 CLASS="FUNCTION"
 289 >ter_tsk</TT
 290 >(
 291   ID <SPAN
 292 CLASS="emphasis"
 293 ><I
 294 CLASS="EMPHASIS"
 295 >tskid</I
 296 ></SPAN
 297 > )</PRE
 298 ></TD
 299 ></TR
 300 ></TABLE
 301 ><TABLE
 302 BORDER="5"
 303 BGCOLOR="#E0E0F0"
 304 WIDTH="70%"
 305 ><TR
 306 ><TD
 307 ><PRE
 308 CLASS="PROGRAMLISTING"
 309 >ER <TT
 310 CLASS="FUNCTION"
 311 >rel_wai</TT
 312 >(
 313   ID <SPAN
 314 CLASS="emphasis"
 315 ><I
 316 CLASS="EMPHASIS"
 317 >tskid</I
 318 ></SPAN
 319 > )</PRE
 320 ></TD
 321 ></TR
 322 ></TABLE
 323 ><P
 324 >The following two functions are supported in this release,
 325 when enabled with the configuration option
 326 <TT
 327 CLASS="LITERAL"
 328 >CYGPKG_UITRON_TASKS_CREATE_DELETE</TT
 329 >
 330 with some restrictions:</P
 331 ><TABLE
 332 BORDER="5"
 333 BGCOLOR="#E0E0F0"
 334 WIDTH="70%"
 335 ><TR
 336 ><TD
 337 ><PRE
 338 CLASS="PROGRAMLISTING"
 339 >ER <TT
 340 CLASS="FUNCTION"
 341 >cre_tsk</TT
 342 >(
 343   ID <SPAN
 344 CLASS="emphasis"
 345 ><I
 346 CLASS="EMPHASIS"
 347 >tskid,</I
 348 ></SPAN
 349 >
 350   T_CTSK *<SPAN
 351 CLASS="emphasis"
 352 ><I
 353 CLASS="EMPHASIS"
 354 >pk_ctsk</I
 355 ></SPAN
 356 > )</PRE
 357 ></TD
 358 ></TR
 359 ></TABLE
 360 ><TABLE
 361 BORDER="5"
 362 BGCOLOR="#E0E0F0"
 363 WIDTH="70%"
 364 ><TR
 365 ><TD
 366 ><PRE
 367 CLASS="PROGRAMLISTING"
 368 >ER <TT
 369 CLASS="FUNCTION"
 370 >del_tsk</TT
 371 >(
 372   ID <SPAN
 373 CLASS="emphasis"
 374 ><I
 375 CLASS="EMPHASIS"
 376 >tskid</I
 377 ></SPAN
 378 > )</PRE
 379 ></TD
 380 ></TR
 381 ></TABLE
 382 ><P
 383 >These functions are restricted as follows:</P
 384 ><P
 385 >Because of the static initialization facilities provided for
 386 system objects, a task is allocated stack space statically in the
 387 configuration. So while tasks can be created and deleted, the same
 388 stack space is used for that task (task ID number) each time. Thus
 389 the stack size (pk_ctsk-&gt;stksz) requested in <TT
 390 CLASS="FUNCTION"
 391 >cre_tsk()</TT
 392 > is
 393 checked for being less than that which was statically allocated,
 394 and otherwise ignored. This ensures that the new task will have
 395 enough stack to run. For this reason <TT
 396 CLASS="FUNCTION"
 397 >del_tsk()</TT
 398 > does
 399 not in any sense free the memory that was in use for the task's
 400 stack. </P
 401 ><P
 402 >The task attributes (pk_ctsk-&gt;tskatr) are
 403 ignored; current versions of <SPAN
 404 CLASS="emphasis"
 405 ><I
 406 CLASS="EMPHASIS"
 407 >eCos</I
 408 ></SPAN
 409 > do not need
 410 to know whether a task is written in assembler or C/C&#0043;&#0043; so
 411 long as the procedure call standard appropriate to the CPU is followed.</P
 412 ><P
 413 >Extended information (pk_ctsk-&gt;exinf) is
 414           ignored.</P
 415 ><DIV
 416 CLASS="SECT2"
 417 ><H2
 418 CLASS="SECT2"
 419 ><A
 420 NAME="AEN13490">Error checking</H2
 421 ><P
 422 >For all these calls, an invalid task id (tskid) (less than
 423 1 or greater than the number of configured tasks) only returns E_ID
 424 when bad params return errors (
 425 <TT
 426 CLASS="LITERAL"
 427 >CYGSEM_UITRON_BAD_PARAMS_RETURN_ERRORS</TT
 428 >
 429 is enabled, see above).</P
 430 ><P
 431 >Similarly, the following conditions are only checked for,
 432 and only return errors if
 433 <TT
 434 CLASS="LITERAL"
 435 >CYGSEM_UITRON_BAD_PARAMS_RETURN_ERRORS</TT
 436 >
 437 is enabled:</P
 438 ><P
 439 ></P
 440 ><UL
 441 ><LI
 442 ><P
 443 >pk_crtk in
 444 <TT
 445 CLASS="FUNCTION"
 446 >cre_tsk()</TT
 447 >
 448  is a valid pointer, otherwise return E_PAR</P
 449 ></LI
 450 ><LI
 451 ><P
 452 ><TT
 453 CLASS="FUNCTION"
 454 >ter_tsk()</TT
 455 >
 456  or
 457 <TT
 458 CLASS="FUNCTION"
 459 >rel_wai()</TT
 460 >
 461  on the calling task returns E_OBJ</P
 462 ></LI
 463 ><LI
 464 ><P
 465 >the CPU is not locked already in
 466 <TT
 467 CLASS="FUNCTION"
 468 >dis_dsp()</TT
 469 >
 470  and
 471 <TT
 472 CLASS="FUNCTION"
 473 >ena_dsp()</TT
 474 >
 475 ; returns E_CTX</P
 476 ></LI
 477 ><LI
 478 ><P
 479 >priority level in
 480 <TT
 481 CLASS="FUNCTION"
 482 >chg_pri()</TT
 483 >
 484  and
 485 <TT
 486 CLASS="FUNCTION"
 487 >rot_rdq()</TT
 488 >
 489  is checked for validity, E_PAR</P
 490 ></LI
 491 ><LI
 492 ><P
 493 >return value pointer in
 494 <TT
 495 CLASS="FUNCTION"
 496 >get_tid()</TT
 497 >
 498  and
 499 <TT
 500 CLASS="FUNCTION"
 501 >ref_tsk()</TT
 502 >
 503  is a valid pointer, or E_PAR</P
 504 ></LI
 505 ></UL
 506 ><P
 507 >The following conditions are checked for, and return
 508             error codes if appropriate, regardless of the setting of
 509 <TT
 510 CLASS="LITERAL"
 511 >CYGSEM_UITRON_BAD_PARAMS_RETURN_ERRORS</TT
 512 >
 513 :</P
 514 ><P
 515 ></P
 516 ><UL
 517 ><LI
 518 ><P
 519 >When create and delete functions
 520 <TT
 521 CLASS="FUNCTION"
 522 >cre_tsk()</TT
 523 >
 524  and
 525 <TT
 526 CLASS="FUNCTION"
 527 >del_tsk()</TT
 528 >
 529  are supported, all calls which use a valid task ID number check
 530 that the task exists; if not, E_NOEXS is returned</P
 531 ></LI
 532 ><LI
 533 ><P
 534 >When supported,
 535 <TT
 536 CLASS="FUNCTION"
 537 >cre_tsk()</TT
 538 >
 539 : the task must not already exist; otherwise E_OBJ</P
 540 ></LI
 541 ><LI
 542 ><P
 543 >When supported,
 544 <TT
 545 CLASS="FUNCTION"
 546 >cre_tsk()</TT
 547 >
 548 : the requested stack size must not be larger than that statically
 549 configured for the task; see the configuration options
 550 &#8220;Static initializers&#8221;, and &#8220;Default stack size&#8221;.
 551 Else E_NOMEM</P
 552 ></LI
 553 ><LI
 554 ><P
 555 >When supported,
 556 <TT
 557 CLASS="FUNCTION"
 558 >del_tsk()</TT
 559 >
 560 : the underlying
 561 <SPAN
 562 CLASS="emphasis"
 563 ><I
 564 CLASS="EMPHASIS"
 565 >eCos</I
 566 ></SPAN
 567 >
 568  thread must not be running - this would imply either a bug or some
 569 program bypassing the
 570 &micro;ITRON compatibility layer and manipulating the thread directly.
 571 E_OBJ</P
 572 ></LI
 573 ><LI
 574 ><P
 575 ><TT
 576 CLASS="FUNCTION"
 577 >sta_tsk()</TT
 578 >
 579 : the task must be dormant, else E_OBJ</P
 580 ></LI
 581 ><LI
 582 ><P
 583 ><TT
 584 CLASS="FUNCTION"
 585 >ter_tsk()</TT
 586 >
 587 : the task must not be dormant, else E_OBJ</P
 588 ></LI
 589 ><LI
 590 ><P
 591 ><TT
 592 CLASS="FUNCTION"
 593 >chg_pri()</TT
 594 >
 595 : the task must not be dormant, else E_OBJ</P
 596 ></LI
 597 ><LI
 598 ><P
 599 ><TT
 600 CLASS="FUNCTION"
 601 >rel_wai()</TT
 602 >
 603 : the task must be in
 604 <TT
 605 CLASS="VARNAME"
 606 >WAIT</TT
 607 > or <TT
 608 CLASS="VARNAME"
 609 >WAIT-SUSPEND</TT
 610 >
 611  state, else E_OBJ</P
 612 ></LI
 613 ></UL
 614 ></DIV
 615 ></DIV
 616 ><DIV
 617 CLASS="NAVFOOTER"
 618 ><HR
 619 ALIGN="LEFT"
 620 WIDTH="100%"><TABLE
 621 SUMMARY="Footer navigation table"
 622 WIDTH="100%"
 623 BORDER="0"
 624 CELLPADDING="0"
 625 CELLSPACING="0"
 626 ><TR
 627 ><TD
 628 WIDTH="33%"
 629 ALIGN="left"
 630 VALIGN="top"
 631 ><A
 632 HREF="compat-uitron-over-ecos.html"
 633 ACCESSKEY="P"
 634 >Prev</A
 635 ></TD
 636 ><TD
 637 WIDTH="34%"
 638 ALIGN="center"
 639 VALIGN="top"
 640 ><A
 641 HREF="ecos-ref.html"
 642 ACCESSKEY="H"
 643 >Home</A
 644 ></TD
 645 ><TD
 646 WIDTH="33%"
 647 ALIGN="right"
 648 VALIGN="top"
 649 ><A
 650 HREF="compat-uitron-task-dependent-synch-functions.html"
 651 ACCESSKEY="N"
 652 >Next</A
 653 ></TD
 654 ></TR
 655 ><TR
 656 ><TD
 657 WIDTH="33%"
 658 ALIGN="left"
 659 VALIGN="top"
 660 >&micro;ITRON and <SPAN
 661 CLASS="emphasis"
 662 ><I
 663 CLASS="EMPHASIS"
 664 >eCos</I
 665 ></SPAN
 666 ></TD
 667 ><TD
 668 WIDTH="34%"
 669 ALIGN="center"
 670 VALIGN="top"
 671 ><A
 672 HREF="compat-uitron-microitron-api.html"
 673 ACCESSKEY="U"
 674 >Up</A
 675 ></TD
 676 ><TD
 677 WIDTH="33%"
 678 ALIGN="right"
 679 VALIGN="top"
 680 >Task-Dependent Synchronization Functions</TD
 681 ></TR
 682 ></TABLE
 683 ></DIV
 684 ></BODY
 685 ></HTML
 686 >