/*
* Copyright (c) 2012-2021 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 _KERN_BTLOG_H_
#define _KERN_BTLOG_H_
#include <sys/cdefs.h>
#include <stdbool.h>
#include <stdint.h>
#include <mach/vm_types.h>
#include <kern/kern_types.h>
#include <kern/debug.h>
__BEGIN_DECLS __ASSUME_PTR_ABI_SINGLE_BEGIN
#pragma GCC visibility push(hidden)
/*
* The btlog subsystem allows for fast unobtrusive backtraces
* to be recorded and maintained in chronological order.
*
* Each backtrace is associated with an element/object,
* and an operation. For example, memory allocations and
* frees can be tracked with this infrastructure. So
* can refcounts. The "operation" namespace is maintained
* by the caller.
*
* When the event buffer fills, records are reused in FIFO
* order.
*
* When a btlog_t is created, callbacks can be provided
* to ensure proper locking of the datastructures. If these
* are not provided, the caller is responsible for
* preventing simultaneous modification.
*/
/*
* BTLOG_MAX_DEPTH configures how deep of a stack trace is stored. 15
* levels is usually enough to get past all the layers of code in
* kalloc and IOKit and see who the actual caller is up above these
* lower levels, when used by the zone allocator logging code.
*/
#define BTLOG_MAX_DEPTH 15
#if __has_attribute(diagnose_if)
#define __btlog_check(cond, msg) \
__attribute__((diagnose_if(cond, msg, "error")))
#else
#define __btlog_check(cond, msg)
#endif
struct btlog;
struct zone_btrecord;
typedef struct btlog *btlog_t;
/*!
* @typedef btref_t
*
* @brief
* A backtrace ref is a compact pointer referencing a unique backtrace
* in the centralized backtrace pool.
*/
typedef uint32_t btref_t;
#define BTREF_NULL ((btref_t)0)
__options_decl(btref_get_flags_t, uint32_t, {
BTREF_GET_PERMANENT = 0x0001,
BTREF_GET_NOWAIT = 0x0002,
});
/*!
* @function btref_get()
*
* @brief
* Get the backtrace reference anchored at the given @c fp
* for the current thread.
*
* @returns
* - BTREF_NULL if allocating the backtrace failed
* - a non 0 backtrace reference otherwise with a +1 refcount.
*/
extern btref_t btref_get(
void *fp,
btref_get_flags_t flags);
/*!
* @function btref_retain()
*
* @brief
* Retains a given backtrace ref.
*/
extern btref_t btref_retain(
btref_t ref);
/*!
* @function btref_put()
*
* @brief
* Release a given backtrace ref.
*/
extern void btref_put(
btref_t btref);
/*!
* @function btref_decode_unslide()
*
* @brief
* Decodes a backtrace into a specified buffer with unslid addresses.
*
* @returns
* The number of frames in the buffer.
*/
extern uint32_t btref_decode_unslide(
btref_t btref,
mach_vm_address_t bt[__counted_by(BTLOG_MAX_DEPTH)]);
/*!
* @typedef btlog_type_t
*
* @const BTLOG_LOG
* A linear log of entries, as a circular buffer.
*
* @const BTLOG_HASH
* A log of entries indexed by element address,
* where entries can be pruned by element address,
* but where entries might go missing.
*/
__enum_decl(btlog_type_t, uint8_t, {
BTLOG_LOG = 1,
BTLOG_HASH = 2,
});
/*!
* @function btlog_create()
*
* @brief
* Creates a backtrace log of the specified type.
*
* @param type the log type to create.
* @param num_records how many records the log should hold.
* @param sample sampling rate (0 to disable).
*/
extern btlog_t btlog_create(
btlog_type_t type,
uint32_t num_records,
uint32_t sample);
/*!
* @function btlog_enable()
*
* @brief
* Enable the specified btlog back.
*
* @discussion
* This operation is not thread safe with respect
* to @c btlog_disable() or @c btlog_destroy(),
* and the caller is supposed to provide serialization.
*/
extern kern_return_t btlog_enable(
btlog_t log);
/*!
* @function btlog_disable()
*
* @brief
* Disables the specified btlog.
*
* @discussion
* This operation is not thread safe with respect
* to @c btlog_enable() or @c btlog_destroy(),
* and the caller is supposed to provide serialization.
*/
extern void btlog_disable(
btlog_t log);
/*!
* @function btlog_destroy()
*
* @brief
* Destroys a backtrace log made with btlog_create().
*/
extern void btlog_destroy(
btlog_t btlog);
/*!
* @function btlog_get_type()
*
* @brief
* Returns the type for the given btlog.
*/
extern btlog_type_t btlog_get_type(
btlog_t btlog) __pure2;
/*!
* @function btlog_get_count()
*
* @brief
* Returns how many records this log can hold.
*/
extern uint32_t btlog_get_count(
btlog_t btlog) __pure2;
/*!
* @function btlog_sample()
*
* @brief
* Returns whether it's the right time to record an event.
*/
extern bool btlog_sample(
btlog_t btlog);
/*!
* @function btlog_record()
*
* @brief
* Records an event for a given address with
* a user provided "operation" to tag it.
* btlog_record will consume a reference on btref.
*/
extern void btlog_record(
btlog_t btlog,
void *element,
uint8_t op,
btref_t btref);
/*!
* @function btlog_erase()
*
* @brief
* Erase all records for a given address.
*
* @discussion
* This only does something for BTLOG_HASH logs.
*/
extern void btlog_erase(
btlog_t btlog,
void *element);
#if !__has_ptrcheck // rdar://88209707
/*!
* @function btlog_get_records()
*
* @brief
* Translates btlog records into zone bt records.
*/
extern kern_return_t btlog_get_records(
btlog_t btlog,
struct zone_btrecord *__counted_by(*numrecs) *records,
unsigned int *numrecs);
#endif
/*!
* @function btlog_guess_top()
*
* @brief
* Tries to guess the "top" active backtrace
* in a @c BTLOG_HASH btlog.
*
* @returns
* The number of outstanding records for this backtrace,
* or 0 if something bad happened.
*/
extern uint32_t btlog_guess_top(
btlog_t btlog,
vm_address_t bt[__counted_by(BTLOG_MAX_DEPTH)],
uint32_t *len);
#if DEBUG || DEVELOPMENT
/*!
* @function btlog_copy_backtraces_for_elements()
*
* @brief
* Copy backtraces for the specified list of elements.
*
* @discussion
* This only does something for BTLOG_HASH logs with a single event per element.
* This is really tailored for zalloc and isn't a very useful interface as is.
*/
extern void btlog_copy_backtraces_for_elements(
btlog_t btlog,
vm_address_t *__counted_by(*count)instances,
uint32_t *count,
uint32_t elem_size,
leak_site_proc proc);
#endif /* DEBUG || DEVELOPMENT */
#pragma GCC visibility pop
__ASSUME_PTR_ABI_SINGLE_END __END_DECLS
#endif /* _KERN_BTLOG_H_ */