path: root/include/mach/mach_port.defs

/*
 * Mach Operating System
 * Copyright (c) 1991,1990,1989 Carnegie Mellon University.
 * Copyright (c) 1993,1994 The University of Utah and
 * the Computer Systems Laboratory (CSL).
 * 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, THE UNIVERSITY OF UTAH AND CSL ALLOW FREE USE OF
 * THIS SOFTWARE IN ITS "AS IS" CONDITION, AND DISCLAIM 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
 *
 *	Copyright (c) 1989 Richard P. Draves, Jr.
 *
 *	Exported kernel calls.
 */

subsystem
#if	KERNEL_SERVER
	  KernelServer
#endif
		       mach_port 3200;

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

/*
 *	Returns the set of port and port set names
 *	to which the target task has access, along with
 *	the type (set or port) for each name.
 */

routine mach_port_names(
		task		: ipc_space_t;
	out	names		: mach_port_name_array_t =
					^array[] of mach_port_name_t
					ctype: mach_port_array_t;
	out	types		: mach_port_type_array_t =
					^array[] of mach_port_type_t);

/*
 *	Returns the type (set or port) for the port name
 *	within the target task.  Also indicates whether
 *	there is a dead-name request for the name.
 */

routine mach_port_type(
		task		: ipc_space_t;
		name		: mach_port_name_t;
	out	ptype		: mach_port_type_t);

/*
 *	Changes the name by which a port (or port set) is known to
 *	the target task.  The new name can't be in use.  The
 *	old name becomes available for recycling.
 */

routine mach_port_rename(
		task		: ipc_space_t;
		old_name	: mach_port_name_t;
		new_name	: mach_port_name_t);

/*
 *	Allocates the specified kind of object, with the given name.
 *	The right must be one of
 *		MACH_PORT_RIGHT_RECEIVE
 *		MACH_PORT_RIGHT_PORT_SET
 *		MACH_PORT_RIGHT_DEAD_NAME
 *	New port sets are empty.  New ports don't have any
 *	send/send-once rights or queued messages.  The make-send
 *	count is zero and their queue limit is MACH_PORT_QLIMIT_DEFAULT.
 *	New sets, ports, and dead names have one user reference.
 */

routine mach_port_allocate_name(
		task		: ipc_space_t;
		right		: mach_port_right_t;
		name		: mach_port_name_t);

/*
 *	Allocates the specified kind of object.
 *	The right must be one of
 *		MACH_PORT_RIGHT_RECEIVE
 *		MACH_PORT_RIGHT_PORT_SET
 *		MACH_PORT_RIGHT_DEAD_NAME
 *	Like port_allocate_name, but the kernel picks a name.
 *	It can use any name not associated with a right.
 */

routine mach_port_allocate(
		task		: ipc_space_t;
		right		: mach_port_right_t;
	out	name		: mach_port_name_t);

/*
 *	Destroys all rights associated with the name and makes it
 *	available for recycling immediately.  The name can be a
 *	port (possibly with multiple user refs), a port set, or
 *	a dead name (again, with multiple user refs).
 */

routine mach_port_destroy(
		task		: ipc_space_t;
		name		: mach_port_name_t);

/*
 *	Releases one send/send-once/dead-name user ref.
 *	Just like mach_port_mod_refs -1, but deduces the
 *	correct type of right.  This allows a user task
 *	to release a ref for a port without worrying
 *	about whether the port has died or not.
 */

routine mach_port_deallocate(
		task		: ipc_space_t;
		name		: mach_port_name_t);

/*
 *	A port set always has one user ref.
 *	A send-once right always has one user ref.
 *	A dead name always has one or more user refs.
 *	A send right always has one or more user refs.
 *	A receive right always has one user ref.
 *	The right must be one of
 *		MACH_PORT_RIGHT_RECEIVE
 *		MACH_PORT_RIGHT_PORT_SET
 *		MACH_PORT_RIGHT_DEAD_NAME
 *		MACH_PORT_RIGHT_SEND
 *		MACH_PORT_RIGHT_SEND_ONCE
 */

routine mach_port_get_refs(
		task		: ipc_space_t;
		name		: mach_port_name_t;
		right		: mach_port_right_t;
	out	refs		: mach_port_urefs_t);

/*
 *	The delta is a signed change to the task's
 *	user ref count for the right.  Only dead names
 *	and send rights can have a positive delta.
 *	The resulting user ref count can't be negative.
 *	If it is zero, the right is deallocated.
 *	If the name isn't a composite right, it becomes
 *	available for recycling.  The right must be one of
 *		MACH_PORT_RIGHT_RECEIVE
 *		MACH_PORT_RIGHT_PORT_SET
 *		MACH_PORT_RIGHT_DEAD_NAME
 *		MACH_PORT_RIGHT_SEND
 *		MACH_PORT_RIGHT_SEND_ONCE
 */

routine mach_port_mod_refs(
		task		: ipc_space_t;
		name		: mach_port_name_t;
		right		: mach_port_right_t;
		delta		: mach_port_delta_t);

/*
 *	Temporary compatibility call.
 */

routine old_mach_port_get_receive_status(
		task		: ipc_space_t;
		name		: mach_port_name_t;
	out	status		: old_mach_port_status_t);

/*
 *	Only valid for receive rights.
 *	Sets the queue-limit for the port.
 *	The limit must be
 *		1 <= qlimit <= MACH_PORT_QLIMIT_MAX
 */

