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 | |