/*
* Copyright (c) 2023 Apple Computer, Inc. All rights reserved.
*
* @APPLE_OSREFERENCE_LICENSE_HEADER_START@
*
* This file contains Original Code and/or Modifications of Original Code
* as defined in and that are subject to the Apple Public Source License
* Version 2.0 (the 'License'). You may not use this file except in
* compliance with the License. The rights granted to you under the License
* may not be used to create, or enable the creation or redistribution of,
* unlawful or unlicensed copies of an Apple operating system, or to
* circumvent, violate, or enable the circumvention or violation of, any
* terms of an Apple operating system software license agreement.
*
* Please obtain a copy of the License at
* http://www.opensource.apple.com/apsl/ and read it before using this file.
*
* The Original Code and all software distributed under the License are
* distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER
* EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
* INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
* FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT.
* Please see the License for the specific language governing rights and
* limitations under the License.
*
* @APPLE_OSREFERENCE_LICENSE_HEADER_END@
*/
#ifndef _VM_SANITIZE_TELEMETRY_H_
#define _VM_SANITIZE_TELEMETRY_H_
#include <stdint.h>
#include <sys/kdebug_triage.h>
#pragma mark Methods
/*
* When adopting telemetry in a new method, add an enum for it here, at the
* bottom
*/
__enum_closed_decl(vm_sanitize_method_t, uint64_t, {
VM_SANITIZE_METHOD_MACH_MAKE_MEMORY_ENTRY = 1,
VM_SANITIZE_METHOD_MACH_MEMORY_ENTRY_PAGE_OP,
VM_SANITIZE_METHOD_MACH_MEMORY_ENTRY_RANGE_OP,
VM_SANITIZE_METHOD_MACH_MEMORY_ENTRY_MAP_SIZE,
VM_SANITIZE_METHOD_MACH_MEMORY_OBJECT_MEMORY_ENTRY,
VM_SANITIZE_METHOD_VM_ALLOCATE_FIXED,
VM_SANITIZE_METHOD_VM_ALLOCATE_ANYWHERE,
VM_SANITIZE_METHOD_VM_DEALLOCATE,
VM_SANITIZE_METHOD_MUNMAP,
VM_SANITIZE_METHOD_VM_MAP_REMAP,
VM_SANITIZE_METHOD_MMAP,
VM_SANITIZE_METHOD_MAP_WITH_LINKING_NP,
VM_SANITIZE_METHOD_ENTER_MEM_OBJ,
VM_SANITIZE_METHOD_ENTER_MEM_OBJ_CTL,
VM_SANITIZE_METHOD_MREMAP_ENCRYPTED,
VM_SANITIZE_METHOD_VM_WIRE_USER,
VM_SANITIZE_METHOD_VM_UNWIRE_USER,
VM_SANITIZE_METHOD_VM_MAP_WIRE,
VM_SANITIZE_METHOD_VM_MAP_UNWIRE,
VM_SANITIZE_METHOD_VSLOCK,
VM_SANITIZE_METHOD_VSUNLOCK,
VM_SANITIZE_METHOD_VM_MAP_COPY_OVERWRITE,
VM_SANITIZE_METHOD_VM_MAP_COPYIN,
VM_SANITIZE_METHOD_VM_MAP_READ_USER,
VM_SANITIZE_METHOD_VM_MAP_WRITE_USER,
VM_SANITIZE_METHOD_MACH_VM_INHERIT,
VM_SANITIZE_METHOD_VM_INHERIT,
VM_SANITIZE_METHOD_VM32_INHERIT,
VM_SANITIZE_METHOD_VM_MAP_INHERIT,
VM_SANITIZE_METHOD_MINHERIT,
VM_SANITIZE_METHOD_MACH_VM_PROTECT,
VM_SANITIZE_METHOD_VM_PROTECT,
VM_SANITIZE_METHOD_VM32_PROTECT,
VM_SANITIZE_METHOD_VM_MAP_PROTECT,
VM_SANITIZE_METHOD_MPROTECT,
VM_SANITIZE_METHOD_USERACC,
VM_SANITIZE_METHOD_VM_MAP_MSYNC,
VM_SANITIZE_METHOD_MSYNC,
VM_SANITIZE_METHOD_VM_MAP_MACHINE_ATTRIBUTE,
VM_SANITIZE_METHOD_MINCORE,
VM_SANITIZE_METHOD_VM_MAP_PAGE_RANGE_INFO,
VM_SANITIZE_METHOD_VM_MAP_PAGE_RANGE_QUERY,
VM_SANITIZE_METHOD_TEST,
});
#pragma mark Checkers
/*
* When adopting telemetry in a new checker, add an enum for it here, at the
* bottom (but before the "counts")
*/
__enum_closed_decl(vm_sanitize_checker_t, uint64_t, {
VM_SANITIZE_CHECKER_ADDR_SIZE = 1, /* arg1=addr, arg2=size, arg3=pgmask */
VM_SANITIZE_CHECKER_PROT_CUR_MAX, /* arg1=cur_prot, arg2=max_prot, arg3=extra_mask */
});
__enum_closed_decl(vm_sanitize_checker_count_t, uint64_t, {
VM_SANITIZE_CHECKER_COUNT_1 = 1,
VM_SANITIZE_CHECKER_COUNT_2,
VM_SANITIZE_CHECKER_COUNT_3,
VM_SANITIZE_CHECKER_COUNT_4,
VM_SANITIZE_CHECKER_COUNT_5,
});
#pragma mark Telemetry API
/*!
* @function vm_sanitize_send_telemetry
* @abstract Send telemetry using CoreAnalytics when a VM API function returns
* a return code affected by the VM API Hygiene work.
* @param method An instance of the method enums above, indicating which VM
* API method is returning the error.
* @param checker An instance of the checker enums above, indicating which VM
* checker/sanitizer caused the error.
* @param checker_count An instance of the checker count enums above. Used to
* distinguish in cases where the same checker can be called multiple times by
* the same function.
* @param ktriage_code The enum to be used for ktriage. Pass 0 to skip ktriage.
* @param arg1 First argument. Interpretation depends on checker.
* @param arg2 Second argument. Interpretation depends on checker.
* @param arg3 Third argument. Interpretation depends on checker.
* @param arg4 Fourth argument. Interpretation depends on checker.
* @param future_ret The error code that will be returned long term when this
* checker fails with this method.
* @param past_ret The error code that would have been returned in the same
* circumstances before the VM API Hygiene work.
*
* @note There is no \p current_ret argument, and what the method is returning
* today should be passed as \p future_ret or \p past_ret as appropriate.
*/
void vm_sanitize_send_telemetry(
vm_sanitize_method_t method,
vm_sanitize_checker_t checker,
vm_sanitize_checker_count_t checker_count,
enum vm_sanitize_subsys_error_codes ktriage_code,
uint64_t arg1,
uint64_t arg2,
uint64_t arg3,
uint64_t arg4,
uint64_t future_ret,
uint64_t past_ret);
#endif /* _VM_SANITIZE_TELEMETRY_H_ */