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
61void 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 */
77typedef 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 */
90typedef 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 */
107typedef 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 */
123typedef 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 */
136typedef 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 */
150typedef 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 */
163typedef 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 */
176typedef 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 */
189typedef 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 */
203typedef kern_return_t (*core_save_misc_data_cb)(void *misc_data, uint64_t length, void *context);
204
205typedef 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 */
232kern_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
237kern_return_t kern_register_xnu_coredump_helper(kern_coredump_callback_config *kc_callbacks);
238kern_return_t kern_register_sk_coredump_helper(kern_coredump_callback_config *kc_callbacks, void *refcon);
239kern_return_t kern_register_userspace_coredump(task_t task, const char * name);
240kern_return_t kern_unregister_userspace_coredump(task_t task);
241
242kern_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
250struct kern_userspace_coredump_context {
251 /* Task to dump */
252 task_t task;
253};
254
255kern_return_t user_dump_init(void *refcon, void *context);
256kern_return_t user_dump_save_summary(void *refcon, core_save_summary_cb callback, void *context);
257kern_return_t user_dump_save_seg_descriptions(void *refcon, core_save_segment_descriptions_cb callback, void *context);
258kern_return_t user_dump_save_thread_state(void *refcon, void *buf, core_save_thread_state_cb callback, void *context);
259kern_return_t user_dump_save_sw_vers_detail(void *refcon, core_save_sw_vers_detail_cb callback, void *context);
260kern_return_t user_dump_save_segment_data(void *refcon, core_save_segment_data_cb callback, void *context);
261kern_return_t user_dump_save_note_summary(void *refcon, core_save_note_summary_cb callback, void *context);
262kern_return_t user_dump_save_note_descriptions(void *refcon, core_save_note_descriptions_cb callback, void *context);
263kern_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