Initial revision
[karo-tx-redboot.git] / packages / kernel / v2_0 / include / sched.hxx
1 #ifndef CYGONCE_KERNEL_SCHED_HXX
2 #define CYGONCE_KERNEL_SCHED_HXX
3
4 //==========================================================================
5 //
6 //      sched.hxx
7 //
8 //      Scheduler class declaration(s)
9 //
10 //==========================================================================
11 //####ECOSGPLCOPYRIGHTBEGIN####
12 // -------------------------------------------
13 // This file is part of eCos, the Embedded Configurable Operating System.
14 // Copyright (C) 1998, 1999, 2000, 2001, 2002 Red Hat, Inc.
15 //
16 // eCos is free software; you can redistribute it and/or modify it under
17 // the terms of the GNU General Public License as published by the Free
18 // Software Foundation; either version 2 or (at your option) any later version.
19 //
20 // eCos is distributed in the hope that it will be useful, but WITHOUT ANY
21 // WARRANTY; without even the implied warranty of MERCHANTABILITY or
22 // FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
23 // for more details.
24 //
25 // You should have received a copy of the GNU General Public License along
26 // with eCos; if not, write to the Free Software Foundation, Inc.,
27 // 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA.
28 //
29 // As a special exception, if other files instantiate templates or use macros
30 // or inline functions from this file, or you compile this file and link it
31 // with other works to produce a work based on this file, this file does not
32 // by itself cause the resulting work to be covered by the GNU General Public
33 // License. However the source code for this file must still be made available
34 // in accordance with section (3) of the GNU General Public License.
35 //
36 // This exception does not invalidate any other reasons why a work based on
37 // this file might be covered by the GNU General Public License.
38 //
39 // Alternative licenses for eCos may be arranged by contacting Red Hat, Inc.
40 // at http://sources.redhat.com/ecos/ecos-license/
41 // -------------------------------------------
42 //####ECOSGPLCOPYRIGHTEND####
43 //==========================================================================
44 //#####DESCRIPTIONBEGIN####
45 //
46 // Author(s):   nickg
47 // Contributors:        nickg
48 // Date:        1997-09-09
49 // Purpose:     Define Scheduler class interfaces
50 // Description: These class definitions supply the internal API
51 //              used to scheduler threads. 
52 // Usage:       #include <cyg/kernel/sched.hxx>
53 //
54 //####DESCRIPTIONEND####
55 //
56 //==========================================================================
57
58 #include <cyg/kernel/ktypes.h>
59 #include <cyg/infra/cyg_ass.h>         // assertion macros
60
61 #include <cyg/kernel/smp.hxx>          // SMP support
62
63 // -------------------------------------------------------------------------
64 // Miscellaneous types
65
66 #ifdef CYGSEM_KERNEL_SCHED_ASR_SUPPORT
67
68 typedef void Cyg_ASR( CYG_ADDRWORD data );      // ASR type signature
69
70 #endif
71
72 __externC void cyg_scheduler_set_need_reschedule();
73
74 // -------------------------------------------------------------------------
75 // Scheduler base class. This defines stuff that is needed by the
76 // specific scheduler implementation. Each scheduler comprises three
77 // classes: Cyg_Scheduler_Base, Cyg_Scheduler_Implementation which
78 // inherits from it and Cyg_Scheduler which inherits from _it_ in turn.
79
80 class Cyg_Scheduler_Base
81      : public Cyg_Scheduler_SchedLock
82 {
83     friend class Cyg_HardwareThread;
84     friend class Cyg_SchedThread;
85     
86 protected:
87     // The following variables are implicit in the API, but are
88     // not publically visible.
89
90     // Current running thread    
91     static Cyg_Thread * volatile current_thread[CYGNUM_KERNEL_CPU_MAX]
92                                                 CYGBLD_ANNOTATE_VARIABLE_SCHED; 
93
94     // Set when reschedule needed
95     static volatile cyg_bool     need_reschedule[CYGNUM_KERNEL_CPU_MAX]
96                                                  CYGBLD_ANNOTATE_VARIABLE_SCHED; 
97
98     // Count of number of thread switches
99     static volatile cyg_ucount32 thread_switches[CYGNUM_KERNEL_CPU_MAX]
100                                                  CYGBLD_ANNOTATE_VARIABLE_SCHED; 
101
102 public:
103
104     // return a pointer to the current thread
105     static Cyg_Thread *get_current_thread();
106
107     // Set current thread pointer
108     static void set_current_thread(Cyg_Thread *thread);
109     static void set_current_thread(Cyg_Thread *thread, HAL_SMP_CPU_TYPE cpu);
110     
111     // Set need_reschedule flag
112     static void set_need_reschedule();
113     static void set_need_reschedule(Cyg_Thread *thread);
114
115     // Get need_reschedule flag
116     static cyg_bool get_need_reschedule();
117
118     // Return current value of lock
119     static cyg_ucount32 get_sched_lock();
120
121     // Clear need_reschedule flag
122     static void clear_need_reschedule();
123     
124     // Return current number of thread switches
125     static cyg_ucount32 get_thread_switches();
126     
127 };
128
129 // -------------------------------------------------------------------------
130 // Include the scheduler implementation header
131
132 #include CYGPRI_KERNEL_SCHED_IMPL_HXX
133
134 // Do some checking that we have a consistent universe.
135
136 #ifdef CYGSEM_KERNEL_SYNCH_MUTEX_PRIORITY_INVERSION_PROTOCOL
137 # ifndef CYGIMP_THREAD_PRIORITY
138 #  error Priority inversion protocols will not work without priorities!!!
139 # endif
140 #endif
141
142 // -------------------------------------------------------------------------
143 // Scheduler class. This is the public scheduler interface seen by the
144 // rest of the kernel.
145
146 class Cyg_Scheduler
147     : public Cyg_Scheduler_Implementation
148 {
149     friend class Cyg_Thread;
150     
151     // This function is the actual implementation of the unlock
152     // function.  The unlock() later is an inline shell that deals
153     // with the common case.
154     
155     static void             unlock_inner(cyg_uint32 new_lock = 0);
156     
157 public:
158
159     CYGDBG_DEFINE_CHECK_THIS
160
161     // The following API functions are common to all scheduler
162     // implementations.
163
164     // claim the preemption lock
165     static void             lock();         
166
167     // release the preemption lock and possibly reschedule
168     static void             unlock();
169
170     // release and reclaim the lock atomically, keeping the old
171     // value on restart
172     static void             reschedule();
173
174     // decrement the lock but also look for a reschedule opportunity
175     static void             unlock_reschedule();
176
177     // release the preemption lock without rescheduling
178     static void             unlock_simple();
179     
180     // Start execution of the scheduler
181     static void start() CYGBLD_ATTRIB_NORET;
182
183     // Start execution of the scheduler on the current CPU
184     static void start_cpu() CYGBLD_ATTRIB_NORET;    
185     
186     // The only  scheduler instance should be this one...
187     static Cyg_Scheduler scheduler CYGBLD_ANNOTATE_VARIABLE_SCHED;
188
189 };
190
191 // -------------------------------------------------------------------------
192 // This class encapsulates the scheduling abstractions in a thread.
193 // Cyg_SchedThread is included as a base class of Cyg_Thread. The actual
194 // implementation of the abstractions is in Cyg_SchedThread_Implementation
195 // so this class has little to do.
196
197 class Cyg_SchedThread
198     : public Cyg_SchedThread_Implementation
199 {
200     friend class Cyg_ThreadQueue_Implementation;
201     friend class Cyg_Scheduler_Implementation;
202     friend class Cyg_Scheduler;
203     
204     Cyg_ThreadQueue     *queue;
205
206
207 public:
208
209     Cyg_SchedThread(Cyg_Thread *thread, CYG_ADDRWORD sched_info);
210
211     // Return current queue pointer
212
213     Cyg_ThreadQueue     *get_current_queue();
214     
215     // Remove this thread from current queue
216     void remove();
217
218 #ifdef CYGSEM_KERNEL_SCHED_ASR_SUPPORT
219
220     // ASR support.
221     // An ASR is an Asynchronous Service Routine. When set pending it
222     // is called when the thread exits the scheduler. ASRs are mainly
223     // used by compatibility subsystems, such as POSIX, to implement
224     // such things as thread cancellation and signal delivery.
225
226 private:
227
228     volatile cyg_ucount32       asr_inhibit;    // If > 0, blocks calls to ASRs
229
230     volatile cyg_bool           asr_pending;    // If true, this thread's ASR should be called.
231
232 #ifdef CYGSEM_KERNEL_SCHED_ASR_GLOBAL
233     static
234 #endif    
235     Cyg_ASR             *asr;            // ASR function
236 #ifdef CYGSEM_KERNEL_SCHED_ASR_DATA_GLOBAL
237     static
238 #endif    
239     CYG_ADDRWORD        asr_data;       // ASR data pointer
240
241     // Default ASR function
242     static void         asr_default(CYG_ADDRWORD data);
243
244 public:
245
246     // Public interface to ASR mechanism
247
248     // Set, clear and get inhibit flag.
249     inline void set_asr_inhibit() { asr_inhibit++; }
250     inline void clear_asr_inhibit() { asr_inhibit--; }
251     inline cyg_ucount32 get_asr_inhibit() { return asr_inhibit; }
252
253     // Set and get pending flag. The flag is only cleared when the
254     // ASR is called.
255     inline void set_asr_pending() { asr_pending = true; }
256     inline cyg_bool get_asr_pending() { return asr_pending; }
257
258     // Set a new ASR, returning the old one. 
259     void set_asr( Cyg_ASR  *new_asr, CYG_ADDRWORD  new_data,
260                   Cyg_ASR **old_asr, CYG_ADDRWORD *old_data);
261
262     // Clear the ASR function back to the default.
263     void clear_asr();
264
265 #else
266
267 public:
268     
269     // Even when we do not have ASRs enabled, we keep these functions
270     // available. This avoids excessive ifdefs in the rest of the
271     // kernel code.
272     inline void set_asr_inhibit() { }
273     inline void clear_asr_inhibit() { }
274     
275 #endif    
276     
277 #ifdef CYGSEM_KERNEL_SYNCH_MUTEX_PRIORITY_INVERSION_PROTOCOL
278
279 private:
280
281     // For all priority inversion protocols we need to keep track of how
282     // many mutexes we have locked, including one which we are waiting to
283     // lock, because we can inherit priority while sleeping just prior to
284     // wakeup.
285     
286     cyg_count32         mutex_count;
287
288 protected:
289     // These are implementation functions that are common to all protocols.
290         
291     // Inherit the given priority. If thread is non-NULL the priority is
292     // being inherited from it, otherwise it has come from the mutex.
293     void set_inherited_priority( cyg_priority pri, Cyg_Thread *thread = 0 );
294
295     // Relay the priority of the ex-owner thread or from the queue if it
296     // has a higher priority than ours.
297     void relay_inherited_priority( Cyg_Thread *ex_owner, Cyg_ThreadQueue *pqueue);
298
299     // Lose priority inheritance
300     void clear_inherited_priority();
301     
302 public:    
303     // Count and uncount the number of mutexes held by
304     // this thread.
305     void count_mutex() { mutex_count++; };
306     void uncount_mutex() { mutex_count--; };
307
308 #if defined(CYGSEM_KERNEL_SYNCH_MUTEX_PRIORITY_INVERSION_PROTOCOL_SIMPLE)
309     
310 protected:    
311
312     // The simple priority inversion protocols simply needs
313     // somewhere to store the base priority of the current thread.
314     
315     cyg_priority        original_priority;      // our original priority
316
317     cyg_bool            priority_inherited;     // have we inherited?
318
319 #endif
320
321 #ifdef CYGSEM_KERNEL_SYNCH_MUTEX_PRIORITY_INVERSION_PROTOCOL_INHERIT
322     
323 public:
324
325     // Inherit the priority of the provided thread if it
326     // has higher priority than this.
327     void inherit_priority( Cyg_Thread *thread);
328
329     // Relay the priority of the ex-owner thread or from the queue if it
330     // has a higher priority than ours.
331     void relay_priority( Cyg_Thread *ex_owner, Cyg_ThreadQueue *pqueue);
332
333     // Lose priority inheritance
334     void disinherit_priority();
335     
336 #endif
337
338 #ifdef CYGSEM_KERNEL_SYNCH_MUTEX_PRIORITY_INVERSION_PROTOCOL_CEILING
339
340 public:
341
342     // Set the priority of this thread to the given ceiling.
343     void set_priority_ceiling( cyg_priority pri );
344
345     // Clear the ceiling, if necessary.
346     void clear_priority_ceiling();
347     
348 #endif    
349
350 #endif
351     
352 };
353
354 // -------------------------------------------------------------------------
355 // Simple inline accessor functions
356
357 inline Cyg_Thread *Cyg_Scheduler_Base::get_current_thread()
358 {
359     return current_thread[CYG_KERNEL_CPU_THIS()];
360 }
361
362 inline void Cyg_Scheduler_Base::set_current_thread(Cyg_Thread *thread )
363 {
364     current_thread[CYG_KERNEL_CPU_THIS()] = thread;
365 }
366
367 inline void Cyg_Scheduler_Base::set_current_thread(Cyg_Thread *thread,
368                                                    HAL_SMP_CPU_TYPE cpu)
369 {
370     current_thread[cpu] = thread;
371 }
372
373 inline cyg_bool Cyg_Scheduler_Base::get_need_reschedule()
374 {
375     return need_reschedule[CYG_KERNEL_CPU_THIS()];
376 }
377
378 inline void Cyg_Scheduler_Base::set_need_reschedule()
379 {
380     need_reschedule[CYG_KERNEL_CPU_THIS()] = true;
381 }
382
383 inline void Cyg_Scheduler_Base::set_need_reschedule(Cyg_Thread *thread)
384 {
385     need_reschedule[CYG_KERNEL_CPU_THIS()] = true;
386 }
387
388 inline void Cyg_Scheduler_Base::clear_need_reschedule()
389 {
390     need_reschedule[CYG_KERNEL_CPU_THIS()] = false;
391 }
392
393 inline cyg_ucount32 Cyg_Scheduler_Base::get_sched_lock()
394 {
395     return Cyg_Scheduler_SchedLock::get_sched_lock();
396 }
397
398 // Return current number of thread switches
399 inline cyg_ucount32 Cyg_Scheduler_Base::get_thread_switches()
400 {
401     return thread_switches[CYG_KERNEL_CPU_THIS()];
402 }
403
404 // Return current queue pointer
405 inline Cyg_ThreadQueue *Cyg_SchedThread::get_current_queue()
406 {
407     return queue;
408 }
409
410 // -------------------------------------------------------------------------
411 #endif // ifndef __SCHED_HXX__
412 // EOF sched.hxx