1/* 2 * Copyright (c) 2000-2004 Apple Computer, 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 mach_port 3200; 70 71#if !KERNEL && !LIBSYSCALL_INTERFACE 72 UserPrefix _kernelrpc_; 73#endif 74 75#include <mach/std_types.defs> 76#include <mach/mach_types.defs> 77#include <mach_debug/mach_debug_types.defs> 78 79/* 80 * Returns the set of port and port set names 81 * to which the target task has access, along with 82 * the type (set or port) for each name. 83 */ 84 85routine mach_port_names( 86 task : ipc_space_t; 87 out names : mach_port_name_array_t; 88 out types : mach_port_type_array_t); 89 90/* 91 * Returns the type (set or port) for the port name 92 * within the target task. Also indicates whether 93 * there is a dead-name request for the name. 94 */ 95 96routine mach_port_type( 97 task : ipc_space_t; 98 name : mach_port_name_t; 99 out ptype : mach_port_type_t); 100 101/* 102 * Changes the name by which a port (or port set) is known to 103 * the target task. The new name can't be in use. The 104 * old name becomes available for recycling. 105 * 106 * This interface is OBSOLETE and will always 107 * return KERN_NOT_SUPPORTED. 108 */ 109 110routine mach_port_rename( 111 task : ipc_space_t; 112 old_name : mach_port_name_t; 113 new_name : mach_port_name_t); 114 115/* 116 * Allocates the specified kind of object, with the given name. 117 * The right must be one of 118 * MACH_PORT_RIGHT_RECEIVE 119 * MACH_PORT_RIGHT_PORT_SET 120 * MACH_PORT_RIGHT_DEAD_NAME 121 * New port sets are empty. New ports don't have any 122 * send/send-once rights or queued messages. The make-send 123 * count is zero and their queue limit is MACH_PORT_QLIMIT_DEFAULT. 124 * New sets, ports, and dead names have one user reference. 125 */ 126 127routine mach_port_allocate_name( 128 task : ipc_space_t; 129 right : mach_port_right_t; 130 name : mach_port_name_t); 131 132/* 133 * Allocates the specified kind of object. 134 * The right must be one of 135 * MACH_PORT_RIGHT_RECEIVE 136 * MACH_PORT_RIGHT_PORT_SET 137 * MACH_PORT_RIGHT_DEAD_NAME 138 * Like port_allocate_name, but the kernel picks a name. 139 * It can use any name not associated with a right. 140 */ 141 142routine mach_port_allocate( 143 task : ipc_space_t; 144 right : mach_port_right_t; 145 out name : mach_port_name_t); 146 147/* 148 * Destroys all rights associated with the name and makes it 149 * available for recycling immediately. The name can be a 150 * port (possibly with multiple user refs), a port set, or 151 * a dead name (again, with multiple user refs). 152 */ 153 154routine mach_port_destroy( 155 task : ipc_space_t; 156 name : mach_port_name_t); 157 158/* 159 * Releases one send/send-once/dead-name user ref. 160 * Just like mach_port_mod_refs -1, but deduces the 161 * correct type of right. This allows a user task 162 * to release a ref for a port without worrying 163 * about whether the port has died or not. 164 */ 165 166routine mach_port_deallocate( 167 task : ipc_space_t; 168 name : mach_port_name_t); 169 170/* 171 * A port set always has one user ref. 172 * A send-once right always has one user ref. 173 * A dead name always has one or more user refs. 174 * A send right always has one or more user refs. 175 * A receive right always has one user ref. 176 * The right must be one of 177 * MACH_PORT_RIGHT_RECEIVE 178 * MACH_PORT_RIGHT_PORT_SET 179 * MACH_PORT_RIGHT_DEAD_NAME 180 * MACH_PORT_RIGHT_SEND 181 * MACH_PORT_RIGHT_SEND_ONCE 182 */ 183 184routine mach_port_get_refs( 185 task : ipc_space_t; 186 name : mach_port_name_t; 187 right : mach_port_right_t; 188 out refs : mach_port_urefs_t); 189 190/* 191 * The delta is a signed change to the task's 192 * user ref count for the right. Only dead names 193 * and send rights can have a positive delta. 194 * The resulting user ref count can't be negative. 195 * If it is zero, the right is deallocated. 196 * If the name isn't a composite right, it becomes 197 * available for recycling. The right must be one of 198 * MACH_PORT_RIGHT_RECEIVE 199 * MACH_PORT_RIGHT_PORT_SET 200 * MACH_PORT_RIGHT_DEAD_NAME 201 * MACH_PORT_RIGHT_SEND 202 * MACH_PORT_RIGHT_SEND_ONCE 203 */ 204 205routine mach_port_mod_refs( 206 task : ipc_space_t; 207 name : mach_port_name_t; 208 right : mach_port_right_t; 209 delta : mach_port_delta_t); 210 211skip; 212 213/* 214 * Only valid for receive rights. 215 * Sets the make-send count for the port. 216 */ 217routine mach_port_set_mscount( 218 task : ipc_space_t; 219 name : mach_port_name_t; 220 mscount : mach_port_mscount_t); 221 222/* 223 * Only valid for port sets. Returns a list of 224 * the members. 225 */ 226 227routine mach_port_get_set_status( 228 task : ipc_space_t; 229 name : mach_port_name_t; 230 out members : mach_port_name_array_t); 231 232/* 233 * Puts the member port (the task must have receive rights) 234 * into the after port set. If the port is already a member 235 * of any set(s), it is atomically removed from those sets as 236 * part of this operation. (If after is MACH_PORT_NULL, the 237 * port is still removed from all current sets). 238 */ 239 240routine mach_port_move_member( 241 task : ipc_space_t; 242 member : mach_port_name_t; 243 after : mach_port_name_t); 244 245/* 246 * Requests a notification from the kernel. The request 247 * must supply the send-once right which is used for 248 * the notification. If a send-once right was previously 249 * registered, it is returned. The msgid must be one of: 250 * MACH_NOTIFY_PORT_DESTROYED (receive rights) 251 * MACH_NOTIFY_DEAD_NAME (send/receive/send-once rights) 252 * MACH_NOTIFY_SEND_POSSIBLE (send/receive/send-once rights) 253 * MACH_NOTIFY_NO_SENDERS (receive rights) 254 * 255 * The sync value specifies whether a notification should 256 * get sent immediately, if appropriate. The exact meaning 257 * depends on the notification: 258 * MACH_NOTIFY_PORT_DESTROYED: must be zero. 259 * MACH_NOTIFY_DEAD_NAME: if non-zero, then name can be dead, 260 * and the notification gets sent immediately. 261 * If zero, then name can't be dead. 262 * MACH_NOTIFY_SEND_POSSIBLE: if non-zero, will generate a send- 263 * possible notification as soon as it is possible to send 264 * to the port. If zero, will generate a send-possible 265 * notification only after a subsequent failed send 266 * (with MACH_SEND_NOTIFY option to mach_msg call). Can 267 * generate a dead-name notification if name is already dead 268 * or becomes dead before a send-possible notification fires. 269 * MACH_NOTIFY_NO_SENDERS: the notification gets sent 270 * immediately if the current mscount is greater 271 * than or equal to the sync value and there are no 272 * extant send rights. 273 * 274 * If the name is deleted before a successfully registered notification 275 * is delivered, it is replaced with a port-deleted notification. 276 */ 277 278routine mach_port_request_notification( 279 task : ipc_space_t; 280 name : mach_port_name_t; 281 msgid : mach_msg_id_t; 282 sync : mach_port_mscount_t; 283 notify : mach_port_send_once_t; 284 out previous : mach_port_move_send_once_t); 285 286/* 287 * Inserts the specified rights into the target task, 288 * using the specified name. If inserting send/receive 289 * rights and the task already has send/receive rights 290 * for the port, then the names must agree. In any case, 291 * the task gains a user ref for the port. 292 */ 293 294routine mach_port_insert_right( 295 task : ipc_space_t; 296 name : mach_port_name_t; 297 poly : mach_port_poly_t); 298 299/* 300 * Returns the specified right for the named port 301 * in the target task, extracting that right from 302 * the target task. The target task loses a user 303 * ref and the name may be available for recycling. 304 * msgt_name must be one of 305 * MACH_MSG_TYPE_MOVE_RECEIVE 306 * MACH_MSG_TYPE_COPY_SEND 307 * MACH_MSG_TYPE_MAKE_SEND 308 * MACH_MSG_TYPE_MOVE_SEND 309 * MACH_MSG_TYPE_MAKE_SEND_ONCE 310 * MACH_MSG_TYPE_MOVE_SEND_ONCE 311 */ 312 313routine mach_port_extract_right( 314 task : ipc_space_t; 315 name : mach_port_name_t; 316 msgt_name : mach_msg_type_name_t; 317 out poly : mach_port_poly_t); 318 319/* 320 * Only valid for receive rights. 321 * Sets the sequence number for the port. 322 */ 323 324routine mach_port_set_seqno( 325 task : ipc_space_t; 326 name : mach_port_name_t; 327 seqno : mach_port_seqno_t); 328 329/* 330 * Returns information about a port. 331 */ 332 333routine mach_port_get_attributes( 334 task : ipc_space_t; 335 name : mach_port_name_t; 336 flavor : mach_port_flavor_t; 337 out port_info_out : mach_port_info_t, CountInOut); 338 339/* 340 * Set attributes of a port 341 */ 342 343routine mach_port_set_attributes( 344 task : ipc_space_t; 345 name : mach_port_name_t; 346 flavor : mach_port_flavor_t; 347 port_info : mach_port_info_t); 348 349 350/* 351 * Allocates the specified kind of object, qos version. 352 * The right must be 353 * MACH_PORT_RIGHT_RECEIVE 354 * Like port_allocate_name, but the kernel picks a name. 355 * It can use any name not associated with a right. 356 */ 357 358routine mach_port_allocate_qos( 359 task : ipc_space_t; 360 right : mach_port_right_t; 361 inout qos : mach_port_qos_t; 362 out name : mach_port_name_t); 363 364 365/* 366 * Generic interface to allocation various kinds of ports. 367 * Should never be called directly by users (at least not 368 * unless they are exceedingly masochistic). 369 */ 370 371routine mach_port_allocate_full( 372 task : ipc_space_t; 373 right : mach_port_right_t; 374 proto : mach_port_t; 375 inout qos : mach_port_qos_t; 376 inout name : mach_port_name_t); 377 378 379/* 380 * Pre-expand task port name space. 381 */ 382routine task_set_port_space( 383 task : ipc_space_t; 384 table_entries : int); 385 386 387/* 388 * Returns the exact number of extant send rights 389 * for the given receive right. 390 * This call is only valid on MACH_IPC_DEBUG kernels. 391 * Otherwise, KERN_FAILURE is returned. 392 */ 393routine mach_port_get_srights( 394 task : ipc_space_t; 395 name : mach_port_name_t; 396 out srights : mach_port_rights_t); 397 398 399/* 400 * Returns information about an IPC space. 401 * This call is only valid on MACH_IPC_DEBUG kernels. 402 * Otherwise, KERN_FAILURE is returned. 403 */ 404routine mach_port_space_info( 405 task : ipc_space_t; 406 out space_info : ipc_info_space_t; 407 out table_info : ipc_info_name_array_t; 408 out tree_info : ipc_info_tree_name_array_t); 409 410/* 411 * Returns information about the dead-name requests 412 * registered with the named receive right. 413 * This call is only valid on MACH_IPC_DEBUG kernels. 414 * Otherwise, KERN_FAILURE is returned. 415 */ 416routine mach_port_dnrequest_info( 417 task : ipc_space_t; 418 name : mach_port_name_t; 419 out dnr_total : unsigned; /* total size of table */ 420 out dnr_used : unsigned); /* amount used */ 421 422/* 423 * Return the type and address of the kernel object 424 * that the given send/receive right represents. 425 * This call is only valid on MACH_IPC_DEBUG kernels. 426 * Otherwise, KERN_FAILURE is returned. 427 * 428 * This interface is DEPRECATED in favor of the new 429 * mach_port_kernel_object64() call (see below). 430 */ 431routine mach_port_kernel_object( 432 task : ipc_space_t; 433 name : mach_port_name_t; 434 out object_type : unsigned; 435 out object_addr : unsigned); 436 437 438/* 439 * Inserts the specified rights into the portset identified 440 * by the <task, pset> pair. The results of passing in the 441 * Poly argument via the supplied disposition must yield a 442 * receive right. 443 * 444 * If the <task,pset> pair does not represent a valid portset 445 * KERN_INVALID_RIGHT is returned. 446 * 447 * If the passed in name argument does not represent a receive 448 * right, KERN_INVALID_CAPABILITY will be returned. 449 * 450 * If the port represented by the receive right is already in 451 * the portset, KERN_ALREADY_IN_SET is returned. 452 */ 453routine mach_port_insert_member( 454 task : ipc_space_t; 455 name : mach_port_name_t; 456 pset : mach_port_name_t); 457 458/* 459 * Extracts the specified right from the named portset 460 * in the target task. 461 * the target task. The target task loses a user 462 * ref and the name may be available for recycling. 463 * msgt_name must be one of 464 * MACH_MSG_TYPE_MOVE_RECEIVE 465 * MACH_MSG_TYPE_COPY_SEND 466 * MACH_MSG_TYPE_MAKE_SEND 467 * MACH_MSG_TYPE_MOVE_SEND 468 * MACH_MSG_TYPE_MAKE_SEND_ONCE 469 * MACH_MSG_TYPE_MOVE_SEND_ONCE 470 */ 471 472routine mach_port_extract_member( 473 task : ipc_space_t; 474 name : mach_port_name_t; 475 pset : mach_port_name_t); 476 477/* 478 * Only valid for receive rights. 479 * Gets the context pointer for the port. 480 */ 481 482routine mach_port_get_context( 483 task : ipc_space_t; 484 name : mach_port_name_t; 485#ifdef LIBSYSCALL_INTERFACE 486 out context : mach_port_context_t 487#else 488 out context : mach_vm_address_t 489#endif 490 ); 491 492/* 493 * Only valid for receive rights. 494 * Sets the context pointer for the port. 495 */ 496 497routine mach_port_set_context( 498 task : ipc_space_t; 499 name : mach_port_name_t; 500#ifdef LIBSYSCALL_INTERFACE 501 context : mach_port_context_t 502#else 503 context : mach_vm_address_t 504#endif 505 ); 506 507/* 508 * Return the type and address of the kernel object 509 * that the given send/receive right represents. 510 * This call is only valid on MACH_IPC_DEBUG kernels. 511 * Otherwise, KERN_FAILURE is returned. 512 */ 513routine mach_port_kobject( 514 task : ipc_space_t; 515 name : mach_port_name_t; 516 out object_type : natural_t; 517 out object_addr : mach_vm_address_t); 518 519 520/* vim: set ft=c : */ 521