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.  (Or removes it from any port set
 228  *      if after is MACH_PORT_NULL.)  If the port is already in
 229  *      a set, does an atomic move.
 230  */
 231
 232 routine mach_port_move_member(
 233                 task            : ipc_space_t;
 234                 member          : mach_port_name_t;
 235                 after           : mach_port_name_t);
 236
 237 /*
 238  *      Requests a notification from the kernel.  The request
 239  *      must supply the send-once right which is used for
 240  *      the notification.  If a send-once right was previously
 241  *      registered, it is returned.  The msg_id must be one of
 242  *              MACH_NOTIFY_PORT_DESTROYED (receive rights)
 243  *              MACH_NOTIFY_DEAD_NAME (send/receive/send-once rights)
 244  *              MACH_NOTIFY_NO_SENDERS (receive rights)
 245  *
 246  *      The sync value specifies whether a notification should
 247  *      get sent immediately, if appropriate.  The exact meaning
 248  *      depends on the notification:
 249  *              MACH_NOTIFY_PORT_DESTROYED: must be zero.
 250  *              MACH_NOTIFY_DEAD_NAME: if non-zero, then name can be dead,
 251  *                      and the notification gets sent immediately.
 252  *                      If zero, then name can't be dead.
 253  *              MACH_NOTIFY_NO_SENDERS: the notification gets sent
 254  *                      immediately if the current mscount is greater
 255  *                      than or equal to the sync value and there are no
 256  *                      extant send rights.
 257  */
 258
 259 routine mach_port_request_notification(
 260                 task            : ipc_space_t;
 261                 name            : mach_port_name_t;
 262                 msgid           : mach_msg_id_t;
 263                 sync            : mach_port_mscount_t;
 264                 notify          : mach_port_send_once_t;
 265         out     previous        : mach_port_move_send_once_t);
 266
 267 /*
 268  *      Inserts the specified rights into the target task,
 269  *      using the specified name.  If inserting send/receive
 270  *      rights and the task already has send/receive rights
 271  *      for the port, then the names must agree.  In any case,
 272  *      the task gains a user ref for the port.
 273  */
 274
 275 routine mach_port_insert_right(
 276                 task            : ipc_space_t;
 277                 name            : mach_port_name_t;
 278                 poly            : mach_port_poly_t);
 279
 280 /*
 281  *      Returns the specified right for the named port
 282  *      in the target task, extracting that right from
 283  *      the target task.  The target task loses a user
 284  *      ref and the name may be available for recycling.
 285  *      msgt_name must be one of
 286  *              MACH_MSG_TYPE_MOVE_RECEIVE
 287  *              MACH_MSG_TYPE_COPY_SEND
 288  *              MACH_MSG_TYPE_MAKE_SEND
 289  *              MACH_MSG_TYPE_MOVE_SEND
 290  *              MACH_MSG_TYPE_MAKE_SEND_ONCE
 291  *              MACH_MSG_TYPE_MOVE_SEND_ONCE
 292  */
 293
 294 routine mach_port_extract_right(
 295                 task            : ipc_space_t;
 296                 name            : mach_port_name_t;
 297                 msgt_name       : mach_msg_type_name_t;
 298         out     poly            : mach_port_poly_t);
 299
 300 /*
 301  *      Only valid for receive rights.
 302  *      Sets the sequence number for the port.
 303  */
 304
 305 routine mach_port_set_seqno(
 306                 task            : ipc_space_t;
 307                 name            : mach_port_name_t;
 308                 seqno           : mach_port_seqno_t);
 309
 310 /*
 311  *      Returns information about a port.
 312  */
 313
 314 routine mach_port_get_attributes(
 315                 task            : ipc_space_t;
 316                 name            : mach_port_name_t;
 317                 flavor          : mach_port_flavor_t;
 318         out     port_info_out   : mach_port_info_t, CountInOut);
 319
 320 /*
 321  *      Set attributes of a port
 322  */
 323
 324 routine mach_port_set_attributes(
 325                 task            : ipc_space_t;
 326                 name            : mach_port_name_t;
 327                 flavor          : mach_port_flavor_t;
 328                 port_info       : mach_port_info_t);
 329
 330
 331 /*
 332  *      Allocates the specified kind of object, qos version.
 333  *      The right must be
 334  *              MACH_PORT_RIGHT_RECEIVE
 335  *      Like port_allocate_name, but the kernel picks a name.
 336  *      It can use any name not associated with a right.
 337  */
 338
 339 routine mach_port_allocate_qos(
 340                 task            : ipc_space_t;
 341                 right           : mach_port_right_t;
 342         inout   qos             : mach_port_qos_t;
 343         out     name            : mach_port_name_t);
 344
 345
 346 /*
 347  *      Generic interface to allocation various kinds of ports.
 348  *      Should never be called directly by users (at least not
 349  *      unless they are exceedingly masochistic).
 350  */
 351
 352 routine mach_port_allocate_full(
 353                 task            : ipc_space_t;
 354                 right           : mach_port_right_t;
 355                 proto           : mach_port_t;
 356         inout   qos             : mach_port_qos_t;
 357         inout   name            : mach_port_name_t);
 358
 359
 360 /*
 361  *      Pre-expand task port name space.
 362  */
 363 routine task_set_port_space(
 364                 task            : ipc_space_t;
 365                 table_entries   : int);
 366
 367
 368 /*
 369  *      Returns the exact number of extant send rights
 370  *      for the given receive right.
 371  *      This call is only valid on MACH_IPC_DEBUG kernels.
 372  *      Otherwise, KERN_FAILURE is returned.
 373  */
 374 routine mach_port_get_srights(
 375                 task            : ipc_space_t;
 376                 name            : mach_port_name_t;
 377         out     srights         : mach_port_rights_t);
 378
 379
 380 /*
 381  *      Returns information about an IPC space.
 382  *      This call is only valid on MACH_IPC_DEBUG kernels.
 383  *      Otherwise, KERN_FAILURE is returned.
 384  */
 385 routine mach_port_space_info(
 386                 task            : ipc_space_t;
 387         out     space_info      : ipc_info_space_t;
 388         out     table_info      : ipc_info_name_array_t,
 389                                         Dealloc;
 390         out     tree_info       : ipc_info_tree_name_array_t,
 391                                         Dealloc);
 392
 393 /*
 394  *      Returns information about the dead-name requests
 395  *      registered with the named receive right.
 396  *      This call is only valid on MACH_IPC_DEBUG kernels.
 397  *      Otherwise, KERN_FAILURE is returned.
 398  */
 399 routine mach_port_dnrequest_info(
 400                 task            : ipc_space_t;
 401                 name            : mach_port_name_t;
 402         out     dnr_total       : unsigned;     /* total size of table */
 403         out     dnr_used        : unsigned);    /* amount used */
 404
 405 /*
 406  *      Return the type and address of the kernel object
 407  *      that the given send/receive right represents.
 408  *      This call is only valid on MACH_IPC_DEBUG kernels.
 409  *      Otherwise, KERN_FAILURE is returned.
 410  */
 411 routine mach_port_kernel_object(
 412                 task            : ipc_space_t;
 413                 name            : mach_port_name_t;
 414         out     object_type     : unsigned;
 415         out     object_addr     : vm_offset_t);
 416
 417
 418 /*
 419  *      Inserts the specified rights into the portset identified
 420  *      by the <task, pset> pair.  The results of passing in the
 421  *      Poly argument via the supplied disposition must yield a
 422  *      receive right.
 423  *
 424  *      If the <task,pset> pair does not represent a valid portset
 425  *      KERN_INVALID_RIGHT is returned.
 426  *
 427  *      If the passed in name argument does not represent a receive
 428  *      right, KERN_INVALID_CAPABILITY will be returned.
 429  *
 430  *      If the port represented by the receive right is already in
 431  *      the portset, KERN_ALREADY_IN_SET is returned.
 432  */
 433 routine mach_port_insert_member(
 434                 task            : ipc_space_t;
 435                 name            : mach_port_name_t;
 436                 pset            : mach_port_name_t);
 437
 438 /*
 439  *      Extracts the specified right from the named portset
 440  *      in the target task.
 441  *      the target task.  The target task loses a user
 442  *      ref and the name may be available for recycling.
 443  *      msgt_name must be one of
 444  *              MACH_MSG_TYPE_MOVE_RECEIVE
 445  *              MACH_MSG_TYPE_COPY_SEND
 446  *              MACH_MSG_TYPE_MAKE_SEND
 447  *              MACH_MSG_TYPE_MOVE_SEND
 448  *              MACH_MSG_TYPE_MAKE_SEND_ONCE
 449  *              MACH_MSG_TYPE_MOVE_SEND_ONCE
 450  */
 451
 452 routine mach_port_extract_member(
 453                 task            : ipc_space_t;
 454                 name            : mach_port_name_t;
 455                 pset            : mach_port_name_t);
 456