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 IPC_OBJECT_COPYIN_FLAGS_ALLOW_REPLY_MAKE_SEND_ONCE = 0x8, /* Port is a reply port. */
104 IPC_OBJECT_COPYIN_FLAGS_ALLOW_REPLY_MOVE_SEND_ONCE = 0x10, /* Port is a reply port. */
105 IPC_OBJECT_COPYIN_FLAGS_ALLOW_IMMOVABLE_RECEIVE = 0x20,
106 IPC_OBJECT_COPYIN_FLAGS_ALLOW_CONN_IMMOVABLE_RECEIVE = 0x40, /* Port is a libxpc connection port. */
107 IPC_OBJECT_COPYIN_FLAGS_DEST_EXTRA_COPY = 0x80,
108 IPC_OBJECT_COPYIN_FLAGS_DEST_EXTRA_MOVE = 0x100,
109 });
110
111 /*
112 * The ipc_object is used to both tag and reference count these two data
113 * structures, and (Noto Bene!) pointers to either of these or the
114 * ipc_object at the head of these are freely cast back and forth; hence
115 * the ipc_object MUST BE FIRST in the ipc_common_data.
116 *
117 * If the RPC implementation enabled user-mode code to use kernel-level
118 * data structures (as ours used to), this peculiar structuring would
119 * avoid having anything in user code depend on the kernel configuration
120 * (with which lock size varies).
121 */
122 struct ipc_object {
123 ipc_object_bits_t _Atomic io_bits;
124 ipc_object_refs_t _Atomic io_references;
125 } __attribute__((aligned(8)));
126
127 /*
128 * IPC steals the high-order bits from the kotype to use
129 * for its own purposes. This allows IPC to record facts
130 * about ports that aren't otherwise obvious from the
131 * existing port fields. In particular, IPC can optionally
132 * mark a port for no more senders detection. Any change
133 * to IO_BITS_PORT_INFO must be coordinated with bitfield
134 * definitions in ipc_port.h.
135 *
136 * Note that the io_bits can be read atomically without
137 * holding the object lock (for example to read the kobject type).
138 * As such updates to this field need to use the io_bits_or()
139 * or io_bits_andnot() functions.
140 */
141 #define IO_BITS_PORT_INFO 0x0000f000 /* stupid port tricks */
142 #define IO_BITS_KOTYPE 0x000003ff /* used by the object */
143 #define IO_BITS_KOLABEL 0x00000400 /* The kobject has a label */
144 #define IO_BITS_OTYPE 0x7fff0000 /* determines a zone */
145 #define IO_BITS_ACTIVE 0x80000000 /* is object alive? */
146
147 #define io_bits(io) atomic_load_explicit(&(io)->io_bits, memory_order_relaxed)
148
149 static inline void
io_bits_or(ipc_object_t io,ipc_object_bits_t bits)150 io_bits_or(ipc_object_t io, ipc_object_bits_t bits)
151 {
152 /*
153 * prevent any possibility for the compiler to tear the update,
154 * the update still requires the io lock to be held.
155 */
156 os_atomic_store(&io->io_bits, io_bits(io) | bits, relaxed);
157 }
158
159 static inline void
io_bits_andnot(ipc_object_t io,ipc_object_bits_t bits)160 io_bits_andnot(ipc_object_t io, ipc_object_bits_t bits)
161 {
162 /*
163 * prevent any possibility for the compiler to tear the update,
164 * the update still requires the io lock to be held.
165 */
166 os_atomic_store(&io->io_bits, io_bits(io) & ~bits, relaxed);
167 }
168
169 #define io_active(io) ((io_bits(io) & IO_BITS_ACTIVE) != 0)
170
171 #define io_otype(io) ((io_bits(io) & IO_BITS_OTYPE) >> 16)
172 #define io_kotype(io) (io_bits(io) & IO_BITS_KOTYPE)
173 #define io_is_kobject(io) (io_kotype(io) != 0)
174 #define io_is_kolabeled(io) ((io_bits(io) & IO_BITS_KOLABEL) != 0)
175 #define io_makebits(otype) (IO_BITS_ACTIVE | ((otype) << 16))
176
177 /*
178 * Object types: ports, port sets, kernel-loaded ports
179 */
180 #define IOT_PORT 0
181 #define IOT_PORT_SET 1
182 #define IOT_NUMBER 2 /* number of types used */
183
184 extern zone_t __single ipc_object_zones[IOT_NUMBER];
185
186 #define io_alloc(otype, flags) \
187 zalloc_flags(ipc_object_zones[otype], flags)
188
189 /*
190 * Here we depend on all ipc_objects being an ipc_wait_queue
191 */
192 #define io_waitq(io) \
193 (&__container_of(io, struct ipc_object_waitq, iowq_object)->iowq_waitq)
194 #define io_from_waitq(waitq) \
195 (&__container_of(waitq, struct ipc_object_waitq, iowq_waitq)->iowq_object)
196
197 #define io_unlock(io) waitq_unlock(io_waitq(io))
198 #define io_lock_held(io) assert(waitq_held(io_waitq(io)))
199 #define io_lock_held_kdp(io) waitq_held(io_waitq(io))
200 #define io_lock_allow_invalid(io) ipc_object_lock_allow_invalid(io)
201
202 #define io_reference(io) ipc_object_reference(io)
203 #define io_release(io) ipc_object_release(io)
204 #define io_release_safe(io) ipc_object_release_safe(io)
205 #define io_release_live(io) ipc_object_release_live(io)
206
207 /*
208 * Exported interfaces
209 */
210
211 extern bool ipc_object_lock_allow_invalid(
212 ipc_object_t object) __result_use_check;
213
214 extern void ipc_object_deallocate_register_queue(void);
215
216 /* Take a reference to an object */
217 extern void ipc_object_reference(
218 ipc_object_t object);
219
220 /* Release a reference to an object */
221 extern void ipc_object_release(
222 ipc_object_t object);
223
224 extern void ipc_object_release_safe(
225 ipc_object_t object);
226
227 /* Release a reference to an object that isn't the last one */
228 extern void ipc_object_release_live(
229 ipc_object_t object);
230
231 /* Look up an object in a space */
232 extern kern_return_t ipc_object_translate(
233 ipc_space_t space,
234 mach_port_name_t name,
235 mach_port_right_t right,
236 ipc_object_t *objectp);
237
238 /* Look up two objects in a space, locking them in the order described */
239 extern kern_return_t ipc_object_translate_port_pset(
240 ipc_space_t space,
241 mach_port_name_t port_name,
242 ipc_port_t *port,
243 mach_port_name_t pset_name,
244 ipc_pset_t *pset);
245
246 /* Validate an object as belonging to the correct zone */
247 extern void ipc_object_validate(
248 ipc_object_t object,
249 ipc_object_type_t type);
250
251 /* Allocate a dead-name entry */
252 extern kern_return_t ipc_object_alloc_dead(
253 ipc_space_t space,
254 mach_port_name_t *namep);
255
256 /* Allocate an object */
257 extern kern_return_t ipc_object_alloc(
258 ipc_space_t space,
259 ipc_object_type_t otype,
260 mach_port_type_t type,
261 mach_port_urefs_t urefs,
262 mach_port_name_t *namep,
263 ipc_object_t *objectp);
264
265 /* Allocate an object, with a specific name */
266 extern kern_return_t ipc_object_alloc_name(
267 ipc_space_t space,
268 ipc_object_type_t otype,
269 mach_port_type_t type,
270 mach_port_urefs_t urefs,
271 mach_port_name_t name,
272 ipc_object_t *objectp,
273 void (^finish_init)(ipc_object_t object));
274
275 /* Convert a send type name to a received type name */
276 extern mach_msg_type_name_t ipc_object_copyin_type(
277 mach_msg_type_name_t msgt_name);
278
279 /* Copyin a capability from a space */
280 extern kern_return_t ipc_object_copyin(
281 ipc_space_t space,
282 mach_port_name_t name,
283 mach_msg_type_name_t msgt_name,
284 ipc_object_copyin_flags_t copyin_flags,
285 mach_msg_guarded_port_descriptor_t *gdesc,
286 ipc_port_t *portp);
287
288 /* Copyin a naked capability from the kernel */
289 extern void ipc_object_copyin_from_kernel(
290 ipc_port_t port,
291 mach_msg_type_name_t msgt_name);
292
293 /* Destroy a naked capability */
294 extern void ipc_object_destroy(
295 ipc_port_t port,
296 mach_msg_type_name_t msgt_name);
297
298 /* Destroy a naked destination capability */
299 extern void ipc_object_destroy_dest(
300 ipc_port_t port,
301 mach_msg_type_name_t msgt_name);
302
303 /* Insert a send right into an object already in the current space */
304 extern kern_return_t ipc_object_insert_send_right(
305 ipc_space_t space,
306 mach_port_name_t name,
307 mach_msg_type_name_t msgt_name);
308
309 /* Copyout a capability, placing it into a space */
310 extern kern_return_t ipc_object_copyout(
311 ipc_space_t space,
312 ipc_port_t port,
313 mach_msg_type_name_t msgt_name,
314 ipc_object_copyout_flags_t flags,
315 mach_msg_guarded_port_descriptor_t *gdesc,
316 mach_port_name_t *namep);
317
318 /* Copyout a capability with a name, placing it into a space */
319 extern kern_return_t ipc_object_copyout_name(
320 ipc_space_t space,
321 ipc_port_t port,
322 mach_msg_type_name_t msgt_name,
323 mach_port_name_t name);
324
325 /* Translate/consume the destination right of a message */
326 extern void ipc_object_copyout_dest(
327 ipc_space_t space,
328 ipc_port_t port,
329 mach_msg_type_name_t msgt_name,
330 mach_port_name_t *namep);
331
332 #pragma GCC visibility pop
333 __ASSUME_PTR_ABI_SINGLE_END __END_DECLS
334
335 #endif /* _IPC_IPC_OBJECT_H_ */
336