osfmk/mach/mach_port.defs

   1 /*
   2  * Copyright (c) 2000-2004 Apple Computer, Inc. All rights reserved.
   3  *
   4  * @APPLE_LICENSE_OSREFERENCE_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
  10  * License may not be used to create, or enable the creation or
  11  * redistribution of, unlawful or unlicensed copies of an Apple operating
  12  * system, or to circumvent, violate, or enable the circumvention or
  13  * violation of, any terms of an Apple operating system software license
  14  * agreement.
  15  *
  16  * Please obtain a copy of the License at
  17  * http://www.opensource.apple.com/apsl/ and read it before using this
  18  * file.
  19  *
  20  * The Original Code and all software distributed under the License are
  21  * distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER
  22  * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
  23  * INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
  24  * FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT.
  25  * Please see the License for the specific language governing rights and
  26  * limitations under the License.
  27  *
  28  * @APPLE_LICENSE_OSREFERENCE_HEADER_END@
  29  */
  30 /*
  31  * @OSF_FREE_COPYRIGHT@
  32  */
  33 /*
  34  * Mach Operating System
  35  * Copyright (c) 1991,1990,1989 Carnegie Mellon University
  36  * All Rights Reserved.
  37  *
  38  * Permission to use, copy, modify and distribute this software and its
  39  * documentation is hereby granted, provided that both the copyright
  40  * notice and this permission notice appear in all copies of the
  41  * software, derivative works or modified versions, and any portions
  42  * thereof, and that both notices appear in supporting documentation.
  43  *
  44  * CARNEGIE MELLON ALLOWS FREE USE OF THIS SOFTWARE IN ITS "AS IS"
  45  * CONDITION.  CARNEGIE MELLON DISCLAIMS ANY LIABILITY OF ANY KIND FOR
  46  * ANY DAMAGES WHATSOEVER RESULTING FROM THE USE OF THIS SOFTWARE.
  47  *
  48  * Carnegie Mellon requests users of this software to return to
  49  *
  50  *  Software Distribution Coordinator  or  Software.Distribution@CS.CMU.EDU
  51  *  School of Computer Science
  52  *  Carnegie Mellon University
  53  *  Pittsburgh PA 15213-3890
  54  *
  55  * any improvements or extensions that they make and grant Carnegie Mellon
  56  * the rights to redistribute these changes.
  57  */
  58 /*
  59  */
  60 /*
  61  *      File:   mach/mach_port.defs
  62  *      Author: Rich Draves
  63  *
  64  *      Exported kernel calls.
  65  */
  66
  67 subsystem
  68 #if     KERNEL_SERVER
  69           KernelServer
  70 #endif  /* KERNEL_SERVER */
  71           mach_port 3200;
  72
  73 #include <mach/std_types.defs>
  74 #include <mach/mach_types.defs>
  75 #include <mach_debug/mach_debug_types.defs>
  76
  77 /*
  78  *      Returns the set of port and port set names
  79  *      to which the target task has access, along with
  80  *      the type (set or port) for each name.
  81  */
  82
  83 routine mach_port_names(
  84                 task            : ipc_space_t;
  85         out     names           : mach_port_name_array_t;
  86         out     types           : mach_port_type_array_t);
  87
  88 /*
  89  *      Returns the type (set or port) for the port name
  90  *      within the target task.  Also indicates whether
  91  *      there is a dead-name request for the name.
  92  */
  93
  94 routine mach_port_type(
  95                 task            : ipc_space_t;
  96                 name            : mach_port_name_t;
  97         out     ptype           : mach_port_type_t);
  98
  99 /*
 100  *      Changes the name by which a port (or port set) is known to
 101  *      the target task.  The new name can't be in use.  The
 102  *      old name becomes available for recycling.
 103  */
 104
 105 routine mach_port_rename(
 106                 task            : ipc_space_t;
 107                 old_name        : mach_port_name_t;
 108                 new_name        : mach_port_name_t);
 109
 110 /*
 111  *      Allocates the specified kind of object, with the given name.
 112  *      The right must be one of
 113  *              MACH_PORT_RIGHT_RECEIVE
 114  *              MACH_PORT_RIGHT_PORT_SET
 115  *              MACH_PORT_RIGHT_DEAD_NAME
 116  *      New port sets are empty.  New ports don't have any
 117  *      send/send-once rights or queued messages.  The make-send
 118  *      count is zero and their queue limit is MACH_PORT_QLIMIT_DEFAULT.
 119  *      New sets, ports, and dead names have one user reference.
 120  */
 121
 122 routine mach_port_allocate_name(
 123                 task            : ipc_space_t;
 124                 right           : mach_port_right_t;
 125                 name            : mach_port_name_t);
 126
 127 /*
 128  *      Allocates the specified kind of object.
 129  *      The right must be one of
 130  *              MACH_PORT_RIGHT_RECEIVE
 131  *              MACH_PORT_RIGHT_PORT_SET
 132  *              MACH_PORT_RIGHT_DEAD_NAME
 133  *      Like port_allocate_name, but the kernel picks a name.
 134  *      It can use any name not associated with a right.
 135  */
 136
 137 routine mach_port_allocate(
 138                 task            : ipc_space_t;
 139                 right           : mach_port_right_t;
 140         out     name            : mach_port_name_t);
 141
 142 /*
 143  *      Destroys all rights associated with the name and makes it
 144  *      available for recycling immediately.  The name can be a
 145  *      port (possibly with multiple user refs), a port set, or
 146  *      a dead name (again, with multiple user refs).
 147  */
 148
 149 routine mach_port_destroy(
 150                 task            : ipc_space_t;
 151                 name            : mach_port_name_t);
 152
 153 /*
 154  *      Releases one send/send-once/dead-name user ref.
 155  *      Just like mach_port_mod_refs -1, but deduces the
 156  *      correct type of right.  This allows a user task
 157  *      to release a ref for a port without worrying
 158  *      about whether the port has died or not.
 159  */
 160
 161 routine mach_port_deallocate(
 162                 task            : ipc_space_t;
 163                 name            : mach_port_name_t);
 164
 165 /*
 166  *      A port set always has one user ref.
 167  *      A send-once right always has one user ref.
 168  *      A dead name always has one or more user refs.
 169  *      A send right always has one or more user refs.
 170  *      A receive right always has one user ref.
 171  *      The right must be one of
 172  *              MACH_PORT_RIGHT_RECEIVE
 173  *              MACH_PORT_RIGHT_PORT_SET
 174  *              MACH_PORT_RIGHT_DEAD_NAME
 175  *              MACH_PORT_RIGHT_SEND
 176  *              MACH_PORT_RIGHT_SEND_ONCE
 177  */
 178
 179 routine mach_port_get_refs(
 180                 task            : ipc_space_t;
 181                 name            : mach_port_name_t;
 182                 right           : mach_port_right_t;
 183         out     refs            : mach_port_urefs_t);
 184
 185 /*
 186  *      The delta is a signed change to the task's
 187  *      user ref count for the right.  Only dead names
 188  *      and send rights can have a positive delta.
 189  *      The resulting user ref count can't be negative.
 190  *      If it is zero, the right is deallocated.
 191  *      If the name isn't a composite right, it becomes
 192  *      available for recycling.  The right must be one of
 193  *              MACH_PORT_RIGHT_RECEIVE
 194  *              MACH_PORT_RIGHT_PORT_SET
 195  *              MACH_PORT_RIGHT_DEAD_NAME
 196  *              MACH_PORT_RIGHT_SEND
 197  *              MACH_PORT_RIGHT_SEND_ONCE
 198  */
 199
 200 routine mach_port_mod_refs(
 201                 task            : ipc_space_t;
 202                 name            : mach_port_name_t;
 203                 right           : mach_port_right_t;
 204                 delta           : mach_port_delta_t);
 205
 206 skip;
 207
 208 /*
 209  *      Only valid for receive rights.
 210  *      Sets the make-send count for the port.
 211  */
 212 routine mach_port_set_mscount(
 213                 task            : ipc_space_t;
 214                 name            : mach_port_name_t;
 215                 mscount         : mach_port_mscount_t);
 216
 217 /*
 218  *      Only valid for port sets.  Returns a list of
 219  *      the members.
 220  */
 221
 222 routine mach_port_get_set_status(
 223                 task            : ipc_space_t;
 224                 name            : mach_port_name_t;
 225         out     members         : mach_port_name_array_t);
 226
 227 /*
 228  *      Puts the member port (the task must have receive rights)
 229  *      into the after port set.  (Or removes it from any port set
 230  *      if after is MACH_PORT_NULL.)  If the port is already in
 231  *      a set, does an atomic move.
 232  */
 233
 234 routine mach_port_move_member(
 235                 task            : ipc_space_t;
 236                 member          : mach_port_name_t;
 237                 after           : mach_port_name_t);
 238
 239 /*
 240  *      Requests a notification from the kernel.  The request
 241  *      must supply the send-once right which is used for
 242  *      the notification.  If a send-once right was previously
 243  *      registered, it is returned.  The msg_id must be one of
 244  *              MACH_NOTIFY_PORT_DESTROYED (receive rights)
 245  *              MACH_NOTIFY_DEAD_NAME (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_NO_SENDERS: the notification gets sent
 256  *                      immediately if the current mscount is greater
 257  *                      than or equal to the sync value and there are no
 258  *                      extant send rights.
 259  */
 260
 261 routine mach_port_request_notification(
 262                 task            : ipc_space_t;
 263                 name            : mach_port_name_t;
 264                 msgid           : mach_msg_id_t;
 265                 sync            : mach_port_mscount_t;
 266                 notify          : mach_port_send_once_t;
 267         out     previous        : mach_port_move_send_once_t);
 268
 269 /*
 270  *      Inserts the specified rights into the target task,
 271  *      using the specified name.  If inserting send/receive
 272  *      rights and the task already has send/receive rights
 273  *      for the port, then the names must agree.  In any case,
 274  *      the task gains a user ref for the port.
 275  */
 276
 277 routine mach_port_insert_right(
 278                 task            : ipc_space_t;
 279                 name            : mach_port_name_t;
 280                 poly            : mach_port_poly_t);
 281
 282 /*
 283  *      Returns the specified right for the named port
 284  *      in the target task, extracting that right from
 285  *      the target task.  The target task loses a user
 286  *      ref and the name may be available for recycling.
 287  *      msgt_name must be one of
 288  *              MACH_MSG_TYPE_MOVE_RECEIVE
 289  *              MACH_MSG_TYPE_COPY_SEND
 290  *              MACH_MSG_TYPE_MAKE_SEND
 291  *              MACH_MSG_TYPE_MOVE_SEND
 292  *              MACH_MSG_TYPE_MAKE_SEND_ONCE
 293  *              MACH_MSG_TYPE_MOVE_SEND_ONCE
 294  */
 295
 296 routine mach_port_extract_right(
 297                 task            : ipc_space_t;
 298                 name            : mach_port_name_t;
 299                 msgt_name       : mach_msg_type_name_t;
 300         out     poly            : mach_port_poly_t);
 301
 302 /*
 303  *      Only valid for receive rights.
 304  *      Sets the sequence number for the port.
 305  */
 306
 307 routine mach_port_set_seqno(
 308                 task            : ipc_space_t;
 309                 name            : mach_port_name_t;
 310                 seqno           : mach_port_seqno_t);
 311
 312 /*
 313  *      Returns information about a port.
 314  */
 315
 316 routine mach_port_get_attributes(
 317                 task            : ipc_space_t;
 318                 name            : mach_port_name_t;
 319                 flavor          : mach_port_flavor_t;
 320         out     port_info_out   : mach_port_info_t, CountInOut);
 321
 322 /*
 323  *      Set attributes of a port
 324  */
 325
 326 routine mach_port_set_attributes(
 327                 task            : ipc_space_t;
 328                 name            : mach_port_name_t;
 329                 flavor          : mach_port_flavor_t;
 330                 port_info       : mach_port_info_t);
 331
 332
 333 /*
 334  *      Allocates the specified kind of object, qos version.
 335  *      The right must be
 336  *              MACH_PORT_RIGHT_RECEIVE
 337  *      Like port_allocate_name, but the kernel picks a name.
 338  *      It can use any name not associated with a right.
 339  */
 340
 341 routine mach_port_allocate_qos(
 342                 task            : ipc_space_t;
 343                 right           : mach_port_right_t;
 344         inout   qos             : mach_port_qos_t;
 345         out     name            : mach_port_name_t);
 346
 347
 348 /*
 349  *      Generic interface to allocation various kinds of ports.
 350  *      Should never be called directly by users (at least not
 351  *      unless they are exceedingly masochistic).
 352  */
 353
 354 routine mach_port_allocate_full(
 355                 task            : ipc_space_t;
 356                 right           : mach_port_right_t;
 357                 proto           : mach_port_t;
 358         inout   qos             : mach_port_qos_t;
 359         inout   name            : mach_port_name_t);
 360
 361
 362 /*
 363  *      Pre-expand task port name space.
 364  */
 365 routine task_set_port_space(
 366                 task            : ipc_space_t;
 367                 table_entries   : int);
 368
 369
 370 /*
 371  *      Returns the exact number of extant send rights
 372  *      for the given receive right.
 373  *      This call is only valid on MACH_IPC_DEBUG kernels.
 374  *      Otherwise, KERN_FAILURE is returned.
 375  */
 376 routine mach_port_get_srights(
 377                 task            : ipc_space_t;
 378                 name            : mach_port_name_t;
 379         out     srights         : mach_port_rights_t);
 380
 381
 382 /*
 383  *      Returns information about an IPC space.
 384  *      This call is only valid on MACH_IPC_DEBUG kernels.
 385  *      Otherwise, KERN_FAILURE is returned.
 386  */
 387 routine mach_port_space_info(
 388                 task            : ipc_space_t;
 389         out     space_info      : ipc_info_space_t;
 390         out     table_info      : ipc_info_name_array_t,
 391                                         Dealloc;
 392         out     tree_info       : ipc_info_tree_name_array_t,
 393                                         Dealloc);
 394
 395 /*
 396  *      Returns information about the dead-name requests
 397  *      registered with the named receive right.
 398  *      This call is only valid on MACH_IPC_DEBUG kernels.
 399  *      Otherwise, KERN_FAILURE is returned.
 400  */
 401 routine mach_port_dnrequest_info(
 402                 task            : ipc_space_t;
 403                 name            : mach_port_name_t;
 404         out     dnr_total       : unsigned;     /* total size of table */
 405         out     dnr_used        : unsigned);    /* amount used */
 406
 407 /*
 408  *      Return the type and address of the kernel object
 409  *      that the given send/receive right represents.
 410  *      This call is only valid on MACH_IPC_DEBUG kernels.
 411  *      Otherwise, KERN_FAILURE is returned.
 412  */
 413 routine mach_port_kernel_object(
 414                 task            : ipc_space_t;
 415                 name            : mach_port_name_t;
 416         out     object_type     : unsigned;
 417         out     object_addr     : vm_offset_t);
 418
 419
 420 /*
 421  *      Inserts the specified rights into the portset identified
 422  *      by the <task, pset> pair.  The results of passing in the
 423  *      Poly argument via the supplied disposition must yield a
 424  *      receive right.
 425  *
 426  *      If the <task,pset> pair does not represent a valid portset
 427  *      KERN_INVALID_RIGHT is returned.
 428  *
 429  *      If the passed in name argument does not represent a receive
 430  *      right, KERN_INVALID_CAPABILITY will be returned.
 431  *
 432  *      If the port represented by the receive right is already in
 433  *      the portset, KERN_ALREADY_IN_SET is returned.
 434  */
 435 routine mach_port_insert_member(
 436                 task            : ipc_space_t;
 437                 name            : mach_port_name_t;
 438                 pset            : mach_port_name_t);
 439
 440 /*
 441  *      Extracts the specified right from the named portset
 442  *      in the target task.
 443  *      the target task.  The target task loses a user
 444  *      ref and the name may be available for recycling.
 445  *      msgt_name must be one of
 446  *              MACH_MSG_TYPE_MOVE_RECEIVE
 447  *              MACH_MSG_TYPE_COPY_SEND
 448  *              MACH_MSG_TYPE_MAKE_SEND
 449  *              MACH_MSG_TYPE_MOVE_SEND
 450  *              MACH_MSG_TYPE_MAKE_SEND_ONCE
 451  *              MACH_MSG_TYPE_MOVE_SEND_ONCE
 452  */
 453
 454 routine mach_port_extract_member(
 455                 task            : ipc_space_t;
 456                 name            : mach_port_name_t;
 457                 pset            : mach_port_name_t);
 458