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

/*
 * Copyright (c) 2000-2004 Apple Computer, 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 */
	  task 3400;

#include <mach/std_types.defs>
#include <mach/mach_types.defs>
/*
 *	Create a new task with an empty set of IPC rights,
 *	and having an address space constructed from the
 *	target task (or empty, if inherit_memory is FALSE).
 */
routine task_create(
		target_task	: task_t;
		ledgers		: ledger_array_t;
		inherit_memory	: boolean_t;
	out	child_task	: task_t);

/*
 *	Destroy the target task, causing all of its threads
 *	to be destroyed, all of its IPC rights to be deallocated,
 *	and all of its address space to be deallocated.
 */
routine task_terminate(
		target_task	: task_t);

/*
 *	Returns the set of threads belonging to the target task.
 */
routine task_threads(
		target_task	: task_t;
	out	act_list	: thread_act_array_t);

/*
 *	Stash a handful of ports for the target task; child
 *	tasks inherit this stash at task_create time.
 */
routine	mach_ports_register(
		target_task	: task_t;
		init_port_set	: mach_port_array_t =
					^array[] of mach_port_t);

/*
 *	Retrieve the stashed ports for the target task.
 */
routine	mach_ports_lookup(
		target_task	: task_t;
	out	init_port_set	: mach_port_array_t =
					^array[] of mach_port_t);

/*
 *      Returns information about the target task.
 */
routine task_info(
                target_task     : task_name_t;
                flavor          : task_flavor_t;
        out     task_info_out   : task_info_t, CountInOut);

/*
 * Set task information.
 */
routine	task_set_info(
		target_task	: task_t;
		flavor		: task_flavor_t;
		task_info_in	: task_info_t);

/*
 *	Increment the suspend count for the target task.
 *	No threads within a task may run when the suspend
 *	count for that task is non-zero.
 */
routine	task_suspend(
		target_task	: task_t);


/*
 *	Decrement the suspend count for the target task,
 *	if the count is currently non-zero.  If the resulting
 *	suspend	count is zero, then threads within the task
 *	that also have non-zero suspend counts may execute.
 */
routine	task_resume(
		target_task	: task_t);

/*
 *	Returns the current value of the selected special port
 *	associated with the target task.
 */
routine task_get_special_port(
		task		: task_t;
		which_port	: int;
	out	special_port	: mach_port_t);

/*
 *	Set one of the special ports associated with the
 *	target task.
 */
routine task_set_special_port(
		task		: task_t;
		which_port	: int;
		special_port	: mach_port_t);

/*
 *	Create a new thread within the target task, returning
 *	the port representing the first thr_act in that new thread.  The
 *	initial execution state of the thread is undefined.
 */
routine thread_create(
		parent_task	: task_t;
	out	child_act	: thread_act_t);

/*
 *      Create a new thread within the target task, returning
 *      the port representing that new thread.  The new thread 
 *	is not suspended; its initial execution state is given
 *	by flavor and new_state. Returns the port representing 
 *	the new thread.
 */
routine thread_create_running(
                parent_task     : task_t;
                flavor          : thread_state_flavor_t;
                new_state       : thread_state_t;
        out     child_act       : thread_act_t);

/*
 * Set an exception handler for a task on one or more exception types.
 * These handlers are invoked for all threads in the task if there are
 * no thread-specific exception handlers or those handlers returned an
 * error.
 */
