kernel.sgml

ecos实时嵌入式操作系统

The exact stack size requirements for any given thread depend on a
number of factors. The most important is of course the code that will
be executed in the context of this code: if this involves significant
nesting of function calls, recursion, or large local arrays, then the
stack size needs to be set to a suitably high value. There are some
architectural issues, for example the number of cpu registers and the
calling conventions will have some effect on stack usage. Also,
depending on the configuration, it is possible that some other code
such as interrupt handlers will occasionally run on the current
thread's stack. This depends in part on configuration options such as
<varname>CYGIMP_HAL_COMMON_INTERRUPTS_USE_INTERRUPT_STACK</varname>
and <varname>CYGSEM_HAL_COMMON_INTERRUPTS_ALLOW_NESTING</varname>.
      </para>
      <para>
Determining an application's actual stack size requirements is the
responsibility of the application developer, since the kernel cannot
know in advance what code a given thread will run. However, the system
does provide some hints about reasonable stack sizes in the form of
two constants: <varname>CYGNUM_HAL_STACK_SIZE_MINIMUM</varname> and
<varname>CYGNUM_HAL_STACK_SIZE_TYPICAL</varname>. These are defined by
the appropriate HAL package. The <varname>MINIMUM</varname> value is
appropriate for a thread that just runs a single function and makes
very simple system calls. Trying to create a thread with a smaller
stack than this is illegal. The <varname>TYPICAL</varname> value is
appropriate for applications where application calls are nested no
more than half a dozen or so levels, and there are no large arrays on
the stack.
      </para>
      <para>
If the stack sizes are not estimated correctly and a stack overflow
occurs, the probably result is some form of memory corruption. This
can be very hard to track down. The kernel does contain some code to
help detect stack overflows, controlled by the configuration option
<varname>CYGFUN_KERNEL_THREADS_STACK_CHECKING</varname>: a small
amount of space is reserved at the stack limit and filled with a
special signature: every time a thread context switch occurs this
signature is checked, and if invalid that is a good indication (but
not absolute proof) that a stack overflow has occurred. This form of
stack checking is enabled by default when the system is built with
debugging enabled. A related configuration option is
<varname>CYGFUN_KERNEL_THREADS_STACK_MEASUREMENT</varname>: enabling
this option means that a thread can call the function
<function>cyg_thread_measure_stack_usage</function> to find out the
maximum stack usage to date. Note that this is not necessarily the
true maximum because, for example, it is possible that in the current
run no interrupt occurred at the worst possible moment.
      </para>
    </refsect1>

    <refsect1 id="kernel-thread-create-context"><title>Valid contexts</title>
      <para>
<function>cyg_thread_create</function> may be called during
initialization and from within thread context. It may not be called
from inside a DSR.
      </para>
    </refsect1>

    <refsect1 id="kernel-thread-create-example"><title>Example</title>
      <para>
A simple example of thread creation is shown below. This involves
creating five threads, one producer and four consumers or workers. The
threads are created in the system's
<function>cyg_user_start</function>: depending on the configuration it
might be more appropriate to do this elsewhere, for example inside
<function>main</function>.
      </para>
      <programlisting width=72>
#include &lt;cyg/hal/hal_arch.h&gt;
#include &lt;cyg/kernel/kapi.h&gt;

// These numbers depend entirely on your application
#define NUMBER_OF_WORKERS    4
#define PRODUCER_PRIORITY   10
#define WORKER_PRIORITY     11
#define PRODUCER_STACKSIZE  CYGNUM_HAL_STACK_SIZE_TYPICAL
#define WORKER_STACKSIZE    (CYGNUM_HAL_STACK_SIZE_MINIMUM + 1024)

static unsigned char producer_stack[PRODUCER_STACKSIZE];
static unsigned char worker_stacks[NUMBER_OF_WORKERS][WORKER_STACKSIZE];
static cyg_handle_t producer_handle, worker_handles[NUMBER_OF_WORKERS];
static cyg_thread_t producer_thread, worker_threads[NUMBER_OF_WORKERS];

static void
producer(cyg_addrword_t data)
{
    &hellip;
}

static void
worker(cyg_addrword_t data)
{
    &hellip;
}

void
cyg_user_start(void)
{
    int i;

    cyg_thread_create(PRODUCER_PRIORITY, &amp;producer, 0, "producer",
                      producer_stack, PRODUCER_STACKSIZE,
                      &amp;producer_handle, &amp;producer_thread);
    cyg_thread_resume(producer_handle);
    for (i = 0; i < NUMBER_OF_WORKERS; i++) {
        cyg_thread_create(WORKER_PRIORITY, &amp;worker, i, "worker",
                          worker_stacks[i], WORKER_STACKSIZE,
                          &amp;(worker_handles[i]), &amp;(worker_threads[i]));
        cyg_thread_resume(worker_handles[i]);
    }
}
      </programlisting>
    </refsect1>


    <refsect1 id="kernel-thread-create-cxx"><title>Thread Entry Points and C++</title>
      <para>
