1 /* 2 * Copyright (c) 2000-2006 Apple Computer, Inc. All rights reserved. 3 * 4 * @APPLE_OSREFERENCE_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. The rights granted to you under the License 10 * may not be used to create, or enable the creation or redistribution of, 11 * unlawful or unlicensed copies of an Apple operating system, or to 12 * circumvent, violate, or enable the circumvention or violation of, any 13 * terms of an Apple operating system software license agreement. 14 * 15 * Please obtain a copy of the License at 16 * http://www.opensource.apple.com/apsl/ and read it before using this file. 17 * 18 * The Original Code and all software distributed under the License are 19 * distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER 20 * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES, 21 * INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY, 22 * FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT. 23 * Please see the License for the specific language governing rights and 24 * limitations under the License. 25 * 26 * @APPLE_OSREFERENCE_LICENSE_HEADER_END@ 27 */ 28 /* 29 * @OSF_COPYRIGHT@ 30 */ 31 /* 32 * Mach Operating System 33 * Copyright (c) 1991,1990,1989,1988,1987 Carnegie Mellon University 34 * All Rights Reserved. 35 * 36 * Permission to use, copy, modify and distribute this software and its 37 * documentation is hereby granted, provided that both the copyright 38 * notice and this permission notice appear in all copies of the 39 * software, derivative works or modified versions, and any portions 40 * thereof, and that both notices appear in supporting documentation. 41 * 42 * CARNEGIE MELLON ALLOWS FREE USE OF THIS SOFTWARE IN ITS "AS IS" 43 * CONDITION. CARNEGIE MELLON DISCLAIMS ANY LIABILITY OF ANY KIND FOR 44 * ANY DAMAGES WHATSOEVER RESULTING FROM THE USE OF THIS SOFTWARE. 45 * 46 * Carnegie Mellon requests users of this software to return to 47 * 48 * Software Distribution Coordinator or Software.Distribution@CS.CMU.EDU 49 * School of Computer Science 50 * Carnegie Mellon University 51 * Pittsburgh PA 15213-3890 52 * 53 * any improvements or extensions that they make and grant Carnegie Mellon 54 * the rights to redistribute these changes. 55 */ 56 /* 57 * NOTICE: This file was modified by McAfee Research in 2004 to introduce 58 * support for mandatory and extensible security protections. This notice 59 * is included in support of clause 2.2 (b) of the Apple Public License, 60 * Version 2.0. 61 */ 62 /* 63 */ 64 /* 65 * File: mach/port.h 66 * 67 * Definition of a Mach port 68 * 69 * Mach ports are the endpoints to Mach-implemented communications 70 * channels (usually uni-directional message queues, but other types 71 * also exist). 72 * 73 * Unique collections of these endpoints are maintained for each 74 * Mach task. Each Mach port in the task's collection is given a 75 * [task-local] name to identify it - and the the various "rights" 76 * held by the task for that specific endpoint. 77 * 78 * This header defines the types used to identify these Mach ports 79 * and the various rights associated with them. For more info see: 80 * 81 * <mach/mach_port.h> - manipulation of port rights in a given space 82 * <mach/message.h> - message queue [and port right passing] mechanism 83 * 84 */ 85 86 #ifndef _MACH_PORT_H_ 87 #define _MACH_PORT_H_ 88 89 #include <sys/cdefs.h> 90 #include <stdint.h> 91 #include <mach/boolean.h> 92 #include <mach/machine/vm_types.h> 93 94 /* 95 * mach_port_name_t - the local identity for a Mach port 96 * 97 * The name is Mach port namespace specific. It is used to 98 * identify the rights held for that port by the task whose 99 * namespace is implied [or specifically provided]. 100 * 101 * Use of this type usually implies just a name - no rights. 102 * See mach_port_t for a type that implies a "named right." 103 * 104 */ 105 106 typedef natural_t mach_port_name_t; 107 typedef mach_port_name_t *mach_port_name_array_t; 108 109 110 /* 111 * mach_port_t - a named port right 112 * 113 * In user-space, "rights" are represented by the name of the 114 * right in the Mach port namespace. Even so, this type is 115 * presented as a unique one to more clearly denote the presence 116 * of a right coming along with the name. 117 * 118 * Often, various rights for a port held in a single name space 119 * will coalesce and are, therefore, be identified by a single name 120 * [this is the case for send and receive rights]. But not 121 * always [send-once rights currently get a unique name for 122 * each right]. 123 * 124 */ 125 126 #include <sys/_types.h> 127 #include <sys/_types/_mach_port_t.h> 128 129 130 typedef mach_port_t *mach_port_array_t; 131 132 /* 133 * MACH_PORT_NULL is a legal value that can be carried in messages. 134 * It indicates the absence of any port or port rights. (A port 135 * argument keeps the message from being "simple", even if the 136 * value is MACH_PORT_NULL.) The value MACH_PORT_DEAD is also a legal 137 * value that can be carried in messages. It indicates 138 * that a port right was present, but it died. 139 */ 140 141 #define MACH_PORT_NULL 0 /* intentional loose typing */ 142 #define MACH_PORT_DEAD ((mach_port_name_t) ~0) 143 #define MACH_PORT_VALID(name) \ 144 (((name) != MACH_PORT_NULL) && \ 145 ((name) != MACH_PORT_DEAD)) 146 147 148 /* 149 * For kernel-selected [assigned] port names, the name is 150 * comprised of two parts: a generation number and an index. 151 * This approach keeps the exact same name from being generated 152 * and reused too quickly [to catch right/reference counting bugs]. 153 * The dividing line between the constituent parts is exposed so 154 * that efficient "mach_port_name_t to data structure pointer" 155 * conversion implementation can be made. But it is possible 156 * for user-level code to assign their own names to Mach ports. 157 * These are not required to participate in this algorithm. So 158 * care should be taken before "assuming" this model. 159 * 160 */ 161 162 #ifndef NO_PORT_GEN 163 164 #define MACH_PORT_INDEX(name) ((name) >> 8) 165 #define MACH_PORT_GEN(name) (((name) & 0xff) << 24) 166 #define MACH_PORT_MAKE(index, gen) \ 167 (((index) << 8) | (gen) >> 24) 168 169 #else /* NO_PORT_GEN */ 170 171 #define MACH_PORT_INDEX(name) (name) 172 #define MACH_PORT_GEN(name) (0) 173 #define MACH_PORT_MAKE(index, gen) (index) 174 175 #endif /* NO_PORT_GEN */ 176 177 178 /* 179 * These are the different rights a task may have for a port. 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_LABELH ((mach_port_right_t) 5) /* obsolete right */ 196 #define MACH_PORT_RIGHT_NUMBER ((mach_port_right_t) 6) /* right not implemented */ 197 198 199 typedef natural_t mach_port_type_t; 200 typedef mach_port_type_t *mach_port_type_array_t; 201 202 #define MACH_PORT_TYPE(right) \ 203 ((mach_port_type_t)(((mach_port_type_t) 1) \ 204 << ((right) + ((mach_port_right_t) 16)))) 205 #define MACH_PORT_TYPE_NONE ((mach_port_type_t) 0L) 206 #define MACH_PORT_TYPE_SEND MACH_PORT_TYPE(MACH_PORT_RIGHT_SEND) 207 #define MACH_PORT_TYPE_RECEIVE MACH_PORT_TYPE(MACH_PORT_RIGHT_RECEIVE) 208 #define MACH_PORT_TYPE_SEND_ONCE MACH_PORT_TYPE(MACH_PORT_RIGHT_SEND_ONCE) 209 #define MACH_PORT_TYPE_PORT_SET MACH_PORT_TYPE(MACH_PORT_RIGHT_PORT_SET) 210 #define MACH_PORT_TYPE_DEAD_NAME MACH_PORT_TYPE(MACH_PORT_RIGHT_DEAD_NAME) 211 #define MACH_PORT_TYPE_LABELH MACH_PORT_TYPE(MACH_PORT_RIGHT_LABELH) /* obsolete */ 212 213 214 /* Convenient combinations. */ 215 216 #define MACH_PORT_TYPE_SEND_RECEIVE \ 217 (MACH_PORT_TYPE_SEND|MACH_PORT_TYPE_RECEIVE) 218 #define MACH_PORT_TYPE_SEND_RIGHTS \ 219 (MACH_PORT_TYPE_SEND|MACH_PORT_TYPE_SEND_ONCE) 220 #define MACH_PORT_TYPE_PORT_RIGHTS \ 221 (MACH_PORT_TYPE_SEND_RIGHTS|MACH_PORT_TYPE_RECEIVE) 222 #define MACH_PORT_TYPE_PORT_OR_DEAD \ 223 (MACH_PORT_TYPE_PORT_RIGHTS|MACH_PORT_TYPE_DEAD_NAME) 224 #define MACH_PORT_TYPE_ALL_RIGHTS \ 225 (MACH_PORT_TYPE_PORT_OR_DEAD|MACH_PORT_TYPE_PORT_SET) 226 227 /* Dummy type bits that mach_port_type/mach_port_names can return. */ 228 229 #define MACH_PORT_TYPE_DNREQUEST 0x80000000 230 #define MACH_PORT_TYPE_SPREQUEST 0x40000000 231 #define MACH_PORT_TYPE_SPREQUEST_DELAYED 0x20000000 232 233 /* User-references for capabilities. */ 234 235 typedef natural_t mach_port_urefs_t; 236 typedef integer_t mach_port_delta_t; /* change in urefs */ 237 238 /* Attributes of ports. (See mach_port_get_receive_status.) */ 239 240 typedef natural_t mach_port_seqno_t; /* sequence number */ 241 typedef natural_t mach_port_mscount_t; /* make-send count */ 242 typedef natural_t mach_port_msgcount_t; /* number of msgs */ 243 typedef natural_t mach_port_rights_t; /* number of rights */ 244 245 /* 246 * Are there outstanding send rights for a given port? 247 */ 248 #define MACH_PORT_SRIGHTS_NONE 0 /* no srights */ 249 #define MACH_PORT_SRIGHTS_PRESENT 1 /* srights */ 250 typedef unsigned int mach_port_srights_t; /* status of send rights */ 251 252 typedef struct mach_port_status { 253 mach_port_rights_t mps_pset; /* count of containing port sets */ 254 mach_port_seqno_t mps_seqno; /* sequence number */ 255 mach_port_mscount_t mps_mscount; /* make-send count */ 256 mach_port_msgcount_t mps_qlimit; /* queue limit */ 257 mach_port_msgcount_t mps_msgcount; /* number in the queue */ 258 mach_port_rights_t mps_sorights; /* how many send-once rights */ 259 boolean_t mps_srights; /* do send rights exist? */ 260 boolean_t mps_pdrequest; /* port-deleted requested? */ 261 boolean_t mps_nsrequest; /* no-senders requested? */ 262 natural_t mps_flags; /* port flags */ 263 } mach_port_status_t; 264 265 /* System-wide values for setting queue limits on a port */ 266 #define MACH_PORT_QLIMIT_ZERO (0) 267 #define MACH_PORT_QLIMIT_BASIC (5) 268 #define MACH_PORT_QLIMIT_SMALL (16) 269 #define MACH_PORT_QLIMIT_LARGE (1024) 270 #define MACH_PORT_QLIMIT_KERNEL (65534) 271 #define MACH_PORT_QLIMIT_MIN MACH_PORT_QLIMIT_ZERO 272 #define MACH_PORT_QLIMIT_DEFAULT MACH_PORT_QLIMIT_BASIC 273 #define MACH_PORT_QLIMIT_MAX MACH_PORT_QLIMIT_LARGE 274 275 typedef struct mach_port_limits { 276 mach_port_msgcount_t mpl_qlimit; /* number of msgs */ 277 } mach_port_limits_t; 278 279 /* Possible values for mps_flags (part of mach_port_status_t) */ 280 #define MACH_PORT_STATUS_FLAG_TEMPOWNER 0x01 281 #define MACH_PORT_STATUS_FLAG_GUARDED 0x02 282 #define MACH_PORT_STATUS_FLAG_STRICT_GUARD 0x04 283 #define MACH_PORT_STATUS_FLAG_IMP_DONATION 0x08 284 #define MACH_PORT_STATUS_FLAG_REVIVE 0x10 285 #define MACH_PORT_STATUS_FLAG_TASKPTR 0x20 286 #define MACH_PORT_STATUS_FLAG_GUARD_IMMOVABLE_RECEIVE 0x40 287 #define MACH_PORT_STATUS_FLAG_NO_GRANT 0x80 288 289 typedef struct mach_port_info_ext { 290 mach_port_status_t mpie_status; 291 mach_port_msgcount_t mpie_boost_cnt; 292 uint32_t reserved[6]; 293 } mach_port_info_ext_t; 294 295 typedef integer_t *mach_port_info_t; /* varying array of natural_t */ 296 297 /* Flavors for mach_port_get/set_attributes() */ 298 typedef int mach_port_flavor_t; 299 #define MACH_PORT_LIMITS_INFO 1 /* uses mach_port_limits_t */ 300 #define MACH_PORT_RECEIVE_STATUS 2 /* uses mach_port_status_t */ 301 #define MACH_PORT_DNREQUESTS_SIZE 3 /* info is int */ 302 #define MACH_PORT_TEMPOWNER 4 /* indicates receive right will be reassigned to another task */ 303 #define MACH_PORT_IMPORTANCE_RECEIVER 5 /* indicates recieve right accepts priority donation */ 304 #define MACH_PORT_DENAP_RECEIVER 6 /* indicates receive right accepts de-nap donation */ 305 #define MACH_PORT_INFO_EXT 7 /* uses mach_port_info_ext_t */ 306 307 #define MACH_PORT_LIMITS_INFO_COUNT ((natural_t) \ 308 (sizeof(mach_port_limits_t)/sizeof(natural_t))) 309 #define MACH_PORT_RECEIVE_STATUS_COUNT ((natural_t) \ 310 (sizeof(mach_port_status_t)/sizeof(natural_t))) 311 #define MACH_PORT_DNREQUESTS_SIZE_COUNT 1 312 #define MACH_PORT_INFO_EXT_COUNT ((natural_t) \ 313 (sizeof(mach_port_info_ext_t)/sizeof(natural_t))) 314 /* 315 * Structure used to pass information about port allocation requests. 316 * Must be padded to 64-bits total length. 317 */ 318 typedef struct mach_port_qos { 319 unsigned int name:1; /* name given */ 320 unsigned int prealloc:1; /* prealloced message */ 321 boolean_t pad1:30; 322 natural_t len; 323 } mach_port_qos_t; 324 325 /* Mach Port Guarding definitions */ 326 327 /* 328 * Flags for mach_port_options (used for 329 * invocation of mach_port_construct). 330 * Indicates attributes to be set for the newly 331 * allocated port. 332 */ 333 #define MPO_CONTEXT_AS_GUARD 0x01 /* Add guard to the port */ 334 #define MPO_QLIMIT 0x02 /* Set qlimit for the port msg queue */ 335 #define MPO_TEMPOWNER 0x04 /* Set the tempowner bit of the port */ 336 #define MPO_IMPORTANCE_RECEIVER 0x08 /* Mark the port as importance receiver */ 337 #define MPO_INSERT_SEND_RIGHT 0x10 /* Insert a send right for the port */ 338 #define MPO_STRICT 0x20 /* Apply strict guarding for port */ 339 #define MPO_DENAP_RECEIVER 0x40 /* Mark the port as App de-nap receiver */ 340 #define MPO_IMMOVABLE_RECEIVE 0x80 /* Mark the port as immovable; protected by the guard context */ 341 #define MPO_FILTER_MSG 0x100 /* Allow message filtering */ 342 #define MPO_TG_BLOCK_TRACKING 0x200 /* Track blocking relationship for thread group during sync IPC */ 343 344 /* 345 * Structure to define optional attributes for a newly 346 * constructed port. 347 */ 348 typedef struct mach_port_options { 349 uint32_t flags; /* Flags defining attributes for port */ 350 mach_port_limits_t mpl; /* Message queue limit for port */ 351 union { 352 uint64_t reserved[2]; /* Reserved */ 353 mach_port_name_t work_interval_port; /* Work interval port */ 354 }; 355 }mach_port_options_t; 356 357 typedef mach_port_options_t *mach_port_options_ptr_t; 358 359 /* 360 * EXC_GUARD represents a guard violation for both 361 * mach ports and file descriptors. GUARD_TYPE_ is used 362 * to differentiate among them. 363 */ 364 #define GUARD_TYPE_MACH_PORT 0x1 365 366 /* Reasons for exception for a guarded mach port */ 367 enum mach_port_guard_exception_codes { 368 kGUARD_EXC_DESTROY = 1u << 0, 369 kGUARD_EXC_MOD_REFS = 1u << 1, 370 kGUARD_EXC_SET_CONTEXT = 1u << 2, 371 kGUARD_EXC_UNGUARDED = 1u << 3, 372 kGUARD_EXC_INCORRECT_GUARD = 1u << 4, 373 kGUARD_EXC_IMMOVABLE = 1u << 5, 374 kGUARD_EXC_STRICT_REPLY = 1u << 6, 375 kGUARD_EXC_MSG_FILTERED = 1u << 7, 376 /* start of [optionally] non-fatal guards */ 377 kGUARD_EXC_INVALID_RIGHT = 1u << 8, 378 kGUARD_EXC_INVALID_NAME = 1u << 9, 379 kGUARD_EXC_INVALID_VALUE = 1u << 10, 380 kGUARD_EXC_INVALID_ARGUMENT = 1u << 11, 381 kGUARD_EXC_RIGHT_EXISTS = 1u << 12, 382 kGUARD_EXC_KERN_NO_SPACE = 1u << 13, 383 kGUARD_EXC_KERN_FAILURE = 1u << 14, 384 kGUARD_EXC_KERN_RESOURCE = 1u << 15, 385 kGUARD_EXC_SEND_INVALID_REPLY = 1u << 16, 386 kGUARD_EXC_SEND_INVALID_VOUCHER = 1u << 17, 387 kGUARD_EXC_SEND_INVALID_RIGHT = 1u << 18, 388 kGUARD_EXC_RCV_INVALID_NAME = 1u << 19, 389 kGUARD_EXC_RCV_GUARDED_DESC = 1u << 20, /* should never be fatal; for development only */ 390 kGUARD_EXC_MOD_REFS_NON_FATAL = 1u << 21, 391 kGUARD_EXC_IMMOVABLE_NON_FATAL = 1u << 22, 392 }; 393 394 #define MAX_FATAL_kGUARD_EXC_CODE (1u << 7) 395 396 /* 397 * Mach port guard flags. 398 */ 399 #define MPG_FLAGS_NONE (0x00ull) 400 401 /* 402 * These flags are used as bits in the subcode of kGUARD_EXC_STRICT_REPLY exceptions. 403 */ 404 #define MPG_FLAGS_STRICT_REPLY_INVALID_REPLY_DISP (0x01ull << 56) 405 #define MPG_FLAGS_STRICT_REPLY_INVALID_REPLY_PORT (0x02ull << 56) 406 #define MPG_FLAGS_STRICT_REPLY_INVALID_VOUCHER (0x04ull << 56) 407 #define MPG_FLAGS_STRICT_REPLY_NO_BANK_ATTR (0x08ull << 56) 408 #define MPG_FLAGS_STRICT_REPLY_MISMATCHED_PERSONA (0x10ull << 56) 409 #define MPG_FLAGS_STRICT_REPLY_MASK (0xffull << 56) 410 411 /* 412 * These flags are used as bits in the subcode of kGUARD_EXC_MOD_REFS exceptions. 413 */ 414 #define MPG_FLAGS_MOD_REFS_PINNED_DEALLOC (0x01ull << 56) 415 416 /* 417 * These flags are used as bits in the subcode of kGUARD_EXC_IMMOVABLE exceptions. 418 */ 419 #define MPG_FLAGS_IMMOVABLE_PINNED (0x01ull << 56) 420 421 /* 422 * Flags for mach_port_guard_with_flags. These flags extend 423 * the attributes associated with a guarded port. 424 */ 425 #define MPG_STRICT 0x01 /* Apply strict guarding for a port */ 426 #define MPG_IMMOVABLE_RECEIVE 0x02 /* Receive right cannot be moved out of the space */ 427 428 #if !__DARWIN_UNIX03 && !defined(_NO_PORT_T_FROM_MACH) 429 /* 430 * Mach 3.0 renamed everything to have mach_ in front of it. 431 * These types and macros are provided for backward compatibility 432 * but are deprecated. 433 */ 434 typedef mach_port_t port_t; 435 typedef mach_port_name_t port_name_t; 436 typedef mach_port_name_t *port_name_array_t; 437 438 #define PORT_NULL ((port_t) 0) 439 #define PORT_DEAD ((port_t) ~0) 440 #define PORT_VALID(name) \ 441 ((port_t)(name) != PORT_NULL && (port_t)(name) != PORT_DEAD) 442 443 #endif /* !__DARWIN_UNIX03 && !_NO_PORT_T_FROM_MACH */ 444 445 #endif /* _MACH_PORT_H_ */