URL
https://opencores.org/ocsvn/openrisc_me/openrisc_me/trunk
Subversion Repositories openrisc_me
[/] [openrisc/] [trunk/] [rtos/] [ecos-2.0/] [doc/] [html/] [ref/] [kernel-thread-info.html] - Rev 441
Go to most recent revision | Compare with Previous | Blame | View Log
<!-- Copyright (C) 2003 Red Hat, Inc. --> <!-- This material may be distributed only subject to the terms --> <!-- and conditions set forth in the Open Publication License, v1.0 --> <!-- or later (the latest version is presently available at --> <!-- http://www.opencontent.org/openpub/). --> <!-- Distribution of the work or derivative of the work in any --> <!-- standard (paper) book form is prohibited unless prior --> <!-- permission is obtained from the copyright holder. --> <HTML ><HEAD ><TITLE >Thread information</TITLE ><meta name="MSSmartTagsPreventParsing" content="TRUE"> <META NAME="GENERATOR" CONTENT="Modular DocBook HTML Stylesheet Version 1.76b+ "><LINK REL="HOME" TITLE="eCos Reference Manual" HREF="ecos-ref.html"><LINK REL="UP" TITLE="The eCos Kernel" HREF="kernel.html"><LINK REL="PREVIOUS" TITLE="Thread creation" HREF="kernel-thread-create.html"><LINK REL="NEXT" TITLE="Thread control" HREF="kernel-thread-control.html"></HEAD ><BODY CLASS="REFENTRY" BGCOLOR="#FFFFFF" TEXT="#000000" LINK="#0000FF" VLINK="#840084" ALINK="#0000FF" ><DIV CLASS="NAVHEADER" ><TABLE SUMMARY="Header navigation table" WIDTH="100%" BORDER="0" CELLPADDING="0" CELLSPACING="0" ><TR ><TH COLSPAN="3" ALIGN="center" >eCos Reference Manual</TH ></TR ><TR ><TD WIDTH="10%" ALIGN="left" VALIGN="bottom" ><A HREF="kernel-thread-create.html" ACCESSKEY="P" >Prev</A ></TD ><TD WIDTH="80%" ALIGN="center" VALIGN="bottom" ></TD ><TD WIDTH="10%" ALIGN="right" VALIGN="bottom" ><A HREF="kernel-thread-control.html" ACCESSKEY="N" >Next</A ></TD ></TR ></TABLE ><HR ALIGN="LEFT" WIDTH="100%"></DIV ><H1 ><A NAME="KERNEL-THREAD-INFO">Thread information</H1 ><DIV CLASS="REFNAMEDIV" ><A NAME="AEN356" ></A ><H2 >Name</H2 >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 ><DIV CLASS="REFSYNOPSISDIV" ><A NAME="AEN366"><H2 >Synopsis</H2 ><DIV CLASS="FUNCSYNOPSIS" ><A NAME="AEN367"><P ></P ><TABLE BORDER="5" BGCOLOR="#E0E0F0" WIDTH="70%" ><TR ><TD ><PRE CLASS="FUNCSYNOPSISINFO" >#include <cyg/kernel/kapi.h> </PRE ></TD ></TR ></TABLE ><P ><CODE ><CODE CLASS="FUNCDEF" >cyg_handle_t cyg_thread_self</CODE >(void);</CODE ></P ><P ><CODE ><CODE CLASS="FUNCDEF" >cyg_handle_t cyg_thread_idle_thread</CODE >(void);</CODE ></P ><P ><CODE ><CODE CLASS="FUNCDEF" >cyg_addrword_t cyg_thread_get_stack_base</CODE >(cyg_handle_t thread);</CODE ></P ><P ><CODE ><CODE CLASS="FUNCDEF" >cyg_uint32 cyg_thread_get_stack_size</CODE >(cyg_handle_t thread);</CODE ></P ><P ><CODE ><CODE CLASS="FUNCDEF" >cyg_uint32 cyg_thread_measure_stack_usage</CODE >(cyg_handle_t thread);</CODE ></P ><P ><CODE ><CODE CLASS="FUNCDEF" >cyg_bool cyg_thread_get_next</CODE >(cyg_handle_t *thread, cyg_uint16 *id);</CODE ></P ><P ><CODE ><CODE CLASS="FUNCDEF" >cyg_bool cyg_thread_get_info</CODE >(cyg_handle_t thread, cyg_uint16 id, cyg_thread_info *info);</CODE ></P ><P ><CODE ><CODE CLASS="FUNCDEF" >cyg_handle_t cyg_thread_find</CODE >(cyg_uint16 id);</CODE ></P ><P ></P ></DIV ></DIV ><DIV CLASS="REFSECT1" ><A NAME="KERNEL-THREAD-INFO-DESCRIPTION" ></A ><H2 >Description</H2 ><P >These functions can be used to obtain some basic information about various threads in the system. Typically they serve little or no purpose in real applications, but they can be useful during debugging. </P ><P ><TT CLASS="FUNCTION" >cyg_thread_self</TT > returns a handle corresponding to the current thread. It will be the same as the value filled in by <TT CLASS="FUNCTION" >cyg_thread_create</TT > when the current thread was created. This handle can then be passed to other functions such as <TT CLASS="FUNCTION" >cyg_thread_get_priority</TT >. </P ><P ><TT CLASS="FUNCTION" >cyg_thread_idle_thread</TT > returns the handle corresponding to the idle thread. This thread is created automatically by the kernel, so application-code has no other way of getting hold of this information. </P ><P ><TT CLASS="FUNCTION" >cyg_thread_get_stack_base</TT > and <TT CLASS="FUNCTION" >cyg_thread_get_stack_size</TT > return information about a specific thread's stack. The values returned will match the values passed to <TT CLASS="FUNCTION" >cyg_thread_create</TT > when this thread was created. </P ><P ><TT CLASS="FUNCTION" >cyg_thread_measure_stack_usage</TT > is only available if the configuration option <TT CLASS="VARNAME" >CYGFUN_KERNEL_THREADS_STACK_MEASUREMENT</TT > is enabled. The return value is the maximum number of bytes of stack space used so far by the specified thread. Note that this should not be considered a true upper bound, for example it is possible that in the current test run the specified thread has not yet been interrupted at the deepest point in the function call graph. Never the less the value returned can give some useful indication of the thread's stack requirements. </P ><P ><TT CLASS="FUNCTION" >cyg_thread_get_next</TT > is used to enumerate all the current threads in the system. It should be called initially with the locations pointed to by <TT CLASS="PARAMETER" ><I >thread</I ></TT > and <TT CLASS="PARAMETER" ><I >id</I ></TT > set to zero. On return these will be set to the handle and ID of the first thread. On subsequent calls, these parameters should be left set to the values returned by the previous call. The handle and ID of the next thread in the system will be installed each time, until a <TT CLASS="LITERAL" >false</TT > return value indicates the end of the list. </P ><P ><TT CLASS="FUNCTION" >cyg_thread_get_info</TT > fills in the <SPAN CLASS="TYPE" >cyg_thread_info</SPAN > structure with information about the thread described by the <TT CLASS="PARAMETER" ><I >thread</I ></TT > and <TT CLASS="PARAMETER" ><I >id</I ></TT > arguments. The information returned includes the thread's handle and id, its state and name, priorities and stack parameters. If the thread does not exist the function returns <TT CLASS="LITERAL" >false</TT >. </P ><P >The <SPAN CLASS="TYPE" >cyg_thread_info</SPAN > structure is defined as follows by <<TT CLASS="FILENAME" >cyg/kernel/kapi.h</TT >>, but may be extended in future with additional members, and so its size should not be relied upon: <TABLE BORDER="5" BGCOLOR="#E0E0F0" WIDTH="70%" ><TR ><TD ><PRE CLASS="PROGRAMLISTING" >typedef struct { <SPAN CLASS="TYPE" >cyg_handle_t</SPAN > <TT CLASS="STRUCTFIELD" ><I >handle</I ></TT >; <SPAN CLASS="TYPE" >cyg_uint16</SPAN > <TT CLASS="STRUCTFIELD" ><I >id</I ></TT >; <SPAN CLASS="TYPE" >cyg_uint32</SPAN > <TT CLASS="STRUCTFIELD" ><I >state</I ></TT >; <SPAN CLASS="TYPE" >char</SPAN > <TT CLASS="STRUCTFIELD" ><I >*name</I ></TT >; <SPAN CLASS="TYPE" >cyg_priority_t</SPAN > <TT CLASS="STRUCTFIELD" ><I >set_pri</I ></TT >; <SPAN CLASS="TYPE" >cyg_priority_t</SPAN > <TT CLASS="STRUCTFIELD" ><I >cur_pri</I ></TT >; <SPAN CLASS="TYPE" >cyg_addrword_t</SPAN > <TT CLASS="STRUCTFIELD" ><I >stack_base</I ></TT >; <SPAN CLASS="TYPE" >cyg_uint32</SPAN > <TT CLASS="STRUCTFIELD" ><I >stack_size</I ></TT >; <SPAN CLASS="TYPE" >cyg_uint32</SPAN > <TT CLASS="STRUCTFIELD" ><I >stack_used</I ></TT >; } cyg_thread_info;</PRE ></TD ></TR ></TABLE > </P ><P ><TT CLASS="FUNCTION" >cyg_thread_find</TT > returns a handle for the thread whose ID is <TT CLASS="PARAMETER" ><I >id</I ></TT >. If no such thread exists, a zero handle is returned. </P ></DIV ><DIV CLASS="REFSECT1" ><A NAME="KERNEL-THREAD-INFO-CONTEXT" ></A ><H2 >Valid contexts</H2 ><P ><TT CLASS="FUNCTION" >cyg_thread_self</TT > may only be called from thread context. <TT CLASS="FUNCTION" >cyg_thread_idle_thread</TT > may be called from thread or DSR context, but only after the system has been initialized. <TT CLASS="FUNCTION" >cyg_thread_get_stack_base</TT >, <TT CLASS="FUNCTION" >cyg_thread_get_stack_size</TT > and <TT CLASS="FUNCTION" >cyg_thread_measure_stack_usage</TT > may be called any time after the specified thread has been created, but measuring stack usage involves looping over at least part of the thread's stack so this should normally only be done from thread context. </P ></DIV ><DIV CLASS="REFSECT1" ><A NAME="KERNEL-THREAD-INFO-EXAMPLES" ></A ><H2 >Examples</H2 ><P >A simple example of the use of the <TT CLASS="FUNCTION" >cyg_thread_get_next</TT > and <TT CLASS="FUNCTION" >cyg_thread_get_info</TT > follows: </P ><TABLE BORDER="5" BGCOLOR="#E0E0F0" WIDTH="70%" ><TR ><TD ><PRE CLASS="PROGRAMLISTING" > #include <cyg/kernel/kapi.h> #include <stdio.h> void show_threads(void) { cyg_handle_t thread = 0; cyg_uint16 id = 0; while( cyg_thread_get_next( &thread, &id ) ) { cyg_thread_info info; if( !cyg_thread_get_info( thread, id, &info ) ) break; printf("ID: %04x name: %10s pri: %d\n", info.id, info.name?info.name:"----", info.set_pri ); } } </PRE ></TD ></TR ></TABLE ></DIV ><DIV CLASS="NAVFOOTER" ><HR ALIGN="LEFT" WIDTH="100%"><TABLE SUMMARY="Footer navigation table" WIDTH="100%" BORDER="0" CELLPADDING="0" CELLSPACING="0" ><TR ><TD WIDTH="33%" ALIGN="left" VALIGN="top" ><A HREF="kernel-thread-create.html" ACCESSKEY="P" >Prev</A ></TD ><TD WIDTH="34%" ALIGN="center" VALIGN="top" ><A HREF="ecos-ref.html" ACCESSKEY="H" >Home</A ></TD ><TD WIDTH="33%" ALIGN="right" VALIGN="top" ><A HREF="kernel-thread-control.html" ACCESSKEY="N" >Next</A ></TD ></TR ><TR ><TD WIDTH="33%" ALIGN="left" VALIGN="top" >Thread creation</TD ><TD WIDTH="34%" ALIGN="center" VALIGN="top" ><A HREF="kernel.html" ACCESSKEY="U" >Up</A ></TD ><TD WIDTH="33%" ALIGN="right" VALIGN="top" >Thread control</TD ></TR ></TABLE ></DIV ></BODY ></HTML >
Go to most recent revision | Compare with Previous | Blame | View Log