osfmk/kdp/processor_core.h

   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 KERN_COREDUMP_HEADERSIZE 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_ */