osfmk/mach/port.h

   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_COPYRIGHT@
  27  */
  28 /*
  29  * Mach Operating System
  30  * Copyright (c) 1991,1990,1989,1988,1987 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/port.h
  57  *
  58  *      Definition of a port
  59  *
  60  *      [The basic port_t type should probably be machine-dependent,
  61  *      as it must be represented by a 32-bit integer.]
  62  */
  63
  64 #ifndef _MACH_PORT_H_
  65 #define _MACH_PORT_H_
  66
  67 #include <stdint.h>
  68 #include <mach/boolean.h>
  69 #include <mach/machine/vm_types.h>
  70
  71 #include <sys/appleapiopts.h>
  72
  73 /*
  74  * A port_name_t is a 32 bit value which represents a name of a
  75  * port right within some ipc space.  This is a constant definition
  76  * everywhere.
  77  *
  78  * The type port_t represents a reference added or deleted to a
  79  * port right.
  80  *
  81  *      At user space, this is represented by returning the name of
  82  *      the right(s) that got altered within the user's ipc space.
  83  *      So a port_t is the same type as a port_name_t there.
  84  *
  85  *      Since there is no right space for the kernel proper (all rights
  86  *      are naked rights) these rights are represented by passing a
  87  *      pointer to the specific ipc_object_t subclass (typically
  88  *      ipc_port_t) that got altered/is to be altered.
  89  *
  90  *      JMM - Because of this pointer/integer overloading, port names
  91  *      should be defined as uintptr_t types.  But that would make
  92  *      message headers and descriptors pointer-length dependent.
  93  */
  94 typedef natural_t port_name_t;
  95 typedef port_name_t *port_name_array_t;
  96
  97 #ifdef KERNEL_PRIVATE
  98
  99 #if !defined(__APPLE_API_PRIVATE) || !defined(MACH_KERNEL_PRIVATE)
 100 /*
 101  * For kernel code that resides outside of mach
 102  * we define empty structs so that everything will
 103  * remain strongly typed, without giving out
 104  * implementation details.
 105  */
 106 struct ipc_port ;
 107
 108 #endif /* !__APPLE_API_PRIVATE || !MACH_KERNEL_PRIVATE */
 109
 110 typedef struct ipc_port         *ipc_port_t;
 111 typedef ipc_port_t              port_t;
 112
 113 #define IPC_PORT_NULL           ((ipc_port_t) 0)
 114 #define IPC_PORT_DEAD           ((ipc_port_t)~0)
 115 #define IPC_PORT_VALID(port)    (((port) != IPC_PORT_NULL) && \
 116                                  ((port) != IPC_PORT_DEAD))
 117
 118 #else  /* ! KERNEL_PRIVATE */
 119
 120 typedef port_name_t             port_t;
 121
 122 #endif /* KERNEL_PRIVATE */
 123
 124 /*
 125  *  PORT_NULL is a legal value that can be carried in messages.
 126  *  It indicates the absence of any port or port rights.  (A port
 127  *  argument keeps the message from being "simple", even if the
 128  *  value is PORT_NULL.)  The value PORT_DEAD is also a legal
 129  *  value that can be carried in messages.  It indicates
 130  *  that a port right was present, but it died.
 131  */
 132 #define PORT_NULL               ((port_t) 0)
 133 #define PORT_DEAD               ((port_t) ~0)
 134 #define PORT_VALID(name)                                \
 135                 (((port_t)(name) != PORT_NULL) &&       \
 136                  ((port_t)(name) != PORT_DEAD))
 137
 138 /*
 139  *  Mach 3.0 renamed everything to have mach_ in front of it.
 140  *  Do that mapping here, so we have the types and macros in
 141  *  both formats.
 142  */
 143 typedef port_t                  mach_port_t;
 144 typedef port_t                  *mach_port_array_t;
 145 typedef port_name_t             mach_port_name_t;
 146 typedef mach_port_name_t        *mach_port_name_array_t;
 147
 148 #define MACH_PORT_NULL          0  /* intentional loose typing */
 149 #define MACH_PORT_DEAD          ((mach_port_name_t) ~0)
 150 #define MACH_PORT_VALID(name)                           \
 151                 (((name) != MACH_PORT_NULL) &&          \
 152                  ((name) != MACH_PORT_DEAD))
 153
 154 /*
 155  *  mach_port_name_t must be an unsigned type.  Port values
 156  *  have two parts, a generation number and an index.
 157  *  These macros encapsulate all knowledge of how
 158  *  a mach_port_name_t is laid out.  They are made visible
 159  *  to user tasks so that packages to map from a mach_port_name_t
 160  *  to associated user data can discount the generation
 161  *  nuber (if desired) in doing the mapping.
 162  *
 163  *  Within the kernel, ipc/ipc_entry.c implicitly assumes
 164  *  when it uses the splay tree functions that the generation
 165  *  number is in the low bits, so that names are ordered first
 166  *  by index and then by generation.  If the size of generation
 167  *  numbers changes, be sure to update IE_BITS_GEN_MASK and
 168  *  friends in ipc/ipc_entry.h.
 169  */
 170 #ifndef NO_PORT_GEN
 171 #define MACH_PORT_INDEX(name)           ((name) >> 8)
 172 #define MACH_PORT_GEN(name)             (((name) & 0xff) << 24)
 173 #define MACH_PORT_MAKE(index, gen)      \
 174                 (((index) << 8) | (gen) >> 24)
 175 #else
 176 #define MACH_PORT_INDEX(name)           (name)
 177 #define MACH_PORT_GEN(name)             (0)
 178 #define MACH_PORT_MAKE(index, gen)      (index)
 179 #endif  /* !NO_PORT_GEN */
 180
 181 /*
 182  *  These are the different rights a task may have.
 183  *  The MACH_PORT_RIGHT_* definitions are used as arguments
 184  *  to mach_port_allocate, mach_port_get_refs, etc, to specify
 185  *  a particular right to act upon.  The mach_port_names and
 186  *  mach_port_type calls return bitmasks using the MACH_PORT_TYPE_*
 187  *  definitions.  This is because a single name may denote
 188  *  multiple rights.
 189  */
 190
 191 typedef natural_t mach_port_right_t;
 192
 193 #define MACH_PORT_RIGHT_SEND            ((mach_port_right_t) 0)
 194 #define MACH_PORT_RIGHT_RECEIVE         ((mach_port_right_t) 1)
 195 #define MACH_PORT_RIGHT_SEND_ONCE       ((mach_port_right_t) 2)
 196 #define MACH_PORT_RIGHT_PORT_SET        ((mach_port_right_t) 3)
 197 #define MACH_PORT_RIGHT_DEAD_NAME       ((mach_port_right_t) 4)
 198 #define MACH_PORT_RIGHT_NUMBER          ((mach_port_right_t) 5)
 199
 200 typedef natural_t mach_port_type_t;
 201 typedef mach_port_type_t *mach_port_type_array_t;
 202
 203 #define MACH_PORT_TYPE(right)                                           \
 204                 ((mach_port_type_t)(((mach_port_type_t) 1)              \
 205                 << ((right) + ((mach_port_right_t) 16))))
 206 #define MACH_PORT_TYPE_NONE         ((mach_port_type_t) 0L)
 207 #define MACH_PORT_TYPE_SEND         MACH_PORT_TYPE(MACH_PORT_RIGHT_SEND)
 208 #define MACH_PORT_TYPE_RECEIVE      MACH_PORT_TYPE(MACH_PORT_RIGHT_RECEIVE)
 209 #define MACH_PORT_TYPE_SEND_ONCE    MACH_PORT_TYPE(MACH_PORT_RIGHT_SEND_ONCE)
 210 #define MACH_PORT_TYPE_PORT_SET     MACH_PORT_TYPE(MACH_PORT_RIGHT_PORT_SET)
 211 #define MACH_PORT_TYPE_DEAD_NAME    MACH_PORT_TYPE(MACH_PORT_RIGHT_DEAD_NAME)
 212
 213 /* Convenient combinations. */
 214
 215 #define MACH_PORT_TYPE_SEND_RECEIVE                                     \
 216                 (MACH_PORT_TYPE_SEND|MACH_PORT_TYPE_RECEIVE)
 217 #define MACH_PORT_TYPE_SEND_RIGHTS                                      \
 218                 (MACH_PORT_TYPE_SEND|MACH_PORT_TYPE_SEND_ONCE)
 219 #define MACH_PORT_TYPE_PORT_RIGHTS                                      \
 220                 (MACH_PORT_TYPE_SEND_RIGHTS|MACH_PORT_TYPE_RECEIVE)
 221 #define MACH_PORT_TYPE_PORT_OR_DEAD                                     \
 222                 (MACH_PORT_TYPE_PORT_RIGHTS|MACH_PORT_TYPE_DEAD_NAME)
 223 #define MACH_PORT_TYPE_ALL_RIGHTS                                       \
 224                 (MACH_PORT_TYPE_PORT_OR_DEAD|MACH_PORT_TYPE_PORT_SET)
 225
 226 /* Dummy type bits that mach_port_type/mach_port_names can return. */
 227
 228 #define MACH_PORT_TYPE_DNREQUEST        0x80000000
 229
 230 /* User-references for capabilities. */
 231
 232 typedef natural_t mach_port_urefs_t;
 233 typedef integer_t mach_port_delta_t;                    /* change in urefs */
 234
 235 /* Attributes of ports.  (See mach_port_get_receive_status.) */
 236
 237 typedef natural_t mach_port_seqno_t;            /* sequence number */
 238 typedef natural_t mach_port_mscount_t;          /* make-send count */
 239 typedef natural_t mach_port_msgcount_t;         /* number of msgs */
 240 typedef natural_t mach_port_rights_t;           /* number of rights */
 241
 242 /*
 243  *      Are there outstanding send rights for a given port?
 244  */
 245 #define MACH_PORT_SRIGHTS_NONE          0               /* no srights */
 246 #define MACH_PORT_SRIGHTS_PRESENT       1               /* srights */
 247 typedef unsigned int mach_port_srights_t;       /* status of send rights */
 248
 249 typedef struct mach_port_status {
 250         mach_port_name_t        mps_pset;       /* containing port set */
 251         mach_port_seqno_t       mps_seqno;      /* sequence number */
 252         mach_port_mscount_t     mps_mscount;    /* make-send count */
 253         mach_port_msgcount_t    mps_qlimit;     /* queue limit */
 254         mach_port_msgcount_t    mps_msgcount;   /* number in the queue */
 255         mach_port_rights_t      mps_sorights;   /* how many send-once rights */
 256         boolean_t               mps_srights;    /* do send rights exist? */
 257         boolean_t               mps_pdrequest;  /* port-deleted requested? */
 258         boolean_t               mps_nsrequest;  /* no-senders requested? */
 259         unsigned int            mps_flags;      /* port flags */
 260 } mach_port_status_t;
 261
 262 #define MACH_PORT_QLIMIT_DEFAULT        ((mach_port_msgcount_t) 5)
 263 #define MACH_PORT_QLIMIT_MAX            ((mach_port_msgcount_t) 16)
 264
 265 typedef struct mach_port_limits {
 266         mach_port_msgcount_t    mpl_qlimit;     /* number of msgs */
 267 } mach_port_limits_t;
 268
 269 typedef integer_t *mach_port_info_t;            /* varying array of natural_t */
 270
 271 /* Flavors for mach_port_get/set_attributes() */
 272 typedef int     mach_port_flavor_t;
 273 #define MACH_PORT_LIMITS_INFO           1       /* uses mach_port_status_t */
 274 #define MACH_PORT_RECEIVE_STATUS        2       /* uses mach_port_limits_t */
 275 #define MACH_PORT_DNREQUESTS_SIZE       3       /* info is int */
 276
 277 #define MACH_PORT_LIMITS_INFO_COUNT \
 278         (sizeof(mach_port_limits_t)/sizeof(natural_t))
 279 #define MACH_PORT_RECEIVE_STATUS_COUNT \
 280         (sizeof(mach_port_status_t)/sizeof(natural_t))
 281 #define MACH_PORT_DNREQUESTS_SIZE_COUNT 1
 282
 283 /*
 284  * Structure used to pass information about port allocation requests.
 285  * Must be padded to 64-bits total length.
 286  */
 287
 288 typedef struct mach_port_qos {
 289         boolean_t               name:1;         /* name given */
 290         boolean_t               prealloc:1;     /* prealloced message */
 291         boolean_t               pad1:30;
 292         natural_t               len;
 293 } mach_port_qos_t;
 294
 295 #endif  /* _MACH_PORT_H_ */