OpenCores
URL https://opencores.org/ocsvn/openrisc/openrisc/trunk

Subversion Repositories openrisc

[/] [openrisc/] [trunk/] [rtos/] [ecos-2.0/] [doc/] [html/] [ref/] [kernel-thread-info.html] - Blame information for rev 28

Go to most recent revision | Details | Compare with Previous | View Log

Line No. Rev Author Line
1 28 unneback 
<!-- 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 
>

powered by: WebSVN 2.1.0

© copyright 1999-2024 OpenCores.org, equivalent to Oliscience, all rights reserved. OpenCores®, registered trademark.