[apple/xnu.git] / osfmk / kern / sched_prim.h

/*
 * Copyright (c) 2000 Apple Computer, Inc. All rights reserved.
 *
 * @APPLE_LICENSE_HEADER_START@
 * 
 * The contents of this file constitute Original Code as defined in and
 * are subject to the Apple Public Source License Version 1.1 (the
 * "License").  You may not use this file except in compliance with the
 * License.  Please obtain a copy of the License at
 * http://www.apple.com/publicsource and read it before using this file.
 * 
 * This Original Code and all software distributed under the License are
 * distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY KIND, EITHER
 * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
 * INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
 * FITNESS FOR A PARTICULAR PURPOSE OR NON-INFRINGEMENT.  Please see the
 * License for the specific language governing rights and limitations
 * under the License.
 * 
 * @APPLE_LICENSE_HEADER_END@
 */
/*
 * @OSF_COPYRIGHT@
 */
/* 
 * Mach Operating System
 * Copyright (c) 1991,1990,1989,1988,1987 Carnegie Mellon University
 * All Rights Reserved.
 * 
 * Permission to use, copy, modify and distribute this software and its
 * documentation is hereby granted, provided that both the copyright
 * notice and this permission notice appear in all copies of the
 * software, derivative works or modified versions, and any portions
 * thereof, and that both notices appear in supporting documentation.
 * 
 * CARNEGIE MELLON ALLOWS FREE USE OF THIS SOFTWARE IN ITS "AS IS"
 * CONDITION.  CARNEGIE MELLON DISCLAIMS ANY LIABILITY OF ANY KIND FOR
 * ANY DAMAGES WHATSOEVER RESULTING FROM THE USE OF THIS SOFTWARE.
 * 
 * Carnegie Mellon requests users of this software to return to
 * 
 *  Software Distribution Coordinator  or  Software.Distribution@CS.CMU.EDU
 *  School of Computer Science
 *  Carnegie Mellon University
 *  Pittsburgh PA 15213-3890
 * 
 * any improvements or extensions that they make and grant Carnegie Mellon
 * the rights to redistribute these changes.
 */
/*
 */
/*
 *	File:	sched_prim.h
 *	Author:	David Golub
 *
 *	Scheduling primitive definitions file
 *
 */

#ifndef	_KERN_SCHED_PRIM_H_
#define _KERN_SCHED_PRIM_H_

#include <mach/boolean.h>
#include <mach/machine/vm_types.h>
#include <mach/kern_return.h>
#include <kern/clock.h>
#include <kern/kern_types.h>
#include <kern/thread.h>
#include <kern/lock.h>
#include <kern/time_out.h>	/*** ??? temp - remove me soon ***/
#include <kern/cpu_data.h>
#include <kern/wait_queue.h>

#ifdef MACH_KERNEL_PRIVATE

#include <mach_ldebug.h>
/*
 *	Exported interface to sched_prim.c.
 *	A few of these functions are actually defined in
 *	ipc_sched.c, for historical reasons.
 */

/* Initialize scheduler module */
extern void		sched_init(void);

/*
 * Set up thread timeout element(s) when thread is created.
 */
extern void		thread_timer_setup(
					thread_t		thread);

extern void		thread_timer_terminate(void);

#define thread_bind_locked(thread, processor)	\
		(thread)->bound_processor = (processor)

/*
 * Prevent a thread from restarting after it blocks interruptibly
 */
extern boolean_t	thread_stop( 
						thread_t	thread);

/*
 * wait for a thread to stop
 */
extern boolean_t	thread_wait(
						thread_t	thread);

/* Select a thread to run on a particular processor */
extern thread_t	thread_select(
						processor_t	myprocessor);

extern void		thread_go_locked(
					 	thread_t	thread,
						int		result);

/* Stop old thread and run new thread */
extern boolean_t thread_invoke(
						thread_t	old_thread,
						thread_t	new_thread,
						int			reason,
						void        (*continuation)(void));

/* Called when current thread is given new stack */
extern void		thread_continue(
						thread_t	old_thread);

/* Switch directly to a particular thread */
extern int		thread_run(
						thread_t	old_thread,
						void		(*continuation)(void),
						thread_t	new_thread);

/* Dispatch a thread not on a run queue */
extern void		thread_dispatch(
						thread_t	thread);

/* Invoke continuation */
extern void		call_continuation(
						void		(*continuation)(void));

/* Compute effective priority of the specified thread */
extern void		compute_priority(
						thread_t	thread,
						int			resched);

/* Version of compute_priority for current thread or
 * thread being manipuldated by scheduler.
 */
