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 211/* 212 * Peek at the message queue for the specified receive 213 * right and return info about the message with the 214 * sequence number matching the input. If zero is 215 * specified as the seqno, the first message in the 216 * queue will be peeked. 217 * 218 * Only the following trailer types are currently supported: 219 * MACH_RCV_TRAILER_TYPE(MACH_MSG_TRAILER_FORMAT_0) 220 * 221 * or'ed with one of these element types: 222 * MACH_RCV_TRAILER_ELEMENTS(MACH_RCV_TRAILER_NULL) 223 * MACH_RCV_TRAILER_ELEMENTS(MACH_RCV_TRAILER_SEQNO) 224 * MACH_RCV_TRAILER_ELEMENTS(MACH_RCV_TRAILER_SENDER) 225 * MACH_RCV_TRAILER_ELEMENTS(MACH_RCV_TRAILER_AUDIT) 226 */ 227routine mach_port_peek( 228 task : ipc_space_t; 229 name : mach_port_name_t; 230 trailer_type : mach_msg_trailer_type_t; 231 inout request_seqnop : mach_port_seqno_t; 232 out msg_sizep : mach_msg_size_t; 233 out msg_idp : mach_msg_id_t; 234 out trailer_infop : mach_msg_trailer_info_t, CountInOut); 235 236/* 237 * Only valid for receive rights. 238 * Sets the make-send count for the port. 239 */ 240routine mach_port_set_mscount( 241 task : ipc_space_t; 242 name : mach_port_name_t; 243 mscount : mach_port_mscount_t); 244 245/* 246 * Only valid for port sets. Returns a list of 247 * the members. 248 */ 249 250routine mach_port_get_set_status( 251 task : ipc_space_t; 252 name : mach_port_name_t; 253 out members : mach_port_name_array_t); 254 255/* 256 * Puts the member port (the task must have receive rights) 257 * into the after port set. If the port is already a member 258 * of any set(s), it is atomically removed from those sets as 259 * part of this operation. (If after is MACH_PORT_NULL, the 260 * port is still removed from all current sets). 261 */ 262 263routine mach_port_move_member( 264 task : ipc_space_t; 265 member : mach_port_name_t; 266 after : mach_port_name_t); 267 268/* 269 * Requests a notification from the kernel. The request 270 * must supply the send-once right which is used for 271 * the notification. If a send-once right was previously 272 * registered, it is returned. The msgid must be one of: 273 * MACH_NOTIFY_PORT_DESTROYED (receive rights) 274 * MACH_NOTIFY_DEAD_NAME (send/receive/send-once rights) 275 * MACH_NOTIFY_SEND_POSSIBLE (send/receive/send-once rights) 276 * MACH_NOTIFY_NO_SENDERS (receive rights) 277 * 278 * The sync value specifies whether a notification should 279 * get sent immediately, if appropriate. The exact meaning 280 * depends on the notification: 281 * MACH_NOTIFY_PORT_DESTROYED: must be zero. 282 * MACH_NOTIFY_DEAD_NAME: if non-zero, then name can be dead, 283 * and the notification gets sent immediately. 284 * If zero, then name can't be dead. 285 * MACH_NOTIFY_SEND_POSSIBLE: if non-zero, will generate a send- 286 * possible notification as soon as it is possible to send 287 * to the port. If zero, will generate a send-possible 288 * notification only after a subsequent failed send 289 * (with MACH_SEND_NOTIFY option to mach_msg call). Can 290 * generate a dead-name notification if name is already dead 291 * or becomes dead before a send-possible notification fires. 292 * MACH_NOTIFY_NO_SENDERS: the notification gets sent 293 * immediately if the current mscount is greater 294 * than or equal to the sync value and there are no 295 * extant send rights. 296 * 297 * If the name is deleted before a successfully registered notification 298 * is delivered, it is replaced with a port-deleted notification. 299 */ 300 301routine mach_port_request_notification( 302 task : ipc_space_t; 303 name : mach_port_name_t; 304 msgid : mach_msg_id_t; 305 sync : mach_port_mscount_t; 306 notify : mach_port_send_once_t; 307 out previous : mach_port_move_send_once_t); 308 309/* 310 * Inserts the specified rights into the target task, 311 * using the specified name. If inserting send/receive 312 * rights and the task already has send/receive rights 313 * for the port, then the names must agree. In any case, 314 * the task gains a user ref for the port. 315 */ 316 317routine mach_port_insert_right( 318 task : ipc_space_t; 319 name : mach_port_name_t; 320 poly : mach_port_poly_t); 321 322/* 323 * Returns the specified right for the named port 324 * in the target task, extracting that right from 325 * the target task. The target task loses a user 326 * ref and the name may be available for recycling. 327 * msgt_name must be one of 328 * MACH_MSG_TYPE_MOVE_RECEIVE 329 * MACH_MSG_TYPE_COPY_SEND 330 * MACH_MSG_TYPE_MAKE_SEND 331 * MACH_MSG_TYPE_MOVE_SEND 332 * MACH_MSG_TYPE_MAKE_SEND_ONCE 333 * MACH_MSG_TYPE_MOVE_SEND_ONCE 334 */ 335 336routine mach_port_extract_right( 337 task : ipc_space_t; 338 name : mach_port_name_t; 339 msgt_name : mach_msg_type_name_t; 340 out poly : mach_port_poly_t); 341 342/* 343 * Only valid for receive rights. 344 * Sets the sequence number for the port. 345 */ 346 347routine mach_port_set_seqno( 348 task : ipc_space_t; 349 name : mach_port_name_t; 350 seqno : mach_port_seqno_t); 351 352/* 353 * Returns information about a port. 354 */ 355 356routine mach_port_get_attributes( 357 task : ipc_space_t; 358 name : mach_port_name_t; 359 flavor : mach_port_flavor_t; 360 out port_info_out : mach_port_info_t, CountInOut); 361 362/* 363 * Set attributes of a port 364 */ 365 366routine mach_port_set_attributes( 367 task : ipc_space_t; 368 name : mach_port_name_t; 369 flavor : mach_port_flavor_t; 370 port_info : mach_port_info_t); 371 372 373/* 374 * Allocates the specified kind of object, qos version. 375 * The right must be 376 * MACH_PORT_RIGHT_RECEIVE 377 * Like port_allocate_name, but the kernel picks a name. 378 * It can use any name not associated with a right. 379 */ 380 381routine mach_port_allocate_qos( 382 task : ipc_space_t; 383 right : mach_port_right_t; 384 inout qos : mach_port_qos_t; 385 out name : mach_port_name_t); 386 387 388/* 389 * Generic interface to allocation various kinds of ports. 390 * Should never be called directly by users (at least not 391 * unless they are exceedingly masochistic). 392 */ 393 394routine mach_port_allocate_full( 395 task : ipc_space_t; 396 right : mach_port_right_t; 397 proto : mach_port_t; 398 inout qos : mach_port_qos_t; 399 inout name : mach_port_name_t); 400 401 402/* 403 * Pre-expand task port name space. 404 */ 405routine task_set_port_space( 406 task : ipc_space_t; 407 table_entries : int); 408 409 410/* 411 * Returns the exact number of extant send rights 412 * for the given receive right. 413 * This call is only valid on MACH_IPC_DEBUG kernels. 414 * Otherwise, KERN_FAILURE is returned. 415 */ 416routine mach_port_get_srights( 417 task : ipc_space_t; 418 name : mach_port_name_t; 419 out srights : mach_port_rights_t); 420 421 422/* 423 * Returns information about an IPC space. 424 * This call is only valid on MACH_IPC_DEBUG kernels. 425 * Otherwise, KERN_FAILURE is returned. 426 */ 427routine mach_port_space_info( 428 task : ipc_space_t; 429 out space_info : ipc_info_space_t; 430 out table_info : ipc_info_name_array_t; 431 out tree_info : ipc_info_tree_name_array_t); 432 433/* 434 * Returns information about the dead-name requests 435 * registered with the named receive right. 436 * This call is only valid on MACH_IPC_DEBUG kernels. 437 * Otherwise, KERN_FAILURE is returned. 438 */ 439routine mach_port_dnrequest_info( 440 task : ipc_space_t; 441 name : mach_port_name_t; 442 out dnr_total : unsigned; /* total size of table */ 443 out dnr_used : unsigned); /* amount used */ 444 445/* 446 * Return the type and address of the kernel object 447 * that the given send/receive right represents. 448 * This call is only valid on MACH_IPC_DEBUG kernels. 449 * Otherwise, KERN_FAILURE is returned. 450 * 451 * This interface is DEPRECATED in favor of the new 452 * mach_port_kernel_object64() call (see below). 453 */ 454routine mach_port_kernel_object( 455 task : ipc_space_t; 456 name : mach_port_name_t; 457 out object_type : unsigned; 458 out object_addr : unsigned); 459 460 461/* 462 * Inserts the specified rights into the portset identified 463 * by the <task, pset> pair. The results of passing in the 464 * Poly argument via the supplied disposition must yield a 465 * receive right. 466 * 467 * If the <task,pset> pair does not represent a valid portset 468 * KERN_INVALID_RIGHT is returned. 469 * 470 * If the passed in name argument does not represent a receive 471 * right, KERN_INVALID_CAPABILITY will be returned. 472 * 473 * If the port represented by the receive right is already in 474 * the portset, KERN_ALREADY_IN_SET is returned. 475 */ 476routine mach_port_insert_member( 477 task : ipc_space_t; 478 name : mach_port_name_t; 479 pset : mach_port_name_t); 480 481/* 482 * Extracts the specified right from the named portset 483 * in the target task. 484 * the target task. The target task loses a user 485 * ref and the name may be available for recycling. 486 * msgt_name must be one of 487 * MACH_MSG_TYPE_MOVE_RECEIVE 488 * MACH_MSG_TYPE_COPY_SEND 489 * MACH_MSG_TYPE_MAKE_SEND 490 * MACH_MSG_TYPE_MOVE_SEND 491 * MACH_MSG_TYPE_MAKE_SEND_ONCE 492 * MACH_MSG_TYPE_MOVE_SEND_ONCE 493 */ 494 495routine mach_port_extract_member( 496 task : ipc_space_t; 497 name : mach_port_name_t; 498 pset : mach_port_name_t); 499 500/* 501 * Only valid for receive rights. 502 * Gets the context pointer for the port. 503 */ 504 505routine mach_port_get_context( 506 task : ipc_space_t; 507 name : mach_port_name_t; 508#ifdef LIBSYSCALL_INTERFACE 509 out context : mach_port_context_t 510#else 511 out context : mach_vm_address_t 512#endif 513 ); 514 515/* 516 * Only valid for receive rights. 517 * Sets the context pointer for the port. 518 */ 519 520routine mach_port_set_context( 521 task : ipc_space_t; 522 name : mach_port_name_t; 523#ifdef LIBSYSCALL_INTERFACE 524 context : mach_port_context_t 525#else 526 context : mach_vm_address_t 527#endif 528 ); 529 530/* 531 * Return the type and address of the kernel object 532 * that the given send/receive right represents. 533 * This call is only valid on MACH_IPC_DEBUG kernels. 534 * Otherwise, KERN_FAILURE is returned. 535 */ 536routine mach_port_kobject( 537 task : ipc_space_t; 538 name : mach_port_name_t; 539 out object_type : natural_t; 540 out object_addr : mach_vm_address_t); 541 542 543/* 544 * Constructs a right based on the options passed 545 * in. Also allows guarding the port as one of the 546 * options if the requested right is a receive 547 * right. 548 */ 549routine mach_port_construct( 550 task : ipc_space_t; 551 options : mach_port_options_ptr_t; 552#ifdef LIBSYSCALL_INTERFACE 553 context : mach_port_context_t; 554#else 555 context : uint64_t; 556#endif 557 out name : mach_port_name_t); 558 559/* 560 * Destroys a mach port using the guard provided 561 * for guarded ports. Also reduces the user ref 562 * count for send rights as specified by srdelta. 563 */ 564routine mach_port_destruct( 565 task : ipc_space_t; 566 name : mach_port_name_t; 567 srdelta : mach_port_delta_t; 568#ifdef LIBSYSCALL_INTERFACE 569 guard : mach_port_context_t 570#else 571 guard : uint64_t 572#endif 573 ); 574 575/* 576 * Guard an already existing port. Allows guarding 577 * receive rights only. Uses the context field in the 578 * port structure to store the guard. 579 */ 580routine mach_port_guard( 581 task : ipc_space_t; 582 name : mach_port_name_t; 583#ifdef LIBSYSCALL_INTERFACE 584 guard : mach_port_context_t; 585#else 586 guard : uint64_t; 587#endif 588 strict : boolean_t); 589 590/* 591 * Unguard a port guarded previously. For unguarded ports 592 * or incorrect guards passed in it raises an exception 593 * indicating guarding misbehavior. 594 */ 595routine mach_port_unguard( 596 task : ipc_space_t; 597 name : mach_port_name_t; 598#ifdef LIBSYSCALL_INTERFACE 599 guard : mach_port_context_t 600#else 601 guard : uint64_t 602#endif 603 ); 604 605/* vim: set ft=c : */ 606