routine	task_set_exception_ports(
		task		: task_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 task
 */
routine	task_get_exception_ports(
		task		: task_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	task_swap_exception_ports(
		task		: task_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_handlerss	: exception_handler_array_t, SameCount;
	  out	old_behaviors	: exception_behavior_array_t, SameCount;
	  out	old_flavors	: exception_flavor_array_t, SameCount);

/*
 * Create and destroy lock_set and semaphore synchronizers on a
 * per-task basis (i.e. the task owns them).
 */
routine lock_set_create(
		task		: task_t;
	out	new_lock_set	: lock_set_t;
		n_ulocks	: int;
		policy		: int);

routine lock_set_destroy(
		task		: task_t;
		lock_set	: lock_set_t);

routine semaphore_create(
		task		: task_t;
	out	semaphore	: semaphore_t;
		policy		: int;
		value		: int);

routine semaphore_destroy(
		task		: task_t;
		semaphore	: semaphore_consume_ref_t);

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

routine task_policy_set(
	task			: task_t;
	flavor			: task_policy_flavor_t;
	policy_info		: task_policy_t);

routine task_policy_get(
	task			: task_t;
	flavor			: task_policy_flavor_t;
out	policy_info		: task_policy_t, CountInOut;
inout	get_default		: boolean_t);

/*
 * Task profiling.
 */
routine task_sample(
		task		: task_t;
		reply		: mach_port_make_send_t);

/*
 * JMM - Everything from here down is likely to go away soon
 */
/*
 * OBSOLETE interface.
 */
routine task_policy(
	task			: task_t;
	policy			: policy_t;
	base			: policy_base_t;
	set_limit		: boolean_t;
	change			: boolean_t);


/*
 *	Establish a user-level handler for the specified
 *	system call.
 */
routine task_set_emulation(
		target_port	: task_t;
		routine_entry_pt: vm_address_t;
		routine_number  : int);	

/*
 *	Get user-level handler entry points for all
 *	emulated system calls.
 */
routine task_get_emulation_vector(
		task		: task_t;
	out	vector_start	: int;
	out	emulation_vector: emulation_vector_t);

/*
 *	Establish user-level handlers for the specified
 *	system calls. Non-emulated system calls are specified
 *	with emulation_vector[i] == EML_ROUTINE_NULL.
 */
routine task_set_emulation_vector(
		task		: task_t;
		vector_start	: int;
		emulation_vector: emulation_vector_t);


/*
 *      Establish restart pc for interrupted atomic sequences.
 */
routine task_set_ras_pc(
		target_task     : task_t;
		basepc          : vm_address_t;
		boundspc        : vm_address_t);


skip; /* was kernel_task_create() */

/* 
 * JMM - Want to eliminate processor_set so keep them at the end.
 */

/*
 *	Assign task to processor set.
 */
routine task_assign(
		task		: task_t;
		new_set		: processor_set_t;
		assign_threads	: boolean_t);

/*
 *	Assign task to default set.
 */
routine task_assign_default(
		task		: task_t;
		assign_threads	: boolean_t);

/*
 *	Get current assignment for task.
 */
routine task_get_assignment(
		task		: task_t;
	out	assigned_set	: processor_set_name_t);

/*
 * OBSOLETE interface.
 */
routine task_set_policy(
	task			: task_t;
	pset			: processor_set_t;
	policy			: policy_t;
	base			: policy_base_t;
	limit			: policy_limit_t;
	change			: boolean_t);
Commit	Line	Data
1c79356b	1	/*
91447636	2	* Copyright (c) 2000-2004 Apple Computer, Inc. All rights reserved.
1c79356b	3	*
8f6c56a5	4	* @APPLE_OSREFERENCE_LICENSE_HEADER_START@
1c79356b	5	*
8f6c56a5 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.
	14	*
	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
	20	* EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
	21	* INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
	22	* FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT.
	23	* Please see the License for the specific language governing rights and
8ad349bb	24	* limitations under the License.
8f6c56a5 A	25	*
8f6c56a5 A	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	task 3400;
	70
	71	#include <mach/std_types.defs>
	72	#include <mach/mach_types.defs>
	73	/*
	74	* Create a new task with an empty set of IPC rights,
	75	* and having an address space constructed from the
	76	* target task (or empty, if inherit_memory is FALSE).
	77	*/
	78	routine task_create(
	79	target_task : task_t;
	80	ledgers : ledger_array_t;
	81	inherit_memory : boolean_t;
	82	out child_task : task_t);
	83
	84	/*
	85	* Destroy the target task, causing all of its threads
	86	* to be destroyed, all of its IPC rights to be deallocated,
	87	* and all of its address space to be deallocated.
	88	*/
	89	routine task_terminate(
	90	target_task : task_t);
	91
	92	/*
	93	* Returns the set of threads belonging to the target task.
	94	*/
	95	routine task_threads(
	96	target_task : task_t;
	97	out act_list : thread_act_array_t);
	98
	99	/*
	100	* Stash a handful of ports for the target task; child
	101	* tasks inherit this stash at task_create time.
	102	*/
	103	routine mach_ports_register(
	104	target_task : task_t;
	105	init_port_set : mach_port_array_t =
	106	^array[] of mach_port_t);
	107
	108	/*
	109	* Retrieve the stashed ports for the target task.
	110	*/
	111	routine mach_ports_lookup(
	112	target_task : task_t;
	113	out init_port_set : mach_port_array_t =
	114	^array[] of mach_port_t);
	115
	116	/*
	117	* Returns information about the target task.
	118	*/
	119	routine task_info(
4452a7af	120	target_task : task_name_t;
1c79356b A	121	flavor : task_flavor_t;
	122	out task_info_out : task_info_t, CountInOut);
	123
	124	/*
	125	* Set task information.
	126	*/
	127	routine task_set_info(
	128	target_task : task_t;
	129	flavor : task_flavor_t;
	130	task_info_in : task_info_t);
	131
	132	/*
	133	* Increment the suspend count for the target task.
	134	* No threads within a task may run when the suspend
	135	* count for that task is non-zero.
	136	*/
	137	routine task_suspend(
	138	target_task : task_t);
	139
	140
	141	/*
	142	* Decrement the suspend count for the target task,
	143	* if the count is currently non-zero. If the resulting
	144	* suspend count is zero, then threads within the task
	145	* that also have non-zero suspend counts may execute.
	146	*/
	147	routine task_resume(
	148	target_task : task_t);
	149
	150	/*
	151	* Returns the current value of the selected special port
	152	* associated with the target task.
	153	*/
	154	routine task_get_special_port(
	155	task : task_t;
	156	which_port : int;
	157	out special_port : mach_port_t);
	158
	159	/*
	160	* Set one of the special ports associated with the
	161	* target task.
	162	*/
	163	routine task_set_special_port(
	164	task : task_t;
	165	which_port : int;
	166	special_port : mach_port_t);
	167
	168	/*
	169	* Create a new thread within the target task, returning
	170	* the port representing the first thr_act in that new thread. The
	171	* initial execution state of the thread is undefined.
	172	*/
	173	routine thread_create(
	174	parent_task : task_t;
	175	out child_act : thread_act_t);
	176
	177	/*
	178	* Create a new thread within the target task, returning
	179	* the port representing that new thread. The new thread
	180	* is not suspended; its initial execution state is given
	181	* by flavor and new_state. Returns the port representing
	182	* the new thread.
	183	*/
	184	routine thread_create_running(
185	parent_task : task_t;
186	flavor : thread_state_flavor_t;
187	new_state : thread_state_t;
188	out child_act : thread_act_t);
189
190	/*
191	* Set an exception handler for a task on one or more exception types.
192	* These handlers are invoked for all threads in the task if there are
193	* no thread-specific exception handlers or those handlers returned an
194	* error.
195	*/
196	routine task_set_exception_ports(
197	task : task_t;
198	exception_mask : exception_mask_t;
199	new_port : mach_port_t;
200	behavior : exception_behavior_t;
201	new_flavor : thread_state_flavor_t);
202
203
204	/*
205	* Lookup some of the old exception handlers for a task
206	*/
207	routine task_get_exception_ports(
208	task : task_t;
209	exception_mask : exception_mask_t;
210	out masks : exception_mask_array_t;
211	out old_handlers : exception_handler_array_t, SameCount;
212	out old_behaviors : exception_behavior_array_t, SameCount;
213	out old_flavors : exception_flavor_array_t, SameCount);
214
215
216	/*
217	* Set an exception handler for a thread on one or more exception types.
218	* At the same time, return the previously defined exception handlers for
219	* those types.
220	*/
221	routine task_swap_exception_ports(
222	task : task_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	out masks : exception_mask_array_t;
228	out old_handlerss : exception_handler_array_t, SameCount;
229	out old_behaviors : exception_behavior_array_t, SameCount;
230	out old_flavors : exception_flavor_array_t, SameCount);
231
232	/*
233	* Create and destroy lock_set and semaphore synchronizers on a
234	* per-task basis (i.e. the task owns them).
235	*/
236	routine lock_set_create(
237	task : task_t;
238	out new_lock_set : lock_set_t;
239	n_ulocks : int;
240	policy : int);
241
242	routine lock_set_destroy(
243	task : task_t;
244	lock_set : lock_set_t);
245
246	routine semaphore_create(
247	task : task_t;
248	out semaphore : semaphore_t;
249	policy : int;
250	value : int);
251
252	routine semaphore_destroy(
253	task : task_t;
254	semaphore : semaphore_consume_ref_t);
255
256	/*
257	* Set/get policy information for a task.
258	* (Approved Mac OS X microkernel interface)
259	*/
260
261	routine task_policy_set(
262	task : task_t;
263	flavor : task_policy_flavor_t;
264	policy_info : task_policy_t);
265
266	routine task_policy_get(
267	task : task_t;
268	flavor : task_policy_flavor_t;
269	out policy_info : task_policy_t, CountInOut;
270	inout get_default : boolean_t);
271
272	/*
273	* Task profiling.
274	*/
275	routine task_sample(
276	task : task_t;
277	reply : mach_port_make_send_t);
278
279	/*
280	* JMM - Everything from here down is likely to go away soon
281	*/
282	/*
283	* OBSOLETE interface.
284	*/
285	routine task_policy(
286	task : task_t;
287	policy : policy_t;
288	base : policy_base_t;
289	set_limit : boolean_t;
290	change : boolean_t);
291
292
293	/*
294	* Establish a user-level handler for the specified
295	* system call.
296	*/
297	routine task_set_emulation(
298	target_port : task_t;
299	routine_entry_pt: vm_address_t;
300	routine_number : int);
301
302	/*
303	* Get user-level handler entry points for all
304	* emulated system calls.
305	*/
306	routine task_get_emulation_vector(
307	task : task_t;
308	out vector_start : int;
309	out emulation_vector: emulation_vector_t);
310
311	/*
312	* Establish user-level handlers for the specified
313	* system calls. Non-emulated system calls are specified
314	* with emulation_vector[i] == EML_ROUTINE_NULL.
315	*/
316	routine task_set_emulation_vector(
317	task : task_t;
318	vector_start : int;
319	emulation_vector: emulation_vector_t);
320
321
322	/*
323	* Establish restart pc for interrupted atomic sequences.
324	*/
325	routine task_set_ras_pc(
326	target_task : task_t;
327	basepc : vm_address_t;
328	boundspc : vm_address_t);
329
330
91447636 A	331	skip; /* was kernel_task_create() */
91447636 A	332
1c79356b	333	/*
91447636	334	* JMM - Want to eliminate processor_set so keep them at the end.
1c79356b	335	*/
1c79356b A	336
	337	/*
	338	* Assign task to processor set.
	339	*/
	340	routine task_assign(
	341	task : task_t;
	342	new_set : processor_set_t;
	343	assign_threads : boolean_t);
	344
	345	/*
	346	* Assign task to default set.
	347	*/
	348	routine task_assign_default(
	349	task : task_t;
	350	assign_threads : boolean_t);
	351
	352	/*
	353	* Get current assignment for task.
	354	*/
	355	routine task_get_assignment(
	356	task : task_t;
	357	out assigned_set : processor_set_name_t);
	358
	359	/*
	360	* OBSOLETE interface.
	361	*/
	362	routine task_set_policy(
	363	task : task_t;
	364	pset : processor_set_t;
	365	policy : policy_t;
	366	base : policy_base_t;
	367	limit : policy_limit_t;
	368	change : boolean_t);
	369