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

/*
 * Copyright (c) 2000 Apple Computer, Inc. All rights reserved.
 *
 * @APPLE_LICENSE_HEADER_START@
 * 
 * Copyright (c) 1999-2003 Apple Computer, Inc.  All Rights Reserved.
 * 
 * This file contains Original Code and/or Modifications of Original Code
 * as defined in and that are subject to the Apple Public Source License
 * Version 2.0 (the 'License'). You may not use this file except in
 * compliance with the License. Please obtain a copy of the License at
 * http://www.opensource.apple.com/apsl/ and read it before using this
 * file.
 * 
 * The 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, QUIET ENJOYMENT 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 <sys/appleapiopts.h>

#ifdef	__APPLE_API_PRIVATE

#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);

extern void		sched_timebase_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);

/*
 * Stop a thread and wait for it to stop running.
 */
extern boolean_t	thread_stop( 
						thread_t	thread);

/*
 * Wait for a thread to stop running.
 */
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 kern_return_t thread_go_locked(
					 	thread_t		thread,
						wait_result_t	result);

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

/* 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,
						thread_continue_t continuation,
						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(
						thread_continue_t continuation);		  

/* Set the current scheduled priority */
extern void		set_sched_pri(
					thread_t		thread,
					int				priority);

/* Set base priority of the specified thread */
extern void		set_priority(
					thread_t		thread,
					int				priority);

/* Reset scheduled priority of thread */
extern void		compute_priority(
					thread_t		thread,
					boolean_t		override_depress);

/* Adjust scheduled priority of thread during execution */
extern void		compute_my_priority(
					thread_t		thread);

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

/*
 * Update thread to the current scheduler tick.
 */
extern void		update_priority(
					thread_t		thread);

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

/*
 *	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);

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

/* Block current thread, indicating reason */
extern wait_result_t	thread_block_reason(
							thread_continue_t	continuation,
							ast_t				reason);

/* Dispatch a thread for execution */
extern void		thread_setrun(
					thread_t	thread,
					integer_t	options);

#define SCHED_TAILQ		0
#define SCHED_HEADQ		1
#define SCHED_PREEMPT	2

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

/* Set the maximum interrupt level for the thread */
__private_extern__ wait_interrupt_t thread_interrupt_level(
						wait_interrupt_t interruptible);

__private_extern__ wait_result_t thread_mark_wait_locked(
						thread_t		 thread,
						wait_interrupt_t interruptible);

/* Sleep, unlocking and then relocking a usimple_lock in the process */
__private_extern__ wait_result_t thread_sleep_fast_usimple_lock(
						event_t			event,
						simple_lock_t	lock,
						wait_interrupt_t interruptible);

/* Wake up locked thread directly, passing result */
__private_extern__ kern_return_t clear_wait_internal(
						thread_t		thread,
						wait_result_t	result);

__private_extern__
	wait_queue_t	wait_event_wait_queue(
						event_t			event);

#endif /* MACH_KERNEL_PRIVATE */

extern wait_result_t	assert_wait_prim(
							event_t				event,
							thread_roust_t		roust_hint,
							uint64_t			deadline,
							wait_interrupt_t	interruptible);

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

/*
 * Cancel a stop and unblock the thread if already stopped.
 */
extern void		thread_unstop(
						thread_t		thread);

/* Wake up thread directly, passing result */
extern kern_return_t clear_wait(
						thread_t		thread,
						wait_result_t	result);

#endif	/* __APPLE_API_PRIVATE */

/*
 * *********************   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);

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

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

/* Sleep, unlocking and then relocking a usimple_lock in the process */
extern wait_result_t thread_sleep_usimple_lock(
						event_t			event,
						usimple_lock_t	lock,
						wait_interrupt_t interruptible);	

/* Sleep, unlocking and then relocking a mutex in the process */
extern wait_result_t thread_sleep_mutex(
						event_t			event,
						mutex_t			*mutex,
						wait_interrupt_t interruptible);	
										
/* Sleep with a deadline, unlocking and then relocking a mutex in the process */
extern wait_result_t thread_sleep_mutex_deadline(
						event_t			event,
						mutex_t			*mutex,
						uint64_t		deadline,
						wait_interrupt_t interruptible);	

/* Sleep, unlocking and then relocking a write lock in the process */
extern wait_result_t thread_sleep_lock_write(
						event_t			event,
						lock_t			*lock,
						wait_interrupt_t interruptible);	
									   
/* Sleep, hinting that a thread funnel may be involved in the process */
extern wait_result_t thread_sleep_funnel(
						event_t			event,
						wait_interrupt_t interruptible);	

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

