[apple/xnu.git] / osfmk / kdp / processor_core.h

/*
 * Copyright (c) 2017 Apple Computer, Inc. All rights reserved.
 *
 * @APPLE_OSREFERENCE_LICENSE_HEADER_START@
 *
 * This file contains Original Code and/or Modifications of Original Code
 * as defined in and that are subject to the Apple Public Source License
 * Version 2.0 (the 'License'). You may not use this file except in
 * compliance with the License. The rights granted to you under the License
 * may not be used to create, or enable the creation or redistribution of,
 * unlawful or unlicensed copies of an Apple operating system, or to
 * circumvent, violate, or enable the circumvention or violation of, any
 * terms of an Apple operating system software license agreement.
 *
 * Please obtain a copy of the License at
 * http://www.opensource.apple.com/apsl/ and read it before using this file.
 *
 * The Original Code and all software distributed under the License are
 * distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER
 * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
 * INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
 * FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT.
 * Please see the License for the specific language governing rights and
 * limitations under the License.
 *
 * @APPLE_OSREFERENCE_LICENSE_HEADER_END@
 */
#ifndef _PROCESSOR_CORE_H_
#define _PROCESSOR_CORE_H_

#include <stdint.h>
#include <mach/vm_types.h>
#include <mach/kern_return.h>
#include <mach/machine.h>
#include <mach_debug/mach_debug_types.h>

__BEGIN_DECLS

/*
 * Kernel support for generating corefiles on device.
 *
 * The kernel provides support for co-operatively generating core files
 * for any co/processors that register a coredump handler callback.
 *
 * The kernel will use the provided callbacks to generate a compressed
 * corefile in a file on disk.
 *
 * Corefiles consist of three main sections
 *      -- The headers that describe the corefile -- number of segments, etc
 *      -- The segment commands that describe the data in the corefile
 *      -- The segment data
 *
 * When a coredump handler is registered, a pointer to a kern_coredump_callback_config
 * structure is provided with callbacks that will be called as part of generating the
 * coredump.
 *
 * It's expected that each of these callbacks will return 0 on success (and non-zero on
 * error).
 */

void kern_coredump_log(void *context, const char *string, ...) __printflike(2, 3);

/*
 * The core_save_summary callback is provided with the call to the kcc_coredump_get_summary
 * routine that was registered. The caller should provide the following
 *
 * core_segment_count   -- Number of segments (LC_SEGMENT_KERNEL) that will be recorded
 * core_byte_count      -- Overall length of all data to be included across all segments
 * thread_count         -- Number of threads that will be recorded with thread state (LC_THREAD)
 * thread_state_size    -- Size of a thread's saved state (should be the overall LC_THREAD command size)
 * misc_bytes_count     -- Length of misc data that will be included in the core
 * mh_magic             -- mh_magic to be included in corefile
 * cpu_type             -- CPU type
 * cpu_subtype          -- CPU subtype
 * context              -- Passed to kcc_coredump_get_summary_routine
 */
typedef kern_return_t (*core_save_summary_cb)(uint64_t core_segment_count, uint64_t core_byte_count,
    uint64_t thread_count, uint64_t thread_state_size,
    uint64_t misc_bytes_count, void *context);

/*
 * The core_save_segment_descriptions callback is provided with the call to the
 * kcc_coredump_save_segment_descriptions routine that was registered.
 *
 * It's expected that the caller should iterate all of the segments they want to include in
 * the corefile and call the callback with the following for each:
 *
 * Please note that seg_end is address of the byte immediately following the last byte in the segment.
 * For example, if a segment spans addresses 0x1000 to 0x1FFF, seg_end would be 0x2000.
 *
 * seg_start -- Start of the segment in the core's address space
 * seg_end   -- End of the segment in the core's address space
 * context   -- Passed to kcc_coredump_save_segment_descriptions routine
 */
typedef kern_return_t (*core_save_segment_descriptions_cb)(uint64_t seg_start, uint64_t seg_end,
    void *context);
/*
 * The core_save_thread_state callback is provided with the call to the
 * kcc_coredump_save_thread_state routine that was registered.
 *
 * The routine is provided a pointer to a buffer of thread_state_size (as specified
 * previously) that can be used to populate thread state.
 *
 * It's expected that the caller should iterate all of the threads
 * that they would like to include and call the callback with the following
 * for each:
 *
 * thread_state -- A pointer to the buffer with an LC_THREAD command
 * context      -- Passed to kcc_coredump_save_thread_state routine
 */
typedef kern_return_t (*core_save_thread_state_cb)(void *thread_state, void *context);

