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.