#ifdef	__APPLE_API_UNSTABLE

/* Block current thread (Block reason) */
extern wait_result_t thread_block(
						thread_continue_t continuation);

#endif	/* __APPLE_API_UNSTABLE */

/*
 *	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)

#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	*
43866e37	6	* Copyright (c) 1999-2003 Apple Computer, Inc. All Rights Reserved.
1c79356b	7	*
43866e37 A	8	* This file contains Original Code and/or Modifications of Original Code
	9	* as defined in and that are subject to the Apple Public Source License
	10	* Version 2.0 (the 'License'). You may not use this file except in
	11	* compliance with the License. Please obtain a copy of the License at
	12	* http://www.opensource.apple.com/apsl/ and read it before using this
	13	* file.
	14	*
	15	* The Original Code and all software distributed under the License are
	16	* distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER
1c79356b A	17	* EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
1c79356b A	18	* INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
43866e37 A	19	* FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT.
	20	* Please see the License for the specific language governing rights and
	21	* limitations under the License.
1c79356b A	22	*
	23	* @APPLE_LICENSE_HEADER_END@
	24	*/
	25	/*
	26	* @OSF_COPYRIGHT@
	27	*/
	28	/*
	29	* Mach Operating System
	30	* Copyright (c) 1991,1990,1989,1988,1987 Carnegie Mellon University
	31	* All Rights Reserved.
	32	*
	33	* Permission to use, copy, modify and distribute this software and its
	34	* documentation is hereby granted, provided that both the copyright
	35	* notice and this permission notice appear in all copies of the
	36	* software, derivative works or modified versions, and any portions
	37	* thereof, and that both notices appear in supporting documentation.
	38	*
	39	* CARNEGIE MELLON ALLOWS FREE USE OF THIS SOFTWARE IN ITS "AS IS"
	40	* CONDITION. CARNEGIE MELLON DISCLAIMS ANY LIABILITY OF ANY KIND FOR
	41	* ANY DAMAGES WHATSOEVER RESULTING FROM THE USE OF THIS SOFTWARE.
	42	*
	43	* Carnegie Mellon requests users of this software to return to
	44	*
	45	* Software Distribution Coordinator or Software.Distribution@CS.CMU.EDU
	46	* School of Computer Science
	47	* Carnegie Mellon University
	48	* Pittsburgh PA 15213-3890
	49	*
	50	* any improvements or extensions that they make and grant Carnegie Mellon
	51	* the rights to redistribute these changes.
	52	*/
	53	/*
	54	*/
	55	/*
	56	* File: sched_prim.h
	57	* Author: David Golub
	58	*
	59	* Scheduling primitive definitions file
	60	*
	61	*/
	62
	63	#ifndef _KERN_SCHED_PRIM_H_
	64	#define _KERN_SCHED_PRIM_H_
	65
	66	#include <mach/boolean.h>
	67	#include <mach/machine/vm_types.h>
	68	#include <mach/kern_return.h>
	69	#include <kern/clock.h>
	70	#include <kern/kern_types.h>
	71	#include <kern/thread.h>
	72	#include <kern/lock.h>
	73	#include <kern/time_out.h> /* ??? temp - remove me soon */
	74	#include <kern/cpu_data.h>
1c79356b	75
9bccf70c A	76	#include <sys/appleapiopts.h>
	77
	78	#ifdef __APPLE_API_PRIVATE
	79
	80	#ifdef MACH_KERNEL_PRIVATE
1c79356b A	81
	82	#include <mach_ldebug.h>
	83	/*
	84	* Exported interface to sched_prim.c.
	85	* A few of these functions are actually defined in
	86	* ipc_sched.c, for historical reasons.
	87	*/
	88
	89	/* Initialize scheduler module */
	90	extern void sched_init(void);
	91
55e303ae A	92	extern void sched_timebase_init(void);
55e303ae A	93
1c79356b A	94	/*
	95	* Set up thread timeout element(s) when thread is created.
	96	*/
	97	extern void thread_timer_setup(
	98	thread_t thread);
	99
	100	extern void thread_timer_terminate(void);
	101
1c79356b	102	/*
9bccf70c	103	* Stop a thread and wait for it to stop running.
1c79356b A	104	*/
	105	extern boolean_t thread_stop(
	106	thread_t thread);
	107
	108	/*
9bccf70c	109	* Wait for a thread to stop running.
1c79356b A	110	*/
	111	extern boolean_t thread_wait(
	112	thread_t thread);
	113
	114	/* Select a thread to run on a particular processor */
	115	extern thread_t thread_select(
	116	processor_t myprocessor);
	117
