osfmk/mach/port.h

   1 /*
   2  * Copyright (c) 2000-2005 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_COPYRIGHT@
  32  */
  33 /*
  34  * Mach Operating System
  35  * Copyright (c) 1991,1990,1989,1988,1987 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/port.h
  62  *
  63  *      Definition of a Mach port
  64  *
  65  *      Mach ports are the endpoints to Mach-implemented communications
  66  *      channels (usually uni-directional message queues, but other types
  67  *      also exist).
  68  *
  69  *      Unique collections of these endpoints are maintained for each
  70  *      Mach task.  Each Mach port in the task's collection is given a
  71  *      [task-local] name to identify it - and the the various "rights"
  72  *      held by the task for that specific endpoint.
  73  *
  74  *      This header defines the types used to identify these Mach ports
  75  *      and the various rights associated with them.  For more info see:
  76  *
  77  *      <mach/mach_port.h> - manipulation of port rights in a given space
  78  *      <mach/message.h> - message queue [and port right passing] mechanism
  79  *
  80  */
  81
  82 #ifndef _MACH_PORT_H_
  83 #define _MACH_PORT_H_
  84
  85 #include <stdint.h>
  86 #include <mach/boolean.h>
  87 #include <mach/machine/vm_types.h>
  88
  89 /*
  90  *      mach_port_name_t - the local identity for a Mach port
  91  *
  92  *      The name is Mach port namespace specific.  It is used to
  93  *      identify the rights held for that port by the task whose
  94  *      namespace is implied [or specifically provided].
  95  *
  96  *      Use of this type usually implies just a name - no rights.
  97  *      See mach_port_t for a type that implies a "named right."
  98  *
  99  */
 100
 101 typedef natural_t mach_port_name_t;
 102 typedef mach_port_name_t *mach_port_name_array_t;
 103
 104 #ifdef  KERNEL
 105
 106 /*
 107  *      mach_port_t - a named port right
 108  *
 109  *      In the kernel, "rights" are represented [named] by pointers to
 110  *      the ipc port object in question. There is no port namespace for the
 111  *      rights to be collected.
 112  *
 113  *      Actually, there is namespace for the kernel task.  But most kernel
 114  *      code - including, but not limited to, Mach IPC code - lives in the
 115  *      limbo between the current user-level task and the "next" task. Very
 116  *      little of the kernel code runs in full kernel task context.  So very
 117  *      little of it gets to use the kernel task's port name space.
 118  *
 119  *      Because of this implementation approach, all in-kernel rights for
 120  *      a given port coalesce [have the same name/pointer].  The actual
 121  *      references are counted in the port itself.  It is up to the kernel
 122  *      code in question to "just remember" how many [and what type of]
 123  *      rights it holds and handle them appropriately.
 124  *
 125  */
 126
 127 #ifndef MACH_KERNEL_PRIVATE
 128 /*
 129  *      For kernel code that resides outside of Mach proper, we opaque the
 130  *      port structure definition.
 131  */
 132 struct ipc_port ;
 133
 134 #endif  /* MACH_KERNEL_PRIVATE */
 135
 136 typedef struct ipc_port         *ipc_port_t;
 137
 138 #define IPC_PORT_NULL           ((ipc_port_t) 0)
 139 #define IPC_PORT_DEAD           ((ipc_port_t)~0)
 140 #define IPC_PORT_VALID(port) \
 141         ((port) != IPC_PORT_NULL && (port) != IPC_PORT_DEAD)
 142
 143 typedef ipc_port_t              mach_port_t;
 144
 145 #else   /* KERNEL */
 146
 147 /*
 148  *      mach_port_t - a named port right
 149  *
 150  *      In user-space, "rights" are represented by the name of the
 151  *      right in the Mach port namespace.  Even so, this type is
 152  *      presented as a unique one to more clearly denote the presence
 153  *      of a right coming along with the name.
 154  *
 155  *      Often, various rights for a port held in a single name space
 156  *      will coalesce and are, therefore, be identified by a single name
 157  *      [this is the case for send and receive rights].  But not
 158  *      always [send-once rights currently get a unique name for
 159  *      each right].
 160  *
 161  */
 162
 163 #ifndef _MACH_PORT_T
 164 #define _MACH_PORT_T
 165 typedef mach_port_name_t                mach_port_t;
 166 #endif
 167
 168 #endif  /* KERNEL */
 169
 170 typedef mach_port_t                     *mach_port_array_t;
 171
 172 /*
 173  *  MACH_PORT_NULL is a legal value that can be carried in messages.
 174  *  It indicates the absence of any port or port rights.  (A port
 175  *  argument keeps the message from being "simple", even if the
 176  *  value is MACH_PORT_NULL.)  The value MACH_PORT_DEAD is also a legal
 177  *  value that can be carried in messages.  It indicates
 178  *  that a port right was present, but it died.
 179  */
 180
 181 #define MACH_PORT_NULL          0  /* intentional loose typing */
 182 #define MACH_PORT_DEAD          ((mach_port_name_t) ~0)
 183 #define MACH_PORT_VALID(name)                           \
 184                 (((name) != MACH_PORT_NULL) &&          \
 185                  ((name) != MACH_PORT_DEAD))
 186
 187
 188 /*
 189  *      For kernel-selected [assigned] port names, the name is
 190  *      comprised of two parts: a generation number and an index.
 191  *      This approach keeps the exact same name from being generated
 192  *      and reused too quickly [to catch right/reference counting bugs].
 193  *      The dividing line between the constituent parts is exposed so
 194  *      that efficient "mach_port_name_t to data structure pointer"
 195  *      conversion implementation can be made.  But it is possible
 196  *      for user-level code to assign their own names to Mach ports.
 197  *      These are not required to participate in this algorithm.  So
 198  *      care should be taken before "assuming" this model.
 199  *
 200  */
 201
 202 #ifndef NO_PORT_GEN
 203
 204 #define MACH_PORT_INDEX(name)           ((name) >> 8)
 205 #define MACH_PORT_GEN(name)             (((name) & 0xff) << 24)
 206 #define MACH_PORT_MAKE(index, gen)      \
 207                 (((index) << 8) | (gen) >> 24)
 208
 209 #else   /* NO_PORT_GEN */
 210
 211 #define MACH_PORT_INDEX(name)           (name)
 212 #define MACH_PORT_GEN(name)             (0)
 213 #define MACH_PORT_MAKE(index, gen)      (index)
 214
 215 #endif  /* NO_PORT_GEN */
 216
 217
 218 /*
 219  *  These are the different rights a task may have for a port.
 220  *  The MACH_PORT_RIGHT_* definitions are used as arguments
 221  *  to mach_port_allocate, mach_port_get_refs, etc, to specify
 222  *  a particular right to act upon.  The mach_port_names and
 223  *  mach_port_type calls return bitmasks using the MACH_PORT_TYPE_*
 224  *  definitions.  This is because a single name may denote
 225  *  multiple rights.
 226  */
 227
 228 typedef natural_t mach_port_right_t;
 229
 230 #define MACH_PORT_RIGHT_SEND            ((mach_port_right_t) 0)
 231 #define MACH_PORT_RIGHT_RECEIVE         ((mach_port_right_t) 1)
 232 #define MACH_PORT_RIGHT_SEND_ONCE       ((mach_port_right_t) 2)
 233 #define MACH_PORT_RIGHT_PORT_SET        ((mach_port_right_t) 3)
 234 #define MACH_PORT_RIGHT_DEAD_NAME       ((mach_port_right_t) 4)
 235 #define MACH_PORT_RIGHT_NUMBER          ((mach_port_right_t) 5)
 236
 237 typedef natural_t mach_port_type_t;
 238 typedef mach_port_type_t *mach_port_type_array_t;
 239
 240 #define MACH_PORT_TYPE(right)                                           \
 241                 ((mach_port_type_t)(((mach_port_type_t) 1)              \
 242                 << ((right) + ((mach_port_right_t) 16))))
 243 #define MACH_PORT_TYPE_NONE         ((mach_port_type_t) 0L)
 244 #define MACH_PORT_TYPE_SEND         MACH_PORT_TYPE(MACH_PORT_RIGHT_SEND)
 245 #define MACH_PORT_TYPE_RECEIVE      MACH_PORT_TYPE(MACH_PORT_RIGHT_RECEIVE)
 246 #define MACH_PORT_TYPE_SEND_ONCE    MACH_PORT_TYPE(MACH_PORT_RIGHT_SEND_ONCE)
 247 #define MACH_PORT_TYPE_PORT_SET     MACH_PORT_TYPE(MACH_PORT_RIGHT_PORT_SET)
 248 #define MACH_PORT_TYPE_DEAD_NAME    MACH_PORT_TYPE(MACH_PORT_RIGHT_DEAD_NAME)
 249
 250 /* Convenient combinations. */
 251
 252 #define MACH_PORT_TYPE_SEND_RECEIVE                                     \
 253                 (MACH_PORT_TYPE_SEND|MACH_PORT_TYPE_RECEIVE)
 254 #define MACH_PORT_TYPE_SEND_RIGHTS                                      \
 255                 (MACH_PORT_TYPE_SEND|MACH_PORT_TYPE_SEND_ONCE)
 256 #define MACH_PORT_TYPE_PORT_RIGHTS                                      \
 257                 (MACH_PORT_TYPE_SEND_RIGHTS|MACH_PORT_TYPE_RECEIVE)
 258 #define MACH_PORT_TYPE_PORT_OR_DEAD                                     \
 259                 (MACH_PORT_TYPE_PORT_RIGHTS|MACH_PORT_TYPE_DEAD_NAME)
 260 #define MACH_PORT_TYPE_ALL_RIGHTS                                       \
 261                 (MACH_PORT_TYPE_PORT_OR_DEAD|MACH_PORT_TYPE_PORT_SET)
 262
 263 /* Dummy type bits that mach_port_type/mach_port_names can return. */
 264
 265 #define MACH_PORT_TYPE_DNREQUEST        0x80000000
 266
 267 /* User-references for capabilities. */
 268
 269 typedef natural_t mach_port_urefs_t;
 270 typedef integer_t mach_port_delta_t;                    /* change in urefs */
 271
 272 /* Attributes of ports.  (See mach_port_get_receive_status.) */
 273
 274 typedef natural_t mach_port_seqno_t;            /* sequence number */
 275 typedef natural_t mach_port_mscount_t;          /* make-send count */
 276 typedef natural_t mach_port_msgcount_t;         /* number of msgs */
 277 typedef natural_t mach_port_rights_t;           /* number of rights */
 278
 279 /*
 280  *      Are there outstanding send rights for a given port?
 281  */
 282 #define MACH_PORT_SRIGHTS_NONE          0               /* no srights */
 283 #define MACH_PORT_SRIGHTS_PRESENT       1               /* srights */
 284 typedef unsigned int mach_port_srights_t;       /* status of send rights */
 285
 286 typedef struct mach_port_status {
 287         mach_port_name_t        mps_pset;       /* containing port set */
 288         mach_port_seqno_t       mps_seqno;      /* sequence number */
 289         mach_port_mscount_t     mps_mscount;    /* make-send count */
 290         mach_port_msgcount_t    mps_qlimit;     /* queue limit */
 291         mach_port_msgcount_t    mps_msgcount;   /* number in the queue */
 292         mach_port_rights_t      mps_sorights;   /* how many send-once rights */
 293         boolean_t               mps_srights;    /* do send rights exist? */
 294         boolean_t               mps_pdrequest;  /* port-deleted requested? */
 295         boolean_t               mps_nsrequest;  /* no-senders requested? */
 296         natural_t               mps_flags;              /* port flags */
 297 } mach_port_status_t;
 298
 299 #define MACH_PORT_QLIMIT_DEFAULT        ((mach_port_msgcount_t) 5)
 300 #define MACH_PORT_QLIMIT_MAX    ((mach_port_msgcount_t) 16)
 301
 302 typedef struct mach_port_limits {
 303         mach_port_msgcount_t    mpl_qlimit;     /* number of msgs */
 304 } mach_port_limits_t;
 305
 306 typedef integer_t *mach_port_info_t;            /* varying array of natural_t */
 307
 308 /* Flavors for mach_port_get/set_attributes() */
 309 typedef int     mach_port_flavor_t;
 310 #define MACH_PORT_LIMITS_INFO           1       /* uses mach_port_status_t */
 311 #define MACH_PORT_RECEIVE_STATUS        2       /* uses mach_port_limits_t */
 312 #define MACH_PORT_DNREQUESTS_SIZE       3       /* info is int */
 313
 314 #define MACH_PORT_LIMITS_INFO_COUNT     ((natural_t) \
 315         (sizeof(mach_port_limits_t)/sizeof(natural_t)))
 316 #define MACH_PORT_RECEIVE_STATUS_COUNT  ((natural_t) \
 317         (sizeof(mach_port_status_t)/sizeof(natural_t)))
 318 #define MACH_PORT_DNREQUESTS_SIZE_COUNT 1
 319
 320 /*
 321  * Structure used to pass information about port allocation requests.
 322  * Must be padded to 64-bits total length.
 323  */
 324 typedef struct mach_port_qos {
 325         boolean_t               name:1;         /* name given */
 326         boolean_t               prealloc:1;     /* prealloced message */
 327         boolean_t               pad1:30;
 328         natural_t               len;
 329 } mach_port_qos_t;
 330
 331 #if     !defined(_POSIX_C_SOURCE) && !defined(_NO_PORT_T_FROM_MACH)
 332 /*
 333  *  Mach 3.0 renamed everything to have mach_ in front of it.
 334  *  These types and macros are provided for backward compatibility
 335  *      but are deprecated.
 336  */
 337 typedef mach_port_t             port_t;
 338 typedef mach_port_name_t        port_name_t;
 339 typedef mach_port_name_t        *port_name_array_t;
 340
 341 #define PORT_NULL               ((port_t) 0)
 342 #define PORT_DEAD               ((port_t) ~0)
 343 #define PORT_VALID(name) \
 344                 ((port_t)(name) != PORT_NULL && (port_t)(name) != PORT_DEAD)
 345
 346 #endif  /* !_POSIX_C_SOURCE && !_NO_PORT_T_FROM_MACH */
 347
 348 #endif  /* _MACH_PORT_H_ */