osfmk/mach/mach_port.defs

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