1 /* 2 * Copyright (c) 2021 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 #ifndef _KERN_LOCK_TYPES_H 29 #define _KERN_LOCK_TYPES_H 30 31 #include <kern/kern_types.h> 32 33 __BEGIN_DECLS 34 35 #ifdef XNU_KERNEL_PRIVATE 36 #if __x86_64__ 37 /* 38 * Extended mutexes are only implemented on x86_64 39 */ 40 #define HAS_EXT_MUTEXES 1 41 #endif /* __x86_64__ */ 42 #endif /* XNU_KERNEL_PRIVATE */ 43 44 /*! 45 * @enum lck_sleep_action_t 46 * 47 * @abstract 48 * An action to pass to the @c lck_*_sleep* family of functions. 49 */ 50 __options_decl(lck_sleep_action_t, unsigned int, { 51 LCK_SLEEP_DEFAULT = 0x00, /**< Release the lock while waiting for the event, then reclaim */ 52 LCK_SLEEP_UNLOCK = 0x01, /**< Release the lock and return unheld */ 53 LCK_SLEEP_SHARED = 0x02, /**< Reclaim the lock in shared mode (RW only) */ 54 LCK_SLEEP_EXCLUSIVE = 0x04, /**< Reclaim the lock in exclusive mode (RW only) */ 55 LCK_SLEEP_SPIN = 0x08, /**< Reclaim the lock in spin mode (mutex only) */ 56 LCK_SLEEP_PROMOTED_PRI = 0x10, /**< Sleep at a promoted priority */ 57 LCK_SLEEP_SPIN_ALWAYS = 0x20, /**< Reclaim the lock in spin-always mode (mutex only) */ 58 }); 59 60 #define LCK_SLEEP_MASK 0x3f /* Valid actions */ 61 62 __options_decl(lck_wake_action_t, unsigned int, { 63 LCK_WAKE_DEFAULT = 0x00, /* If waiters are present, transfer their push to the wokenup thread */ 64 LCK_WAKE_DO_NOT_TRANSFER_PUSH = 0x01, /* Do not transfer waiters push when waking up */ 65 }); 66 67 #if MACH_KERNEL_PRIVATE 68 69 /*! 70 * @enum hw_lock_status_t 71 * 72 * @abstract 73 * Used to pass information about very low level locking primitives. 74 * 75 */ 76 __enum_closed_decl(hw_lock_status_t, int, { 77 /** 78 * The lock was not taken because it is in an invalid state, 79 * or the memory was unmapped. 80 * 81 * This is only valid for @c *_allow_invalid() variants. 82 * 83 * Preemption is preserved to the caller level for all variants. 84 */ 85 HW_LOCK_INVALID = -1, 86 87 /** 88 * the lock wasn't acquired and is contended / timed out. 89 * 90 * - @c *_nopreempt() variants: preemption level preserved 91 * - @c *_trylock() variants: preemption level preserved 92 * - other variants: preemption is disabled 93 */ 94 HW_LOCK_CONTENDED = 0, 95 96 /** 97 * the lock was acquired successfully 98 * 99 * - @c *_nopreempt() variants: preemption level preserved 100 * - other variants: preemption is disabled 101 */ 102 HW_LOCK_ACQUIRED = 1, 103 }); 104 105 /*! 106 * @enum hw_lock_timeout_status_t 107 * 108 * @abstract 109 * Used by spinlock timeout handlers. 110 * 111 * @const HW_LOCK_TIMEOUT_RETURN 112 * Tell the @c hw_lock*_to* caller to break out of the wait 113 * and return HW_LOCK_CONTENDED. 114 * 115 * @const HW_LOCK_TIMEOUT_CONTINUE 116 * Keep spinning for another "timeout". 117 */ 118 __enum_closed_decl(hw_lock_timeout_status_t, _Bool, { 119 HW_LOCK_TIMEOUT_RETURN, /**< return without taking the lock */ 120 HW_LOCK_TIMEOUT_CONTINUE, /**< keep spinning */ 121 }); 122 123 /*! 124 * @typedef hw_lock_timeout_handler_t 125 * 126 * @abstract 127 * The type of the timeout handlers for low level locking primitives. 128 * 129 * @discussion 130 * Typical handlers are written to just panic and not return 131 * unless some very specific conditions are met (debugging, ...). 132 */ 133 typedef hw_lock_timeout_status_t (*hw_lock_timeout_handler_t)(void *lock, 134 uint64_t timeout, uint64_t start, uint64_t now, uint64_t interrupt_time); 135 136 #endif /* MACH_KERNEL_PRIVATE */ 137 138 __END_DECLS 139 140 #endif /* _KERN_LOCK_TYPES_H */ 141