Mercurial > ecos

comparison packages/kernel/current/include/thread.hxx @ 0:3111d98ba7b3 ecos-v1_1-release

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Initial commit of eCos version 1.1
author jlarmour
date Tue, 11 May 1999 11:16:07 +0000
parents
children 443894e2e912
comparison
equal deleted inserted replaced
-1:000000000000 0:3111d98ba7b3
1 #ifndef CYGONCE_KERNEL_THREAD_HXX
2 #define CYGONCE_KERNEL_THREAD_HXX
3
4 //==========================================================================
5 //
6 // thread.hxx
7 //
8 // Thread class declarations
9 //
10 //==========================================================================
11 //####COPYRIGHTBEGIN####
12 //
13 // -------------------------------------------
14 // The contents of this file are subject to the Cygnus eCos Public License
15 // Version 1.0 (the "License"); you may not use this file except in
16 // compliance with the License. You may obtain a copy of the License at
17 // http://sourceware.cygnus.com/ecos
18 //
19 // Software distributed under the License is distributed on an "AS IS"
20 // basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See the
21 // License for the specific language governing rights and limitations under
22 // the License.
23 //
24 // The Original Code is eCos - Embedded Cygnus Operating System, released
25 // September 30, 1998.
26 //
27 // The Initial Developer of the Original Code is Cygnus. Portions created
28 // by Cygnus are Copyright (C) 1998 Cygnus Solutions. All Rights Reserved.
29 // -------------------------------------------
30 //
31 //####COPYRIGHTEND####
32 //==========================================================================
33 //#####DESCRIPTIONBEGIN####
34 //
35 // Author(s): nickg
36 // Contributors: nickg
37 // Date: 1997-09-09
38 // Purpose: Define Thread class interfaces
39 // Description: The classes defined here collectively implement the
40 // internal API used to create, configure and manage threads.
41 // Usage: #include <cyg/kernel/thread.hxx>
42 //
43 //####DESCRIPTIONEND####
44 //
45 //==========================================================================
46
47 #include <cyg/kernel/ktypes.h>
48 #include <cyg/infra/cyg_ass.h> // assertion macros
49 #include <cyg/kernel/sched.hxx>
50 #include <cyg/kernel/clock.hxx>
51 #include <cyg/kernel/except.hxx>
52
53 #include <cyg/hal/hal_arch.h>
54
55 // -------------------------------------------------------------------------
56 // Miscellaneous types
57
58 typedef void cyg_thread_entry(CYG_ADDRWORD data);// Thread entry point function
59
60 // -------------------------------------------------------------------------
61 // Hardware thread interface.
62 // The implementation of this class is provided by the HAL.
63
64 class Cyg_HardwareThread
65 {
66 friend class Cyg_Scheduler;
67
68 protected:
69
70 CYG_ADDRESS stack_base; // pointer to base of stack area
71
72 cyg_uint32 stack_size; // size of stack area in bytes
73
74 #ifdef CYGFUN_KERNEL_THREADS_STACK_LIMIT
75 CYG_ADDRESS stack_limit; // movable stack limit
76 #endif
77
78 CYG_ADDRESS stack_ptr; // pointer to saved state on stack
79
80 cyg_thread_entry *entry_point; // main entry point (code pointer!)
81
82 CYG_ADDRWORD entry_data; // entry point argument
83
84 #ifdef CYGDBG_KERNEL_DEBUG_GDB_THREAD_SUPPORT
85
86 HAL_SavedRegisters *saved_context; // If non-zero, this points at a more
87 // interesting context than stack_ptr.
88 #endif
89
90 Cyg_HardwareThread(
91 cyg_thread_entry *entry_point, // entry point function
92 CYG_ADDRWORD entry_data, // entry data
93 cyg_ucount32 stack_size = 0, // stack size, 0 = use default
94 CYG_ADDRESS stack_base = 0 // stack base, NULL = allocate
95 );
96
97 // Thread entry point. This is where all threads begin execution.
98 // This routine does a little housekeeping and then call the main
99 // entry_point specified above.
100 static void thread_entry(Cyg_Thread *thread);
101
102 // Initialize the context of the thread to start execution at thread_entry
103 void init_context( Cyg_Thread *thread );
104
105 // Save current thread's context and load that of the given next thread.
106 void switch_context(Cyg_HardwareThread *next);
107
108 // load this thread's context without saving current context
109 void load_context();
110
111 // attach a stack to this thread
112 void attach_stack(CYG_ADDRESS stack, cyg_uint32 stack_size);
113
114 // detach the stack from this thread
115 CYG_ADDRESS detach_stack();
116
117 // Adjust the thread's saved state to call the exception
118 // handler when next executed.
119 void prepare_exception (
120 cyg_exception_handler *exception_handler,
121 CYG_ADDRWORD exception_data,
122 cyg_code exception_number,
123 CYG_ADDRWORD exception_info
124 );
125
126 public:
127
128 CYGDBG_DEFINE_CHECK_THIS
129
130 // Get and set entry_data.
131
132 void set_entry_data( CYG_ADDRWORD data );
133
134 CYG_ADDRWORD get_entry_data();
135
136 #ifdef CYGDBG_KERNEL_DEBUG_GDB_THREAD_SUPPORT
137 // Return the current saved state for this thread.
138 HAL_SavedRegisters *get_saved_context();
139
140 // Set the saved context pointer.
141 void set_saved_context(HAL_SavedRegisters *ctx);
142 #endif
143
144 // get the size/base of this thread's stack
145 CYG_ADDRESS get_stack_base();
146
147 cyg_uint32 get_stack_size();
148
149 #ifdef CYGFUN_KERNEL_THREADS_STACK_LIMIT
150 // Allocate some memory at the lower end of the stack
151 // by moving the stack limit pointer.
152
153 void *increment_stack_limit( cyg_ucount32 size);
154
155 CYG_ADDRESS get_stack_limit();
156 #endif
157 };
158
159 // -------------------------------------------------------------------------
160 // Per-thread timer support class.
161 // This is only included when required.
162
163 #ifdef CYGFUN_KERNEL_THREADS_TIMER
164
165 class Cyg_ThreadTimer
166 : public Cyg_Alarm
167 {
168 friend class Cyg_Thread;
169
170 // Pointer to current thread
171 Cyg_Thread *thread;
172
173 // Constructor
174 Cyg_ThreadTimer(
175 Cyg_Thread *thread
176 );
177
178 // Alarm function
179 static void alarm( Cyg_Alarm *alarm, CYG_ADDRWORD data);
180
181 CYGDBG_DEFINE_CHECK_THIS
182
183 };
184
185 #endif
186
187 // -------------------------------------------------------------------------
188 // Main Thread class.
189 // This provides the public API for controlling threads.
190
191 class Cyg_Thread
192 : public Cyg_HardwareThread, // provides hardware abstractions
193 public Cyg_SchedThread // provides scheduling abstractions
194 {
195 friend class Cyg_Scheduler;
196 friend void deliver_exception( CYG_WORD code, CYG_ADDRWORD data );
197
198 // The following definitions are used by all variants of the
199 // basic thread object.
200
201 public:
202 enum { // Thread state values
203
204 RUNNING = 0, // Thread is runnable or running
205 SLEEPING = 1, // Thread is waiting for something to happen
206 COUNTSLEEP = 2, // Sleep in counted manner
207 SUSPENDED = 4, // Suspend count is non-zero
208 CREATING = 8, // Thread is being created
209 EXITED = 16, // Thread has exited
210
211 // This is the set of bits that must be cleared by a generic
212 // wake() or release().
213 SLEEPSET = (SLEEPING | COUNTSLEEP)
214 };
215
216 private:
217 // Current thread state, a logical OR of the above values.
218 // Only if this word is zero can the thread execute.
219 cyg_uint32 state;
220
221 // Suspension counter, if > 0, the thread is suspended
222 cyg_ucount32 suspend_count;
223
224 // Wakeup counter, if > 0, sleep will not sleep, just decrement
225 cyg_ucount32 wakeup_count;
226
227 // A word of data used in syncronization object to communicate
228 // information between sleepers and wakers.
229 CYG_ADDRWORD wait_info;
230
231 // Unique thread id assigned on creation
232 cyg_uint16 unique_id;
233
234 #ifdef CYGPKG_KERNEL_EXCEPTIONS
235
236 // If exceptions are supported, define an exception control
237 // object that will be used to manage and deliver them. If
238 // exceptions are global there is a single static instance
239 // of this object, if they are per-thread then there is one
240 // for each thread.
241 private:
242
243 #ifdef CYGSEM_KERNEL_EXCEPTIONS_GLOBAL
244 static
245 #endif
246 Cyg_Exception_Control exception_control;
247
248 public:
249
250 static void register_exception(
251 cyg_code exception_number, // exception number
252 cyg_exception_handler handler, // handler function
253 CYG_ADDRWORD data, // data argument
254 cyg_exception_handler **old_handler, // handler function
255 CYG_ADDRWORD *old_data // data argument
256 );
257
258 static void deregister_exception(
259 cyg_code exception_number // exception number
260 );
261
262 void deliver_exception(
263 cyg_code exception_number, // exception being raised
264 CYG_ADDRWORD exception_info // exception specific info
265 );
266
267 #endif
268
269
270 public:
271
272 CYGDBG_DEFINE_CHECK_THIS
273
274 // Constructor, Initialize the thread structure. The thread is
275 // created in suspended state, and needs to be resumed to execute.
276 // It is also started at some (configurable) default priority, which
277 // may need to be changed before calling resume.
278
279 Cyg_Thread (
280 cyg_thread_entry *entry, // entry point function
281 CYG_ADDRWORD entry_data, // entry data
282 cyg_ucount32 stack_size = 0, // stack size, 0 = use default
283 CYG_ADDRESS stack_base = 0 // stack base, NULL = allocate
284 );
285
286 Cyg_Thread (
287 CYG_ADDRWORD sched_info, // Scheduling parameter(s)
288 cyg_thread_entry *entry, // entry point function
289 CYG_ADDRWORD entry_data, // entry data
290 char *name, // thread name
291 CYG_ADDRESS stack_base = 0, // stack base, NULL = allocate
292 cyg_ucount32 stack_size = 0 // stack size, 0 = use default
293 );
294
295 // Re-initialize the thread back to it's initial state.
296 void Cyg_Thread::reinitialize();
297
298 ~Cyg_Thread();
299
300 // The following are invoked implicitly on the current thread,
301 // hence they are static member functions.
302
303 static void sleep(); // Put thread to sleep
304
305 static void counted_sleep();// Decrement counter or put
306 // thread to sleep
307 #ifdef CYGFUN_KERNEL_THREADS_TIMER
308 static void counted_sleep( cyg_tick_count delay );
309 // ...for delay ticks
310 #endif
311
312 static void exit(); // Terminate thread
313
314 static void yield(); // Yield CPU to another thread
315
316 #ifdef CYGSEM_KERNEL_SCHED_MLQUEUE
317 static void rotate_queue( cyg_priority pri );
318 // Rotate that run queue
319 #endif
320
321 static Cyg_Thread *self(); // Return current thread
322
323
324 // The following are called on threads other than the current one.
325
326 void wake(); // Wake this thread from sleep.
327
328 void counted_wake(); // Increment counter or wake thread
329 cyg_uint32 cancel_counted_wake();
330 // Cancel counted wakeups for this
331 // thread and return how many were
332 // pending
333
334 void suspend(); // Suspend this thread: increment counter and
335 // deschedule.
336
337 void resume(); // Resume this thread: decrement counter and
338 // reschedule if counter is zero.
339
340 void release(); // Release thread from sleep with BREAK
341 // wake_reason.
342
343 void kill(); // Kill this thread
344
345 void force_resume(); // Resume this thread: set counter to zero.
346
347 cyg_uint32 get_state(); // Return current thread state.
348
349
350 // Accessor functions to set and get wait_info.
351
352 void set_wait_info(CYG_ADDRWORD data);
353
354 CYG_ADDRWORD get_wait_info();
355
356 // This part of the API is used if we have a clock and want
357 // per-thread timers for doing delays and timeouts.
358
359 // delay the given number of ticks
360 void delay( cyg_tick_count delay );
361
362
363 enum cyg_reason // sleep/wakeup reason codes
364 {
365 NONE, // No recorded reason
366 WAIT, // Wait with no timeout
367 DELAY, // Simple time delay
368 TIMEOUT, // Wait with timeout/timeout expired
369 BREAK, // forced break out of sleep
370 DESTRUCT, // wait object destroyed[note]
371 EXIT, // forced termination
372 DONE // Wait/delay complete
373 };
374 // [note] NOT the thread, some object it was waiting on.
375 // Thread destruction would first involve EXITing it.
376
377 private:
378
379 #ifdef CYGFUN_KERNEL_THREADS_TIMER
380 Cyg_ThreadTimer timer; // per-thread timer
381 #endif
382
383 cyg_reason sleep_reason; // reason for sleeping
384
385 cyg_reason wake_reason; // reason for waking
386
387 #ifdef CYGIMP_THREAD_PRIORITY
388
389 public:
390
391 // If the scheduler implements priorities, provide
392 // functions to set and get it.
393
394 void set_priority( cyg_priority pri );
395
396 cyg_priority get_priority();
397
398 // This returns the current dispatching priority of the
399 // thread. This may differ from the result of get_priority()
400 // in the presence of priority inheritance or certain
401 // scheduling algorithms.
402 cyg_priority get_current_priority();
403
404 #endif
405
406 #ifdef CYGVAR_KERNEL_THREADS_DATA
407
408 private:
409 // Array of single word entries for each index.
410 CYG_ADDRWORD thread_data[CYGNUM_KERNEL_THREADS_DATA_MAX];
411
412 // Map of free thread_data indexes. Each bit represents an index
413 // and is 1 if that index is free, and 0 if it is in use.
414 static cyg_ucount32 thread_data_map;
415
416 public:
417
418 static CYG_ADDRWORD get_data( cyg_ucount32 index );
419
420 static CYG_ADDRWORD *get_data_ptr( cyg_ucount32 index );
421
422 void set_data( cyg_ucount32 index, CYG_ADDRWORD data );
423
424 static cyg_ucount32 new_data_index();
425
426 static void free_data_index( cyg_ucount32 index );
427
428 #endif
429
430 #ifdef CYGVAR_KERNEL_THREADS_NAME
431
432 private:
433 // An optional thread name string, for humans to read
434 char *name;
435
436 public:
437 // function to get the name string
438 char *get_name();
439
440 #endif
441
442
443 #ifdef CYGVAR_KERNEL_THREADS_LIST
444
445 // Housekeeping list that tracks all threads
446 private:
447 Cyg_Thread *list_next;
448 static Cyg_Thread *thread_list;
449
450 void add_to_list( void );
451 void remove_from_list( void );
452 public:
453
454 static Cyg_Thread *get_list_head();
455
456 Cyg_Thread *get_list_next();
457
458 #endif
459
460 public:
461
462 // Set sleep reason to reason and wake reason to NONE
463 static void set_sleep_reason( cyg_reason reason = WAIT);
464
465 cyg_reason get_sleep_reason();
466
467 // Set the wakeup reason to the given value
468 void set_wake_reason( cyg_reason reason = DONE);
469
470 // Get current wake reason
471 cyg_reason get_wake_reason();
472
473 static void set_timer( // Set timeout and sleep reason
474 cyg_tick_count trigger, // Absolute wakeup time
475 cyg_reason sleep_reason // reason for sleeping
476 );
477
478 static void clear_timer(); // disable thread timer
479
480 // Get a 16 bit unique id for this thread. This is
481 // used in tracing and instrumentation to identify the
482 // current thread.
483
484 cyg_uint16 get_unique_id();
485
486 };
487
488 // -------------------------------------------------------------------------
489 // Thread Queue class.
490 // This defines the main API for manipulating queues of threads.
491
492 class Cyg_ThreadQueue
493 : private Cyg_ThreadQueue_Implementation
494 {
495
496 public:
497
498 CYGDBG_DEFINE_CHECK_THIS
499
500 // API used by rest of kernel.
501
502 // Add thread to queue
503 void enqueue(Cyg_Thread *thread);
504
505 // return first thread on queue
506 Cyg_Thread *highpri();
507
508 // remove first thread on queue
509 Cyg_Thread *dequeue();
510
511 // remove specified thread from queue
512 void remove(Cyg_Thread *thread);
513
514 // test if queue is empty
515 cyg_bool empty();
516
517 };
518
519 // -------------------------------------------------------------------------
520 // Thread inlines
521
522 // Return current thread state.
523 inline cyg_uint32 Cyg_Thread::get_state()
524 {
525 return state;
526 }
527
528 inline void Cyg_Thread::set_wait_info(CYG_ADDRWORD data)
529 {
530 wait_info = data;
531 }
532
533 inline CYG_ADDRWORD Cyg_Thread::get_wait_info()
534 {
535 return wait_info;
536 }
537
538 // -------------------------------------------------------------------------
539 #endif // ifndef CYGONCE_KERNEL_THREAD_HXX
540 // EOF thread.hxx