9bccf70c A	118	extern kern_return_t thread_go_locked(
	119	thread_t thread,
	120	wait_result_t result);
1c79356b A	121
	122	/* Stop old thread and run new thread */
	123	extern boolean_t thread_invoke(
9bccf70c A	124	thread_t old_thread,
	125	thread_t new_thread,
	126	int reason,
	127	thread_continue_t continuation);
1c79356b A	128
	129	/* Called when current thread is given new stack */
	130	extern void thread_continue(
9bccf70c	131	thread_t old_thread);
1c79356b A	132
	133	/* Switch directly to a particular thread */
	134	extern int thread_run(
9bccf70c A	135	thread_t old_thread,
	136	thread_continue_t continuation,
	137	thread_t new_thread);
1c79356b A	138
	139	/* Dispatch a thread not on a run queue */
	140	extern void thread_dispatch(
9bccf70c	141	thread_t thread);
1c79356b A	142
	143	/* Invoke continuation */
	144	extern void call_continuation(
9bccf70c A	145	thread_continue_t continuation);
	146
	147	/* Set the current scheduled priority */
	148	extern void set_sched_pri(
	149	thread_t thread,
	150	int priority);
1c79356b	151
9bccf70c A	152	/* Set base priority of the specified thread */
	153	extern void set_priority(
	154	thread_t thread,
	155	int priority);
	156
	157	/* Reset scheduled priority of thread */
1c79356b	158	extern void compute_priority(
9bccf70c A	159	thread_t thread,
9bccf70c A	160	boolean_t override_depress);
1c79356b	161
9bccf70c	162	/* Adjust scheduled priority of thread during execution */
1c79356b	163	extern void compute_my_priority(
9bccf70c	164	thread_t thread);
1c79356b A	165
1c79356b A	166	/* Periodic scheduler activity */
0b4e3aa0	167	extern void sched_tick_init(void);
1c79356b	168
9bccf70c A	169	/*
9bccf70c A	170	* Update thread to the current scheduler tick.
1c79356b A	171	*/
1c79356b A	172	extern void update_priority(
9bccf70c	173	thread_t thread);
1c79356b A	174
	175	/* Idle thread loop */
	176	extern void idle_thread(void);
	177
1c79356b A	178	/*
	179	* Machine-dependent code must define these functions.
	180	*/
	181
	182	/* Start thread running */
	183	extern void thread_bootstrap_return(void);
	184
	185	/* Return from exception */
	186	extern void thread_exception_return(void);
	187
	188	/* Continuation return from syscall */
	189	extern void thread_syscall_return(
	190	kern_return_t ret);
	191
1c79356b A	192	/*
	193	* These functions are either defined in kern/thread.c
	194	* or are defined directly by machine-dependent code.
	195	*/
	196
9bccf70c A	197	/* Block current thread, indicating reason */
	198	extern wait_result_t thread_block_reason(
	199	thread_continue_t continuation,
	200	ast_t reason);
1c79356b	201
9bccf70c	202	/* Dispatch a thread for execution */
1c79356b	203	extern void thread_setrun(
9bccf70c	204	thread_t thread,
55e303ae	205	integer_t options);
1c79356b	206
55e303ae A	207	#define SCHED_TAILQ 0
	208	#define SCHED_HEADQ 1
	209	#define SCHED_PREEMPT 2
1c79356b A	210
1c79356b A	211	/* Bind thread to a particular processor */
55e303ae A	212	extern processor_t thread_bind(
	213	thread_t thread,
	214	processor_t processor);
1c79356b	215
9bccf70c A	216	/* Set the maximum interrupt level for the thread */
	217	__private_extern__ wait_interrupt_t thread_interrupt_level(
	218	wait_interrupt_t interruptible);
	219
	220	__private_extern__ wait_result_t thread_mark_wait_locked(
	221	thread_t thread,
	222	wait_interrupt_t interruptible);
	223
	224	/* Sleep, unlocking and then relocking a usimple_lock in the process */
	225	__private_extern__ wait_result_t thread_sleep_fast_usimple_lock(
	226	event_t event,
	227	simple_lock_t lock,
	228	wait_interrupt_t interruptible);
	229
	230	/* Wake up locked thread directly, passing result */
	231	__private_extern__ kern_return_t clear_wait_internal(
	232	thread_t thread,
	233	wait_result_t result);
1c79356b	234
55e303ae A	235	__private_extern__
	236	wait_queue_t wait_event_wait_queue(
	237	event_t event);
	238
