Writing Custom Debugger Visualizations
You can write custom visualizations that can be viewed in the graphical debugger during simulation runs.
Creating a custom debugger visualization involves the following steps:
- Write and build the visualization library functions and header.
- If necessary, modify a process model to provide information needed by the visualization.
- Configure ODB to use the visualization.
The following sections provide details about these steps.
To see an example of a visualization plug-in, examine the source code for the built-in IP_Routing visualization in the following locations:
header: <reldir>/models/std/include/odb_vis_iprte.h
source: <reldir>/models/std/utilities/odb_vis/odb_vis_iprte.ets.cpp
Creating the Visualization Library
Visualization plug-ins are written in C/C++ and can use the Riverbed prg and ets APIs. Of particular use are the functions in the ETS “ODB Package”, which help you access simulation objects and run ODB commands from your plug-in.
Each plug-in must implement six callbacks. These are called by the simulation at various times to perform the visualization:
- init() – initializes the visualization
- configure() – displays a dialog when the visualization is first displayed
- draw() – draws the visualization
- select() – handles a click on an object in the visualization
- unselect_all() – handles actions that should restore the visualization to its initial state
- destroy() – cleans up when the visualization is closed or simulation ends
Note: Each of these callbacks must exist (even if they do nothing) or the plug-in will not be loaded.
Details about each callback appear in Debugger Visualization Callbacks.
In addition to callbacks, you’ll probably need to write additional functions to perform specific tasks needed by the visualization. For example, the IP_Routing plug-in has functions to show routes, get the next hop, and add reachability icons to nodes. Functions that might be useful to different visualizations can be included in a visualization utilities library (<reldir>/models/std/utilities/odb_vis/odb_vis_util.ets.cpp).
Obtaining Debugger Information
A visualization plug-in can get information about the simulation by running ODB commands via Ets_Odb_Run_Command() and parsing the command output. Sometimes, however, the necessary information is not available from a command. In such cases, you can add code to the diagnostic block of a process model that will gather and return the information you need.
For example, the IP_Routing plug-in obtains routing table information by defining a label (ip_interfaces) in the debug header of the ip_dispatch process model. The plug-in uses the “proldiag” command to execute the diagnostic block code associated with this label and get the routing table for a specified node.
Build Commands
Use the utility programs “op_mko” and “op_mkso” to build the plug-in library. For example:
op_mko -type ets -m odb_vis_iprte
op_mkso -type ets -f odb_vis_iprte.gui32.i0.ets.obj -m simviz.gui32.i0.ets.dll
Configuring ODB
To use a custom plug-in in ODB, you must add it to the available visualizations list. To do so, either edit the Debugger Visualizations preference or use this procedure:
Procedure 10: Adding a Custom Visualization to ODB
-
While running a simulation in the graphical debugger, click the Visualizations tab.
-
On the Add Visualization Tabbed Page, click the Configure Available Visualizations button.
-
In the Configure Debugger Visualizations Dialog Box, add the visualization:
3.1 Click Add Row. 3.2 Enter the Friendly Name, Function Prefix, and Library Name. 3.3 Click Save Changes.