For code written in C++ the thread entry function must be either a
static member function of a class or an ordinary function outside any
class. It cannot be a normal member function of a class because such
member functions take an implicit additional argument
<varname>this</varname>, and the kernel has no way of knowing what
value to use for this argument. One way around this problem is to make
use of a special static member function, for example:
      </para>
      <programlisting width=72>
class fred {
  public:
    void thread_function();
    static void static_thread_aux(cyg_addrword_t);
};

void
fred::static_thread_aux(cyg_addrword_t objptr)
{
    fred* object = static_cast&lt;fred*&gt;(objptr);
    object-&gt;thread_function();
}

static fred instance;

extern "C" void
cyg_start( void )
{
    &hellip;
    cyg_thread_create( &hellip;,
                      &amp;fred::static_thread_aux,
                      static_cast&lt;cyg_addrword_t&gt;(&amp;instance),
                      &hellip;);
    &hellip;
}
      </programlisting>
      <para>
Effectively this uses the <parameter
class="function">entry_data</parameter> argument to
<function>cyg_thread_create</function> to hold the
<varname>this</varname> pointer. Unfortunately this approach does
require the use of some C++ casts, so some of the type safety that can
be achieved when programming in C++ is lost.
      </para>
    </refsect1>

  </refentry>

<!-- }}} -->
<!-- {{{ Thread info                    -->

  <refentry id="kernel-thread-info">

    <refmeta>
    <refentrytitle>Thread information</refentrytitle>
    </refmeta>

    <refnamediv>
      <refname>cyg_thread_self</refname>
      <refname>cyg_thread_idle_thread</refname>
      <refname>cyg_thread_get_stack_base</refname>
      <refname>cyg_thread_get_stack_size</refname>
      <refname>cyg_thread_measure_stack_usage</refname>
      <refname>cyg_thread_get_next</refname>
      <refname>cyg_thread_get_info</refname>
      <refname>cyg_thread_find</refname>
      <refpurpose>Get basic thread information</refpurpose>
    </refnamediv>

    <refsynopsisdiv>
      <funcsynopsis>
	<funcsynopsisinfo>
#include &lt;cyg/kernel/kapi.h&gt;    
	</funcsynopsisinfo>
        <funcprototype>
          <funcdef>cyg_handle_t <function>cyg_thread_self</function></funcdef>
          <void>
        </funcprototype>
        <funcprototype>
          <funcdef>cyg_handle_t <function>cyg_thread_idle_thread</function></funcdef>
          <void>
        </funcprototype>
        <funcprototype>
          <funcdef>cyg_addrword_t <function>cyg_thread_get_stack_base</function></funcdef>
          <paramdef>cyg_handle_t <parameter>thread</parameter></paramdef>
        </funcprototype>
        <funcprototype>
          <funcdef>cyg_uint32 <function>cyg_thread_get_stack_size</function></funcdef>
          <paramdef>cyg_handle_t <parameter>thread</parameter></paramdef>
        </funcprototype>
        <funcprototype>
          <funcdef>cyg_uint32 <function>cyg_thread_measure_stack_usage</function></funcdef>
          <paramdef>cyg_handle_t <parameter>thread</parameter></paramdef>
        </funcprototype>        
        <funcprototype>
          <funcdef>cyg_bool <function>cyg_thread_get_next</function></funcdef>
          <paramdef>cyg_handle_t *<parameter>thread</parameter></paramdef>
          <paramdef>cyg_uint16 *<parameter>id</parameter></paramdef>
        </funcprototype>        
        <funcprototype>
          <funcdef>cyg_bool <function>cyg_thread_get_info</function></funcdef>
          <paramdef>cyg_handle_t <parameter>thread</parameter></paramdef>
          <paramdef>cyg_uint16 <parameter>id</parameter></paramdef>
          <paramdef>cyg_thread_info *<parameter>info</parameter></paramdef>
        </funcprototype>        
        <funcprototype>
          <funcdef>cyg_handle_t <function>cyg_thread_find</function></funcdef>
          <paramdef>cyg_uint16 <parameter>id</parameter></paramdef>
        </funcprototype>        
      </funcsynopsis>
    </refsynopsisdiv>

    <refsect1 id="kernel-thread-info-description"><title>Description</title>
      <para>
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.
      </para>
      <para>
<function>cyg_thread_self</function> returns a handle corresponding
to the current thread. It will be the same as the value filled in by
<function>cyg_thread_create</function> when the current thread was
created. This handle can then be passed to other functions such as
<function>cyg_thread_get_priority</function>.
      </para>
      <para>
<function>cyg_thread_idle_thread</function> 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.
      </para>
      <para>
<function>cyg_thread_get_stack_base</function> and
<function>cyg_thread_get_stack_size</function> return information
about a specific thread's stack. The values returned will match the
values passed to <function>cyg_thread_create</function> when this
thread was created.
      </para>
      <para>
<function>cyg_thread_measure_stack_usage</function> is only available
if the configuration option
<varname>CYGFUN_KERNEL_THREADS_STACK_MEASUREMENT</varname> 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.
      </para>
      <para>
<function>cyg_thread_get_next</function> is used to enumerate all the
current threads in the system. It should be called initially with the
locations pointed to by <parameter>thread</parameter> and
<parameter>id</parameter> 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