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_segment_descriptions callback is provided with the call to the |
83 | * kcc_coredump_save_segment_descriptions routine that was registered. |
84 | * |
85 | * It's expected that the caller should iterate all of the segments they want to include in |
86 | * the corefile and call the callback with the following for each: |
87 | * |
88 | * Please note that seg_end is address of the byte immediately following the last byte in the segment. |
89 | * For example, if a segment spans addresses 0x1000 to 0x1FFF, seg_end would be 0x2000. |
90 | * |
91 | * seg_start -- Start of the segment in the core's address space |
92 | * seg_end -- End of the segment in the core's address space |
93 | * context -- Passed to kcc_coredump_save_segment_descriptions routine |
94 | */ |
95 | typedef kern_return_t (*core_save_segment_descriptions_cb)(uint64_t seg_start, uint64_t seg_end, |
96 | void *context); |
97 | /* |
98 | * The core_save_thread_state callback is provided with the call to the |
99 | * kcc_coredump_save_thread_state routine that was registered. |
100 | * |
101 | * The routine is provided a pointer to a buffer of thread_state_size (as specified |
102 | * previously) that can be used to populate thread state. |
103 | * |
104 | * It's expected that the caller should iterate all of the threads |
105 | * that they would like to include and call the callback with the following |
106 | * for each: |
107 | * |
108 | * thread_state -- A pointer to the buffer with an LC_THREAD command |
109 | * context -- Passed to kcc_coredump_save_thread_state routine |
110 | */ |
111 | typedef kern_return_t (*core_save_thread_state_cb)(void *thread_state, void *context); |
112 | |
113 | /* |
114 | * The core_save_sw_vers callback is provided with the call to the |
115 | * kcc_coredump_save_sw_vers routine that was registered. |
116 | * |
117 | * The caller should call the callback with the following: |
118 | * |
119 | * sw_vers -- A pointer the software version information |
120 | * length -- Length of the software version information to be copied (< KERN_COREDUMP_VERSIONSTRINGMAXSIZE) |
121 | * context -- Passed to kcc_coredump_save_sw_vers routine |
122 | */ |
123 | typedef kern_return_t (*core_save_sw_vers_cb)(void *sw_vers, uint64_t length, void *context); |
124 | |
125 | /* |
126 | * The core_save_segment_data callback is provided with the call to the |
127 | * kcc_coredump_save_segment_data routine that was registered. |
128 | * |
129 | * It's expected that the caller should iterate all of the segments they want to include in |
130 | * the corefile and call the callback with the following for each: |
131 | * |
132 | * seg_data -- A pointer to the segment data (mapped in the kernel's address space) |
133 | * length -- Length of the data to be copied from the segment |
134 | * context -- Passed to kcc_coredump_save_segment_data routine |
135 | */ |
136 | typedef kern_return_t (*core_save_segment_data_cb)(void *seg_data, uint64_t length, void *context); |
137 | |
138 | /* |
139 | * ---------------------- OPTIONAL ------------------------- |
140 | * The core_save_misc_data callback is provided with the call to the |
141 | * kcc_coredump_save_misc_data routine that was registered |
142 | * |
143 | * The caller should call the callback with the following: |
144 | * |
145 | * misc_data -- A pointer to the data to be copied |
146 | * length -- The length of the data to be copied |
147 | * context -- Passed to kcc_coredump_save_misc_data routine |
148 | */ |
149 | typedef kern_return_t (*core_save_misc_data_cb)(void *misc_data, uint64_t length, void *context); |
150 | |
151 | typedef struct { |
152 | kern_return_t (*kcc_coredump_init)(void *refcon, void *context); /* OPTIONAL -- return KERN_NODE_DOWN if the co-processor should be skipped */ |
153 | kern_return_t (*kcc_coredump_get_summary)(void *refcon, core_save_summary_cb callback, void *context); |
154 | kern_return_t (*kcc_coredump_save_segment_descriptions)(void *refcon, core_save_segment_descriptions_cb callback, void *context); |
155 | kern_return_t (*kcc_coredump_save_thread_state)(void *refcon, void *buf, core_save_thread_state_cb callback, void *context); |
156 | kern_return_t (*kcc_coredump_save_sw_vers)(void *refcon, core_save_sw_vers_cb callback, void *context); |
157 | kern_return_t (*kcc_coredump_save_segment_data)(void *refcon, core_save_segment_data_cb callback, void *context); |
158 | kern_return_t (*kcc_coredump_save_misc_data)(void *refcon, core_save_misc_data_cb callback, void *context); /* OPTIONAL */ |
159 | /* End of version 1 */ |
160 | } kern_coredump_callback_config; |
161 | |
162 | #define KERN_COREDUMP_MAX_CORES MACH_CORE_FILEHEADER_MAXFILES |
163 | #define KERN_COREDUMP_MIN_CONFIG_VERSION 1 |
164 | #define KERN_COREDUMP_CONFIG_VERSION 1 |
165 | #define KERN_COREDUMP_VERSIONSTRINGMAXSIZE 256 |
166 | |
167 | /* |
168 | * kern_register_coredump_helper is called to register a core with the kernel |
169 | * coredump infrastructure. In addition to the callback config and version of the config |
170 | * structure, a description of the core should be provided -- i.e.: AP |
171 | */ |
172 | kern_return_t kern_register_coredump_helper(int kern_coredump_config_vers, kern_coredump_callback_config *kc_callbacks, void *refcon, |
173 | const char *core_description, boolean_t is64bit, uint32_t mh_magic, cpu_type_t cpu_type, cpu_subtype_t cpu_subtype); |
174 | |
175 | #if PRIVATE |
176 | |
177 | kern_return_t kern_register_xnu_coredump_helper(kern_coredump_callback_config *kc_callbacks); |
178 | |
179 | kern_return_t kern_do_coredump(void *core_outvars, boolean_t kernel_only, uint64_t first_file_offset, uint64_t *last_file_offset); |
180 | |
181 | #define 4096 |
182 | static_assert((sizeof(struct mach_core_fileheader) <= KERN_COREDUMP_HEADERSIZE), "struct mach_core_fileheader larger than KERN_COREDUMP_HEADERSIZE (space that will be allocated for it in the corefile)" ); |
183 | |
184 | #define KERN_COREDUMP_MAXDEBUGLOGSIZE 16384 |
185 | #define KERN_COREDUMP_BEGIN_FILEBYTES_ALIGN 4096 |
186 | #define KERN_COREDUMP_THREADSIZE_MAX 1024 |
187 | |
188 | #endif /* PRIVATE */ |
189 | |
190 | __END_DECLS |
191 | #endif /* _PROCESSOR_CORE_H_ */ |
192 | |