routine mach_port_set_qlimit(
		task		: ipc_space_t;
		name		: mach_port_name_t;
		qlimit		: mach_port_msgcount_t);

/*
 *	Only valid for receive rights.
 *	Sets the make-send count for the port.
 */

routine mach_port_set_mscount(
		task		: ipc_space_t;
		name		: mach_port_name_t;
		mscount		: mach_port_mscount_t);

/*
 *	Only valid for port sets.  Returns a list of
 *	the members.
 */

routine mach_port_get_set_status(
		task		: ipc_space_t;
		name		: mach_port_name_t;
	out	members		: mach_port_name_array_t =
					^array[] of mach_port_name_t
					ctype: mach_port_array_t);

/*
 *	Puts the member port (the task must have receive rights)
 *	into the after port set.  (Or removes it from any port set
 *	if after is MACH_PORT_NULL.)  If the port is already in
 *	a set, does an atomic move.
 */

routine mach_port_move_member(
		task		: ipc_space_t;
		member		: mach_port_name_t;
		after		: mach_port_name_t);

/*
 *	Requests a notification from the kernel.  The request
 *	must supply the send-once right which is used for
 *	the notification.  If a send-once right was previously
 *	registered, it is returned.  The msg_id must be one of
 *		MACH_NOTIFY_PORT_DESTROYED (receive rights)
 *		MACH_NOTIFY_DEAD_NAME (send/receive/send-once rights)
 *		MACH_NOTIFY_NO_SENDERS (receive rights)
 *
 *	The sync value specifies whether a notification should
 *	get sent immediately, if appropriate.  The exact meaning
 *	depends on the notification:
 *		MACH_NOTIFY_PORT_DESTROYED: must be zero.
 *		MACH_NOTIFY_DEAD_NAME: if non-zero, then name can be dead,
 *			and the notification gets sent immediately.
 *			If zero, then name can't be dead.
 *		MACH_NOTIFY_NO_SENDERS: the notification gets sent
 *			immediately if the current mscount is greater
 *			than or equal to the sync value and there are no
 *			extant send rights.
 */

routine mach_port_request_notification(
		task		: ipc_space_t;
		name		: mach_port_name_t;
		id		: mach_msg_id_t;
		sync		: mach_port_mscount_t;
		notify		: mach_port_send_once_t;
	out	previous	: mach_port_send_once_t);

/*
 *	Inserts the specified rights into the target task,
 *	using the specified name.  If inserting send/receive
 *	rights and the task already has send/receive rights
 *	for the port, then the names must agree.  In any case,
 *	the task gains a user ref for the port.
 */

routine mach_port_insert_right(
		task		: ipc_space_t;
		name		: mach_port_name_t;
		poly		: mach_port_poly_t);

/*
 *	Returns the specified right for the named port
 *	in the target task, extracting that right from
 *	the target task.  The target task loses a user
 *	ref and the name may be available for recycling.
 *	msgt_name must be one of
 *		MACH_MSG_TYPE_MOVE_RECEIVE
 *		MACH_MSG_TYPE_COPY_SEND
 *		MACH_MSG_TYPE_MAKE_SEND
 *		MACH_MSG_TYPE_MOVE_SEND
 *		MACH_MSG_TYPE_MAKE_SEND_ONCE
 *		MACH_MSG_TYPE_MOVE_SEND_ONCE
 */

routine mach_port_extract_right(
		task		: ipc_space_t;
		name		: mach_port_name_t;
		msgt_name	: mach_msg_type_name_t;
	out	poly		: mach_port_poly_t);

/*
 *	The task must have receive rights for the named port.
 *	Returns a status structure (see mach/port.h).
 */

routine mach_port_get_receive_status(
		task		: ipc_space_t;
		name		: mach_port_name_t;
	out	status		: mach_port_status_t);

/*
 *	Only valid for receive rights.
 *	Sets the sequence number for the port.
 */

routine mach_port_set_seqno(
		task		: ipc_space_t;
		name		: mach_port_name_t;
		seqno		: mach_port_seqno_t);

#ifdef MIGRATING_THREADS
/*
 *	Only valid for receive rights.
 *	Set the user-mode entry info for RPCs coming through this port.
 *	Do this BEFORE attaching an ActPool to this port,
 *	unless you can be sure no RPCs will be coming through it yet.
 */

routine mach_port_set_rpcinfo(
		task		: ipc_space_t;
		name		: mach_port_name_t;
		rpc_info	: thread_info_t);	/* XXX */

/*
 *	Only valid for receive rights.
 *	Create a new activation for migrating RPC, and attach it to the port's ActPool.
 *	Create an ActPool for the port if it doesn't already have one.
 *	Supply a stack and receive memory buffer.
 */

routine mach_port_create_act(
		task		: task_t;
		name		: mach_port_name_t;
		user_stack	: vm_offset_t;
		user_rbuf	: vm_offset_t;
		user_rbuf_size	: vm_size_t;
	out	new_act		: thread_t);

#else  /* MIGRATING_THREADS */

skip; /* mach_port_set_rpcinfo */
skip; /* mach_port_create_act */

#endif /* MIGRATING_THREADS */

/*
 *	Only valid for receive rights.
 *	Set the protected payload for this right to the given value.
 */

routine mach_port_set_protected_payload(
		task		: ipc_space_t;
		name		: mach_port_name_t;
		payload		: natural_t);

/*
 *	Only valid for receive rights.
 *	Clear the protected payload for this right.
 */

routine mach_port_clear_protected_payload(
		task		: ipc_space_t;
		name		: mach_port_name_t);