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