1 /* 2 * Copyright (c) 2023 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 #ifndef _VM_SANITIZE_TELEMETRY_H_ 30 #define _VM_SANITIZE_TELEMETRY_H_ 31 32 #include <stdint.h> 33 #include <sys/kdebug_triage.h> 34 35 #pragma mark Methods 36 37 /* 38 * When adopting telemetry in a new method, add an enum for it here, at the 39 * bottom 40 */ 41 __enum_closed_decl(vm_sanitize_method_t, uint64_t, { 42 VM_SANITIZE_METHOD_MACH_MAKE_MEMORY_ENTRY = 1, 43 VM_SANITIZE_METHOD_MACH_MEMORY_ENTRY_PAGE_OP, 44 VM_SANITIZE_METHOD_MACH_MEMORY_ENTRY_RANGE_OP, 45 VM_SANITIZE_METHOD_MACH_MEMORY_ENTRY_MAP_SIZE, 46 VM_SANITIZE_METHOD_MACH_MEMORY_OBJECT_MEMORY_ENTRY, 47 VM_SANITIZE_METHOD_VM_ALLOCATE_FIXED, 48 VM_SANITIZE_METHOD_VM_ALLOCATE_ANYWHERE, 49 VM_SANITIZE_METHOD_VM_DEALLOCATE, 50 VM_SANITIZE_METHOD_MUNMAP, 51 VM_SANITIZE_METHOD_VM_MAP_REMAP, 52 VM_SANITIZE_METHOD_MMAP, 53 VM_SANITIZE_METHOD_MAP_WITH_LINKING_NP, 54 VM_SANITIZE_METHOD_ENTER_MEM_OBJ, 55 VM_SANITIZE_METHOD_ENTER_MEM_OBJ_CTL, 56 VM_SANITIZE_METHOD_MREMAP_ENCRYPTED, 57 VM_SANITIZE_METHOD_VM_WIRE_USER, 58 VM_SANITIZE_METHOD_VM_UNWIRE_USER, 59 VM_SANITIZE_METHOD_VM_MAP_WIRE, 60 VM_SANITIZE_METHOD_VM_MAP_UNWIRE, 61 VM_SANITIZE_METHOD_VSLOCK, 62 VM_SANITIZE_METHOD_VSUNLOCK, 63 VM_SANITIZE_METHOD_VM_MAP_COPY_OVERWRITE, 64 VM_SANITIZE_METHOD_VM_MAP_COPYIN, 65 VM_SANITIZE_METHOD_VM_MAP_READ_USER, 66 VM_SANITIZE_METHOD_VM_MAP_WRITE_USER, 67 VM_SANITIZE_METHOD_MACH_VM_INHERIT, 68 VM_SANITIZE_METHOD_VM_INHERIT, 69 VM_SANITIZE_METHOD_VM32_INHERIT, 70 VM_SANITIZE_METHOD_VM_MAP_INHERIT, 71 VM_SANITIZE_METHOD_MINHERIT, 72 VM_SANITIZE_METHOD_MACH_VM_PROTECT, 73 VM_SANITIZE_METHOD_VM_PROTECT, 74 VM_SANITIZE_METHOD_VM32_PROTECT, 75 VM_SANITIZE_METHOD_VM_MAP_PROTECT, 76 VM_SANITIZE_METHOD_MPROTECT, 77 VM_SANITIZE_METHOD_USERACC, 78 VM_SANITIZE_METHOD_VM_MAP_MSYNC, 79 VM_SANITIZE_METHOD_MSYNC, 80 VM_SANITIZE_METHOD_VM_MAP_MACHINE_ATTRIBUTE, 81 VM_SANITIZE_METHOD_MINCORE, 82 VM_SANITIZE_METHOD_VM_MAP_PAGE_RANGE_INFO, 83 VM_SANITIZE_METHOD_VM_MAP_PAGE_RANGE_QUERY, 84 VM_SANITIZE_METHOD_TEST, 85 }); 86 87 #pragma mark Checkers 88 89 /* 90 * When adopting telemetry in a new checker, add an enum for it here, at the 91 * bottom (but before the "counts") 92 */ 93 __enum_closed_decl(vm_sanitize_checker_t, uint64_t, { 94 VM_SANITIZE_CHECKER_ADDR_SIZE = 1, /* arg1=addr, arg2=size, arg3=pgmask */ 95 VM_SANITIZE_CHECKER_PROT_CUR_MAX, /* arg1=cur_prot, arg2=max_prot, arg3=extra_mask */ 96 }); 97 98 99 __enum_closed_decl(vm_sanitize_checker_count_t, uint64_t, { 100 VM_SANITIZE_CHECKER_COUNT_1 = 1, 101 VM_SANITIZE_CHECKER_COUNT_2, 102 VM_SANITIZE_CHECKER_COUNT_3, 103 VM_SANITIZE_CHECKER_COUNT_4, 104 VM_SANITIZE_CHECKER_COUNT_5, 105 }); 106 107 #pragma mark Telemetry API 108 109 /*! 110 * @function vm_sanitize_send_telemetry 111 * @abstract Send telemetry using CoreAnalytics when a VM API function returns 112 * a return code affected by the VM API Hygiene work. 113 * @param method An instance of the method enums above, indicating which VM 114 * API method is returning the error. 115 * @param checker An instance of the checker enums above, indicating which VM 116 * checker/sanitizer caused the error. 117 * @param checker_count An instance of the checker count enums above. Used to 118 * distinguish in cases where the same checker can be called multiple times by 119 * the same function. 120 * @param ktriage_code The enum to be used for ktriage. Pass 0 to skip ktriage. 121 * @param arg1 First argument. Interpretation depends on checker. 122 * @param arg2 Second argument. Interpretation depends on checker. 123 * @param arg3 Third argument. Interpretation depends on checker. 124 * @param arg4 Fourth argument. Interpretation depends on checker. 125 * @param future_ret The error code that will be returned long term when this 126 * checker fails with this method. 127 * @param past_ret The error code that would have been returned in the same 128 * circumstances before the VM API Hygiene work. 129 * 130 * @note There is no \p current_ret argument, and what the method is returning 131 * today should be passed as \p future_ret or \p past_ret as appropriate. 132 */ 133 void vm_sanitize_send_telemetry( 134 vm_sanitize_method_t method, 135 vm_sanitize_checker_t checker, 136 vm_sanitize_checker_count_t checker_count, 137 enum vm_sanitize_subsys_error_codes ktriage_code, 138 uint64_t arg1, 139 uint64_t arg2, 140 uint64_t arg3, 141 uint64_t arg4, 142 uint64_t future_ret, 143 uint64_t past_ret); 144 145 #endif /* _VM_SANITIZE_TELEMETRY_H_ */ 146