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