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