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

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

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

extern thread_t	switch_context(
						thread_t	old_thread,
						thread_continue_t continuation,
						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);

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

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

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

#endif /* MACH_KERNEL_PRIVATE */

/*
 ****************** 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	*
	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>
1c79356b	72
9bccf70c A	73	#include <sys/appleapiopts.h>
	74
	75	#ifdef __APPLE_API_PRIVATE
	76
	77	#ifdef MACH_KERNEL_PRIVATE
1c79356b A	78
	79	#include <mach_ldebug.h>
	80	/*
	81	* Exported interface to sched_prim.c.
	82	* A few of these functions are actually defined in
	83	* ipc_sched.c, for historical reasons.
	84	*/
	85
	86	/* Initialize scheduler module */
	87	extern void sched_init(void);
	88
	89	/*
	90	* Set up thread timeout element(s) when thread is created.
	91	*/
	92	extern void thread_timer_setup(
	93	thread_t thread);
	94
	95	extern void thread_timer_terminate(void);
	96
	97	#define thread_bind_locked(thread, processor) \
	98	(thread)->bound_processor = (processor)
	99
	100	/*
9bccf70c	101	* Stop a thread and wait for it to stop running.
1c79356b A	102	*/
	103	extern boolean_t thread_stop(
	104	thread_t thread);
	105
	106	/*
9bccf70c	107	* Wait for a thread to stop running.
1c79356b A	108	*/
	109	extern boolean_t thread_wait(
	110	thread_t thread);
	111
	112	/* Select a thread to run on a particular processor */
	113	extern thread_t thread_select(
	114	processor_t myprocessor);
	115
9bccf70c A	116	extern kern_return_t thread_go_locked(
	117	thread_t thread,
	118	wait_result_t result);
1c79356b A	119
	120	/* Stop old thread and run new thread */
	121	extern boolean_t thread_invoke(
9bccf70c A	122	thread_t old_thread,
	123	thread_t new_thread,
	124	int reason,
	125	thread_continue_t continuation);
1c79356b A	126
	127	/* Called when current thread is given new stack */
	128	extern void thread_continue(
9bccf70c	129	thread_t old_thread);
1c79356b A	130
	131	/* Switch directly to a particular thread */
	132	extern int thread_run(
9bccf70c A	133	thread_t old_thread,
	134	thread_continue_t continuation,
	135	thread_t new_thread);
1c79356b A	136
	137	/* Dispatch a thread not on a run queue */
	138	extern void thread_dispatch(
9bccf70c	139	thread_t thread);
1c79356b A	140
	141	/* Invoke continuation */
	142	extern void call_continuation(
9bccf70c A	143	thread_continue_t continuation);
	144
	145	/* Set the current scheduled priority */
	146	extern void set_sched_pri(
	147	thread_t thread,
	148	int priority);
1c79356b	149
9bccf70c A	150	/* Set base priority of the specified thread */
	151	extern void set_priority(
	152	thread_t thread,
	153	int priority);
	154
	155	/* Reset scheduled priority of thread */
1c79356b	156	extern void compute_priority(
9bccf70c A	157	thread_t thread,
9bccf70c A	158	boolean_t override_depress);
1c79356b	159
9bccf70c	160	/* Adjust scheduled priority of thread during execution */
1c79356b	161	extern void compute_my_priority(
9bccf70c	162	thread_t thread);
1c79356b A	163
1c79356b A	164	/* Periodic scheduler activity */
0b4e3aa0	165	extern void sched_tick_init(void);
1c79356b	166
9bccf70c A	167	/*
9bccf70c A	168	* Update thread to the current scheduler tick.
1c79356b A	169	*/
1c79356b A	170	extern void update_priority(
9bccf70c	171	thread_t thread);
1c79356b A	172
	173	/* Idle thread loop */
	174	extern void idle_thread(void);
	175
1c79356b A	176	/*
	177	* Machine-dependent code must define these functions.
	178	*/
	179
	180	/* Start thread running */
	181	extern void thread_bootstrap_return(void);
	182
	183	/* Return from exception */
	184	extern void thread_exception_return(void);
	185
	186	/* Continuation return from syscall */
	187	extern void thread_syscall_return(
	188	kern_return_t ret);
	189
	190	extern thread_t switch_context(
	191	thread_t old_thread,
9bccf70c	192	thread_continue_t continuation,
1c79356b A	193	thread_t new_thread);
	194
	195	/* Attach stack to thread */
	196	extern void machine_kernel_stack_init(
	197	thread_t thread,
	198	void (*start_pos)(thread_t));
	199
	200	extern void load_context(
	201	thread_t thread);
	202
	203	extern thread_act_t switch_act(
	204	thread_act_t act);
	205
	206	extern void machine_switch_act(
	207	thread_t thread,
	208	thread_act_t old,
	209	thread_act_t new,
	210	int cpu);
	211
	212	/*
	213	* These functions are either defined in kern/thread.c
	214	* or are defined directly by machine-dependent code.
	215	*/
	216
	217	/* Allocate an activation stack */
	218	extern vm_offset_t stack_alloc(thread_t thread, void (*start_pos)(thread_t));
	219
	220	/* Free an activation stack */
	221	extern void stack_free(thread_t thread);
	222
	223	/* Collect excess kernel stacks */
	224	extern void stack_collect(void);
	225
9bccf70c A	226	/* Block current thread, indicating reason */
	227	extern wait_result_t thread_block_reason(
	228	thread_continue_t continuation,
	229	ast_t reason);
