osfmk/mach/mach_port.defs

   1 /*
   2  * Copyright (c) 2000 Apple Computer, Inc. All rights reserved.
   3  *
   4  * @APPLE_LICENSE_HEADER_START@
   5  *
   6  * The contents of this file constitute Original Code as defined in and
   7  * are subject to the Apple Public Source License Version 1.1 (the
   8  * "License").  You may not use this file except in compliance with the
   9  * License.  Please obtain a copy of the License at
  10  * http://www.apple.com/publicsource and read it before using this file.
  11  *
  12  * This Original Code and all software distributed under the License are
  13  * distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY KIND, EITHER
  14  * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
  15  * INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
  16  * FITNESS FOR A PARTICULAR PURPOSE OR NON-INFRINGEMENT.  Please see the
  17  * License for the specific language governing rights and limitations
  18  * under the License.
  19  *
  20  * @APPLE_LICENSE_HEADER_END@
  21  */
  22 /*
  23  * @OSF_FREE_COPYRIGHT@
  24  */
  25 /*
  26  * Mach Operating System
  27  * Copyright (c) 1991,1990,1989 Carnegie Mellon University
  28  * All Rights Reserved.
  29  *
  30  * Permission to use, copy, modify and distribute this software and its
  31  * documentation is hereby granted, provided that both the copyright
  32  * notice and this permission notice appear in all copies of the
  33  * software, derivative works or modified versions, and any portions
  34  * thereof, and that both notices appear in supporting documentation.
  35  *
  36  * CARNEGIE MELLON ALLOWS FREE USE OF THIS SOFTWARE IN ITS "AS IS"
  37  * CONDITION.  CARNEGIE MELLON DISCLAIMS ANY LIABILITY OF ANY KIND FOR
  38  * ANY DAMAGES WHATSOEVER RESULTING FROM THE USE OF THIS SOFTWARE.
  39  *
  40  * Carnegie Mellon requests users of this software to return to
  41  *
  42  *  Software Distribution Coordinator  or  Software.Distribution@CS.CMU.EDU
  43  *  School of Computer Science
  44  *  Carnegie Mellon University
  45  *  Pittsburgh PA 15213-3890
  46  *
  47  * any improvements or extensions that they make and grant Carnegie Mellon
  48  * the rights to redistribute these changes.
  49  */
  50 /*
  51  */
  52 /*
  53  *      File:   mach/mach_port.defs
  54  *      Author: Rich Draves
  55  *
  56  *      Exported kernel calls.
  57  */
  58
  59 subsystem
  60 #if     KERNEL_SERVER
  61           KernelServer
  62 #endif  KERNEL_SERVER
  63           mach_port 3200;
  64
  65 #include <mach/std_types.defs>
  66 #include <mach/mach_types.defs>
  67 #include <mach_debug/mach_debug_types.defs>
  68
  69 /*
  70  *      Returns the set of port and port set names
  71  *      to which the target task has access, along with
  72  *      the type (set or port) for each name.
  73  */
  74
  75 routine mach_port_names(
  76                 task            : ipc_space_t;
  77         out     names           : mach_port_name_array_t;
  78         out     types           : mach_port_type_array_t);
  79
  80 /*
  81  *      Returns the type (set or port) for the port name
  82  *      within the target task.  Also indicates whether
  83  *      there is a dead-name request for the name.
  84  */
  85
  86 routine mach_port_type(
  87                 task            : ipc_space_t;
  88                 name            : mach_port_name_t;
  89         out     ptype           : mach_port_type_t);
  90
  91 /*
  92  *      Changes the name by which a port (or port set) is known to
  93  *      the target task.  The new name can't be in use.  The
  94  *      old name becomes available for recycling.
  95  */
  96
  97 routine mach_port_rename(
  98                 task            : ipc_space_t;
  99                 old_name        : mach_port_name_t;
 100                 new_name        : mach_port_name_t);
 101
 102 /*
 103  *      Allocates the specified kind of object, with the given name.
 104  *      The right must be one of
 105  *              MACH_PORT_RIGHT_RECEIVE
 106  *              MACH_PORT_RIGHT_PORT_SET
 107  *              MACH_PORT_RIGHT_DEAD_NAME
 108  *      New port sets are empty.  New ports don't have any
 109  *      send/send-once rights or queued messages.  The make-send
 110  *      count is zero and their queue limit is MACH_PORT_QLIMIT_DEFAULT.
 111  *      New sets, ports, and dead names have one user reference.
 112  */
 113
 114 routine mach_port_allocate_name(
 115                 task            : ipc_space_t;
 116                 right           : mach_port_right_t;
 117                 name            : mach_port_name_t);
 118
 119 /*
 120  *      Allocates the specified kind of object.
 121  *      The right must be one of
 122  *              MACH_PORT_RIGHT_RECEIVE
 123  *              MACH_PORT_RIGHT_PORT_SET
 124  *              MACH_PORT_RIGHT_DEAD_NAME
 125  *      Like port_allocate_name, but the kernel picks a name.
 126  *      It can use any name not associated with a right.
 127  */
 128
 129 routine mach_port_allocate(
 130                 task            : ipc_space_t;
 131                 right           : mach_port_right_t;
 132         out     name            : mach_port_name_t);
 133
 134 /*
 135  *      Destroys all rights associated with the name and makes it
 136  *      available for recycling immediately.  The name can be a
 137  *      port (possibly with multiple user refs), a port set, or
 138  *      a dead name (again, with multiple user refs).
 139  */
 140
 141 routine mach_port_destroy(
 142                 task            : ipc_space_t;
 143                 name            : mach_port_name_t);
 144
 145 /*
 146  *      Releases one send/send-once/dead-name user ref.
 147  *      Just like mach_port_mod_refs -1, but deduces the
 148  *      correct type of right.  This allows a user task
 149  *      to release a ref for a port without worrying
 150  *      about whether the port has died or not.
 151  */
 152
 153 routine mach_port_deallocate(
 154                 task            : ipc_space_t;
 155                 name            : mach_port_name_t);
 156
 157 /*
 158  *      A port set always has one user ref.
 159  *      A send-once right always has one user ref.
 160  *      A dead name always has one or more user refs.
 161  *      A send right always has one or more user refs.
 162  *      A receive right always has one user ref.
 163  *      The right must be one of
 164  *              MACH_PORT_RIGHT_RECEIVE
 165  *              MACH_PORT_RIGHT_PORT_SET
 166  *              MACH_PORT_RIGHT_DEAD_NAME
 167  *              MACH_PORT_RIGHT_SEND
 168  *              MACH_PORT_RIGHT_SEND_ONCE
 169  */
 170
 171 routine mach_port_get_refs(
 172                 task            : ipc_space_t;
 173                 name            : mach_port_name_t;
 174                 right           : mach_port_right_t;
 175         out     refs            : mach_port_urefs_t);
 176
 177 /*
 178  *      The delta is a signed change to the task's
 179  *      user ref count for the right.  Only dead names
 180  *      and send rights can have a positive delta.
 181  *      The resulting user ref count can't be negative.
 182  *      If it is zero, the right is deallocated.
 183  *      If the name isn't a composite right, it becomes
 184  *      available for recycling.  The right must be one of
 185  *              MACH_PORT_RIGHT_RECEIVE
 186  *              MACH_PORT_RIGHT_PORT_SET
 187  *              MACH_PORT_RIGHT_DEAD_NAME
 188  *              MACH_PORT_RIGHT_SEND
 189  *              MACH_PORT_RIGHT_SEND_ONCE
 190  */
 191
 192 routine mach_port_mod_refs(
 193                 task            : ipc_space_t;
 194                 name            : mach_port_name_t;
 195                 right           : mach_port_right_t;
 196                 delta           : mach_port_delta_t);
 197
 198 /*
 199  *      Allocates a new receive right, and associates it with the
 200  *      specified RPC subsystem.
 201  */
 202 routine mach_port_allocate_subsystem(
 203                 task            : ipc_space_t;
 204                 subsys          : subsystem_t;
 205         out     name            : mach_port_name_t);
 206
 207 /*
 208  *      Only valid for receive rights.
 209  *      Sets the make-send count for the port.
 210  */
 211 routine mach_port_set_mscount(
 212                 task            : ipc_space_t;
 213                 name            : mach_port_name_t;
 214                 mscount         : mach_port_mscount_t);
 215
 216 /*
 217  *      Only valid for port sets.  Returns a list of
 218  *      the members.
 219  */
 220
 221 routine mach_port_get_set_status(
 222                 task            : ipc_space_t;
 223                 name            : mach_port_name_t;
 224         out     members         : mach_port_name_array_t);
 225
 226 /*
 227  *      Puts the member port (the task must have receive rights)
 228  *      into the after port set.  (Or removes it from any port set
 229  *      if after is MACH_PORT_NULL.)  If the port is already in
 230  *      a set, does an atomic move.
 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 msg_id must be one of
 243  *              MACH_NOTIFY_PORT_DESTROYED (receive rights)
 244  *              MACH_NOTIFY_DEAD_NAME (send/receive/send-once rights)
 245  *              MACH_NOTIFY_NO_SENDERS (receive rights)
 246  *
 247  *      The sync value specifies whether a notification should
 248  *      get sent immediately, if appropriate.  The exact meaning
 249  *      depends on the notification:
 250  *              MACH_NOTIFY_PORT_DESTROYED: must be zero.
 251  *              MACH_NOTIFY_DEAD_NAME: if non-zero, then name can be dead,
 252  *                      and the notification gets sent immediately.
 253  *                      If zero, then name can't be dead.
 254  *              MACH_NOTIFY_NO_SENDERS: the notification gets sent
 255  *                      immediately if the current mscount is greater
 256  *                      than or equal to the sync value and there are no
 257  *                      extant send rights.
 258  */
 259
 260 routine mach_port_request_notification(
 261                 task            : ipc_space_t;
 262                 name            : mach_port_name_t;
 263                 msgid           : mach_msg_id_t;
 264                 sync            : mach_port_mscount_t;
 265                 notify          : mach_port_send_once_t;
 266         out     previous        : mach_port_send_once_t);
 267
 268 /*
 269  *      Inserts the specified rights into the target task,
 270  *      using the specified name.  If inserting send/receive
 271  *      rights and the task already has send/receive rights
 272  *      for the port, then the names must agree.  In any case,
 273  *      the task gains a user ref for the port.
 274  */
 275
 276 routine mach_port_insert_right(
 277                 task            : ipc_space_t;
 278                 name            : mach_port_name_t;
 279                 poly            : mach_port_poly_t);
 280
 281 /*
 282  *      Returns the specified right for the named port
 283  *      in the target task, extracting that right from
 284  *      the target task.  The target task loses a user
 285  *      ref and the name may be available for recycling.
 286  *      msgt_name must be one of
 287  *              MACH_MSG_TYPE_MOVE_RECEIVE
 288  *              MACH_MSG_TYPE_COPY_SEND
 289  *              MACH_MSG_TYPE_MAKE_SEND
 290  *              MACH_MSG_TYPE_MOVE_SEND
 291  *              MACH_MSG_TYPE_MAKE_SEND_ONCE
 292  *              MACH_MSG_TYPE_MOVE_SEND_ONCE
 293  */
 294
 295 routine mach_port_extract_right(
 296                 task            : ipc_space_t;
 297                 name            : mach_port_name_t;
 298                 msgt_name       : mach_msg_type_name_t;
 299         out     poly            : mach_port_poly_t);
 300
 301 /*
 302  *      Only valid for receive rights.
 303  *      Sets the sequence number for the port.
 304  */
 305
 306 routine mach_port_set_seqno(
 307                 task            : ipc_space_t;
 308                 name            : mach_port_name_t;
 309                 seqno           : mach_port_seqno_t);
 310
 311 /*
 312  *      Returns information about a port.
 313  */
 314
 315 routine mach_port_get_attributes(
 316                 task            : ipc_space_t;
 317                 name            : mach_port_name_t;
 318                 flavor          : mach_port_flavor_t;
 319         out     port_info_out   : mach_port_info_t, CountInOut);
 320
 321 /*
 322  *      Set attributes of a port
 323  */
 324
 325 routine mach_port_set_attributes(
 326                 task            : ipc_space_t;
 327                 name            : mach_port_name_t;
 328                 flavor          : mach_port_flavor_t;
 329                 port_info       : mach_port_info_t);
 330
 331
 332 /*
 333  *      Allocates the specified kind of object, qos version.
 334  *      The right must be
 335  *              MACH_PORT_RIGHT_RECEIVE
 336  *      Like port_allocate_name, but the kernel picks a name.
 337  *      It can use any name not associated with a right.
 338  */
 339
 340 routine mach_port_allocate_qos(
 341                 task            : ipc_space_t;
 342                 right           : mach_port_right_t;
 343         inout   qos             : mach_port_qos_t;
 344         out     name            : mach_port_name_t);
 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                 subs            : subsystem_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     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     total           : unsigned;     /* total size of table */
 403         out     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