]> git.saurik.com Git - apple/xnu.git/blob - osfmk/ipc/ipc_port.h
cde159cd00f6b6f29f7b6aff0902713f2abdf90c
[apple/xnu.git] / osfmk / ipc / ipc_port.h
1 /*
2 * Copyright (c) 2000-2016 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 #ifdef MACH_KERNEL_PRIVATE
76
77 #include <mach_rt.h>
78 #include <mach_assert.h>
79 #include <mach_debug.h>
80
81 #include <mach/mach_types.h>
82 #include <mach/boolean.h>
83 #include <mach/kern_return.h>
84 #include <mach/port.h>
85
86 #include <kern/assert.h>
87 #include <kern/kern_types.h>
88
89 #include <ipc/ipc_types.h>
90 #include <ipc/ipc_object.h>
91 #include <ipc/ipc_mqueue.h>
92 #include <ipc/ipc_space.h>
93
94 #include <security/_label.h>
95
96 /*
97 * A receive right (port) can be in four states:
98 * 1) dead (not active, ip_timestamp has death time)
99 * 2) in a space (ip_receiver_name != 0, ip_receiver points
100 * to the space but doesn't hold a ref for it)
101 * 3) in transit (ip_receiver_name == 0, ip_destination points
102 * to the destination port and holds a ref for it)
103 * 4) in limbo (ip_receiver_name == 0, ip_destination == IP_NULL)
104 *
105 * If the port is active, and ip_receiver points to some space,
106 * then ip_receiver_name != 0, and that space holds receive rights.
107 * If the port is not active, then ip_timestamp contains a timestamp
108 * taken when the port was destroyed.
109 */
110
111 typedef unsigned int ipc_port_timestamp_t;
112
113 struct ipc_port {
114
115 /*
116 * Initial sub-structure in common with ipc_pset
117 * First element is an ipc_object second is a
118 * message queue
119 */
120 struct ipc_object ip_object;
121 struct ipc_mqueue ip_messages;
122
123 union {
124 struct ipc_space *receiver;
125 struct ipc_port *destination;
126 ipc_port_timestamp_t timestamp;
127 } data;
128
129 union {
130 ipc_kobject_t kobject;
131 ipc_importance_task_t imp_task;
132 uintptr_t alias;
133 } kdata;
134
135 struct ipc_port *ip_nsrequest;
136 struct ipc_port *ip_pdrequest;
137 struct ipc_port_request *ip_requests;
138 struct ipc_kmsg *ip_premsg;
139
140 mach_vm_address_t ip_context;
141
142 natural_t ip_sprequests:1, /* send-possible requests outstanding */
143 ip_spimportant:1, /* ... at least one is importance donating */
144 ip_impdonation:1, /* port supports importance donation */
145 ip_tempowner:1, /* dont give donations to current receiver */
146 ip_guarded:1, /* port guarded (use context value as guard) */
147 ip_strict_guard:1, /* Strict guarding; Prevents user manipulation of context values directly */
148 ip_reserved:2,
149 ip_impcount:24; /* number of importance donations in nested queue */
150
151 mach_port_mscount_t ip_mscount;
152 mach_port_rights_t ip_srights;
153 mach_port_rights_t ip_sorights;
154
155 #if MACH_ASSERT
156 #define IP_NSPARES 4
157 #define IP_CALLSTACK_MAX 16
158 /* queue_chain_t ip_port_links;*//* all allocated ports */
159 thread_t ip_thread; /* who made me? thread context */
160 unsigned long ip_timetrack; /* give an idea of "when" created */
161 uintptr_t ip_callstack[IP_CALLSTACK_MAX]; /* stack trace */
162 unsigned long ip_spares[IP_NSPARES]; /* for debugging */
163 #endif /* MACH_ASSERT */
164 } __attribute__((__packed__));
165
166
167 #define ip_references ip_object.io_references
168 #define ip_bits ip_object.io_bits
169
170 #define ip_receiver_name ip_messages.imq_receiver_name
171 #define ip_in_pset ip_messages.imq_in_pset
172
173 #define ip_receiver data.receiver
174 #define ip_destination data.destination
175 #define ip_timestamp data.timestamp
176
177 #define ip_kobject kdata.kobject
178 #define ip_imp_task kdata.imp_task
179 #define ip_alias kdata.alias
180
181 #define IP_NULL IPC_PORT_NULL
182 #define IP_DEAD IPC_PORT_DEAD
183 #define IP_VALID(port) IPC_PORT_VALID(port)
184
185 #define ip_active(port) io_active(&(port)->ip_object)
186 #define ip_lock_init(port) io_lock_init(&(port)->ip_object)
187 #define ip_lock(port) io_lock(&(port)->ip_object)
188 #define ip_lock_try(port) io_lock_try(&(port)->ip_object)
189 #define ip_unlock(port) io_unlock(&(port)->ip_object)
190
191 #define ip_reference(port) io_reference(&(port)->ip_object)
192 #define ip_release(port) io_release(&(port)->ip_object)
193
194 /* get an ipc_port pointer from an ipc_mqueue pointer */
195 #define ip_from_mq(mq) ((struct ipc_port *)((void *)( \
196 (char *)(mq) - \
197 __offsetof(struct ipc_port, ip_messages)) \
198 ))
199
200 #define ip_reference_mq(mq) ip_reference(ip_from_mq(mq))
201 #define ip_release_mq(mq) ip_release(ip_from_mq(mq))
202
203 #define ip_kotype(port) io_kotype(&(port)->ip_object)
204
205 #define ip_full_kernel(port) imq_full_kernel(&(port)->ip_messages)
206 #define ip_full(port) imq_full(&(port)->ip_messages)
207
208 /*
209 * JMM - Preallocation flag
210 * This flag indicates that there is a message buffer preallocated for this
211 * port and we should use that when sending (from the kernel) rather than
212 * allocate a new one. This avoids deadlocks during notification message
213 * sends by critical system threads (which may be needed to free memory and
214 * therefore cannot be blocked waiting for memory themselves).
215 */
216 #define IP_BIT_PREALLOC 0x00008000 /* preallocated mesg */
217 #define IP_PREALLOC(port) ((port)->ip_bits & IP_BIT_PREALLOC)
218
219 #define IP_SET_PREALLOC(port, kmsg) \
220 MACRO_BEGIN \
221 (port)->ip_bits |= IP_BIT_PREALLOC; \
222 (port)->ip_premsg = (kmsg); \
223 MACRO_END
224
225 #define IP_CLEAR_PREALLOC(port, kmsg) \
226 MACRO_BEGIN \
227 assert((port)->ip_premsg == kmsg); \
228 (port)->ip_bits &= ~IP_BIT_PREALLOC; \
229 (port)->ip_premsg = IKM_NULL; \
230 MACRO_END
231
232 /* JMM - address alignment/packing for LP64 */
233 struct ipc_port_request {
234 union {
235 struct ipc_port *port;
236 ipc_port_request_index_t index;
237 } notify;
238
239 union {
240 mach_port_name_t name;
241 struct ipc_table_size *size;
242 } name;
243 };
244
245 #define ipr_next notify.index
246 #define ipr_size name.size
247
248 #define ipr_soright notify.port
249 #define ipr_name name.name
250
251 /*
252 * Use the low bits in the ipr_soright to specify the request type
253 */
254 #define IPR_SOR_SPARM_MASK 1 /* send-possible armed */
255 #define IPR_SOR_SPREQ_MASK 2 /* send-possible requested */
256 #define IPR_SOR_SPBIT_MASK 3 /* combo */
257 #define IPR_SOR_SPARMED(sor) (((uintptr_t)(sor) & IPR_SOR_SPARM_MASK) != 0)
258 #define IPR_SOR_SPREQ(sor) (((uintptr_t)(sor) & IPR_SOR_SPREQ_MASK) != 0)
259 #define IPR_SOR_PORT(sor) ((ipc_port_t)((uintptr_t)(sor) & ~IPR_SOR_SPBIT_MASK))
260 #define IPR_SOR_MAKE(p,m) ((ipc_port_t)((uintptr_t)(p) | (m)))
261
262 extern lck_grp_t ipc_lck_grp;
263 extern lck_attr_t ipc_lck_attr;
264
265 /*
266 * Taking the ipc_port_multiple lock grants the privilege
267 * to lock multiple ports at once. No ports must locked
268 * when it is taken.
269 */
270
271 extern lck_spin_t ipc_port_multiple_lock_data;
272
273 #define ipc_port_multiple_lock_init() \
274 lck_spin_init(&ipc_port_multiple_lock_data, &ipc_lck_grp, &ipc_lck_attr)
275
276 #define ipc_port_multiple_lock() \
277 lck_spin_lock(&ipc_port_multiple_lock_data)
278
279 #define ipc_port_multiple_unlock() \
280 lck_spin_unlock(&ipc_port_multiple_lock_data)
281
282 /*
283 * The port timestamp facility provides timestamps
284 * for port destruction. It is used to serialize
285 * mach_port_names with port death.
286 */
287
288 extern ipc_port_timestamp_t ipc_port_timestamp_data;
289
290 /* Retrieve a port timestamp value */
291 extern ipc_port_timestamp_t ipc_port_timestamp(void);
292
293 /*
294 * Compares two timestamps, and returns TRUE if one
295 * happened before two. Note that this formulation
296 * works when the timestamp wraps around at 2^32,
297 * as long as one and two aren't too far apart.
298 */
299
300 #define IP_TIMESTAMP_ORDER(one, two) ((int) ((one) - (two)) < 0)
301
302 #define ipc_port_translate_receive(space, name, portp) \
303 ipc_object_translate((space), (name), \
304 MACH_PORT_RIGHT_RECEIVE, \
305 (ipc_object_t *) (portp))
306
307 #define ipc_port_translate_send(space, name, portp) \
308 ipc_object_translate((space), (name), \
309 MACH_PORT_RIGHT_SEND, \
310 (ipc_object_t *) (portp))
311
312 /* Allocate a notification request slot */
313 #if IMPORTANCE_INHERITANCE
314 extern kern_return_t
315 ipc_port_request_alloc(
316 ipc_port_t port,
317 mach_port_name_t name,
318 ipc_port_t soright,
319 boolean_t send_possible,
320 boolean_t immediate,
321 ipc_port_request_index_t *indexp,
322 boolean_t *importantp);
323 #else
324 extern kern_return_t
325 ipc_port_request_alloc(
326 ipc_port_t port,
327 mach_port_name_t name,
328 ipc_port_t soright,
329 boolean_t send_possible,
330 boolean_t immediate,
331 ipc_port_request_index_t *indexp);
332 #endif /* IMPORTANCE_INHERITANCE */
333
334 /* Grow one of a port's tables of notifcation requests */
335 extern kern_return_t ipc_port_request_grow(
336 ipc_port_t port,
337 ipc_table_elems_t target_size);
338
339 /* Return the type(s) of notification requests outstanding */
340 extern mach_port_type_t ipc_port_request_type(
341 ipc_port_t port,
342 mach_port_name_t name,
343 ipc_port_request_index_t index);
344
345 /* Cancel a notification request and return the send-once right */
346 extern ipc_port_t ipc_port_request_cancel(
347 ipc_port_t port,
348 mach_port_name_t name,
349 ipc_port_request_index_t index);
350
351 /* Arm any delayed send-possible notification */
352 extern boolean_t ipc_port_request_sparm(
353 ipc_port_t port,
354 mach_port_name_t name,
355 ipc_port_request_index_t index,
356 mach_msg_option_t option,
357 mach_msg_priority_t override);
358
359 /* Macros for manipulating a port's dead name notificaiton requests */
360 #define ipc_port_request_rename(port, index, oname, nname) \
361 MACRO_BEGIN \
362 ipc_port_request_t ipr, table; \
363 \
364 assert(ip_active(port)); \
365 \
366 table = port->ip_requests; \
367 assert(table != IPR_NULL); \
368 \
369 ipr = &table[index]; \
370 assert(ipr->ipr_name == oname); \
371 \
372 ipr->ipr_name = nname; \
373 MACRO_END
374
375
376 /* Make a port-deleted request */
377 extern void ipc_port_pdrequest(
378 ipc_port_t port,
379 ipc_port_t notify,
380 ipc_port_t *previousp);
381
382 /* Make a no-senders request */
383 extern void ipc_port_nsrequest(
384 ipc_port_t port,
385 mach_port_mscount_t sync,
386 ipc_port_t notify,
387 ipc_port_t *previousp);
388
389 #define ipc_port_set_mscount(port, mscount) \
390 MACRO_BEGIN \
391 assert(ip_active(port)); \
392 \
393 (port)->ip_mscount = (mscount); \
394 MACRO_END
395
396 /* Prepare a receive right for transmission/destruction */
397 extern boolean_t ipc_port_clear_receiver(
398 ipc_port_t port,
399 boolean_t should_destroy);
400
401 /* Initialize a newly-allocated port */
402 extern void ipc_port_init(
403 ipc_port_t port,
404 ipc_space_t space,
405 mach_port_name_t name);
406
407 /* Allocate a port */
408 extern kern_return_t ipc_port_alloc(
409 ipc_space_t space,
410 mach_port_name_t *namep,
411 ipc_port_t *portp);
412
413 /* Allocate a port, with a specific name */
414 extern kern_return_t ipc_port_alloc_name(
415 ipc_space_t space,
416 mach_port_name_t name,
417 ipc_port_t *portp);
418
419 /* Generate dead name notifications */
420 extern void ipc_port_dnnotify(
421 ipc_port_t port);
422
423 /* Generate send-possible notifications */
424 extern void ipc_port_spnotify(
425 ipc_port_t port);
426
427 /* Destroy a port */
428 extern void ipc_port_destroy(
429 ipc_port_t port);
430
431 /* Check if queueing "port" in a message for "dest" would create a circular
432 group of ports and messages */
433 extern boolean_t
434 ipc_port_check_circularity(
435 ipc_port_t port,
436 ipc_port_t dest);
437
438 #if IMPORTANCE_INHERITANCE
439
440 enum {
441 IPID_OPTION_NORMAL = 0, /* normal boost */
442 IPID_OPTION_SENDPOSSIBLE = 1, /* send-possible induced boost */
443 };
444
445 /* apply importance delta to port only */
446 extern mach_port_delta_t
447 ipc_port_impcount_delta(
448 ipc_port_t port,
449 mach_port_delta_t delta,
450 ipc_port_t base);
451
452 /* apply importance delta to port, and return task importance for update */
453 extern boolean_t
454 ipc_port_importance_delta_internal(
455 ipc_port_t port,
456 natural_t options,
457 mach_port_delta_t *deltap,
458 ipc_importance_task_t *imp_task);
459
460 /* Apply an importance delta to a port and reflect change in receiver task */
461 extern boolean_t
462 ipc_port_importance_delta(
463 ipc_port_t port,
464 natural_t options,
465 mach_port_delta_t delta);
466 #endif /* IMPORTANCE_INHERITANCE */
467
468 /* Make a send-once notify port from a receive right */
469 extern ipc_port_t ipc_port_lookup_notify(
470 ipc_space_t space,
471 mach_port_name_t name);
472
473 /* Make a naked send right from a receive right - port locked and active */
474 extern ipc_port_t ipc_port_make_send_locked(
475 ipc_port_t port);
476
477 /* Make a naked send right from a receive right */
478 extern ipc_port_t ipc_port_make_send(
479 ipc_port_t port);
480
481 /* Make a naked send right from another naked send right */
482 extern ipc_port_t ipc_port_copy_send(
483 ipc_port_t port);
484
485 /* Copyout a naked send right */
486 extern mach_port_name_t ipc_port_copyout_send(
487 ipc_port_t sright,
488 ipc_space_t space);
489
490 #endif /* MACH_KERNEL_PRIVATE */
491
492 #if KERNEL_PRIVATE
493
494 /* Release a (valid) naked send right */
495 extern void ipc_port_release_send(
496 ipc_port_t port);
497
498 extern void ipc_port_reference(
499 ipc_port_t port);
500
501 extern void ipc_port_release(
502 ipc_port_t port);
503
504 #endif /* KERNEL_PRIVATE */
505
506 #ifdef MACH_KERNEL_PRIVATE
507
508 /* Make a naked send-once right from a locked and active receive right */
509 extern ipc_port_t ipc_port_make_sonce_locked(
510 ipc_port_t port);
511
512 /* Make a naked send-once right from a receive right */
513 extern ipc_port_t ipc_port_make_sonce(
514 ipc_port_t port);
515
516 /* Release a naked send-once right */
517 extern void ipc_port_release_sonce(
518 ipc_port_t port);
519
520 /* Release a naked (in limbo or in transit) receive right */
521 extern void ipc_port_release_receive(
522 ipc_port_t port);
523
524 /* finalize the destruction of a port before it gets freed */
525 extern void ipc_port_finalize(
526 ipc_port_t port);
527
528 /* Allocate a port in a special space */
529 extern ipc_port_t ipc_port_alloc_special(
530 ipc_space_t space);
531
532 /* Deallocate a port in a special space */
533 extern void ipc_port_dealloc_special(
534 ipc_port_t port,
535 ipc_space_t space);
536
537 #if MACH_ASSERT
538 /* Track low-level port deallocation */
539 extern void ipc_port_track_dealloc(
540 ipc_port_t port);
541
542 /* Initialize general port debugging state */
543 extern void ipc_port_debug_init(void);
544 #endif /* MACH_ASSERT */
545
546 #define ipc_port_alloc_kernel() \
547 ipc_port_alloc_special(ipc_space_kernel)
548 #define ipc_port_dealloc_kernel(port) \
549 ipc_port_dealloc_special((port), ipc_space_kernel)
550
551 #define ipc_port_alloc_reply() \
552 ipc_port_alloc_special(ipc_space_reply)
553 #define ipc_port_dealloc_reply(port) \
554 ipc_port_dealloc_special((port), ipc_space_reply)
555
556 #endif /* MACH_KERNEL_PRIVATE */
557
558 #endif /* _IPC_IPC_PORT_H_ */