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_entry_v1_s { 42 mach_vm_address_t address; 43 uint32_t size; 44 uint16_t opcode; 45 uint16_t flags; 46 } mach_vm_reclaim_entry_v1_t; 47 48 typedef struct mach_vm_reclaim_indices_v1_s { 49 _Atomic uint64_t head; 50 _Atomic uint64_t tail; 51 _Atomic uint64_t busy; 52 } mach_vm_reclaim_indices_v1_t; 53 54 /* 55 * Contains the data used for synchronization with the kernel. This structure 56 * should be page-aligned. 57 */ 58 typedef struct mach_vm_reclaim_buffer_v1_s { 59 mach_vm_reclaim_indices_v1_t indices; 60 /* align to multiple of entry size */ 61 uint64_t _unused; 62 /* 63 * The ringbuffer entries themselves populate the remainder of this 64 * buffer's vm allocation. 65 */ 66 mach_vm_reclaim_entry_v1_t entries[0]; 67 } *mach_vm_reclaim_buffer_v1_t; 68 69 #if !KERNEL 70 #define VM_RECLAIM_INDEX_NULL UINT64_MAX 71 72 /* 73 * Userspace interface for placing items in the reclamation buffer and trying to take them back out. 74 * Note that these interfaces are NOT thread safe. It is the caller's responsibility to synchronize concurrent 75 * operations on the same buffer. 76 * 77 * These operations are implemented in libsyscall. 78 */ 79 80 typedef struct mach_vm_reclaim_ringbuffer_v1_s { 81 mach_vm_reclaim_buffer_v1_t buffer; 82 mach_vm_size_t buffer_len; 83 uint64_t va_in_buffer; 84 uint64_t last_accounting_given_to_kernel; 85 } *mach_vm_reclaim_ringbuffer_v1_t; 86 87 kern_return_t mach_vm_reclaim_ringbuffer_init(mach_vm_reclaim_ringbuffer_v1_t ringbuffer); 88 89 /* 90 * Mark the given range as free. 91 * Returns a unique identifier for the range that can be used by reclaim_mark_used 92 * This will update the userspace reclaim buffer accounting, but will not 93 * inform the kernel about the new bytes in the buffer. If the kernel should be informed, 94 * should_update_kernel_accounting will be set to true and the caller should call 95 * mach_vm_reclaim_update_kernel_accounting. That syscall might reclaim the buffer, so 96 * this gives the caller an opportunity to first drop any locks. 97 */ 98 uint64_t mach_vm_reclaim_mark_free( 99 mach_vm_reclaim_ringbuffer_v1_t buffer, 100 mach_vm_address_t start_addr, 101 uint32_t size, 102 bool *should_update_kernel_accounting); 103 104 /* 105 * Attempt to take back the range determined by id. 106 * Returns true iff range can now be used. 107 * Subsequent calls to reclaim_mark_used with the same id are not supported & may return true or false. 108 */ 109 bool mach_vm_reclaim_mark_used( 110 mach_vm_reclaim_ringbuffer_v1_t buffer, 111 uint64_t id, 112 mach_vm_address_t start_addr, 113 uint32_t size); 114 115 /* 116 * Check if the range has been reclaimed. 117 * Returns true if the range is still available. Note that this doesn't claim the range, so it may be reclaimed in parallel. 118 * Note that a return value of false does not guarantee that the kernel has reclaimed the range already (it may just be considering it). 119 */ 120 bool mach_vm_reclaim_is_available( 121 const mach_vm_reclaim_ringbuffer_v1_t buffer, 122 uint64_t id); 123 124 /* 125 * Force the kernel to reclaim at least num_entries_to_reclaim entries from the ringbuffer (if present). 126 * Note that mach_vm_reclaim_mark_free automatically handles the full ringbuffer case. 127 */ 128 kern_return_t mach_vm_reclaim_synchronize( 129 mach_vm_reclaim_ringbuffer_v1_t ringbuffer, 130 mach_vm_size_t num_entries_to_reclaim); 131 132 /* 133 * Let the kernel know how much VA is in the ringbuffer. 134 * The kernel may choose to reclaim from the ringbuffer on this thread. 135 * This should be called whenever mach_vm_reclaim_mark_free returns true in 136 * should_update_kernel_accounting. It may be called at any other time 137 * if the caller wants to update the kernel's accounting & is 138 * thread safe w.r.t. all other mach_vm_reclaim calls. 139 */ 140 kern_return_t mach_vm_reclaim_update_kernel_accounting( 141 const mach_vm_reclaim_ringbuffer_v1_t ring_buffer); 142 143 #endif /* !KENREL */ 144 145 __END_DECLS 146 147 #endif /* PRIVATE */ 148 149 #endif /* __LP64__ */ 150 151 #endif /* _VM_RECLAIM_H_ */ 152