extern void		compute_my_priority(
						thread_t	thread);

/* Periodic scheduler activity */
extern void		sched_tick_init(void);

/* Update priority of thread that has been sleeping or suspended.
 * Used to "catch up" with the system.
 */
extern void		update_priority(
						thread_t	thread);

/* Idle thread loop */
extern void		idle_thread(void);

/*
 *	thread_sleep_interlock:
 *
 *	Cause the current thread to wait until the specified event
 *	occurs.  The specified HW interlock is unlocked before releasing
 *	the cpu.  (This is a convenient way to sleep without manually
 *	calling assert_wait).
 */

#define thread_sleep_interlock(event, lock, interruptible)	\
MACRO_BEGIN													\
	assert_wait(event, interruptible);						\
	interlock_unlock(lock);									\
	thread_block((void (*)(void)) 0);						\
MACRO_END

/*
 *	Machine-dependent code must define these functions.
 */

/* Start thread running */
extern void		thread_bootstrap_return(void);

/* Return from exception */
extern void		thread_exception_return(void);

/* Continuation return from syscall */
extern void     thread_syscall_return(
                        kern_return_t   ret);

extern thread_t	switch_context(
						thread_t	old_thread,
						void		(*continuation)(void),
						thread_t	new_thread);

/* Attach stack to thread */
extern void		machine_kernel_stack_init(
						thread_t	thread,
						void		(*start_pos)(thread_t));

extern void		load_context(
						thread_t	thread);

extern thread_act_t		switch_act(
							thread_act_t	act);

extern void		machine_switch_act(
							thread_t		thread,
							thread_act_t	old,
							thread_act_t	new,
							int				cpu);

/*
 *	These functions are either defined in kern/thread.c
 *	or are defined directly by machine-dependent code.
 */

/* Allocate an activation stack */
extern vm_offset_t	stack_alloc(thread_t thread, void (*start_pos)(thread_t));

/* Free an activation stack */
extern void		stack_free(thread_t thread);

/* Collect excess kernel stacks */
extern void		stack_collect(void);

extern void		set_pri(
					thread_t	thread,
					int			pri,
					boolean_t	resched);

/* Block current thread, indicating reason (Block or Quantum expiration) */
extern int		thread_block_reason(
						void		(*continuation)(void),
						int		reason);

/* Make thread runnable */
extern void		thread_setrun(
						thread_t	thread,
						boolean_t	may_preempt,
						boolean_t	tail);
/*
 *	Flags for thread_setrun()
 */

#define HEAD_Q		0		/* FALSE */
#define TAIL_Q		1		/* TRUE */

/* Bind thread to a particular processor */
extern void		thread_bind(
						thread_t	thread,
						processor_t	processor);

extern void		thread_mark_wait_locked(
						thread_t	thread,
						int			interruptible);

#endif /* MACH_KERNEL_PRIVATE */

/*
 ****************** Only exported until BSD stops using ********************
 */

/*
 * Cancel a stop and continue the thread if necessary.
 */
extern void		thread_unstop(
						thread_t	thread);

/* Wake up thread directly, passing result */
extern void		clear_wait(
						thread_t	thread,
						int		result);

/* Bind thread to a particular processor */
extern void		thread_bind(
						thread_t	thread,
						processor_t	processor);


/*
 * *********************   PUBLIC APIs ************************************
 */

/* Set timer for current thread */
extern void		thread_set_timer(
					uint32_t		interval,
					uint32_t		scale_factor);

extern void		thread_set_timer_deadline(
					uint64_t		deadline);

extern void		thread_cancel_timer(void);

/*
 * thread_stop a thread then wait for it to stop (both of the above)
 */
extern boolean_t	thread_stop_wait(
						thread_t	thread);

/* Declare thread will wait on a particular event */
extern void		assert_wait(
						event_t		event,
						int		interruptflag);

/* Assert that the thread intends to wait for a timeout */
extern void		assert_wait_timeout(
					        natural_t	msecs,
						int		interruptflags);

/* Wake up thread (or threads) waiting on a particular event */
extern void		thread_wakeup_prim(
						event_t		event,
						boolean_t	one_thread,
						int		result);

/* Block current thread (Block reason) */
extern int		thread_block(
						void		(*continuation)(void));


/*
 *	Routines defined as macros
 */

#define thread_wakeup(x)					\
			thread_wakeup_prim((x), FALSE, THREAD_AWAKENED)
#define thread_wakeup_with_result(x, z)		\
			thread_wakeup_prim((x), FALSE, (z))
#define thread_wakeup_one(x)				\
			thread_wakeup_prim((x), TRUE, THREAD_AWAKENED)

