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
FINis inserted near the function entrance point. The exact position varies, as follows:- In C++,
FINshould 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
FINmacro contains both variable declarations and statements. Furthermore, a process model’s state variables and some of the Kernel Procedures rely onFIN() having been invoked before their use. Thus, for simplicity, we recommend that you declare all other function-level variables before theFINand place all other C statements after theFIN. - 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
FINfirst, but be sure that the code will always be compiled with C99 support.
- In C++,
FOUTis inserted at function exit points that do not return any value.FRETis 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
FINdoes not require double-quotes (it also includes its own). - The arguments to
FINandFRETare 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
FINmacro might be replaced by aFIN_MTmacro in some functions that support parallel simulation (as described in “Simulation Context Pointer“ on page 423). The syntax ofFINandFIN_MTis 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.