1/* 2 * Copyright (c) 2000-2004 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 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: ipc/ipc_port.h 66 * Author: Rich Draves 67 * Date: 1989 68 * 69 * Definitions for ports. 70 */ 71 72#ifndef _IPC_IPC_PORT_H_ 73#define _IPC_IPC_PORT_H_ 74 75#include <norma_vm.h> 76#include <mach_rt.h> 77#include <mach_assert.h> 78#include <mach_debug.h> 79 80#include <mach/mach_types.h> 81#include <mach/boolean.h> 82#include <mach/kern_return.h> 83#include <mach/port.h> 84 85#include <kern/kern_types.h> 86 87#include <ipc/ipc_types.h> 88#include <ipc/ipc_object.h> 89#include <ipc/ipc_mqueue.h> 90#include <ipc/ipc_space.h> 91 92#include <security/_label.h> 93 94/* 95 * A receive right (port) can be in four states: 96 * 1) dead (not active, ip_timestamp has death time) 97 * 2) in a space (ip_receiver_name != 0, ip_receiver points 98 * to the space but doesn't hold a ref for it) 99 * 3) in transit (ip_receiver_name == 0, ip_destination points 100 * to the destination port and holds a ref for it) 101 * 4) in limbo (ip_receiver_name == 0, ip_destination == IP_NULL) 102 * 103 * If the port is active, and ip_receiver points to some space, 104 * then ip_receiver_name != 0, and that space holds receive rights. 105 * If the port is not active, then ip_timestamp contains a timestamp 106 * taken when the port was destroyed. 107 */ 108 109typedef unsigned int ipc_port_timestamp_t; 110 111struct ipc_port { 112 113 /* 114 * Initial sub-structure in common with ipc_pset and rpc_port 115 * First element is an ipc_object 116 */ 117 struct ipc_object ip_object; 118 119 union { 120 struct ipc_space *receiver; 121 struct ipc_port *destination; 122 ipc_port_timestamp_t timestamp; 123 } data; 124 125 ipc_kobject_t ip_kobject; 126 mach_port_mscount_t ip_mscount; 127 mach_port_rights_t ip_srights; 128 mach_port_rights_t ip_sorights; 129 130 struct ipc_port *ip_nsrequest; 131 struct ipc_port *ip_pdrequest; 132 struct ipc_port_request *ip_dnrequests; 133 134 unsigned int ip_pset_count; 135 struct ipc_mqueue ip_messages; 136 struct ipc_kmsg *ip_premsg; 137 138#if NORMA_VM 139 /* 140 * These fields are needed for the use of XMM. 141 * Few ports need this information; it should 142 * be kept in XMM instead (TBD). XXX 143 */ 144 long ip_norma_xmm_object_refs; 145 struct ipc_port *ip_norma_xmm_object; 146#endif 147 148#if MACH_ASSERT 149#define IP_NSPARES 10 150#define IP_CALLSTACK_MAX 10 151 queue_chain_t ip_port_links; /* all allocated ports */ 152 thread_t ip_thread; /* who made me? thread context */ 153 unsigned long ip_timetrack; /* give an idea of "when" created */ 154 natural_t ip_callstack[IP_CALLSTACK_MAX]; /* stack trace */ 155 unsigned long ip_spares[IP_NSPARES]; /* for debugging */ 156#endif /* MACH_ASSERT */ 157 int alias; 158 159//#if MAC 160 struct label ip_label; 161//#endif 162}; 163 164 165#define ip_references ip_object.io_references 166#define ip_bits ip_object.io_bits 167#define ip_receiver_name ip_object.io_receiver_name 168 169#define ip_receiver data.receiver 170#define ip_destination data.destination 171#define ip_timestamp data.timestamp 172 173#define IP_NULL IPC_PORT_NULL 174#define IP_DEAD IPC_PORT_DEAD 175#define IP_VALID(port) IPC_PORT_VALID(port) 176 177#define ip_active(port) io_active(&(port)->ip_object) 178#define ip_lock_init(port) io_lock_init(&(port)->ip_object) 179#define ip_lock(port) io_lock(&(port)->ip_object) 180#define ip_lock_try(port) io_lock_try(&(port)->ip_object) 181#define ip_unlock(port) io_unlock(&(port)->ip_object) 182#define ip_check_unlock(port) io_check_unlock(&(port)->ip_object) 183 184#define ip_reference(port) io_reference(&(port)->ip_object) 185#define ip_release(port) io_release(&(port)->ip_object) 186 187#define ip_kotype(port) io_kotype(&(port)->ip_object) 188 189/* 190 * JMM - Preallocation flag 191 * This flag indicates that there is a message buffer preallocated for this 192 * port and we should use that when sending (from the kernel) rather than 193 * allocate a new one. This avoids deadlocks during notification message 194 * sends by critical system threads (which may be needed to free memory and 195 * therefore cannot be blocked waiting for memory themselves). 196 */ 197#define IP_BIT_PREALLOC 0x00008000 /* preallocated mesg */ 198#define IP_PREALLOC(port) ((port)->ip_bits & IP_BIT_PREALLOC) 199 200#define IP_SET_PREALLOC(port, kmsg) \ 201MACRO_BEGIN \ 202 (port)->ip_bits |= IP_BIT_PREALLOC; \ 203 (port)->ip_premsg = (kmsg); \ 204MACRO_END 205 206#define IP_CLEAR_PREALLOC(port, kmsg) \ 207MACRO_BEGIN \ 208 assert((port)->ip_premsg == kmsg); \ 209 (port)->ip_bits &= ~IP_BIT_PREALLOC; \ 210 (port)->ip_premsg = IKM_NULL; \ 211MACRO_END 212 213 214struct ipc_port_request { 215 union { 216 struct ipc_port *port; 217 ipc_port_request_index_t index; 218 } notify; 219 220 union { 221 mach_port_name_t name; 222 struct ipc_table_size *size; 223 } name; 224}; 225 226#define ipr_next notify.index 227#define ipr_size name.size 228 229#define ipr_soright notify.port 230#define ipr_name name.name 231 232/* 233 * Taking the ipc_port_multiple lock grants the privilege 234 * to lock multiple ports at once. No ports must locked 235 * when it is taken. 236 */ 237 238decl_mutex_data(extern,ipc_port_multiple_lock_data) 239 240#define ipc_port_multiple_lock_init() \ 241 mutex_init(&ipc_port_multiple_lock_data, 0) 242 243#define ipc_port_multiple_lock() \ 244 mutex_lock(&ipc_port_multiple_lock_data) 245 246#define ipc_port_multiple_unlock() \ 247 mutex_unlock(&ipc_port_multiple_lock_data) 248 249/* 250 * The port timestamp facility provides timestamps 251 * for port destruction. It is used to serialize 252 * mach_port_names with port death. 253 */ 254 255decl_mutex_data(extern,ipc_port_timestamp_lock_data) 256extern ipc_port_timestamp_t ipc_port_timestamp_data; 257 258#define ipc_port_timestamp_lock_init() \ 259 mutex_init(&ipc_port_timestamp_lock_data, 0) 260 261#define ipc_port_timestamp_lock() \ 262 mutex_lock(&ipc_port_timestamp_lock_data) 263 264#define ipc_port_timestamp_unlock() \ 265 mutex_unlock(&ipc_port_timestamp_lock_data) 266 267/* Retrieve a port timestamp value */ 268extern ipc_port_timestamp_t ipc_port_timestamp(void); 269 270/* 271 * Compares two timestamps, and returns TRUE if one 272 * happened before two. Note that this formulation 273 * works when the timestamp wraps around at 2^32, 274 * as long as one and two aren't too far apart. 275 */ 276 277#define IP_TIMESTAMP_ORDER(one, two) ((int) ((one) - (two)) < 0) 278 279#define ipc_port_translate_receive(space, name, portp) \ 280 ipc_object_translate((space), (name), \ 281 MACH_PORT_RIGHT_RECEIVE, \ 282 (ipc_object_t *) (portp)) 283 284#define ipc_port_translate_send(space, name, portp) \ 285 ipc_object_translate((space), (name), \ 286 MACH_PORT_RIGHT_SEND, \ 287 (ipc_object_t *) (portp)) 288 289/* Allocate a dead-name request slot */ 290extern kern_return_t 291ipc_port_dnrequest( 292 ipc_port_t port, 293 mach_port_name_t name, 294 ipc_port_t soright, 295 ipc_port_request_index_t *indexp); 296 297/* Grow a port's table of dead-name requests */ 298extern kern_return_t ipc_port_dngrow( 299 ipc_port_t port, 300 ipc_table_elems_t target_size); 301 302/* Cancel a dead-name request and return the send-once right */ 303extern ipc_port_t ipc_port_dncancel( 304 ipc_port_t port, 305 mach_port_name_t name, 306 ipc_port_request_index_t index); 307 308#define ipc_port_dnrename(port, index, oname, nname) \ 309MACRO_BEGIN \ 310 ipc_port_request_t ipr, table; \ 311 \ 312 assert(ip_active(port)); \ 313 \ 314 table = port->ip_dnrequests; \ 315 assert(table != IPR_NULL); \ 316 \ 317 ipr = &table[index]; \ 318 assert(ipr->ipr_name == oname); \ 319 \ 320 ipr->ipr_name = nname; \ 321MACRO_END 322 323/* Make a port-deleted request */ 324extern void ipc_port_pdrequest( 325 ipc_port_t port, 326 ipc_port_t notify, 327 ipc_port_t *previousp); 328 329/* Make a no-senders request */ 330extern void ipc_port_nsrequest( 331 ipc_port_t port, 332 mach_port_mscount_t sync, 333 ipc_port_t notify, 334 ipc_port_t *previousp); 335 336#define ipc_port_set_mscount(port, mscount) \ 337MACRO_BEGIN \ 338 assert(ip_active(port)); \ 339 \ 340 (port)->ip_mscount = (mscount); \ 341MACRO_END 342 343/* Prepare a receive right for transmission/destruction */ 344extern void ipc_port_clear_receiver( 345 ipc_port_t port); 346 347/* Initialize a newly-allocated port */ 348extern void ipc_port_init( 349 ipc_port_t port, 350 ipc_space_t space, 351 mach_port_name_t name); 352 353/* Allocate a port */ 354extern kern_return_t ipc_port_alloc( 355 ipc_space_t space, 356 mach_port_name_t *namep, 357 ipc_port_t *portp); 358 359/* Allocate a port, with a specific name */ 360extern kern_return_t ipc_port_alloc_name( 361 ipc_space_t space, 362 mach_port_name_t name, 363 ipc_port_t *portp); 364 365/* Generate dead name notifications */ 366extern void ipc_port_dnnotify( 367 ipc_port_t port, 368 ipc_port_request_t dnrequests); 369 370/* Destroy a port */ 371extern void ipc_port_destroy( 372 ipc_port_t port); 373 374/* Check if queueing "port" in a message for "dest" would create a circular 375 group of ports and messages */ 376extern boolean_t 377ipc_port_check_circularity( 378 ipc_port_t port, 379 ipc_port_t dest); 380 381/* Make a send-once notify port from a receive right */ 382extern ipc_port_t ipc_port_lookup_notify( 383 ipc_space_t space, 384 mach_port_name_t name); 385 386/* Make a naked send right from a receive right - port locked and active */ 387extern ipc_port_t ipc_port_make_send_locked( 388 ipc_port_t port); 389 390/* Make a naked send right from a receive right */ 391extern ipc_port_t ipc_port_make_send( 392 ipc_port_t port); 393 394/* Make a naked send right from another naked send right */ 395extern ipc_port_t ipc_port_copy_send( 396 ipc_port_t port); 397 398/* Copyout a naked send right */ 399extern mach_port_name_t ipc_port_copyout_send( 400 ipc_port_t sright, 401 ipc_space_t space); 402 403/* Release a (valid) naked send right */ 404extern void ipc_port_release_send( 405 ipc_port_t port); 406 407/* Make a naked send-once right from a receive right */ 408extern ipc_port_t ipc_port_make_sonce( 409 ipc_port_t port); 410 411/* Release a naked send-once right */ 412extern void ipc_port_release_sonce( 413 ipc_port_t port); 414 415/* Release a naked (in limbo or in transit) receive right */ 416extern void ipc_port_release_receive( 417 ipc_port_t port); 418 419/* Allocate a port in a special space */ 420extern ipc_port_t ipc_port_alloc_special( 421 ipc_space_t space); 422 423/* Deallocate a port in a special space */ 424extern void ipc_port_dealloc_special( 425 ipc_port_t port, 426 ipc_space_t space); 427 428#if MACH_ASSERT 429/* Track low-level port deallocation */ 430extern void ipc_port_track_dealloc( 431 ipc_port_t port); 432 433/* Initialize general port debugging state */ 434extern void ipc_port_debug_init(void); 435#endif /* MACH_ASSERT */ 436 437#define ipc_port_alloc_kernel() \ 438 ipc_port_alloc_special(ipc_space_kernel) 439#define ipc_port_dealloc_kernel(port) \ 440 ipc_port_dealloc_special((port), ipc_space_kernel) 441 442#define ipc_port_alloc_reply() \ 443 ipc_port_alloc_special(ipc_space_reply) 444#define ipc_port_dealloc_reply(port) \ 445 ipc_port_dealloc_special((port), ipc_space_reply) 446 447#define ipc_port_reference(port) \ 448 ipc_object_reference(&(port)->ip_object) 449 450#define ipc_port_release(port) \ 451 ipc_object_release(&(port)->ip_object) 452 453#endif /* _IPC_IPC_PORT_H_ */ 454