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 creation</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
26 HREF="kernel-smp.html"><LINK
28 TITLE="Thread information"
29 HREF="kernel-thread-info.html"></HEAD
40 SUMMARY="Header navigation table"
49 >eCos Reference Manual</TH
57 HREF="kernel-smp.html"
71 HREF="kernel-thread-info.html"
82 NAME="KERNEL-THREAD-CREATE">Thread creation</H1
90 >cyg_thread_create -- Create a new thread</DIV
92 CLASS="REFSYNOPSISDIV"
108 CLASS="FUNCSYNOPSISINFO"
109 >#include <cyg/kernel/kapi.h>
118 >void cyg_thread_create</CODE
119 >(cyg_addrword_t sched_info, cyg_thread_entry_t* entry, cyg_addrword_t entry_data, char* name, void* stack_base, cyg_ucount32 stack_size, cyg_handle_t* handle, cyg_thread* thread);</CODE
128 NAME="KERNEL-THREAD-CREATE-DESCRIPTION"
135 >cyg_thread_create</TT
136 > function allows application
137 code and eCos packages to create new threads. In many applications
138 this only happens during system initialization and all required data
139 is allocated statically. However additional threads can be created at
140 any time, if necessary. A newly created thread is always in suspended
141 state and will not start running until it has been resumed via a call
144 >cyg_thread_resume</TT
145 >. Also, if threads are
146 created during system initialization then they will not start running
147 until the eCos scheduler has been started.
156 primarily for debugging purposes, making it easier to keep track of
160 > structure is associated with
161 which application-level thread. The kernel configuration option
164 >CYGVAR_KERNEL_THREADS_NAME</TT
165 > controls whether or not
166 this name is actually used.
169 >On creation each thread is assigned a unique handle, and this will be
170 stored in the location pointed at by the <TT
175 > argument. Subsequent operations on
176 this thread including the required
179 >cyg_thread_resume</TT
180 > should use this handle to
184 >The kernel requires a small amount of space for each thread, in the
188 > data structure, to hold
189 information such as the current state of that thread. To avoid any
190 need for dynamic memory allocation within the kernel this space has to
191 be provided by higher-level code, typically in the form of a static
204 NAME="KERNEL-THREAD-CREATE-ENTRY"
207 >Thread Entry Point</H2
209 >The entry point for a thread takes the form:
218 CLASS="PROGRAMLISTING"
220 thread_entry_function(cyg_addrword_t data)
229 >The second argument to <TT
231 >cyg_thread_create</TT
233 pointer to such a function. The third argument <TT
238 > is used to pass additional
239 data to the function. Typically this takes the form of a pointer to
240 some static data, or a small integer, or <TT
244 thread does not require any additional data.
247 >If the thread entry function ever returns then this is equivalent to
248 the thread calling <TT
252 the thread will no longer run again, it remains registered with the
253 scheduler. If the application needs to re-use the
257 > data structure then a call to
260 >cyg_thread_delete</TT
267 NAME="KERNEL-THREAD-CREATE-PRIORITIES"
270 >Thread Priorities</H2
278 provides additional information to the scheduler. The exact details
279 depend on the scheduler being used. For the bitmap and mlqueue
280 schedulers it is a small integer, typically in the range 0 to 31, with
281 0 being the highest priority. The lowest priority is normally used
282 only by the system's idle thread. The exact number of priorities is
283 controlled by the kernel configuration option
286 >CYGNUM_KERNEL_SCHED_PRIORITIES</TT
290 >It is the responsibility of the application developer to be aware of
291 the various threads in the system, including those created by eCos
292 packages, and to ensure that all threads run at suitable priorities.
293 For threads created by other packages the documentation provided by
294 those packages should indicate any requirements.
299 >cyg_thread_set_priority</TT
303 >cyg_thread_get_priority</TT
307 >cyg_thread_get_current_priority</TT
309 manipulate a thread's priority.
315 NAME="KERNEL-THREAD-CREATE-STACK"
318 >Stacks and Stack Sizes</H2
320 >Each thread needs its own stack for local variables and to keep track
321 of function calls and returns. Again it is expected that this stack is
322 provided by the calling code, usually in the form of static data, so
323 that the kernel does not need any dynamic memory allocation
326 >cyg_thread_create</TT
327 > takes two arguments
328 related to the stack, a pointer to the base of the stack and the total
329 size of this stack. On many processors stacks actually descend from the
330 top down, so the kernel will add the stack size to the base address to
331 determine the starting location.
334 >The exact stack size requirements for any given thread depend on a
335 number of factors. The most important is of course the code that will
336 be executed in the context of this code: if this involves significant
337 nesting of function calls, recursion, or large local arrays, then the
338 stack size needs to be set to a suitably high value. There are some
339 architectural issues, for example the number of cpu registers and the
340 calling conventions will have some effect on stack usage. Also,
341 depending on the configuration, it is possible that some other code
342 such as interrupt handlers will occasionally run on the current
343 thread's stack. This depends in part on configuration options such as
346 >CYGIMP_HAL_COMMON_INTERRUPTS_USE_INTERRUPT_STACK</TT
350 >CYGSEM_HAL_COMMON_INTERRUPTS_ALLOW_NESTING</TT
354 >Determining an application's actual stack size requirements is the
355 responsibility of the application developer, since the kernel cannot
356 know in advance what code a given thread will run. However, the system
357 does provide some hints about reasonable stack sizes in the form of
360 >CYGNUM_HAL_STACK_SIZE_MINIMUM</TT
364 >CYGNUM_HAL_STACK_SIZE_TYPICAL</TT
365 >. These are defined by
366 the appropriate HAL package. The <TT
370 appropriate for a thread that just runs a single function and makes
371 very simple system calls. Trying to create a thread with a smaller
372 stack than this is illegal. The <TT
376 appropriate for applications where application calls are nested no
377 more than half a dozen or so levels, and there are no large arrays on
381 >If the stack sizes are not estimated correctly and a stack overflow
382 occurs, the probably result is some form of memory corruption. This
383 can be very hard to track down. The kernel does contain some code to
384 help detect stack overflows, controlled by the configuration option
387 >CYGFUN_KERNEL_THREADS_STACK_CHECKING</TT
389 amount of space is reserved at the stack limit and filled with a
390 special signature: every time a thread context switch occurs this
391 signature is checked, and if invalid that is a good indication (but
392 not absolute proof) that a stack overflow has occurred. This form of
393 stack checking is enabled by default when the system is built with
394 debugging enabled. A related configuration option is
397 >CYGFUN_KERNEL_THREADS_STACK_MEASUREMENT</TT
399 this option means that a thread can call the function
402 >cyg_thread_measure_stack_usage</TT
404 maximum stack usage to date. Note that this is not necessarily the
405 true maximum because, for example, it is possible that in the current
406 run no interrupt occurred at the worst possible moment.
412 NAME="KERNEL-THREAD-CREATE-CONTEXT"
419 >cyg_thread_create</TT
420 > may be called during
421 initialization and from within thread context. It may not be called
428 NAME="KERNEL-THREAD-CREATE-EXAMPLE"
433 >A simple example of thread creation is shown below. This involves
434 creating five threads, one producer and four consumers or workers. The
435 threads are created in the system's
439 >: depending on the configuration it
440 might be more appropriate to do this elsewhere, for example inside
453 CLASS="PROGRAMLISTING"
454 >#include <cyg/hal/hal_arch.h>
455 #include <cyg/kernel/kapi.h>
457 // These numbers depend entirely on your application
458 #define NUMBER_OF_WORKERS 4
459 #define PRODUCER_PRIORITY 10
460 #define WORKER_PRIORITY 11
461 #define PRODUCER_STACKSIZE CYGNUM_HAL_STACK_SIZE_TYPICAL
462 #define WORKER_STACKSIZE (CYGNUM_HAL_STACK_SIZE_MINIMUM + 1024)
464 static unsigned char producer_stack[PRODUCER_STACKSIZE];
465 static unsigned char worker_stacks[NUMBER_OF_WORKERS][WORKER_STACKSIZE];
466 static cyg_handle_t producer_handle, worker_handles[NUMBER_OF_WORKERS];
467 static cyg_thread_t producer_thread, worker_threads[NUMBER_OF_WORKERS];
470 producer(cyg_addrword_t data)
476 worker(cyg_addrword_t data)
486 cyg_thread_create(PRODUCER_PRIORITY, &producer, 0, "producer",
487 producer_stack, PRODUCER_STACKSIZE,
488 &producer_handle, &producer_thread);
489 cyg_thread_resume(producer_handle);
490 for (i = 0; i < NUMBER_OF_WORKERS; i++) {
491 cyg_thread_create(WORKER_PRIORITY, &worker, i, "worker",
492 worker_stacks[i], WORKER_STACKSIZE,
493 &(worker_handles[i]), &(worker_threads[i]));
494 cyg_thread_resume(worker_handles[i]);
505 NAME="KERNEL-THREAD-CREATE-CXX"
508 >Thread Entry Points and C++</H2
510 >For code written in C++ the thread entry function must be either a
511 static member function of a class or an ordinary function outside any
512 class. It cannot be a normal member function of a class because such
513 member functions take an implicit additional argument
517 >, and the kernel has no way of knowing what
518 value to use for this argument. One way around this problem is to make
519 use of a special static member function, for example:
528 CLASS="PROGRAMLISTING"
531 void thread_function();
532 static void static_thread_aux(cyg_addrword_t);
536 fred::static_thread_aux(cyg_addrword_t objptr)
538 fred* object = static_cast<fred*>(objptr);
539 object->thread_function();
542 static fred instance;
548 cyg_thread_create( …,
549 &fred::static_thread_aux,
550 static_cast<cyg_addrword_t>(&instance),
559 >Effectively this uses the <TT
567 >cyg_thread_create</TT
572 > pointer. Unfortunately this approach does
573 require the use of some C++ casts, so some of the type safety that can
574 be achieved when programming in C++ is lost.
582 SUMMARY="Footer navigation table"
593 HREF="kernel-smp.html"
611 HREF="kernel-thread-info.html"
635 >Thread information</TD