1 /* 2 * Copyright (c) 2017 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 #ifndef _PROCESSOR_CORE_H_ 29 #define _PROCESSOR_CORE_H_ 30 31 #include <stdint.h> 32 #include <mach/vm_types.h> 33 #include <mach/kern_return.h> 34 #include <mach/machine.h> 35 #include <mach_debug/mach_debug_types.h> 36 37 __BEGIN_DECLS 38 39 /* 40 * Kernel support for generating corefiles on device. 41 * 42 * The kernel provides support for co-operatively generating core files 43 * for any co/processors that register a coredump handler callback. 44 * 45 * The kernel will use the provided callbacks to generate a compressed 46 * corefile in a file on disk. 47 * 48 * Corefiles consist of three main sections 49 * -- The headers that describe the corefile -- number of segments, etc 50 * -- The segment commands that describe the data in the corefile 51 * -- The segment data 52 * 53 * When a coredump handler is registered, a pointer to a kern_coredump_callback_config 54 * structure is provided with callbacks that will be called as part of generating the 55 * coredump. 56 * 57 * It's expected that each of these callbacks will return 0 on success (and non-zero on 58 * error). 59 */ 60 61 void kern_coredump_log(void *context, const char *string, ...) __printflike(2, 3); 62 63 /* 64 * The core_save_summary callback is provided with the call to the kcc_coredump_get_summary 65 * routine that was registered. The caller should provide the following 66 * 67 * core_segment_count -- Number of segments (LC_SEGMENT_KERNEL) that will be recorded 68 * core_byte_count -- Overall length of all data to be included across all segments 69 * thread_count -- Number of threads that will be recorded with thread state (LC_THREAD) 70 * thread_state_size -- Size of a thread's saved state (should be the overall LC_THREAD command size) 71 * misc_bytes_count -- Length of misc data that will be included in the core 72 * mh_magic -- mh_magic to be included in corefile 73 * cpu_type -- CPU type 74 * cpu_subtype -- CPU subtype 75 * context -- Passed to kcc_coredump_get_summary_routine 76 */ 77 typedef kern_return_t (*core_save_summary_cb)(uint64_t core_segment_count, uint64_t core_byte_count, 78 uint64_t thread_count, uint64_t thread_state_size, 79 uint64_t misc_bytes_count, void *context); 80 81 /* 82 * The core_save_note_summary callback is provided with the call to the 83 * kcc_coredump_save_note_summary routine that was registered. The caller should 84 * provide the following 85 * 86 * core_note_count -- the number of LC_NOTE segments that will be recorded 87 * core_note_byte_count -- overall length of all data to be included across all LC_NOTE segments 88 * context -- Passed to kcc_coredump_save_note_summary routine 89 */ 90 typedef kern_return_t (*core_save_note_summary_cb)(uint64_t core_note_count, uint64_t core_note_byte_count, 91 void *context); 92 93 /* 94 * The core_save_segment_descriptions callback is provided with the call to the 95 * kcc_coredump_save_segment_descriptions routine that was registered. 96 * 97 * It's expected that the caller should iterate all of the segments they want to include in 98 * the corefile and call the callback with the following for each: 99 * 100 * Please note that seg_end is address of the byte immediately following the last byte in the segment. 101 * For example, if a segment spans addresses 0x1000 to 0x1FFF, seg_end would be 0x2000. 102 * 103 * seg_start -- Start of the segment in the core's address space 104 * seg_end -- End of the segment in the core's address space 105 * context -- Passed to kcc_coredump_save_segment_descriptions routine 106 */ 107 typedef kern_return_t (*core_save_segment_descriptions_cb)(uint64_t seg_start, uint64_t seg_end, 108 void *context); 109 /* 110 * The core_save_thread_state callback is provided with the call to the 111 * kcc_coredump_save_thread_state routine that was registered. 112 * 113 * The routine is provided a pointer to a buffer of thread_state_size (as specified 114 * previously) that can be used to populate thread state. 115 * 116 * It's expected that the caller should iterate all of the threads 117 * that they would like to include and call the callback with the following 118 * for each: 119 * 120 * thread_state -- A pointer to the buffer with an LC_THREAD command 121 * context -- Passed to kcc_coredump_save_thread_state routine 122 */ 123 typedef kern_return_t (*core_save_thread_state_cb)(void *thread_state, void *context); 124 125 /* 126 * The core_save_note_descriptions_cb callback is provided with the call to the 127 * kcc_coredump_save_note_descriptions routine that was registered. 128 * 129 * It's expected that the caller should call this function for each LC_NOTE segment that 130 * they want to include in the corefile and provide the following for each: 131 * 132 * data_owner -- owner name for this LC_NOTE 133 * length -- length of the payload for this LC_NOTE 134 * context -- Passed to kcc_coredump_save_note_descriptions routine 135 */ 136 typedef kern_return_t (*core_save_note_descriptions_cb)(const char *data_owner, uint64_t length, void *context); 137 138 /* 139 * deprecated - please switch to core_save_sw_vers_detail_cb 140 * 141 * The core_save_sw_vers callback is provided with the call to the 142 * kcc_coredump_save_sw_vers routine that was registered. 143 * 144 * The caller should call the callback with the following: 145 * 146 * sw_vers -- A pointer the software version information 147 * length -- Length of the software version information to be copied (< KERN_COREDUMP_VERSIONSTRINGMAXSIZE) 148 * context -- Passed to kcc_coredump_save_sw_vers routine 149 */ 150 typedef kern_return_t (*core_save_sw_vers_cb)(void *sw_vers, uint64_t length, void *context); 151 152 /* 153 * The core_save_sw_vers_detail_cb callback is provided with the call to the 154 * kcc_coredump_save_sw_vers_detail routine that was registered. 155 * 156 * The caller should call the callback with the following: 157 * 158 * address -- base address of TEXT segment 159 * uuid -- uuid of running binary 160 * log2_pagesize -- process page size in log base 2 (e.g. 4k pages are 12. 0 for unspecified) 161 * context -- Passed to kcc_coredump_save_sw_vers_detail routine 162 */ 163 typedef kern_return_t (*core_save_sw_vers_detail_cb)(uint64_t address, uuid_t uuid, uint32_t log2_pagesize, void *context); 164 165 /* 166 * The core_save_segment_data callback is provided with the call to the 167 * kcc_coredump_save_segment_data routine that was registered. 168 * 169 * It's expected that the caller should iterate all of the segments they want to include in 170 * the corefile and call the callback with the following for each: 171 * 172 * seg_data -- A pointer to the segment data (mapped in the kernel's address space) 173 * length -- Length of the data to be copied from the segment 174 * context -- Passed to kcc_coredump_save_segment_data routine 175 */ 176 typedef kern_return_t (*core_save_segment_data_cb)(void *seg_data, uint64_t length, void *context); 177 178 /* 179 * The core_save_note_data_cb callback is provided with the call to the 180 * kcc_coredump_save_note_data routine that was registered. 181 * 182 * It's expected that the caller should iterate all of the notes they want to include in 183 * the corefile and call the callback with the following for each: 184 * 185 * note_data -- A pointer to the payload data for this LC_NOTE (mapped in the kernel's address space) 186 * length -- length of the payload for this LC_NOTE 187 * context -- Passed to kcc_coredump_save_note_data routine 188 */ 189 typedef kern_return_t (*core_save_note_data_cb)(void *note_data, uint64_t length, void *context); 190 191 /* 192 * deprecated - please switch to core_save_note* 193 * 194 * The core_save_misc_data callback is provided with the call to the 195 * kcc_coredump_save_misc_data routine that was registered 196 * 197 * The caller should call the callback with the following: 198 * 199 * misc_data -- A pointer to the data to be copied 200 * length -- The length of the data to be copied 201 * context -- Passed to kcc_coredump_save_misc_data routine 202 */ 203 typedef kern_return_t (*core_save_misc_data_cb)(void *misc_data, uint64_t length, void *context); 204 205 typedef struct { 206 kern_return_t (*kcc_coredump_init)(void *refcon, void *context); /* OPTIONAL -- return KERN_NODE_DOWN if the co-processor should be skipped */ 207 kern_return_t (*kcc_coredump_get_summary)(void *refcon, core_save_summary_cb callback, void *context); 208 kern_return_t (*kcc_coredump_save_segment_descriptions)(void *refcon, core_save_segment_descriptions_cb callback, void *context); 209 kern_return_t (*kcc_coredump_save_thread_state)(void *refcon, void *buf, core_save_thread_state_cb callback, void *context); 210 kern_return_t (*kcc_coredump_save_sw_vers)(void *refcon, core_save_sw_vers_cb callback, void *context) __deprecated_msg("please switch to kcc_coredump_save_sw_vers_detail"); 211 kern_return_t (*kcc_coredump_save_segment_data)(void *refcon, core_save_segment_data_cb callback, void *context); 212 kern_return_t (*kcc_coredump_save_misc_data)(void *refcon, core_save_misc_data_cb callback, void *context) __deprecated_msg("please switch to kcc_coredump_save_note_*"); 213 /* End of version 1 */ 214 kern_return_t (*kcc_coredump_save_note_summary)(void *refcon, core_save_note_summary_cb callback, void *context); 215 kern_return_t (*kcc_coredump_save_note_descriptions)(void *refcon, core_save_note_descriptions_cb callback, void *context); 216 kern_return_t (*kcc_coredump_save_note_data)(void *refcon, core_save_note_data_cb callback, void *context); 217 kern_return_t (*kcc_coredump_save_sw_vers_detail)(void *refcon, core_save_sw_vers_detail_cb callback, void *context); 218 /* End of version 2 */ 219 } kern_coredump_callback_config; 220 221 #define KERN_COREDUMP_MAX_CORES 64 222 #define KERN_COREDUMP_MIN_CONFIG_VERSION 1 223 #define KERN_COREDUMP_MIN_CONFIG_NOTES 2 224 #define KERN_COREDUMP_CONFIG_VERSION 2 225 #define KERN_COREDUMP_VERSIONSTRINGMAXSIZE 256 226 227 /* 228 * kern_register_coredump_helper is called to register a core with the kernel 229 * coredump infrastructure. In addition to the callback config and version of the config 230 * structure, a description of the core should be provided -- i.e.: AP 231 */ 232 kern_return_t kern_register_coredump_helper(int kern_coredump_config_vers, const kern_coredump_callback_config *kc_callbacks, void *refcon, 233 const char *core_description, boolean_t is64bit, uint32_t mh_magic, cpu_type_t cpu_type, cpu_subtype_t cpu_subtype); 234 235 #if PRIVATE 236 237 kern_return_t kern_register_xnu_coredump_helper(kern_coredump_callback_config *kc_callbacks); 238 kern_return_t kern_register_sk_coredump_helper(kern_coredump_callback_config *kc_callbacks, void *refcon); 239 kern_return_t kern_register_userspace_coredump(task_t task, const char * name); 240 kern_return_t kern_unregister_userspace_coredump(task_t task); 241 242 kern_return_t kern_do_coredump(void *core_outvars, boolean_t kernel_only, uint64_t first_file_offset, uint64_t *last_file_offset, uint64_t details_flags); 243 244 #define KERN_COREDUMP_MAXDEBUGLOGSIZE 16384 245 #define KERN_COREDUMP_BEGIN_FILEBYTES_ALIGN 4096 246 #define KERN_COREDUMP_THREADSIZE_MAX 1024 247 248 #if XNU_KERNEL_PRIVATE 249 250 struct kern_userspace_coredump_context { 251 /* Task to dump */ 252 task_t task; 253 }; 254 255 kern_return_t user_dump_init(void *refcon, void *context); 256 kern_return_t user_dump_save_summary(void *refcon, core_save_summary_cb callback, void *context); 257 kern_return_t user_dump_save_seg_descriptions(void *refcon, core_save_segment_descriptions_cb callback, void *context); 258 kern_return_t user_dump_save_thread_state(void *refcon, void *buf, core_save_thread_state_cb callback, void *context); 259 kern_return_t user_dump_save_sw_vers_detail(void *refcon, core_save_sw_vers_detail_cb callback, void *context); 260 kern_return_t user_dump_save_segment_data(void *refcon, core_save_segment_data_cb callback, void *context); 261 kern_return_t user_dump_save_note_summary(void *refcon, core_save_note_summary_cb callback, void *context); 262 kern_return_t user_dump_save_note_descriptions(void *refcon, core_save_note_descriptions_cb callback, void *context); 263 kern_return_t user_dump_save_note_data(void *refcon, core_save_note_data_cb callback, void *context); 264 265 #endif /* XNU_KERNEL_PRIVATE */ 266 267 #endif /* PRIVATE */ 268 269 __END_DECLS 270 #endif /* _PROCESSOR_CORE_H_ */ 271