|
[ source navigation ] [ diff markup ] [ identifier search ] [ general search ] |
|||
|
001 /* Copyright (C) 2004,2005 David Decotigny 001 /* Copyright (C) 2004,2005 David Decotigny 002 002 003 This program is free software; you can redi 003 This program is free software; you can redistribute it and/or 004 modify it under the terms of the GNU Genera 004 modify it under the terms of the GNU General Public License 005 as published by the Free Software Foundatio 005 as published by the Free Software Foundation; either version 2 006 of the License, or (at your option) any lat 006 of the License, or (at your option) any later version. 007 007 008 This program is distributed in the hope tha 008 This program is distributed in the hope that it will be useful, 009 but WITHOUT ANY WARRANTY; without even the 009 but WITHOUT ANY WARRANTY; without even the implied warranty of 010 MERCHANTABILITY or FITNESS FOR A PARTICULAR 010 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 011 GNU General Public License for more details 011 GNU General Public License for more details. 012 012 013 You should have received a copy of the GNU 013 You should have received a copy of the GNU General Public License 014 along with this program; if not, write to t 014 along with this program; if not, write to the Free Software 015 Foundation, Inc., 59 Temple Place - Suite 3 015 Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, 016 USA. 016 USA. 017 */ 017 */ 018 #ifndef _SOS_THREAD_H_ 018 #ifndef _SOS_THREAD_H_ 019 #define _SOS_THREAD_H_ 019 #define _SOS_THREAD_H_ 020 020 021 /** 021 /** 022 * @file thread.h 022 * @file thread.h 023 * 023 * 024 * SOS Thread management API 024 * SOS Thread management API 025 */ 025 */ 026 026 027 #include <sos/errno.h> 027 #include <sos/errno.h> 028 028 029 /* Forward declaration */ 029 /* Forward declaration */ 030 struct sos_thread; 030 struct sos_thread; 031 031 032 #include <hwcore/cpu_context.h> 032 #include <hwcore/cpu_context.h> 033 #include <sos/sched.h> 033 #include <sos/sched.h> 034 #include <sos/kwaitq.h> 034 #include <sos/kwaitq.h> 035 #include <sos/time.h> 035 #include <sos/time.h> 036 #include <sos/process.h> << 037 #include <sos/umem_vmm.h> << 038 036 039 /** 037 /** 040 * The possible states of a valid thread 038 * The possible states of a valid thread 041 */ 039 */ 042 typedef enum { SOS_THR_CREATED, /**< Thread cr 040 typedef enum { SOS_THR_CREATED, /**< Thread created, not fully initialized */ 043 SOS_THR_READY, /**< Thread fu 041 SOS_THR_READY, /**< Thread fully initialized or 044 waiting f 042 waiting for CPU after having been 045 blocked o 043 blocked or preempted */ 046 SOS_THR_RUNNING, /**< Thread cu 044 SOS_THR_RUNNING, /**< Thread currently running on CPU */ 047 SOS_THR_BLOCKED, /**< Thread wa 045 SOS_THR_BLOCKED, /**< Thread waiting for I/O (+ in at LEAST 048 one kwait 046 one kwaitq) and/or sleeping (+ in NO 049 kwaitq) * 047 kwaitq) */ 050 SOS_THR_ZOMBIE, /**< Thread te 048 SOS_THR_ZOMBIE, /**< Thread terminated execution, waiting to 051 be delete 049 be deleted by kernel */ 052 } sos_thread_state_t; 050 } sos_thread_state_t; 053 051 054 052 055 /** 053 /** 056 * TCB (Thread Control Block): structure descr 054 * TCB (Thread Control Block): structure describing a thread. Don't 057 * access these fields directly: prefer using 055 * access these fields directly: prefer using the accessor functions 058 * below. 056 * below. 059 */ 057 */ 060 struct sos_thread 058 struct sos_thread 061 { 059 { 062 #define SOS_THR_MAX_NAMELEN 32 060 #define SOS_THR_MAX_NAMELEN 32 063 char name[SOS_THR_MAX_NAMELEN]; 061 char name[SOS_THR_MAX_NAMELEN]; 064 062 065 sos_thread_state_t state; 063 sos_thread_state_t state; 066 sos_sched_priority_t priority; << 067 064 068 /** 065 /** 069 * The hardware context of the thread. 066 * The hardware context of the thread. 070 * 067 * 071 * It will reflect the CPU state of the thre 068 * It will reflect the CPU state of the thread: 072 * - From an interrupt handler: the state o 069 * - From an interrupt handler: the state of the thread at the time 073 * of the OUTERMOST irq. An IRQ is not al 070 * of the OUTERMOST irq. An IRQ is not allowed to make context 074 * switches, so this context will remain 071 * switches, so this context will remain valid from the begining of 075 * the outermost IRQ handler to the end o 072 * the outermost IRQ handler to the end of it, no matter if there 076 * are other IRQ handlers nesting in one 073 * are other IRQ handlers nesting in one another. You may safely 077 * use it from IRQ handlers to query the 074 * use it from IRQ handlers to query the state of the interrupted 078 * thread, no matter if there has been ot 075 * thread, no matter if there has been other IRQ handlers 079 * executing meanwhile. 076 * executing meanwhile. 080 * - From normal kernel code, exceptions an 077 * - From normal kernel code, exceptions and syscall: the state of 081 * the thread the last time there was a c 078 * the thread the last time there was a context switch from this 082 * thread to another one. Thus this field 079 * thread to another one. Thus this field WON'T reflect the 083 * current's thread cpu_state in these ca 080 * current's thread cpu_state in these cases. So, in these cases, 084 * simply DO NOT USE IT outside thread.c 081 * simply DO NOT USE IT outside thread.c ! Note: for syscall and 085 * exception handlers, the VALID state of 082 * exception handlers, the VALID state of the interrupted thread is 086 * passed as an argument to the handlers. 083 * passed as an argument to the handlers. 087 */ 084 */ 088 struct sos_cpu_state *cpu_state; 085 struct sos_cpu_state *cpu_state; 089 086 090 /* Kernel stack parameters */ 087 /* Kernel stack parameters */ 091 sos_vaddr_t kernel_stack_base_addr; 088 sos_vaddr_t kernel_stack_base_addr; 092 sos_size_t kernel_stack_size; 089 sos_size_t kernel_stack_size; 093 090 094 /* Process this thread belongs to. Always NU << 095 thread */ << 096 struct sos_process *process; << 097 << 098 /** << 099 * Address space currently "squatted" by the << 100 * active when the thread was interrupted/pr << 101 * configuration expected before the cpu_sta << 102 * restored on CPU. << 103 * - For kernel threads: should normally b << 104 * thread will squat the current mm_cont << 105 * MMU. Might be NON NULL when a kernel << 106 * process to manipulate its address spa << 107 * - For user threads: should normally be << 108 * - in user mode: the thread->process << 109 * set on MMU. squatted_mm_context i << 110 * situation, meaning that the threa << 111 * process-space as expected << 112 * - in kernel mode: NULL means that w << 113 * mm_context currently set on MMU, << 114 * mm_context of another process. Th << 115 * thread in kernel mode normally on << 116 * space. BTW, this limits the numbe << 117 * there are exceptions where this s << 118 * NOT be NULL. One is the copy_from << 119 * force the effective mm_context so << 120 * (re)configured upon every context << 121 * the squatted_mm_context. Another << 122 * thread creates the address space << 123 * which case the parent thread migh << 124 * switch to the child's process spa << 125 * << 126 * This is the SOS implementation of the Lin << 127 * address-space loaning. << 128 */ << 129 struct sos_mm_context *squatted_mm_context; << 130 << 131 /* Data specific to each state */ 091 /* Data specific to each state */ 132 union 092 union 133 { 093 { 134 struct 094 struct 135 { 095 { 136 struct sos_sched_queue *rdy_queue; << 137 struct sos_thread *rdy_prev, *rdy_ne 096 struct sos_thread *rdy_prev, *rdy_next; 138 } ready; 097 } ready; 139 << 140 struct << 141 { << 142 struct sos_time user_time_spent_in_slice << 143 } running; << 144 }; /* Anonymous union (gcc extenion) */ 098 }; /* Anonymous union (gcc extenion) */ 145 099 146 100 147 /** << 148 * When a thread in kernel mode is accessing << 149 * page fault in the usual way only if retur << 150 * set. This structure holds information reg << 151 * page fault from kernel into user space co << 152 * << 153 * @note the fields below should be consider << 154 * sos_thread_prepare_user_space_access() an << 155 * sos_thread_end_user_space_access() to mod << 156 */ << 157 struct << 158 { << 159 /** This is the address (in kernel code) t << 160 user-space page fault from a kernel-mo << 161 resolved. @see sos_thread_prepare_use << 162 sos_vaddr_t return_vaddr; << 163 << 164 /** This is the address of the user-space << 165 unresolved page fault (set by the page << 166 sos_uaddr_t faulted_uaddr; << 167 } fixup_uaccess; << 168 << 169 << 170 /* 101 /* 171 * Data used by the kwaitq subsystem: list o 102 * Data used by the kwaitq subsystem: list of kwaitqueues the thread 172 * is waiting for. 103 * is waiting for. 173 * 104 * 174 * @note: a RUNNING or READY thread might be 105 * @note: a RUNNING or READY thread might be in one or more 175 * waitqueues ! The only property we have is 106 * waitqueues ! The only property we have is that, among these 176 * waitqueues (if any), _at least_ one has w 107 * waitqueues (if any), _at least_ one has woken the thread. 177 */ 108 */ 178 struct sos_kwaitq_entry *kwaitq_list; 109 struct sos_kwaitq_entry *kwaitq_list; 179 110 180 111 181 /** 112 /** 182 * Some statistics << 183 */ << 184 struct rusage << 185 { << 186 /* Updated by sched.c */ << 187 struct sos_time ru_utime; /* Time spent in << 188 struct sos_time ru_stime; /* Time spent in << 189 } rusage; << 190 << 191 << 192 /** << 193 * Chaining pointers for the list of threads << 194 */ << 195 struct sos_thread *prev_in_process, *next_in << 196 << 197 << 198 /** << 199 * Chaining pointers for global ("gbl") list 113 * Chaining pointers for global ("gbl") list of threads (debug) 200 */ 114 */ 201 struct sos_thread *gbl_prev, *gbl_next; 115 struct sos_thread *gbl_prev, *gbl_next; 202 }; 116 }; 203 117 204 118 205 /** 119 /** 206 * Definition of the function executed by a ke 120 * Definition of the function executed by a kernel thread 207 */ 121 */ 208 typedef void (*sos_kernel_thread_start_routine 122 typedef void (*sos_kernel_thread_start_routine_t)(void *arg); 209 123 210 124 211 /** 125 /** 212 * Initialize the subsystem responsible for th 126 * Initialize the subsystem responsible for thread management 213 * 127 * 214 * Initialize the primary kernel thread so tha 128 * Initialize the primary kernel thread so that it can be handled the 215 * same way as an ordinary thread created by s 129 * same way as an ordinary thread created by sos_thread_create(). 216 */ 130 */ 217 sos_ret_t sos_thread_subsystem_setup(sos_vaddr 131 sos_ret_t sos_thread_subsystem_setup(sos_vaddr_t init_thread_stack_base_addr, 218 sos_size_ 132 sos_size_t init_thread_stack_size); 219 133 220 134 221 /** 135 /** 222 * Create a new kernel thread 136 * Create a new kernel thread 223 */ 137 */ 224 struct sos_thread * 138 struct sos_thread * 225 sos_create_kernel_thread(const char *name, 139 sos_create_kernel_thread(const char *name, 226 sos_kernel_thread_sta 140 sos_kernel_thread_start_routine_t start_func, 227 void *start_arg, !! 141 void *start_arg); 228 sos_sched_priority_t << 229 << 230 << 231 /** << 232 * Create a new user thread << 233 */ << 234 struct sos_thread * << 235 sos_create_user_thread(const char *name, << 236 struct sos_process *pro << 237 sos_uaddr_t user_initia << 238 sos_ui32_t user_start_ << 239 sos_ui32_t user_start_ << 240 sos_uaddr_t user_initia << 241 sos_sched_priority_t pr << 242 << 243 << 244 /** << 245 * Create a new user thread, copy of the given << 246 * given user context << 247 */ << 248 struct sos_thread * << 249 sos_duplicate_user_thread(const char *name, << 250 struct sos_process * << 251 const struct sos_thr << 252 const struct sos_cpu << 253 sos_ui32_t retval); << 254 142 255 143 256 /** 144 /** 257 * Terminate the execution of the current thre 145 * Terminate the execution of the current thread. For kernel threads, 258 * it is called by default when the start rout 146 * it is called by default when the start routine returns. 259 */ 147 */ 260 void sos_thread_exit() __attribute__((noreturn 148 void sos_thread_exit() __attribute__((noreturn)); 261 149 262 150 263 /** 151 /** 264 * Get the identifier of the thread currently 152 * Get the identifier of the thread currently running on CPU. Trivial 265 * function. 153 * function. 266 */ 154 */ 267 struct sos_thread *sos_thread_get_current(); 155 struct sos_thread *sos_thread_get_current(); 268 156 269 157 270 /** 158 /** 271 * If thr == NULL, set the priority of the cur << 272 * function. << 273 * << 274 * @note NOT protected against interrupts << 275 */ << 276 sos_sched_priority_t sos_thread_get_priority(s << 277 << 278 << 279 /** << 280 * If thr == NULL, get the state of the curren 159 * If thr == NULL, get the state of the current thread. Trivial 281 * function. 160 * function. 282 * 161 * 283 * @note NOT protected against interrupts 162 * @note NOT protected against interrupts 284 */ 163 */ 285 sos_thread_state_t sos_thread_get_state(struct 164 sos_thread_state_t sos_thread_get_state(struct sos_thread *thr); 286 165 287 166 288 /** 167 /** 289 * If thr == NULL, set the priority of the cur << 290 * << 291 * @note NO context-switch ever occurs in this << 292 */ << 293 sos_ret_t sos_thread_set_priority(struct sos_t << 294 sos_sched_pr << 295 << 296 << 297 /** << 298 * Yield CPU to another ready thread. 168 * Yield CPU to another ready thread. 299 * 169 * 300 * @note This is a BLOCKING FUNCTION 170 * @note This is a BLOCKING FUNCTION 301 */ 171 */ 302 sos_ret_t sos_thread_yield(); 172 sos_ret_t sos_thread_yield(); 303 173 304 174 305 /** 175 /** 306 * Release the CPU for (at least) the given de 176 * Release the CPU for (at least) the given delay. 307 * 177 * 308 * @param delay The delay to wait for. If dela 178 * @param delay The delay to wait for. If delay == NULL then wait 309 * forever that any event occurs. 179 * forever that any event occurs. 310 * 180 * 311 * @return SOS_OK when delay expired (and dela 181 * @return SOS_OK when delay expired (and delay is reset to zero), 312 * -SOS_EINTR otherwise (and delay contains th 182 * -SOS_EINTR otherwise (and delay contains the amount of time 313 * remaining). 183 * remaining). 314 * 184 * 315 * @note This is a BLOCKING FUNCTION 185 * @note This is a BLOCKING FUNCTION 316 */ 186 */ 317 sos_ret_t sos_thread_sleep(/* in/out */struct 187 sos_ret_t sos_thread_sleep(/* in/out */struct sos_time *delay); 318 188 319 189 320 /** 190 /** 321 * Mark the given thread as READY (if not alre 191 * Mark the given thread as READY (if not already ready) even if it is 322 * blocked in a kwaitq or in a sleep ! As a re 192 * blocked in a kwaitq or in a sleep ! As a result, the interrupted 323 * kwaitq/sleep function call of the thread wi 193 * kwaitq/sleep function call of the thread will return with 324 * -SOS_EINTR. 194 * -SOS_EINTR. 325 * 195 * 326 * @return -SOS_EINVAL if thread does not exis 196 * @return -SOS_EINVAL if thread does not exist, or -SOS_EFATAL if 327 * marked ZOMBIE. 197 * marked ZOMBIE. 328 * 198 * 329 * @note As a result, the semaphore/mutex/cond 199 * @note As a result, the semaphore/mutex/conditions/... functions 330 * return values SHOULD ALWAYS be checked ! If 200 * return values SHOULD ALWAYS be checked ! If they are != SOS_OK, 331 * then the caller should consider that the re 201 * then the caller should consider that the resource is not aquired 332 * because somebody woke the thread by some wa 202 * because somebody woke the thread by some way. 333 */ 203 */ 334 sos_ret_t sos_thread_force_unblock(struct sos_ 204 sos_ret_t sos_thread_force_unblock(struct sos_thread *thread); 335 << 336 /** << 337 * Dump the backtrace of the current thread to << 338 */ << 339 void sos_thread_dump_backtrace(sos_bool_t on_c << 340 sos_bool_t on_b << 341 << 342 << 343 /* ******************************************* << 344 * Restricted functions << 345 */ << 346 << 347 << 348 /** << 349 * Restricted function to indicate that we are << 350 * user address space from inside the kernel. << 351 * << 352 * @param dest_as The address space we want to << 353 * access current thread's address space << 354 * << 355 * @param fixup_retvaddr When != 0, then dest_ << 356 * don't allow controlled access from kernel i << 357 * foreign thread). In this case, the page fau << 358 * page faults from the kernel in user space, << 359 * usual way. The value in retvaddr is where t << 360 * has to return to in case the page fault rem << 361 * address of the faulting address is kept in << 362 * éthread->fixup_uaccess.faulted_uaddr << 363 * << 364 * @note typical values for fixup_retvaddr are << 365 * values" (see gcc's doc: operator "&&"). See << 366 * code. << 367 */ << 368 sos_ret_t << 369 sos_thread_prepare_user_space_access(struct so << 370 sos_vaddr << 371 << 372 << 373 /** << 374 * Restricted function to signal we are not ac << 375 * space anymore << 376 */ << 377 sos_ret_t << 378 sos_thread_end_user_space_access(void); << 379 << 380 << 381 /** << 382 * Restricted callback called when a syscall g << 383 * to reconfigure the MMU to match that of the << 384 * process MMU context. << 385 * << 386 * @note The use of this function is RESERVED << 387 */ << 388 void sos_thread_prepare_syscall_switch_back(st << 389 << 390 << 391 /** << 392 * Restricted callback called when an exceptio << 393 * the interrupted thread to reconfigure the M << 394 * current thread's process MMU context. << 395 * << 396 * @note The use of this function is RESERVED << 397 */ << 398 void sos_thread_prepare_exception_switch_back( << 399 << 400 << 401 /** << 402 * Restricted callback called when an IRQ is e << 403 * NOT already servicing any other IRQ (ie the << 404 * is entered). This callback simply updates t << 405 * that IRQ handlers always know the state of << 406 * even if they are imbricated in other IRQ ha << 407 * << 408 * @note The use of this function is RESERVED << 409 */ << 410 void << 411 sos_thread_prepare_irq_servicing(struct sos_cp << 412 << 413 << 414 /** << 415 * Restricted callback called when the outermo << 416 * to select the thread to return to. This cal << 417 * - preemption of user threads in user mode << 418 * - non-preemption of user threads in kerne << 419 * is restored on CPU "as is") << 420 * - non-preemption of kernel threads (same << 421 * The MMU is reconfigured correctly to match << 422 * selected thread. << 423 * << 424 * @return The CPU context of the thread to re << 425 * << 426 * @note The use of this function is RESERVED << 427 */ << 428 struct sos_cpu_state * << 429 sos_thread_prepare_irq_switch_back(void); << 430 205 431 206 432 #endif /* _SOS_THREAD_H_ */ 207 #endif /* _SOS_THREAD_H_ */
[ source navigation ] | [ diff markup ] | [ identifier search ] | [ general search ] |