[apple/xnu.git] / bsd / sys / stackshot.h

/*
 * Copyright (c) 2014 Apple 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 _SYS_STACKSHOT_H
#define _SYS_STACKSHOT_H

#include <stdint.h>

#define STACKSHOT_CONFIG_TYPE 1

typedef struct stackshot_config {
	/* Input options */
	int             sc_pid;                 /* PID to trace, or -1 for the entire system */
	uint64_t        sc_flags;               /* Stackshot flags */
	uint64_t        sc_delta_timestamp;     /* Retrieve a delta stackshot of system state that has changed since this time */

	/* Stackshot results */
	uint64_t        sc_buffer;              /* Pointer to stackshot buffer */
	uint32_t        sc_size;                /* Length of the stackshot buffer */

	/* Internals */
	uint64_t        sc_out_buffer_addr;     /* Location where the kernel should copy the address of the newly mapped buffer in user space */
	uint64_t        sc_out_size_addr;       /* Location where the kernel should copy the size of the stackshot buffer */
	uint64_t                sc_pagetable_mask;      /* Mask of page table levels to dump, must pass STACKSHOT_PAGE_TABLES */
} stackshot_config_t;

#ifndef KERNEL

stackshot_config_t * stackshot_config_create(void);
int stackshot_config_set_pid(stackshot_config_t * stackshot_config, int pid);
int stackshot_config_set_flags(stackshot_config_t * stackshot_config, uint64_t flags);
int stackshot_capture_with_config(stackshot_config_t * stackshot_config);
void * stackshot_config_get_stackshot_buffer(stackshot_config_t * stackshot_config);
uint32_t stackshot_config_get_stackshot_size(stackshot_config_t * stackshot_config);
int stackshot_config_set_size_hint(stackshot_config_t * stackshot_config, uint32_t suggested_size);
int stackshot_config_set_delta_timestamp(stackshot_config_t * stackshot_config, uint64_t delta_timestamp);
int stackshot_config_set_pagetable_mask(stackshot_config_t * stackshot_config, uint32_t mask);
int stackshot_config_dealloc_buffer(stackshot_config_t * stackshot_config);
int stackshot_config_dealloc(stackshot_config_t * stackshot_config);

#endif /* ! KERNEL */

#endif /* _SYS_STACKSHOT_H */
Commit	Line	Data
3e170ce0 A	1	/*
	2	* Copyright (c) 2014 Apple 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
	29	#ifndef _SYS_STACKSHOT_H
	30	#define _SYS_STACKSHOT_H
	31
	32	#include <stdint.h>
	33
	34	#define STACKSHOT_CONFIG_TYPE 1
	35
	36	typedef struct stackshot_config {
	37	/* Input options */
0a7de745	38	int sc_pid; /* PID to trace, or -1 for the entire system */
f427ee49	39	uint64_t sc_flags; /* Stackshot flags */
0a7de745	40	uint64_t sc_delta_timestamp; /* Retrieve a delta stackshot of system state that has changed since this time */
3e170ce0 A	41
3e170ce0 A	42	/* Stackshot results */
0a7de745 A	43	uint64_t sc_buffer; /* Pointer to stackshot buffer */
0a7de745 A	44	uint32_t sc_size; /* Length of the stackshot buffer */
3e170ce0 A	45
3e170ce0 A	46	/* Internals */
0a7de745 A	47	uint64_t sc_out_buffer_addr; /* Location where the kernel should copy the address of the newly mapped buffer in user space */
0a7de745 A	48	uint64_t sc_out_size_addr; /* Location where the kernel should copy the size of the stackshot buffer */
f427ee49	49	uint64_t sc_pagetable_mask; /* Mask of page table levels to dump, must pass STACKSHOT_PAGE_TABLES */
3e170ce0 A	50	} stackshot_config_t;
	51
	52	#ifndef KERNEL
	53
3e170ce0 A	54	stackshot_config_t * stackshot_config_create(void);
3e170ce0 A	55	int stackshot_config_set_pid(stackshot_config_t * stackshot_config, int pid);
f427ee49	56	int stackshot_config_set_flags(stackshot_config_t * stackshot_config, uint64_t flags);
3e170ce0 A	57	int stackshot_capture_with_config(stackshot_config_t * stackshot_config);
	58	void * stackshot_config_get_stackshot_buffer(stackshot_config_t * stackshot_config);
	59	uint32_t stackshot_config_get_stackshot_size(stackshot_config_t * stackshot_config);
	60	int stackshot_config_set_size_hint(stackshot_config_t * stackshot_config, uint32_t suggested_size);
39037602	61	int stackshot_config_set_delta_timestamp(stackshot_config_t * stackshot_config, uint64_t delta_timestamp);
f427ee49	62	int stackshot_config_set_pagetable_mask(stackshot_config_t * stackshot_config, uint32_t mask);
3e170ce0 A	63	int stackshot_config_dealloc_buffer(stackshot_config_t * stackshot_config);
	64	int stackshot_config_dealloc(stackshot_config_t * stackshot_config);
	65
f427ee49	66	#endif /* ! KERNEL */
3e170ce0 A	67
3e170ce0 A	68	#endif /* _SYS_STACKSHOT_H */