libsyscall/mach/mach/mach_sync_ipc.h

   1 /*
   2  * Copyright (c) 2018 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  * Mach Operating System
  30  * Copyright (c) 1991,1990,1989 Carnegie Mellon University
  31  * All Rights Reserved.
  32  *
  33  * Permission to use, copy, modify and distribute this software and its
  34  * documentation is hereby granted, provided that both the copyright
  35  * notice and this permission notice appear in all copies of the
  36  * software, derivative works or modified versions, and any portions
  37  * thereof, and that both notices appear in supporting documentation.
  38  *
  39  * CARNEGIE MELLON ALLOWS FREE USE OF THIS SOFTWARE IN ITS "AS IS"
  40  * CONDITION.  CARNEGIE MELLON DISCLAIMS ANY LIABILITY OF ANY KIND FOR
  41  * ANY DAMAGES WHATSOEVER RESULTING FROM THE USE OF THIS SOFTWARE.
  42  *
  43  * Carnegie Mellon requests users of this software to return to
  44  *
  45  *  Software Distribution Coordinator  or  Software.Distribution@CS.CMU.EDU
  46  *  School of Computer Science
  47  *  Carnegie Mellon University
  48  *  Pittsburgh PA 15213-3890
  49  *
  50  * any improvements or extensions that they make and grant Carnegie Mellon
  51  * the rights to redistribute these changes.
  52  */
  53
  54 #ifndef _MACH_SYNC_IPC_H_
  55 #define _MACH_SYNC_IPC_H_
  56
  57 #include <mach/mach.h>
  58
  59 __BEGIN_DECLS
  60
  61 /*!
  62  * @function mach_sync_ipc_link_monitoring_start
  63  *
  64  * @abstract
  65  * Starts monitoring the sync IPC priority inversion avoidance
  66  * facility of the current thread.
  67  * A subsequent call to mach_sync_ipc_link_monitoring_stop() will
  68  * validate that the facility took effect for all synchronous IPC
  69  * performed from this thread between the calls to start and stop.
  70  *
  71  * @discussion
  72  * In case of success, a port right is returned, which has to be
  73  * deallocated by passing it to mach_sync_ipc_link_monitoring_stop().
  74  *
  75  * @param port
  76  * Pointer to a mach_port_t that will be populated in case of success.
  77  *
  78  * @result
  79  * KERN_SUCCESS in case of success, specific error otherwise.
  80  * If the call is not supported, KERN_NOT_SUPPORTED is returned.
  81  */
  82 extern kern_return_t mach_sync_ipc_link_monitoring_start(mach_port_t* port);
  83
  84 /*!
  85  * @function mach_sync_ipc_link_monitoring_stop
  86  *
  87  * @abstract
  88  * Stops monitoring the sync IPC priority inversion avoidance facility
  89  * of the current thread started by a call to mach_sync_ipc_link_monitoring_start().
  90  *
  91  * Returns whether the facility took effect for all synchronous IPC performed
  92  * from this thread between the calls to start and stop.
  93  *
  94  * Reasons for this function to return false include:
  95  * -remote message event handler did not reply to the message itself
  96  * -remote message was not received by a workloop (xpc connection or dispatch mach channel)
  97  *
  98  * @discussion
  99  * To be called after mach_sync_ipc_link_monitoring_start(). If
 100  * mach_sync_ipc_link_monitoring_start() didn't return an error this
 101  * function must be called to deallocate the port right that was returned.
 102  *
 103  * @param port
 104  * mach_port_t returned by mach_sync_ipc_link_monitoring_start().
 105  *
 106  * @param in_effect
 107  * Pointer to boolean_t value that will be populated in the case of success.
 108  * Indicates whether the sync IPC priority inversion avoidance facility took
 109  * effect for all synchronous IPC performed from this thread between the calls
 110  * to start and stop.
 111  *
 112  * @result
 113  * KERN_SUCCESS in case of no errors, specific error otherwise.
 114  * If the call is not supported, KERN_NOT_SUPPORTED is returned.
 115  */
 116 extern kern_return_t mach_sync_ipc_link_monitoring_stop(mach_port_t port, boolean_t* in_effect);
 117
 118 typedef enum thread_destruct_special_reply_port_rights {
 119         THREAD_SPECIAL_REPLY_PORT_ALL,
 120         THREAD_SPECIAL_REPLY_PORT_RECEIVE_ONLY,
 121         THREAD_SPECIAL_REPLY_PORT_SEND_ONLY,
 122 } thread_destruct_special_reply_port_rights_t;
 123
 124 extern kern_return_t thread_destruct_special_reply_port(mach_port_name_t port, thread_destruct_special_reply_port_rights_t rights);
 125
 126 extern mach_port_t mig_get_special_reply_port(void);
 127
 128 extern void mig_dealloc_special_reply_port(mach_port_t migport);
 129
 130
 131 __END_DECLS
 132
 133 #endif  /* _MACH_SYNC_IPC_H_ */