1c79356b A	239	#endif /* MACH_KERNEL_PRIVATE */
1c79356b A	240
55e303ae A	241	extern wait_result_t assert_wait_prim(
	242	event_t event,
	243	thread_roust_t roust_hint,
	244	uint64_t deadline,
	245	wait_interrupt_t interruptible);
	246
1c79356b A	247	/*
	248	**************** Only exported until BSD stops using ******************
	249	*/
	250
	251	/*
9bccf70c	252	* Cancel a stop and unblock the thread if already stopped.
1c79356b A	253	*/
1c79356b A	254	extern void thread_unstop(
9bccf70c	255	thread_t thread);
1c79356b A	256
1c79356b A	257	/* Wake up thread directly, passing result */
9bccf70c A	258	extern kern_return_t clear_wait(
	259	thread_t thread,
	260	wait_result_t result);
1c79356b	261
9bccf70c	262	#endif /* __APPLE_API_PRIVATE */
1c79356b A	263
	264	/*
	265	* ******************* PUBLIC APIs **********************************
	266	*/
	267
	268	/* Set timer for current thread */
	269	extern void thread_set_timer(
0b4e3aa0 A	270	uint32_t interval,
0b4e3aa0 A	271	uint32_t scale_factor);
1c79356b A	272
1c79356b A	273	extern void thread_set_timer_deadline(
0b4e3aa0	274	uint64_t deadline);
1c79356b A	275
	276	extern void thread_cancel_timer(void);
	277
1c79356b	278	/* Declare thread will wait on a particular event */
9bccf70c A	279	extern wait_result_t assert_wait(
	280	event_t event,
	281	wait_interrupt_t interruptflag);
1c79356b A	282
1c79356b A	283	/* Assert that the thread intends to wait for a timeout */
9bccf70c A	284	extern wait_result_t assert_wait_timeout(
	285	natural_t msecs,
	286	wait_interrupt_t interruptflags);
	287
	288	/* Sleep, unlocking and then relocking a usimple_lock in the process */
	289	extern wait_result_t thread_sleep_usimple_lock(
	290	event_t event,
	291	usimple_lock_t lock,
	292	wait_interrupt_t interruptible);
	293
	294	/* Sleep, unlocking and then relocking a mutex in the process */
	295	extern wait_result_t thread_sleep_mutex(
	296	event_t event,
	297	mutex_t *mutex,
	298	wait_interrupt_t interruptible);
	299
	300	/* Sleep with a deadline, unlocking and then relocking a mutex in the process */
	301	extern wait_result_t thread_sleep_mutex_deadline(
	302	event_t event,
	303	mutex_t *mutex,
	304	uint64_t deadline,
	305	wait_interrupt_t interruptible);
	306
	307	/* Sleep, unlocking and then relocking a write lock in the process */
	308	extern wait_result_t thread_sleep_lock_write(
	309	event_t event,
	310	lock_t *lock,
	311	wait_interrupt_t interruptible);
	312
	313	/* Sleep, hinting that a thread funnel may be involved in the process */
	314	extern wait_result_t thread_sleep_funnel(
	315	event_t event,
	316	wait_interrupt_t interruptible);
1c79356b A	317
1c79356b A	318	/* Wake up thread (or threads) waiting on a particular event */
9bccf70c A	319	extern kern_return_t thread_wakeup_prim(
	320	event_t event,
	321	boolean_t one_thread,
	322	wait_result_t result);
	323
	324	#ifdef __APPLE_API_UNSTABLE
1c79356b A	325
1c79356b A	326	/* Block current thread (Block reason) */
9bccf70c A	327	extern wait_result_t thread_block(
9bccf70c A	328	thread_continue_t continuation);
1c79356b	329
9bccf70c	330	#endif /* __APPLE_API_UNSTABLE */
1c79356b A	331
	332	/*
	333	* Routines defined as macros
	334	*/
	335
	336	#define thread_wakeup(x) \
	337	thread_wakeup_prim((x), FALSE, THREAD_AWAKENED)
	338	#define thread_wakeup_with_result(x, z) \
	339	thread_wakeup_prim((x), FALSE, (z))
	340	#define thread_wakeup_one(x) \
	341	thread_wakeup_prim((x), TRUE, THREAD_AWAKENED)
	342
0b4e3aa0 A	343	#if !defined(MACH_KERNEL_PRIVATE) && !defined(ABSOLUTETIME_SCALAR_TYPE)
	344
	345	#include <libkern/OSBase.h>
	346
	347	#define thread_set_timer_deadline(a) \
	348	thread_set_timer_deadline(__OSAbsoluteTime(a))
	349
	350	#endif
1c79356b A	351
1c79356b A	352	#endif /* _KERN_SCHED_PRIM_H_ */