/*
 *	thread_sleep_mutex:
 *
 *	Cause the current thread to wait until the specified event
 *	occurs.  The specified mutex is unlocked before releasing
 *	the cpu.  (This is a convenient way to sleep without manually
 *	calling assert_wait).
 */

#define thread_sleep_mutex(event, lock, interruptible)	\
MACRO_BEGIN												\
	assert_wait(event, interruptible);					\
	mutex_unlock(lock);									\
	thread_block((void (*)(void)) 0);					\
MACRO_END

/*
 *	thread_sleep_simple_lock:
 *
 *	Cause the current thread to wait until the specified event
 *	occurs.  The specified simple_lock is unlocked before releasing
 *	the cpu.  (This is a convenient way to sleep without manually
 *	calling assert_wait).
 */

#define thread_sleep_simple_lock(event, lock, interruptible)	\
MACRO_BEGIN														\
	assert_wait(event, interruptible);							\
	simple_unlock(lock);										\
	thread_block((void (*)(void)) 0);							\
MACRO_END

#if		!defined(MACH_KERNEL_PRIVATE) && !defined(ABSOLUTETIME_SCALAR_TYPE)

#include <libkern/OSBase.h>

#define thread_set_timer_deadline(a)	\
	thread_set_timer_deadline(__OSAbsoluteTime(a))

#endif

#endif	/* _KERN_SCHED_PRIM_H_ */
Commit	Line	Data
1c79356b A	1	/*
	2	* Copyright (c) 2000 Apple Computer, Inc. All rights reserved.
	3	*
	4	* @APPLE_LICENSE_HEADER_START@
	5	*
	6	* The contents of this file constitute Original Code as defined in and
	7	* are subject to the Apple Public Source License Version 1.1 (the
	8	* "License"). You may not use this file except in compliance with the
	9	* License. Please obtain a copy of the License at
	10	* http://www.apple.com/publicsource and read it before using this file.
	11	*
	12	* This Original Code and all software distributed under the License are
	13	* distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY KIND, EITHER
	14	* EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
	15	* INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
	16	* FITNESS FOR A PARTICULAR PURPOSE OR NON-INFRINGEMENT. Please see the
	17	* License for the specific language governing rights and limitations
	18	* under the License.
	19	*
	20	* @APPLE_LICENSE_HEADER_END@
	21	*/
	22	/*
	23	* @OSF_COPYRIGHT@
	24	*/
	25	/*
	26	* Mach Operating System
	27	* Copyright (c) 1991,1990,1989,1988,1987 Carnegie Mellon University
	28	* All Rights Reserved.
	29	*
	30	* Permission to use, copy, modify and distribute this software and its
	31	* documentation is hereby granted, provided that both the copyright
	32	* notice and this permission notice appear in all copies of the
	33	* software, derivative works or modified versions, and any portions
	34	* thereof, and that both notices appear in supporting documentation.
	35	*
	36	* CARNEGIE MELLON ALLOWS FREE USE OF THIS SOFTWARE IN ITS "AS IS"
	37	* CONDITION. CARNEGIE MELLON DISCLAIMS ANY LIABILITY OF ANY KIND FOR
	38	* ANY DAMAGES WHATSOEVER RESULTING FROM THE USE OF THIS SOFTWARE.
	39	*
	40	* Carnegie Mellon requests users of this software to return to
	41	*
	42	* Software Distribution Coordinator or Software.Distribution@CS.CMU.EDU
	43	* School of Computer Science
	44	* Carnegie Mellon University
	45	* Pittsburgh PA 15213-3890
	46	*
	47	* any improvements or extensions that they make and grant Carnegie Mellon
	48	* the rights to redistribute these changes.
	49	*/
	50	/*
	51	*/
	52	/*
	53	* File: sched_prim.h
	54	* Author: David Golub
	55	*
	56	* Scheduling primitive definitions file
	57	*
	58	*/
	59
	60	#ifndef _KERN_SCHED_PRIM_H_
	61	#define _KERN_SCHED_PRIM_H_
	62
	63	#include <mach/boolean.h>
	64	#include <mach/machine/vm_types.h>
