[apple/xnu.git] / osfmk / mach / thread_act.defs

/*
 * Copyright (c) 2000-2007 Apple Inc. All rights reserved.
 *
 * @APPLE_OSREFERENCE_LICENSE_HEADER_START@
 * 
 * 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. The rights granted to you under the License
 * may not be used to create, or enable the creation or redistribution of,
 * unlawful or unlicensed copies of an Apple operating system, or to
 * circumvent, violate, or enable the circumvention or violation of, any
 * terms of an Apple operating system software license agreement.
 * 
 * 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_OSREFERENCE_LICENSE_HEADER_END@
 */
/*
 * @OSF_FREE_COPYRIGHT@
 */
/* 
 * Mach Operating System
 * Copyright (c) 1991,1990,1989 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:	mach/mach_port.defs
 *	Author:	Rich Draves
 *
 *	Exported kernel calls.
 */

subsystem
#if	KERNEL_SERVER
	  KernelServer
#endif	/* KERNEL_SERVER */
	  thread_act 3600;

#include <mach/std_types.defs>
#include <mach/mach_types.defs>

/*
 *	Destroy the target thread.
 *
 *	JMM - For legacy reasons this consumes a reference to the
 *	target thread.  This will have to change in the future because
 *	we want the interfaces to be able to be defined in more standard
 *	IDLs and transports, and most of them do not support the notion
 *	of reference ownership transfers (just sharing).
 */
routine thread_terminate(
		target_act	: thread_act_consume_ref_t); 


/*
 *	Return the selected state information for the target
 *	thr_act.  If the thr_act is currently executing, the results
 *	may be stale.  [Flavor THREAD_STATE_FLAVOR_LIST provides a
 *	list of valid flavors for the target thread.]
 */
routine act_get_state(
		target_act	: thread_act_t;
		flavor		: int;
	out	old_state	: thread_state_t, CountInOut);

/*
 *	Set the selected state information for the target thread.
 *	If the thread is currently executing, the state change
 *	may be ill-defined.
 */