1c79356b	230
9bccf70c	231	/* Dispatch a thread for execution */
1c79356b	232	extern void thread_setrun(
9bccf70c A	233	thread_t thread,
9bccf70c A	234	boolean_t tail);
1c79356b A	235
	236	#define HEAD_Q 0 /* FALSE */
	237	#define TAIL_Q 1 /* TRUE */
	238
	239	/* Bind thread to a particular processor */
	240	extern void thread_bind(
9bccf70c A	241	thread_t thread,
9bccf70c A	242	processor_t processor);
1c79356b	243
9bccf70c A	244	/* Set the maximum interrupt level for the thread */
	245	__private_extern__ wait_interrupt_t thread_interrupt_level(
	246	wait_interrupt_t interruptible);
	247
	248	__private_extern__ wait_result_t thread_mark_wait_locked(
	249	thread_t thread,
	250	wait_interrupt_t interruptible);
	251
	252	/* Sleep, unlocking and then relocking a usimple_lock in the process */
	253	__private_extern__ wait_result_t thread_sleep_fast_usimple_lock(
	254	event_t event,
	255	simple_lock_t lock,
	256	wait_interrupt_t interruptible);
	257
	258	/* Wake up locked thread directly, passing result */
	259	__private_extern__ kern_return_t clear_wait_internal(
	260	thread_t thread,
	261	wait_result_t result);
1c79356b A	262
	263	#endif /* MACH_KERNEL_PRIVATE */
	264
	265	/*
	266	**************** Only exported until BSD stops using ******************
	267	*/
	268
	269	/*
9bccf70c	270	* Cancel a stop and unblock the thread if already stopped.
1c79356b A	271	*/
1c79356b A	272	extern void thread_unstop(
9bccf70c	273	thread_t thread);
1c79356b A	274
1c79356b A	275	/* Wake up thread directly, passing result */
9bccf70c A	276	extern kern_return_t clear_wait(
	277	thread_t thread,
	278	wait_result_t result);
1c79356b	279
9bccf70c	280	#endif /* __APPLE_API_PRIVATE */
1c79356b A	281
	282	/*
	283	* ******************* PUBLIC APIs **********************************
	284	*/
	285
	286	/* Set timer for current thread */
	287	extern void thread_set_timer(
0b4e3aa0 A	288	uint32_t interval,
0b4e3aa0 A	289	uint32_t scale_factor);
1c79356b A	290
1c79356b A	291	extern void thread_set_timer_deadline(
0b4e3aa0	292	uint64_t deadline);
1c79356b A	293
	294	extern void thread_cancel_timer(void);
	295
1c79356b	296	/* Declare thread will wait on a particular event */
9bccf70c A	297	extern wait_result_t assert_wait(
	298	event_t event,
	299	wait_interrupt_t interruptflag);
1c79356b A	300
1c79356b A	301	/* Assert that the thread intends to wait for a timeout */
9bccf70c A	302	extern wait_result_t assert_wait_timeout(
	303	natural_t msecs,
	304	wait_interrupt_t interruptflags);
	305
	306	/* Sleep, unlocking and then relocking a usimple_lock in the process */
	307	extern wait_result_t thread_sleep_usimple_lock(
	308	event_t event,
	309	usimple_lock_t lock,
	310	wait_interrupt_t interruptible);
	311
	312	/* Sleep, unlocking and then relocking a mutex in the process */
	313	extern wait_result_t thread_sleep_mutex(
	314	event_t event,
	315	mutex_t *mutex,
	316	wait_interrupt_t interruptible);
	317
	318	/* Sleep with a deadline, unlocking and then relocking a mutex in the process */
	319	extern wait_result_t thread_sleep_mutex_deadline(
	320	event_t event,
	321	mutex_t *mutex,
	322	uint64_t deadline,
	323	wait_interrupt_t interruptible);
	324
	325	/* Sleep, unlocking and then relocking a write lock in the process */
	326	extern wait_result_t thread_sleep_lock_write(
	327	event_t event,
	328	lock_t *lock,
	329	wait_interrupt_t interruptible);
	330
	331	/* Sleep, hinting that a thread funnel may be involved in the process */
	332	extern wait_result_t thread_sleep_funnel(
	333	event_t event,
	334	wait_interrupt_t interruptible);
1c79356b A	335
1c79356b A	336	/* Wake up thread (or threads) waiting on a particular event */
9bccf70c A	337	extern kern_return_t thread_wakeup_prim(
	338	event_t event,
	339	boolean_t one_thread,
	340	wait_result_t result);
	341
	342	#ifdef __APPLE_API_UNSTABLE
1c79356b A	343
1c79356b A	344	/* Block current thread (Block reason) */
9bccf70c A	345	extern wait_result_t thread_block(
9bccf70c A	346	thread_continue_t continuation);
1c79356b	347
9bccf70c	348	#endif /* __APPLE_API_UNSTABLE */
1c79356b A	349
	350	/*
	351	* Routines defined as macros
	352	*/
	353
	354	#define thread_wakeup(x) \
	355	thread_wakeup_prim((x), FALSE, THREAD_AWAKENED)
	356	#define thread_wakeup_with_result(x, z) \
	357	thread_wakeup_prim((x), FALSE, (z))
	358	#define thread_wakeup_one(x) \
	359	thread_wakeup_prim((x), TRUE, THREAD_AWAKENED)
	360
0b4e3aa0 A	361	#if !defined(MACH_KERNEL_PRIVATE) && !defined(ABSOLUTETIME_SCALAR_TYPE)
	362
	363	#include <libkern/OSBase.h>
	364
	365	#define thread_set_timer_deadline(a) \
	366	thread_set_timer_deadline(__OSAbsoluteTime(a))
	367
	368	#endif
1c79356b A	369
1c79356b A	370	#endif /* _KERN_SCHED_PRIM_H_ */