FreeBSD/Linux Kernel Cross Reference
sys/kern/thread.h
1 /*
2 * Mach Operating System
3 * Copyright (c) 1993-1987 Carnegie Mellon University
4 * All Rights Reserved.
5 *
6 * Permission to use, copy, modify and distribute this software and its
7 * documentation is hereby granted, provided that both the copyright
8 * notice and this permission notice appear in all copies of the
9 * software, derivative works or modified versions, and any portions
10 * thereof, and that both notices appear in supporting documentation.
11 *
12 * CARNEGIE MELLON ALLOWS FREE USE OF THIS SOFTWARE IN ITS "AS IS"
13 * CONDITION. CARNEGIE MELLON DISCLAIMS ANY LIABILITY OF ANY KIND FOR
14 * ANY DAMAGES WHATSOEVER RESULTING FROM THE USE OF THIS SOFTWARE.
15 *
16 * Carnegie Mellon requests users of this software to return to
17 *
18 * Software Distribution Coordinator or Software.Distribution@CS.CMU.EDU
19 * School of Computer Science
20 * Carnegie Mellon University
21 * Pittsburgh PA 15213-3890
22 *
23 * any improvements or extensions that they make and grant Carnegie Mellon
24 * the rights to redistribute these changes.
25 */
26 /*
27 * HISTORY
28 * $Log: thread.h,v $
29 * Revision 2.20 93/11/17 17:31:15 dbg
30 * Added thread_deallocate_nowait for use by AST routines.
31 * [93/07/21 dbg]
32 *
33 * Remove ith_lock in favor of thread_lock.
34 * [93/07/12 dbg]
35 *
36 * Break up thread lock, to simplify interactions between thread
37 * lock and processor set lock and to reduce the amount of code
38 * that runs with interrupts blocked. There are now three locks:
39 * . thread_ref_lock locks the reference count
40 * . thread_sched_lock locks fields involved with scheduling
41 * state machine
42 * . thread_lock locks everything else.
43 * [93/05/26 dbg]
44 *
45 * Scheduling policy fields are now added at end of thread
46 * structure by policy configuration.
47 * [93/05/10 dbg]
48 *
49 * Changed policy to policy_index.
50 * [93/05/05 dbg]
51 *
52 * Removed thread->depress_timer. It and thread->timer were never
53 * used simultaneously. Added sched_policy.
54 * [93/04/08 dbg]
55 *
56 * Renamed ipc/ipc_kmsg_queue.h to ipc/ipc_types.h.
57 * [93/03/29 dbg]
58 *
59 * Remove include of kern/sched.h. Add fields for real-time
60 * threads.
61 * [93/01/28 dbg]
62 *
63 * Revision 2.19 93/08/10 15:12:01 mrt
64 * Conditionalized atm hooks.
65 * [93/07/30 cmaeda]
66 * Included hook for network interface.
67 * [93/06/09 15:45:03 jcb]
68 *
69 * Revision 2.18 93/01/27 09:33:10 danner
70 * Break latent include circularity by introduction of ipc_kmsg_queue.h.
71 *
72 * Revision 2.17 93/01/24 13:20:32 danner
73 * Added sample_control to indicate that this thread is to
74 * have its pc sampled periodically.
75 * [93/01/12 rvb]
76 *
77 * Revision 2.16 93/01/21 14:04:00 danner
78 * Typo correction.
79 *
80 * Revision 2.15 93/01/19 09:01:07 danner
81 * Correct arguments to natural_t.
82 * [93/01/19 danner]
83 *
84 * Revision 2.14 93/01/14 17:37:12 danner
85 * Moved actual declaration of struct thread and thread_t to
86 * kern/kern_types.h, to permit mutually recursive structure
87 * definitions. Added ANSI function prototypes.
88 * [92/12/28 dbg]
89 * Swapped some fields for better alignment.
90 * [92/12/01 af]
91 *
92 * Revision 2.13 91/08/28 11:14:53 jsb
93 * Added ith_seqno.
94 * [91/08/10 rpd]
95 *
96 * Revision 2.12 91/07/31 17:49:44 dbg
97 * Consolidated interruptible, swap_state, halted into state field.
98 * Revised state machine.
99 * [91/07/30 17:06:37 dbg]
100 *
101 * Revision 2.11 91/05/18 14:34:28 rpd
102 * Added depress_timer.
103 * [91/03/31 rpd]
104 *
105 * Replaced swap_privilege with stack_privilege.
106 * [91/03/30 rpd]
107 *
108 * Revision 2.10 91/05/14 16:48:57 mrt
109 * Correcting copyright
110 *
111 * Revision 2.9 91/03/16 14:52:58 rpd
112 * Removed ith_saved.
113 * [91/02/16 rpd]
114 * Added save-state fields for page faults.
115 * [91/02/05 rpd]
116 * Added NCPUS to active_threads declaration.
117 * Added active_stacks.
118 * [91/01/28 rpd]
119 * Added swap_privilege.
120 * [91/01/18 rpd]
121 *
122 * Revision 2.8 91/02/05 17:30:34 mrt
123 * Changed to new Mach copyright
124 * [91/02/01 16:19:58 mrt]
125 *
126 * Revision 2.7 91/01/08 15:18:11 rpd
127 * Added saved-state fields for exceptions.
128 * [90/12/23 rpd]
129 * Added swap_func.
130 * [90/11/20 rpd]
131 *
132 * Revision 2.6 90/08/27 22:04:23 dbg
133 * Remove import of thread_modes.h (unneeded).
134 * [90/07/17 dbg]
135 *
136 * Revision 2.5 90/08/07 17:59:15 rpd
137 * Put last_processor field under NCPUS > 1.
138 * Removed tmp_address and tmp_object fields.
139 * [90/08/07 rpd]
140 *
141 * Revision 2.4 90/06/02 14:57:07 rpd
142 * Converted to new IPC.
143 * [90/03/26 22:25:34 rpd]
144 *
145 * Revision 2.3 90/02/22 20:04:18 dbg
146 * Add per-thread global VM variables (tmp_address, tmp_object).
147 * [89/04/29 mwyoung]
148 *
149 * Revision 2.2 89/09/08 11:26:59 dbg
150 * Added simple_rpc_kmsg [rfr]. Set its size to size of
151 * small Kmsg. Moved all IPC data structures to end of
152 * thread structure.
153 * [89/08/16 dbg]
154 *
155 * Revision 2.6 88/10/11 10:26:00 rpd
156 * Added ipc_data to the thread structure.
157 * [88/10/10 08:00:16 rpd]
158 *
159 * Revision 2.5 88/08/24 02:47:53 mwyoung
160 * Adjusted include file references.
161 * [88/08/17 02:24:57 mwyoung]
162 *
163 * 1-Sep-88 David Black (dlb) at Carnegie-Mellon University
164 * Change all usage and delta fields to unsigned to prevent
165 * negative priorities.
166 *
167 * 11-Aug-88 David Black (dlb) at Carnegie-Mellon University
168 * Split exit_code field into ast and halted fields.
169 * Changed thread_should_halt() macro.
170 *
171 * 9-Aug-88 David Black (dlb) at Carnegie-Mellon University
172 * Replaced preempt_pri field with first_quantum.
173 *
174 * 19-Aug-88 David Golub (dbg) at Carnegie-Mellon University
175 * Changed 'struct pcb *' to 'pcb_t' to pry this file loose from
176 * old data structures. Removed include of 'machine/pcb.h' - the
177 * structure definition should be moved to 'machine/thread.h'.
178 *
179 * Revision 2.4 88/08/06 19:22:05 rpd
180 * Declare external variables as "extern".
181 * Added macros ipc_thread_lock(), ipc_thread_unlock().
182 *
183 * Revision 2.3 88/07/17 18:55:10 mwyoung
184 * .
185 *
186 * Revision 2.2.1.1 88/06/28 20:53:40 mwyoung
187 * Reorganized. Added thread_t->vm_privilege.
188 *
189 * Added current_task() declaration.
190 *
191 *
192 * 6-Jul-88 David Golub (dbg) at Carnegie-Mellon University
193 * Remove compatibility data structures. Add per-thread timeout
194 * element.
195 *
196 * 21-Jun-88 Michael Young (mwyoung) at Carnegie-Mellon University
197 * Reorganized. Added thread_t->vm_privilege.
198 *
199 * 4-May-88 David Golub (dbg) at Carnegie-Mellon University
200 * Remove vax-specific field (pcb physical address).
201 *
202 * 19-Apr-88 Michael Young (mwyoung) at Carnegie-Mellon University
203 * Added current_task() declaration.
204 *
205 * 7-Apr-88 David Black (dlb) at Carnegie-Mellon University
206 * MACH_TIME_NEW is now standard.
207 *
208 * 4-Mar-88 David Black (dlb) at Carnegie-Mellon University
209 * Added usage_save and preempt_pri fields.
210 *
211 * 19-Feb-88 David Black (dlb) at Carnegie-Mellon University
212 * Deleted unused ticks field. Rearranged and added MACH_TIME_NEW
213 * fields for scheduler interface. user_ticks and system_ticks are
214 * not needed under MACH_TIME_NEW. Change wait_time to sched_stamp.
215 *
216 * 21-Jan-88 David Golub (dbg) at Carnegie-Mellon University
217 * Replaced swappable boolean with swap_state field. Swap states
218 * are defined in sys/thread_swap.h.
219 *
220 * 17-Jan-88 David Golub (dbg) at Carnegie-Mellon University
221 * Added declarations of new routines.
222 *
223 * 29-Dec-87 David Golub (dbg) at Carnegie-Mellon University
224 * Added declarations of thread_halt() and thread_halt_self().
225 *
226 * 21-Dec-87 David Golub (dbg) at Carnegie-Mellon University
227 * Added thread_should_halt macro.
228 *
229 * 9-Dec-87 David Golub (dbg) at Carnegie-Mellon University
230 * Added exit_code for thread termination and interrupt.
231 * Removed ipc_message_waiting and ipc_timer_set.
232 *
233 * 3-Dec-87 David Black (dlb) at Carnegie-Mellon University
234 * Added ipc_kernel field to indicate when message buffer is in
235 * kernel address space. Added exception_clear_port to cache
236 * reply port for reuse in exc rpc.
237 *
238 * 2-Dec-87 David Black (dlb) at Carnegie-Mellon University
239 * Removed conditionals, purged history.
240 */
241 /*
242 * File: thread.h
243 * Author: Avadis Tevanian, Jr.
244 *
245 * This file contains the structure definitions for threads.
246 *
247 */
248
249 #ifndef _KERN_THREAD_H_
250 #define _KERN_THREAD_H_
251
252 #include <hw_footprint.h>
253 #include <mach_host.h>
254 #include <mach_ipc_compat.h>
255 #include <mach_pcsample.h>
256 #include <mach_rt.h>
257 #include <net_atm.h>
258
259 #include <mach/boolean.h>
260 #include <mach/thread_info.h>
261 #include <mach/thread_status.h>
262 #include <mach/machine/vm_types.h>
263 #include <mach/message.h>
264 #include <mach/port.h>
265 #include <mach/vm_prot.h>
266
267 #include <kern/kern_types.h>
268
269 #include <kern/ast.h>
270 #include <kern/cpu_number.h>
271 #include <kern/lock.h>
272 #include <kern/mach_timer.h>
273 #include <kern/queue.h>
274 #include <kern/sched_policy.h>
275 #include <kern/sched_prim.h> /* event_t, continuation_t */
276 #include <kern/task.h> /* for current_space(), current_map() */
277 #include <kern/timer.h>
278 #include <machine/thread.h>
279 #include <ipc/ipc_types.h>
280
281 #if MACH_PCSAMPLE
282 #include <kern/pc_sample.h>
283 #endif
284
285 /*
286 * Thread structure.
287 *
288 * Fields prefixed with S are locked by thread_sched_lock.
289 * Other fields are locked by thread_lock.
290 */
291
292 struct thread {
293 /* Run queues */
294 queue_chain_t links; /* S current run queue links */
295 struct run_queue_head *runq; /* S run queue p is on SEE BELOW */
296
297 /*
298 * NOTE: The runq field in the thread structure has an unusual
299 * locking protocol. If its value is RUN_QUEUE_HEAD_NULL, then
300 * it is locked by thread_sched_lock, but if its value is something
301 * else (i.e. a run_queue) then it is locked by that run_queue`s
302 * lock.
303 */
304
305 /* Task information */
306 task_t task; /* Task to which I belong */
307 queue_chain_t thread_list; /* list of threads in task */
308
309 /* Thread bookkeeping */
310 queue_chain_t pset_threads; /* list of all threads in proc set*/
311
312 /* Self-preservation */
313 int ref_count; /* number of references to me */
314 decl_simple_lock_data(,ref_lock)
315 /* lock for ref_count */
316 decl_simple_lock_data(,lock) /* lock for everything else */
317
318 /* Hardware state */
319 pcb_t pcb; /* hardware pcb & machine state */
320 vm_offset_t kernel_stack; /* S kernel stack: accurate only
321 if the thread is not swapped
322 and not executing */
323 vm_offset_t stack_privilege;/* reserved kernel stack */
324
325 /* Swapping information */
326 continuation_t swap_func; /* start here after swapin */
327
328 /* Blocking information */
329 decl_simple_lock_data(,sched_lock)
330 /* lock for scheduling fields */
331 event_t wait_event; /* S event we are waiting on */
332 int suspend_count; /* S internal hold (suspend) count */
333 kern_return_t wait_result; /* S outcome of wait -
334 may be examined by this thread
335 WITHOUT locking */
336 boolean_t suspend_wait; /* S someone is waiting for this
337 thread to become suspended */
338 int state; /* S Thread state: */
339 /*
340 * Thread states [bits or'ed]
341 */
342 #define TH_WAIT 0x01 /* thread is queued for waiting */
343 #define TH_SUSP 0x02 /* thread has been asked to stop */
344 #define TH_RUN 0x04 /* thread is running or on runq */
345 #define TH_UNINT 0x08 /* thread is waiting uninteruptibly */
346 #define TH_HALTED 0x10 /* thread is halted at a clean
347 point */
348 #define TH_IDLE 0x80 /* thread is an idle thread */
349
350 #define TH_SCHED_STATE (TH_WAIT|TH_SUSP|TH_RUN|TH_UNINT)
351
352 #define TH_SWAPPED 0x0100 /* thread has no kernel stack */
353 #define TH_SW_COMING_IN 0x0200 /* thread is waiting for kernel
354 stack */
355
356 #define TH_SWAP_STATE (TH_SWAPPED | TH_SW_COMING_IN)
357
358 /* Ast/Halt data structures */
359 int ast; /* S ast's needed. See ast.h */
360 boolean_t active; /* how alive is the thread */
361
362 /* User-visible scheduling state */
363 int user_stop_count;
364 /* S outstanding stops */
365
366 /* Timing data structures */
367 timer_data_t user_timer; /* S user mode timer */
368 timer_data_t system_timer; /* S system mode timer */
369 timer_save_data_t user_timer_save;
370 /* S saved user timer value */
371 timer_save_data_t system_timer_save;
372 /* S saved sys timer value */
373 unsigned int cpu_delta; /* S cpu usage since last update */
374 unsigned int sched_delta; /* S weighted cpu usage since update */
375 unsigned int cpu_usage; /* S exp. decaying cpu usage [%cpu] */
376 unsigned int sched_usage; /* S load-weighted cpu usage [sched] */
377 unsigned int sched_stamp; /* S last time priority was updated */
378
379 /* VM global variables */
380 vm_offset_t recover; /* page fault recovery (copyin/out) */
381 boolean_t vm_privilege; /* Can use reserved memory? */
382
383 /* IPC data structures */
384 thread_t ith_next;
385 thread_t ith_prev; /* IPC thread queue */
386 mach_msg_return_t ith_state;
387 /* send/receive status */
388 union ipc_kmsg_return data; /* received message, or max size */
389 mach_port_seqno_t ith_seqno;
390 /* seqno of recvd message */
391 struct ipc_kmsg_queue ith_messages;
392 /* queue of blocked messages */
393 ipc_port_t ith_self; /* not a right, doesn't hold ref */
394 ipc_port_t ith_sself; /* a send right */
395 ipc_port_t ith_exception; /* a send right */
396 #if MACH_IPC_COMPAT
397 ipc_port_t ith_reply; /* a send right */
398 #endif /* MACH_IPC_COMPAT */
399
400 mach_port_t ith_mig_reply; /* reply port for mig */
401 ipc_port_t ith_rpc_reply; /* reply port for kernel RPCs */
402
403 /* State saved when thread's stack is discarded */
404 union {
405 struct {
406 mach_msg_header_t *msg;
407 mach_msg_option_t option;
408 mach_msg_size_t rcv_size;
409 mach_msg_timeout_t timeout;
410 mach_port_t notify;
411 struct ipc_object *object;
412 struct ipc_mqueue *mqueue;
413 } receive;
414 struct {
415 ipc_port_t port;
416 int exc;
417 int code;
418 int subcode;
419 } exception;
420 void *other; /* catch-all for other state */
421 } saved;
422
423 /* Time-outs */
424 timer_elt_data_t timer; /* S timer for thread */
425
426 /* Processor data structures */
427 processor_set_t processor_set; /* assigned processor set */
428 #if NCPUS > 1
429 processor_t bound_processor; /* bound to processor ? */
430 processor_t last_processor; /* S processor this last ran on */
431 #endif /* NCPUS > 1 */
432
433 #if MACH_PCSAMPLE
434 /* PC sampling */
435 sample_control_t pc_sample; /* S PC sample buffer control */
436 #endif
437
438 #if MACH_RT
439 mach_timer_t rt_wakeup_timer;
440 /* periodic wakeup timer */
441 mach_timer_t rt_deadline_timer;
442 /* deadline expiration timer */
443 ipc_port_t rt_deadline_port;
444 /* deadline notification port */
445 #endif
446
447 /* Scheduling information */
448 int policy_index; /* S current scheduling policy index */
449 sched_policy_t cur_policy; /* S current scheduling policy vector */
450 sched_policy_t sched_policy; /* S scheduling policy in effect,
451 when priority not depressed */
452 sched_param_data_t
453 sched_data; /* S per-policy scheduling parameters */
454 #if NET_ATM
455 nw_ep_owned_t nw_ep_waited;
456 #endif /* NET_ATM */
457 };
458
459 #define ith_msize data.msize
460 #define ith_kmsg data.kmsg
461 #define ith_wait_result wait_result
462
463 #define ith_msg saved.receive.msg
464 #define ith_option saved.receive.option
465 #define ith_rcv_size saved.receive.rcv_size
466 #define ith_timeout saved.receive.timeout
467 #define ith_notify saved.receive.notify
468 #define ith_object saved.receive.object
469 #define ith_mqueue saved.receive.mqueue
470
471 #define ith_port saved.exception.port
472 #define ith_exc saved.exception.exc
473 #define ith_exc_code saved.exception.code
474 #define ith_exc_subcode saved.exception.subcode
475
476 #define ith_other saved.other
477
478 #ifndef _KERN_KERN_TYPES_H_
479 typedef struct thread *thread_t;
480
481 #define THREAD_NULL ((thread_t) 0)
482
483 typedef mach_port_t *thread_array_t;
484 #endif /* _KERN_KERN_TYPES_H_ */
485
486
487 extern thread_t active_threads[NCPUS]; /* active threads */
488 extern vm_offset_t active_stacks[NCPUS]; /* active kernel stacks */
489
490 /*
491 * User routines
492 */
493
494 extern kern_return_t thread_create(
495 task_t parent_task,
496 thread_t *child_thread);
497
498 extern kern_return_t thread_terminate(
499 thread_t thread);
500
501 extern kern_return_t thread_suspend(
502 thread_t thread);
503
504 extern kern_return_t thread_resume(
505 thread_t thread);
506
507 extern kern_return_t thread_abort(
508 thread_t thread);
509
510 extern kern_return_t thread_get_state(
511 thread_t thread,
512 int flavor,
513 thread_state_t old_state,
514 natural_t *old_state_count);
515
516 extern kern_return_t thread_set_state(
517 thread_t thread,
518 int flavor,
519 thread_state_t new_state,
520 natural_t new_state_count);
521
522 extern kern_return_t thread_get_special_port(
523 thread_t thread,
524 int which,
525 ipc_port_t *portp);
526
527 extern kern_return_t thread_set_special_port(
528 thread_t thread,
529 int which,
530 ipc_port_t port);
531
532 extern kern_return_t thread_info(
533 thread_t thread,
534 int flavor,
535 thread_info_t thread_info_out,
536 natural_t *thread_info_count);
537
538 extern kern_return_t thread_assign(
539 thread_t thread,
540 processor_set_t new_pset);
541
542 extern kern_return_t thread_assign_default(
543 thread_t thread);
544
545 extern kern_return_t thread_set_policy(
546 thread_t thread,
547 processor_set_t pset,
548 int policy,
549 policy_param_t param,
550 natural_t count);
551
552 extern kern_return_t thread_set_policy_param(
553 thread_t thread,
554 boolean_t set_limit,
555 policy_param_t param,
556 natural_t count);
557
558 extern kern_return_t thread_set_policy_limit(
559 thread_t thread,
560 processor_set_t pset,
561 policy_param_t param,
562 natural_t count);
563
564 /*
565 * Kernel-only routines
566 */
567
568 extern void thread_init(void);
569 extern void thread_reference(thread_t);
570 extern void thread_deallocate(thread_t);
571 extern void thread_hold(thread_t);
572 extern kern_return_t thread_dowait(
573 thread_t thread,
574 boolean_t must_halt);
575 extern void thread_release(thread_t);
576 extern kern_return_t thread_halt(
577 thread_t thread,
578 boolean_t must_halt);
579 extern void thread_halt_self(continuation_t);
580 extern no_return thread_terminate_self(void);
581 extern void thread_force_terminate(thread_t);
582 extern void thread_set_own_priority(
583 int priority);
584 extern thread_t kernel_thread(
585 task_t task,
586 continuation_t start,
587 void * arg);
588 extern void thread_start(
589 thread_t thread,
590 continuation_t start);
591
592 extern void thread_suspend_nowait(thread_t);
593 extern void thread_deallocate_nowait(thread_t);
594
595 extern no_return reaper_thread(void);
596
597 #if MACH_HOST
598 extern processor_set_t thread_assign_if_empty(
599 thread_t thread);
600 #endif /* MACH_HOST */
601
602 extern void consider_thread_collect(void);
603
604 /*
605 * Macro-defined routines
606 */
607
608 #define thread_pcb(th) ((th)->pcb)
609
610 #define thread_lock(th) simple_lock(&(th)->lock)
611 #define thread_unlock(th) simple_unlock(&(th)->lock)
612 #define thread_ref_lock(th) simple_lock(&(th)->ref_lock)
613 #define thread_ref_unlock(th) simple_unlock(&(th)->ref_lock)
614 #define thread_sched_lock(th) simple_lock(&(th)->sched_lock)
615 #define thread_sched_unlock(th) simple_unlock(&(th)->sched_lock)
616
617 /*
618 * Machine specific implementations of the current thread macro
619 * designate this by defining CURRENT_THREAD.
620 */
621 #ifndef CURRENT_THREAD
622 #define current_thread() (active_threads[cpu_number()])
623 #endif /* CURRENT_THREAD */
624
625 #define current_stack() (active_stacks[cpu_number()])
626
627 #define current_task() (current_thread()->task)
628 #define current_space() (current_task()->itk_space)
629 #define current_map() (current_task()->map)
630
631 /*
632 * Routines required from the machine-dependent
633 * thread module (usually called machine/pcb.c).
634 */
635 extern void pcb_module_init(void);
636
637 extern void pcb_init(
638 thread_t thread);
639 extern void pcb_terminate(
640 thread_t thread);
641 extern void pcb_collect(
642 thread_t thread);
643 extern kern_return_t thread_setstatus(
644 thread_t thread,
645 int flavor,
646 thread_state_t tstate,
647 natural_t count);
648 extern kern_return_t thread_getstatus(
649 thread_t thread,
650 int flavor,
651 thread_state_t tstate, /* in/out */
652 natural_t *count); /* in/out */
653 extern void thread_set_syscall_return(
654 thread_t thread,
655 kern_return_t retval);
656
657 extern vm_offset_t user_stack_low(
658 vm_size_t stack_size);
659
660 extern vm_offset_t set_user_regs(
661 vm_offset_t stack_base,
662 vm_size_t stack_size,
663 natural_t *entry,
664 vm_size_t arg_len);
665
666 #endif /* _KERN_THREAD_H_ */
Cache object: 24f0237610096a6abec04919d64d5d34
|