osfmk/mach/mach_port.defs

   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
  65 subsystem
  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
  85 routine 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
  96 routine 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
 110 routine 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
 127 routine 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
 142 routine 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
 154 routine 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
 166 routine 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
 184 routine 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
 205 routine 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  */
 227 routine 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  */
 240 routine 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
 250 routine mach_port_get_set_status(
 251                 task            : ipc_space_inspect_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
 263 routine 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
 301 routine 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
 317 routine 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
 336 routine 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
 347 routine 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
 356 routine mach_port_get_attributes(
 357                 task            : ipc_space_inspect_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
 366 routine 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
 381 routine 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
 394 routine 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  */
 405 routine 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  */
 416 routine 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  */
 427 routine mach_port_space_info(
 428                 task            : ipc_space_inspect_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  */
 439 routine 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  */
 454 routine mach_port_kernel_object(
 455                 task            : ipc_space_inspect_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  */
 476 routine 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
 495 routine 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
 505 routine mach_port_get_context(
 506                 task            : ipc_space_inspect_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
 520 routine 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  */
 536 routine mach_port_kobject(
 537                 task            : ipc_space_inspect_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  */
 549 routine 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  */
 564 routine 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  */
 580 routine 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  */
 595 routine 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 /*
 606  *      Returns basic information about an IPC space.
 607  *      This call is only valid on MACH_IPC_DEBUG kernels.
 608  *      Otherwise, KERN_FAILURE is returned.
 609  */
 610 routine mach_port_space_basic_info(
 611                 task            : ipc_space_inspect_t;
 612         out     basic_info      : ipc_info_space_basic_t);
 613
 614 /* vim: set ft=c : */