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