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 [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_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_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/assert.h>
86 #include <kern/kern_types.h>
87 #include <kern/turnstile.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 #include <ptrauth.h>
97
98 struct task_watchport_elem;
99
100 typedef unsigned int ipc_port_timestamp_t;
101
102 struct ipc_port {
103 struct ipc_object ip_object;
104 union {
105 /*
106 * The waitq_eventmask field is only used on the global queues.
107 * We hence repurpose all those bits for our own use.
108 *
109 * Note: if too many bits are added, compilation will fail
110 * with errors about "negative bitfield sizes"
111 */
112 WAITQ_FLAGS(ip_waitq
113 , ip_fullwaiters:1 /* Whether there are senders blocked on a full queue */
114 , ip_sprequests:1 /* send-possible requests outstanding */
115 , ip_spimportant:1 /* ... at least one is importance donating */
116 , ip_impdonation:1 /* port supports importance donation */
117 , ip_tempowner:1 /* dont give donations to current receiver */
118 , ip_guarded:1 /* port guarded (use context value as guard) */
119 , ip_strict_guard:1 /* Strict guarding; Prevents user manipulation of context values directly */
120 , ip_specialreply:1 /* port is a special reply port */
121 , ip_sync_link_state:3 /* link the port to destination port/ Workloop */
122 , ip_sync_bootstrap_checkin:1 /* port part of sync bootstrap checkin, push on thread doing the checkin */
123 , ip_immovable_receive:1 /* the receive right cannot be moved out of a space, until it is destroyed */
124 , ip_no_grant:1 /* Port wont accept complex messages containing (ool) port descriptors */
125 , ip_immovable_send:1 /* No send(once) rights to this port can be moved out of a space, never unset */
126 , ip_tg_block_tracking:1 /* Track blocking relationship between thread groups during sync IPC */
127 , ip_pinned:1 /* Can't deallocate the last send right from a space while the bit is set */
128 , ip_service_port:1 /* port is a service port */
129 , ip_has_watchport:1 /* port has an exec watchport */
130 , ip_kernel_iotier_override:2 /* kernel iotier override */
131 , ip_kernel_qos_override:3 /* kernel qos override */
132 #if DEVELOPMENT || DEBUG
133 , ip_srp_lost_link:1 /* special reply port turnstile link chain broken */
134 , ip_srp_msg_sent:1 /* special reply port msg sent */
135 #endif
136 );
137 struct waitq ip_waitq;
138 };
139
140 struct ipc_mqueue ip_messages;
141
142 /*
143 * IMPORTANT: Direct access of unionized fields are highly discouraged.
144 * Use accessor functions below and see header doc for possible states.
145 */
146 union {
147 struct ipc_space *XNU_PTRAUTH_SIGNED_PTR("ipc_port.ip_receiver") ip_receiver;
148 struct ipc_port *XNU_PTRAUTH_SIGNED_PTR("ipc_port.ip_destination") ip_destination;
149 ipc_port_timestamp_t ip_timestamp;
150 };
151
152 /* update ipc_kobject_upgrade() if this union is changed */
153 union {
154 uintptr_t ip_kobject; /* manually PAC-ed, see ipc_kobject_get_raw() */
155 ipc_importance_task_t ip_imp_task; /* use accessor ip_get_imp_task() */
156 struct ipc_port *ip_sync_inheritor_port;
157 struct knote *ip_sync_inheritor_knote;
158 struct turnstile *ip_sync_inheritor_ts;
159 };
160
161 /*
162 * ip_specialreply: ip_pid
163 * ip_has_watchport: ip_twe
164 * else: ip_pdrequest
165 */
166 union {
167 int ip_pid;
168 struct task_watchport_elem *XNU_PTRAUTH_SIGNED_PTR("ipc_port.ip_twe") ip_twe;
169 struct ipc_port *XNU_PTRAUTH_SIGNED_PTR("ipc_port.ip_pdrequest") ip_pdrequest;
170 };
171
172 #define IP_KOBJECT_NSREQUEST_ARMED ((struct ipc_port *)1)
173 struct ipc_port *ip_nsrequest;
174 struct ipc_port_request *ip_requests;
175 union {
176 struct ipc_kmsg *XNU_PTRAUTH_SIGNED_PTR("ipc_port.premsg") ip_premsg;
177 struct turnstile *ip_send_turnstile;
178 };
179 mach_vm_address_t ip_context;
180
181 natural_t ip_impcount; /* number of importance donations in nested queue */
182 mach_port_mscount_t ip_mscount;
183 mach_port_rights_t ip_srights;
184 mach_port_rights_t ip_sorights;
185
186 union {
187 ipc_kobject_label_t XNU_PTRAUTH_SIGNED_PTR("ipc_port.kolabel") ip_kolabel;
188 /* Union of service and connection ports' message filtering metadata */
189 void * XNU_PTRAUTH_SIGNED_PTR("ipc_port.ip_splabel") ip_splabel;
190 };
191
192 #if MACH_ASSERT
193 unsigned long ip_timetrack; /* give an idea of "when" created */
194 uint32_t ip_made_bt; /* stack trace (btref_t) */
195 uint32_t ip_made_pid; /* for debugging */
196 #endif /* MACH_ASSERT */
197 };
198
199 static inline bool
ip_in_pset(ipc_port_t port)200 ip_in_pset(ipc_port_t port)
201 {
202 return !circle_queue_empty(&port->ip_waitq.waitq_links);
203 }
204
205 #define ip_receiver_name ip_messages.imq_receiver_name
206 #define ip_reply_context ip_messages.imq_context
207 #define ip_klist ip_messages.imq_klist
208
209 #define port_send_turnstile(port) \
210 (IP_PREALLOC(port) ? (port)->ip_premsg->ikm_turnstile : (port)->ip_send_turnstile)
211
212 #define set_port_send_turnstile(port, value) \
213 MACRO_BEGIN \
214 if (IP_PREALLOC(port)) { \
215 (port)->ip_premsg->ikm_turnstile = (value); \
216 } else { \
217 (port)->ip_send_turnstile = (value); \
218 } \
219 MACRO_END
220
221 #define port_send_turnstile_address(port) \
222 (IP_PREALLOC(port) ? &((port)->ip_premsg->ikm_turnstile) : &((port)->ip_send_turnstile))
223
224 #define port_rcv_turnstile_address(port) (&(port)->ip_waitq.waitq_ts)
225
226
227 /*
228 * SYNC IPC state flags for special reply port/ rcv right.
229 *
230 * PORT_SYNC_LINK_ANY
231 * Special reply port is not linked to any other port
232 * or WL and linkage should be allowed.
233 *
234 * PORT_SYNC_LINK_PORT
235 * Special reply port is linked to the port and
236 * ip_sync_inheritor_port contains the inheritor
237 * port.
238 *
239 * PORT_SYNC_LINK_WORKLOOP_KNOTE
240 * Special reply port is linked to a WL (via a knote).
241 * ip_sync_inheritor_knote contains a pointer to the knote
242 * the port is stashed on.
243 *
244 * PORT_SYNC_LINK_WORKLOOP_STASH
245 * Special reply port is linked to a WL (via a knote stash).
246 * ip_sync_inheritor_ts contains a pointer to the turnstile with a +1
247 * the port is stashed on.
248 *
249 * PORT_SYNC_LINK_NO_LINKAGE
250 * Message sent to special reply port, do
251 * not allow any linkages till receive is
252 * complete.
253 *
254 * PORT_SYNC_LINK_RCV_THREAD
255 * Receive right copied out as a part of bootstrap check in,
256 * push on the thread which copied out the port.
257 */
258 #define PORT_SYNC_LINK_ANY (0)
259 #define PORT_SYNC_LINK_PORT (0x1)
260 #define PORT_SYNC_LINK_WORKLOOP_KNOTE (0x2)
261 #define PORT_SYNC_LINK_WORKLOOP_STASH (0x3)
262 #define PORT_SYNC_LINK_NO_LINKAGE (0x4)
263 #define PORT_SYNC_LINK_RCV_THREAD (0x5)
264
265 #define IP_NULL IPC_PORT_NULL
266 #define IP_DEAD IPC_PORT_DEAD
267 #define IP_VALID(port) IPC_PORT_VALID(port)
268
269 #define ip_object_to_port(io) __container_of(io, struct ipc_port, ip_object)
270 #define ip_to_object(port) (&(port)->ip_object)
271 #define ip_active(port) io_active(ip_to_object(port))
272 #define ip_mq_lock_held(port) io_lock_held(ip_to_object(port))
273 #define ip_mq_lock(port) io_lock(ip_to_object(port))
274 #define ip_mq_lock_try(port) io_lock_try(ip_to_object(port))
275 #define ip_mq_lock_held_kdp(port) io_lock_held_kdp(ip_to_object(port))
276 #define ip_mq_unlock(port) io_unlock(ip_to_object(port))
277
278 #define ip_reference(port) io_reference(ip_to_object(port))
279 #define ip_release(port) io_release(ip_to_object(port))
280 #define ip_release_safe(port) io_release_safe(ip_to_object(port))
281 #define ip_release_live(port) io_release_live(ip_to_object(port))
282
283 #define ip_from_waitq(wq) __container_of(wq, struct ipc_port, ip_waitq)
284 #define ip_from_mq(mq) __container_of(mq, struct ipc_port, ip_messages)
285
286 #define ip_kotype(port) io_kotype(ip_to_object(port))
287 #define ip_is_kobject(port) io_is_kobject(ip_to_object(port))
288 #define ip_is_control(port) \
289 (ip_is_kobject(port) && (ip_kotype(port) == IKOT_TASK_CONTROL || ip_kotype(port) == IKOT_THREAD_CONTROL))
290 #define ip_is_kolabeled(port) io_is_kolabeled(ip_to_object(port))
291
292 #define ip_full_kernel(port) imq_full_kernel(&(port)->ip_messages)
293 #define ip_full(port) imq_full(&(port)->ip_messages)
294
295 #define ip_is_immovable_send(port) ((port)->ip_immovable_send)
296 #define ip_is_pinned(port) ((port)->ip_pinned)
297
298 /* Bits reserved in IO_BITS_PORT_INFO are defined here */
299
300 /*
301 * JMM - Preallocation flag
302 * This flag indicates that there is a message buffer preallocated for this
303 * port and we should use that when sending (from the kernel) rather than
304 * allocate a new one. This avoids deadlocks during notification message
305 * sends by critical system threads (which may be needed to free memory and
306 * therefore cannot be blocked waiting for memory themselves).
307 */
308 #define IP_BIT_PREALLOC 0x00008000 /* preallocated mesg */
309 #define IP_PREALLOC(port) (io_bits(ip_to_object(port)) & IP_BIT_PREALLOC)
310
311 #define IP_SET_PREALLOC(port, kmsg) \
312 MACRO_BEGIN \
313 io_bits_or(ip_to_object(port), IP_BIT_PREALLOC); \
314 (port)->ip_premsg = (kmsg); \
315 MACRO_END
316
317 /*
318 * This flag indicates that the port has opted into message filtering based
319 * on a policy defined in the Sandbox.
320 */
321 #define IP_BIT_FILTER_MSG 0x00001000
322 #define ip_enforce_msg_filtering(port) ((io_bits(ip_to_object(port)) & IP_BIT_FILTER_MSG) != 0)
323
324 /* JMM - address alignment/packing for LP64 */
325 struct ipc_port_request {
326 union {
327 struct ipc_port *port;
328 ipc_port_request_index_t index;
329 } notify;
330
331 union {
332 mach_port_name_t name;
333 struct ipc_table_size *size;
334 } name;
335 };
336
337 #define ipr_next notify.index
338 #define ipr_size name.size
339
340 #define ipr_soright notify.port
341 #define ipr_name name.name
342
343 /*
344 * Use the low bits in the ipr_soright to specify the request type
345 */
346 #define IPR_SOR_SPARM_MASK 1 /* send-possible armed */
347 #define IPR_SOR_SPREQ_MASK 2 /* send-possible requested */
348 #define IPR_SOR_SPBIT_MASK 3 /* combo */
349 #define IPR_SOR_SPARMED(sor) (((uintptr_t)(sor) & IPR_SOR_SPARM_MASK) != 0)
350 #define IPR_SOR_SPREQ(sor) (((uintptr_t)(sor) & IPR_SOR_SPREQ_MASK) != 0)
351 #define IPR_SOR_PORT(sor) ((ipc_port_t)((uintptr_t)(sor) & ~IPR_SOR_SPBIT_MASK))
352 #define IPR_SOR_MAKE(p, m) ((ipc_port_t)((uintptr_t)(p) | (m)))
353
354 extern lck_grp_t ipc_lck_grp;
355 extern lck_attr_t ipc_lck_attr;
356
357 /*
358 * Taking the ipc_port_multiple lock grants the privilege
359 * to lock multiple ports at once. No ports must locked
360 * when it is taken.
361 */
362
363 extern lck_spin_t ipc_port_multiple_lock_data;
364
365 #define ipc_port_multiple_lock() \
366 lck_spin_lock_grp(&ipc_port_multiple_lock_data, &ipc_lck_grp)
367
368 #define ipc_port_multiple_unlock() \
369 lck_spin_unlock(&ipc_port_multiple_lock_data)
370
371 /*
372 * Search for the end of the chain (a port not in transit),
373 * acquiring locks along the way.
374 */
375 extern boolean_t ipc_port_destination_chain_lock(
376 ipc_port_t port,
377 ipc_port_t *base);
378
379 /*
380 * The port timestamp facility provides timestamps
381 * for port destruction. It is used to serialize
382 * mach_port_names with port death.
383 */
384
385 extern ipc_port_timestamp_t ipc_port_timestamp_data;
386
387 /* Retrieve a port timestamp value */
388 extern ipc_port_timestamp_t ipc_port_timestamp(void);
389
390 /*
391 * Compares two timestamps, and returns TRUE if one
392 * happened before two. Note that this formulation
393 * works when the timestamp wraps around at 2^32,
394 * as long as one and two aren't too far apart.
395 */
396
397 #define IP_TIMESTAMP_ORDER(one, two) ((int) ((one) - (two)) < 0)
398
399 extern void __abortlike __ipc_port_inactive_panic(ipc_port_t port);
400
401 static inline void
require_ip_active(ipc_port_t port)402 require_ip_active(ipc_port_t port)
403 {
404 if (!ip_active(port)) {
405 __ipc_port_inactive_panic(port);
406 }
407 }
408
409 /*
410 * A receive right (port) can be in ONE of the following four states:
411 *
412 * 1) INACTIVE: Dead
413 * 2) IN-SPACE: In a space
414 * 3) IN-TRANSIT: Enqueued in a message
415 * 4) IN-LIMBO
416 *
417 * If the port is active and ip_receiver_name != MACH_PORT_NULL, we can safely
418 * deference the union as ip_receiver, which points to the space that holds
419 * receive right (but doesn't hold a ref for it).
420 *
421 * If the port is active and ip_receiver_name == MACH_PORT_NULL, we can safely
422 * deference the union as ip_destination. The port is either IN-LIMBO (ip_destination == IP_NULL)
423 * or ip_destination points to the destination port and holds a ref for it.
424 *
425 * If the port is not active, we can safely deference the union as ip_timestamp,
426 * which contains a timestamp taken when the port was destroyed.
427 *
428 * If the port is in a space, ip_receiver_name denotes the port name its receive
429 * right occupies in the receiving space. The only exception, as an optimization trick,
430 * is task's self port (itk_self), whose ip_receiver_name actually denotes the name
431 * of mach_task_self() in owning task's space (a send right, with receive right in ipc_space_kernel).
432 */
433
434 static inline bool
ip_in_a_space(ipc_port_t port)435 ip_in_a_space(ipc_port_t port)
436 {
437 /* IN-SPACE */
438 return ip_active(port) && port->ip_receiver_name != MACH_PORT_NULL;
439 }
440
441 static inline bool
ip_in_space(ipc_port_t port,ipc_space_t space)442 ip_in_space(ipc_port_t port, ipc_space_t space)
443 {
444 ip_mq_lock_held(port); /* port must be locked, otherwise PAC could fail */
445 return ip_in_a_space(port) && port->ip_receiver == space;
446 }
447
448 /* use sparsely when port lock is not possible, just compare raw pointer */
449 static inline bool
ip_in_space_noauth(ipc_port_t port,void * space)450 ip_in_space_noauth(ipc_port_t port, void* space)
451 {
452 void *raw_ptr = ptrauth_strip(*(void **)&port->ip_receiver, ptrauth_key_process_independent_data);
453 return raw_ptr == space;
454 }
455
456 static inline bool
ip_in_transit(ipc_port_t port)457 ip_in_transit(ipc_port_t port)
458 {
459 /* IN-TRANSIT */
460 ip_mq_lock_held(port); /* port must be locked, otherwise PAC could fail */
461 return ip_active(port) && !ip_in_a_space(port) && port->ip_destination != IP_NULL;
462 }
463
464 static inline bool
ip_in_limbo(ipc_port_t port)465 ip_in_limbo(ipc_port_t port)
466 {
467 /* IN-LIMBO */
468 ip_mq_lock_held(port); /* port must be locked, otherwise PAC could fail */
469 return ip_active(port) && !ip_in_a_space(port) && port->ip_destination == IP_NULL;
470 }
471
472 static inline ipc_space_t
ip_get_receiver(ipc_port_t port)473 ip_get_receiver(ipc_port_t port)
474 {
475 ip_mq_lock_held(port); /* port must be locked, otherwise PAC could fail */
476 return ip_in_a_space(port) ? port->ip_receiver : NULL;
477 }
478
479 static inline void*
ip_get_receiver_ptr_noauth(ipc_port_t port)480 ip_get_receiver_ptr_noauth(ipc_port_t port)
481 {
482 void *raw_ptr = ptrauth_strip(*(void **)&port->ip_receiver, ptrauth_key_process_independent_data);
483 return raw_ptr;
484 }
485
486 static inline mach_port_name_t
ip_get_receiver_name(ipc_port_t port)487 ip_get_receiver_name(ipc_port_t port)
488 {
489 return ip_in_a_space(port) ? port->ip_receiver_name : MACH_PORT_NULL;
490 }
491
492 static inline ipc_port_t
ip_get_destination(ipc_port_t port)493 ip_get_destination(ipc_port_t port)
494 {
495 ip_mq_lock_held(port); /* port must be locked, otherwise PAC could fail */
496 return ip_active(port) && !ip_in_a_space(port) ? port->ip_destination : IP_NULL;
497 }
498
499 static inline ipc_port_timestamp_t
ip_get_death_time(ipc_port_t port)500 ip_get_death_time(ipc_port_t port)
501 {
502 assert(!ip_active(port));
503 return port->ip_timestamp;
504 }
505
506 static inline ipc_importance_task_t
ip_get_imp_task(ipc_port_t port)507 ip_get_imp_task(ipc_port_t port)
508 {
509 return (!ip_is_kobject(port) && !port->ip_specialreply && port->ip_tempowner) ? port->ip_imp_task : IIT_NULL;
510 }
511
512 extern kern_return_t ipc_port_translate_send(
513 ipc_space_t space,
514 mach_port_name_t name,
515 ipc_port_t *portp);
516
517 extern kern_return_t ipc_port_translate_receive(
518 ipc_space_t space,
519 mach_port_name_t name,
520 ipc_port_t *portp);
521
522 /* Allocate a notification request slot */
523 #if IMPORTANCE_INHERITANCE
524 extern kern_return_t ipc_port_request_alloc(
525 ipc_port_t port,
526 mach_port_name_t name,
527 ipc_port_t soright,
528 boolean_t send_possible,
529 boolean_t immediate,
530 ipc_port_request_index_t *indexp,
531 boolean_t *importantp);
532 #else
533 extern kern_return_t ipc_port_request_alloc(
534 ipc_port_t port,
535 mach_port_name_t name,
536 ipc_port_t soright,
537 boolean_t send_possible,
538 boolean_t immediate,
539 ipc_port_request_index_t *indexp);
540 #endif /* IMPORTANCE_INHERITANCE */
541
542 /* Grow one of a port's tables of notifcation requests */
543 extern kern_return_t ipc_port_request_grow(
544 ipc_port_t port,
545 ipc_table_elems_t target_size);
546
547 /* Return the type(s) of notification requests outstanding */
548 extern mach_port_type_t ipc_port_request_type(
549 ipc_port_t port,
550 mach_port_name_t name,
551 ipc_port_request_index_t index);
552
553 /* Cancel a notification request and return the send-once right */
554 extern ipc_port_t ipc_port_request_cancel(
555 ipc_port_t port,
556 mach_port_name_t name,
557 ipc_port_request_index_t index);
558
559 /* Arm any delayed send-possible notification */
560 extern boolean_t ipc_port_request_sparm(
561 ipc_port_t port,
562 mach_port_name_t name,
563 ipc_port_request_index_t index,
564 mach_msg_option_t option,
565 mach_msg_priority_t priority);
566
567 /* Make a no-senders request */
568 extern void ipc_port_nsrequest(
569 ipc_port_t port,
570 mach_port_mscount_t sync,
571 ipc_port_t notify,
572 ipc_port_t *previousp);
573
574 /* Prepare a receive right for transmission/destruction */
575 extern boolean_t ipc_port_clear_receiver(
576 ipc_port_t port,
577 boolean_t should_destroy,
578 waitq_link_list_t *free_l);
579
580 __options_decl(ipc_port_init_flags_t, uint32_t, {
581 IPC_PORT_INIT_NONE = 0x00000000,
582 IPC_PORT_INIT_MAKE_SEND_RIGHT = 0x00000001,
583 IPC_PORT_INIT_MESSAGE_QUEUE = 0x00000002,
584 IPC_PORT_INIT_SPECIAL_REPLY = 0x00000004,
585 IPC_PORT_INIT_FILTER_MESSAGE = 0x00000008,
586 IPC_PORT_INIT_TG_BLOCK_TRACKING = 0x00000010,
587 IPC_PORT_INIT_LOCKED = 0x00000020,
588 });
589
590 /* Initialize a newly-allocated port */
591 extern void ipc_port_init(
592 ipc_port_t port,
593 ipc_space_t space,
594 ipc_port_init_flags_t flags,
595 mach_port_name_t name);
596
597 /* Allocate a port */
598 extern kern_return_t ipc_port_alloc(
599 ipc_space_t space,
600 ipc_port_init_flags_t flags,
601 mach_port_name_t *namep,
602 ipc_port_t *portp);
603
604 /* Allocate a port, with a specific name */
605 extern kern_return_t ipc_port_alloc_name(
606 ipc_space_t space,
607 ipc_port_init_flags_t flags,
608 mach_port_name_t name,
609 ipc_port_t *portp);
610
611 /* Attach a label to the port */
612 extern void ipc_port_set_label(
613 ipc_port_t port,
614 ipc_label_t label);
615
616 /* Generate dead name notifications */
617 extern void ipc_port_dnnotify(
618 ipc_port_t port);
619
620 /* Generate send-possible notifications */
621 extern void ipc_port_spnotify(
622 ipc_port_t port);
623
624 /* Destroy a port */
625 extern void ipc_port_destroy(
626 ipc_port_t port);
627
628 /* Check if queueing "port" in a message for "dest" would create a circular
629 * group of ports and messages */
630 extern boolean_t
631 ipc_port_check_circularity(
632 ipc_port_t port,
633 ipc_port_t dest);
634
635 #if IMPORTANCE_INHERITANCE
636
637 enum {
638 IPID_OPTION_NORMAL = 0, /* normal boost */
639 IPID_OPTION_SENDPOSSIBLE = 1, /* send-possible induced boost */
640 };
641
642 /* link the destination port with special reply port */
643 void
644 ipc_port_link_special_reply_port(
645 ipc_port_t special_reply_port,
646 ipc_port_t dest_port,
647 boolean_t sync_bootstrap_checkin);
648
649 #define IPC_PORT_ADJUST_SR_NONE 0
650 #define IPC_PORT_ADJUST_SR_ALLOW_SYNC_LINKAGE 0x1
651 #define IPC_PORT_ADJUST_SR_LINK_WORKLOOP 0x2
652 #define IPC_PORT_ADJUST_UNLINK_THREAD 0x4
653 #define IPC_PORT_ADJUST_SR_RECEIVED_MSG 0x8
654 #define IPC_PORT_ADJUST_SR_ENABLE_EVENT 0x10
655 #define IPC_PORT_ADJUST_RESET_BOOSTRAP_CHECKIN 0x20
656
657 void
658 ipc_special_reply_port_bits_reset(ipc_port_t special_reply_port);
659
660 void
661 ipc_special_reply_port_msg_sent(ipc_port_t special_reply_port);
662
663 void
664 ipc_special_reply_port_msg_sent(ipc_port_t special_reply_port);
665
666 /* Adjust special reply port linkage */
667 void
668 ipc_port_adjust_special_reply_port_locked(
669 ipc_port_t special_reply_port,
670 struct knote *kn,
671 uint8_t flags,
672 boolean_t get_turnstile);
673
674 void
675 ipc_port_adjust_sync_link_state_locked(
676 ipc_port_t port,
677 int sync_link_state,
678 turnstile_inheritor_t inheritor);
679
680 /* Adjust special reply port linkage */
681 void
682 ipc_port_adjust_special_reply_port(
683 ipc_port_t special_reply_port,
684 uint8_t flags);
685
686 void
687 ipc_port_adjust_port_locked(
688 ipc_port_t port,
689 struct knote *kn,
690 boolean_t sync_bootstrap_checkin);
691
692 void
693 ipc_port_clear_sync_rcv_thread_boost_locked(
694 ipc_port_t port);
695
696 bool
697 ipc_port_has_prdrequest(
698 ipc_port_t port);
699
700 kern_return_t
701 ipc_port_add_watchport_elem_locked(
702 ipc_port_t port,
703 struct task_watchport_elem *watchport_elem,
704 struct task_watchport_elem **old_elem);
705
706 kern_return_t
707 ipc_port_clear_watchport_elem_internal_conditional_locked(
708 ipc_port_t port,
709 struct task_watchport_elem *watchport_elem);
710
711 kern_return_t
712 ipc_port_replace_watchport_elem_conditional_locked(
713 ipc_port_t port,
714 struct task_watchport_elem *old_watchport_elem,
715 struct task_watchport_elem *new_watchport_elem);
716
717 struct task_watchport_elem *
718 ipc_port_clear_watchport_elem_internal(
719 ipc_port_t port);
720
721 void
722 ipc_port_send_turnstile_prepare(ipc_port_t port);
723
724 void
725 ipc_port_send_turnstile_complete(ipc_port_t port);
726
727 struct waitq *
728 ipc_port_rcv_turnstile_waitq(struct waitq *waitq);
729
730 /* apply importance delta to port only */
731 extern mach_port_delta_t
732 ipc_port_impcount_delta(
733 ipc_port_t port,
734 mach_port_delta_t delta,
735 ipc_port_t base);
736
737 /* apply importance delta to port, and return task importance for update */
738 extern boolean_t
739 ipc_port_importance_delta_internal(
740 ipc_port_t port,
741 natural_t options,
742 mach_port_delta_t *deltap,
743 ipc_importance_task_t *imp_task);
744
745 /* Apply an importance delta to a port and reflect change in receiver task */
746 extern boolean_t
747 ipc_port_importance_delta(
748 ipc_port_t port,
749 natural_t options,
750 mach_port_delta_t delta);
751 #endif /* IMPORTANCE_INHERITANCE */
752
753 /* Make a naked send right from a receive right - port locked and active */
754 extern ipc_port_t ipc_port_make_send_locked(
755 ipc_port_t port);
756
757 /* Make a naked send right from a receive right */
758 extern ipc_port_t ipc_port_make_send(
759 ipc_port_t port) __result_use_check;
760
761 /* Make a naked send right from another naked send right - port locked */
762 extern void ipc_port_copy_send_locked(
763 ipc_port_t port);
764
765 /* Make a naked send right from another naked send right */
766 extern ipc_port_t ipc_port_copy_send(
767 ipc_port_t port) __result_use_check;
768
769 /* Copyout a naked send right */
770 extern mach_port_name_t ipc_port_copyout_send(
771 ipc_port_t sright,
772 ipc_space_t space);
773
774 extern mach_port_name_t ipc_port_copyout_send_pinned(
775 ipc_port_t sright,
776 ipc_space_t space);
777
778 extern void ipc_port_thread_group_blocked(
779 ipc_port_t port);
780
781 extern void ipc_port_thread_group_unblocked(void);
782
783 extern void ipc_port_release_send_and_unlock(
784 ipc_port_t port);
785 #endif /* MACH_KERNEL_PRIVATE */
786
787 #if KERNEL_PRIVATE
788
789 /* Release a (valid) naked send right */
790 extern void ipc_port_release_send(
791 ipc_port_t port);
792
793 extern void ipc_port_reference(
794 ipc_port_t port);
795
796 extern void ipc_port_release(
797 ipc_port_t port);
798
799 struct thread_attr_for_ipc_propagation {
800 union {
801 struct {
802 uint64_t tafip_iotier:2,
803 tafip_qos:3;
804 };
805 uint64_t tafip_value;
806 };
807 uint64_t tafip_reserved;
808 };
809
810 extern kern_return_t
811 ipc_port_propagate_thread_attr(
812 ipc_port_t port,
813 struct thread_attr_for_ipc_propagation attr);
814
815 extern kern_return_t
816 ipc_port_reset_thread_attr(ipc_port_t port);
817 #endif /* KERNEL_PRIVATE */
818
819 #ifdef MACH_KERNEL_PRIVATE
820
821 /* Make a naked send-once right from a locked and active receive right */
822 extern ipc_port_t ipc_port_make_sonce_locked(
823 ipc_port_t port);
824
825 /* Make a naked send-once right from a receive right */
826 extern ipc_port_t ipc_port_make_sonce(
827 ipc_port_t port);
828
829 /* Release a naked send-once right */
830 extern void ipc_port_release_sonce(
831 ipc_port_t port);
832
833 /* Release a naked send-once right */
834 extern void ipc_port_release_sonce_and_unlock(
835 ipc_port_t port);
836
837 /* Release a naked (in limbo or in transit) receive right */
838 extern void ipc_port_release_receive(
839 ipc_port_t port);
840
841 /* Finalize the destruction of a port before it gets freed */
842 extern void ipc_port_finalize(
843 ipc_port_t port);
844
845 /* Get receiver task and its pid (if any) for port. */
846 extern pid_t ipc_port_get_receiver_task(ipc_port_t port, uintptr_t *task);
847
848 /* Allocate a port in a special space */
849 extern ipc_port_t ipc_port_alloc_special(
850 ipc_space_t space,
851 ipc_port_init_flags_t flags);
852
853 /* Deallocate a port in a special space */
854 extern void ipc_port_dealloc_special_and_unlock(
855 ipc_port_t port,
856 ipc_space_t space);
857
858 /* Deallocate a port in a special space */
859 extern void ipc_port_dealloc_special(
860 ipc_port_t port,
861 ipc_space_t space);
862
863 extern void ipc_port_recv_update_inheritor(ipc_port_t port,
864 struct turnstile *turnstile,
865 turnstile_update_flags_t flags);
866
867 extern void ipc_port_send_update_inheritor(ipc_port_t port,
868 struct turnstile *turnstile,
869 turnstile_update_flags_t flags);
870
871 extern int
872 ipc_special_reply_get_pid_locked(ipc_port_t port);
873
874 #define ipc_port_alloc_reply() \
875 ipc_port_alloc_special(ipc_space_reply, IPC_PORT_INIT_MESSAGE_QUEUE | IPC_PORT_INIT_SPECIAL_REPLY)
876 #define ipc_port_dealloc_reply(port) \
877 ipc_port_dealloc_special((port), ipc_space_reply)
878
879 #endif /* MACH_KERNEL_PRIVATE */
880
881 #endif /* _IPC_IPC_PORT_H_ */
882