Function Stack Tracing

One of the most useful techniques for diagnosing and debugging program errors is the stack traceback (a listing of all function calls currently on the stack of the executing program). A traceback serves as a roadmap to the location of the error, pinpointing the place in the “tree of functions” at which the error occurred. Many times, the cause of an error may be located in a part of the program far removed from the location of the error’s occurrence, but the traceback still is an important starting point.

All Riverbed programs, including simulations, have the capability of generating a stack traceback for Riverbed-supplied functions (operating system calls are not included in the traceback, because the stack tracing technology requires that special code be included in traced functions). Should an error occur, the traceback of functions can be printed using the op_vuerr utility (documented in “op_vuerr“ on page 221). Figure 1 shows an example op_vuerr output listing. Note that the stack listing consists of a series of function references, each of which consists of the function name and a list of its argument names. The function listing builds down, from the top-level function towards the function in which the error occurred. Thus, in the example, function #10 (sim_err_pk_access()) is associated with the segmentation violation that caused the program to abort.

Figure 1: Example Output of op_vuerr

extracted the following messages from 'err_log' file:
<<< Program Abort >>>
 * Time:      13:32:07 Wed Aug 06 2003
 * Product:   modeler
 * Program:   op_runsim (Version 10.0.A PL1 Build 2282)
 * System:    Windows NT 5.0 Build 2195
 * Package:   process (acb_fifo) at module (top.m1.queue)
 * Function:  sim_err_pk_access
 * Error:     Packet pointer is NIL
                     T (0), EV (4), MOD (top.m1.queue), KP (op_pk_destroy)

 * Function call stack: (builds down)
   ------------------------------------------------------------
              Call   Block
              Count  Line#  Function
   ------------------------------------------------------------
     0)          1  1073741928  0x09254d0e [name not available]
     1)          1  1879048703  0x00004c00 [name not available]
     2)          1  -805306207  0x0000c400 [name not available]
     3)          1    284  m3_main
     4)          1    935  sim_main
     5)          1   2364  sim_ev_loop
     6)          1    354  sim_strm_insert
     7)          5    522  sim_obj_qps_intrpt
     8)          2      1  acb_fifo [arrival enter execs]
     9)          1   1341  op_pk_destroy (pkptr)
    10)          1   1483  sim_err_pk_access
   ------------------------------------------------------------

In simulations, all Riverbed-supplied functions, including the Kernel Procedures and the underlying Simulation Kernel functions, incorporate stack tracing code. User-defined simulation functions, which appear in process model function blocks or external C/C++ files, can also be traced. In fact, most users find the best application of op_vuerr is assisting their simulation function debugging.

For a user-defined simulation function to be traced, it must incorporate the special stack tracing code. Stack tracing is accomplished by inserting preprocessor macro statements at the entrance point and exit point(s) of a function (a function has only one entrance point, but can have multiple exit points due to the return statement of C). The macro statements are named FIN, FOUT, and FRET (which stand for Function-In, Function-Out, and Function-Returns, respectively).

All example models provided with Riverbed analysis software incorporate these macros. It is recommended that user-defined functions incorporate them as well. If FIN, FOUT, and FRET statements are properly inserted into user-defined functions, op_vuerr can be used to determine the location of a program error even in a nested group of model function calls.

The syntax for these macros is as follows.

FIN (<function name & arguments>)
FOUT
FRET (<return type>)

Syntax and Placement Notes

  • FIN is inserted near the function entrance point. The exact position varies, as follows:
    • In C++, FIN should be placed first (after the opening “{“ bracket) to ensure that the function call stack is set up before any local variable invokes its constructor.
    • In C, the FIN macro contains both variable declarations and statements. Furthermore, a process model’s state variables and some of the Kernel Procedures rely on FIN() having been invoked before their use. Thus, for simplicity, we recommend that you declare all other function-level variables before the FIN and place all other C statements after the FIN.
    • Variable declarations can include constant assignments. Anything involving a function invocation, however, should be placed after the FIN; this will ensure that the function call stack has been set up appropriately in case an error or warning needs to be reported.
    • If your compiler allows C99 features (gcc: -std=c99; Intel ICL: /Qstd=c99), variables can be declared anywhere in the function. In this case, you might as well put FIN first, but be sure that the code will always be compiled with C99 support.
  • FOUT is inserted at function exit points that do not return any value.
  • FRET is inserted at function exit points that do return a value.
  • These macros do not need trailing semi-colons (they include their own).
  • The argument to FIN does not require double-quotes (it also includes its own).
  • The arguments to FIN and FRET are used when printing function call stacks in the error log and for general debugging. They are not used as symbols during compilation, so you can include whatever information you find useful.
  • The FIN macro might be replaced by a FIN_MT macro in some functions that support parallel simulation (as described in “Simulation Context Pointer“ on page 423). The syntax of FIN and FIN_MT is identical.

Figure 2: Example Use of FIN / FRET

int
sum_three (int a, int b, int c)
	{
	int sum;
	FIN (sum_three (a, b, c))
	sum = a + b + c;
	FRET (sum)
	}

Figure 3: Example Use of FIN / FOUT

void
pr_banner (char* string)
	{
	FIN (pr_banner (string))
	printf ("-----------\n");
	printf ("%s\n", string);
	printf ("-----------\n");
	FOUT
	}

WARNING: Do not use the FIN, FOUT, and FRET macros in the main() function of an EMA or ET program. An abnormal function stack imbalance error will occur if these macros occur before either prg_init(), Vos_Init(), or Ema_Init() has been invoked.