// context tapset
// Copyright (C) 2005, 2006, 2007 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.

///<chapter id="context_stp">
///  <title>Context Functions</title>
///  <para>
///    The context functions provide additional information about the where
///    the event occurred.
///    These functions can provide information such as a backtrace
///    where the event occured
///    and the current register values for the processor.
///  </para>

///<formalpara id="print_regs">
///  <title>print_regs()</title>
///  <indexterm><primary>print_regs</primary></indexterm>
///  <para>
///	Print a register dump.
///  </para>
///</formalpara>
function print_regs () %{
	if (CONTEXT->regs) {
		_stp_print_regs (CONTEXT->regs);
	}
%}

///<formalpara id="print_backtrace">
///  <title>print_backtrace()</title>
///  <indexterm><primary>print_backtrace</primary></indexterm>
///  <para>
///     Equivalent to <command>print_stack(backtrace())</command>,
///     except that deeper stack nesting may be supported.  Return nothing.
///  </para>
///</formalpara>
function print_backtrace () %{
	if (CONTEXT->regs) {
		_stp_stack_print(CONTEXT->regs, 1, CONTEXT->pi, MAXTRACE);
	} else {
		_stp_printf("Systemtap probe: %s\n", CONTEXT->probe_point);
	}
%}

///<formalpara id="backtrace">
///  <title>backtrace:string()</title>
///  <indexterm><primary>backtrace</primary></indexterm>
///  <para>
///	Return a string of hex addresses that are a backtrace of the
///     stack.  It may be truncated due to maximum string length.
///  </para>
///</formalpara>
function backtrace:string () %{ /* pure */
	if (CONTEXT->regs)
		_stp_stack_snprint (THIS->__retvalue, MAXSTRINGLEN, CONTEXT->regs, 0, CONTEXT->pi, MAXTRACE);
	else 
		strlcpy (THIS->__retvalue, "", MAXSTRINGLEN);
%}

///<formalpara id="execname">
///  <title>execname:string()</title>
///  <indexterm><primary>execname</primary></indexterm>
///  <para>
///     Return the name of the current process.
///  </para>
///</formalpara>
function execname:string () %{ /* pure */
	strlcpy (THIS->__retvalue, current->comm, MAXSTRINGLEN);
%}

///<formalpara id="pid">
///  <title>pid:long ()</title>
///  <indexterm><primary>pid</primary></indexterm>
///  <para>
///	Return the id of the current process.
///  </para>
///</formalpara>
function pid:long () %{ /* pure */
	THIS->__retvalue = current->tgid;
%}

///<formalpara id="tid">
///  <title>tid:long()</title>
///  <indexterm><primary>tid</primary></indexterm>
///  <para>
///	Return the id of the current thread.
///  </para>
///</formalpara>
function tid:long () %{ /* pure */
	THIS->__retvalue = current->pid;
%}

///<formalpara id="ppid">
///  <title>ppid:long()</title>
///  <indexterm><primary>ppid</primary></indexterm>
///  <para>
///	Return the id of the parent process.
///  </para>
///</formalpara>
function ppid:long () %{ /* pure */
#if defined(STAPCONF_REAL_PARENT)
	THIS->__retvalue = current->real_parent->tgid;
#else
	THIS->__retvalue = current->parent->tgid;
#endif
%}

///<formalpara id="pexecname">
///  <title>pexecname:string()</title>
///  <indexterm><primary>pexecname</primary></indexterm>
///  <para>
///	Return the name of the parent process.
///  </para>
///</formalpara>
function pexecname:string () %{ /* pure */
#if defined(STAPCONF_REAL_PARENT)
	strlcpy (THIS->__retvalue, current->real_parent->comm, MAXSTRINGLEN);
#else
	strlcpy (THIS->__retvalue, current->parent->comm, MAXSTRINGLEN);
#endif
%}

///<formalpara id="gid">
///  <title>gid:long()</title>
///  <indexterm><primary>gid</primary></indexterm>
///  <para>
///	Return the gid of the current process.
///  </para>
///</formalpara>
function gid:long () %{ /* pure */
	THIS->__retvalue = current->gid;		
%}

///<formalpara id="egid">
///  <title>egid:long()</title>
///  <indexterm><primary>egid</primary></indexterm>
///  <para>
///    Return the effective gid of the current process.
///  </para>
///</formalpara>
function egid:long () %{ /* pure */
	THIS->__retvalue = current->egid;		
%}

///<formalpara id="uid">
///  <title>uid:long()</title>
///  <indexterm><primary>uid</primary></indexterm>
///  <para>
///	Return the uid of the current process.
///  </para>
///</formalpara>
function uid:long () %{ /* pure */
	THIS->__retvalue = current->uid;		
%}