routine
#ifdef KERNEL_SERVER
act_set_state_from_user(
#else
act_set_state(
#endif
		target_act	: thread_act_t;
		flavor		: int;
		new_state	: thread_state_t);

/*
 * Backward compatible old-style thread routines.
 * These have different semantics than the new activation versions.
 *
 *	Return the selected state information for the target
 *	thread.  If the thread is currently executing, the results
 *	may be stale.  [Flavor THREAD_STATE_FLAVOR_LIST provides a
 *	list of valid flavors for the target thr_act.]
 */
routine thread_get_state(
		target_act	: thread_act_t;
		flavor		: thread_state_flavor_t;
	out	old_state	: thread_state_t, CountInOut);

/*
 *	Set the selected state information for the target thread.
 *	If the thread is currently executing, the state change
 *	may be ill-defined.
 */
routine
#ifdef KERNEL_SERVER
thread_set_state_from_user(
#else
thread_set_state(
#endif
		target_act	: thread_act_t;
		flavor		: thread_state_flavor_t;
		new_state	: thread_state_t);

/*
 *	Increment the suspend count for the target thread.
 *	Once this call has completed, the thread will not
 *	execute any further user or meta- instructions.
 *	Once suspended, a thread may not execute again until
 *	its suspend count is zero, and the suspend count
 *	for its task is also zero.
 */
routine	thread_suspend(
		target_act	: thread_act_t);

/*
 *	Decrement the suspend count for the target thread,
 *	if that count is not already zero.
 */
routine	thread_resume(
		target_act	: thread_act_t);

/*
 *	Cause any user or meta- instructions currently being
 *	executed by the target thread to be aborted.  [Meta-
 *	instructions consist of the basic traps for IPC
 *	(e.g., msg_send, msg_receive) and self-identification
 *	(e.g., task_self, thread_self, thread_reply).  Calls
 *	described by MiG interfaces are not meta-instructions
 *	themselves.]
 */
routine thread_abort(
		target_act	: thread_act_t);

/*
 *	Cause any user or meta- instructions currently being
 *	executed by the target thread to be aborted so that
 *	they are transparently restartable.  This call fails
 *	if the abort would result in a non-restartable condition.
 *	Retry is the caller's responsibility.  [Meta-
 *	instructions consist of the basic traps for IPC
 *	(e.g., msg_send, msg_receive) and self-identification
 *	(e.g., task_self, thread_self, thread_reply).  Calls
 *	described by MiG interfaces are not meta-instructions
 *	themselves.]
 */
routine thread_abort_safely(
		target_act	: thread_act_t);


routine thread_depress_abort(
		thread		: thread_act_t);


/*
 *	Returns the current value of the selected special port
 *	associated with the target thread.
 */
routine thread_get_special_port(
		thr_act		: thread_act_t;
		which_port	: int;
	out	special_port	: mach_port_t);

/*
 *	Set one of the special ports associated with the
 *	target thread.
 */
routine thread_set_special_port(
		thr_act		: thread_act_t;
		which_port	: int;
		special_port	: mach_port_t);

/*
 *      Returns information about the target thread.
 */
routine thread_info(
                target_act      : thread_act_t;
                flavor          : thread_flavor_t;
        out     thread_info_out : thread_info_t, CountInOut);

/*
 * Set an exception handler for a thread on one or more exception types
 */
routine		thread_set_exception_ports(
			thread		: thread_act_t;
			exception_mask	: exception_mask_t;
			new_port	: mach_port_t;
			behavior	: exception_behavior_t;
			new_flavor	: thread_state_flavor_t);

/*
 * Lookup some of the old exception handlers for a thread
 */
routine		thread_get_exception_ports(
			thread		: thread_act_t;
			exception_mask	: exception_mask_t;
		  out	masks		: exception_mask_array_t;
		  out	old_handlers	: exception_handler_array_t, SameCount;
		  out	old_behaviors	: exception_behavior_array_t, SameCount;
		  out	old_flavors	: exception_flavor_array_t, SameCount);

/*
 * Set an exception handler for a thread on one or more exception types.
 * At the same time, return the previously defined exception handlers for
 * those types.
 */
routine		thread_swap_exception_ports(
			thread		: thread_act_t;
			exception_mask	: exception_mask_t;
			new_port	: mach_port_t;
			behavior	: exception_behavior_t;
			new_flavor	: thread_state_flavor_t;
		  out	masks		: exception_mask_array_t;
		  out	old_handlers	: exception_handler_array_t, SameCount;
		  out	old_behaviors	: exception_behavior_array_t, SameCount;
		  out	old_flavors	: exception_flavor_array_t, SameCount);

/*
 * OBSOLETE interface.
 */
routine thread_policy(
	thr_act			: thread_act_t;
	policy			: policy_t;
	base			: policy_base_t;
	set_limit		: boolean_t);

/*
 * Set/get policy information for a thread.
 * (Approved Mac OS X microkernel interface)
 */

routine thread_policy_set(
	thread			: thread_act_t;
	flavor			: thread_policy_flavor_t;
	policy_info		: thread_policy_t);

routine thread_policy_get(
	thread			: thread_act_t;
	flavor			: thread_policy_flavor_t;
out	policy_info		: thread_policy_t, CountInOut;
inout	get_default		: boolean_t);

/*
 *	Removed from the kernel.
 */
#if KERNEL_SERVER
skip;
#else
routine thread_sample(
		thread		: thread_act_t;
		reply		: mach_port_make_send_t);
#endif

/*
 *	ETAP has been removed from the kernel.
 */
#if KERNEL_SERVER
skip;
#else
routine	etap_trace_thread(
		target_act	: thread_act_t;
		trace_status	: boolean_t);
#endif

/*
 *	Assign thread to processor set.
 */
routine	thread_assign(
		thread		: thread_act_t;
		new_set		: processor_set_t);

/*
 *	Assign thread to default set.
 */
routine thread_assign_default(
		thread		: thread_act_t);

/*
 *	Get current assignment for thread.
 */
routine thread_get_assignment(
		thread		: thread_act_t;
	out	assigned_set	: processor_set_name_t);


/*
 * OBSOLETE interface.
 */
routine thread_set_policy(
	thr_act			: thread_act_t;
	pset			: processor_set_t;
	policy			: policy_t;
	base			: policy_base_t;
	limit			: policy_limit_t);

/* vim: set ft=c : */
Commit	Line	Data
1c79356b	1	/*
2d21ac55	2	* Copyright (c) 2000-2007 Apple Inc. All rights reserved.
1c79356b	3	*
2d21ac55	4	* @APPLE_OSREFERENCE_LICENSE_HEADER_START@
8f6c56a5	5	*
2d21ac55 A	6	* This file contains Original Code and/or Modifications of Original Code
	7	* as defined in and that are subject to the Apple Public Source License
	8	* Version 2.0 (the 'License'). You may not use this file except in
	9	* compliance with the License. The rights granted to you under the License
	10	* may not be used to create, or enable the creation or redistribution of,
	11	* unlawful or unlicensed copies of an Apple operating system, or to
	12	* circumvent, violate, or enable the circumvention or violation of, any
	13	* terms of an Apple operating system software license agreement.
8f6c56a5	14	*
2d21ac55 A	15	* Please obtain a copy of the License at
	16	* http://www.opensource.apple.com/apsl/ and read it before using this file.
	17	*
	18	* The Original Code and all software distributed under the License are
	19	* distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER
8f6c56a5 A	20	* EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
8f6c56a5 A	21	* INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
2d21ac55 A	22	* FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT.
	23	* Please see the License for the specific language governing rights and
	24	* limitations under the License.
8f6c56a5	25	*
2d21ac55	26	* @APPLE_OSREFERENCE_LICENSE_HEADER_END@
1c79356b A	27	*/
	28	/*
	29	* @OSF_FREE_COPYRIGHT@
	30	*/
	31	/*
	32	* Mach Operating System
	33	* Copyright (c) 1991,1990,1989 Carnegie Mellon University
	34	* All Rights Reserved.
	35	*
	36	* Permission to use, copy, modify and distribute this software and its
	37	* documentation is hereby granted, provided that both the copyright
	38	* notice and this permission notice appear in all copies of the
	39	* software, derivative works or modified versions, and any portions
	40	* thereof, and that both notices appear in supporting documentation.
	41	*
	42	* CARNEGIE MELLON ALLOWS FREE USE OF THIS SOFTWARE IN ITS "AS IS"
	43	* CONDITION. CARNEGIE MELLON DISCLAIMS ANY LIABILITY OF ANY KIND FOR
	44	* ANY DAMAGES WHATSOEVER RESULTING FROM THE USE OF THIS SOFTWARE.
	45	*
	46	* Carnegie Mellon requests users of this software to return to
	47	*
	48	* Software Distribution Coordinator or Software.Distribution@CS.CMU.EDU
	49	* School of Computer Science
	50	* Carnegie Mellon University
	51	* Pittsburgh PA 15213-3890
	52	*
	53	* any improvements or extensions that they make and grant Carnegie Mellon
	54	* the rights to redistribute these changes.
	55	*/
	56	/*
	57	*/
	58	/*
	59	* File: mach/mach_port.defs
	60	* Author: Rich Draves
	61	*
	62	* Exported kernel calls.
	63	*/
	64
	65	subsystem
	66	#if KERNEL_SERVER
	67	KernelServer
55e303ae	68	#endif /* KERNEL_SERVER */
1c79356b A	69	thread_act 3600;
	70
	71	#include <mach/std_types.defs>
	72	#include <mach/mach_types.defs>
	73
	74	/*
	75	* Destroy the target thread.
	76	*
	77	* JMM - For legacy reasons this consumes a reference to the
	78	* target thread. This will have to change in the future because
	79	* we want the interfaces to be able to be defined in more standard
	80	* IDLs and transports, and most of them do not support the notion
	81	* of reference ownership transfers (just sharing).
	82	*/
	83	routine thread_terminate(
	84	target_act : thread_act_consume_ref_t);
	85
	86
	87	/*
	88	* Return the selected state information for the target
	89	* thr_act. If the thr_act is currently executing, the results
	90	* may be stale. [Flavor THREAD_STATE_FLAVOR_LIST provides a
	91	* list of valid flavors for the target thread.]
	92	*/
	93	routine act_get_state(
	94	target_act : thread_act_t;
	95	flavor : int;
	96	out old_state : thread_state_t, CountInOut);
	97
	98	/*
	99	* Set the selected state information for the target thread.
	100	* If the thread is currently executing, the state change
	101	* may be ill-defined.
	102	*/
6d2010ae A	103	routine
	104	#ifdef KERNEL_SERVER
	105	act_set_state_from_user(
	106	#else
	107	act_set_state(
	108	#endif
1c79356b A	109	target_act : thread_act_t;
	110	flavor : int;
	111	new_state : thread_state_t);
	112
	113	/*
	114	* Backward compatible old-style thread routines.
	115	* These have different semantics than the new activation versions.
	116	*
	117	* Return the selected state information for the target
	118	* thread. If the thread is currently executing, the results
	119	* may be stale. [Flavor THREAD_STATE_FLAVOR_LIST provides a
	120	* list of valid flavors for the target thr_act.]
	121	*/
	122	routine thread_get_state(
	123	target_act : thread_act_t;
	124	flavor : thread_state_flavor_t;
	125	out old_state : thread_state_t, CountInOut);
	126
	127	/*
	128	* Set the selected state information for the target thread.
	129	* If the thread is currently executing, the state change
	130	* may be ill-defined.
	131	*/
6d2010ae A	132	routine
	133	#ifdef KERNEL_SERVER
	134	thread_set_state_from_user(
	135	#else
	136	thread_set_state(
	137	#endif
1c79356b A	138	target_act : thread_act_t;
	139	flavor : thread_state_flavor_t;
	140	new_state : thread_state_t);
	141
	142	/*
	143	* Increment the suspend count for the target thread.
	144	* Once this call has completed, the thread will not
	145	* execute any further user or meta- instructions.
	146	* Once suspended, a thread may not execute again until
	147	* its suspend count is zero, and the suspend count
	148	* for its task is also zero.
	149	*/
	150	routine thread_suspend(
	151	target_act : thread_act_t);
	152
	153	/*
	154	* Decrement the suspend count for the target thread,
	155	* if that count is not already zero.
	156	*/
	157	routine thread_resume(
	158	target_act : thread_act_t);
	159
	160	/*
	161	* Cause any user or meta- instructions currently being
	162	* executed by the target thread to be aborted. [Meta-
	163	* instructions consist of the basic traps for IPC
	164	* (e.g., msg_send, msg_receive) and self-identification
	165	* (e.g., task_self, thread_self, thread_reply). Calls
	166	* described by MiG interfaces are not meta-instructions
	167	* themselves.]
	168	*/
	169	routine thread_abort(
	170	target_act : thread_act_t);
	171
	172	/*
	173	* Cause any user or meta- instructions currently being
	174	* executed by the target thread to be aborted so that
	175	* they are transparently restartable. This call fails
	176	* if the abort would result in a non-restartable condition.
	177	* Retry is the caller's responsibility. [Meta-
	178	* instructions consist of the basic traps for IPC
	179	* (e.g., msg_send, msg_receive) and self-identification
	180	* (e.g., task_self, thread_self, thread_reply). Calls
	181	* described by MiG interfaces are not meta-instructions
	182	* themselves.]
	183	*/
	184	routine thread_abort_safely(
	185	target_act : thread_act_t);
	186
	187
	188	routine thread_depress_abort(
	189	thread : thread_act_t);
	190
	191
	192	/*
	193	* Returns the current value of the selected special port
	194	* associated with the target thread.
	195	*/
	196	routine thread_get_special_port(
	197	thr_act : thread_act_t;
	198	which_port : int;
	199	out special_port : mach_port_t);
	200
	201	/*
202	* Set one of the special ports associated with the
203	* target thread.
204	*/
205	routine thread_set_special_port(
206	thr_act : thread_act_t;
207	which_port : int;
208	special_port : mach_port_t);
209
210	/*
211	* Returns information about the target thread.
212	*/
213	routine thread_info(
214	target_act : thread_act_t;
215	flavor : thread_flavor_t;
216	out thread_info_out : thread_info_t, CountInOut);
217
218	/*
219	* Set an exception handler for a thread on one or more exception types
220	*/
221	routine thread_set_exception_ports(
222	thread : thread_act_t;
223	exception_mask : exception_mask_t;
224	new_port : mach_port_t;
225	behavior : exception_behavior_t;
226	new_flavor : thread_state_flavor_t);
227
228	/*
229	* Lookup some of the old exception handlers for a thread
230	*/
231	routine thread_get_exception_ports(
232	thread : thread_act_t;
233	exception_mask : exception_mask_t;
234	out masks : exception_mask_array_t;
235	out old_handlers : exception_handler_array_t, SameCount;
236	out old_behaviors : exception_behavior_array_t, SameCount;
237	out old_flavors : exception_flavor_array_t, SameCount);
238
239	/*
240	* Set an exception handler for a thread on one or more exception types.
241	* At the same time, return the previously defined exception handlers for
242	* those types.
243	*/
244	routine thread_swap_exception_ports(
245	thread : thread_act_t;
246	exception_mask : exception_mask_t;
247	new_port : mach_port_t;
248	behavior : exception_behavior_t;
249	new_flavor : thread_state_flavor_t;
250	out masks : exception_mask_array_t;
251	out old_handlers : exception_handler_array_t, SameCount;
252	out old_behaviors : exception_behavior_array_t, SameCount;
253	out old_flavors : exception_flavor_array_t, SameCount);
254
255	/*
256	* OBSOLETE interface.
257	*/
258	routine thread_policy(
259	thr_act : thread_act_t;
260	policy : policy_t;
261	base : policy_base_t;
262	set_limit : boolean_t);
263
264	/*
265	* Set/get policy information for a thread.
266	* (Approved Mac OS X microkernel interface)
267	*/
268
269	routine thread_policy_set(
270	thread : thread_act_t;
271	flavor : thread_policy_flavor_t;
272	policy_info : thread_policy_t);
273
274	routine thread_policy_get(
275	thread : thread_act_t;
276	flavor : thread_policy_flavor_t;
277	out policy_info : thread_policy_t, CountInOut;
278	inout get_default : boolean_t);
279
280	/*
2d21ac55	281	* Removed from the kernel.
1c79356b	282	*/
2d21ac55 A	283	#if KERNEL_SERVER
	284	skip;
	285	#else
1c79356b A	286	routine thread_sample(
	287	thread : thread_act_t;
	288	reply : mach_port_make_send_t);
2d21ac55	289	#endif
1c79356b A	290
1c79356b A	291	/*
91447636	292	* ETAP has been removed from the kernel.
1c79356b	293	*/
91447636 A	294	#if KERNEL_SERVER
	295	skip;
	296	#else
1c79356b A	297	routine etap_trace_thread(
	298	target_act : thread_act_t;
	299	trace_status : boolean_t);
91447636	300	#endif
1c79356b A	301
	302	/*
	303	* Assign thread to processor set.
	304	*/
	305	routine thread_assign(
	306	thread : thread_act_t;
	307	new_set : processor_set_t);
	308
	309	/*
	310	* Assign thread to default set.
	311	*/
	312	routine thread_assign_default(
	313	thread : thread_act_t);
	314
	315	/*
	316	* Get current assignment for thread.
	317	*/
	318	routine thread_get_assignment(
	319	thread : thread_act_t;
	320	out assigned_set : processor_set_name_t);
	321
	322
	323	/*
	324	* OBSOLETE interface.
	325	*/
	326	routine thread_set_policy(
	327	thr_act : thread_act_t;
	328	pset : processor_set_t;
	329	policy : policy_t;
	330	base : policy_base_t;
	331	limit : policy_limit_t);
2d21ac55 A	332
2d21ac55 A	333	/* vim: set ft=c : */