osfmk/mach/mach_port.defs

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