/* * 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 #include /* * 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); skip; /* old old_mach_port_get_receive_status */ /* * 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);