1 /* 2 * Copyright (c) 2021 Apple 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 #ifndef _VM_RECLAIM_H_ 30 #define _VM_RECLAIM_H_ 31 32 #ifdef PRIVATE 33 #if defined(__LP64__) 34 35 #include <mach/mach_types.h> 36 #include <mach/kern_return.h> 37 #include <stdbool.h> 38 39 __BEGIN_DECLS 40 41 typedef struct mach_vm_reclaim_indices_v1_s { 42 _Atomic uint64_t head; 43 _Atomic uint64_t tail; 44 _Atomic uint64_t busy; 45 } mach_vm_reclaim_indices_v1_t; 46 47 // The action to be performed by the kernel on reclamation of an entry 48 __enum_decl(mach_vm_reclaim_behavior_v1_t, uint16_t, { 49 // Deallocate (unmap) the entry 50 MACH_VM_RECLAIM_DEALLOCATE = 0, 51 // Mark the entry as clean and leave mapped (VM_BEHAVIOR_REUSABLE) 52 MACH_VM_RECLAIM_REUSABLE = 1, 53 }); 54 55 typedef struct mach_vm_reclaim_entry_v1_s { 56 mach_vm_address_t address; 57 uint32_t size; 58 mach_vm_reclaim_behavior_v1_t behavior; 59 uint16_t flags; 60 } mach_vm_reclaim_entry_v1_t; 61 62 /* 63 * Contains the data used for synchronization with the kernel. This structure 64 * should be page-aligned. 65 */ 66 typedef struct mach_vm_reclaim_buffer_v1_s { 67 mach_vm_reclaim_indices_v1_t indices; 68 /* align to multiple of entry size */ 69 uint64_t _unused; 70 /* 71 * The ringbuffer entries themselves populate the remainder of this 72 * buffer's vm allocation. 73 */ 74 mach_vm_reclaim_entry_v1_t entries[0]; 75 } *mach_vm_reclaim_buffer_v1_t; 76 77 #if !KERNEL 78 #define VM_RECLAIM_INDEX_NULL UINT64_MAX 79 80 /* 81 * Userspace interface for placing items in the reclamation buffer and trying to take them back out. 82 * Note that these interfaces are NOT thread safe. It is the caller's responsibility to synchronize concurrent 83 * operations on the same buffer. 84 * 85 * These operations are implemented in libsyscall. 86 */ 87 88 typedef struct mach_vm_reclaim_ringbuffer_v1_s { 89 mach_vm_reclaim_buffer_v1_t buffer; 90 mach_vm_size_t buffer_len; 91 uint64_t va_in_buffer; 92 uint64_t last_accounting_given_to_kernel; 93 } *mach_vm_reclaim_ringbuffer_v1_t; 94 95 kern_return_t mach_vm_reclaim_ringbuffer_init( 96 mach_vm_reclaim_ringbuffer_v1_t ringbuffer); 97 98 /* 99 * Mark the given range as free. 100 * Returns a unique identifier for the range that can be used by reclaim_mark_used 101 * 102 * This will update the userspace reclaim buffer accounting, but will not 103 * inform the kernel about the new bytes in the buffer. If the kernel should be informed, 104 * should_update_kernel_accounting will be set to true and the caller should call 105 * mach_vm_reclaim_update_kernel_accounting. That syscall might reclaim the buffer, so 106 * this gives the caller an opportunity to first drop any locks. 107 */ 108 uint64_t mach_vm_reclaim_mark_free( 109 mach_vm_reclaim_ringbuffer_v1_t buffer, 110 mach_vm_address_t start_addr, 111 uint32_t size, 112 mach_vm_reclaim_behavior_v1_t behavior, 113 bool *should_update_kernel_accounting); 114 115 /* 116 * Mark the given range as free with a specific id. 117 * 118 * It is the callers responsibility to ensure that the ID is not currently in 119 * use (i.e. the caller has successfully called mach_vm_reclaim_mark_used() on 120 * this ID). Attempting to double-mark-free to the same reclaim ID is likely to 121 * result in a crash. 122 * 123 * Returns KERN_SUCCESS if the operation was successful. In the event that the 124 * ID is no longer available (because the kernel has reclaimed it), returns 125 * KERN_FAILURE. 126 * 127 * This will update the userspace reclaim buffer accounting, but will not 128 * inform the kernel about the new bytes in the buffer. If the kernel should be informed, 129 * should_update_kernel_accounting will be set to true and the caller should call 130 * mach_vm_reclaim_update_kernel_accounting. That syscall might reclaim the buffer, so 131 * this gives the caller an opportunity to first drop any locks. 132 */ 133 kern_return_t mach_vm_reclaim_mark_free_with_id( 134 mach_vm_reclaim_ringbuffer_v1_t buffer, 135 mach_vm_address_t start_addr, 136 uint32_t size, 137 mach_vm_reclaim_behavior_v1_t behavior, 138 uint64_t id, 139 bool *should_update_kernel_accounting); 140 141 /* 142 * Attempt to take back the range determined by id. 143 * Returns true iff range can now be used. 144 * Subsequent calls to reclaim_mark_used with the same id are not supported & may return true or false. 145 */ 146 bool mach_vm_reclaim_mark_used( 147 mach_vm_reclaim_ringbuffer_v1_t buffer, 148 uint64_t id, 149 mach_vm_address_t start_addr, 150 uint32_t size); 151 152 /* 153 * Check if the range is available for re-use. 154 * Returns true if the range is still available. Note that this doesn't claim the range, so it may be reclaimed in parallel. 155 * Note that a return value of false does not guarantee that the kernel has reclaimed the range already (it may just be considering it). 156 */ 157 bool mach_vm_reclaim_is_available( 158 const mach_vm_reclaim_ringbuffer_v1_t buffer, 159 uint64_t id); 160 161 /* 162 * Check if the range has been reclaimed. 163 * Returns true if the range is no longer available for re-use. 164 */ 165 bool mach_vm_reclaim_is_reclaimed( 166 const mach_vm_reclaim_ringbuffer_v1_t buffer, 167 uint64_t id); 168 169 /* 170 * Force the kernel to reclaim at least num_entries_to_reclaim entries from the ringbuffer (if present). 171 * Note that mach_vm_reclaim_mark_free automatically handles the full ringbuffer case. 172 */ 173 kern_return_t mach_vm_reclaim_synchronize( 174 mach_vm_reclaim_ringbuffer_v1_t ringbuffer, 175 mach_vm_size_t num_entries_to_reclaim); 176 177 /* 178 * Let the kernel know how much VA is in the ringbuffer. 179 * The kernel may choose to reclaim from the ringbuffer on this thread. 180 * This should be called whenever mach_vm_reclaim_mark_free returns true in 181 * should_update_kernel_accounting. It may be called at any other time 182 * if the caller wants to update the kernel's accounting & is 183 * thread safe w.r.t. all other mach_vm_reclaim calls. 184 */ 185 kern_return_t mach_vm_reclaim_update_kernel_accounting( 186 const mach_vm_reclaim_ringbuffer_v1_t ring_buffer); 187 188 #endif /* !KENREL */ 189 190 __END_DECLS 191 192 #endif /* PRIVATE */ 193 194 #endif /* __LP64__ */ 195 196 #endif /* _VM_RECLAIM_H_ */ 197