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 * Create and destroy lock_set and semaphore synchronizers on a
246 * per-task basis (i.e. the task owns them).
247 */
248routine lock_set_create(
249		task		: task_t;
250	out	new_lock_set	: lock_set_t;
251		n_ulocks	: int;
252		policy		: int);
253
254routine lock_set_destroy(
255		task		: task_t;
256		lock_set	: lock_set_t);
257
258routine semaphore_create(
259		task		: task_t;
260	out	semaphore	: semaphore_t;
261		policy		: int;
262		value		: int);
263
264routine semaphore_destroy(
265		task		: task_t;
266		semaphore	: semaphore_consume_ref_t);
267
268/*
269 * Set/get policy information for a task.
270 * (Approved Mac OS X microkernel interface)
271 */
272
273routine task_policy_set(
274	task			: task_t;
275	flavor			: task_policy_flavor_t;
276	policy_info		: task_policy_t);
277
278routine task_policy_get(
279	task			: task_t;
280	flavor			: task_policy_flavor_t;
281out	policy_info		: task_policy_t, CountInOut;
282inout	get_default		: boolean_t);
283
284/*
285 *	Removed from the kernel.
286 */
287#if KERNEL_SERVER
288skip;
289#else
290routine task_sample(
291		task		: task_t;
292		reply		: mach_port_make_send_t);
293#endif
294
295/*
296 * JMM - Everything from here down is likely to go away soon
297 */
298/*
299 * OBSOLETE interface.
300 */
301routine task_policy(
302	task			: task_t;
303	policy			: policy_t;
304	base			: policy_base_t;
305	set_limit		: boolean_t;
306	change			: boolean_t);
307
308
309/*
310 *	Establish a user-level handler for the specified
311 *	system call.
312 */
313routine task_set_emulation(
314		target_port	: task_t;
315		routine_entry_pt: vm_address_t;
316		routine_number  : int);
317
318/*
319 *	Get user-level handler entry points for all
320 *	emulated system calls.
321 */
322routine task_get_emulation_vector(
323		task		: task_t;
324	out	vector_start	: int;
325	out	emulation_vector: emulation_vector_t);
326
327/*
328 *	Establish user-level handlers for the specified
329 *	system calls. Non-emulated system calls are specified
330 *	with emulation_vector[i] == EML_ROUTINE_NULL.
331 */
332routine task_set_emulation_vector(
333		task		: task_t;
334		vector_start	: int;
335		emulation_vector: emulation_vector_t);
336
337
338/*
339 *      Establish restart pc for interrupted atomic sequences.
340 */
341routine task_set_ras_pc(
342		target_task     : task_t;
343		basepc          : vm_address_t;
344		boundspc        : vm_address_t);
345
346
347/*
348 * Return zone info as seen/used by this task.
349 */
350routine task_zone_info(
351		target_task	: task_t;
352	out	names		: mach_zone_name_array_t,
353					Dealloc;
354	out	info		: task_zone_info_array_t,
355					Dealloc);
356
357
358/*
359 * JMM - Want to eliminate processor_set so keep them at the end.
360 */
361
362/*
363 *	Assign task to processor set.
364 */
365routine task_assign(
366		task		: task_t;
367		new_set		: processor_set_t;
368		assign_threads	: boolean_t);
369
370/*
371 *	Assign task to default set.
372 */
373routine task_assign_default(
374		task		: task_t;
375		assign_threads	: boolean_t);
376
377/*
378 *	Get current assignment for task.
379 */
380routine task_get_assignment(
381		task		: task_t;
382	out	assigned_set	: processor_set_name_t);
383
384/*
385 * OBSOLETE interface.
386 */
387routine task_set_policy(
388	task			: task_t;
389	pset			: processor_set_t;
390	policy			: policy_t;
391	base			: policy_base_t;
392	limit			: policy_limit_t;
393	change			: boolean_t);
394
395/*
396 * Read the selected state which is to be installed on new
397 * threads in the task as they are created.
398 */
399routine task_get_state(
400		task		: task_t;
401		flavor		: thread_state_flavor_t;
402	out	old_state	: thread_state_t, CountInOut);
403
404/*
405 * Set the selected state information to be installed on
406 * all subsequently created threads in the task.
407 */
408routine	task_set_state(
409		task		: task_t;
410		flavor		: thread_state_flavor_t;
411		new_state	: thread_state_t);
412
413/* vim: set ft=c : */
414