1/*
2 * Copyright (c) 2000-2005 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,1988,1987 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 * Copyright (c) 2005 SPARTA, Inc.
62 */
63/*
64 */
65/*
66 * File: mach/message.h
67 *
68 * Mach IPC message and primitive function definitions.
69 */
70
71#ifndef _MACH_MESSAGE_H_
72#define _MACH_MESSAGE_H_
73
74#include <stddef.h>
75#include <stdint.h>
76#include <machine/limits.h>
77#include <machine/types.h> /* user_addr_t */
78#include <mach/port.h>
79#include <mach/boolean.h>
80#include <mach/kern_return.h>
81#include <mach/machine/vm_types.h>
82
83#include <sys/cdefs.h>
84#include <sys/appleapiopts.h>
85#include <Availability.h>
86#if __has_feature(ptrauth_calls)
87#include <ptrauth.h>
88#endif
89
90/*
91 * The timeout mechanism uses mach_msg_timeout_t values,
92 * passed by value. The timeout units are milliseconds.
93 * It is controlled with the MACH_SEND_TIMEOUT
94 * and MACH_RCV_TIMEOUT options.
95 */
96
97typedef natural_t mach_msg_timeout_t;
98
99/*
100 * The value to be used when there is no timeout.
101 * (No MACH_SEND_TIMEOUT/MACH_RCV_TIMEOUT option.)
102 */
103
104#define MACH_MSG_TIMEOUT_NONE ((mach_msg_timeout_t) 0)
105
106/*
107 * The kernel uses MACH_MSGH_BITS_COMPLEX as a hint. If it isn't on, it
108 * assumes the body of the message doesn't contain port rights or OOL
109 * data. The field is set in received messages. A user task must
110 * use caution in interpreting the body of a message if the bit isn't
111 * on, because the mach_msg_type's in the body might "lie" about the
112 * contents. If the bit isn't on, but the mach_msg_types
113 * in the body specify rights or OOL data, the behavior is undefined.
114 * (Ie, an error may or may not be produced.)
115 *
116 * The value of MACH_MSGH_BITS_REMOTE determines the interpretation
117 * of the msgh_remote_port field. It is handled like a msgt_name,
118 * but must result in a send or send-once type right.
119 *
120 * The value of MACH_MSGH_BITS_LOCAL determines the interpretation
121 * of the msgh_local_port field. It is handled like a msgt_name,
122 * and also must result in a send or send-once type right.
123 *
124 * The value of MACH_MSGH_BITS_VOUCHER determines the interpretation
125 * of the msgh_voucher_port field. It is handled like a msgt_name,
126 * but must result in a send right (and the msgh_voucher_port field
127 * must be the name of a send right to a Mach voucher kernel object.
128 *
129 * MACH_MSGH_BITS() combines two MACH_MSG_TYPE_* values, for the remote
130 * and local fields, into a single value suitable for msgh_bits.
131 *
132 * MACH_MSGH_BITS_CIRCULAR should be zero; is is used internally.
133 *
134 * The unused bits should be zero and are reserved for the kernel
135 * or for future interface expansion.
136 */
137
138#define MACH_MSGH_BITS_ZERO 0x00000000
139
140#define MACH_MSGH_BITS_REMOTE_MASK 0x0000001f
141#define MACH_MSGH_BITS_LOCAL_MASK 0x00001f00
142#define MACH_MSGH_BITS_VOUCHER_MASK 0x001f0000
143
144#define MACH_MSGH_BITS_PORTS_MASK \
145 (MACH_MSGH_BITS_REMOTE_MASK | \
146 MACH_MSGH_BITS_LOCAL_MASK | \
147 MACH_MSGH_BITS_VOUCHER_MASK)
148
149#define MACH_MSGH_BITS_COMPLEX 0x80000000U /* message is complex */
150
151#define MACH_MSGH_BITS_USER 0x801f1f1fU /* allowed bits user->kernel */
152
153#define MACH_MSGH_BITS_RAISEIMP 0x20000000U /* importance raised due to msg */
154#define MACH_MSGH_BITS_DENAP MACH_MSGH_BITS_RAISEIMP
155
156#define MACH_MSGH_BITS_IMPHOLDASRT 0x10000000U /* assertion help, userland private */
157#define MACH_MSGH_BITS_DENAPHOLDASRT MACH_MSGH_BITS_IMPHOLDASRT
158
159#define MACH_MSGH_BITS_CIRCULAR 0x10000000U /* message circular, kernel private */
160
161#define MACH_MSGH_BITS_USED 0xb01f1f1fU
162
163/* setter macros for the bits */
164#define MACH_MSGH_BITS(remote, local) /* legacy */ \
165 ((remote) | ((local) << 8))
166#define MACH_MSGH_BITS_SET_PORTS(remote, local, voucher) \
167 (((remote) & MACH_MSGH_BITS_REMOTE_MASK) | \
168 (((local) << 8) & MACH_MSGH_BITS_LOCAL_MASK) | \
169 (((voucher) << 16) & MACH_MSGH_BITS_VOUCHER_MASK))
170#define MACH_MSGH_BITS_SET(remote, local, voucher, other) \
171 (MACH_MSGH_BITS_SET_PORTS((remote), (local), (voucher)) \
172 | ((other) &~ MACH_MSGH_BITS_PORTS_MASK))
173
174/* getter macros for pulling values out of the bits field */
175#define MACH_MSGH_BITS_REMOTE(bits) \
176 ((bits) & MACH_MSGH_BITS_REMOTE_MASK)
177#define MACH_MSGH_BITS_LOCAL(bits) \
178 (((bits) & MACH_MSGH_BITS_LOCAL_MASK) >> 8)
179#define MACH_MSGH_BITS_VOUCHER(bits) \
180 (((bits) & MACH_MSGH_BITS_VOUCHER_MASK) >> 16)
181#define MACH_MSGH_BITS_PORTS(bits) \
182 ((bits) & MACH_MSGH_BITS_PORTS_MASK)
183#define MACH_MSGH_BITS_OTHER(bits) \
184 ((bits) &~ MACH_MSGH_BITS_PORTS_MASK)
185
186/* checking macros */
187#define MACH_MSGH_BITS_HAS_REMOTE(bits) \
188 (MACH_MSGH_BITS_REMOTE(bits) != MACH_MSGH_BITS_ZERO)
189#define MACH_MSGH_BITS_HAS_LOCAL(bits) \
190 (MACH_MSGH_BITS_LOCAL(bits) != MACH_MSGH_BITS_ZERO)
191#define MACH_MSGH_BITS_HAS_VOUCHER(bits) \
192 (MACH_MSGH_BITS_VOUCHER(bits) != MACH_MSGH_BITS_ZERO)
193#define MACH_MSGH_BITS_IS_COMPLEX(bits) \
194 (((bits) & MACH_MSGH_BITS_COMPLEX) != MACH_MSGH_BITS_ZERO)
195
196/* importance checking macros */
197#define MACH_MSGH_BITS_RAISED_IMPORTANCE(bits) \
198 (((bits) & MACH_MSGH_BITS_RAISEIMP) != MACH_MSGH_BITS_ZERO)
199#define MACH_MSGH_BITS_HOLDS_IMPORTANCE_ASSERTION(bits) \
200 (((bits) & MACH_MSGH_BITS_IMPHOLDASRT) != MACH_MSGH_BITS_ZERO)
201
202/*
203 * Every message starts with a message header.
204 * Following the message header, if the message is complex, are a count
205 * of type descriptors and the type descriptors themselves
206 * (mach_msg_descriptor_t). The size of the message must be specified in
207 * bytes, and includes the message header, descriptor count, descriptors,
208 * and inline data.
209 *
210 * The msgh_remote_port field specifies the destination of the message.
211 * It must specify a valid send or send-once right for a port.
212 *
213 * The msgh_local_port field specifies a "reply port". Normally,
214 * This field carries a send-once right that the receiver will use
215 * to reply to the message. It may carry the values MACH_PORT_NULL,
216 * MACH_PORT_DEAD, a send-once right, or a send right.
217 *
218 * The msgh_voucher_port field specifies a Mach voucher port. Only
219 * send rights to kernel-implemented Mach Voucher kernel objects in
220 * addition to MACH_PORT_NULL or MACH_PORT_DEAD may be passed.
221 *
222 * The msgh_id field is uninterpreted by the message primitives.
223 * It normally carries information specifying the format
224 * or meaning of the message.
225 */
226
227typedef unsigned int mach_msg_bits_t;
228typedef natural_t mach_msg_size_t;
229typedef integer_t mach_msg_id_t;
230
231#define MACH_MSG_SIZE_NULL (mach_msg_size_t *) 0
232
233typedef unsigned int mach_msg_priority_t;
234
235#define MACH_MSG_PRIORITY_UNSPECIFIED (mach_msg_priority_t) 0
236
237
238typedef unsigned int mach_msg_type_name_t;
239
240#define MACH_MSG_TYPE_MOVE_RECEIVE 16 /* Must hold receive right */
241#define MACH_MSG_TYPE_MOVE_SEND 17 /* Must hold send right(s) */
242#define MACH_MSG_TYPE_MOVE_SEND_ONCE 18 /* Must hold sendonce right */
243#define MACH_MSG_TYPE_COPY_SEND 19 /* Must hold send right(s) */
244#define MACH_MSG_TYPE_MAKE_SEND 20 /* Must hold receive right */
245#define MACH_MSG_TYPE_MAKE_SEND_ONCE 21 /* Must hold receive right */
246#define MACH_MSG_TYPE_COPY_RECEIVE 22 /* NOT VALID */
247#define MACH_MSG_TYPE_DISPOSE_RECEIVE 24 /* must hold receive right */
248#define MACH_MSG_TYPE_DISPOSE_SEND 25 /* must hold send right(s) */
249#define MACH_MSG_TYPE_DISPOSE_SEND_ONCE 26 /* must hold sendonce right */
250
251typedef unsigned int mach_msg_copy_options_t;
252
253#define MACH_MSG_PHYSICAL_COPY 0
254#define MACH_MSG_VIRTUAL_COPY 1
255#define MACH_MSG_ALLOCATE 2
256#define MACH_MSG_OVERWRITE 3 /* deprecated */
257#ifdef MACH_KERNEL
258#define MACH_MSG_KALLOC_COPY_T 4
259#endif /* MACH_KERNEL */
260
261#define MACH_MSG_GUARD_FLAGS_NONE 0x0000
262#define MACH_MSG_GUARD_FLAGS_IMMOVABLE_RECEIVE 0x0001 /* Move the receive right and mark it as immovable */
263#define MACH_MSG_GUARD_FLAGS_UNGUARDED_ON_SEND 0x0002 /* Verify that the port is unguarded */
264#define MACH_MSG_GUARD_FLAGS_MASK 0x0003 /* Valid flag bits */
265typedef unsigned int mach_msg_guard_flags_t;
266
267/*
268 * In a complex mach message, the mach_msg_header_t is followed by
269 * a descriptor count, then an array of that number of descriptors
270 * (mach_msg_*_descriptor_t). The type field of mach_msg_type_descriptor_t
271 * (which any descriptor can be cast to) indicates the flavor of the
272 * descriptor.
273 *
274 * Note that in LP64, the various types of descriptors are no longer all
275 * the same size as mach_msg_descriptor_t, so the array cannot be indexed
276 * as expected.
277 */
278
279typedef unsigned int mach_msg_descriptor_type_t;
280
281#define MACH_MSG_PORT_DESCRIPTOR 0
282#define MACH_MSG_OOL_DESCRIPTOR 1
283#define MACH_MSG_OOL_PORTS_DESCRIPTOR 2
284#define MACH_MSG_OOL_VOLATILE_DESCRIPTOR 3
285#define MACH_MSG_GUARDED_PORT_DESCRIPTOR 4
286
287#define MACH_MSG_DESCRIPTOR_MAX MACH_MSG_GUARDED_PORT_DESCRIPTOR
288
289#define __ipc_desc_sign(d)
290
291#pragma pack(push, 4)
292
293typedef struct {
294 natural_t pad1;
295 mach_msg_size_t pad2;
296 unsigned int pad3 : 24;
297 mach_msg_descriptor_type_t type : 8;
298} mach_msg_type_descriptor_t;
299xnu_static_assert_struct_size(mach_msg_type_descriptor_t, 12);
300
301typedef struct {
302 mach_port_t name;
303 mach_msg_size_t pad1;
304 unsigned int pad2 : 16;
305 mach_msg_type_name_t disposition : 8;
306 mach_msg_descriptor_type_t type : 8;
307} mach_msg_port_descriptor_t;
308xnu_static_assert_struct_size_kernel_user(mach_msg_port_descriptor_t, 16, 12);
309
310
311typedef struct {
312 uint32_t address;
313 mach_msg_size_t size;
314 boolean_t deallocate: 8;
315 mach_msg_copy_options_t copy: 8;
316 unsigned int pad1: 8;
317 mach_msg_descriptor_type_t type: 8;
318} mach_msg_ool_descriptor32_t;
319xnu_static_assert_struct_size(mach_msg_ool_descriptor32_t, 12);
320
321typedef struct {
322 uint64_t address;
323 boolean_t deallocate: 8;
324 mach_msg_copy_options_t copy: 8;
325 unsigned int pad1: 8;
326 mach_msg_descriptor_type_t type: 8;
327 mach_msg_size_t size;
328} mach_msg_ool_descriptor64_t;
329xnu_static_assert_struct_size(mach_msg_ool_descriptor64_t, 16);
330
331typedef struct {
332 void *address;
333#if !defined(__LP64__)
334 mach_msg_size_t size;
335#endif
336 boolean_t deallocate: 8;
337 mach_msg_copy_options_t copy: 8;
338 unsigned int pad1: 8;
339 mach_msg_descriptor_type_t type: 8;
340#if defined(__LP64__)
341 mach_msg_size_t size;
342#endif
343} mach_msg_ool_descriptor_t;
344xnu_static_assert_struct_size_kernel_user64_user32(mach_msg_ool_descriptor_t, 16, 16, 12);
345
346typedef struct {
347 uint32_t address;
348 mach_msg_size_t count;
349 boolean_t deallocate: 8;
350 mach_msg_copy_options_t copy: 8;
351 mach_msg_type_name_t disposition : 8;
352 mach_msg_descriptor_type_t type : 8;
353} mach_msg_ool_ports_descriptor32_t;
354xnu_static_assert_struct_size(mach_msg_ool_descriptor32_t, 12);
355
356typedef struct {
357 uint64_t address;
358 boolean_t deallocate: 8;
359 mach_msg_copy_options_t copy: 8;
360 mach_msg_type_name_t disposition : 8;
361 mach_msg_descriptor_type_t type : 8;
362 mach_msg_size_t count;
363} mach_msg_ool_ports_descriptor64_t;
364xnu_static_assert_struct_size(mach_msg_ool_ports_descriptor64_t, 16);
365
366typedef struct {
367 void *address;
368#if !defined(__LP64__)
369 mach_msg_size_t count;
370#endif
371 boolean_t deallocate: 8;
372 mach_msg_copy_options_t copy: 8;
373 mach_msg_type_name_t disposition : 8;
374 mach_msg_descriptor_type_t type : 8;
375#if defined(__LP64__)
376 mach_msg_size_t count;
377#endif
378} mach_msg_ool_ports_descriptor_t;
379xnu_static_assert_struct_size_kernel_user64_user32(mach_msg_ool_ports_descriptor_t, 16, 16, 12);
380
381typedef struct {
382 uint32_t context;
383 mach_port_name_t name;
384 mach_msg_guard_flags_t flags : 16;
385 mach_msg_type_name_t disposition : 8;
386 mach_msg_descriptor_type_t type : 8;
387} mach_msg_guarded_port_descriptor32_t;
388xnu_static_assert_struct_size(mach_msg_guarded_port_descriptor32_t, 12);
389
390typedef struct {
391 uint64_t context;
392 mach_msg_guard_flags_t flags : 16;
393 mach_msg_type_name_t disposition : 8;
394 mach_msg_descriptor_type_t type : 8;
395 mach_port_name_t name;
396} mach_msg_guarded_port_descriptor64_t;
397xnu_static_assert_struct_size(mach_msg_guarded_port_descriptor64_t, 16);
398
399typedef struct {
400 mach_port_context_t context;
401#if !defined(__LP64__)
402 mach_port_name_t name;
403#endif
404 mach_msg_guard_flags_t flags : 16;
405 mach_msg_type_name_t disposition : 8;
406 mach_msg_descriptor_type_t type : 8;
407#if defined(__LP64__)
408 mach_port_name_t name;
409#endif /* defined(__LP64__) */
410} mach_msg_guarded_port_descriptor_t;
411xnu_static_assert_struct_size_kernel_user64_user32(mach_msg_guarded_port_descriptor_t, 16, 16, 12);
412
413/*
414 * LP64support - This union definition is not really
415 * appropriate in LP64 mode because not all descriptors
416 * are of the same size in that environment.
417 */
418typedef union {
419 mach_msg_port_descriptor_t port;
420 mach_msg_ool_descriptor_t out_of_line;
421 mach_msg_ool_ports_descriptor_t ool_ports;
422 mach_msg_type_descriptor_t type;
423 mach_msg_guarded_port_descriptor_t guarded_port;
424} mach_msg_descriptor_t;
425xnu_static_assert_struct_size_kernel_user64_user32(mach_msg_descriptor_t, 16, 16, 12);
426
427typedef struct {
428 mach_msg_size_t msgh_descriptor_count;
429} mach_msg_body_t;
430xnu_static_assert_struct_size(mach_msg_body_t, 4);
431
432#define MACH_MSG_BODY_NULL ((mach_msg_body_t *) 0)
433#define MACH_MSG_DESCRIPTOR_NULL ((mach_msg_descriptor_t *) 0)
434
435typedef struct {
436 mach_msg_bits_t msgh_bits;
437 mach_msg_size_t msgh_size;
438 mach_port_t msgh_remote_port;
439 mach_port_t msgh_local_port;
440 mach_port_name_t msgh_voucher_port;
441 mach_msg_id_t msgh_id;
442} mach_msg_header_t;
443xnu_static_assert_struct_size_kernel_user(mach_msg_header_t, 32, 24);
444
445
446#define msgh_reserved msgh_voucher_port
447#define MACH_MSG_NULL ((mach_msg_header_t *) 0)
448
449typedef struct {
450 mach_msg_header_t header;
451 mach_msg_body_t body;
452} mach_msg_base_t;
453xnu_static_assert_struct_size_kernel_user(mach_msg_base_t, 36, 28);
454
455
456typedef unsigned int mach_msg_trailer_type_t;
457
458#define MACH_MSG_TRAILER_FORMAT_0 0
459
460typedef unsigned int mach_msg_trailer_size_t;
461typedef char *mach_msg_trailer_info_t;
462
463typedef struct {
464 mach_msg_trailer_type_t msgh_trailer_type;
465 mach_msg_trailer_size_t msgh_trailer_size;
466} mach_msg_trailer_t;
467xnu_static_assert_struct_size(mach_msg_trailer_t, 8);
468
469/*
470 * The msgh_seqno field carries a sequence number
471 * associated with the received-from port. A port's
472 * sequence number is incremented every time a message
473 * is received from it and included in the received
474 * trailer to help put messages back in sequence if
475 * multiple threads receive and/or process received
476 * messages.
477 */
478typedef struct {
479 mach_msg_trailer_type_t msgh_trailer_type;
480 mach_msg_trailer_size_t msgh_trailer_size;
481 mach_port_seqno_t msgh_seqno;
482} mach_msg_seqno_trailer_t;
483xnu_static_assert_struct_size(mach_msg_seqno_trailer_t, 12);
484
485typedef struct {
486 unsigned int val[2];
487} security_token_t;
488
489typedef struct {
490 mach_msg_trailer_type_t msgh_trailer_type;
491 mach_msg_trailer_size_t msgh_trailer_size;
492 mach_port_seqno_t msgh_seqno;
493 security_token_t msgh_sender;
494} mach_msg_security_trailer_t;
495xnu_static_assert_struct_size(mach_msg_security_trailer_t, 20);
496
497/*
498 * The audit token is an opaque token which identifies
499 * Mach tasks and senders of Mach messages as subjects
500 * to the BSM audit system. Only the appropriate BSM
501 * library routines should be used to interpret the
502 * contents of the audit token as the representation
503 * of the subject identity within the token may change
504 * over time.
505 */
506typedef struct {
507 unsigned int val[8];
508} audit_token_t;
509
510/*
511 * Safe initializer for audit_token_t.
512 * Variables holding unset audit tokens should generally
513 * be initialized to INVALID_AUDIT_TOKEN_VALUE, to allow
514 * unset audit tokens be distinguished from the kernel's
515 * audit token, KERNEL_AUDIT_TOKEN_VALUE. It is `safe'
516 * in that it limits potential damage if such an unset
517 * audit token, or one of its fields, were ever to be
518 * interpreted as valid by mistake. Notably, the pid is
519 * outside of range of valid pids, and none of the
520 * fields correspond to privileged users or groups.
521 */
522#define INVALID_AUDIT_TOKEN_VALUE {{ \
523 UINT_MAX, UINT_MAX, UINT_MAX, UINT_MAX, \
524 UINT_MAX, UINT_MAX, UINT_MAX, UINT_MAX }}
525
526typedef struct {
527 mach_msg_trailer_type_t msgh_trailer_type;
528 mach_msg_trailer_size_t msgh_trailer_size;
529 mach_port_seqno_t msgh_seqno;
530 security_token_t msgh_sender;
531 audit_token_t msgh_audit;
532} mach_msg_audit_trailer_t;
533xnu_static_assert_struct_size(mach_msg_audit_trailer_t, 52);
534
535typedef struct {
536 mach_msg_trailer_type_t msgh_trailer_type;
537 mach_msg_trailer_size_t msgh_trailer_size;
538 mach_port_seqno_t msgh_seqno;
539 security_token_t msgh_sender;
540 audit_token_t msgh_audit;
541 mach_port_context_t msgh_context;
542} mach_msg_context_trailer_t;
543xnu_static_assert_struct_size_kernel_user64_user32(mach_msg_context_trailer_t, 60, 60, 56);
544
545
546
547typedef struct {
548 mach_port_name_t sender;
549} msg_labels_t;
550
551typedef int mach_msg_filter_id;
552#define MACH_MSG_FILTER_POLICY_ALLOW (mach_msg_filter_id)0
553
554/*
555 * Trailer type to pass MAC policy label info as a mach message trailer.
556 *
557 */
558
559typedef struct {
560 mach_msg_trailer_type_t msgh_trailer_type;
561 mach_msg_trailer_size_t msgh_trailer_size;
562 mach_port_seqno_t msgh_seqno;
563 security_token_t msgh_sender;
564 audit_token_t msgh_audit;
565 mach_port_context_t msgh_context;
566 mach_msg_filter_id msgh_ad;
567 msg_labels_t msgh_labels;
568} mach_msg_mac_trailer_t;
569xnu_static_assert_struct_size_kernel_user64_user32(mach_msg_mac_trailer_t, 68, 68, 64);
570
571
572#define MACH_MSG_TRAILER_MINIMUM_SIZE sizeof(mach_msg_trailer_t)
573
574/*
575 * These values can change from release to release - but clearly
576 * code cannot request additional trailer elements one was not
577 * compiled to understand. Therefore, it is safe to use this
578 * constant when the same module specified the receive options.
579 * Otherwise, you run the risk that the options requested by
580 * another module may exceed the local modules notion of
581 * MAX_TRAILER_SIZE.
582 */
583
584typedef mach_msg_mac_trailer_t mach_msg_max_trailer_t;
585#define MAX_TRAILER_SIZE ((mach_msg_size_t)sizeof(mach_msg_max_trailer_t))
586
587/*
588 * Legacy requirements keep us from ever updating these defines (even
589 * when the format_0 trailers gain new option data fields in the future).
590 * Therefore, they shouldn't be used going forward. Instead, the sizes
591 * should be compared against the specific element size requested using
592 * REQUESTED_TRAILER_SIZE.
593 */
594typedef mach_msg_security_trailer_t mach_msg_format_0_trailer_t;
595
596/*typedef mach_msg_mac_trailer_t mach_msg_format_0_trailer_t;
597 */
598
599#define MACH_MSG_TRAILER_FORMAT_0_SIZE sizeof(mach_msg_format_0_trailer_t)
600
601#define KERNEL_SECURITY_TOKEN_VALUE { {0, 1} }
602extern const security_token_t KERNEL_SECURITY_TOKEN;
603
604#define KERNEL_AUDIT_TOKEN_VALUE { {0, 0, 0, 0, 0, 0, 0, 0} }
605extern const audit_token_t KERNEL_AUDIT_TOKEN;
606
607typedef integer_t mach_msg_options_t;
608
609#define MACH_MSG_HEADER_EMPTY (mach_msg_header_t){ }
610
611typedef struct {
612 mach_msg_header_t header;
613} mach_msg_empty_send_t;
614
615typedef struct {
616 mach_msg_header_t header;
617 mach_msg_trailer_t trailer;
618} mach_msg_empty_rcv_t;
619
620typedef union{
621 mach_msg_empty_send_t send;
622 mach_msg_empty_rcv_t rcv;
623} mach_msg_empty_t;
624
625#pragma pack(pop)
626
627/* utility to round the message size - will become machine dependent */
628#define round_msg(x) (((mach_msg_size_t)(x) + sizeof (natural_t) - 1) & \
629 ~(sizeof (natural_t) - 1))
630
631
632/*
633 * There is no fixed upper bound to the size of Mach messages.
634 */
635#define MACH_MSG_SIZE_MAX ((mach_msg_size_t) ~0)
636
637#if defined(__APPLE_API_PRIVATE)
638/*
639 * But architectural limits of a given implementation, or
640 * temporal conditions may cause unpredictable send failures
641 * for messages larger than MACH_MSG_SIZE_RELIABLE.
642 *
643 * In either case, waiting for memory is [currently] outside
644 * the scope of send timeout values provided to IPC.
645 */
646#define MACH_MSG_SIZE_RELIABLE ((mach_msg_size_t) 256 * 1024)
647#endif
648/*
649 * Compatibility definitions, for code written
650 * when there was a msgh_kind instead of msgh_seqno.
651 */
652#define MACH_MSGH_KIND_NORMAL 0x00000000
653#define MACH_MSGH_KIND_NOTIFICATION 0x00000001
654#define msgh_kind msgh_seqno
655#define mach_msg_kind_t mach_port_seqno_t
656
657typedef natural_t mach_msg_type_size_t;
658typedef natural_t mach_msg_type_number_t;
659
660/*
661 * Values received/carried in messages. Tells the receiver what
662 * sort of port right he now has.
663 *
664 * MACH_MSG_TYPE_PORT_NAME is used to transfer a port name
665 * which should remain uninterpreted by the kernel. (Port rights
666 * are not transferred, just the port name.)
667 */
668
669#define MACH_MSG_TYPE_PORT_NONE 0
670
671#define MACH_MSG_TYPE_PORT_NAME 15
672#define MACH_MSG_TYPE_PORT_RECEIVE MACH_MSG_TYPE_MOVE_RECEIVE
673#define MACH_MSG_TYPE_PORT_SEND MACH_MSG_TYPE_MOVE_SEND
674#define MACH_MSG_TYPE_PORT_SEND_ONCE MACH_MSG_TYPE_MOVE_SEND_ONCE
675
676#define MACH_MSG_TYPE_LAST 22 /* Last assigned */
677
678/*
679 * A dummy value. Mostly used to indicate that the actual value
680 * will be filled in later, dynamically.
681 */
682
683#define MACH_MSG_TYPE_POLYMORPHIC ((mach_msg_type_name_t) -1)
684
685/*
686 * Is a given item a port type?
687 */
688
689#define MACH_MSG_TYPE_PORT_ANY(x) \
690 (((x) >= MACH_MSG_TYPE_MOVE_RECEIVE) && \
691 ((x) <= MACH_MSG_TYPE_MAKE_SEND_ONCE))
692
693#define MACH_MSG_TYPE_PORT_ANY_SEND(x) \
694 (((x) >= MACH_MSG_TYPE_MOVE_SEND) && \
695 ((x) <= MACH_MSG_TYPE_MAKE_SEND_ONCE))
696
697#define MACH_MSG_TYPE_PORT_ANY_SEND_ONCE(x) \
698 (((x) == MACH_MSG_TYPE_MOVE_SEND_ONCE) || \
699 ((x) == MACH_MSG_TYPE_MAKE_SEND_ONCE))
700
701#define MACH_MSG_TYPE_PORT_ANY_RIGHT(x) \
702 (((x) >= MACH_MSG_TYPE_MOVE_RECEIVE) && \
703 ((x) <= MACH_MSG_TYPE_MOVE_SEND_ONCE))
704
705typedef integer_t mach_msg_option_t;
706
707#define MACH_MSG_OPTION_NONE 0x00000000
708
709#define MACH_SEND_MSG 0x00000001
710#define MACH_RCV_MSG 0x00000002
711
712#define MACH_RCV_LARGE 0x00000004 /* report large message sizes */
713#define MACH_RCV_LARGE_IDENTITY 0x00000008 /* identify source of large messages */
714
715#define MACH_SEND_TIMEOUT 0x00000010 /* timeout value applies to send */
716#define MACH_SEND_OVERRIDE 0x00000020 /* priority override for send */
717#define MACH_SEND_INTERRUPT 0x00000040 /* don't restart interrupted sends */
718#define MACH_SEND_NOTIFY 0x00000080 /* arm send-possible notify */
719#define MACH_SEND_ALWAYS 0x00010000 /* ignore qlimits - kernel only */
720#define MACH_SEND_FILTER_NONFATAL 0x00010000 /* rejection by message filter should return failure - user only */
721#define MACH_SEND_TRAILER 0x00020000 /* sender-provided trailer */
722#define MACH_SEND_NOIMPORTANCE 0x00040000 /* msg won't carry importance */
723#define MACH_SEND_NODENAP MACH_SEND_NOIMPORTANCE
724#define MACH_SEND_IMPORTANCE 0x00080000 /* msg carries importance - kernel only */
725#define MACH_SEND_SYNC_OVERRIDE 0x00100000 /* msg should do sync IPC override (on legacy kernels) */
726#define MACH_SEND_PROPAGATE_QOS 0x00200000 /* IPC should propagate the caller's QoS */
727#define MACH_SEND_SYNC_USE_THRPRI MACH_SEND_PROPAGATE_QOS /* obsolete name */
728#define MACH_SEND_KERNEL 0x00400000 /* full send from kernel space - kernel only */
729#define MACH_SEND_SYNC_BOOTSTRAP_CHECKIN 0x00800000 /* special reply port should boost thread doing sync bootstrap checkin */
730
731#define MACH_RCV_TIMEOUT 0x00000100 /* timeout value applies to receive */
732#define MACH_RCV_NOTIFY 0x00000000 /* legacy name (value was: 0x00000200) */
733#define MACH_RCV_INTERRUPT 0x00000400 /* don't restart interrupted receive */
734#define MACH_RCV_VOUCHER 0x00000800 /* willing to receive voucher port */
735#define MACH_RCV_OVERWRITE 0x00000000 /* scatter receive (deprecated) */
736#define MACH_RCV_GUARDED_DESC 0x00001000 /* Can receive new guarded descriptor */
737#define MACH_RCV_SYNC_WAIT 0x00004000 /* sync waiter waiting for rcv */
738#define MACH_RCV_SYNC_PEEK 0x00008000 /* sync waiter waiting to peek */
739
740#define MACH_MSG_STRICT_REPLY 0x00000200 /* Enforce specific properties about the reply port, and
741 * the context in which a thread replies to a message.
742 * This flag must be passed on both the SEND and RCV */
743
744
745/*
746 * NOTE: a 0x00------ RCV mask implies to ask for
747 * a MACH_MSG_TRAILER_FORMAT_0 with 0 Elements,
748 * which is equivalent to a mach_msg_trailer_t.
749 *
750 * XXXMAC: unlike the rest of the MACH_RCV_* flags, MACH_RCV_TRAILER_LABELS
751 * needs its own private bit since we only calculate its fields when absolutely
752 * required.
753 */
754#define MACH_RCV_TRAILER_NULL 0
755#define MACH_RCV_TRAILER_SEQNO 1
756#define MACH_RCV_TRAILER_SENDER 2
757#define MACH_RCV_TRAILER_AUDIT 3
758#define MACH_RCV_TRAILER_CTX 4
759#define MACH_RCV_TRAILER_AV 7
760#define MACH_RCV_TRAILER_LABELS 8
761
762#define MACH_RCV_TRAILER_TYPE(x) (((x) & 0xf) << 28)
763#define MACH_RCV_TRAILER_ELEMENTS(x) (((x) & 0xf) << 24)
764#define MACH_RCV_TRAILER_MASK ((0xf << 24))
765
766#define GET_RCV_ELEMENTS(y) (((y) >> 24) & 0xf)
767
768
769/*
770 * XXXMAC: note that in the case of MACH_RCV_TRAILER_LABELS,
771 * we just fall through to mach_msg_max_trailer_t.
772 * This is correct behavior since mach_msg_max_trailer_t is defined as
773 * mac_msg_mac_trailer_t which is used for the LABELS trailer.
774 * It also makes things work properly if MACH_RCV_TRAILER_LABELS is ORed
775 * with one of the other options.
776 */
777
778#define REQUESTED_TRAILER_SIZE_NATIVE(y) \
779 ((mach_msg_trailer_size_t) \
780 ((GET_RCV_ELEMENTS(y) == MACH_RCV_TRAILER_NULL) ? \
781 sizeof(mach_msg_trailer_t) : \
782 ((GET_RCV_ELEMENTS(y) == MACH_RCV_TRAILER_SEQNO) ? \
783 sizeof(mach_msg_seqno_trailer_t) : \
784 ((GET_RCV_ELEMENTS(y) == MACH_RCV_TRAILER_SENDER) ? \
785 sizeof(mach_msg_security_trailer_t) : \
786 ((GET_RCV_ELEMENTS(y) == MACH_RCV_TRAILER_AUDIT) ? \
787 sizeof(mach_msg_audit_trailer_t) : \
788 ((GET_RCV_ELEMENTS(y) == MACH_RCV_TRAILER_CTX) ? \
789 sizeof(mach_msg_context_trailer_t) : \
790 ((GET_RCV_ELEMENTS(y) == MACH_RCV_TRAILER_AV) ? \
791 sizeof(mach_msg_mac_trailer_t) : \
792 sizeof(mach_msg_max_trailer_t))))))))
793
794
795#define REQUESTED_TRAILER_SIZE(y) REQUESTED_TRAILER_SIZE_NATIVE(y)
796
797/*
798 * Much code assumes that mach_msg_return_t == kern_return_t.
799 * This definition is useful for descriptive purposes.
800 *
801 * See <mach/error.h> for the format of error codes.
802 * IPC errors are system 4. Send errors are subsystem 0;
803 * receive errors are subsystem 1. The code field is always non-zero.
804 * The high bits of the code field communicate extra information
805 * for some error codes. MACH_MSG_MASK masks off these special bits.
806 */
807
808typedef kern_return_t mach_msg_return_t;
809
810#define MACH_MSG_SUCCESS 0x00000000
811
812
813#define MACH_MSG_MASK 0x00003e00
814/* All special error code bits defined below. */
815#define MACH_MSG_IPC_SPACE 0x00002000
816/* No room in IPC name space for another capability name. */
817#define MACH_MSG_VM_SPACE 0x00001000
818/* No room in VM address space for out-of-line memory. */
819#define MACH_MSG_IPC_KERNEL 0x00000800
820/* Kernel resource shortage handling an IPC capability. */
821#define MACH_MSG_VM_KERNEL 0x00000400
822/* Kernel resource shortage handling out-of-line memory. */
823
824#define MACH_SEND_IN_PROGRESS 0x10000001
825/* Thread is waiting to send. (Internal use only.) */
826#define MACH_SEND_INVALID_DATA 0x10000002
827/* Bogus in-line data. */
828#define MACH_SEND_INVALID_DEST 0x10000003
829/* Bogus destination port. */
830#define MACH_SEND_TIMED_OUT 0x10000004
831/* Message not sent before timeout expired. */
832#define MACH_SEND_INVALID_VOUCHER 0x10000005
833/* Bogus voucher port. */
834#define MACH_SEND_INTERRUPTED 0x10000007
835/* Software interrupt. */
836#define MACH_SEND_MSG_TOO_SMALL 0x10000008
837/* Data doesn't contain a complete message. */
838#define MACH_SEND_INVALID_REPLY 0x10000009
839/* Bogus reply port. */
840#define MACH_SEND_INVALID_RIGHT 0x1000000a
841/* Bogus port rights in the message body. */
842#define MACH_SEND_INVALID_NOTIFY 0x1000000b
843/* Bogus notify port argument. */
844#define MACH_SEND_INVALID_MEMORY 0x1000000c
845/* Invalid out-of-line memory pointer. */
846#define MACH_SEND_NO_BUFFER 0x1000000d
847/* No message buffer is available. */
848#define MACH_SEND_TOO_LARGE 0x1000000e
849/* Send is too large for port */
850#define MACH_SEND_INVALID_TYPE 0x1000000f
851/* Invalid msg-type specification. */
852#define MACH_SEND_INVALID_HEADER 0x10000010
853/* A field in the header had a bad value. */
854#define MACH_SEND_INVALID_TRAILER 0x10000011
855/* The trailer to be sent does not match kernel format. */
856#define MACH_SEND_INVALID_CONTEXT 0x10000012
857/* The sending thread context did not match the context on the dest port */
858#define MACH_SEND_INVALID_OPTIONS 0x10000013
859/* Send options are invalid. */
860#define MACH_SEND_INVALID_RT_OOL_SIZE 0x10000015
861/* compatibility: no longer a returned error */
862#define MACH_SEND_NO_GRANT_DEST 0x10000016
863/* compatibility: no longer a returned error */
864#define MACH_SEND_MSG_FILTERED 0x10000017
865/* Message send was rejected by message filter */
866#define MACH_SEND_AUX_TOO_SMALL 0x10000018
867/* Message auxiliary data is too small */
868#define MACH_SEND_AUX_TOO_LARGE 0x10000019
869/* Message auxiliary data is too large */
870
871#define MACH_RCV_IN_PROGRESS 0x10004001
872/* Thread is waiting for receive. (Internal use only.) */
873#define MACH_RCV_INVALID_NAME 0x10004002
874/* Bogus name for receive port/port-set. */
875#define MACH_RCV_TIMED_OUT 0x10004003
876/* Didn't get a message within the timeout value. */
877#define MACH_RCV_TOO_LARGE 0x10004004
878/* Message buffer is not large enough for inline data. */
879#define MACH_RCV_INTERRUPTED 0x10004005
880/* Software interrupt. */
881#define MACH_RCV_PORT_CHANGED 0x10004006
882/* compatibility: no longer a returned error */
883#define MACH_RCV_INVALID_NOTIFY 0x10004007
884/* Bogus notify port argument. */
885#define MACH_RCV_INVALID_DATA 0x10004008
886/* Bogus message buffer for inline data. */
887#define MACH_RCV_PORT_DIED 0x10004009
888/* Port/set was sent away/died during receive. */
889#define MACH_RCV_IN_SET 0x1000400a
890/* compatibility: no longer a returned error */
891#define MACH_RCV_HEADER_ERROR 0x1000400b
892/* Error receiving message header. See special bits. */
893#define MACH_RCV_BODY_ERROR 0x1000400c
894/* Error receiving message body. See special bits. */
895#define MACH_RCV_INVALID_TYPE 0x1000400d
896/* Invalid msg-type specification in scatter list. */
897#define MACH_RCV_SCATTER_SMALL 0x1000400e
898/* Out-of-line overwrite region is not large enough */
899#define MACH_RCV_INVALID_TRAILER 0x1000400f
900/* trailer type or number of trailer elements not supported */
901#define MACH_RCV_IN_PROGRESS_TIMED 0x10004011
902/* Waiting for receive with timeout. (Internal use only.) */
903#define MACH_RCV_INVALID_REPLY 0x10004012
904/* invalid reply port used in a STRICT_REPLY message */
905#define MACH_RCV_INVALID_ARGUMENTS 0x10004013
906/* invalid receive arguments, receive has not started */
907
908
909__BEGIN_DECLS
910
911/*
912 * Routine: mach_msg_overwrite
913 * Purpose:
914 * Send and/or receive a message. If the message operation
915 * is interrupted, and the user did not request an indication
916 * of that fact, then restart the appropriate parts of the
917 * operation silently (trap version does not restart).
918 *
919 * Distinct send and receive buffers may be specified. If
920 * no separate receive buffer is specified, the msg parameter
921 * will be used for both send and receive operations.
922 *
923 * In addition to a distinct receive buffer, that buffer may
924 * already contain scatter control information to direct the
925 * receiving of the message.
926 */
927__WATCHOS_PROHIBITED __TVOS_PROHIBITED
928extern mach_msg_return_t mach_msg_overwrite(
929 mach_msg_header_t *msg,
930 mach_msg_option_t option,
931 mach_msg_size_t send_size,
932 mach_msg_size_t rcv_size,
933 mach_port_name_t rcv_name,
934 mach_msg_timeout_t timeout,
935 mach_port_name_t notify,
936 mach_msg_header_t *rcv_msg,
937 mach_msg_size_t rcv_limit);
938
939
940/*
941 * Routine: mach_msg
942 * Purpose:
943 * Send and/or receive a message. If the message operation
944 * is interrupted, and the user did not request an indication
945 * of that fact, then restart the appropriate parts of the
946 * operation silently (trap version does not restart).
947 */
948__WATCHOS_PROHIBITED __TVOS_PROHIBITED
949extern mach_msg_return_t mach_msg(
950 mach_msg_header_t *msg,
951 mach_msg_option_t option,
952 mach_msg_size_t send_size,
953 mach_msg_size_t rcv_size,
954 mach_port_name_t rcv_name,
955 mach_msg_timeout_t timeout,
956 mach_port_name_t notify);
957
958
959/*
960 * Routine: mach_voucher_deallocate
961 * Purpose:
962 * Deallocate a mach voucher created or received in a message. Drops
963 * one (send right) reference to the voucher.
964 */
965__WATCHOS_PROHIBITED __TVOS_PROHIBITED
966extern kern_return_t mach_voucher_deallocate(
967 mach_port_name_t voucher);
968
969
970__END_DECLS
971
972#endif /* _MACH_MESSAGE_H_ */