osfmk/mach/port.h

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