1/*
2 * Copyright (c) 2000-2007 Apple Inc. All rights reserved.
3 *
4 * @APPLE_OSREFERENCE_LICENSE_HEADER_START@
5 *
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
24 * limitations under the License.
25 *
26 * @APPLE_OSREFERENCE_LICENSE_HEADER_END@
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
65subsystem
66#if	KERNEL_SERVER
67	  KernelServer
68#endif	/* KERNEL_SERVER */
69	  task 3400;
70
71#include <mach/std_types.defs>
72#include <mach/mach_types.defs>
73#include <mach_debug/mach_debug_types.defs>
74
75/*
76 *	Create a new task with an empty set of IPC rights,
77 *	and having an address space constructed from the
78 *	target task (or empty, if inherit_memory is FALSE).
79 */
80routine task_create(
81		target_task	: task_t;
82		ledgers		: ledger_array_t;
83		inherit_memory	: boolean_t;
84	out	child_task	: task_t);
85
86/*
87 *	Destroy the target task, causing all of its threads
88 *	to be destroyed, all of its IPC rights to be deallocated,
89 *	and all of its address space to be deallocated.
90 */
91routine task_terminate(
92		target_task	: task_t);
93
94/*
95 *	Returns the set of threads belonging to the target task.
96 */
97routine task_threads(
98		target_task	: task_t;
99	out	act_list	: thread_act_array_t);
100
101/*
102 *	Stash a handful of ports for the target task; child
103 *	tasks inherit this stash at task_create time.
104 */
105routine	mach_ports_register(
106		target_task	: task_t;
107		init_port_set	: mach_port_array_t =
108					^array[] of mach_port_t);
109
110/*
111 *	Retrieve the stashed ports for the target task.
112 */
113routine	mach_ports_lookup(
114		target_task	: task_t;
115	out	init_port_set	: mach_port_array_t =
116					^array[] of mach_port_t);
117
118/*
119 *      Returns information about the target task.
120 */
121routine task_info(
122                target_task     : task_name_t;
123                flavor          : task_flavor_t;
124        out     task_info_out   : task_info_t, CountInOut);
125
126/*
127 * Set task information.
128 */
129routine	task_set_info(
130		target_task	: task_t;
131		flavor		: task_flavor_t;
132		task_info_in	: task_info_t);
133
134/*
135 *	Increment the suspend count for the target task.
136 *	No threads within a task may run when the suspend
137 *	count for that task is non-zero.
138 */
139routine	task_suspend(
140		target_task	: task_t);
141
142
143/*
144 *	Decrement the suspend count for the target task,
145 *	if the count is currently non-zero.  If the resulting
146 *	suspend	count is zero, then threads within the task
147 *	that also have non-zero suspend counts may execute.
148 */
149routine	task_resume(
150		target_task	: task_t);
151
152/*
153 *	Returns the current value of the selected special port
154 *	associated with the target task.
155 */
156routine task_get_special_port(
157		task		: task_t;
158		which_port	: int;
159	out	special_port	: mach_port_t);
160
161/*
162 *	Set one of the special ports associated with the
163 *	target task.
164 */
165routine task_set_special_port(
166		task		: task_t;
167		which_port	: int;
168		special_port	: mach_port_t);
169
170/*
171 *	Create a new thread within the target task, returning
172 *	the port representing the first thr_act in that new thread.  The
173 *	initial execution state of the thread is undefined.
174 */
175routine
176#ifdef KERNEL_SERVER
177thread_create_from_user(
178#else
179thread_create(
180#endif
181		parent_task	: task_t;
182	out	child_act	: thread_act_t);
183
184/*
185 *      Create a new thread within the target task, returning
186 *      the port representing that new thread.  The new thread
187 *	is not suspended; its initial execution state is given
188 *	by flavor and new_state. Returns the port representing
189 *	the new thread.
190 */
191routine
192#ifdef KERNEL_SERVER
193thread_create_running_from_user(
194#else
195thread_create_running(
196#endif
197                parent_task     : task_t;
198                flavor          : thread_state_flavor_t;
199                new_state       : thread_state_t;
200        out     child_act       : thread_act_t);
201
202/*
203 * Set an exception handler for a task on one or more exception types.
204 * These handlers are invoked for all threads in the task if there are
205 * no thread-specific exception handlers or those handlers returned an
206 * error.
207 */
208routine	task_set_exception_ports(
209		task		: task_t;
210		exception_mask	: exception_mask_t;
211		new_port	: mach_port_t;
212		behavior	: exception_behavior_t;
213		new_flavor	: thread_state_flavor_t);
214
215
216/*
217 * Lookup some of the old exception handlers for a task
218 */
219routine	task_get_exception_ports(
220		task		: task_t;
221		exception_mask	: exception_mask_t;
222	  out	masks		: exception_mask_array_t;
223	  out	old_handlers	: exception_handler_array_t, SameCount;
224	  out	old_behaviors	: exception_behavior_array_t, SameCount;
225	  out	old_flavors	: exception_flavor_array_t, SameCount);
226
227
228/*
229 * Set an exception handler for a thread on one or more exception types.
230 * At the same time, return the previously defined exception handlers for
231 * those types.
232 */
233routine	task_swap_exception_ports(
234		task		: task_t;
235		exception_mask	: exception_mask_t;
236		new_port	: mach_port_t;
237		behavior	: exception_behavior_t;
238		new_flavor	: thread_state_flavor_t;
239	  out	masks		: exception_mask_array_t;
240	  out	old_handlerss	: exception_handler_array_t, SameCount;
241	  out	old_behaviors	: exception_behavior_array_t, SameCount;
242	  out	old_flavors	: exception_flavor_array_t, SameCount);
243
244/*
245 * OBSOLETE interface.
246 */
247routine lock_set_create(
248		task		: task_t;
249	out	new_lock_set	: lock_set_t;
250		n_ulocks	: int;
251		policy		: int);
252
253/*
254 * OBSOLETE interface.
255 */
256routine lock_set_destroy(
257		task		: task_t;
258		lock_set	: lock_set_t);
259
260/*
261 * Create and destroy semaphore synchronizers on a
262 * per-task basis (i.e. the task owns them).
263 */
264
265routine semaphore_create(
266		task		: task_t;
267	out	semaphore	: semaphore_t;
268		policy		: int;
269		value		: int);
270
271routine semaphore_destroy(
272		task		: task_t;
273		semaphore	: semaphore_consume_ref_t);
274
275/*
276 * Set/get policy information for a task.
277 * (Approved Mac OS X microkernel interface)
278 */
279
280routine task_policy_set(
281	task			: task_t;
282	flavor			: task_policy_flavor_t;
283	policy_info		: task_policy_t);
284
285routine task_policy_get(
286	task			: task_t;
287	flavor			: task_policy_flavor_t;
288out	policy_info		: task_policy_t, CountInOut;
289inout	get_default		: boolean_t);
290
291/*
292 *	Removed from the kernel.
293 */
294#if KERNEL_SERVER
295skip;
296#else
297routine task_sample(
298		task		: task_t;
299		reply		: mach_port_make_send_t);
300#endif
301
302/*
303 * JMM - Everything from here down is likely to go away soon
304 */
305/*
306 * OBSOLETE interface.
307 */
308routine task_policy(
309	task			: task_t;
310	policy			: policy_t;
311	base			: policy_base_t;
312	set_limit		: boolean_t;
313	change			: boolean_t);
314
315
316/*
317 *	Establish a user-level handler for the specified
318 *	system call.
319 */
320routine task_set_emulation(
321		target_port	: task_t;
322		routine_entry_pt: vm_address_t;
323		routine_number  : int);
324
325/*
326 *	Get user-level handler entry points for all
327 *	emulated system calls.
328 */
329routine task_get_emulation_vector(
330		task		: task_t;
331	out	vector_start	: int;
332	out	emulation_vector: emulation_vector_t);
333
334/*
335 *	Establish user-level handlers for the specified
336 *	system calls. Non-emulated system calls are specified
337 *	with emulation_vector[i] == EML_ROUTINE_NULL.
338 */
339routine task_set_emulation_vector(
340		task		: task_t;
341		vector_start	: int;
342		emulation_vector: emulation_vector_t);
343
344
345/*
346 *      Establish restart pc for interrupted atomic sequences.
347 */
348routine task_set_ras_pc(
349		target_task     : task_t;
350		basepc          : vm_address_t;
351		boundspc        : vm_address_t);
352
353
354/*
355 * Return zone info as seen/used by this task.
356 */
357routine task_zone_info(
358		target_task	: task_t;
359	out	names		: mach_zone_name_array_t,
360					Dealloc;
361	out	info		: task_zone_info_array_t,
362					Dealloc);
363
364
365/*
366 * JMM - Want to eliminate processor_set so keep them at the end.
367 */
368
369/*
370 *	Assign task to processor set.
371 */
372routine task_assign(
373		task		: task_t;
374		new_set		: processor_set_t;
375		assign_threads	: boolean_t);
376
377/*
378 *	Assign task to default set.
379 */
380routine task_assign_default(
381		task		: task_t;
382		assign_threads	: boolean_t);
383
384/*
385 *	Get current assignment for task.
386 */
387routine task_get_assignment(
388		task		: task_t;
389	out	assigned_set	: processor_set_name_t);
390
391/*
392 * OBSOLETE interface.
393 */
394routine task_set_policy(
395	task			: task_t;
396	pset			: processor_set_t;
397	policy			: policy_t;
398	base			: policy_base_t;
399	limit			: policy_limit_t;
400	change			: boolean_t);
401
402/*
403 * Read the selected state which is to be installed on new
404 * threads in the task as they are created.
405 */
406routine task_get_state(
407		task		: task_t;
408		flavor		: thread_state_flavor_t;
409	out	old_state	: thread_state_t, CountInOut);
410
411/*
412 * Set the selected state information to be installed on
413 * all subsequently created threads in the task.
414 */
415routine	task_set_state(
416		task		: task_t;
417		flavor		: thread_state_flavor_t;
418		new_state	: thread_state_t);
419
420/*
421 * Change the task's physical footprint limit (in MB).
422 */
423routine task_set_phys_footprint_limit(
424		task		: task_t;
425		new_limit	: int;
426	out old_limit	: int);
427
428routine task_suspend2(
429		target_task : task_t;
430	out suspend_token : task_suspension_token_t);
431
432routine task_resume2(
433		suspend_token : task_suspension_token_t);
434
435routine task_purgable_info(
436		task 		: task_t;
437	out	stats		: task_purgable_info_t);
438
439routine task_get_mach_voucher(
440		task		: task_t;
441		which		: mach_voucher_selector_t;
442	out	voucher		: ipc_voucher_t);
443
444routine task_set_mach_voucher(
445		task		: task_t;
446		voucher		: ipc_voucher_t);
447
448routine task_swap_mach_voucher(
449		task		: task_t;
450		new_voucher	: ipc_voucher_t;
451	inout	old_voucher	: ipc_voucher_t);
452
453/* vim: set ft=c : */
454
455