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. -->
12 >Thread information</TITLE
13 ><meta name="MSSmartTagsPreventParsing" content="TRUE">
16 CONTENT="Modular DocBook HTML Stylesheet Version 1.76b+
19 TITLE="eCos Reference Manual"
20 HREF="ecos-ref.html"><LINK
22 TITLE="The eCos Kernel"
23 HREF="kernel.html"><LINK
25 TITLE="Thread creation"
26 HREF="kernel-thread-create.html"><LINK
28 TITLE="Thread control"
29 HREF="kernel-thread-control.html"></HEAD
40 SUMMARY="Header navigation table"
49 >eCos Reference Manual</TH
57 HREF="kernel-thread-create.html"
71 HREF="kernel-thread-control.html"
82 NAME="KERNEL-THREAD-INFO">Thread information</H1
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 -- Get basic thread information</DIV
92 CLASS="REFSYNOPSISDIV"
108 CLASS="FUNCSYNOPSISINFO"
109 >#include <cyg/kernel/kapi.h>
118 >cyg_handle_t cyg_thread_self</CODE
125 >cyg_handle_t cyg_thread_idle_thread</CODE
132 >cyg_addrword_t cyg_thread_get_stack_base</CODE
133 >(cyg_handle_t thread);</CODE
139 >cyg_uint32 cyg_thread_get_stack_size</CODE
140 >(cyg_handle_t thread);</CODE
146 >cyg_uint32 cyg_thread_measure_stack_usage</CODE
147 >(cyg_handle_t thread);</CODE
153 >cyg_bool cyg_thread_get_next</CODE
154 >(cyg_handle_t *thread, cyg_uint16 *id);</CODE
160 >cyg_bool cyg_thread_get_info</CODE
161 >(cyg_handle_t thread, cyg_uint16 id, cyg_thread_info *info);</CODE
167 >cyg_handle_t cyg_thread_find</CODE
168 >(cyg_uint16 id);</CODE
177 NAME="KERNEL-THREAD-INFO-DESCRIPTION"
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.
190 > returns a handle corresponding
191 to the current thread. It will be the same as the value filled in by
194 >cyg_thread_create</TT
195 > when the current thread was
196 created. This handle can then be passed to other functions such as
199 >cyg_thread_get_priority</TT
205 >cyg_thread_idle_thread</TT
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
214 >cyg_thread_get_stack_base</TT
218 >cyg_thread_get_stack_size</TT
220 about a specific thread's stack. The values returned will match the
223 >cyg_thread_create</TT
230 >cyg_thread_measure_stack_usage</TT
232 if the configuration option
235 >CYGFUN_KERNEL_THREADS_STACK_MEASUREMENT</TT
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.
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
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
269 indicates the end of the list.
274 >cyg_thread_get_info</TT
278 >cyg_thread_info</SPAN
279 > structure with information about the
280 thread described by the <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
302 >cyg_thread_info</SPAN
303 > structure is defined as follows by
306 >cyg/kernel/kapi.h</TT
308 be extended in future with additional members, and so its size should
317 CLASS="PROGRAMLISTING"
358 >cyg_priority_t</SPAN
367 >cyg_priority_t</SPAN
376 >cyg_addrword_t</SPAN
401 } cyg_thread_info;</PRE
411 > returns a handle for the thread
417 >. If no such thread exists, a
418 zero handle is returned.
424 NAME="KERNEL-THREAD-INFO-CONTEXT"
432 > may only be called from thread
435 >cyg_thread_idle_thread</TT
437 from thread or DSR context, but only after the system has been
440 >cyg_thread_get_stack_base</TT
444 >cyg_thread_get_stack_size</TT
448 >cyg_thread_measure_stack_usage</TT
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.
458 NAME="KERNEL-THREAD-INFO-EXAMPLES"
463 >A simple example of the use of the
466 >cyg_thread_get_next</TT
470 >cyg_thread_get_info</TT
480 CLASS="PROGRAMLISTING"
481 > #include <cyg/kernel/kapi.h>
482 #include <stdio.h>
484 void show_threads(void)
486 cyg_handle_t thread = 0;
489 while( cyg_thread_get_next( &thread, &id ) )
491 cyg_thread_info info;
493 if( !cyg_thread_get_info( thread, id, &info ) )
496 printf("ID: %04x name: %10s pri: %d\n",
497 info.id, info.name?info.name:"----", info.set_pri );
511 SUMMARY="Footer navigation table"
522 HREF="kernel-thread-create.html"
540 HREF="kernel-thread-control.html"