doc/html/ref/kernel-thread-info.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 >Thread information</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="The eCos Kernel"
  23 HREF="kernel.html"><LINK
  24 REL="PREVIOUS"
  25 TITLE="Thread creation"
  26 HREF="kernel-thread-create.html"><LINK
  27 REL="NEXT"
  28 TITLE="Thread control"
  29 HREF="kernel-thread-control.html"></HEAD
  30 ><BODY
  31 CLASS="REFENTRY"
  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="kernel-thread-create.html"
  58 ACCESSKEY="P"
  59 >Prev</A
  60 ></TD
  61 ><TD
  62 WIDTH="80%"
  63 ALIGN="center"
  64 VALIGN="bottom"
  65 ></TD
  66 ><TD
  67 WIDTH="10%"
  68 ALIGN="right"
  69 VALIGN="bottom"
  70 ><A
  71 HREF="kernel-thread-control.html"
  72 ACCESSKEY="N"
  73 >Next</A
  74 ></TD
  75 ></TR
  76 ></TABLE
  77 ><HR
  78 ALIGN="LEFT"
  79 WIDTH="100%"></DIV
  80 ><H1
  81 ><A
  82 NAME="KERNEL-THREAD-INFO">Thread information</H1
  83 ><DIV
  84 CLASS="REFNAMEDIV"
  85 ><A
  86 NAME="AEN356"
  87 ></A
  88 ><H2
  89 >Name</H2
  90 >cyg_thread_self, cyg_thread_idle_thread, cyg_thread_get_stack_base, cyg_thread_get_stack_size, cyg_thread_measure_stack_usage, cyg_thread_get_next, cyg_thread_get_info, cyg_thread_find&nbsp;--&nbsp;Get basic thread information</DIV
  91 ><DIV
  92 CLASS="REFSYNOPSISDIV"
  93 ><A
  94 NAME="AEN366"><H2
  95 >Synopsis</H2
  96 ><DIV
  97 CLASS="FUNCSYNOPSIS"
  98 ><A
  99 NAME="AEN367"><P
 100 ></P
 101 ><TABLE
 102 BORDER="5"
 103 BGCOLOR="#E0E0F0"
 104 WIDTH="70%"
 105 ><TR
 106 ><TD
 107 ><PRE
 108 CLASS="FUNCSYNOPSISINFO"
 109 >#include &lt;cyg/kernel/kapi.h&gt;
 110         </PRE
 111 ></TD
 112 ></TR
 113 ></TABLE
 114 ><P
 115 ><CODE
 116 ><CODE
 117 CLASS="FUNCDEF"
 118 >cyg_handle_t cyg_thread_self</CODE
 119 >(void);</CODE
 120 ></P
 121 ><P
 122 ><CODE
 123 ><CODE
 124 CLASS="FUNCDEF"
 125 >cyg_handle_t cyg_thread_idle_thread</CODE
 126 >(void);</CODE
 127 ></P
 128 ><P
 129 ><CODE
 130 ><CODE
 131 CLASS="FUNCDEF"
 132 >cyg_addrword_t cyg_thread_get_stack_base</CODE
 133 >(cyg_handle_t thread);</CODE
 134 ></P
 135 ><P
 136 ><CODE
 137 ><CODE
 138 CLASS="FUNCDEF"
 139 >cyg_uint32 cyg_thread_get_stack_size</CODE
 140 >(cyg_handle_t thread);</CODE
 141 ></P
 142 ><P
 143 ><CODE
 144 ><CODE
 145 CLASS="FUNCDEF"
 146 >cyg_uint32 cyg_thread_measure_stack_usage</CODE
 147 >(cyg_handle_t thread);</CODE
 148 ></P
 149 ><P
 150 ><CODE
 151 ><CODE
 152 CLASS="FUNCDEF"
 153 >cyg_bool cyg_thread_get_next</CODE
 154 >(cyg_handle_t *thread, cyg_uint16 *id);</CODE
 155 ></P
 156 ><P
 157 ><CODE
 158 ><CODE
 159 CLASS="FUNCDEF"
 160 >cyg_bool cyg_thread_get_info</CODE
 161 >(cyg_handle_t thread, cyg_uint16 id, cyg_thread_info *info);</CODE
 162 ></P
 163 ><P
 164 ><CODE
 165 ><CODE
 166 CLASS="FUNCDEF"
 167 >cyg_handle_t cyg_thread_find</CODE
 168 >(cyg_uint16 id);</CODE
 169 ></P
 170 ><P
 171 ></P
 172 ></DIV
 173 ></DIV
 174 ><DIV
 175 CLASS="REFSECT1"
 176 ><A
 177 NAME="KERNEL-THREAD-INFO-DESCRIPTION"
 178 ></A
 179 ><H2
 180 >Description</H2
 181 ><P
 182 >These functions can be used to obtain some basic information about
 183 various threads in the system. Typically they serve little or no
 184 purpose in real applications, but they can be useful during debugging.
 185       </P
 186 ><P
 187 ><TT
 188 CLASS="FUNCTION"
 189 >cyg_thread_self</TT
 190 > returns a handle corresponding
 191 to the current thread. It will be the same as the value filled in by
 192 <TT
 193 CLASS="FUNCTION"
 194 >cyg_thread_create</TT
 195 > when the current thread was
 196 created. This handle can then be passed to other functions such as
 197 <TT
 198 CLASS="FUNCTION"
 199 >cyg_thread_get_priority</TT
 200 >.
 201       </P
 202 ><P
 203 ><TT
 204 CLASS="FUNCTION"
 205 >cyg_thread_idle_thread</TT
 206 > returns the handle
 207 corresponding to the idle thread. This thread is created automatically
 208 by the kernel, so application-code has no other way of getting hold of
 209 this information.
 210       </P
 211 ><P
 212 ><TT
 213 CLASS="FUNCTION"
 214 >cyg_thread_get_stack_base</TT
 215 > and
 216 <TT
 217 CLASS="FUNCTION"
 218 >cyg_thread_get_stack_size</TT
 219 > return information
 220 about a specific thread's stack. The values returned will match the
 221 values passed to <TT
 222 CLASS="FUNCTION"
 223 >cyg_thread_create</TT
 224 > when this
 225 thread was created.
 226       </P
 227 ><P
 228 ><TT
 229 CLASS="FUNCTION"
 230 >cyg_thread_measure_stack_usage</TT
 231 > is only available
 232 if the configuration option
 233 <TT
 234 CLASS="VARNAME"
 235 >CYGFUN_KERNEL_THREADS_STACK_MEASUREMENT</TT
 236 > is enabled.
 237 The return value is the maximum number of bytes of stack space used so
 238 far by the specified thread. Note that this should not be considered a
 239 true upper bound, for example it is possible that in the current test
 240 run the specified thread has not yet been interrupted at the deepest
 241 point in the function call graph. Never the less the value returned
 242 can give some useful indication of the thread's stack requirements.
 243       </P
 244 ><P
 245 ><TT
 246 CLASS="FUNCTION"
 247 >cyg_thread_get_next</TT
 248 > is used to enumerate all the
 249 current threads in the system. It should be called initially with the
 250 locations pointed to by <TT
 251 CLASS="PARAMETER"
 252 ><I
 253 >thread</I
 254 ></TT
 255 > and
 256 <TT
 257 CLASS="PARAMETER"
 258 ><I
 259 >id</I
 260 ></TT
 261 > set to zero. On return these will be set to
 262 the handle and ID of the first thread. On subsequent calls, these
 263 parameters should be left set to the values returned by the previous
 264 call.  The handle and ID of the next thread in the system will be
 265 installed each time, until a <TT
 266 CLASS="LITERAL"
 267 >false</TT
 268 > return value
 269 indicates the end of the list.
 270       </P
 271 ><P
 272 ><TT
 273 CLASS="FUNCTION"
 274 >cyg_thread_get_info</TT
 275 > fills in the
 276 <SPAN
 277 CLASS="TYPE"
 278 >cyg_thread_info</SPAN
 279 > structure with information about the
 280 thread described by the <TT
 281 CLASS="PARAMETER"
 282 ><I
 283 >thread</I
 284 ></TT
 285 > and
 286 <TT
 287 CLASS="PARAMETER"
 288 ><I
 289 >id</I
 290 ></TT
 291 > arguments. The information returned includes
 292 the thread's handle and id, its state and name, priorities and stack
 293 parameters. If the thread does not exist the function returns
 294 <TT
 295 CLASS="LITERAL"
 296 >false</TT
 297 >.
 298     </P
 299 ><P
 300 >The <SPAN
 301 CLASS="TYPE"
 302 >cyg_thread_info</SPAN
 303 > structure is defined as follows by
 304 &lt;<TT
 305 CLASS="FILENAME"
 306 >cyg/kernel/kapi.h</TT
 307 >&gt;, but may
 308 be extended in future with additional members, and so its size should
 309 not be relied upon:
 310 <TABLE
 311 BORDER="5"
 312 BGCOLOR="#E0E0F0"
 313 WIDTH="70%"
 314 ><TR
 315 ><TD
 316 ><PRE
 317 CLASS="PROGRAMLISTING"
 318 >typedef struct
 319 {
 320     <SPAN
 321 CLASS="TYPE"
 322 >cyg_handle_t</SPAN
 323 >        <TT
 324 CLASS="STRUCTFIELD"
 325 ><I
 326 >handle</I
 327 ></TT
 328 >;
 329     <SPAN
 330 CLASS="TYPE"
 331 >cyg_uint16</SPAN
 332 >          <TT
 333 CLASS="STRUCTFIELD"
 334 ><I
 335 >id</I
 336 ></TT
 337 >;
 338     <SPAN
 339 CLASS="TYPE"
 340 >cyg_uint32</SPAN
 341 >          <TT
 342 CLASS="STRUCTFIELD"
 343 ><I
 344 >state</I
 345 ></TT
 346 >;
 347     <SPAN
 348 CLASS="TYPE"
 349 >char</SPAN
 350 >                <TT
 351 CLASS="STRUCTFIELD"
 352 ><I
 353 >*name</I
 354 ></TT
 355 >;
 356     <SPAN
 357 CLASS="TYPE"
 358 >cyg_priority_t</SPAN
 359 >      <TT
 360 CLASS="STRUCTFIELD"
 361 ><I
 362 >set_pri</I
 363 ></TT
 364 >;
 365     <SPAN
 366 CLASS="TYPE"
 367 >cyg_priority_t</SPAN
 368 >      <TT
 369 CLASS="STRUCTFIELD"
 370 ><I
 371 >cur_pri</I
 372 ></TT
 373 >;
 374     <SPAN
 375 CLASS="TYPE"
 376 >cyg_addrword_t</SPAN
 377 >      <TT
 378 CLASS="STRUCTFIELD"
 379 ><I
 380 >stack_base</I
 381 ></TT
 382 >;
 383     <SPAN
 384 CLASS="TYPE"
 385 >cyg_uint32</SPAN
 386 >          <TT
 387 CLASS="STRUCTFIELD"
 388 ><I
 389 >stack_size</I
 390 ></TT
 391 >;
 392     <SPAN
 393 CLASS="TYPE"
 394 >cyg_uint32</SPAN
 395 >          <TT
 396 CLASS="STRUCTFIELD"
 397 ><I
 398 >stack_used</I
 399 ></TT
 400 >;
 401 } cyg_thread_info;</PRE
 402 ></TD
 403 ></TR
 404 ></TABLE
 405 >
 406     </P
 407 ><P
 408 ><TT
 409 CLASS="FUNCTION"
 410 >cyg_thread_find</TT
 411 > returns a handle for the thread
 412 whose ID is <TT
 413 CLASS="PARAMETER"
 414 ><I
 415 >id</I
 416 ></TT
 417 >. If no such thread exists, a
 418 zero handle is returned.
 419     </P
 420 ></DIV
 421 ><DIV
 422 CLASS="REFSECT1"
 423 ><A
 424 NAME="KERNEL-THREAD-INFO-CONTEXT"
 425 ></A
 426 ><H2
 427 >Valid contexts</H2
 428 ><P
 429 ><TT
 430 CLASS="FUNCTION"
 431 >cyg_thread_self</TT
 432 > may only be called from thread
 433 context. <TT
 434 CLASS="FUNCTION"
 435 >cyg_thread_idle_thread</TT
 436 > may be called
 437 from thread or DSR context, but only after the system has been
 438 initialized. <TT
 439 CLASS="FUNCTION"
 440 >cyg_thread_get_stack_base</TT
 441 >,
 442 <TT
 443 CLASS="FUNCTION"
 444 >cyg_thread_get_stack_size</TT
 445 > and
 446 <TT
 447 CLASS="FUNCTION"
 448 >cyg_thread_measure_stack_usage</TT
 449 > may be called
 450 any time after the specified thread has been created, but measuring
 451 stack usage involves looping over at least part of the thread's stack
 452 so this should normally only be done from thread context.
 453       </P
 454 ></DIV
 455 ><DIV
 456 CLASS="REFSECT1"
 457 ><A
 458 NAME="KERNEL-THREAD-INFO-EXAMPLES"
 459 ></A
 460 ><H2
 461 >Examples</H2
 462 ><P
 463 >A simple example of the use of the
 464 <TT
 465 CLASS="FUNCTION"
 466 >cyg_thread_get_next</TT
 467 > and
 468 <TT
 469 CLASS="FUNCTION"
 470 >cyg_thread_get_info</TT
 471 > follows:
 472       </P
 473 ><TABLE
 474 BORDER="5"
 475 BGCOLOR="#E0E0F0"
 476 WIDTH="70%"
 477 ><TR
 478 ><TD
 479 ><PRE
 480 CLASS="PROGRAMLISTING"
 481 >&#13;#include &lt;cyg/kernel/kapi.h&gt;
 482 #include &lt;stdio.h&gt;
 483
 484 void show_threads(void)
 485 {
 486     cyg_handle_t thread = 0;
 487     cyg_uint16 id = 0;
 488
 489     while( cyg_thread_get_next( &amp;thread, &amp;id ) )
 490     {
 491         cyg_thread_info info;
 492
 493         if( !cyg_thread_get_info( thread, id, &amp;info ) )
 494             break;
 495
 496         printf("ID: %04x name: %10s pri: %d\n",
 497                 info.id, info.name?info.name:"----", info.set_pri );
 498     }
 499 }
 500
 501       </PRE
 502 ></TD
 503 ></TR
 504 ></TABLE
 505 ></DIV
 506 ><DIV
 507 CLASS="NAVFOOTER"
 508 ><HR
 509 ALIGN="LEFT"
 510 WIDTH="100%"><TABLE
 511 SUMMARY="Footer navigation table"
 512 WIDTH="100%"
 513 BORDER="0"
 514 CELLPADDING="0"
 515 CELLSPACING="0"
 516 ><TR
 517 ><TD
 518 WIDTH="33%"
 519 ALIGN="left"
 520 VALIGN="top"
 521 ><A
 522 HREF="kernel-thread-create.html"
 523 ACCESSKEY="P"
 524 >Prev</A
 525 ></TD
 526 ><TD
 527 WIDTH="34%"
 528 ALIGN="center"
 529 VALIGN="top"
 530 ><A
 531 HREF="ecos-ref.html"
 532 ACCESSKEY="H"
 533 >Home</A
 534 ></TD
 535 ><TD
 536 WIDTH="33%"
 537 ALIGN="right"
 538 VALIGN="top"
 539 ><A
 540 HREF="kernel-thread-control.html"
 541 ACCESSKEY="N"
 542 >Next</A
 543 ></TD
 544 ></TR
 545 ><TR
 546 ><TD
 547 WIDTH="33%"
 548 ALIGN="left"
 549 VALIGN="top"
 550 >Thread creation</TD
 551 ><TD
 552 WIDTH="34%"
 553 ALIGN="center"
 554 VALIGN="top"
 555 ><A
 556 HREF="kernel.html"
 557 ACCESSKEY="U"
 558 >Up</A
 559 ></TD
 560 ><TD
 561 WIDTH="33%"
 562 ALIGN="right"
 563 VALIGN="top"
 564 >Thread control</TD
 565 ></TR
 566 ></TABLE
 567 ></DIV
 568 ></BODY
 569 ></HTML
 570 >