/*
 * The core_save_sw_vers callback is provided with the call to the
 * kcc_coredump_save_sw_vers routine that was registered.
 *
 * The caller should call the callback with the following:
 *
 * sw_vers -- A pointer the software version information
 * length  -- Length of the software version information to be copied (< KERN_COREDUMP_VERSIONSTRINGMAXSIZE)
 * context -- Passed to kcc_coredump_save_sw_vers routine
 */
typedef kern_return_t (*core_save_sw_vers_cb)(void *sw_vers, uint64_t length, void *context);

/*
 * The core_save_segment_data callback is provided with the call to the
 * kcc_coredump_save_segment_data routine that was registered.
 *
 * It's expected that the caller should iterate all of the segments they want to include in
 * the corefile and call the callback with the following for each:
 *
 * seg_data -- A pointer to the segment data (mapped in the kernel's address space)
 * length   -- Length of the data to be copied from the segment
 * context  -- Passed to kcc_coredump_save_segment_data routine
 */
typedef kern_return_t (*core_save_segment_data_cb)(void *seg_data, uint64_t length, void *context);

/*
 *  ---------------------- OPTIONAL -------------------------
 * The core_save_misc_data callback is provided with the call to the
 * kcc_coredump_save_misc_data routine that was registered
 *
 * The caller should call the callback with the following:
 *
 * misc_data -- A pointer to the data to be copied
 * length    -- The length of the data to be copied
 * context   -- Passed to kcc_coredump_save_misc_data routine
 */
typedef kern_return_t (*core_save_misc_data_cb)(void *misc_data, uint64_t length, void *context);

typedef struct {
	kern_return_t (*kcc_coredump_init)(void *refcon, void *context); /* OPTIONAL -- return KERN_NODE_DOWN if the co-processor should be skipped */
	kern_return_t (*kcc_coredump_get_summary)(void *refcon, core_save_summary_cb callback, void *context);
	kern_return_t (*kcc_coredump_save_segment_descriptions)(void *refcon, core_save_segment_descriptions_cb callback, void *context);
	kern_return_t (*kcc_coredump_save_thread_state)(void *refcon, void *buf, core_save_thread_state_cb callback, void *context);
	kern_return_t (*kcc_coredump_save_sw_vers)(void *refcon, core_save_sw_vers_cb callback, void *context);
	kern_return_t (*kcc_coredump_save_segment_data)(void *refcon, core_save_segment_data_cb callback, void *context);
	kern_return_t (*kcc_coredump_save_misc_data)(void *refcon, core_save_misc_data_cb callback, void *context); /* OPTIONAL */
	/* End of version 1 */
} kern_coredump_callback_config;

#define KERN_COREDUMP_MAX_CORES MACH_CORE_FILEHEADER_MAXFILES
#define KERN_COREDUMP_MIN_CONFIG_VERSION 1
#define KERN_COREDUMP_CONFIG_VERSION 1
#define KERN_COREDUMP_VERSIONSTRINGMAXSIZE 256

/*
 * kern_register_coredump_helper is called to register a core with the kernel
 * coredump infrastructure. In addition to the callback config and version of the config
 * structure, a description of the core should be provided -- i.e.: AP
 */
kern_return_t kern_register_coredump_helper(int kern_coredump_config_vers, kern_coredump_callback_config *kc_callbacks, void *refcon,
    const char *core_description, boolean_t is64bit, uint32_t mh_magic, cpu_type_t cpu_type, cpu_subtype_t cpu_subtype);

#if PRIVATE

kern_return_t kern_register_xnu_coredump_helper(kern_coredump_callback_config *kc_callbacks);

kern_return_t kern_do_coredump(void *core_outvars, boolean_t kernel_only, uint64_t first_file_offset, uint64_t *last_file_offset);

#define KERN_COREDUMP_HEADERSIZE 4096
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)");

#define KERN_COREDUMP_MAXDEBUGLOGSIZE 16384
#define KERN_COREDUMP_BEGIN_FILEBYTES_ALIGN 4096
#define KERN_COREDUMP_THREADSIZE_MAX 1024

#endif /* PRIVATE */

__END_DECLS
#endif /* _PROCESSOR_CORE_H_ */
Commit	Line	Data
5ba3f43e A	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
0a7de745	61	void kern_coredump_log(void context, const char string, ...) __printflike(2, 3);
5ba3f43e A	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,
0a7de745 A	78	uint64_t thread_count, uint64_t thread_state_size,
0a7de745 A	79	uint64_t misc_bytes_count, void *context);
5ba3f43e A	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,
0a7de745	96	void *context);
5ba3f43e A	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 {
0a7de745 A	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 */
5ba3f43e A	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,
0a7de745	173	const char *core_description, boolean_t is64bit, uint32_t mh_magic, cpu_type_t cpu_type, cpu_subtype_t cpu_subtype);
5ba3f43e A	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_ */