1 //===-- scudo/interface.h ---------------------------------------*- C++ -*-===// 2 // 3 // Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions. 4 // See https://llvm.org/LICENSE.txt for license information. 5 // SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception 6 // 7 //===----------------------------------------------------------------------===// 8 9 #ifndef SCUDO_INTERFACE_H_ 10 #define SCUDO_INTERFACE_H_ 11 12 #include <stddef.h> 13 14 extern "C" { 15 16 __attribute__((weak)) const char *__scudo_default_options(); 17 18 // Post-allocation & pre-deallocation hooks. 19 // They must be thread-safe and not use heap related functions. 20 __attribute__((weak)) void __scudo_allocate_hook(void *ptr, size_t size); 21 __attribute__((weak)) void __scudo_deallocate_hook(void *ptr); 22 23 void __scudo_print_stats(void); 24 25 typedef void (*iterate_callback)(uintptr_t base, size_t size, void *arg); 26 27 // Determine the likely cause of a tag check fault or other memory protection 28 // error on a system with memory tagging support. The results are returned via 29 // the error_info data structure. Up to three possible causes are returned in 30 // the reports array, in decreasing order of probability. The remaining elements 31 // of reports are zero-initialized. 32 // 33 // This function may be called from a different process from the one that 34 // crashed. In this case, various data structures must be copied from the 35 // crashing process to the process that analyzes the crash. 36 // 37 // This interface is not guaranteed to be stable and may change at any time. 38 // Furthermore, the version of scudo in the crashing process must be the same as 39 // the version in the process that analyzes the crash. 40 // 41 // fault_addr is the fault address. On aarch64 this is available in the system 42 // register FAR_ELx, or far_context.far in an upcoming release of the Linux 43 // kernel. This address must include the pointer tag; note that the kernel 44 // strips the tag from the fields siginfo.si_addr and sigcontext.fault_address, 45 // so these addresses are not suitable to be passed as fault_addr. 46 // 47 // stack_depot is a pointer to the stack depot data structure, which may be 48 // obtained by calling the function __scudo_get_stack_depot_addr() in the 49 // crashing process. The size of the stack depot is available by calling the 50 // function __scudo_get_stack_depot_size(). 51 // 52 // region_info is a pointer to the region info data structure, which may be 53 // obtained by calling the function __scudo_get_region_info_addr() in the 54 // crashing process. The size of the region info is available by calling the 55 // function __scudo_get_region_info_size(). 56 // 57 // memory is a pointer to a region of memory surrounding the fault address. 58 // The more memory available via this pointer, the more likely it is that the 59 // function will be able to analyze a crash correctly. It is recommended to 60 // provide an amount of memory equal to 16 * the primary allocator's largest 61 // size class either side of the fault address. 62 // 63 // memory_tags is a pointer to an array of memory tags for the memory accessed 64 // via memory. Each byte of this array corresponds to a region of memory of size 65 // equal to the architecturally defined memory tag granule size (16 on aarch64). 66 // 67 // memory_addr is the start address of memory in the crashing process's address 68 // space. 69 // 70 // memory_size is the size of the memory region referred to by the memory 71 // pointer. 72 void __scudo_get_error_info(struct scudo_error_info *error_info, 73 uintptr_t fault_addr, const char *stack_depot, 74 const char *region_info, const char *memory, 75 const char *memory_tags, uintptr_t memory_addr, 76 size_t memory_size); 77 78 enum scudo_error_type { 79 UNKNOWN, 80 USE_AFTER_FREE, 81 BUFFER_OVERFLOW, 82 BUFFER_UNDERFLOW, 83 }; 84 85 struct scudo_error_report { 86 enum scudo_error_type error_type; 87 88 uintptr_t allocation_address; 89 uintptr_t allocation_size; 90 91 uint32_t allocation_tid; 92 uintptr_t allocation_trace[64]; 93 94 uint32_t deallocation_tid; 95 uintptr_t deallocation_trace[64]; 96 }; 97 98 struct scudo_error_info { 99 struct scudo_error_report reports[3]; 100 }; 101 102 const char *__scudo_get_stack_depot_addr(); 103 size_t __scudo_get_stack_depot_size(); 104 105 const char *__scudo_get_region_info_addr(); 106 size_t __scudo_get_region_info_size(); 107 108 } // extern "C" 109 110 #endif // SCUDO_INTERFACE_H_ 111