// context-unwind tapset
// Copyright (C) 2005-2011 Red Hat Inc.
// Copyright (C) 2006 Intel Corporation.
//
// This file is part of systemtap, and is free software.  You can
// redistribute it and/or modify it under the terms of the GNU General
// Public License (GPL); either version 2, or (at your option) any
// later version.
// <tapsetdescription>
// Context functions provide additional information about where an event occurred. These functions can 
//provide information such as a backtrace to where the event occurred and the current register values for the 
//processor.
// </tapsetdescription>

/**
 *  sfunction print_backtrace - Print stack back trace
 * 
 *  Description: This function is equivalent to print_stack(backtrace()), 
 *  except that deeper stack nesting may be supported.
 *  The function does not return a value.
 */
function print_backtrace () %{
	/* pragma:unwind */ /* pragma:symbols */
	_stp_stack_kernel_print(CONTEXT, _STP_SYM_FULL);
%}

/**
 * sfunction sprint_backtrace - Return stack back trace as string
 *
 * Returns a simple (kernel) backtrace. One line per address.
 * Includes the symbol name (or hex address if symbol
 * couldn't be resolved) and module name (if found). Includes the
 * offset from the start of the function if found, otherwise the
 * offset will be added to the module (if found, between
 * brackets). Returns the backtrace as string (each line terminated by
 * a newline character).  Note that the returned stack will be
 * truncated to MAXSTRINGLEN, to print fuller and richer stacks use
 * print_backtrace(). Equivalent to sprint_stack(backtrace()),
 * but more efficient (no need to translate between hex strings and
 * final backtrace string).
 */
function sprint_backtrace:string () %{
	/* pure */ /* pragma:unwind */ /* pragma:symbols */
	_stp_stack_kernel_sprint (STAP_RETVALUE, MAXSTRINGLEN,
				  CONTEXT, _STP_SYM_SIMPLE);
%}

/**
 * sfunction backtrace - Hex backtrace of current stack
 * 
 * Description: This function returns a string of hex addresses 
 * that are a backtrace of the stack. Output may be truncated as 
 * as per maximum string length (MAXSTRINGLEN).
 */
function backtrace:string () %{ /* pure */ /* pragma:unwind */
	_stp_stack_kernel_sprint (STAP_RETVALUE, MAXSTRINGLEN,
				  CONTEXT, _STP_SYM_NONE);
%}

%( systemtap_v <= "1.6" %?
/**
 *  sfunction task_backtrace - Hex backtrace of an arbitrary task
 *  @task: pointer to task_struct
 *
 *  Description: This function returns a string of hex addresses
 *  that are a backtrace of the stack of a particular task
 *  Output may be truncated as per maximum string length.
 *  Deprecated in SystemTap 1.6.
 */
function task_backtrace:string (task:long) {
	warn("task_backtrace unsupported")
}
%)