osfmk/mach/message.h

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