preempt: Implement scheduling priorities
[bertos.git] / bertos / kern / proc.h
1 /**
2  * \file
3  * <!--
4  * This file is part of BeRTOS.
5  *
6  * Bertos is free software; you can redistribute it and/or modify
7  * it under the terms of the GNU General Public License as published by
8  * the Free Software Foundation; either version 2 of the License, or
9  * (at your option) any later version.
10  *
11  * This program is distributed in the hope that it will be useful,
12  * but WITHOUT ANY WARRANTY; without even the implied warranty of
13  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
14  * GNU General Public License for more details.
15  *
16  * You should have received a copy of the GNU General Public License
17  * along with this program; if not, write to the Free Software
18  * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301  USA
19  *
20  * As a special exception, you may use this file as part of a free software
21  * library without restriction.  Specifically, if other files instantiate
22  * templates or use macros or inline functions from this file, or you compile
23  * this file and link it with other files to produce an executable, this
24  * file does not by itself cause the resulting executable to be covered by
25  * the GNU General Public License.  This exception does not however
26  * invalidate any other reasons why the executable file might be covered by
27  * the GNU General Public License.
28  *
29  * Copyright 2001, 2004 Develer S.r.l. (http://www.develer.com/)
30  * Copyright 1999, 2000, 2001, 2008 Bernie Innocenti <bernie@codewiz.org>
31  * -->
32  *
33  * \brief Process scheduler (public interface).
34  *
35  * \version $Id$
36  * \author Bernie Innocenti <bernie@codewiz.org>
37  */
38 #ifndef KERN_PROC_H
39 #define KERN_PROC_H
40
41 #include "cfg/cfg_kern.h"
42 #include <cfg/compiler.h>
43
44 #if CONFIG_KERN_PREEMPT
45         #include <cfg/debug.h> // ASSERT()
46 #endif
47
48 #include <cpu/types.h> // cpustack_t
49
50 /*
51  * Forward declaration. The definition of struct Process is private to the
52  * scheduler and hidden in proc_p.h.
53  */
54 struct Process;
55
56 /* Task scheduling services */
57 void proc_init(void);
58 struct Process *proc_new_with_name(const char* name, void (*entry)(void), iptr_t data, size_t stacksize, cpustack_t *stack);
59
60 #if !CONFIG_KERN_MONITOR
61         #define proc_new(entry,data,size,stack) proc_new_with_name(NULL,(entry),(data),(size),(stack))
62 #else
63         #define proc_new(entry,data,size,stack) proc_new_with_name(#entry,(entry),(data),(size),(stack))
64 #endif
65
66 void proc_exit(void);
67 void proc_yield(void);
68 #define proc_switch proc_yield /* OBSOLETE */
69
70 int proc_testSetup(void);
71 int proc_testRun(void);
72 int proc_testTearDown(void);
73
74 struct Process *proc_current(void);
75 iptr_t proc_currentUserData(void);
76 void proc_rename(struct Process *proc, const char *name);
77 const char *proc_name(struct Process *proc);
78 const char *proc_currentName(void);
79
80 #if CONFIG_KERN_PRI
81 void proc_setPri(struct Process *proc, int pri);
82 #endif
83
84 /**
85  * Disable preemptive task switching.
86  *
87  * The scheduler maintains a global nesting counter.  Task switching is
88  * effectively re-enabled only when the number of calls to proc_permit()
89  * matches the number of calls to proc_forbid().
90  *
91  * \note Calling functions that could sleep while task switching is disabled
92  * is dangerous and unsupported.
93  *
94  * \note proc_permit() expands inline to 1-2 asm instructions, so it's a
95  * very efficient locking primitive in simple but performance-critical
96  * situations.  In all other cases, semaphores offer a more flexible and
97  * fine-grained locking primitive.
98  *
99  * \sa proc_permit()
100  */
101 INLINE void proc_forbid(void)
102 {
103         #if CONFIG_KERN_PREEMPT
104                 // No need to protect against interrupts here.
105                 extern int preempt_forbid_cnt;
106                 ++preempt_forbid_cnt;
107
108                 /*
109                  * Make sure preempt_forbid_cnt is flushed to memory so the
110                  * preemption softirq will see the correct value from now on.
111                  */
112                 MEMORY_BARRIER;
113         #endif
114 }
115
116 /**
117  * Re-enable preemptive task switching.
118  *
119  * \sa proc_forbid()
120  */
121 INLINE void proc_permit(void)
122 {
123         #if CONFIG_KERN_PREEMPT
124
125                 /*
126                  * This is to ensure any global state changed by the process gets
127                  * flushed to memory before task switching is re-enabled.
128                  */
129                 MEMORY_BARRIER;
130
131                 /* No need to protect against interrupts here. */
132                 extern int preempt_forbid_cnt;
133                 --preempt_forbid_cnt;
134                 ASSERT(preempt_forbid_cnt >= 0);
135
136                 /*
137                  * This ensures preempt_forbid_cnt is flushed to memory immediately
138                  * so the preemption interrupt sees the correct value.
139                  */
140                 MEMORY_BARRIER;
141
142         #endif
143 }
144
145
146 /**
147  * Execute a block of \a CODE atomically with respect to task scheduling.
148  */
149 #define PROC_ATOMIC(CODE) \
150         do { \
151                 proc_forbid(); \
152                 CODE; \
153                 proc_permit(); \
154         } while(0)
155
156 #ifndef CONFIG_KERN_MINSTACKSIZE
157
158         #if (ARCH & ARCH_EMUL)
159                 /* We need a large stack because system libraries are bloated */
160                 #define CONFIG_KERN_MINSTACKSIZE  65536
161         #else
162                 /**
163                  * Default stack size for each thread, in bytes.
164                  *
165                  * The goal here is to allow a minimal task to save all of its
166                  * registers twice, plus push a maximum of 32 variables on the
167                  * stack.
168                  *
169                  * The actual size computed by the default formula is:
170                  *   AVR:    102
171                  *   i386:   156
172                  *   ARM:    164
173                  *   x86_64: 184
174                  *
175                  * Note that on most 16bit architectures, interrupts will also
176                  * run on the stack of the currently running process.  Nested
177                  * interrupts will greatly increases the amount of stack space
178                  * required per process.  Use irqmanager to minimize stack
179                  * usage.
180                  */
181                 #define CONFIG_KERN_MINSTACKSIZE  \
182                     (CPU_SAVED_REGS_CNT * 2 * sizeof(cpustack_t) \
183                     + 32 * sizeof(int))
184         #endif
185 #endif
186
187 #define CONFIG_PROC_DEFSTACKSIZE CONFIG_KERN_MINSTACKSIZE // OBSOLETE
188
189 /* Memory fill codes to help debugging */
190 #if CONFIG_KERN_MONITOR
191         #include <cpu/types.h>
192         #if (SIZEOF_CPUSTACK_T == 1)
193                 /* 8bit cpustack_t */
194                 #define CONFIG_KERN_STACKFILLCODE  0xA5
195                 #define CONFIG_KERN_MEMFILLCODE    0xDB
196         #elif (SIZEOF_CPUSTACK_T == 2)
197                 /* 16bit cpustack_t */
198                 #define CONFIG_KERN_STACKFILLCODE  0xA5A5
199                 #define CONFIG_KERN_MEMFILLCODE    0xDBDB
200         #elif (SIZEOF_CPUSTACK_T == 4)
201                 /* 32bit cpustack_t */
202                 #define CONFIG_KERN_STACKFILLCODE  0xA5A5A5A5UL
203                 #define CONFIG_KERN_MEMFILLCODE    0xDBDBDBDBUL
204         #elif (SIZEOF_CPUSTACK_T == 8)
205                 /* 64bit cpustack_t */
206                 #define CONFIG_KERN_STACKFILLCODE  0xA5A5A5A5A5A5A5A5ULL
207                 #define CONFIG_KERN_MEMFILLCODE    0xDBDBDBDBDBDBDBDBULL
208         #else
209                 #error No cpustack_t size supported!
210         #endif
211 #endif
212
213 #endif /* KERN_PROC_H */