1/* 2 * Copyright (c) 2000-2007 Apple 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_object.h 66 * Author: Rich Draves 67 * Date: 1989 68 * 69 * Definitions for IPC objects, for which tasks have capabilities. 70 */ 71 72#ifndef _IPC_IPC_OBJECT_H_ 73#define _IPC_IPC_OBJECT_H_ 74 75#include <mach_rt.h> 76#include <mach_kdb.h> 77 78#include <mach/kern_return.h> 79#include <mach/message.h> 80#include <kern/lock.h> 81#include <kern/macro_help.h> 82#include <kern/zalloc.h> 83#include <ipc/ipc_types.h> 84 85typedef natural_t ipc_object_refs_t; /* for ipc/ipc_object.h */ 86typedef natural_t ipc_object_bits_t; 87typedef natural_t ipc_object_type_t; 88 89/* 90 * There is no lock in the ipc_object; it is in the enclosing kernel 91 * data structure (rpc_common_data) used by both ipc_port and ipc_pset. 92 * The ipc_object is used to both tag and reference count these two data 93 * structures, and (Noto Bene!) pointers to either of these or the 94 * ipc_object at the head of these are freely cast back and forth; hence 95 * the ipc_object MUST BE FIRST in the ipc_common_data. 96 * 97 * If the RPC implementation enabled user-mode code to use kernel-level 98 * data structures (as ours used to), this peculiar structuring would 99 * avoid having anything in user code depend on the kernel configuration 100 * (with which lock size varies). 101 */ 102struct ipc_object { 103 ipc_object_refs_t io_references; 104 ipc_object_bits_t io_bits; 105 mach_port_name_t io_receiver_name; 106 decl_mutex_data(, io_lock_data) 107}; 108 109/* 110 * Legacy defines. Should use IPC_OBJECT_NULL, etc... 111 */ 112#define IO_NULL ((ipc_object_t) 0) 113#define IO_DEAD ((ipc_object_t) -1) 114#define IO_VALID(io) (((io) != IO_NULL) && ((io) != IO_DEAD)) 115 116/* 117 * IPC steals the high-order bits from the kotype to use 118 * for its own purposes. This allows IPC to record facts 119 * about ports that aren't otherwise obvious from the 120 * existing port fields. In particular, IPC can optionally 121 * mark a port for no more senders detection. Any change 122 * to IO_BITS_PORT_INFO must be coordinated with bitfield 123 * definitions in ipc_port.h. 124 */ 125#define IO_BITS_PORT_INFO 0x0000f000 /* stupid port tricks */ 126#define IO_BITS_KOTYPE 0x00000fff /* used by the object */ 127#define IO_BITS_OTYPE 0x7fff0000 /* determines a zone */ 128#define IO_BITS_ACTIVE 0x80000000 /* is object alive? */ 129 130#define io_active(io) ((io)->io_bits & IO_BITS_ACTIVE) 131 132#define io_otype(io) (((io)->io_bits & IO_BITS_OTYPE) >> 16) 133#define io_kotype(io) ((io)->io_bits & IO_BITS_KOTYPE) 134 135#define io_makebits(active, otype, kotype) \ 136 (((active) ? IO_BITS_ACTIVE : 0) | ((otype) << 16) | (kotype)) 137 138/* 139 * Object types: ports, port sets, kernel-loaded ports 140 */ 141#define IOT_PORT 0 142#define IOT_PORT_SET 1 143#define IOT_NUMBER 2 /* number of types used */ 144 145extern zone_t ipc_object_zones[IOT_NUMBER]; 146 147#define io_alloc(otype) \ 148 ((ipc_object_t) zalloc(ipc_object_zones[(otype)])) 149 150#if MACH_ASSERT || CONFIG_MACF_MACH 151/* 152 * Call the routine for io_free so that checking can be performed. 153 */ 154extern void io_free( 155 unsigned int otype, 156 ipc_object_t object); 157 158#else /* MACH_ASSERT || MAC_MACH */ 159#define io_free(otype, io) \ 160 zfree(ipc_object_zones[(otype)], (io)) 161#endif /* MACH_ASSERT || MAC_MACH */ 162 163/* 164 * Here we depend on the ipc_object being first within the ipc_common_data, 165 * which is first within the rpc_common_data, which in turn must be first 166 * within any kernel data structure needing to lock an ipc_object 167 * (ipc_port and ipc_pset). 168 */ 169#define io_lock_init(io) \ 170 mutex_init(&(io)->io_lock_data, 0) 171#define io_lock(io) \ 172 mutex_lock(&(io)->io_lock_data) 173#define io_lock_try(io) \ 174 mutex_try(&(io)->io_lock_data) 175#define io_unlock(io) \ 176 mutex_unlock(&(io)->io_lock_data) 177 178#define _VOLATILE_ volatile 179 180#define io_check_unlock(io) \ 181MACRO_BEGIN \ 182 _VOLATILE_ ipc_object_refs_t _refs = (io)->io_references; \ 183 \ 184 io_unlock(io); \ 185 if (_refs == 0) \ 186 io_free(io_otype(io), io); \ 187MACRO_END 188 189/* Sanity check the ref count. If it is 0, we may be doubly zfreeing. 190 * If it is larger than max int, it has been corrupted, probably by being 191 * modified into an address (this is architecture dependent, but it's 192 * safe to assume there cannot really be max int references). 193 * 194 * NOTE: The 0 test alone will not catch double zfreeing of ipc_port 195 * structs, because the io_references field is the first word of the struct, 196 * and zfree modifies that to point to the next free zone element. 197 */ 198#define IO_MAX_REFERENCES \ 199 (unsigned)(~0 ^ (1 << (sizeof(int)*BYTE_SIZE - 1))) 200 201#define io_reference(io) \ 202MACRO_BEGIN \ 203 assert((io)->io_references < IO_MAX_REFERENCES); \ 204 (io)->io_references++; \ 205MACRO_END 206 207#define io_release(io) \ 208MACRO_BEGIN \ 209 assert((io)->io_references > 0 && \ 210 (io)->io_references <= IO_MAX_REFERENCES); \ 211 (io)->io_references--; \ 212MACRO_END 213 214/* 215 * Retrieve a label for use in a kernel call that takes a security 216 * label as a parameter. If necessary, io_getlabel acquires internal 217 * (not io_lock) locks, and io_unlocklabel releases them. 218 */ 219 220struct label; 221extern struct label *io_getlabel (ipc_object_t obj); 222#define io_unlocklabel(obj) 223 224/* 225 * Exported interfaces 226 */ 227 228/* Take a reference to an object */ 229extern void ipc_object_reference( 230 ipc_object_t object); 231 232/* Release a reference to an object */ 233extern void ipc_object_release( 234 ipc_object_t object); 235 236/* Look up an object in a space */ 237extern kern_return_t ipc_object_translate( 238 ipc_space_t space, 239 mach_port_name_t name, 240 mach_port_right_t right, 241 ipc_object_t *objectp); 242 243/* Look up two objects in a space, locking them in the order described */ 244extern kern_return_t ipc_object_translate_two( 245 ipc_space_t space, 246 mach_port_name_t name1, 247 mach_port_right_t right1, 248 ipc_object_t *objectp1, 249 mach_port_name_t name2, 250 mach_port_right_t right2, 251 ipc_object_t *objectp2); 252 253/* Allocate a dead-name entry */ 254extern kern_return_t 255ipc_object_alloc_dead( 256 ipc_space_t space, 257 mach_port_name_t *namep); 258 259/* Allocate a dead-name entry, with a specific name */ 260extern kern_return_t ipc_object_alloc_dead_name( 261 ipc_space_t space, 262 mach_port_name_t name); 263 264/* Allocate an object */ 265extern kern_return_t ipc_object_alloc( 266 ipc_space_t space, 267 ipc_object_type_t otype, 268 mach_port_type_t type, 269 mach_port_urefs_t urefs, 270 mach_port_name_t *namep, 271 ipc_object_t *objectp); 272 273/* Allocate an object, with a specific name */ 274extern kern_return_t ipc_object_alloc_name( 275 ipc_space_t space, 276 ipc_object_type_t otype, 277 mach_port_type_t type, 278 mach_port_urefs_t urefs, 279 mach_port_name_t name, 280 ipc_object_t *objectp); 281 282/* Convert a send type name to a received type name */ 283extern mach_msg_type_name_t ipc_object_copyin_type( 284 mach_msg_type_name_t msgt_name); 285 286/* Copyin a capability from a space */ 287extern kern_return_t ipc_object_copyin( 288 ipc_space_t space, 289 mach_port_name_t name, 290 mach_msg_type_name_t msgt_name, 291 ipc_object_t *objectp); 292 293/* Copyin a naked capability from the kernel */ 294extern void ipc_object_copyin_from_kernel( 295 ipc_object_t object, 296 mach_msg_type_name_t msgt_name); 297 298/* Destroy a naked capability */ 299extern void ipc_object_destroy( 300 ipc_object_t object, 301 mach_msg_type_name_t msgt_name); 302 303/* Copyout a capability, placing it into a space */ 304extern kern_return_t ipc_object_copyout( 305 ipc_space_t space, 306 ipc_object_t object, 307 mach_msg_type_name_t msgt_name, 308 boolean_t overflow, 309 mach_port_name_t *namep); 310 311/* Copyout a capability with a name, placing it into a space */ 312extern kern_return_t ipc_object_copyout_name( 313 ipc_space_t space, 314 ipc_object_t object, 315 mach_msg_type_name_t msgt_name, 316 boolean_t overflow, 317 mach_port_name_t name); 318 319/* Translate/consume the destination right of a message */ 320extern void ipc_object_copyout_dest( 321 ipc_space_t space, 322 ipc_object_t object, 323 mach_msg_type_name_t msgt_name, 324 mach_port_name_t *namep); 325 326/* Rename an entry in a space */ 327extern kern_return_t ipc_object_rename( 328 ipc_space_t space, 329 mach_port_name_t oname, 330 mach_port_name_t nname); 331 332#if MACH_KDB 333/* Pretty-print an ipc object */ 334 335extern void ipc_object_print( 336 ipc_object_t object); 337 338#endif /* MACH_KDB */ 339 340#endif /* _IPC_IPC_OBJECT_H_ */ 341