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 skip;
 212
 213 /*
 214  *      Only valid for receive rights.
 215  *      Sets the make-send count for the port.
 216  */
 217 routine 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
 227 routine 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
 240 routine 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
 278 routine 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
 294 routine 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
 313 routine 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
 324 routine 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
 333 routine 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
 343 routine 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
 358 routine 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
 371 routine 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  */
 382 routine 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  */
 393 routine 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  */
 404 routine 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  */
 416 routine 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  */
 431 routine 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  */
 453 routine 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
 472 routine 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
 482 routine 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
 497 routine 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  */
 513 routine 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 : */