///<formalpara id="euid">
///  <title>euid:long()</title>
///  <indexterm><primary>euid</primary></indexterm>
///  <para>
///	Return the effective uid of the current process.
///  </para>
///</formalpara>
function euid:long () %{ /* pure */
	THIS->__retvalue = current->euid;		
%}

// cpuid() is not documented
function cpuid:long () %{ /* pure */
	THIS->__retvalue = smp_processor_id();
%}

///<formalpara id="cpu">
///  <title>cpu:long()</title>
///  <indexterm><primary>cpu</primary></indexterm>
///  <para>
///     Return the current cpu number.
///  </para>
///</formalpara>
function cpu:long () %{ /* pure */
	THIS->__retvalue = smp_processor_id();
%}

///<formalpara id="print_stack">
///  <title>print_stack(stk:string)</title>
///  <indexterm><primary>print_stack</primary></indexterm>
///  <para>
///     Perform a symbolic lookup of the addresses in the given  string,
///     which  is  assumed  to  be  the  result of a prior call to 
///	<xref linkend="backtrace"/>.
///     Print one line per address, including the address, the
///     name  of the function containing the address, and an estimate of
///     its position within that function.  Return nothing.
///  </para>
///</formalpara>
function print_stack(stk:string) %{
	char *ptr = THIS->stk;
	char *tok = strsep(&ptr, " ");
	while (tok && *tok) {
		_stp_print_char(' ');
		_stp_symbol_print (simple_strtol(tok, NULL, 16));
		_stp_print_char('\n');
		tok = strsep(&ptr, " ");
	}
%}

///<formalpara id="pp">
///  <title>pp:string()</title>
///  <indexterm><primary>pp</primary></indexterm>
///  <para>
///     Return the probe point associated with the currently running
///     probe handler, including alias and wildcard expansion effects.
///  </para>
///</formalpara>
function pp:string () %{ /* pure */
	strlcpy (THIS->__retvalue, CONTEXT->probe_point, MAXSTRINGLEN);
%}

///<formalpara id="probefunc">
///  <title>probefunc:string()</title>
///  <indexterm><primary>probefunc</primary></indexterm>
///  <para>
///	Return the probe point's function name, if known.
///  </para>
///</formalpara>
function probefunc:string () %{ /* pure */
	char *ptr, *start;

	start = strstr(CONTEXT->probe_point, "function(\"");
	ptr = start + 10; 
	if (!start) {
		start = strstr(CONTEXT->probe_point, "inline(\"");
		ptr = start + 8;
	}

	if (start) {
		int len = MAXSTRINGLEN;
		char *dst = THIS->__retvalue;
		while (*ptr != '@' && --len > 0 && *ptr)
			*dst++ = *ptr++;
		*dst = 0;

	} else if (CONTEXT->regs &&
#if defined (__ia64__)
		((unsigned long)REG_IP(CONTEXT->regs) >= (unsigned long)KERNEL_START)) {
#else
		((unsigned long)REG_IP(CONTEXT->regs) >= (unsigned long)PAGE_OFFSET)) {
#endif
		_stp_symbol_snprint(THIS->__retvalue, MAXSTRINGLEN, REG_IP(CONTEXT->regs));
       	         if (THIS->__retvalue[0] == '.')  /* powerpc symbol has a dot*/
       	         	strlcpy(THIS->__retvalue,THIS->__retvalue + 1,MAXSTRINGLEN);
	} else {
		THIS->__retvalue[0] = '\0';
	}
%}

///<formalpara id="probemod">
///  <title>probemod:string()</title>
///  <indexterm><primary>probemod</primary></indexterm>
///  <para>
///	Return the probe point's module name, if known.
///  </para>
///</formalpara>
function probemod:string () %{ /* pure */
	char *ptr, *start;

	start = strstr(CONTEXT->probe_point, "module(\"");
	ptr = start + 8;

	if (start) {
		int len = MAXSTRINGLEN;
		char *dst = THIS->__retvalue;
		while (*ptr != '"' && --len && *ptr)
			*dst++ = *ptr++;
		*dst = 0;
	} else {
		/* XXX: need a PC- and symbol-table-based fallback. */
		THIS->__retvalue[0] = '\0';
	}
%}

///<formalpara id="registers_valid">
///  <title>registers_valid:long()</title>
///  <indexterm><primary>registers_valid</primary></indexterm>
///  <para>
///	Return 1 if register() and u_register() can be used
///     in the current context, or 0 otherwise.
///     For example, <command>registers_valid()</command> returns 0
///     when called from a begin or end probe.
///  </para>
///</formalpara>
function registers_valid:long () %{ /* pure */
	THIS->__retvalue = (CONTEXT->regs != NULL);
%}

