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 [email protected]
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 <os/atomic_private.h>
76 #include <mach/kern_return.h>
77 #include <mach/message.h>
78 #include <kern/locks.h>
79 #include <kern/macro_help.h>
80 #include <kern/assert.h>
81 #include <kern/zalloc.h>
82 #include <ipc/ipc_types.h>
83 #include <libkern/OSAtomic.h>
84
85 __BEGIN_DECLS __ASSUME_PTR_ABI_SINGLE_BEGIN
86 #pragma GCC visibility push(hidden)
87
88 typedef natural_t ipc_object_refs_t; /* for ipc/ipc_object.h */
89 typedef natural_t ipc_object_bits_t;
90 typedef natural_t ipc_object_type_t;
91
92 __options_closed_decl(ipc_object_copyout_flags_t, uint32_t, {
93 IPC_OBJECT_COPYOUT_FLAGS_NONE = 0x0,
94 IPC_OBJECT_COPYOUT_FLAGS_PINNED = 0x1,
95 IPC_OBJECT_COPYOUT_FLAGS_NO_LABEL_CHECK = 0x2,
96 });
97
98 __options_closed_decl(ipc_object_copyin_flags_t, uint16_t, {
99 IPC_OBJECT_COPYIN_FLAGS_NONE = 0x0,
100 IPC_OBJECT_COPYIN_FLAGS_ALLOW_IMMOVABLE_SEND = 0x1, /* Dest port contains an immovable send right */
101 IPC_OBJECT_COPYIN_FLAGS_ALLOW_DEAD_SEND_ONCE = 0x2,
102 IPC_OBJECT_COPYIN_FLAGS_DEADOK = 0x4,
103 });
104
105 /*
106 * The ipc_object is used to both tag and reference count these two data
107 * structures, and (Noto Bene!) pointers to either of these or the
108 * ipc_object at the head of these are freely cast back and forth; hence
109 * the ipc_object MUST BE FIRST in the ipc_common_data.
110 *
111 * If the RPC implementation enabled user-mode code to use kernel-level
112 * data structures (as ours used to), this peculiar structuring would
113 * avoid having anything in user code depend on the kernel configuration
114 * (with which lock size varies).
115 */
116 struct ipc_object {
117 ipc_object_bits_t _Atomic io_bits;
118 ipc_object_refs_t _Atomic io_references;
119 } __attribute__((aligned(8)));
120
121 /*
122 * Legacy defines. Should use IPC_OBJECT_NULL, etc...
123 */
124 #define IO_NULL ((ipc_object_t) 0)
125 #define IO_DEAD ((ipc_object_t) ~0UL)
126 #define IO_VALID(io) (((io) != IO_NULL) && ((io) != IO_DEAD))
127
128 /*
129 * IPC steals the high-order bits from the kotype to use
130 * for its own purposes. This allows IPC to record facts
131 * about ports that aren't otherwise obvious from the
132 * existing port fields. In particular, IPC can optionally
133 * mark a port for no more senders detection. Any change
134 * to IO_BITS_PORT_INFO must be coordinated with bitfield
135 * definitions in ipc_port.h.
136 *
137 * Note that the io_bits can be read atomically without
138 * holding the object lock (for example to read the kobject type).
139 * As such updates to this field need to use the io_bits_or()
140 * or io_bits_andnot() functions.
141 */
142 #define IO_BITS_PORT_INFO 0x0000f000 /* stupid port tricks */
143 #define IO_BITS_KOTYPE 0x000003ff /* used by the object */
144 #define IO_BITS_KOBJECT 0x00000800 /* port belongs to a kobject */
145 #define IO_BITS_KOLABEL 0x00000400 /* The kobject has a label */
146 #define IO_BITS_OTYPE 0x7fff0000 /* determines a zone */
147 #define IO_BITS_ACTIVE 0x80000000 /* is object alive? */
148
149 #define io_bits(io) os_atomic_load(&(io)->io_bits, relaxed)
150
151 static inline void
io_bits_or(ipc_object_t io,ipc_object_bits_t bits)152 io_bits_or(ipc_object_t io, ipc_object_bits_t bits)
153 {
154 /*
155 * prevent any possibility for the compiler to tear the update,
156 * the update still requires the io lock to be held.
157 */
158 os_atomic_store(&io->io_bits, io_bits(io) | bits, relaxed);
159 }
160
161 static inline void
io_bits_andnot(ipc_object_t io,ipc_object_bits_t bits)162 io_bits_andnot(ipc_object_t io, ipc_object_bits_t bits)
163 {
164 /*
165 * prevent any possibility for the compiler to tear the update,
166 * the update still requires the io lock to be held.
167 */
168 os_atomic_store(&io->io_bits, io_bits(io) & ~bits, relaxed);
169 }
170
171 #define io_active(io) ((io_bits(io) & IO_BITS_ACTIVE) != 0)
172
173 #define io_otype(io) ((io_bits(io) & IO_BITS_OTYPE) >> 16)
174 #define io_kotype(io) (io_bits(io) & IO_BITS_KOTYPE)
175 #define io_is_kobject(io) ((io_bits(io) & IO_BITS_KOBJECT) != 0)
176 #define io_is_kolabeled(io) ((io_bits(io) & IO_BITS_KOLABEL) != 0)
177 #define io_makebits(active, otype, kotype) \
178 (((active) ? IO_BITS_ACTIVE : 0) | ((otype) << 16) | (kotype))
179
180 /*
181 * Object types: ports, port sets, kernel-loaded ports
182 */
183 #define IOT_PORT 0
184 #define IOT_PORT_SET 1
185 #define IOT_NUMBER 2 /* number of types used */
186
187 extern zone_t __single ipc_object_zones[IOT_NUMBER];
188
189 #define io_alloc(otype, flags) \
190 zalloc_flags(ipc_object_zones[otype], flags)
191
192 /*
193 * Here we depend on all ipc_objects being an ipc_wait_queue
194 */
195 #define io_waitq(io) \
196 (&__container_of(io, struct ipc_object_waitq, iowq_object)->iowq_waitq)
197 #define io_from_waitq(waitq) \
198 (&__container_of(waitq, struct ipc_object_waitq, iowq_waitq)->iowq_object)
199
200 #define io_lock(io) ipc_object_lock(io)
201 #define io_lock_try(io) ipc_object_lock_try(io)
202 #define io_unlock(io) ipc_object_unlock(io)
203 #define io_lock_held(io) assert(waitq_held(io_waitq(io)))
204 #define io_lock_held_kdp(io) waitq_held(io_waitq(io))
205 #define io_lock_allow_invalid(io) ipc_object_lock_allow_invalid(io)
206
207 #define io_reference(io) ipc_object_reference(io)
208 #define io_release(io) ipc_object_release(io)
209 #define io_release_safe(io) ipc_object_release_safe(io)
210 #define io_release_live(io) ipc_object_release_live(io)
211
212 /*
213 * Retrieve a label for use in a kernel call that takes a security
214 * label as a parameter. If necessary, io_getlabel acquires internal
215 * (not io_lock) locks, and io_unlocklabel releases them.
216 */
217
218 struct label;
219 extern struct label *io_getlabel(ipc_object_t obj);
220 #define io_unlocklabel(obj)
221
222 /*
223 * Exported interfaces
224 */
225
226 extern void ipc_object_lock(
227 ipc_object_t object);
228
229 #if MACH_LOCKFREE_SPACE
230 extern bool ipc_object_lock_allow_invalid(
231 ipc_object_t object) __result_use_check;
232 #endif
233
234 extern bool ipc_object_lock_try(
235 ipc_object_t object);
236
237 extern void ipc_object_unlock(
238 ipc_object_t object);
239
240 extern void ipc_object_deallocate_register_queue(void);
241
242 /* Take a reference to an object */
243 extern void ipc_object_reference(
244 ipc_object_t object);
245
246 /* Release a reference to an object */
247 extern void ipc_object_release(
248 ipc_object_t object);
249
250 extern void ipc_object_release_safe(
251 ipc_object_t object);
252
253 /* Release a reference to an object that isn't the last one */
254 extern void ipc_object_release_live(
255 ipc_object_t object);
256
257 /* Look up an object in a space */
258 extern kern_return_t ipc_object_translate(
259 ipc_space_t space,
260 mach_port_name_t name,
261 mach_port_right_t right,
262 ipc_object_t *objectp);
263
264 /* Look up two objects in a space, locking them in the order described */
265 extern kern_return_t ipc_object_translate_two(
266 ipc_space_t space,
267 mach_port_name_t name1,
268 mach_port_right_t right1,
269 ipc_object_t *objectp1,
270 mach_port_name_t name2,
271 mach_port_right_t right2,
272 ipc_object_t *objectp2);
273
274 /* Validate an object as belonging to the correct zone */
275 extern void ipc_object_validate(
276 ipc_object_t object);
277
278 /* Allocate a dead-name entry */
279 extern kern_return_t
280 ipc_object_alloc_dead(
281 ipc_space_t space,
282 mach_port_name_t *namep);
283
284 /* Allocate a dead-name entry, with a specific name */
285 extern kern_return_t ipc_object_alloc_dead_name(
286 ipc_space_t space,
287 mach_port_name_t name);
288
289 /* Allocate an object */
290 extern kern_return_t ipc_object_alloc(
291 ipc_space_t space,
292 ipc_object_type_t otype,
293 mach_port_type_t type,
294 mach_port_urefs_t urefs,
295 mach_port_name_t *namep,
296 ipc_object_t *objectp);
297
298 /* Allocate an object, with a specific name */
299 extern kern_return_t ipc_object_alloc_name(
300 ipc_space_t space,
301 ipc_object_type_t otype,
302 mach_port_type_t type,
303 mach_port_urefs_t urefs,
304 mach_port_name_t name,
305 ipc_object_t *objectp,
306 void (^finish_init)(ipc_object_t object));
307
308 /* Convert a send type name to a received type name */
309 extern mach_msg_type_name_t ipc_object_copyin_type(
310 mach_msg_type_name_t msgt_name);
311
312 /* Copyin a capability from a space */
313 extern kern_return_t ipc_object_copyin(
314 ipc_space_t space,
315 mach_port_name_t name,
316 mach_msg_type_name_t msgt_name,
317 ipc_object_t *objectp,
318 mach_port_context_t context,
319 mach_msg_guard_flags_t *guard_flags,
320 ipc_object_copyin_flags_t copyin_flags);
321
322 /* Copyin a naked capability from the kernel */
323 extern void ipc_object_copyin_from_kernel(
324 ipc_object_t object,
325 mach_msg_type_name_t msgt_name);
326
327 /* Destroy a naked capability */
328 extern void ipc_object_destroy(
329 ipc_object_t object,
330 mach_msg_type_name_t msgt_name);
331
332 /* Destroy a naked destination capability */
333 extern void ipc_object_destroy_dest(
334 ipc_object_t object,
335 mach_msg_type_name_t msgt_name);
336
337 /* Insert a send right into an object already in the current space */
338 extern kern_return_t ipc_object_insert_send_right(
339 ipc_space_t space,
340 mach_port_name_t name,
341 mach_msg_type_name_t msgt_name);
342
343 /* Copyout a capability, placing it into a space */
344 extern kern_return_t ipc_object_copyout(
345 ipc_space_t space,
346 ipc_object_t object,
347 mach_msg_type_name_t msgt_name,
348 ipc_object_copyout_flags_t flags,
349 mach_port_context_t *context,
350 mach_msg_guard_flags_t *guard_flags,
351 mach_port_name_t *namep);
352
353 /* Copyout a capability with a name, placing it into a space */
354 extern kern_return_t ipc_object_copyout_name(
355 ipc_space_t space,
356 ipc_object_t object,
357 mach_msg_type_name_t msgt_name,
358 mach_port_name_t name);
359
360 /* Translate/consume the destination right of a message */
361 extern void ipc_object_copyout_dest(
362 ipc_space_t space,
363 ipc_object_t object,
364 mach_msg_type_name_t msgt_name,
365 mach_port_name_t *namep);
366
367 #pragma GCC visibility pop
368 __ASSUME_PTR_ABI_SINGLE_BEGIN __END_DECLS
369
370 #endif /* _IPC_IPC_OBJECT_H_ */
371