65	#include <mach/kern_return.h>
66	#include <kern/clock.h>
67	#include <kern/kern_types.h>
68	#include <kern/thread.h>
69	#include <kern/lock.h>
70	#include <kern/time_out.h> /* ??? temp - remove me soon */
71	#include <kern/cpu_data.h>
72	#include <kern/wait_queue.h>
73
74	#ifdef MACH_KERNEL_PRIVATE
75
76	#include <mach_ldebug.h>
77	/*
78	* Exported interface to sched_prim.c.
79	* A few of these functions are actually defined in
80	* ipc_sched.c, for historical reasons.
81	*/
82
83	/* Initialize scheduler module */
84	extern void sched_init(void);
85
86	/*
87	* Set up thread timeout element(s) when thread is created.
88	*/
89	extern void thread_timer_setup(
90	thread_t thread);
91
92	extern void thread_timer_terminate(void);
93
94	#define thread_bind_locked(thread, processor) \
95	(thread)->bound_processor = (processor)
96
97	/*
98	* Prevent a thread from restarting after it blocks interruptibly
99	*/
100	extern boolean_t thread_stop(
101	thread_t thread);
102
103	/*
104	* wait for a thread to stop
105	*/
106	extern boolean_t thread_wait(
107	thread_t thread);
108
109	/* Select a thread to run on a particular processor */
110	extern thread_t thread_select(
111	processor_t myprocessor);
112
113	extern void thread_go_locked(
114	thread_t thread,
115	int result);
116
117	/* Stop old thread and run new thread */
118	extern boolean_t thread_invoke(
119	thread_t old_thread,
120	thread_t new_thread,
121	int reason,
122	void (*continuation)(void));
123
124	/* Called when current thread is given new stack */
125	extern void thread_continue(
126	thread_t old_thread);
127
128	/* Switch directly to a particular thread */
129	extern int thread_run(
130	thread_t old_thread,
131	void (*continuation)(void),
132	thread_t new_thread);
133
134	/* Dispatch a thread not on a run queue */
135	extern void thread_dispatch(
136	thread_t thread);
137
138	/* Invoke continuation */
139	extern void call_continuation(
140	void (*continuation)(void));
141
142	/* Compute effective priority of the specified thread */
143	extern void compute_priority(
144	thread_t thread,
145	int resched);
146
147	/* Version of compute_priority for current thread or
148	* thread being manipuldated by scheduler.
149	*/
150	extern void compute_my_priority(
151	thread_t thread);
152
153	/* Periodic scheduler activity */
0b4e3aa0	154	extern void sched_tick_init(void);
1c79356b A	155
	156	/* Update priority of thread that has been sleeping or suspended.
	157	* Used to "catch up" with the system.
	158	*/
	159	extern void update_priority(
	160	thread_t thread);
	161
	162	/* Idle thread loop */
	163	extern void idle_thread(void);
	164
	165	/*
	166	* thread_sleep_interlock:
	167	*
	168	* Cause the current thread to wait until the specified event
	169	* occurs. The specified HW interlock is unlocked before releasing
	170	* the cpu. (This is a convenient way to sleep without manually
	171	* calling assert_wait).
	172	*/
	173
	174	#define thread_sleep_interlock(event, lock, interruptible) \
	175	MACRO_BEGIN \
	176	assert_wait(event, interruptible); \
	177	interlock_unlock(lock); \
	178	thread_block((void (*)(void)) 0); \
	179	MACRO_END
	180
	181	/*
	182	* Machine-dependent code must define these functions.
	183	*/
	184
	185	/* Start thread running */
	186	extern void thread_bootstrap_return(void);
	187
	188	/* Return from exception */
	189	extern void thread_exception_return(void);
	190
	191	/* Continuation return from syscall */
	192	extern void thread_syscall_return(
	193	kern_return_t ret);
	194
	195	extern thread_t switch_context(
	196	thread_t old_thread,
	197	void (*continuation)(void),
	198	thread_t new_thread);
	199
	200	/* Attach stack to thread */
	201	extern void machine_kernel_stack_init(
	202	thread_t thread,
	203	void (*start_pos)(thread_t));
	204
	205	extern void load_context(
	206	thread_t thread);
	207
	208	extern thread_act_t switch_act(
	209	thread_act_t act);
	210
	211	extern void machine_switch_act(
	212	thread_t thread,
	213	thread_act_t old,
	214	thread_act_t new,
	215	int cpu);
	216
	217	/*
	218	* These functions are either defined in kern/thread.c
219	* or are defined directly by machine-dependent code.
220	*/
221
222	/* Allocate an activation stack */
223	extern vm_offset_t stack_alloc(thread_t thread, void (*start_pos)(thread_t));
224
225	/* Free an activation stack */
226	extern void stack_free(thread_t thread);
227
228	/* Collect excess kernel stacks */
229	extern void stack_collect(void);
230
231	extern void set_pri(
232	thread_t thread,
233	int pri,
234	boolean_t resched);
235
236	/* Block current thread, indicating reason (Block or Quantum expiration) */
237	extern int thread_block_reason(
238	void (*continuation)(void),
239	int reason);
240
241	/* Make thread runnable */
242	extern void thread_setrun(
243	thread_t thread,
244	boolean_t may_preempt,
245	boolean_t tail);
246	/*
247	* Flags for thread_setrun()
248	*/
249
250	#define HEAD_Q 0 /* FALSE */
251	#define TAIL_Q 1 /* TRUE */
252
253	/* Bind thread to a particular processor */
254	extern void thread_bind(
255	thread_t thread,
256	processor_t processor);
257
258	extern void thread_mark_wait_locked(
259	thread_t thread,
260	int interruptible);
261
262	#endif /* MACH_KERNEL_PRIVATE */
263
264	/*
265	**************** Only exported until BSD stops using ******************
266	*/
267
268	/*
269	* Cancel a stop and continue the thread if necessary.
270	*/
271	extern void thread_unstop(
272	thread_t thread);
273
274	/* Wake up thread directly, passing result */
275	extern void clear_wait(
276	thread_t thread,
277	int result);
278
279	/* Bind thread to a particular processor */
280	extern void thread_bind(
281	thread_t thread,
282	processor_t processor);
283
284
285	/*
286	* ******************* PUBLIC APIs **********************************
287	*/
288
289	/* Set timer for current thread */
290	extern void thread_set_timer(
0b4e3aa0 A	291	uint32_t interval,
0b4e3aa0 A	292	uint32_t scale_factor);
1c79356b A	293
1c79356b A	294	extern void thread_set_timer_deadline(
0b4e3aa0	295	uint64_t deadline);
1c79356b A	296
	297	extern void thread_cancel_timer(void);
	298
	299	/*
	300	* thread_stop a thread then wait for it to stop (both of the above)
	301	*/
	302	extern boolean_t thread_stop_wait(
	303	thread_t thread);
	304
	305	/* Declare thread will wait on a particular event */
	306	extern void assert_wait(
	307	event_t event,
	308	int interruptflag);
	309
	310	/* Assert that the thread intends to wait for a timeout */
	311	extern void assert_wait_timeout(
	312	natural_t msecs,
	313	int interruptflags);
	314
	315	/* Wake up thread (or threads) waiting on a particular event */
	316	extern void thread_wakeup_prim(
	317	event_t event,
	318	boolean_t one_thread,
	319	int result);
	320
	321	/* Block current thread (Block reason) */
	322	extern int thread_block(
	323	void (*continuation)(void));
	324
	325
	326	/*
	327	* Routines defined as macros
	328	*/
	329
	330	#define thread_wakeup(x) \
	331	thread_wakeup_prim((x), FALSE, THREAD_AWAKENED)
	332	#define thread_wakeup_with_result(x, z) \
	333	thread_wakeup_prim((x), FALSE, (z))
	334	#define thread_wakeup_one(x) \
	335	thread_wakeup_prim((x), TRUE, THREAD_AWAKENED)
	336
	337	/*
	338	* thread_sleep_mutex:
	339	*
	340	* Cause the current thread to wait until the specified event
	341	* occurs. The specified mutex is unlocked before releasing
	342	* the cpu. (This is a convenient way to sleep without manually
	343	* calling assert_wait).
	344	*/
	345
	346	#define thread_sleep_mutex(event, lock, interruptible) \
	347	MACRO_BEGIN \
	348	assert_wait(event, interruptible); \
	349	mutex_unlock(lock); \
	350	thread_block((void (*)(void)) 0); \
	351	MACRO_END
	352
	353	/*
	354	* thread_sleep_simple_lock:
	355	*
	356	* Cause the current thread to wait until the specified event
	357	* occurs. The specified simple_lock is unlocked before releasing
	358	* the cpu. (This is a convenient way to sleep without manually
	359	* calling assert_wait).
360	*/
361
362	#define thread_sleep_simple_lock(event, lock, interruptible) \
363	MACRO_BEGIN \
364	assert_wait(event, interruptible); \
365	simple_unlock(lock); \
366	thread_block((void (*)(void)) 0); \
367	MACRO_END
368
0b4e3aa0 A	369	#if !defined(MACH_KERNEL_PRIVATE) && !defined(ABSOLUTETIME_SCALAR_TYPE)
	370
	371	#include <libkern/OSBase.h>
	372
	373	#define thread_set_timer_deadline(a) \
	374	thread_set_timer_deadline(__OSAbsoluteTime(a))
	375
	376	#endif
1c79356b A	377
1c79356b A	378	#endif /* _KERN_SCHED_PRIM_H_ */