///<formalpara id="user_mode">
///  <title>user_mode:long()</title>
///  <indexterm><primary>user_mode</primary></indexterm>
///  <para>
///	Return 1 if the probe point occurred in user-mode.
///  </para>
///</formalpara>
function user_mode:long () %{ /* pure */ /* currently a user-mode address? */
  if (CONTEXT->regs) {
#if defined(__i386__) || defined(__x86_64__)
     THIS->__retvalue = (uint64_t) user_mode_vm (CONTEXT->regs);
#else
    THIS->__retvalue = (uint64_t) user_mode (CONTEXT->regs);
#endif
  } else {
    THIS->__retvalue = 0;
  }
%}

///<formalpara id="is_return">
///  <title>is_return:long()</title>
///  <indexterm><primary>is_return</primary></indexterm>
///  <para>
///	Return 1 if the probe point is a return probe.
///     <emphasis>Deprecated.</emphasis>
///  </para>
///</formalpara>
function is_return:long () %{ /* pure */
	if (CONTEXT->pi)
		THIS->__retvalue = 1;
	else	
		THIS->__retvalue = 0;	
%}

///<formalpara id="target">
///  <title>target:long()</title>
///  <indexterm><primary>target</primary></indexterm>
///  <para>
///	Return the pid of the target process.
///  </para>
///</formalpara>
function target:long () %{ /* pure */
        THIS->__retvalue = _stp_target;
%}

///<formalpara id="module_name">
///  <title>module_name:string()</title>
///  <indexterm><primary>module_name</primary></indexterm>
///  <para>
///	<remark>FIXME: need description.</remark>
///  </para>
///</formalpara>
function module_name:string () %{ /* pure */
	strlcpy(THIS->__retvalue, THIS_MODULE->name, MAXSTRINGLEN);
%}

///<formalpara id="stp_pid">
///  <title>stp_pid:long()</title>
///  <indexterm><primary>stp_pid</primary></indexterm>
///  <para>
///	<remark>FIXME: need description.</remark>
///  </para>
///</formalpara>
function stp_pid:long () %{ /* pure */
        THIS->__retvalue = _stp_pid;
%}

///<formalpara id="stack_size">
///  <title>stack_size:long()</title>
///  <indexterm><primary>stack_size</primary></indexterm>
///  <para>
///	Return the size of the kernel stack.
///  </para>
///</formalpara>
function stack_size:long () %{ /* pure */
        THIS->__retvalue = THREAD_SIZE;
%}

///<formalpara id="stack_used">
///  <title>stack_used:long ()</title>
///  <indexterm><primary>stack_used</primary></indexterm>
///  <para>
///	Return how many bytes are currently used in the kernel stack.
///  </para>
///</formalpara>
function stack_used:long () %{ /* pure */
	char a;
        THIS->__retvalue = THREAD_SIZE - ((long)&a & (THREAD_SIZE-1));
%}

///<formalpara id="stack_unused">
///  <title>stack_unused:long()</title>
///  <indexterm><primary>stack_unused</primary></indexterm>
///  <para>
///	Return how many bytes are currently available in the kernel stack.
///  </para>
///</formalpara>
function stack_unused:long () %{ /* pure */
	char a;
        THIS->__retvalue = (long)&a & (THREAD_SIZE-1);
%}

///<formalpara id="caller_addr">
///  <title>caller_addr:long()</title>
///  <indexterm><primary>caller_addr</primary></indexterm>
///  <para>
///    Return the address of the calling function.
///    <emphasis> Works only for return probes at this time.</emphasis>
///	
///  </para>
///</formalpara>
function caller_addr:long () %{ /* pure */
        if (CONTEXT->pi)
		THIS->__retvalue = (int64_t)(long)_stp_ret_addr_r(CONTEXT->pi);
        else
		THIS->__retvalue = 0;
%}

///<formalpara id="caller">
///  <title>caller:string()</title>
///  <indexterm><primary>caller</primary></indexterm>
///  <para>
///     Return the address and name of the calling function.
///	<emphasis>Works only for return probes at this time.</emphasis>
///  </para>
///</formalpara>
function caller:string() %{ /* pure */
        if (CONTEXT->pi) 
		_stp_symbol_snprint( THIS->__retvalue, MAXSTRINGLEN, 
			(unsigned long)_stp_ret_addr_r(CONTEXT->pi));
        else
		strlcpy(THIS->__retvalue,"unknown",MAXSTRINGLEN);
%}

///</chapter>